Claude Code를 도입한 팀 중에서 「기대하는 대로 코드가 나오는」 팀과 「매번 수정이 필요한」 팀의 차이를 조사해 보면, CLAUDE.md의 설계 품질에 도달하게 됩니다.

이 기사에서는 프로젝트 규모별로 구분하여 사용하는 7가지 CLAUDE.md 템플릿을 소개합니다. 개인 스크립트부터 대규모 모노레포(Monorepo)까지, 복사해서 바로 사용할 수 있는 실천적인 패턴 모음입니다.

• Claude Code CLI가 도입되어 있을 것 - 셸 환경은 macOS / Linux / WSL을 상정
• 기사 중의 템플릿은 Markdown 형식으로 기술

CLAUDE.md는 Claude Code가 코드를 생성·편집할 때 자동으로 읽어들이는 프로젝트 지시서입니다. 프롬프트에 매번 쓸 필요가 없는 「암묵적인 컨텍스트 (Implicit Context)」를 일원 관리할 수 있습니다.

주로 다음을 정의합니다.

• 프로젝트의 기술 스택(Tech Stack)·아키텍처 방침
• 코딩 규약·명명 규칙 (Naming Convention)
• 해서는 안 되는 조작 (안티 패턴 (Anti-pattern))
• 테스트·빌드·배포에 관한 명령어나 제약 사항

CLAUDE.md는 **3가지 스코프 (Scope)**로 배치할 수 있으며, 하위 단계일수록 우선순위가 높고 머지(Merge)됩니다.

포인트: 서브 디렉토리의 CLAUDE.md는 Claude Code가 해당 디렉토리 내의 파일을 조작할 때 추가로 읽어 들여집니다. 루트의 내용을 덮어쓰는 것이 아니라, 보충하는 설계로 만드는 것이 베스트입니다.

상정 규모: 1명 / 파일 수 110개 / 일회성소규모 툴

「너무 많이 쓰지 않는 것」이 최대의 포인트입니다. 개인 스크립트에 장대한 CLAUDE.md를 쓰는 것은 오버엔지니어링 (Over-engineering)입니다.

# CLAUDE.md
## 프로젝트 개요
CLI 툴. 표준 입력으로부터 CSV를 받아 집계 결과를 JSON으로 출력한다.
...

템플릿 사이즈 기준: 10~20행

필요한 것은 「무엇을 만들고 있는가」 「사용해도 되는 도구는 무엇인가」 「어떻게 구동하는가」의 3가지뿐입니다.

상정 규모: 25명 / 파일 수 50300개 / 웹 애플리케이션 (Web Application)

레이어드 아키텍처 (Layered Architecture)의 경계를 명시함으로써, Claude Code가 「어느 파일에 어떤 로직을 두어야 하는가」를 올바르게 판단할 수 있게 됩니다.

# CLAUDE.md
## 프로젝트 개요
사내용 재고 관리 시스템 (SaaS).
...

템플릿 사이즈 기준: 40~80행

「의존 방향 (Dependency Direction)」과 「해서는 안 되는 것」 섹션이 특히 효과적입니다. Claude Code는 이를 준수한 코드를 높은 정밀도로 생성하게 됩니다.

상정 규모: 5명 이상 / 패키지 수 3개 이상 / 모노레포 (Monorepo) 구성

규모가 커지면 1개 파일에 모든 것을 쓰는 것은 파탄 납니다. 루트에는 공통 방침만 쓰고, 각 패키지에 고유한 CLAUDE.md를 두는 것이 철칙입니다.

# CLAUDE.md (루트)
## 프로젝트 개요
EC 플랫폼. 모노레포 (pnpm workspace).
...

# CLAUDE.md (packages/api)
## 이 패키지의 책임
REST API 서버. 인증·재고·주문 도메인을 제공.
...

템플릿 사이즈 기준: 루트 2040행 ＋ 각 패키지 1530행

프로젝트 규모와는 별개의 축으로, Claude Code에게 특정 태스크를 시킬 때 효과적인 템플릿입니다. 루트의 CLAUDE.md에 추가하거나, ~/.claude/CLAUDE.md에 용도별 섹션으로서 관리합니다.

## 코드 리뷰 모드
다음 관점에서 리뷰해 주세요:
### 반드시 체크할 항목
...

## 테스트 생성 모드
### 방침
- 테스트 프레임워크: Vitest
...

리팩터링 (Refactoring) 모드

원칙

• 외부에서 보이는 동작(입출력)을 변경하지 않는다
  ...

CLAUDE.md는 "쓰면 쓸수록 좋은" 것이 아닙니다. 다음의 안티 패턴 (Anti-pattern)에 주의하세요.

개인 프로젝트: 1020행 -
팀 중규모: 4080행 -
모노레포 (루트): 2040행 + 각 패키지 1530행 합계가 500행을 넘으면 적신호

다음 3가지를 지키면 Claude Code의 출력 품질은 크게 향상됩니다.

규모에 맞는 템플릿을 선택한다. 개인 스크립트라면 미니멀형(10행), 팀 개발이라면 레이어 분리형(40~80행), 모노레포라면 계층 분할을 사용합니다. 과하거나 부족함 없이 작성하는 것이 가장 중요합니다. -
"해서는 안 될 일"을 반드시 작성한다. Claude Code는 "해야 할 일"보다 "해서는 안 될 일"에 대해 더 충실히 따르는 경향이 있습니다. 금지 사항을 명시하세요. -
한 달에 한 번, 정리한다. 기술 스택의 변경, 규칙의 추가 및 폐지를 반영하여 모순이나 비대화를 방지하세요. CLAUDE.md도 코드와 마찬가지로 지속적으로 유지보수해야 하는 대상입니다.

□ 프로젝트 개요를 1~2줄로 작성
□ 기술 스택을 나열
□ 디렉터리 구조와 각 디렉터리의 책임을 작성
...

• Claude Code 공식 문서 – Memory – CLAUDE.md의 작동 원리와 배치 방법 공식 해설
• Anthropic 공식 – Claude Code Overview – Claude Code의 전체 모습
• Claude Code Best Practices – Anthropic 공식 베스트 프랙티스 가이드