CLAUDE.md 파일 구조 설계 가이드 — 프로젝트 규모별 최적 구성
단일 파일부터 디렉토리별 분산까지, CLAUDE.md 파일 구조를 프로젝트 규모에 맞게 설계하는 방법.
한 줄 요약: CLAUDE.md는 프로젝트 규모와 팀 구조에 따라 단일 파일부터 디렉토리별 분산까지 다르게 설계해야 한다. 핵심은 Claude가 현재 작업에 필요한 맥락만 빠르게 읽을 수 있도록 구조화하는 것이다.
※ 이 글은 2026년 3월 기준으로 작성됐습니다.
CLAUDE.md의 역할 다시 정리
CLAUDE.md는 Claude Code 세션이 시작될 때 자동으로 로딩되는 프로젝트 컨텍스트 파일이다. Claude는 이 파일을 읽고 프로젝트 구조, 코딩 규칙, 금지 사항 등을 파악한 뒤 작업을 시작한다. 별도로 지시하지 않아도 자동 로딩된다는 점이 핵심이다.
CLAUDE.md가 하는 일은 크게 세 가지다:
- 세션 시작 시 자동 컨텍스트 전달: 프로젝트가 무엇인지, 어떤 기술 스택을 쓰는지, 어떤 규칙을 따르는지 Claude에게 알려준다.
- 반복 설명 제거: 매 세션마다 "이 프로젝트는 Next.js야, 이 파일은 건드리지 마"처럼 반복하지 않아도 된다.
- 팀 공유 규칙 문서화: git에 커밋하면 팀 전체가 같은 Claude 동작 기준을 공유할 수 있다.
CLAUDE.md의 작성법과 기본 구조는 Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드에서 다룬다. 이 글은 그 내용을 전제로, 파일 구조를 어떻게 설계하는지에 집중한다.
단일 파일 구조 (소규모 프로젝트)
프로젝트 루트에 CLAUDE.md 하나만 두는 방식이다. 사이드 프로젝트, 1~3인 팀, 또는 단일 언어/프레임워크만 쓰는 프로젝트에 적합하다.
단일 파일로 충분한 경우:
- 프론트엔드만 있는 Next.js / React 앱
- 혼자 개발하거나 팀이 2명 이하
- 모노레포가 아닌 단순 구조
- 언어·프레임워크 전환 없이 하나의 스택만 사용
단일 파일에 포함할 섹션 순서:
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를 오버라이드한다.
분산 구조가 필요한 경우:
- 프론트엔드(React) + 백엔드(Node/Go/Python)가 같은 레포에 있는 경우
- 팀 단위로 규칙이 다른 경우 (프론트팀 vs 백엔드팀)
- 모노레포에서 패키지별로 다른 코딩 컨벤션이 적용되는 경우
- 특정 디렉토리에만 추가 제한이 필요한 경우 (예: infrastructure/)
분산 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에서는 해당 파일을 참조하는 방식이 효과적이다.
| 파일명 | 역할 | 사용 시점 |
|---|---|---|
| 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가 이 파일의 규칙을 오버라이드할 수 있다"고 명시해두면 혼선을 방지할 수 있다.