저는 너무나 다양한 형태로 Claude를 사용합니다. 간단한 질문을 위한 채팅 앱, 장기적인 작업을 위한 프로젝트(Projects), 데스크톱 앱, 몇몇 스크립트에서 사용하는 API, 그리고 실제 코드베이스를 다루는 모든 것을 위한 터미널용 Claude Code까지 말이죠.

하지만 아무도 이 대가에 대해 경고해주지 않습니다. 바로 컨텍스트(context)가 이동하지 않는다는 점입니다. 모든 인터페이스는 각자의 섬과 같습니다. 채팅에서 Claude에게 프로젝트의 컨벤션(conventions)을 설명하고 훌륭한 결과물을 얻더라도, 다음 날 Claude Code를 열면 그 모든 것을 다시 설명해야 합니다. 이를 대여섯 개의 프로젝트에 적용해 보면, 다시 설명하는 과정이 AI를 사용하는 주된 비용이 되어버립니다.

지난 몇 달 동안 저는 프로젝트와 관련된 거의 모든 작업에 Claude Code로 조용히 수렴해 왔습니다. 모델이 달라서가 아니라, 단 하나의 파일 때문입니다. 바로 CLAUDE.md입니다. 이것은 제가 공들여 구축한 컨텍스트가 실제로 유지되는 유일한 장소입니다.

제가 마주한 장벽들

CLAUDE.md를 제대로 작동하게 만드는 데 생각보다 오랜 시간이 걸렸는데, 이는 제 사고 모델(mental model)이 틀렸기 때문입니다. 가장 큰 문제는 제가 이것을 일종의 시스템 프롬프트(system prompt), 즉 모델이 항상 준수해야 하는 깨지지 않는 규칙이라고 가정했다는 점입니다. 하지만 그렇지 않습니다. 그것은 일반적인 메시지로 전달되며 권고 사항(advisory)일 뿐입니다. Claude는 이를 읽고 따르려고 노력하지만, 파일이 너무 길거나 모순되면 그냥 잊혀집니다. 제가 대문자로 써놓은 규칙을 Claude Code가 그대로 무시하고 지나가는 것을 처음 보았을 때, 저는 제품이 고장 난 줄 알았습니다. 고장 난 것이 아니었습니다. 제 파일이 너무 길어서 규칙이 묻혀버린 것이었습니다.

그것이 계기가 되어 깊이 파고들게 되었고, 제가 배운 것들은 정말로 직관에 반하는 것들이었습니다:

• 모든 턴마다 모든 줄이 토큰 비용을 발생시킵니다. 비대해진 CLAUDE.md는 Claude를 더 똑똑하게 만드는 것이 아니라, 오히려 당신의 말을 무시하게 만듭니다. 이제 저는 모든 줄에 대해 다음과 같은 테스트를 거칩니다: "이 줄을 삭제해도 실수가 발생할까?" 만약 그렇지 않다면, 삭제합니다.
• /compact 명령 이후에는 프로젝트 루트의 CLAUDE.md만 다시 나타납니다. 하위 디렉토리에 있는 중첩된 CLAUDE.md 파일들과 채팅에서만 언급했던 모든 내용이 그냥 사라져 버립니다. 저는 세션 중간에 규칙들을 잃어버리고 있었으면서도 왜 그런지 전혀 알지 못했습니다.
• @path 임포트는 컨텍스트 (Context)를 저장하지 않습니다. 저는 파일의 부담을 줄일 수 있을 거라 생각하여 파일을 임포트 방식으로 나누었습니다. 하지만 이들은 어차피 실행 시점에 로드됩니다. 즉, 이들은 조직화 (Organisation)를 돕는 것이지 컨텍스트를 돕는 것이 아닙니다.

이 중 어느 것도 마케팅 자료에는 나와 있지 않습니다. 저는 직접 부딪히며 이 사실들을 깨달았습니다.

실제로 도움이 되는, 잘 알려지지 않은 부분들

멘탈 모델 (Mental model)이 잡히고 나니, 몇 가지 덜 알려진 기능들이 프롬프트 수정 (Prompt-tweaking)을 아무리 하는 것보다 저에게 더 큰 도움이 되었습니다:

• 경로 범위 지정 규칙 (Path-scoped rules). CLAUDE.md가 파일 하나로 감당하기 너무 커지면, .claude/rules/*.md로 분리하세요. paths: 글로브 (Glob) 패턴이 포함된 규칙은 Claude가 일치하는 파일을 읽을 때만 로드됩니다. 따라서 서브시스템 (Subsystem)별 지침은 매 턴마다 비용을 발생시키는 것이 아니라, 관련이 있을 때만 컨텍스트 비용을 소모합니다.
• 무엇을 넣을지에 대한 트리거 (Trigger). 저는 무엇이 CLAUDE.md에 포함되어야 하는지 고민하는 것을 멈추고 한 가지 규칙을 사용하기 시작했습니다: 반복해서 말해야 할 상황이 생기는 즉시 한 줄을 추가하세요. Claude가 같은 실수를 두 번 반복하거나, 리뷰 과정에서 Claude가 알았어야 할 것을 잡아내거나, 새로운 팀원이 동일한 컨텍스트를 필요로 하는 경우입니다.
• "완료"를 검증 가능하게 만들기. 스톱 훅 (Stop hook)을 사용하면 체크가 통과될 때까지 턴이 종료되는 것을 차단할 수 있습니다. 또는 /goal 조건을 사용하여 별도의 평가자 (Evaluator)가 조건이 충족될 때까지 Claude가 계속 작업하도록 유지할 수 있습니다. 이것이 바로 긴 실행 과정이 "다 된 것 같다"에서 멈추지 않고 정직하게 마무리될 수 있게 해주는 방법입니다.

그래서 저는 이것들을 수집하기 시작했습니다

어느 시점에 저는 제가 다른 모든 사람들이 겪고 있는 것과 동일한 교훈들을 병렬적으로 역공학 (Reverse-engineering)하고 있다는 사실을 깨달았습니다. 그리고 유용한 지침들은 블로그 포스트, GitHub 리포지토리 (Repos), HN 스레드 등에 흩어져 있었으며, Claude Code가 변경 사항을 출시함에 따라 점점 쓸모없게 되어가고 있었습니다.

그래서 저는 State of CLAUDE.md를 만들었습니다. 이는 실무자들이 배우고 있는 내용을 추적하는 큐레이션된 CLAUDE.md 템플릿으로, 모든 기술적 주장(technical claim)은 배포 전 공식 문서(official docs)를 통해 검증됩니다. 마지막 부분이 생각보다 중요한데, 그 이유는 그럴듯해 보이는 수많은 팁이 검증 과정을 통과하지 못하기 때문입니다. 예를 들어, "프롬프트 캐시(prompt-cache) 적중률을 극대화하기 위해 안정적인 규칙을 상단에 배치하라"는 인기 있는 팁은 한 에디션에서 제외되었습니다. 듣기에는 맞지만, 문서에는 없었기 때문입니다. (그리고 이 검증 방식은 양방향으로 작용합니다. 제가 동일한 방식으로 제외했던 주장이 다음 에디션에서 문서가 업데이트됨에 따라 실제 사실로 밝혀지기도 했습니다.)

이 프로젝트는 무료이며 MIT 라이선스를 따릅니다. 템플릿 자체와 무엇이 왜 바뀌었는지에 대한 변경 이력(changelog), 그리고 Claude Code 프리미티브(primitives) 가이드 — MCP, 훅(hooks), 플랜 모드(plan mode), 그리고 이 파일 전체가 형성하고자 하는 에이전틱 코딩 루프(agentic-coding loop) — 를 포함하고 있습니다.

같은 상황에 처해 있다면

만약 당신이 다섯 가지 환경에서 Claude를 사용하며 매일 자신을 다시 설명하고 있다면, 프로젝트 작업을 Claude Code로 통합하고 하나의 제대로 된 CLAUDE.md를 만드는 데 진정한 노력을 기울여 보세요. 짧게 유지하고, 코드처럼 취급하며, Claude가 무언가를 무시하는 즉시 가지치기(prune) 하십시오.

저는 여전히 정보를 수집하고 있습니다. 제가 주시해야 할 소스가 있거나, 당신의 CLAUDE.md에서 자리를 잡은 규칙이 있다면 진심으로 듣고 싶습니다.