좋은 CLAUDE.md 작성법

Who Should Read

Claude Code, Cursor, Zed, Codex 같은 AI 코딩 에이전트를 팀 프로젝트나 개인 작업에 쓰고 있는 개발자. 특히 CLAUDE.md를 만들어뒀는데 에이전트가 무시하는 것 같아 답답했던 분들.

Core Mechanics

• LLM은 본질적으로 상태가 없는(stateless) 함수다. 가중치가 학습 후 고정되기 때문에 매 세션이 시작될 때마다 코드베이스에 대해 아무것도 모르는 상태에서 출발한다. CLAUDE.md는 이 상태를 보완하기 위해 매 대화에 자동으로 주입되는 유일한 파일이다.
• CLAUDE.md에는 WHAT(기술 스택, 프로젝트 구조), WHY(프로젝트 목적, 각 컴포넌트의 역할), HOW(bun vs node 같은 실행 방식, 테스트·타입체크·빌드 방법)를 담아야 한다. 모노레포라면 어떤 앱이 있고 공유 패키지가 뭔지 반드시 명시해야 에이전트가 길을 잃지 않는다.
• Claude Code는 내부적으로 CLAUDE.md를 system-reminder 태그로 감싸서 주입하면서 'IMPORTANT: this context may or may not be relevant to your tasks'라는 문구를 함께 삽입한다. 그 결과 Claude는 현재 작업과 무관하다고 판단하면 CLAUDE.md 내용 전체를 무시할 수 있다.
• Anthropic이 이 동작을 추가한 이유로 추정되는 건, 많은 사용자가 CLAUDE.md를 '핫픽스' 용도로 남용해서 특정 상황에만 해당되는 지시를 잔뜩 쌓아두는 패턴이 오히려 품질을 떨어뜨렸기 때문이다. 에이전트 입장에서 불필요한 지시를 걸러내도록 한 것이 전체 결과를 개선시켰을 것으로 본다.
• 지시 수가 많아질수록 준수율이 떨어진다는 연구 결과가 있다. 대형 프런티어 모델(thinking 모드 포함)은 150~200개 지시까지 선형적으로 성능이 저하되는 반면, 소형 모델은 지시가 늘어날수록 지수적으로 급격히 나빠진다. 즉, 작은 모델일수록 CLAUDE.md를 짧게 유지하는 게 훨씬 중요하다.
• 권장 패턴은 '목차(Table of Contents)' 방식이다. CLAUDE.md에는 각 작업 유형별 상세 지시 파일 목록과 간단한 설명만 두고, 에이전트가 필요한 파일을 직접 찾아 읽도록 한다. 예를 들어 'CSS 추가 시 docs/ADDING_CSS.md를 먼저 읽어라'는 식이다. 이렇게 하면 관련 없는 지시가 컨텍스트 창을 오염시키지 않는다.
• CLAUDE.md를 직접 쓰는 대신, Claude 자신이 작성하고 업데이트하게 하는 방법도 효과적이다. 'README.md는 사용자용, CLAUDE.md는 너를 위한 것'이라고 알려준 뒤 'CLAUDE.md를 업데이트해서 앞으로 매번 API 문서를 먼저 확인하도록 해'라고 지시하면, 에이전트가 스스로 효과적인 표현으로 작성한다.
• Anthropic 공식 문서에서는 CLAUDE.md를 여러 위치(루트, 부모 디렉토리, 자식 디렉토리, 홈 디렉토리)에 둘 수 있다고 안내한다. 특히 자식 디렉토리의 CLAUDE.md는 해당 디렉토리 파일 작업 시 자동으로 컨텍스트에 포함되므로, 임의 파일명의 마크다운보다 CLAUDE.md 다중 배치가 더 자연스럽게 동작한다.

Evidence

• 'Mr Tinkleberry'라는 별명으로 Claude가 CLAUDE.md를 읽고 있는지 테스트하는 사람 이야기가 공유됐다. 대화 중간에 해당 호칭을 안 쓰면 지시를 무시하고 있다는 신호로 해석한다는 것이다. 실용적인 '주의력 지표'로 주목받았다.
• CLAUDE.md 실효성에 회의적인 의견도 많았다. '새 메서드는 50줄 이하로 작성하라'는 지시를 넣어도 Claude가 계속 무시했다는 경험담, Claude Code와 Codex를 매일 쓰는데 context를 리셋하고 지시를 수동으로 다시 붙여넣는 게 더 낫다는 의견 등이 있었다.
• 코드베이스 자체를 CLAUDE.md 대신 활용하자는 대안도 제시됐다. 린팅, 타입체크, 유닛테스트를 자동화하고 'Claude가 항상 이 체크를 완료 전에 실행하도록' 지시하면, CLAUDE.md를 계속 수정하는 것보다 코드 품질 도구로 에이전트를 제어하는 게 더 안정적이라는 주장이었다.
• 댓글 중 'LLM에게 컨텍스트를 많이 줄수록 고복잡도 작업의 품질 상한선이 낮아진다'는 경험을 공유한 개발자가 있었다. GPT-3.5 시절부터 매일 수 시간씩 LLM을 써온 사람으로, 고난도 문제일수록 코드에 주석과 빈 줄을 제거한 '클린 뷰'만 LLM에 넘긴다고 했다. 새 모델들은 방대한 컨텍스트를 처리하지만 품질 상한선이 낮아지는 건 여전하다고 주장했다.
• 일부는 CLAUDE.md가 사실상 개발자가 아닌 LLM을 위한 문서화 작업이며, 코드가 빠르게 변하는 환경에서 금방 구식이 된다는 점을 비판했다. '인간을 위한 README를 쓰는 게 맞다, 그게 앞으로 가야 할 방향'이라는 의견과 함께, 'CLAUDE.md 설정에 이 정도 공수가 필요하다면 차라리 직접 코딩하겠다'는 현실적 반응도 있었다.

How to Apply

• CLAUDE.md가 길어져서 Claude가 무시하는 것 같다면, 목차 방식으로 재구성한다. 루트 CLAUDE.md에는 '작업 유형 → 읽어야 할 파일' 매핑만 두고(예: 'CSS 작업 시 docs/ADDING_CSS.md 참고'), 상세 지시는 별도 파일로 분리한다. Claude가 관련 파일만 필요할 때 읽으므로 불필요한 컨텍스트 오염을 막을 수 있다.
• Claude가 CLAUDE.md를 실제로 읽는지 확인하려면, '항상 나를 [특정 호칭]으로 불러라' 같은 고유한 지시를 넣어두고 에이전트 응답에서 그 호칭이 나오는지 모니터링한다. 호칭이 사라지면 지시가 무시되고 있다는 신호다.
• 모노레포나 대형 프로젝트라면 서브 디렉토리마다 CLAUDE.md를 배치한다. Anthropic 공식 문서에 따르면 자식 디렉토리의 CLAUDE.md는 해당 디렉토리 파일 작업 시 자동으로 컨텍스트에 포함된다. 임의 파일명 마크다운보다 CLAUDE.md 다중 배치가 더 안정적으로 동작한다.
• CLAUDE.md를 직접 수작업으로 유지보수하기 번거롭다면, Claude에게 위임한다. 'README는 사용자용, CLAUDE.md는 너를 위한 문서'라고 먼저 알려준 뒤, 작업이 끝날 때마다 'README와 CLAUDE.md를 업데이트해'라고 지시하면 에이전트가 스스로 효과적인 표현으로 자신의 온보딩 문서를 갱신한다.

Code Example

# CLAUDE.md 목차 방식 예시

## Documentation References

- CSS 작업 시: docs/ADDING_CSS.md
- 에셋 추가 시: docs/ADDING_ASSETS.md
- 사용자 데이터 작업 시: docs/STORAGE_MANAGER.md

## Stack
- Runtime: Bun (not Node)
- Tests: `bun test`
- Typecheck: `bun tsc --noEmit`

Terminology

Related Resources

• https://www.humanlayer.dev/blog/writing-a-good-claude-md
• https://www.anthropic.com/engineering/claude-code-best-practices
• https://gist.github.com/scpedicini/179626cfb022452bb39eff10b...
• https://gist.github.com/ctoth/d8e629209ff1d9748185b9830fa4e7...