좋은 Claude.md 작성법 | GeekNews

LLM은 세션 간 학습이나 기억을 유지하지 않는 무상태(stateless) 함수이므로, Claude에게 코드베이스 정보를 매 세션마다 온전히 제공해야 합니다. 이를 위해 CLAUDE.md 파일은 Claude Code 에이전트의 모든 대화에 자동 포함되는 핵심 온보딩 문서 역할을 수행합니다.

CLAUDE.md의 역할 및 구성:
CLAUDE.md는 Claude가 프로젝트를 이해하도록 돕는 지도로서, 다음 세 가지 핵심 요소를 간결하게 담아야 합니다.
* WHAT (구조): 기술 스택, 프로젝트 구조, 모노레포 구성 등 코드베이스의 물리적 구조를 설명합니다.
* WHY (목적): 각 구성 요소의 목적과 기능을 명시하여 프로젝트의 상위 레벨 목표를 이해시킵니다.
* HOW (작동 방식): 빌드, 테스트, 타입 체크 등 실제 작업을 수행하는 방법을 간략하게 지시합니다.

Claude가 CLAUDE.md를 무시하는 이유:
Claude Code는 시스템 메시지에 "IMPORTANT: this context may or may not be relevant..."와 같은 리마인더를 삽입하여, 현재 작업과 관련 없는 문맥을 판단하고 무시할 수 있습니다. 파일에 보편적이지 않거나 불필요한 지시사항이 많을수록 Claude가 이를 무시할 가능성이 커지며, 이는 불필요한 지시를 무시할 때 결과 품질이 향상되기 때문입니다.

효과적인 CLAUDE.md 작성 원칙:

지시사항 최소화 (Less is more):

* LLM은 약 150~200개의 지시사항을 안정적으로 따를 수 있으며, Claude Code의 시스템 프롬프트에는 이미 약 50개의 지시사항이 포함되어 있습니다.
* 따라서 CLAUDE.md에는 보편적이고 필수적인 지시만 최소한으로 포함해야 합니다. 지시 수가 늘어날수록 전체 지시 수행 품질이 균등하게 저하됩니다.

파일 길이 및 적용 범위 관리:

* LLM은 집중적이고 관련성 높은 문맥에서 더 잘 작동합니다. CLAUDE.md는 모든 세션에 포함되므로, 보편적으로 적용 가능한 정보만 유지해야 합니다.
* 일반적으로 300줄 미만, 가능하면 60줄 미만으로 짧게 유지하는 것이 권장됩니다.

점진적 공개(Progressive Disclosure):

* 대형 프로젝트의 모든 정보를 한 파일에 담기 어렵기 때문에, 세부 지침은 agent_docs/ 폴더 내 별도 마크다운 파일로 분리합니다 (예: building_the_project.md, running_tests.md).
* CLAUDE.md에는 이 파일들의 목록과 간단한 설명, 그리고 Claude가 필요 시 해당 파일을 읽도록 하는 지시만 포함합니다.
* 코드 스니펫 대신 file:line 참조를 사용하여 최신성을 유지합니다.

Claude는 린터가 아님:

* 코드 스타일 가이드라인을 CLAUDE.md에 포함하는 것은 비효율적입니다. LLM은 비용이 높고 느리며, 린터보다 비결정적입니다.
* 스타일 규칙은 기존 코드 패턴을 통해 자연스럽게 학습되므로 별도 지시가 불필요합니다. 포맷팅은 Biome과 같은 자동 수정 가능한 린터를 활용하고, Claude에는 수정 결과만 전달해야 합니다.
* 필요 시 Stop Hook이나 Slash Command를 사용해 포맷팅/검증을 자동화할 수 있습니다.

자동 생성 금지 및 수작업 작성:

* /init 명령이나 자동 생성 기능으로 CLAUDE.md를 만드는 것은 권장되지 않습니다. 이 파일은 모든 세션과 산출물에 영향을 미치는 높은 영향 지점(high-leverage point)이므로, 잘못된 한 줄의 지시가 전체 코드 품질에 연쇄적인 악영향을 줄 수 있습니다.
* 따라서 모든 문장을 신중히 검토하고 수작업으로 작성해야 합니다.

결론:
CLAUDE.md는 Claude에게 코드베이스를 온보딩하는 핵심 문서로, WHAT, WHY, HOW를 명확히 정의해야 합니다. 지시사항은 최소화하고 보편적이고 간결한 내용만 포함해야 하며, 세부 정보는 Progressive Disclosure 방식으로 관리해야 합니다. Claude를 린터로 사용하지 않고 전용 도구와 훅/명령어 기능을 병행 활용해야 하며, 자동 생성 대신 신중한 수작업 작성을 통해 에이전트 하니스(agent harness) 전체의 품질을 극대화해야 합니다.