좋은 CLAUDE.md 작성법

좋은 CLAUDE.md 작성법

원문: https://www.humanlayer.dev/blog/writing-a-good-claude-md
저자: Kyle
작성일: 2025년 11월 25일
읽는 시간: 약 10분

---

참고: 이 글은 OpenCode, Zed, Cursor, Codex 같은 에이전트 도구에서 사용하는 오픈소스 버전인 AGENTS.md에도 동일하게 적용됩니다.

핵심 원칙: LLM은 (거의) 무상태다

LLM은 상태를 저장하지 않는 함수입니다. 추론 시점에 가중치가 이미 고정되어 있기 때문에, 시간이 지나도 새로운 것을 학습하지 않습니다. 모델이 여러분의 코드베이스에 대해 아는 건 오직 여러분이 직접 입력한 토큰뿐입니다.

Claude Code 같은 코딩 에이전트도 마찬가지입니다. 에이전트의 메모리는 여러분이 직접 관리해야 합니다. CLAUDE.md(또는 AGENTS.md)는 에이전트와 나누는 모든 대화에 기본으로 포함되는 유일한 파일입니다.

여기서 세 가지 중요한 사실을 알 수 있습니다:

1. 코딩 에이전트는 매 세션 시작 시 코드베이스에 대해 아무것도 모른다.
2. 세션을 시작할 때마다 코드베이스의 중요한 정보를 직접 알려줘야 한다.
3. 이를 위한 가장 좋은 방법이 바로 CLAUDE.md다.

CLAUDE.md는 Claude의 온보딩 문서다

Claude는 매 세션마다 코드베이스를 처음 보는 것과 같습니다. 따라서 CLAUDE.md를 통해 Claude를 프로젝트에 온보딩시켜야 합니다. 크게 보면 다음 세 가지를 다뤄야 합니다:

• WHAT (무엇을): 사용하는 기술 스택, 프로젝트 구조를 설명하세요. Claude에게 코드베이스의 지도를 그려주세요. 특히 모노레포에서 중요합니다! 어떤 앱들이 있는지, 공유 패키지는 무엇인지, 각각의 용도가 무엇인지 알려주면 Claude가 필요한 것을 어디서 찾아야 할지 알 수 있습니다.
• WHY (왜): 프로젝트의 목적을 설명하세요. 저장소에 있는 각 부분이 어떤 역할을 하는지, 왜 존재하는지 알려주세요.
• HOW (어떻게): 프로젝트 작업 방식을 알려주세요. node 대신 bun을 쓰나요? 실제로 의미 있는 작업을 하려면 어떤 정보가 필요한지 모두 포함하세요. 변경사항은 어떻게 검증하나요? 테스트, 타입 체크, 빌드는 어떻게 실행하나요?

하지만 작성 방식이 중요합니다! Claude가 실행할 수 있는 모든 명령어를 CLAUDE.md에 욱여넣으려 하면 오히려 결과가 나빠집니다.

Claude는 CLAUDE.md를 자주 무시한다

어떤 모델을 사용하든, Claude가 CLAUDE.md 내용을 자주 무시한다는 걸 눈치챌 수 있습니다.

ANTHROPIC_BASE_URL로 Claude Code CLI와 Anthropic API 사이에 로깅 프록시를 넣어보면 직접 확인할 수 있습니다. Claude Code는 CLAUDE.md 파일과 함께 다음과 같은 시스템 리마인더를 사용자 메시지에 주입합니다:

<system-reminder>
      IMPORTANT: this context may or may not be relevant to your tasks. 
      You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

즉, Claude는 현재 작업과 관련 없다고 판단하면 CLAUDE.md 내용을 무시합니다. 보편적으로 적용할 수 없는 정보가 파일에 많을수록, Claude가 지시사항을 무시할 확률이 높아집니다.

Anthropic은 왜 이렇게 만들었을까요? 확실하진 않지만 추측은 가능합니다. 우리가 본 대부분의 CLAUDE.md 파일에는 실제로 광범위하게 적용할 수 없는 지시사항이 잔뜩 들어 있습니다. 많은 사용자가 마음에 안 드는 동작을 "핫픽스"하려고 별로 범용적이지 않은 지시사항을 계속 추가하는 식으로 이 파일을 사용합니다.

Claude Code 팀은 아마도 잘못된 지시사항을 무시하게 하는 편이 오히려 결과가 더 좋다는 걸 발견한 것 같습니다.

좋은 CLAUDE.md 파일 만들기

이 섹션에서는 컨텍스트 엔지니어링 모범 사례에 따라 좋은 CLAUDE.md를 작성하는 여러 가지 권장사항을 소개합니다.

결과는 상황에 따라 다를 수 있습니다. 이 규칙들이 모든 환경에 최적인 건 아닙니다. 다른 모든 것과 마찬가지로, 규칙을 깨도 됩니다. 단,

1. 언제, 왜 규칙을 깨도 되는지 이해하고 있고
2. 그럴 만한 충분한 이유가 있을 때만

지시사항은 적을수록 좋다

Claude가 실행할 수 있는 모든 명령어와 코드 표준, 스타일 가이드를 전부 CLAUDE.md에 넣고 싶은 유혹이 있을 겁니다. 권장하지 않습니다.

아직 엄밀하게 연구되진 않았지만, 일부 연구에서 다음과 같은 결과가 나왔습니다:

1. 최신 사고형(thinking) LLM은 약 150~200개의 지시사항을 합리적으로 일관되게 따를 수 있습니다. 작은 모델은 큰 모델보다, 비사고형(non-thinking) 모델은 사고형 모델보다 더 적은 지시사항만 처리할 수 있습니다.
2. 작은 모델은 훨씬 빠르게 성능이 떨어집니다. 구체적으로, 작은 모델은 지시사항 수가 늘어날수록 지시사항 준수 성능이 지수적으로 감소하는 반면, 큰 최신 사고형 모델은 선형적으로 감소합니다(아래 그래프 참조). 따라서 다단계 작업이나 복잡한 구현 계획에는 작은 모델을 쓰지 않는 게 좋습니다.
3. LLM은 프롬프트의 양 끝에 있는 지시사항에 더 집중합니다: 맨 앞(Claude Code 시스템 메시지와 CLAUDE.md)과 맨 뒤(가장 최근 사용자 메시지)
4. 지시사항이 많아지면 모든 지시사항의 준수율이 균일하게 떨어집니다. 새로운 지시사항(파일 아래쪽에 있는 것)만 무시하는 게 아니라, 모든 지시사항을 골고루 무시하기 시작합니다.

우리가 분석한 결과, Claude Code의 시스템 프롬프트에는 이미 약 50개의 개별 지시사항이 포함되어 있습니다. 모델에 따라 다르지만, 에이전트가 안정적으로 따를 수 있는 지시사항의 거의 1/3을 이미 차지하는 셈입니다. 규칙, 플러그인, 스킬, 사용자 메시지는 아직 추가하지도 않았는데 말이죠.

결론적으로, CLAUDE.md 파일에는 가능한 한 적은 지시사항만 넣어야 합니다. 이상적으로는 모든 작업에 보편적으로 적용되는 것만요.

CLAUDE.md 파일 길이와 범용성

다른 조건이 같다면, 컨텍스트 윈도우가 집중적이고 관련성 높은 내용으로 채워져 있을 때 LLM의 성능이 더 좋습니다. 예제, 관련 파일, 도구 호출과 결과 같은 것들이요. 관련 없는 내용이 많으면 성능이 떨어집니다.

CLAUDE.md는 모든 세션에 들어가므로, 내용이 최대한 범용적이어야 합니다.

예를 들어, 새 데이터베이스 스키마를 어떻게 구조화하라는 지시사항은 넣지 마세요. 전혀 관련 없는 작업을 할 때는 쓸모없고 모델만 산만하게 만듭니다!

길이도 마찬가지로 '적을수록 좋다' 원칙이 적용됩니다. Anthropic의 공식 권장 길이는 없지만, 일반적으로 300줄 미만이 좋고, 짧을수록 더 좋다는 게 중론입니다.

HumanLayer의 루트 CLAUDE.md 파일은 60줄도 안 됩니다.

점진적 공개(Progressive Disclosure)

특히 큰 프로젝트에서는 Claude에게 알려주고 싶은 모든 것을 간결한 CLAUDE.md 하나에 담기 어려울 수 있습니다.

이럴 때 점진적 공개 원칙을 활용하면 Claude가 필요할 때만 작업별/프로젝트별 지시사항을 보게 할 수 있습니다.

프로젝트 빌드 방법, 테스트 실행법, 코드 컨벤션 등 모든 지시사항을 CLAUDE.md에 넣는 대신, 프로젝트 어딘가에 설명적인 이름을 가진 별도의 마크다운 파일로 분리하세요.

예시:

agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- service_architecture.md
  |- database_schema.md
  |- service_communication_patterns.md

그리고 CLAUDE.md에는 이 파일들의 목록과 간단한 설명만 포함하고, Claude에게 관련 있는 파일이 무엇인지 판단해서 작업 전에 읽으라고 지시하세요. 또는 Claude가 읽고 싶은 파일을 먼저 제시하고 승인을 받은 후 읽게 할 수도 있습니다.

복사본보다 포인터를 선호하세요. 이 파일들에 코드 스니펫을 직접 넣지 마세요. 금방 구식이 됩니다. 대신 파일:라인번호 형식으로 참조해서 Claude가 원본 코드를 직접 보게 하세요.

개념적으로 Claude Skills의 작동 방식과 비슷하지만, 스킬은 지시사항보다 도구 사용에 더 초점을 맞춥니다.

Claude는 (비싼) 린터가 아니다

CLAUDE.md에 가장 흔하게 들어가는 것 중 하나가 코드 스타일 가이드입니다. 린터가 할 일을 LLM에게 시키지 마세요. LLM은 전통적인 린터나 포매터에 비해 비싸고 엄청나게 느립니다. 결정론적 도구를 쓸 수 있다면 언제나 그걸 쓰세요.

코드 스타일 가이드를 넣으면 지시사항과 대부분 관련 없는 코드 스니펫이 컨텍스트 윈도우에 잔뜩 들어가서, LLM의 성능과 지시사항 준수율이 떨어지고 컨텍스트 윈도우만 낭비됩니다.

LLM은 인컨텍스트 학습자입니다! 코드가 특정 스타일 가이드나 패턴을 따르고 있다면, 코드베이스를 몇 번 검색하거나 좋은 리서치 문서가 있으면 에이전트가 별도 지시 없이도 기존 코드의 패턴과 컨벤션을 알아서 따르는 경향이 있습니다.

정 스타일이 중요하다면, 포매터와 린터를 실행한 뒤 오류를 Claude에게 보여주는 Claude Code Stop 훅을 설정하는 걸 고려해보세요. Claude가 직접 포매팅 문제를 찾게 하지 마세요.

보너스 팁: 자동 수정 기능이 있는 린터(저희는 Biome을 선호합니다)를 사용하고, 안전하게 자동 수정할 수 있는 규칙을 신중하게 설정해서 커버리지를 최대화하세요.

코드 가이드라인을 포함하고 버전 관리의 변경사항이나 git status를 Claude에게 보여주는 슬래시 명령어를 만들 수도 있습니다. 이렇게 하면 구현과 포매팅을 분리해서 처리할 수 있습니다. 둘 다 결과가 더 좋아질 겁니다.

/init이나 자동 생성을 쓰지 마세요

Claude Code와 OpenCode 기반 하네스 모두 CLAUDE.md(또는 AGENTS.md)를 자동 생성하는 기능을 제공합니다.

CLAUDE.md는 Claude Code와의 모든 세션에 들어가기 때문에, 하네스에서 가장 레버리지가 높은 지점 중 하나입니다. 어떻게 쓰느냐에 따라 결과가 크게 좋아지거나 나빠질 수 있습니다.

나쁜 코드 한 줄은 그냥 나쁜 코드 한 줄입니다. 하지만 구현 계획의 나쁜 한 줄은 많은 나쁜 코드를 만들어낼 수 있습니다. 시스템 작동 방식을 잘못 이해한 리서치 문서의 나쁜 한 줄은 계획에서 많은 문제를 일으키고, 결과적으로 훨씬 더 많은 나쁜 코드로 이어집니다.

그런데 CLAUDE.md는 워크플로의 모든 단계와 그로부터 생성되는 모든 결과물에 영향을 미칩니다. 그래서 파일에 들어가는 모든 줄을 신중하게 생각하는 데 시간을 투자해야 합니다:

결론

1. CLAUDE.md는 Claude를 코드베이스에 온보딩시키는 문서입니다. 프로젝트의 WHY(왜), WHAT(무엇을), HOW(어떻게)를 정의해야 합니다.
2. 지시사항은 적을수록 좋습니다. 꼭 필요한 지시사항을 빠뜨리면 안 되지만, 합리적으로 가능한 한 적게 유지하세요.
3. CLAUDE.md 내용은 간결하고 범용적으로 유지하세요.
4. 점진적 공개를 활용하세요. Claude에게 알려줄 수 있는 모든 정보를 다 넣지 마세요. 대신 중요한 정보를 찾는 방법을 알려줘서, 필요할 때만 찾아 쓰게 하세요. 컨텍스트 윈도우와 지시사항 수가 불필요하게 늘어나는 걸 막을 수 있습니다.
5. Claude는 린터가 아닙니다. 린터와 포매터를 쓰고, 필요하면 훅이나 슬래시 명령어 같은 기능을 활용하세요.
6. CLAUDE.md는 하네스에서 레버리지가 가장 높은 지점이므로, 자동 생성하지 마세요. 최상의 결과를 위해 직접 신중하게 작성해야 합니다.

---

출처 정보

• 원문 URL: https://www.humanlayer.dev/blog/writing-a-good-claude-md
• 저작권: © 2025 HumanLayer
• 번역일: 2025년 12월 13일