CLAUDE.md 작성 가이드: AI 에이전트에게 프로젝트 규칙을 전달하는 법
AI 코딩 에이전트를 처음 도입했을 때 가장 먼저 맞닥뜨리는 장벽은 "왜 내 규칙을 무시하지?"라는 질문입니다. 매 세션마다 프로젝트 구조를 설명하고, 어떤 라이브러리는 쓰지 말라고 당부하고, 테스트 명령어를 다시 알려주는 일이 반복됩니다. Claude Code는 이 문제를 해결하기 위해 CLAUDE.md라는 지시 파일을 도입했습니다. Cursor의 .cursorrules, GitHub Copilot의 .github/copilot-instructions.md처럼 다른 AI 코딩 도구들도 유사한 형식의 지시 파일을 지원하므로, 이 글에서 다루는 원칙 대부분은 도구에 관계없이 적용됩니다.
이 글을 읽고 나면 CLAUDE.md를 직접 작성하고, 팀 Git 저장소에 커밋해, AI 에이전트가 세션을 시작할 때부터 프로젝트 맥락을 이해하도록 만들 수 있습니다. CLAUDE.md를 올바르게 작성하면 AI 에이전트가 코드베이스를 스캔해도 알기 어려운 '암묵적 맥락'을 정확히 이해하고, 팀의 코딩 컨벤션과 아키텍처 결정을 일관되게 따르게 됩니다.
Claude Code를 아직 설치하지 않으셨다면 공식 문서를 먼저 참고하시면 됩니다.
핵심 개념
CLAUDE.md란 무엇인가
CLAUDE.md는 Claude Code가 프로젝트 세션 시작 시 자동으로 읽는 마크다운 지시 파일입니다. 빌드 명령어, 코딩 컨벤션, 아키텍처 결정의 배경, 워크플로 규칙처럼 코드베이스를 아무리 스캔해도 알기 어려운 맥락을 AI에게 전달하는 "영구적인 프로젝트 매뉴얼" 역할을 합니다.
CLAUDE.md — Claude Code가 세션마다 자동으로 로드하는 마크다운 지시 파일입니다. 팀의 규칙과 프로젝트 컨텍스트를 AI에게 지속적으로 전달합니다.
동일한 개념이 다른 에이전트에서도 동작합니다. OpenAI Codex, Cursor, GitHub Copilot 등은 AGENTS.md 또는 각자의 형식으로 유사한 지시 파일을 지원합니다. 2025년에는 Sourcegraph, OpenAI, Google, Cursor, Factory가 협력해 Linux Foundation 산하 Agentic AI Foundation에 AGENTS.md를 오픈 표준으로 제출했으며, GitHub에서 이미 60,000개 이상의 저장소가 채택했습니다.
파일 계층 구조
CLAUDE.md는 세 가지 레벨로 구성되며, 세 파일이 병합되어 적용됩니다.
| 위치 | 용도 | Git 관리 여부 |
|---|---|---|
~/.claude/CLAUDE.md |
개인 글로벌 지시 (모든 프로젝트 공통) | 개인 dotfiles |
{프로젝트 루트}/CLAUDE.md |
팀 공유 프로젝트 컨텍스트 | 추적 권장 |
{하위 디렉터리}/CLAUDE.md |
서브모듈·패키지별 스코프 지시 | 추적 권장 |
Claude는 해당 디렉터리를 읽을 때 하위 CLAUDE.md를 온디맨드로 로드합니다. 모노레포 환경에서는 이 계층 구조가 특히 강력하게 작동합니다.
초안을 자동 생성하는 /init 명령어
처음부터 빈 파일을 작성하는 대신, 프로젝트 루트에서 claude CLI를 실행한 뒤 /init 명령을 입력하면 Claude가 코드베이스를 분석해 CLAUDE.md 초안을 자동으로 만들어 줍니다. 이 초안을 검토하고 불필요한 내용을 제거하는 것이 가장 빠른 시작 방법입니다.
핵심 원칙: Less is More
모든 지시 줄마다 "이게 없으면 AI가 실수할까?"를 자문하는 것이 좋습니다. AI가 이미 올바르게 수행하는 동작을 적어두는 것은 노이즈입니다. 불필요한 지시는 중요한 규칙을 희석시킵니다. 또한 CLAUDE.md는 매 세션마다 토큰을 소비하기 때문에, 파일이 장황할수록 실제 작업에 사용할 수 있는 컨텍스트 창이 줄어듭니다. 실무 경험상 200줄 이하 유지를 권장하는 경우가 많습니다.
포함하면 좋은 것:
- 빌드·테스트·배포 명령어
- AI가 틀리기 쉬운 아키텍처 결정
- 금지된 라이브러리나 패턴
- 프로젝트 디렉터리 구조 (특히 모노레포)
- Git 워크플로
제외하는 것이 좋은 것:
- 코드 포매팅 규칙 (ESLint, Prettier, ruff 등 린터에 위임 가능한 것)
- AI가 이미 올바르게 수행하는 동작
- 전체 문서 파일 내용 (경로 참조로 대체 가능)
- 자주 변경되는 임시 메모
장단점 분석
실전 예시를 살펴보기 전에, CLAUDE.md의 한계와 주의사항을 미리 파악해두시면 예시를 더 비판적으로 읽을 수 있습니다.
장점
| 항목 | 내용 |
|---|---|
| 맥락 지속성 | 매 세션마다 프로젝트를 재설명할 필요가 없습니다 |
| 팀 일관성 | Git으로 관리하면 팀 전원이 동일한 AI 동작을 경험합니다 |
| 모노레포 세밀 제어 | 디렉터리별 파일로 서비스마다 다른 규칙을 독립 적용할 수 있습니다 |
| 온보딩 가속 | /init 명령으로 코드베이스를 분석해 초안을 자동 생성할 수 있습니다 |
| 에이전트 호환성 | AGENTS.md 표준을 병행하면 여러 AI 도구에서 동일한 규칙을 재사용할 수 있습니다 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 지시 무시 현상 | 파일이 길면 모델이 중간 내용을 사실상 무시합니다 | 200줄 이하로 유지하고 핵심 규칙은 앞뒤에 배치합니다 |
| 토큰 비용 | CLAUDE.md는 매 세션 토큰을 소비합니다 | 장황한 설명을 제거하고 문서는 경로 참조로 대체합니다 |
| 코드 스타일 지시 비효율 | ESLint·Prettier·ruff가 처리할 규칙을 CLAUDE.md에 적는 것은 낭비입니다 | 린터 설정 파일로 위임하고 CLAUDE.md에는 언급하지 않습니다 |
| 지시 충돌 | 루트와 하위 CLAUDE.md 간 상충 규칙은 예측 불가한 동작을 유발합니다 | 각 레벨의 책임 범위를 명확히 분리합니다 |
| MCP 과부하 | MCP 컨텍스트가 20k 토큰을 넘으면 실제 작업 가능한 컨텍스트가 급감합니다 | MCP 도구 수를 최소화하고 필요한 것만 연결합니다 |
MCP (Model Context Protocol) — Claude가 외부 도구(파일 시스템, 데이터베이스, API 등)와 연동할 때 사용하는 프로토콜입니다. MCP 도구가 많을수록 세션당 컨텍스트 소비가 늘어납니다.
실무에서 가장 흔한 실수
- CLAUDE.md를 문서화 도구로 오해하기 — 팀의 모든 컨벤션을 나열하다 보면 파일이 수백 줄을 넘기게 됩니다. AI가 이미 올바르게 하는 동작, 린터가 처리하는 규칙은 모두 제거하는 것이 좋습니다.
- 루트와 하위 CLAUDE.md의 역할 중복 — 루트에서 정의한 규칙을 하위 파일에도 반복 작성하면 충돌이 생기고 관리가 어려워집니다. 루트는 전체 공통 규칙만, 하위는 해당 패키지에만 해당하는 규칙만 담는 구조를 권장합니다.
- 초안을 검증 없이 Git에 커밋하기 —
/init명령으로 자동 생성된 초안에는 부정확한 명령어나 잘못된 경로가 포함될 수 있습니다. 실제 프로젝트에서 명령어를 직접 실행해 확인한 뒤 커밋하는 것이 안전합니다.
실전 적용
예시 1: 소규모 팀 / 풀스택 프로젝트 (추천 시작점)
Next.js + FastAPI 프로젝트를 운영하는 소규모 팀을 가정합니다. 꼭 필요한 것만 담은 최소 구조의 예시입니다. Commands 섹션에 주석을 달아 어느 쪽 스택에서 실행하는 명령인지 명확히 구분하는 것이 좋습니다.
# Project: E-Commerce Platform
Next.js 14 (App Router) + FastAPI 0.111 + PostgreSQL 16
## Commands
# 프론트엔드 (프로젝트 루트에서 실행)
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
# 백엔드 (/api 디렉터리에서 실행)
- Dev: `uvicorn main:app --reload`
- Test: `pytest -x`
- Lint: `ruff check .`
## Conventions
- TypeScript strict mode, async/await only (no .then())
- Server Components by default; Client Components only when needed
- Python: PEP 8 via ruff, type hints required
- DB migrations: Alembic only, never raw ALTER TABLE
## Architecture
- `/app` — Next.js routes and Server Actions
- `/api` — FastAPI routers (thin, business logic in services/)
- `/packages/shared` — shared TypeScript types| 섹션 | 역할 |
|---|---|
| 프로젝트 헤더 | 기술 스택을 한눈에 파악하게 해줍니다 |
| Commands | 매번 명령어를 물어보는 반복을 없애줍니다 |
| Conventions | AI가 틀리기 쉬운 패턴(.then() 사용 등)을 명시합니다 |
| Architecture | 디렉터리 역할을 잘못 이해해 생기는 코드 배치 오류를 방지합니다 |
예시 2: 모노레포 / 대규모 팀 (서비스별 규칙 분리)
규모가 큰 프로젝트에서는 루트 CLAUDE.md와 하위 디렉터리별 CLAUDE.md를 분리하는 것이 효과적입니다.
/CLAUDE.md
/frontend/CLAUDE.md
/backend/CLAUDE.md
/infra/CLAUDE.md각 파일에 담는 내용은 다음과 같이 분리됩니다.
# /CLAUDE.md — 전체 공통
## Git
- 브랜치 전략: feature/*, fix/*, chore/*
- PR merge는 squash merge만 사용
## CI
- `pnpm build` → `pnpm test` → `pnpm lint` 순서로 실행# /frontend/CLAUDE.md — 프론트엔드 전용
## React Conventions
- Server Component 기본, Client Component는 최소화
- Tailwind 클래스 순서: layout → spacing → color → effect
## State Management
- Zustand 사용, Redux 도입 금지# /backend/CLAUDE.md — 백엔드 전용
## NestJS Patterns
- 비즈니스 로직은 Service에, Controller는 thin 유지
- DTO로 입력 검증 필수, custom exception filter 사용
- 직접 TypeORM QueryBuilder 사용 금지 (Repository 패턴 사용)# /infra/CLAUDE.md — 인프라 전용
## Terraform
- 리소스 명명: {env}-{service}-{resource} 패턴
- 환경 변수를 코드에 하드코딩 금지
- `terraform plan` 출력을 PR 설명에 반드시 포함예시 3: 중요 규칙 / 파일 앞뒤 강조 배치
실무 경험에서 자주 보고되는 패턴으로, AI 모델이 파일의 앞부분과 뒷부분에 더 주의를 기울이는 경향이 있습니다. 자주 위반되는 규칙을 파일 맨 위와 맨 아래에 중복 배치하는 방법을 활용해볼 수 있습니다.
# ⚠️ CRITICAL RULES (읽는 즉시 적용)
- DB 마이그레이션은 반드시 Alembic 사용 (raw SQL ALTER TABLE 금지)
- 테스트 없이 서비스 레이어 코드 수정 금지
## Commands
- Dev: `pnpm dev` / `uvicorn main:app --reload`
- Test: `pnpm test` / `pytest -x`
## Architecture
- `/app` — Next.js routes and Server Actions
- `/api` — FastAPI routers (thin, business logic in services/)
# ⚠️ REMINDER (파일 끝 재강조)
- DB 마이그레이션은 반드시 Alembic 사용
- `pnpm test`로 테스트 통과 확인 후 코드 제출예시 4: 긴 세션 / 컴팩션 대응 패턴
Claude Code는 대화가 길어지면 오래된 메시지를 자동으로 요약·압축하는 컴팩션(compaction) 과정을 거칩니다. 이 과정에서 세션 초반에 논의했던 중요한 결정 사항이 유실될 수 있습니다. 아래 패턴은 컴팩션이 발생하더라도 반드시 보존해야 할 컨텍스트를 CLAUDE.md에 명시해, AI가 요약 시 이를 우선적으로 살려두도록 유도합니다.
## Session Management
When compacting, always preserve:
- 현재 작업 중인 브랜치명과 목표
- 완료된 마이그레이션 파일 목록
- 이번 세션에서 결정된 아키텍처 변경 사항
- 의도적으로 보류한 리팩터링 항목과 그 이유이 패턴이 필요한 상황은 주로 대규모 리팩터링, 다단계 마이그레이션, 또는 여러 파일에 걸친 기능 추가처럼 단일 세션에서 맥락이 누적되는 작업입니다. 세션 초반에 결정한 사항이 후반부에서 번복되는 현상을 경험하신 적이 있다면 이 패턴을 추가해보시면 좋습니다.
마치며
CLAUDE.md 하나를 잘 만들어두면, AI 에이전트와의 반복적인 맥락 설명에서 벗어나 실제 코드 작업에 집중할 수 있습니다. 직접 사용해보시면서 효과를 확인하시기 바랍니다.
지금 바로 시작해볼 수 있는 3단계:
- 초안 자동 생성 — 프로젝트 루트에서
claudeCLI를 열고/init명령을 실행해볼 수 있습니다. 생성된 파일을 열어 부정확한 명령어나 경로를 직접 수정하는 것부터 시작하시면 됩니다. - "AI가 없으면 틀릴 것" 필터 적용 — 초안의 각 줄을 검토하면서 린터가 처리하는 규칙과 AI가 이미 잘 따르는 관행을 제거하는 것을 권장합니다.
- 팀 Git 저장소에 커밋 — 검증된 CLAUDE.md를 프로젝트 루트에 커밋하면 팀 전원이 동일한 AI 경험을 공유할 수 있습니다. 모노레포라면
/frontend/CLAUDE.md,/backend/CLAUDE.md형태로 점진적으로 분리해 나가는 방식도 고려해보시면 좋습니다.
다음 글: Claude Code의 MCP(Model Context Protocol) 설정 가이드 — AI 에이전트가 데이터베이스, 파일 시스템, 외부 API를 안전하게 연동하는 방법
참고 자료
- Best Practices for Claude Code | Claude Code Docs — 공식 모범 사례
- Using CLAUDE.MD files: Customizing Claude Code for your codebase | Anthropic Blog — Anthropic 공식 블로그
- Writing a good CLAUDE.md | HumanLayer Blog — 실무 관점의 작성 가이드
- How to Write a Good CLAUDE.md File | Builder.io — 구조화 전략 상세 설명
- Creating the Perfect CLAUDE.md for Claude Code | Dometrain — 실전 예시 중심
- AGENTS.md vs CLAUDE.md: What's the Difference and When to Use Each | The Prompt Shelf — 표준 비교
- .cursorrules vs CLAUDE.md vs AGENTS.md | The Prompt Shelf — 도구별 형식 비교
- How to Configure Every AI Coding Assistant | DeployHQ — 멀티 도구 설정 가이드
- 5 Patterns That Make Claude Code Actually Follow Your Rules | DEV Community — 규칙 준수율 향상 패턴
- Steering AI Agents in Monorepos with AGENTS.md | DEV Community (Datadog) — 모노레포 적용 사례
- Claude Code Best Practices: Lessons From Real Projects | Ran the Builder — 실제 프로젝트 교훈
- GitHub — steipete/agent-rules — Claude Code / Cursor 공용 규칙 오픈소스
- GitHub — shanraisshan/claude-code-best-practice — 커뮤니티 모범 사례 모음