Claude Code의 CLAUDE.md 설계 패턴 완전 가이드
서론
Claude Code를 사용하기 시작하고 얼마 지나지 않아 두 가지 벽에 부딪히게 된다.
벽 1: "CLAUDE.md에 무엇을 써야 할지 모르겠다"
공식 문서에는 "프로젝트의 컨텍스트(Context)를 쓰는 곳"이라고 되어 있지만, 실제로 무엇을 어느 레이어(Layer)에 쓰고 어떻게 구조화해야 AI가 정말로 "똑똑하게 움직이는지"는 시행착오 없이는 알 수 없다.
벽 2: "CLAUDE.md에 규칙을 적었는데, Claude가 지키지 않는다"
사실 이것은 사양(Specification)이다. Claude Code의 공식 문서에도 명시되어 있다.
CLAUDE.md는 어드바이저리(Advisory, 약 70% 준수). Hooks(훅)는 100% 결정론적(Deterministic)으로 실행된다.
CLAUDE.md는 LLM에 대한 소프트한 지시에 불과하다. 확률적으로만 지켜진다. 반면, Hooks(훅)는 쉘 커맨드(Shell Command)로서 실행되기 때문에 100% 동작한다.
이 전제를 바탕으로, "그럼에도 불구하고 CLAUDE.md를 최대한 활용하려면 어떻게 설계해야 하는가"를 실천적인 패턴으로 해설한다. 필자는 여러 프로젝트와 수십 개의 스킬을 횡단 관리하는 Vault 환경을 운용해 온 과정에서 다음과 같은 패턴을 확립했다.
CLAUDE.md의 기본 구조: 3레이어 설계
Claude Code는 CLAUDE.md를 **3가지 스코프(Scope)**로 읽어 들인다.
~/.claude/CLAUDE.md # 글로벌 (모든 프로젝트 공통)
<프로젝트 루트>/CLAUDE.md # 프로젝트 스코프
<서브 디렉토리>/CLAUDE.md # 로컬 스코프
| 레이어 | 작성해야 할 내용 | 작성해서는 안 되는 것 |
|---|
| 글로벌 | 언어 설정 · 출력 형식 · 범용 규칙 · 보안 정책 | 프로젝트 고유의 사양 |
| ... | | |
글로벌에 작성해야 할 것(보안 규칙 · 언어 설정 등)과 프로젝트 고유하게 작성해야 할 것을 분리하는 설계가 기본이 된다.
패턴 1: 우선순위 계층을 명시하기
여러 개의 CLAUDE.md가 존재하는 경우, 어떤 규칙이 우선되는지를 파일 서두에 명시한다.
> 우선순위: 글로벌 `~/.claude/CLAUDE.md` > 이 파일 > PJ 로컬 `CLAUDE.md`
이것만으로도 Claude가 여러 CLAUDE.md를 참조할 때의 판단 정밀도가 올라간다. 특히 글로벌에 보안 규칙을 작성해 두면, 프로젝트 측에 어떻게 적혀 있더라도 보안 정책이 우선된다.
패턴 2: Map 패턴 (폴더 구조를 선언하기)
가장 효과가 높은 패턴 중 하나가 서두에 폴더 맵(Folder Map)을 두는 것이다.
## Map
| 폴더 | 내용 |
|---------|------|
| ... |
Claude는 프로젝트 전체의 파일 구조를 파악하고 있지 않다. 맵을 전달함으로써 "어디를 보면 되는지"를 단번에 이해시킬 수 있다.
중요: 03_Archive/ 는 검색 대상 제외와 같은 제외 지시를 반드시 작성한다. 이것이 없으면 Claude가 불필요한 파일을 참조하여 무의미한 토큰을 소비하고, 잘못된 답변을 생성한다.
상세한 트리는 별도 파일로 분리하면 CLAUDE.md가 비대해지는 것을 막을 수 있다.
상세 트리: → `.claude/docs/vault-structure.md`
패턴 3: 검색 전략을 명시하기
Claude는 기본적으로 Grep이나 Glob을 사용하여 모든 파일을 전수 조사하려고 한다. 이는 토큰의 낭비가 된다. 구분 규칙을 명시해 둔다.
## 검색 규칙
다음 우선순위에 따라 구분하여 사용한다. Vault 전체를 전수 조사하지 않는다. `03_Archive/` 는 제외.
1. **특정 파일명 · 정확한 키워드** → Grep/Glob (고속 · 정확 · 비용 최소)
...
포인트: "실패했을 때 어떻게 할 것인가"에 대한 폴백 체인(Fallback Chain)을 정의하는 것. 이것이 없으면 Claude가 루프(Loop)에 빠진다.
이러한 "검색 플로우차트"를 작성하면, "~에 관한 노트를 찾아줘"와 같은 모호한 지시에 대해 Claude가 적절한 도구를 선택하게 된다.
패턴 4: 이벤트 트리거 테이블 (Layer 2 기록)
## 이벤트 트리거 정의
| 이벤트 | 감지 조건 | 기록 대상 | 액션 |
|---------|-----------|-----------|-----------|
...
세션 종료를 기다리지 않고 즉시 기록하는 규칙으로 설정함으로써, 컨텍스트 압축 (compact) 후에도 지식 (knowledge)이 남게 된다. "판단이 망설여지면 기록한다"라는 철학을 Claude에게 심어주는 것이 중요하다.
패턴 5: 코드 변경 트리거 테이블
변경 사항과 참조해야 할 문서를 대응표로 작성해 두면, AI가 변경 후의 정합성 체크를 자율적으로 수행한다.
## 코드 변경 트리거 테이블
| 변경 대상 | 참조해야 할 사양 | 대응 |
|---------|--------------|------|
...
이를 통해 Claude가 "CLAUDE.md를 변경했으므로 MEMORY.md도 자동으로 업데이트한다"라는 행동을 학습한다. "스킬을 추가했는데 인덱스 업데이트를 잊었다"와 같은 사고가 거의 제로가 된다.
패턴 6: 쿼리 키워드 사전
반복해서 사용하는 조작을 단축키(shortcut)로 정의한다.
## 쿼리 키워드
| 키워드 | 동작 |
|-----------|------|
...
"조간신문"이라고 입력하는 것만으로 뉴스 브리핑이 실행되는 UX를 구현할 수 있다. Claude와의 대화를 자연어 인터페이스화하는 패턴이다. 문서로서도 기능하기 때문에 팀 단위로 사용할 때도 유효하다.
패턴 7: 철학 섹션으로 행동 지침 제공
세세한 규칙을 나열하기보다, AI의 행동 원리 (철학) 를 먼저 정의하는 것이 더 유연하게 작동한다.
## 철학
- AI의 지식을 신뢰하고, 목표와 방향성만 전달한다. 절차서는 최소한으로 유지한다.
- 컨텍스트에 따른 최적해를 AI가 자율적으로 판단하는 것을 환영한다.
...
"규칙을 추가하고 싶다면 인격(persona)으로 대체할 수 없는지 생각한다"는 점이 특히 중요하다. 규칙이 늘어나면 CLAUDE.md가 비대해지고, 준수율이 더욱 떨어진다. 철학 수준에서 방향성을 제시하고, 세세한 규칙은 최소한으로 유지하는 것이 장기 운용의 요령이다.
패턴 8: 시크릿 관리 규칙의 명문화
보안 실수는 CLAUDE.md에 명시함으로써 방지할 수 있다. Claude는 코드 생성 시 이 규칙을 참조하므로, 실수로 키(key)를 하드코딩할 리스크가 급격히 줄어든다.
## 시크릿 관리 (필수)
- 코드 내에 `os.environ.get("KEY", "실제값")`의 폴백(fallback) 값으로 API 키를 작성하는 것은 **금지**
- 폴백은 빈 문자열 `""` 또는 예외(exception)를 발생(raise)시킨다.
...
# NG: 폴백에 실제값을 작성함
api_key = os.environ.get("OPENAI_API_KEY", "sk-xxxxx")
# OK: 폴백은 빈 문자열 또는 예외
...
패턴 9: 단계적 참조 (CLAUDE.md의 비대화 방지)
CLAUDE.md에 모든 정보를 담으면 비대해져서 토큰을 낭비하게 된다. 상세 내용은 별도 파일로 분리하고, 필요할 때만 참조하게 하는 것이 철칙이다.
## 상세 문서 (필요 시 참조)
- **분석 프레임워크** → `.claude/docs/analysis-frameworks.md`
- **워크플로 설계** → `.claude/docs/workflow-orchestration.md`
...
메인 CLAUDE.md에는 "지도"를 두고, "상세"는 별도 파일에 위임한다. Claude는 필요에 따라 참조처를 읽으러 가기 때문에 불필요한 읽기가 발생하지 않는다. 이는 레이어 구조 (layer structure) 라고 부를 수 있는 설계로, CLAUDE.md의 비대화를 장기적으로 방지한다.
요약
CLAUDE.md 설계에서 효과적이었던 패턴을 정리한다.
| 패턴 | 효과 |
|---|
| 우선순위 계층 명시 | 글로벌·PJ·로컬의 역할을 분리한다 |
| ... | |
CLAUDE.md는 "쓰면 끝"이 아니라, 사용하면서 키워나가는 문서다. 준수율 70%라는 제약을 이해한 상태에서, Hooks와 조합하여 "100% 결정론적으로 동작시켜야 할 것"과 "LLM에 맡겨야 할 것"을 명확히 분리하는 것이 장기 운용의 핵심이다. 우선 본 기사의 패턴을 1~2개 정도 시도해 보길 권한다.
Discussion
