CLAUDE.md 부패 방지 방법: 규칙을 코드처럼 다루기

Claude Code를 프로덕션 프로젝트에서 18개월 동안 운영한 결과, u/mm_cm_m_km은 가장 흔한 실패 지점을 발견했습니다: CLAUDE.md 파일이 썩는다는 것입니다. Claude가 무시해서가 아니라, 개발자들이 정리하지 않고 규칙을 계속 추가하기 때문입니다. 그 결과는 모든 턴마다 토큰을 소모하고 실제 코드베이스와 동기화가 어긋나는 500줄짜리 비대한 파일입니다.

1. CLAUDE.md는 매뉴얼이 아니라 인덱스로 사용하세요

CLAUDE.md를 30~50줄로 유지하세요. 특정 문제에 대해 특정 파일을 가리키는 목차 역할을 해야 하지, 설정한 모든 환경설정을 나열하는 벽이 되어서는 안 됩니다. Claude는 매 턴마다 파일을 다시 읽습니다. 짧은 파일은 저렴하고, 긴 파일은 토큰과 주의력을 낭비합니다.

2. 각 섹션은 두 질문 중 하나에 답해야 합니다

• 어떤 동작을 원하나요? (규칙) — CLAUDE.md에 속합니다.
• 현재 진실은 어디에서 찾을 수 있나요? (출처) — 작업 시 Claude가 다시 읽을 수 있는 가져오기 가능한 URL이나 파일 경로로 제공합니다.

규칙과 출처를 혼합하면 파일이 무한히 커집니다. 규칙을 짧게 유지하고, 출처는 외부로 두세요.

3. 병합 전에 감사하고, 병합 후에는 하지 마세요

이름을 바꾸거나, 훅을 리팩터링하거나, 기능을 삭제하면 규칙이 조용히 동기화에서 벗어납니다. 해결책은 "더 조심하라"가 아니라 CI 단계입니다. 작성자는 agentlint(agentlint.net)라는 GitHub 앱을 만들어 모든 PR에서 규칙 표면을 감사합니다: 파일 간 모순, 삭제된 경로 참조, 버전에서 지원하지 않는 기능을 설명하는 규칙 등.

4. 추가보다 삭제를 더 많이 하세요

거의 모든 CLAUDE.md는 주당 한 개의 새 규칙을 얻고, 0개를 삭제합니다. 6개월 후에는 프랑켄슈타인 파일이 됩니다. 규율: 새 규칙 하나당 삭제할 규칙 하나를 찾으세요. 이 규율 덕분에 작성자의 파일은 100줄 미만으로 유지되고 있습니다.

핵심 패턴: 규칙 표면을 코드처럼 다루세요. 코드에는 테스트, 리뷰, 드리프트 감지가 있습니다. 규칙도 마찬가지가 필요합니다.