대부분의 CLAUDE.md 파일은 비슷한 방식으로 시작됩니다. 프로젝트 첫날 오후에 작성된 다섯 개 또는 여섯 개의 불렛 포인트(bullet points) — 명명 규칙(naming convention), 패키지 매니저(package manager), "마이그레이션을 자동으로 실행하지 마세요" 같은 내용들 말이죠. 6개월 후, 동일한 파일은 300줄이 넘게 늘어나 있습니다. 리팩터링(refactor) 과정에서 남겨진 미완성 메모, 번복된 결정을 설명하는 한 단락, 그리고 이미 존재했는지 확인하지 않은 채 세 명의 서로 다른 사람들이 추가한 "TypeScript 엄격 모드(strict mode)를 사용하세요"라는 약간씩 다른 세 가지 표현들까지 말입니다. 아무도 무엇이 여전히 핵심적인 역할을 하는지 확신할 수 없기 때문에, 아무도 아무것도 삭제하지 않습니다.

하지만 이 파일은 매 턴(turn)마다 여전히 전체가 읽힙니다. 사람들이 깊이 생각하지 못하는 부분이 바로 이 지점입니다.

길이는 진짜 문제가 아닙니다 — 문제는 신호 대 잡음비(signal-to-noise)입니다

300줄짜리 CLAUDE.md가 나쁜 이유는 단순히 길기 때문이 아닙니다. 실제로 중요한 한 줄짜리 규칙("never touch billing.py, it's synced from another repo")이, 반복되는 포맷팅 선호도 40줄이나 두 분기 전에 마이그레이션한 라이브러리에 대한 오래된 메모와 동일한 시각적 및 의미적 비중을 갖게 되기 때문입니다. 모델은 그 줄들 중 어떤 것이 다음 행동을 바꿔야 하는지, 그리고 어떤 것이 단순한 역사적 잔재인지 구별할 수 있는 신뢰할 만한 방법이 없습니다. 모든 것이 똑같이 "지침(instructions)"으로 읽히기 때문에, 그 어떤 것도 필요한 강조를 받지 못합니다.

이는 긴 세션에서 지침이 단순히 무시되는 것과는 다릅니다. 이것은 프로젝트의 수명 동안 매 턴마다 동일한 주의력 예산(attention budget)을 두고 신호(signal)와 적극적으로 경쟁하는 잡음(noise)입니다. 동일한 중요한 규칙을 포함하고 있더라도, 파일이 더 짧을수록 동일한 슬롯을 두고 경쟁하는 요소가 적기 때문에 규칙이 준수될 가능성이 더 높아집니다.

빠른 감사(audit): CLAUDE.md를 읽고 불필요한 내용을 삭제하세요

파일을 한 줄씩 훑으며 각 항목에 대해 다음과 같이 질문해 보세요. "만약 내가 지금 이것을 삭제한다면, 향후 한 시간 동안 내가 하는 일 중 실제로 변하는 것이 있을까?"

이 테스트를 통과하지 못하며 보통 바로 휴지통으로 보내도 되는 일반적인 범주들은 다음과 같습니다:

• 관습(convention) 자체가 한 줄이면, 그 관습이 왜 존재하는지에 대한 설명은 생략하세요. 규칙은 유지하되, 에세이는 삭제하세요.
• 더 이상 저장소(repo)에 존재하지 않는 도구, 프레임워크, 또는 파일에 대한 지침.
• 예외 없이 매번 반드시 일어나야 하는 일에 대해 "~하도록 노력해 주세요" 또는 "~하는 것을 기억하세요"라고 표현된 모든 것 — 이는 CLAUDE.md의 라인이 아니라 훅 (hook, 라이프사이클 이벤트에 연결된 셸 명령어로, 애초에 요청이 아니므로 주의를 분산시키지 않음)입니다.
• 가끔씩만 실행하는 다단계 절차 ("릴리스를 할 때는 A를 하고, 그다음 B를 하고, 그다음 C를 하세요") — 이는 매번 관련 없는 턴마다 읽어야 하는 상시 지침이 아니라, 필요할 때 호출하는 슬래시 명령 (slash command)에 포함되어야 합니다.
• 서로 다른 시점에 추가되어 중복된 표현으로 작성된 동일한 규칙. 가장 명확한 것 하나만 남기고 나머지는 삭제하세요.

실제로 유지할 가치가 있는 것

삭제 과정을 견뎌내고 살아남는 것들은 대개 몇 가지 범주로 나뉩니다: 프로젝트의 형태 (파일들이 어디에 위치하는지, 생성된 파일인지 직접 작성한 파일인지), 린터 (linter)에 의해 강제되지 않는 명명 규칙 및 스타일 관습 (naming and style conventions), 엄격한 경계 ("절대 안 됨", "항상 해야 함", 접근 금지된 특정 파일 또는 디렉토리), 그리고 새로운 기여자가 추측할 수 없는 명확하지 않은 맥락 — 즉, 신입 사원에게 첫 일주일이 아니라 첫 10분 안에 말해줄 법한 내용들입니다.

만약 그것이 절차적이고 결정론적 (deterministic)이라면, 그것은 훅 (hook)입니다. 만약 의도적으로 실행하는 다단계 작업이라면, 그것은 명령 (command)입니다. 만약 모든 결정의 형태를 결정짓는 프로젝트에 대한 상시적인 사실이라면, 그것이 바로 CLAUDE.md입니다. 대부분의 비대해진 파일(bloat)은 가장 열어보기 쉽고 한 줄 추가하기 편하다는 이유로 앞의 두 가지 종류의 정보를 세 번째 범주에 집어넣는 데서 발생합니다.

문제가 생겼을 때가 아니라, 정기적으로 정리하세요

정직한 해결책은 일회성 정리(cleanup)가 아니라 습관입니다. 한 줄을 추가하고 싶은 유혹이 들 때마다, 이미 존재하는 줄이 그 내용을 다루고 있지는 않은지 확인하세요. 몇 주마다 파일 전체를 소리 내어 다시 읽어보세요 (또는 Claude에게 요약을 시켜보세요. 만약 그 요약이 당신을 놀라게 한다면, 파일이 당신이 생각하는 내용으로부터 벗어나 있다는 뜻입니다). 40줄의 짜임새 있는 내용으로 활발하게 관리되는 CLAUDE.md가, 400줄까지 불어나서 몇 달 동안 사람이 제대로 읽지 않은 파일보다 훨씬 낫습니다.

(AI의 도움을 받아 작성되었습니다.)