좋은 Claude.md 작성법

• LLM은 상태를 저장하지 않는 함수이므로, CLAUDE.md는 매 세션마다 Claude에게 코드베이스를 소개하는 핵심 문서로 작동함
• 파일에는 프로젝트의 WHAT(구조) , WHY(목적) , HOW(작동 방식) 을 간결히 담아야 하며, 불필요한 명령어 과잉은 성능 저하로 이어짐
• Claude는 시스템 메시지의 지시에 따라 CLAUDE.md의 내용을 관련성이 낮다고 판단하면 무시할 수 있음
• 효과적인 파일은 짧고 보편적으로 적용 가능한 정보만 포함하고, 세부 지침은 별도 문서로 분리해 Progressive Disclosure 방식으로 관리해야 함
• CLAUDE.md는 에이전트 하니스의 가장 높은 영향 지점이므로 자동 생성 대신 신중하게 수작업으로 작성해야 함

LLM의 무상태성과 CLAUDE.md의 역할

• LLM은 추론 시점에 고정된 가중치를 사용하며, 세션 간 학습이나 기억을 유지하지 않음
  • 따라서 모델이 코드베이스를 이해하려면 입력 토큰으로 모든 정보를 제공해야 함
• Claude Code 같은 코딩 에이전트는 메모리를 명시적으로 관리해야 하며, CLAUDE.md는 모든 대화에 자동 포함되는 유일한 파일임
• 이로 인해 다음 세 가지가 필수적임
  1. 세션 시작 시 Claude는 코드베이스에 대해 아무것도 모름
  2. 매 세션마다 필요한 정보를 다시 알려야 함
  3. 이를 위한 표준 수단이 CLAUDE.md임

코드베이스 온보딩: WHAT, WHY, HOW

• CLAUDE.md는 Claude가 프로젝트를 이해하도록 돕는 온보딩 문서 역할을 함
  • WHAT: 기술 스택, 프로젝트 구조, 모노레포 구성 등 코드 지도를 제공
  • WHY: 각 구성 요소의 목적과 기능을 설명
  • HOW: 빌드·테스트·타입체크 등 실제 작업 수행 방법을 명시
• 단, 모든 명령어를 나열하는 것은 비효율적이며, 필요 최소한의 정보만 포함해야 함

Claude가 CLAUDE.md를 무시하는 이유

• Claude Code는 사용자 메시지에 다음과 같은 시스템 리마인더를 삽입함 IMPORTANT: this context may or may not be relevant...
  • 이로 인해 Claude는 해당 문맥이 현재 작업과 관련 없다고 판단하면 무시함
• 파일에 보편적이지 않은 지시사항이 많을수록 무시될 가능성이 커짐
• Anthropic이 이를 추가한 이유는, 불필요한 지시를 무시할 때 결과 품질이 향상되었기 때문으로 추정됨

좋은 CLAUDE.md 작성 원칙

Less (instructions) is more

• LLM은 약 150~200개의 지시사항을 안정적으로 따를 수 있음
  • 작은 모델일수록 성능 저하가 급격하며, 다단계 작업에는 부적합
• Claude Code의 시스템 프롬프트에는 이미 약 50개의 지시사항이 포함되어 있음
  • 따라서 CLAUDE.md에는 보편적이고 필수적인 지시만 최소한으로 포함해야 함
• 지시 수가 늘수록 전체 지시 수행 품질이 균등하게 저하됨

파일 길이와 적용 범위

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

Progressive Disclosure

• 대형 프로젝트에서는 모든 정보를 한 파일에 담기 어렵기 때문에, 점진적 공개(Progressive Disclosure) 방식을 권장
  • 세부 지침은 agent_docs/ 폴더 내 별도 마크다운 파일로 분리
  • 예: building_the_project.md, running_tests.md, code_conventions.md 등
• CLAUDE.md에는 이 파일들의 목록과 간단한 설명, 그리고 Claude가 필요 시 읽도록 하는 지시만 포함
• 코드 스니펫 대신 file:line 참조를 사용해 최신성을 유지
• 이는 Claude Skills 개념과 유사하나, 도구 사용보다는 지시 관리에 초점

Claude는 린터가 아님

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

자동 생성 금지

• /init 명령이나 자동 생성 기능으로 만든 CLAUDE.md는 비추천
  • 이 파일은 모든 세션과 산출물에 영향을 미치는 고레버리지 지점이기 때문
• 잘못된 한 줄의 지시가 전체 코드 품질에 연쇄적 악영향을 줄 수 있음
• 따라서 모든 문장을 신중히 검토하고 수작업으로 작성해야 함

결론

• CLAUDE.md는 Claude를 코드베이스에 온보딩하기 위한 문서로, WHY·WHAT·HOW를 명확히 정의해야 함
• 지시사항은 최소화하고, 보편적이고 간결한 내용만 포함
• Progressive Disclosure를 통해 필요한 정보만 단계적으로 제공
• Claude를 린터로 사용하지 말고, 전용 도구와 훅·명령어 기능을 병행 활용
• 자동 생성 대신 신중한 수작업 작성으로 하니스 전체 품질을 극대화해야 함