CLAUDE.md를 잘 작성하는 법: LLM 기반 코딩 에이전트를 위한 실무 가이드

AI 코딩 에이전트를 도입하려 해도 막상 CLAUDE.md를 어떻게 구성해야 할지는 막막합니다. 무엇을 넣어야 하고, 무엇을 빼야 하는지 기준이 불분명해 길고 복잡한 문서를 만들어 버리기 쉽습니다. 그런데 이렇게 만든 문서는 종종 에이전트에게 무시되거나, 오히려 성능을 떨어뜨리는 원인이 되기도 합니다.

이 글은 CLAUDE.md가 실제로 어떤 역할을 하는지, 왜 ‘짧고 보편적으로 적용 가능한 문서’가 가장 효과적인지, 그리고 실무에서 바로 적용할 수 있는 작성 원칙을 정리한 가이드입니다. 코딩 에이전트를 안정적이고 효율적으로 활용하고 싶다면, CLAUDE.md 구성 방식부터 정확히 이해하는 것이 출발점입니다.

반응형

CLAUDE.md의 역할과 목적

CLAUDE.md는 한마디로 에이전트를 코드베이스에 온보딩하는 문서입니다.
에이전트는 세션이 시작될 때마다 프로젝트에 대해 아무것도 모르는 상태이므로, 코드 구조, 목적, 기술 스택, 빌드 방식처럼 프로젝트 고유의 필수 정보가 필요합니다.

이 문서는 다음과 같은 성격을 가집니다.

• WHAT: 코드베이스의 구조·스택 정보
• WHY: 프로젝트의 목적·각 요소의 역할
• HOW: 빌드·테스트·작업 방식 안내

핵심은 에이전트가 어떤 프로젝트에서 어떤 방식으로 일해야 하는지 기본 환경을 제공하는 것입니다.

LLM의 특성과 문서가 필요한 이유

LLMs는 완전히 Stateless합니다.
즉, 이전 대화나 작업 맥락을 계속해서 기억하지 않습니다. 세션마다 새로운 모델이며, 그때그때 주어지는 문서(token)만을 기반으로 판단합니다.

따라서:

1. 모델은 세션 시작 시 코드베이스에 대해 아무것도 모른다.
2. 매 세션마다 필요한 정보를 반복해서 제공해야 한다.
3. 이 정보를 제공하는 가장 안정적인 방식이 CLAUDE.md이다.

또한 Claude Code에서는 시스템적으로 다음 문구가 삽입됩니다.

“이 맥락은 현재 작업에 관련 있을 수도, 없을 수도 있습니다. 관련이 높을 때만 사용하세요.”

즉, 문서 자체가 너무 길거나 불필요한 내용이 많으면 에이전트는 이를 “비관련”으로 판단하고 무시합니다.
따라서 짧고 핵심적인 문서가 더 잘 작동합니다.

좋은 CLAUDE.md 작성의 핵심 원칙

1. Less is more

LLM이 한 세션에서 안정적으로 따라갈 수 있는 지침 수는 대략 150~200개 정도입니다.
Claude Code 자체가 이미 약 50개의 시스템 지침을 포함하므로, CLAUDE.md가 비대해지면 모델은 전체 지침을 고르게 무시하게 됩니다.

따라서 CLAUDE.md에는 다음이 필요합니다.

• 모두에게 필요한 보편적 지침만 포함
• 모든 태스크에 해당되지 않는 규칙은 절대 포함하지 않기
• 길고 세세한 스크립트, 예외 규칙, 특정 상황 전용 설명은 제거

2. 문서는 ‘항상 관련 있는 내용’으로만 구성

LLM은 컨텍스트에서 “보편적이고 반복적으로 중요한 내용”을 최우선 참고합니다.
따라서 프로젝트 전반에 항상 필요한 정보만 넣어야 합니다.

예를 들어, 다음은 넣으면 안 됩니다.

• 특정 기능 구현 방법
• 특정 스키마 수정 방법
• 팀 내부 코딩 스타일 규칙
• 일회성 태스크에 필요한 정보

이런 내용은 CLAUDE.md에 있으면 오히려 방해가 됩니다.

3. 문서의 길이 기준

권장 기준은 다음과 같습니다.

• 300 lines 이하 권장
• 더 짧으면 더 좋음
• HumanLayer 기준 실제 문서는 60 lines 이하

문서가 짧아질수록 모델이 내용을 무시할 가능성이 줄어듭니다.

4. Progressive Disclosure (점진적 공개)

긴 문서를 한 번에 넣는 대신, 세부 작업 지침은 별도 파일로 분리하여 필요할 때만 보여주는 방식입니다.

예시 구조:

agent_docs/
  ├─ building_the_project.md
  ├─ running_tests.md
  ├─ code_conventions.md
  ├─ service_architecture.md
  ├─ database_schema.md

CLAUDE.md에는 이 파일들의 목록과 “필요하다고 판단되면 읽어라”는 안내만 적습니다.
이 방식은 문서를 작게 유지하며, 필요할 때만 추가 정보를 제공하기 때문에 최적입니다.

5. CLAUDE.md는 린터가 아니다

가장 흔한 실수 중 하나는 코드 스타일 규칙을 CLAUDE.md에 넣는 것입니다.
이 방법은 다음 이유로 비효율적입니다.

• LLM은 린팅·포매팅에 매우 느리고 비싸다
• 엄밀한 규칙 적용은 전통적 린터가 훨씬 정확하다
• 스타일 가이드는 CLAUDE.md를 불필요하게 비대하게 만들며, 무시될 가능성을 높인다

따라서 코드 스타일 검사는 반드시 자동화된 린터가 처리하고, CLAUDE.md에는 넣지 않는 것이 원칙입니다.

흔한 실수와 왜 문제가 되는가

1. 문서를 너무 길게 작성

→ 에이전트가 “비관련 정보”라고 판단해 거의 무시함.

2. 태스크 특정적인 정보 포함

→ 이번 작업과 무관한 내용이 전체 판단을 방해.

3. CLAUDE.md를 “명령 모음집”으로 오해

→ 너무 많은 규칙이 서로 충돌하거나 모델의 지침 처리 능력을 초과.

4. 코드 스타일 규칙 포함

→ 비효율적이고 문서가 쓸데없이 길어짐.

실무적 작성 팁 및 체크리스트

좋은 CLAUDE.md는 다음만 포함합니다.

• 프로젝트의 목적
• 기술 스택
• 폴더 구조(간략)
• 빌드·실행 방식
• 테스트 수행 방식
• 에이전트가 작업할 때 지켜야 할 기본 원칙
• 필요한 추가 문서가 있는 위치(Progressive Disclosure 안내)

포함하지 말아야 할 것:

• 장문의 코드 템플릿
• 스타일 가이드
• 스키마 설계 규칙
• 특정 기능의 상세 구현 방법
• 조직 내 프로세스
• Option이 많은 세세한 규칙

간단한 CLAUDE.md 예시

입력 문서를 기반으로 필요한 요소만 포함한 학습용 예시입니다.
(주의: 실제 프로젝트 정보를 넣어 구성해야 하며, 아래 예시 자체는 임의 정보가 아니라 문서에서 제시한 구조적 원칙만 반영합니다.)

# Project Purpose (WHY)
이 프로젝트는 서비스 전반의 기능을 제공하는 애플리케이션 코드베이스입니다. CLAUDE.md는 에이전트가 이 코드베이스에서 작업하기 위한 기본 정보를 제공합니다.

# Tech & Structure (WHAT)
- 프로젝트 기술 스택과 디렉터리 구조 등 기본적인 구조.
- 주요 애플리케이션, 공유 패키지, 모듈의 역할 설명.

# How to Work (HOW)
- 빌드 방식, 테스트 실행 방식 등 필수 작업 흐름.
- 작업 시 참고해야 할 추가 문서가 있는 경우 위치만 명시:
  - agent_docs/building_the_project.md
  - agent_docs/running_tests.md
  - agent_docs/code_conventions.md

# Guideline
- 모든 작업은 기존 코드 패턴을 우선적으로 따릅니다.
- 세부 구현 규칙이나 스타일 규칙은 CLAUDE.md에 포함하지 않으며, 필요시 관련 문서를 확인합니다.

CLAUDE.md는 AI 코딩 에이전트를 위한 중요한 진입점이지만, 지나치게 많은 정보를 담으면 오히려 역효과가 납니다. LLM은 Stateless하며, 너무 길고 복잡한 문서를 주면 “관련성이 낮다”고 판단해 무시할 수 있습니다. 따라서 핵심만 담고, 나머지 세부 사항은 Progressive Disclosure 방식으로 필요한 순간에만 공개하는 것이 최적의 구조입니다.

정리하면 다음과 같습니다.

• CLAUDE.md의 목적은 에이전트를 코드베이스에 온보딩하는 것
• 문서는 짧을수록 효율적이며, 보편적 규칙만 포함해야 한다
• 스타일 가이드는 절대 넣지 말 것
• 세부 정보는 별도 문서로 분리하여 필요할 때만 제공
• 잘 설계된 CLAUDE.md는 에이전트 작업 효율을 극대화한다

이 원칙을 적용하면 팀이 AI 에이전트를 사용할 때 일관된 품질을 유지할 수 있고, 에이전트가 더 정확하고 일관적으로 코드를 생성하게 됩니다.
CLAUDE.md는 단순한 문서가 아니라, 에이전트 도입 성공 여부를 결정하는 핵심 구성 요소입니다.

300x250

https://www.humanlayer.dev/blog/writing-a-good-claude-md?fbclid=IwY2xjawObK8JleHRuA2FlbQIxMQBzcnRjBmFwcF9pZBAyMjIwMzkxNzg4MjAwODkyAAEecFz3aYb6U3GQAuL6RRGRVdtMTUXOsVftJAg8YAn0YBwshdpmfPp3XGIxhWc_aem_O6km7niANaFrojU8nRJR5g

Writing a good CLAUDE.md