Claude Code를 쓰다 보면 대화 몇 턴 안 했는데 컨텍스트 윈도우가 50%를 넘기는 경험을 하게 된다. 원인은 대화 내용이 아니라 매 세션마다 자동 로드되는 시스템 컨텍스트였다.

실측 데이터

Contents Hub 프로젝트에서 /context 명령으로 실측한 토큰 분포:

카테고리 토큰 비중
System prompt 3.9k 2.0%
System tools 13.5k 6.7%
MCP tools 178 0.1%
Custom agents 1.2k 0.6%
Memory files 26.5k 13.3%
Skills 5k 2.5%
Messages (실제 대화) 19.4k 9.7%
Autocompact buffer 33k 16.5%
Free space 97k 48.7%

대화는 전체의 9.7%인데, 자동 로드되는 것들이 25%를 차지한다.

Memory Files 상세 분석

가장 큰 비중을 차지하는 Memory files의 내역:

파일 토큰 역할
LESSONS.md 11.9k 세션 회고 (28개 레슨)
CLAUDE.md 7.7k 프로젝트 지침서
README.md 2.3k 프로젝트 개요
Global CLAUDE.md 1.7k 전역 사용자 지침
TODO.md 1.4k 작업 추적
SPEC.md 1.2k 기능 사양
MEMORY.md 369 auto memory

최적화 방안 (효과순)

1. LESSONS.md archive (절감: ~10k 토큰)

가장 큰 단일 파일. 28개 레슨이 전문 로드되는데, 대부분의 세션에서 과거 레슨 전체가 필요하지 않다. 오래된 레슨을 docs/archive/로 이동하고, 최근 10개만 유지하면 절반 이상 절감.

2. README.md, SPEC.md, TODO.md 제외 (절감: ~5k 토큰)

이 3개 파일의 핵심 정보는 CLAUDE.md에 이미 포함되어 있다. 중복 로드를 피하고, 필요할 때만 @SPEC.md로 명시적으로 참조하면 된다.

3. CLAUDE.md 경량화 (절감: ~3k 토큰)

배포 아키텍처 ASCII art, JWT 발급 코드 블록, 상세 체크리스트 등 "참조용" 내용을 docs/로 분리. CLAUDE.md에는 규칙과 제약만 남긴다.

4. 미사용 플러그인 정리 (절감: ~3k 토큰)

Skills 5k + Custom agents 1.2k 중 실제 자주 쓰는 것은 소수. document-skills, example-skills 같은 중복 플러그인이 각각 로드되고 있다.

핵심 인사이트

  1. 대화보다 설정이 더 크다 - 실제 대화는 전체의 10% 미만. "컨텍스트가 빨리 찬다"는 느낌의 주 원인은 대화가 아니라 자동 로드되는 문서.

  2. CLAUDE.md는 "규칙서"이지 "백과사전"이 아니다 - 프로젝트가 성장하면서 CLAUDE.md에 모든 정보를 담게 되면, 매 세션마다 불필요한 컨텍스트를 지불하게 된다.

  3. LESSONS.md는 축적의 역설 - 교훈을 많이 기록할수록 좋지만, 그만큼 매 세션의 "입장료"가 비싸진다. 주기적 archive가 필수.

  4. /context 명령을 습관화 - 체감이 아니라 실측으로 병목을 찾아야 한다. 토큰 분포를 보면 어디를 줄여야 할지 명확해진다.

실행 계획

우선순위 조치 예상 절감
1 LESSONS.md archive ~10k (5%)
2 README/SPEC/TODO 제외 ~5k (2.5%)
3 CLAUDE.md 참조 분리 ~3k (1.5%)
4 미사용 플러그인 정리 ~3k (1.5%)
합계 ~21k (10.5%)

1+2번만 해도 대화에 ~15k 토큰의 여유가 생긴다. 이는 대화 약 7-8턴 분량이다.