Claude Code를 만든 Boris Cherny의 CLAUDE.md는 약 2.5k 토큰, 100줄 수준이다. 어떤 개발자는 이걸 8배 길이로 쓰다가 오히려 결과가 더 나빠졌다는 사례도 있더라고.

이유는 간단한데, CLAUDE.md는 매 세션 시작 시 컨텍스트에 포함된다. 시스템 프롬프트, 툴 정의, MCP 스키마만으로 이미 30,000~40,000 토큰이 나간다. CLAUDE.md가 길수록 실제로 쓸 수 있는 컨텍스트가 그만큼 줄어드는 거다.

Boris의 방식은 이렇다. 처음부터 많이 적어두는 게 아니라, Claude가 뭔가 잘못할 때마다 한 줄씩 추가하는 거다. 실제 실수 기반으로 점진적으로 쌓이는 거라 군더더기가 없다.

CLAUDE.md에 들어간 것들 중 대부분은 사실 거기 있을 필요가 없다. 워크플로우, 다단계 프로세스, 스타일 가이드 같은 건 skill로 빼면 된다. skill은 필요할 때만 로드되니까. CLAUDE.md에는 모든 요청에 반드시 적용돼야 하는 것만 남기는 거다. 나머지는 낭비다.