서론: 매 대화마다 내가 내는 '입장료'
Claude Code를 쓰는 사람이라면 CLAUDE.md를 알 것이다. 프로젝트의 지도이자 AI에게 건네는 브리핑 문서. 그런데 이 문서에는 함정이 하나 있다.
CLAUDE.md는 매 대화의 첫 턴에 통째로 로드된다.
286줄짜리 CLAUDE.md가 있다면, 매번 286줄의 토큰이 "입장료"로 빠져나간다. 한 세션에 50턴을 돌리면? 첫 턴의 브리핑이 50번째 턴의 코딩 공간을 잡아먹고 있는 셈이다. Context window는 유한하고, CLAUDE.md는 영원히 그 자리를 차지한다.
오늘 내 프로젝트의 CLAUDE.md를 286줄에서 247줄로 줄였다. 고작 39줄? 아니, 이건 단순한 줄 수 싸움이 아니다.
발견: Claude에게 "이 문서 괜찮아?" 물어봤더니
재미있는 건, 이 다이어트의 시작이 Claude 자신이었다는 점이다.
"CLAUDE.md 잘 정리되어 있는 것 같아?" 한 마디에 Claude가 세 가지 문제를 짚었다:
- 비밀번호가 평문으로 박혀 있다 —
Oikos26!,okJlove26!같은 비밀번호가 git에 체크인된 파일에 그대로 - Session Context가 35줄이나 차지한다 — "이전 세션에서 뭐 했는지" 기록인데, 매 대화마다 로드할 필요가 있나?
- 개선 이력이 7줄 낭비다 — "Phase 1-14는 이거, 15-19는 저거..." 개발 중에 누가 참조하나?
처음엔 "자동 갱신 여부"나 "ARCHIVE.md 정합성" 같은 기술적 관점으로 접근했는데, 한 발 물러서 보니 진짜 질문은 이거였다:
"이 줄이 매 대화마다 로드될 가치가 있는가?"
실행: 세 가지 수술
수술 1: 비밀번호 추방
가장 명백한 문제. 비밀번호가 CLAUDE.md에 있을 이유가 없다.
Before: | **개발** | oikos_finance | localhost:5432 | oikos:Oikos1! |
After: | **개발** | oikos_finance | localhost:5432 |
DB 계정: instance/.env → DATABASE_URL 참조
비밀번호를 지우고 instance/.env 경로만 남겼다. curl 예제도 "password":"<instance/.env 참조>"로 바꿨다.
줄 수는 거의 안 변했지만, 이건 context window가 아니라 보안의 문제다. git에 체크인되는 파일에 비밀번호가 있으면 안 된다. 이미 secrets-index라는 중앙 관리 시스템이 있는데 안 쓰고 있었던 거다.
수술 2: Session Context 이사 (-35줄)
이게 핵심이었다. Session Context는 이런 내용이다:
### Last Sync
- Date: 2026-02-22
- Session: 개발/운영 환경 통일 + CLAUDE.md 대청소
### Active Work
- DB 자격증명: 개발/운영 oikos:Oikos1! 통일
- 테스트 관리자: admin@test / Oikos26! (개발/운영)
...
### Next Entry Point
- [P1/S] 0222 헌금 처리
- [P2/S] 2월 월정 지출 입력
유용하다. 세션 간 연속성을 위해 분명 가치가 있다. 그런데 매 대화의 매 턴마다 35줄의 토큰을 쓸 가치가 있을까?
답은 memory 파일이었다. Claude Code에는 ~/.claude/projects/*/memory/ 라는 영속 메모리 공간이 있다. 여기에 5줄로 압축해서 옮겼다:
- **Last Sync**: 2026-02-22
- **Active**: AI 인사이트 Phase H 완료, CLAUDE.md 압축
- **Next**: 0222 헌금 처리 → 2월 월정 지출
- **Blockers**: None
35줄이 5줄이 되었다. 정보량은 같다.
수술 3: 개선 이력 위임 (-6줄)
CLAUDE.md에 이런 섹션이 있었다:
Phase 1-14: 기본 구조 → Phase 15-19: DB+리포트 → Phase 20-29: OCR+검증 품질
→ Phase 30-31: 월정+보안 → Phase 32-33: AI 인사이트 → Phase A-G: 설치형 배포
최근 (Phase E-G): 대시보드 재설계, action_items 노이즈 제거...
이걸 코딩하면서 참조할 일이 있을까? 없다. 한 줄이면 충분하다:
상세: ARCHIVE.md (Phase 1-34 + A-H)
대신 ARCHIVE.md를 Phase 14까지만 있던 것에서 Phase H까지 전부 채워넣었다. ARCHIVE.md는 별도 파일이라 context window에 영향이 없다. 필요할 때만 읽으면 된다.
원칙: CLAUDE.md 다이어트 3원칙
이 작업을 통해 정리된 원칙이다:
1. 매 턴 로드 테스트
"이 줄이 50번째 턴에서도 필요한가?"
프로젝트 구조, DB 연결, CLI 명령처럼 언제든 참조될 수 있는 정보만 CLAUDE.md에 남긴다. "지난 세션에 뭐 했는지"는 첫 턴에만 필요하다.
2. 참조 vs 내용
"내용을 적을 것인가, 위치를 적을 것인가?"
비밀번호 → 파일 경로. 개발 이력 → 파일 참조. CLAUDE.md에는 포인터만 남기고 실제 내용은 각자의 집으로 보내라.
3. 중복 0 원칙
"같은 정보가 두 곳에 있으면, 한 곳은 거짓말이다."
Session Context의 Key Files는 폴더 구조 섹션과 중복이었다. 개선 이력은 ARCHIVE.md와 중복이었다. 중복이 생기면 한쪽을 참조로 바꿔라.
결과
| 변경 | Before | After | 효과 |
|---|---|---|---|
| 비밀번호 | 평문 4곳 | 환경파일 참조 | 보안 개선 |
| Session Context | 35줄 | memory 5줄 | -35줄 |
| 개선 이력 | 7줄 | 참조 1줄 | -6줄 |
| 합계 | 286줄 | 247줄 | -14% |
14%가 대수냐고? Context window 200K 토큰 기준으로 CLAUDE.md가 약 2K 토큰이라면, 39줄 절약은 대화당 약 280 토큰이다. 하루 10세션이면 2,800 토큰. 큰 숫자는 아니다.
하지만 진짜 효과는 숫자가 아니다. CLAUDE.md가 날씬해지면 Claude가 더 집중한다. 노이즈가 줄면 시그널이 선명해진다. 35줄의 "지난 세션 기록"이 사라지면, Claude는 지금 대화에 더 집중할 수 있다.
에필로그: AI에게 자기 자신을 진단시키기
오늘의 하이라이트는 사실 기술적인 개선이 아니다. "CLAUDE.md 잘 되어 있어?"라는 한 마디로 AI가 자기 자신의 브리핑 문서를 진단하고, 문제를 찾고, 해결책을 제안하고, 직접 실행까지 한 것이다.
AI 도구를 쓸 때 우리는 보통 "이 코드 고쳐줘", "이 기능 만들어줘"를 시킨다. 하지만 가끔은 이렇게 물어보자:
"네가 매일 읽는 이 문서, 너한테 진짜 도움이 돼?"
대답이 의외로 솔직하다.