AI 코딩에서 프로젝트 문서는 한 번에 완벽하게 써두는 물건이 아니다. 두 개의 모드로 굴러간다. 매 작업에서 배운 걸 싸게 쌓는 모드, 그리고 가끔 그걸 한꺼번에 압축하는 모드. CLAUDE.md 관리가 어려운 진짜 이유는 이 둘을 섞어 쓰기 때문이다. 쌓기만 하면 비대해지고, 처음부터 깔끔하게 쓰려 하면 작업이 느려진다.
이 글에서는 CLAUDE.md 관리를 쌓기와 압축 두 모드로 나누는 관점에서, CLAUDE.md가 왜 자꾸 부풀어 오르는지, 누적과 압축을 분리한 운영 루프가 어떻게 작동하는지, 그리고 그 압축을 데이터 한 줄 잃지 않고 안전하게 하는 방법을 정리한다. 거창한 도구가 필요한 이야기가 아니라, 문서를 코드처럼 다루는 습관에 가깝다.
왜 CLAUDE.md는 자꾸 비대해지는가
CLAUDE.md 관리가 어려워지는 첫 지점이 여기다. CLAUDE.md는 에이전트가 매번 읽는 파일이라, 항상 로딩되는 컨텍스트다. 길어질수록 모든 작업의 비용이 올라간다. 그런데 작업을 하다 보면 자연스럽게 살이 붙는다. 이번 세션에서 막혔던 함정, 새로 정한 규칙, 바뀐 폴더 구조를 잊지 않으려고 한 줄씩 적어두기 때문이다. 이 습관 자체는 옳다. 문제는 적은 걸 정리하지 않고 계속 쌓기만 할 때 생긴다.
증상은 비슷하게 나타난다. 날짜별 메모가 본문 규칙과 뒤섞이고, 같은 카테고리 표가 여러 파일에 복붙되고, 발행 절차 같은 실행 순서가 역할 설명 한가운데 박힌다. CLAUDE.md를 처음 세팅하는 단계는 claude 초기 설정 가이드에서 다뤘는데, 운영을 몇 주만 하면 그 깔끔하던 파일이 금세 무거워진다.
CLAUDE.md 관리에서 가장 위험한 건 드리프트다. 문서가 이 파일이 권위 기준이라고 선언해 두었는데, 정작 스크립트는 다른 파일을 읽고 있는 상태. 문서와 코드가 따로 노는 이 어긋남은 눈으로 읽어선 안 잡힌다.
쌓는 모드와 압축하는 모드
CLAUDE.md 관리의 해법은 쓰기 경로와 읽기 경로를 분리하는 것이다. 두 가지 일을 서로 다른 시점에 한다.
쌓는 모드는 매 세션이 끝날 때 돈다. 이번에 배운 걸 어디에 둘지 고민하지 않고 CLAUDE.md 메모란에 그냥 적재한다. 판단을 미루는 게 핵심이다. 적는 마찰이 낮아야 실제로 적기 때문이다.
압축하는 모드는 메모가 쌓였을 때 가끔 돈다. 이때 비로소 정리한다. 실행 절차는 별도의 SOP 문서로 떼어내고, 구조와 데이터 계보는 아키텍처 문서로, 날짜별 이력은 변경 로그로 승격한다. 그러고 나면 CLAUDE.md에는 역할 몇 줄과 이 작업을 하면 저 SOP를 읽어라는 안내, 핵심 파일 목록만 남는다. 슬림한 로더가 되는 것이다.
| 쌓는 모드 | 압축하는 모드 | |
| 시점 | 매 세션 끝 | 메모가 쌓였을 때 |
| 최적화 | 쓰기 비용 낮추기 | 읽기 비용 낮추기 |
| 결과 | 메모 한 줄 추가 | SOP·아키텍처로 승격, 본문은 비움 |
스킬 작성 절차를 따로 관리하는 이야기는 Claude 스킬 파일 업데이트에서도 같은 결로 다뤘다. 절차는 절차 문서에, 안내는 CLAUDE.md에 두는 분리다.
안전하게 압축하는 법과 이 패턴의 선례
압축은 잘못하면 손실적이다. 그래서 CLAUDE.md 관리를 압축할 때는 규칙 세 개를 강제한다. 첫째, 슬림화는 삭제가 아니라 이동이다. 원문의 모든 문장은 옮겨갈 목적지를 가져야 하고, 목적지 없는 문장은 지우지 않는다. 둘째, 줄이기 전에 원본을 스냅샷으로 떠둔다. 롤백 지점이다. 셋째, 무엇을 어디로 옮길지 출처와 목적지를 표로 만들어 먼저 확인한 뒤에만 본문을 줄인다.
여기에 하나 더, 같은 사실이 여러 곳에 있으면 한 곳만 권위로 정하고 나머지는 그 권위에서 파생되게 만든다. 이때 반드시 문서가 권위라고 부르는 파일과 코드가 실제로 읽는 파일이 같은지 대조한다.
직접 적용하면서 이 마지막 규칙의 값을 체감했다. 한 동기화 스크립트가 문서상으로는 권위 인벤토리라 적힌 파일을 쓰는 줄 알았는데, 코드를 열어보니 전혀 다른, 종료된 프로젝트의 옛 파일을 읽고 있었다. 문서만 믿었으면 영영 못 잡았을 어긋남이다. 권위 파일을 하나로 통합하고 스크립트가 그 파일을 읽도록 경로까지 같이 고친 다음에야 선언과 실제가 일치했다. 같은 작업에서 가장 비대했던 CLAUDE.md는 145줄에서 25줄로 줄었는데, 스냅샷과 매핑표 덕분에 한 줄도 잃지 않고 옮겼다.
이 누적과 압축의 짝은 새로 발명한 게 아니다. 데이터베이스의 로그 구조화 저장소가 똑같이 한다. 빠르게 쌓아두고 백그라운드에서 압축으로 정리한다. 사람의 기억도 그렇다. 하루 동안 겪은 일화 기억을 자는 동안 의미 기억으로 응고시킨다. 인프라 팀의 의사결정 기록과 런북, 위키 정리도 결국 같은 원리다. 문서를 쓰고 끝내는 게 아니라, 주기적으로 리팩터링하는 대상으로 보는 것이다.
핵심 요약
CLAUDE.md 관리는 두 모드를 분리하는 일이다. 매 세션 학습을 싸게 쌓고, 메모가 쌓이면 절차는 SOP로 구조는 아키텍처 문서로 승격해 본문을 슬림하게 비운다. 압축할 때는 삭제 대신 이동, 스냅샷, 출처와 목적지 매핑 확인, 그리고 권위와 실제 소스의 일치 점검을 지키면 데이터를 잃지 않는다. 이 패턴은 로그 압축과 기억 응고화처럼 이미 검증된 구조다.
함께 읽으면 좋은 글
레퍼런스로 삼을 프로젝트 폴더를 어떻게 읽고 구조를 파악하는지는 바이브코딩 입문 레퍼런스 구현에서 이어진다.
