큰 코드베이스에서 CLAUDE.md를 어떻게 작성해야 할까?

Claude Code를 실제 업무 코드베이스에 적용하다 보면 금방 이런 문제를 만나게 됩니다.

작은 프로젝트에서는 루트에 CLAUDE.md 하나를 두는 것만으로도 충분합니다. 하지만 코드베이스가 커지면 이야기가 달라집니다. 수십 개의 프로젝트가 있고, 그 안에 다시 수백 개의 폴더가 나뉘어 있는 구조라면 어떨까요?

이런 경우에 CLAUDE.md를 하나의 거대한 설명서처럼 작성하면 오히려 문제가 생깁니다. Claude가 매번 읽어야 하는 정보가 너무 많아지고, 중요한 규칙은 묻히며, 오래된 설명과 최신 코드가 충돌할 가능성도 커집니다.

그래서 큰 코드베이스에서 CLAUDE.md를 운영할 때는 관점을 바꿔야 합니다.

CLAUDE.md는 코드베이스 백과사전이 아니라, Claude가 반복해서 실수하지 않도록 돕는 짧은 작업 규칙 파일에 가깝습니다.

이 글은 Anthropic의 Claude Code 공식 문서(Memory, Best Practices)를 기준으로, 큰 코드베이스에서 CLAUDE.md를 어떻게 나누고 작성하면 좋을지 정리한 내용입니다.

---

1. CLAUDE.md는 무엇인가?

Claude 공식 문서에 따르면 CLAUDE.md는 Claude Code가 프로젝트나 사용자 워크플로에 대한 지속 지침을 얻기 위해 읽는 Markdown 파일입니다. 각 세션은 새로운 컨텍스트 윈도우로 시작되기 때문에, Claude에게 매번 알려줘야 하는 프로젝트 규칙이나 작업 방식을 CLAUDE.md에 담아둘 수 있습니다.

공식 문서에서 설명하는 핵심은 다음입니다.

• CLAUDE.md = 사용자가 작성하는 지속 지침 파일
• Auto memory = Claude가 작업 중 스스로 축적하는 학습 메모리

CLAUDE.md에는 주로 이런 내용을 담습니다.

• 빌드 명령
• 테스트 명령
• 코드 스타일
• 워크플로 규칙
• 프로젝트 아키텍처 관련 판단
• Claude가 코드만 보고 알기 어려운 주의사항

반대로, 이런 내용은 넣지 않는 것이 좋습니다.

• 코드만 읽으면 알 수 있는 파일 설명
• 일반적인 개발 상식
• 긴 API 문서
• 자주 바뀌는 정보
• 파일별 상세 설명
• 장문의 튜토리얼

Best Practices 문서도 CLAUDE.md에는 Claude가 코드만으로 추론하기 어려운 Bash 명령, 코드 스타일, 테스트 지침, 저장소 관례, 프로젝트 특유의 아키텍처 결정, 흔한 gotcha를 넣고, 코드에서 알 수 있는 내용이나 긴 설명은 제외하라고 안내합니다.

---

2. 큰 코드베이스에서 흔히 하는 실수

큰 코드베이스에서 가장 흔한 실수는 루트 CLAUDE.md에 모든 폴더 설명을 넣으려는 것입니다.

예를 들면 이런 식입니다.

# Repository Structure
- apps/admin: 관리자 서비스
- apps/commerce: 커머스 서비스
- apps/creator: 작가 관리 서비스
- packages/ui: 공통 UI 컴포넌트
- packages/api: API 공통 모듈
- packages/utils: 공통 유틸
...

처음에는 도움이 되는 것처럼 보입니다. 하지만 프로젝트가 커질수록 이 방식은 금방 한계에 부딪힙니다.

문제는 세 가지입니다.

첫째, 너무 길어집니다. 공식 문서는 CLAUDE.md가 세션 시작 시 컨텍스트로 로드되며, 파일이 길수록 컨텍스트를 더 많이 소비하고 지시 준수율이 낮아질 수 있다고 설명합니다. 공식 문서는 파일당 200줄 미만을 목표로 하라고 안내합니다.

둘째, 금방 낡습니다. 큰 코드베이스에서는 폴더 구조와 책임이 계속 바뀝니다. 루트 CLAUDE.md에 폴더 설명을 과도하게 적어두면 실제 코드와 문서가 어긋날 가능성이 큽니다.

셋째, Claude가 실제로 따라야 할 규칙이 묻힙니다. CLAUDE.md는 많이 적는다고 좋은 문서가 아닙니다. Best Practices 문서는 *"이 줄을 지웠을 때 Claude가 실수할 가능성이 있는가?"*를 기준으로 판단하고, 아니라면 삭제하라고 설명합니다.

---

3. 큰 코드베이스에서는 "상위 공통 규칙 + 하위 폴더별 규칙"이 적합하다

대형 코드베이스에서는 CLAUDE.md를 계층적으로 나누는 것이 좋습니다.

구조는 대략 이렇습니다.

repo-root/
├── CLAUDE.md
├── apps/
│   ├── admin/
│   │   └── CLAUDE.md
│   ├── commerce/
│   │   └── CLAUDE.md
│   └── creator/
│       └── CLAUDE.md
├── packages/
│   ├── ui/
│   │   └── CLAUDE.md
│   └── shared/
│       └── CLAUDE.md
└── .claude/
    └── rules/
        ├── api.md
        ├── frontend.md
        └── testing.md

역할은 이렇게 나눌 수 있습니다.

• 루트 CLAUDE.md = 전체 레포 공통 원칙, 작업 방식, 금지사항, 탐색 절차, 공통 검증 원칙
• 하위 CLAUDE.md = 해당 프로젝트나 폴더에만 적용되는 구체 규칙, 패턴, Do / Don't, 테스트 방법
• .claude/rules/ = 특정 경로, 파일 타입, 주제에 반복 적용되는 규칙
• Skills = 매번 로드할 필요는 없지만 필요할 때 꺼내 쓰는 긴 절차나 플레이북

이 방식의 핵심은 간단합니다.

루트에는 "모든 곳에 적용되는 원칙"만 둔다. 하위 폴더에는 "그 폴더에서만 중요한 규칙"만 둔다.

참고로 프로젝트 CLAUDE.md는 ./CLAUDE.md와 ./.claude/CLAUDE.md 두 위치 중 어디에 두어도 됩니다. 본문에서는 편의상 ./CLAUDE.md로 통일해 표기합니다.

---

4. 하위 프로젝트에서 작업할 때 상위 CLAUDE.md는 적용될까?

적용됩니다. 단, 로드 시점이 다릅니다.

공식 문서에 따르면 Claude Code는 CLAUDE.md를 다음과 같이 로드합니다.

• 현재 작업 디렉터리의 상위 디렉터리들에 있는 CLAUDE.md와 CLAUDE.local.md → 세션 시작 시 모두 로드
• 현재 작업 디렉터리의 하위 디렉터리에 있는 CLAUDE.md → 시작 시에는 로드되지 않고, Claude가 그 디렉터리의 파일을 읽을 때 그때그때(on demand) 로드

즉, 하위 파일이 상위 파일을 덮어쓰는 것이 아니라, 발견된 파일들이 모두 이어 붙여져 컨텍스트에 들어갑니다. 순서는 파일시스템 루트에서 현재 작업 디렉터리 방향입니다.

예를 들어 아래 위치에서 Claude Code를 실행한다고 가정해보겠습니다.

cd repo/apps/admin
claude

그러면 세션 시작 시점에 다음 파일들이 함께 로드됩니다.

repo/CLAUDE.md
repo/apps/CLAUDE.md          # 있다면
repo/apps/admin/CLAUDE.md

만약 repo/apps/admin/components/에 또 다른 CLAUDE.md가 있다면, 이 파일은 시작 시점에는 로드되지 않다가 Claude가 그 폴더의 파일을 실제로 읽을 때 로드됩니다.

이때 중요한 점은 덮어쓰기 구조가 아니라 함께 로드되는 구조라는 것입니다.

따라서 상위 CLAUDE.md와 하위 CLAUDE.md가 서로 충돌하면 Claude가 임의로 하나를 따를 수 있습니다. 공식 문서도 서로 모순되는 규칙이 있으면 Claude가 임의로 선택할 수 있으므로, 오래되었거나 충돌하는 지시를 주기적으로 정리하라고 안내합니다.

그래서 하위 CLAUDE.md에는 이런 문장을 넣어두는 것이 좋습니다.

This file adds directory-specific rules. Follow the root CLAUDE.md unless a rule here is more specific to this directory.

한국어로 작성한다면 이렇게 쓸 수 있습니다.

이 파일은 이 디렉터리 전용 규칙입니다. 루트 CLAUDE.md의 공통 규칙을 따르되, 이 디렉터리에 대해서는 이 파일의 더 구체적인 규칙을 우선합니다.

---

5. 루트 CLAUDE.md에는 무엇을 써야 할까?

루트 CLAUDE.md는 전체 코드베이스의 "헌법"에 가깝습니다.

여기에는 특정 폴더의 상세 도메인 설명보다, 모든 프로젝트에서 공통으로 지켜야 할 원칙을 적는 것이 좋습니다.

예시는 다음과 같습니다.

# Repository Guide

This is a large multi-project repository. Keep changes narrow, verified, and localized.

## Core Rules
- Do not assume domain behavior from directory or file names alone.
- Explore before editing unfamiliar areas.
- Prefer minimal, localized changes over broad refactors.
- Follow existing patterns in the nearest similar files.
- Do not introduce new dependencies without explicit approval.
- Do not edit generated files.
- Do not modify migration files unless explicitly requested.

## Unknown Domain Protocol
When working in an unfamiliar folder:
1. Read the nearest README, CLAUDE.md, package config, and tests.
2. Identify entry points, call sites, and existing patterns before editing.
3. Summarize your understanding before making behavior changes.
4. Make the smallest safe change.
5. Run the narrowest relevant verification command.
6. If the change affects money, permissions, privacy, security, or user data, explain the impact before editing.

## Verification
- Prefer targeted tests over full test suites.
- If no test exists, describe the safest manual verification path.
- Report which commands were run and their results.

여기서 중요한 것은 "이 레포는 어떤 폴더가 있다"를 길게 설명하는 것이 아닙니다. 오히려 중요한 것은 Claude에게 다음을 알려주는 것입니다.

• 낯선 폴더에서 바로 수정하지 말 것
• 먼저 어떤 파일을 읽어야 하는지
• 어디까지 수정해도 되는지
• 어떤 영역은 조심해야 하는지
• 변경 후 어떻게 검증해야 하는지

특히 도메인 지식이 없는 폴더가 많다면, 도메인 설명을 억지로 추정해서 쓰기보다 도메인을 모를 때의 탐색 절차를 적는 것이 안전합니다.

---

6. 하위 폴더별 CLAUDE.md는 어떻게 작성해야 할까?

하위 폴더의 CLAUDE.md는 짧아야 합니다.

공식 문서는 파일당 200줄 미만을 기준으로 제시합니다. 다만 실무적으로는 하위 폴더별 파일은 20~40줄 정도가 더 안정적이라고 느꼈습니다(이 부분은 글쓴이 경험에 기반한 권장값입니다). 이유는 명확합니다. 하위 폴더의 CLAUDE.md는 설명서가 아니라 "작업 규칙"이어야 하기 때문입니다.

추천하는 형식은 다음입니다.

# Directory Rules

## Scope
- This directory handles ...

## Do
- ...
- ...
- ...

## Don't
- ...
- ...
- ...

## Test
- Run: `...`
- If no test exists, verify by ...

조금 더 구체화하면 이런 형태입니다.

# Admin App Rules

## Scope
- This directory contains the internal admin application.

## Do
- Follow existing admin page patterns before creating new ones.
- Use existing permission guards.
- Reuse shared UI components from `packages/ui`.
- Check similar pages before introducing new table or form patterns.

## Don't
- Do not expose new user fields without checking privacy impact.
- Do not bypass existing API client wrappers.
- Do not change shared types unless all call sites are checked.
- Do not introduce new role logic without reviewing existing permission patterns.

## Test
- Run `pnpm --filter admin test`.
- Run `pnpm --filter admin typecheck`.
- If no automated test exists, verify the affected admin page manually.

이 정도면 충분합니다. 핵심은 "읽기 좋은 문서"를 만드는 것이 아니라, Claude가 실제 작업 중 따라야 할 규칙을 짧게 남기는 것입니다.

---

7. Claude에게 폴더별 CLAUDE.md를 만들게 할 때의 주의점

Claude에게 각 폴더를 분석하게 한 다음, CLAUDE.md 초안을 작성하게 하는 방식은 좋은 접근입니다.

특히 다음 조건을 걸었다면 방향이 좋습니다.

• 30줄 이하
• 규칙 중심
• Do / Don't 형식
• 테스트 방법 포함

다만 한 가지를 반드시 추가해야 합니다.

Claude가 분석한 내용을 그대로 규칙으로 확정하지 말고, 코드 근거가 있는 규칙만 남겨야 합니다.

Claude는 코드 구조를 보고 꽤 그럴듯한 규칙을 뽑아낼 수 있습니다. 하지만 그중 일부는 실제 팀 규칙이 아니라 Claude의 추정일 수 있습니다.

따라서 프롬프트를 이렇게 주는 것이 안전합니다.

이 폴더의 코드를 분석해서 이 폴더 전용 CLAUDE.md 초안을 만들어주세요.

목표:
- 30줄 이하
- 규칙 중심
- Do / Don't / Test 형식
- 추측 금지
- 코드에서 근거를 찾을 수 있는 내용만 포함

작업 순서:
1. 먼저 이 폴더의 주요 파일, 테스트, README, package/config 파일을 읽어주세요.
2. 이 폴더의 책임 범위, 반복되는 구현 패턴, 네이밍 규칙, 의존성 방향, 테스트 방법을 분석해주세요.
3. 각 규칙마다 근거가 된 파일 경로를 함께 제시해주세요.
4. 근거가 약한 내용은 "CLAUDE.md에 넣지 말 것"으로 분리해주세요.
5. 마지막에만 최종 CLAUDE.md 초안을 작성해주세요.

CLAUDE.md 작성 규칙:
- 설명문보다 명령문 위주로 작성
- 일반적인 개발 상식은 제외
- 코드만 읽으면 알 수 있는 폴더 나열은 제외
- 자주 바뀔 가능성이 높은 정보는 제외
- "항상", "절대"는 실제 근거가 있을 때만 사용
- 테스트 명령이 확실하지 않으면 추정하지 말고
  "Check nearest package config for test command"라고 작성

이 방식의 핵심은 먼저 근거를 뽑고, 그다음 규칙을 쓰게 하는 것입니다. 바로 CLAUDE.md를 쓰게 하면 문서는 예쁘게 나올 수 있습니다. 하지만 추정성 규칙이 섞일 가능성이 높습니다. 반대로 먼저 근거 파일을 제시하게 하면 사람이 리뷰하기 쉬워집니다.

---

8. 모든 폴더에 CLAUDE.md를 둘 필요는 없다

대형 코드베이스라고 해서 모든 폴더에 CLAUDE.md를 만들어야 하는 것은 아닙니다.

오히려 모든 폴더에 문서를 만들면 관리 비용이 커집니다. 오래된 규칙이 남고, 서로 충돌하는 지침이 생기고, Claude가 불필요한 정보를 읽게 됩니다.

우선순위를 나누는 것이 좋습니다(아래 분류는 글쓴이 경험을 바탕으로 한 운영 가이드입니다).

• A급: 자주 수정하고 위험도가 높은 영역 → 별도 CLAUDE.md 작성
• B급: 특정 파일 패턴에만 규칙이 필요한 영역 → .claude/rules/ 작성
• C급: 거의 수정하지 않거나 코드 탐색으로 충분한 영역 → 별도 CLAUDE.md 작성하지 않음

별도 CLAUDE.md를 둘 만한 영역은 보통 다음과 같습니다.

• 결제
• 권한
• 인증
• 개인정보
• 정산
• 배포
• 마이그레이션
• 관리자 기능
• 외부 연동
• 데이터 변경이 큰 배치 작업

이런 영역은 Claude가 잘못 수정했을 때 비용이 큽니다. 따라서 짧은 규칙 파일을 두는 것이 좋습니다.

반대로 단순 UI 컴포넌트 모음이나, 코드만 읽어도 패턴이 명확한 유틸 폴더라면 굳이 별도 CLAUDE.md를 둘 필요가 없을 수 있습니다.

---

9. .claude/rules/는 언제 쓰면 좋을까?

모든 폴더에 같은 규칙을 반복해서 쓰는 것도 좋지 않습니다.

예를 들어 API 파일에 공통으로 적용되는 규칙이 있다고 가정해보겠습니다.

• 외부 입력은 검증한다.
• 표준 에러 응답 포맷을 사용한다.
• API 응답 shape를 임의로 바꾸지 않는다.
• 변경된 동작에는 테스트를 추가한다.

이런 규칙을 각 프로젝트의 CLAUDE.md에 반복해서 쓰면 중복이 많아집니다. 이럴 때는 .claude/rules/를 사용하는 것이 적합합니다.

공식 문서에 따르면 .claude/rules/ 디렉터리에 주제별 Markdown 파일을 둘 수 있고, paths frontmatter를 사용하면 특정 파일 경로나 파일 타입에만 규칙을 적용할 수 있습니다. 경로가 지정된 규칙은 Claude가 해당 파일을 다룰 때 로드됩니다. paths가 없는 규칙은 시작 시 무조건 로드되며, .claude/CLAUDE.md와 같은 우선순위로 취급됩니다.

예를 들어 API 규칙은 이렇게 쓸 수 있습니다.

---
paths:
  - "apps/**/src/api/**/*.ts"
  - "packages/**/api/**/*.ts"
---

# API Rules
- Validate external input before business logic.
- Use the existing error response format.
- Do not introduce a new response shape without checking existing endpoints.
- Add or update tests for changed behavior.

프론트엔드 규칙은 이렇게 둘 수 있습니다.

---
paths:
  - "apps/**/src/**/*.{ts,tsx}"
  - "packages/ui/**/*.{ts,tsx}"
---

# Frontend Rules
- Prefer existing shared components before creating new primitives.
- Do not duplicate design system components.
- Keep business logic out of presentational components when possible.
- Check nearby components for state management and naming patterns.

즉 기준은 이렇습니다.

• 특정 폴더에만 적용되는 규칙 → 하위 CLAUDE.md
• 여러 폴더에 반복 적용되는 파일 패턴 규칙 → .claude/rules/
• 특정 상황에서만 필요한 긴 절차 → Skill

---

10. Skill은 언제 쓰면 좋을까?

CLAUDE.md에 절차가 길어지기 시작하면 Skill로 분리하는 것이 좋습니다.

공식 문서는 Skill을 *"반복해서 붙여넣는 플레이북, 체크리스트, 다단계 절차"*가 있을 때 만들라고 설명합니다. 또한 CLAUDE.md와 달리 Skill 본문은 사용될 때만 로드되므로, 긴 참고 자료를 매 세션 컨텍스트에 넣지 않아도 됩니다.

예를 들어 이런 내용은 CLAUDE.md보다 Skill에 가깝습니다.

• 신규 API 추가 절차
• 관리자 페이지 추가 절차
• 배포 전 체크리스트
• 장애 로그 분석 절차
• 마이그레이션 작성 절차
• PR 리뷰 절차

폴더별 CLAUDE.md에는 짧은 규칙만 두고, 긴 작업 절차는 Skill로 빼는 것이 좋습니다.

예를 들면 다음과 같습니다.

.claude/skills/add-api-endpoint/SKILL.md
.claude/skills/create-admin-page/SKILL.md
.claude/skills/debug-production-issue/SKILL.md
.claude/skills/review-migration/SKILL.md

이렇게 나누면 CLAUDE.md가 불필요하게 비대해지는 것을 막을 수 있습니다.

---

11. CLAUDE.md는 강제 장치가 아니다

중요한 점이 하나 더 있습니다.

CLAUDE.md는 Claude의 행동을 유도하는 지침이지, 기술적으로 강제되는 설정이 아닙니다.

공식 문서는 CLAUDE.md와 auto memory가 컨텍스트로 취급되며, 강제 설정이 아니라고 설명합니다. 또한 조직 차원의 보안이나 권한 제한처럼 반드시 강제되어야 하는 것은 settings나 permissions 같은 설정 계층에서 다루어야 한다고 설명합니다.

예를 들어 이런 문장은 CLAUDE.md에 둘 수 있습니다.

• Do not modify migration files unless explicitly requested.
• Do not read or edit secret files.

하지만 이것만으로 기술적으로 차단되는 것은 아닙니다.

정말로 특정 파일 접근을 막아야 한다면 .claude/settings.json의 permissions.deny 같은 설정을 사용해야 합니다. 공식 설정 문서도 민감 파일 접근을 막기 위해 permissions.deny를 사용할 수 있다고 설명합니다.

즉 역할을 구분해야 합니다.

• CLAUDE.md = 행동 지침, 작업 원칙, 프로젝트 맥락
• .claude/settings.json = 권한, 환경 변수, 도구 동작 등 실제 설정
• Hooks = 특정 시점에 반드시 실행되어야 하는 자동화
• Skills = 필요할 때 호출하는 절차와 플레이북

특히 "이 작업은 반드시 실행되어야 한다"는 경우에는 CLAUDE.md보다 hook이 더 적합할 수 있습니다. Best Practices 문서도 hooks는 특정 시점에 자동으로 실행되는 deterministic한 장치이며, CLAUDE.md 지침은 advisory 성격이라고 설명합니다.

---

12. 추천 운영 방식

큰 코드베이스에서 CLAUDE.md를 운영한다면 처음부터 완벽한 문서를 만들려고 하기보다, 점진적으로 축적하는 방식이 좋습니다.

추천 순서는 다음입니다.

1. 루트 CLAUDE.md 작성
   • 전체 레포 공통 원칙
   • 낯선 도메인 탐색 절차
   • 공통 금지사항
   • 검증 원칙
2. 주요 프로젝트 폴더만 하위 CLAUDE.md 작성
   • 자주 수정하는 앱
   • 위험도가 높은 도메인
   • 테스트 방식이 특이한 패키지
3. Claude에게 폴더 분석을 맡기되 근거를 요구
   • 주요 파일
   • 테스트
   • 설정 파일
   • 반복 패턴
   • 금지사항 후보
4. 사람이 리뷰
   • 추정성 규칙 제거
   • 오래된 정보 제거
   • 실제 팀 규칙만 남김
5. 반복 규칙은 .claude/rules/로 이동
   • API 규칙
   • 프론트엔드 규칙
   • 테스트 규칙
   • 보안 규칙
6. 긴 절차는 Skill로 이동
   • 신규 API 추가
   • 배포
   • 장애 대응
   • 마이그레이션 검토
7. 정기적으로 정리
   • 충돌하는 규칙 삭제
   • 더 이상 필요 없는 규칙 삭제
   • 길어진 파일 분리

운영 기준은 단순합니다.

이 한 줄이 없으면 Claude가 실제로 실수할 가능성이 높은가?

그렇다면 남깁니다. 아니라면 삭제합니다.

---

13. 최종 템플릿

루트 CLAUDE.md는 다음 정도로 시작할 수 있습니다.

# CLAUDE.md

This is a large multi-project repository. Keep changes narrow, verified, and localized.

## Core Principles
- Do not assume domain behavior from directory or file names alone.
- Explore before editing unfamiliar areas.
- Prefer minimal changes over broad refactors.
- Follow existing patterns in the nearest similar files.
- Before changing behavior, identify how to verify the change.

## Repository Rules
- Do not introduce new dependencies without explicit approval.
- Do not edit generated files.
- Do not modify migrations unless explicitly requested.
- Do not touch secrets, credentials, or environment files.

## Unknown Domain Protocol
When working in an unfamiliar folder:
1. Read the nearest README, CLAUDE.md, package config, and tests.
2. Identify entry points, call sites, and existing patterns.
3. Summarize your understanding before making changes.
4. Make the smallest safe change.
5. Run the narrowest relevant verification command.
6. If the change affects money, permissions, privacy, security, or user data, explain the impact before editing.

## Verification
- Prefer targeted tests over full test suites.
- If no test exists, describe the safest manual verification path.
- Report which commands were run and their results.

하위 폴더별 CLAUDE.md는 다음 정도면 충분합니다.

# Directory Rules

## Scope
- This directory handles ...

## Do
- Follow existing patterns before creating new ones.
- Check nearby tests and call sites before editing behavior.
- Keep changes local to this directory unless explicitly requested.

## Don't
- Do not change public APIs without checking all consumers.
- Do not introduce new dependencies without approval.
- Do not edit generated files.

## Test
- Run: `...`
- Typecheck: `...`
- If no automated test exists, verify by ...

---

마무리

큰 코드베이스에서 CLAUDE.md를 잘 쓰는 핵심은 많이 적는 것이 아닙니다.

오히려 반대입니다.

• 짧게 적어야 합니다.
• 구체적으로 적어야 합니다.
• 반복되는 실수를 막는 규칙만 남겨야 합니다.
• 도메인 지식이 불확실하다면 추정해서 쓰지 말고, Claude가 어떻게 탐색해야 하는지를 적어야 합니다.

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

• 루트 CLAUDE.md = 전체 레포의 공통 작업 원칙
• 하위 CLAUDE.md = 해당 폴더의 구체 규칙과 테스트 방법
• .claude/rules/ = 특정 경로나 파일 타입에 반복 적용되는 규칙
• Skills = 필요할 때만 호출하는 긴 절차와 플레이북
• settings / hooks = 실제로 강제해야 하는 권한, 차단, 자동화

결국 좋은 CLAUDE.md는 코드베이스를 자세히 설명하는 문서가 아닙니다.

좋은 CLAUDE.md는 Claude가 낯선 코드베이스에서도 함부로 추정하지 않고, 먼저 읽고, 작게 고치고, 검증하게 만드는 작업 안전장치입니다.

---

참고 문서

• Claude Code: How Claude remembers your project
• Claude Code: Best Practices
• Claude Code: Extend Claude with skills
• Claude Code: Settings
• Claude Code: Hooks guide