한 줄 요약: CLAUDE.md는 프로젝트 규모와 팀 구조에 따라 단일 파일부터 디렉토리별 분산까지 다르게 설계해야 한다. 핵심은 Claude가 현재 작업에 필요한 맥락만 빠르게 읽을 수 있도록 구조화하는 것이다. CLAUDE.md는 Claude Code 세션이 시작될 때 자동으로 로딩되는 프로젝트 컨텍스트 파일이다. Claude는 이 파일을 읽고 프로젝트 구조, 코딩 규칙, 금지 사항 등을 파악한 뒤 작업을 시작한다.
한 줄 요약: CLAUDE.md는 프로젝트 규모와 팀 구조에 따라 단일 파일부터 디렉토리별 분산까지 다르게 설계해야 한다. 핵심은 Claude가 현재 작업에 필요한 맥락만 빠르게 읽을 수 있도록 구조화하는 것이다.
※ 이 글은 2026년 3월 기준으로 작성됐습니다.
CLAUDE.md는 Claude Code 세션이 시작될 때 자동으로 로딩되는 프로젝트 컨텍스트 파일이다. Claude는 이 파일을 읽고 프로젝트 구조, 코딩 규칙, 금지 사항 등을 파악한 뒤 작업을 시작한다. 별도로 지시하지 않아도 자동 로딩된다는 점이 핵심이다.
CLAUDE.md가 하는 일은 크게 세 가지다:
CLAUDE.md의 작성법과 기본 구조는 Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드에서 다룬다. 이 글은 그 내용을 전제로, 파일 구조를 어떻게 설계하는지에 집중한다.
프로젝트 루트에 CLAUDE.md 하나만 두는 방식이다. 사이드 프로젝트, 1~3인 팀, 또는 단일 언어/프레임워크만 쓰는 프로젝트에 적합하다.
단일 파일로 충분한 경우:
단일 파일에 포함할 섹션 순서:
CLAUDE.md — 단일 파일 기본 구조# CLAUDE.md ## 1. 프로젝트 정의 - 프로젝트 이름, 목적, URL - 주요 사용자 (누구를 위한 서비스인지) ## 2. 기술 스택 - 언어: TypeScript 5.x - 프레임워크: Next.js 14 (App Router) - 스타일: Tailwind CSS - 배포: Vercel ## 3. 디렉토리 구조 ``` src/ ├── app/ ← 페이지 및 레이아웃 ├── components/ ← 공통 UI 컴포넌트 ├── lib/ ← 유틸리티 함수 └── data/ ← 정적 데이터 ``` ## 4. 코딩 규칙 - 컴포넌트: PascalCase, 파일당 하나 - 함수: camelCase - CSS: Tailwind 우선, 인라인 스타일 금지 - 타입: interface 우선, any 금지 ## 5. 금지 사항 - console.log 커밋 금지 (개발 중엔 허용) - 하드코딩된 API 키 금지 — .env 사용 - pages/ 디렉토리 신규 생성 금지 (App Router 사용) ## 6. 검증 명령 ```bash npm run build # 빌드 전 반드시 확인 npm run lint # 커밋 전 실행 ```
루트 CLAUDE.md는 프로젝트 전체의 공통 규칙만 담고, 각 하위 디렉토리에 별도 CLAUDE.md를 두는 방식이다. Claude는 현재 작업 디렉토리에서 가장 가까운 CLAUDE.md를 우선 적용하며, 하위 디렉토리의 CLAUDE.md가 루트 CLAUDE.md를 오버라이드한다.
분산 구조가 필요한 경우:
분산 CLAUDE.md 구조 예시project-root/ ├── CLAUDE.md ← 전체 공통 규칙 (짧게 유지) ├── frontend/ │ ├── CLAUDE.md ← React / Tailwind 전용 규칙 │ └── src/ ├── backend/ │ ├── CLAUDE.md ← Node.js / API 전용 규칙 │ └── src/ ├── infrastructure/ │ ├── CLAUDE.md ← Terraform / AWS 전용 규칙 │ └── terraform/ └── docs/ └── CLAUDE.md ← 문서 작성 규칙 (선택)
루트 CLAUDE.md에는 공통 규칙만 넣는다. 예를 들어 커밋 메시지 형식, 브랜치 전략, 보안 공통 원칙 등이다. 특정 언어나 프레임워크 규칙은 해당 디렉토리의 CLAUDE.md에만 작성한다.
루트 CLAUDE.md — 공통 규칙만# CLAUDE.md (루트) ## 프로젝트 정의 모노레포: frontend(React) + backend(Node.js) + infrastructure(Terraform) ## 공통 규칙 - 커밋 메시지: [feat|fix|docs|refactor]: 설명 - 브랜치: main(프로덕션), develop(통합), feature/XXX - 환경변수: 절대 하드코딩 금지, .env.example 유지 - 비밀키/토큰: 코드에 포함 금지 ## 하위 디렉토리 규칙 - frontend/ 작업 시 frontend/CLAUDE.md도 함께 읽을 것 - backend/ 작업 시 backend/CLAUDE.md도 함께 읽을 것 - infrastructure/ 작업 시 반드시 infrastructure/CLAUDE.md 확인
CLAUDE.md 하나에 모든 규칙을 담으면 파일이 너무 길어진다. 이를 방지하기 위해 역할별로 파일을 분리하고, CLAUDE.md에서는 해당 파일을 참조하는 방식이 효과적이다.
| 파일명 | 역할 | 사용 시점 |
|---|---|---|
| CLAUDE.md | 프로젝트 정의 + 핵심 규칙 요약 | 항상 (자동 로딩) |
| RULE.md | 세부 코딩 규칙, 네이밍 컨벤션 | CLAUDE.md에서 참조 지시 |
| SKILL.md | 자주 쓰는 작업 패턴, 슬래시 커맨드 정의 | 반복 작업 자동화 시 |
| POST_TEMPLATE.md | 콘텐츠 포스트 작성 기준 | 콘텐츠 사이트 운영 시 |
| INGESTION_RULES.md | 데이터 수집·처리 규칙 | 자동화 파이프라인 있는 경우 |
| ARTICLE_SCHEMA.md | 기사/포스트 데이터 스키마 정의 | 데이터 구조 명세가 필요한 경우 |
CLAUDE.md에서 보조 파일을 참조하는 방법은 간단하다. 세션 시작 시 지시로 명시하면 된다:
CLAUDE.md — 보조 파일 참조 방법# CLAUDE.md > 세션 시작 시 반드시 RULE.md, SKILL.md도 함께 읽을 것. ## 프로젝트 정의 ... ## 핵심 규칙 (요약) - 세부 코딩 규칙은 RULE.md 참조 - 반복 작업 패턴은 SKILL.md 참조 - 포스트 작성 시 POST_TEMPLATE.md 참조
각 섹션에 무엇을 얼마나 써야 하는지는 프로젝트마다 다르지만, 기준을 정해두면 파일이 불필요하게 길어지는 것을 방지할 수 있다.
| 섹션 | 포함할 내용 | 권장 분량 | 주의사항 |
|---|---|---|---|
| 프로젝트 정의 | 이름, 목적, URL, 주요 사용자 | 5줄 이내 | 배경설명 과다 금지 |
| 기술 스택 | 언어, 프레임워크, DB, 배포 환경 | 10줄 이내 | 버전 명시 권장 |
| 디렉토리 구조 | 핵심 디렉토리만, 짧은 한 줄 설명 | 15줄 이내 | 모든 파일 나열 금지 |
| 코딩 규칙 | 네이밍, 포맷, 금지 패턴 요약 | 10~20줄 | 세부 규칙은 RULE.md로 분리 |
| 금지 사항 | 절대 하면 안 되는 것 (하드코딩, 특정 파일 수정 금지 등) | 5~10줄 | 구체적으로 명시할수록 좋음 |
| 검증 명령 | 빌드, 린트, 테스트 명령어 | 5줄 이내 | 실제 동작하는 명령만 |
| 참조 파일 | 보조 파일 목록 및 읽는 조건 | 3~5줄 | 세션 지시 형태로 작성 |
1. 정기적으로 업데이트할 것
프로젝트가 성장하면 디렉토리 구조, 기술 스택, 규칙이 바뀐다. CLAUDE.md가 오래된 정보를 담고 있으면 Claude가 잘못된 맥락을 기반으로 작업한다. 주요 변경이 있을 때마다 CLAUDE.md도 함께 업데이트하는 것을 습관으로 만들어야 한다. 파일 상단에 마지막 업데이트: YYYY-MM-DD를 명시하면 오래된 파일을 쉽게 파악할 수 있다.
2. git으로 버전 관리할 것
CLAUDE.md는 반드시 git에 커밋해서 관리한다. .gitignore에 넣으면 안 된다. 팀 전체가 같은 기준으로 Claude를 사용하려면 CLAUDE.md가 코드베이스의 일부여야 한다. 변경 이력도 남아서 "언제 어떤 규칙이 바뀌었는지" 추적이 가능하다.
3. 팀원과 합의 후 작성할 것
혼자 쓰는 프로젝트라면 자유롭게 쓰면 되지만, 팀 프로젝트라면 CLAUDE.md의 규칙이 팀 전체에 적용된다. 특히 금지 사항 섹션은 팀 논의를 거쳐 확정하는 것이 좋다. 규칙이 너무 많거나 지나치게 제한적이면 실제 개발 흐름을 방해할 수 있다.
4. 검증 명령은 실제 동작하는 것만 넣을 것
CLAUDE.md에 적힌 명령어는 Claude가 실제로 실행할 수 있다. 가상의 명령어나 프로젝트에 존재하지 않는 스크립트를 넣으면 오히려 혼란이 생긴다. npm run build, node --check 등 실제로 해당 프로젝트에서 동작하는 명령만 포함한다.
5. 하위 CLAUDE.md는 상위 규칙을 오버라이드한다는 점을 명시할 것
분산 구조를 쓸 때는 루트 CLAUDE.md에 "하위 디렉토리별 CLAUDE.md가 이 파일의 규칙을 오버라이드할 수 있다"고 명시해두면 혼선을 방지할 수 있다.
단일 파일로 갈지 분산 구조로 갈지부터 정하시면 됩니다. 판단 기준은 단순합니다. 프론트엔드만 있는 단일 스택에 팀이 2명 이하라면 루트에 CLAUDE.md 하나로 충분하고, 프론트(React)와 백엔드(Node·Go·Python)가 한 레포에 섞여 있거나 모노레포에서 패키지별 컨벤션이 다르면 루트에는 커밋 규칙·브랜치 전략 같은 공통 규칙만 두고 frontend/, backend/, infrastructure/ 각각에 별도 CLAUDE.md를 두는 분산 구조가 맞습니다. 이때 하위 디렉토리 파일이 루트를 오버라이드한다는 점을 루트에 명시해 두는 것을 잊지 마세요.
파일을 무한정 길게 키우는 것이 가장 흔한 실수입니다. 본문 주의 callout에서 짚었듯 CLAUDE.md는 세션 시작 때마다 통째로 로딩되므로 200줄을 넘기면 매번 토큰을 낭비합니다. 디렉토리 전체 파일 트리를 붙여넣거나 세부 코딩 규칙까지 한 파일에 몰아넣지 말고, 핵심 디렉토리만 한 줄 설명으로 남기고 상세 규칙은 RULE.md·SKILL.md로 분리해 참조만 거는 것이 맞습니다. 두 번째 함정은 권한 설정을 CLAUDE.md에 섞는 것입니다. allowedTools나 차단 명령 같은 권한은 .claude/settings.json 전용이고, 프로젝트 맥락·코딩 규칙만 CLAUDE.md에 둬야 둘이 충돌하지 않습니다. 마지막으로 존재하지 않는 가상 명령어를 검증 섹션에 적으면 클로드 코드가 실제로 실행하려다 막히니, npm run build처럼 실제 동작하는 명령만 넣으세요.
여기서 대안은 단일 파일 구조와 분산 구조입니다. 단일 파일은 프론트만 있는 단일 스택에 팀이 2명 이하이고 모노레포가 아닐 때 가장 적합합니다. 한 파일만 관리하면 되니 동기화 부담이 없습니다. 분산 구조는 프론트(React)와 백엔드(Node·Go·Python)가 한 레포에 섞이거나, 모노레포에서 패키지별 컨벤션이 다르거나, infrastructure/처럼 특정 디렉토리에만 추가 제한이 필요할 때 맞습니다. 다만 소규모인데 분산 구조를 쓰면 파일이 흩어져 오히려 관리가 번거롭고, 반대로 다중 스택인데 단일 파일을 고집하면 한 파일이 비대해져 토큰만 낭비합니다. 규모와 스택 다양성을 기준으로 고르시면 됩니다.
이 글은 구조 설계에 집중했으니, 다음은 두 갈래로 파시면 됩니다. 작성법 자체는 가이드 #2 CLAUDE.md 완벽 가이드에서 섹션별 문장 다듬는 법을 보시고, 권한 쪽은 가이드 #17 보안·권한 관리로 넘어가 .claude/settings.json의 allowedTools와 차단 명령 설정을 익히세요. 공식 문서에서는 Memory 문서를 핵심 키워드로 검색하면 됩니다. 여기서 하위 디렉토리 CLAUDE.md가 상위를 오버라이드하는 계층 로딩 규칙과, @path 임포트로 보조 파일을 끌어오는 문법을 확인할 수 있어 이 글의 분산 구조를 그대로 구현하는 데 직접 도움이 됩니다.
CLAUDE.md는 프로젝트 규모와 스택 다양성에 따라 단일 파일이냐 디렉토리별 분산이냐를 다르게 설계해야 한다는 글입니다. 소규모 단일 스택은 루트 한 파일로 충분하고, 모노레포·다중 언어는 루트에 공통 규칙만 두고 하위 디렉토리에 특화 규칙을 분산합니다. 어느 경우든 한 파일은 200줄 이내로 가볍게 유지하고 세부 규칙은 RULE.md 같은 보조 파일로 빼며, 권한 설정은 settings.json에 분리하는 것이 핵심 원칙입니다.
