Claude Code의 CLAUDE.md 비대화 문제를 해결하는 「상황별 목차 방식」과 3층 구조

서론

Claude Code를 계속 사용하다 보면, CLAUDE.md가 점점 비대해집니다.

「Netlify 조작 전 확인」, 「버그 수정 절차」, 「Flutter 빌드 규칙」—— 어느샌가 200행을 넘어서게 되고, Claude가 어떤 규칙을 보고 있는지 불확실해집니다.

이 기사에서는 CLAUDE.md를 상황별 목차로 취급하는 「상황별 목차 방식」과, 이를 신뢰할 수 있는 메커니즘으로 만들기 위한 3층 구조를 소개합니다.

제가 조사한 범위 내에서는 Claude Code의 운용 방법으로서 체계적으로 정리된 사례는 찾을 수 없었습니다.

흔한 해결책과 그 한계

CLAUDE.md를 분할·정리하는 메커니즘으로서, Claude Code에는 .claude/rules/ 디렉토리가 있습니다.

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

파일 상단에 이 프론트매터 (Frontmatter)를 작성하면, 대상 경로의 파일을 다룰 때만 자동으로 로드됩니다. 이는 강력합니다.

하지만 경로(Path)만으로는 구분할 수 없는 상황이 있습니다.

• 「Netlify에 배포할 때」
• 「버그를 조사·수정할 때」
• 「자율 주행」(Claude에게 태스크를 위임하여 지속 실행시키는 운용) 모드에 들어갈 때

이것들은 「지금 어떤 파일을 만지고 있는가」가 아니라, 「지금 무엇을 하려고 하는가」에 따라 결정됩니다. 경로 기반의 자동 로드로는 대응할 수 없습니다.

상황별 목차 방식

CLAUDE.md 자체를 상황에 따른 읽기 대상을 나타내는 목차로 만드는 방법입니다.

## 상황별 규칙 파일
규칙 디렉토리: `~/.claude/rules/`
| 상황 | 읽을 파일 |
...

Claude가 이 표를 참조하여 필요한 규칙 파일을 읽으러 가기를 기대합니다.

이를 통해:

• CLAUDE.md 본체는 목차와 상시 규칙으로만 압축할 수 있음
• 각 규칙 파일은 단일 관심사에 집중할 수 있음
• 추가·변경이 목차 한 줄로 끝남

문제점: Claude가 읽을지 보장되지 않음

솔직하게 말씀드리겠습니다. 이 방식에는 약점이 있습니다.

Claude가 규칙 파일을 참조할지 여부는 매번 보장되지 않습니다. 「알고 있음에도 사용하지 않았다」는 실패는 CLAUDE.md에 직접 작성한 규칙에서도 발생합니다. 별도 파일에 대한 참조는 더욱 어긋나기 쉽습니다.

이 문제는 후술할 3층 구조로도 완전히 해결할 수는 없습니다. 특히 층 3은 여전히 확률적입니다. 그럼에도 「치명적인 실패를 방지한다」는 목적에는 충분히 사용할 수 있다는 것이 이 기사의 주장입니다.

3층 구조로 신뢰성을 보완

「Claude의 자발적 판단에 의존하는 부분을 최소화한다」는 방침으로, 세 개의 층을 겹칩니다.

층 1: 자동 로드 (가장 신뢰할 수 있음)

경로로 구분 가능한 규칙은 .claude/rules/의 자동 로드에 맡깁니다. Claude가 「읽어야 할지」를 판단할 여지가 적어집니다.

---
paths:
- "**/*.dart"
...

대상 예시: flutter_android.md / code_quality.md
(bug_fix.md는 버그 수정 중인지 신규 구현 중인지 경로만으로는 구분할 수 없는 경우가 많아, 프로젝트 구성에 따라서는 층 3이 더 적합할 수 있음)

층 2: 직접 작성된 파수꾼 (어기면 치명적인 규칙)

「git reset --hard는 확인 필수」, 「운영 환경으로의 배포는 매번 확인한다」—— 이것들은 놓치면 돌이킬 수 없습니다. CLAUDE.md의 눈에 띄는 위치에 한 줄로 명령을 직접 작성합니다.

## 조작 전 강제 확인
- **Netlify・외부 API를 조작하기 전**: `external_ops.md`를 읽고 나서 동작할 것
- **파일 삭제・git reset・배포 전**: `destructive_ops.md`를 읽고 나서 동작할 것

목차의 「읽을 곳」이 아니라, 「읽어라」라는 명령을 상시 보이는 곳에 두는 것이 포인트입니다.

대상: external_ops.md / destructive_ops.md

층 3: 의도 기반 목차 (나머지)

경로로도 끊기지 않고, 직접 작성할 만큼 치명적이지도 않은 규칙이 남습니다.

• 「앱 아이콘이 확정되었을 때」
• 「자율 주행 모드에 들어갈 때」
• 「신규 프로젝트를 시작할 때」

이것들은 컨텍스트에 따른 참조로만 표현할 수 있습니다. 이 층이 「상황별 목차 방식」이 담당하는 고유한 영역입니다.

하지만 이 층은 여전히 확률적입니다. Claude가 읽지 않고 지나칠 가능성이 제로(0)는 아닙니다.

그럼에도 불구하고 이 방식이 성립하는 이유는, 이 층이 "어긋나더라도 치명적이지 않은 규칙"만을 담당하도록 설계되었기 때문입니다. 치명적인 조작(배포·삭제)은 2층이, 자주 사용하는 코드 규칙은 1층이 수호합니다. 3층이 어긋나더라도 허용 가능한 범위 내에 머뭅니다.

대상: app_icon.md

/ autonomous.md

/ reference.md

완성된 형태의 CLAUDE.md

3개 층을 조합하면 CLAUDE.md는 다음과 같습니다.

# 글로벌 규칙 (Global Rules)
## 조작 전 강제 확인 (직접 작성된 파수꾼)
- **Netlify·외부 API를 조작하기 전**: `~/.claude/rules/external_ops.md`를 읽은 후 동작
...

200행을 넘었던 것이 100행 이하로 줄어들었습니다.

3층의 용도 구분 요약

새로운 규칙을 추가할 때, 다음 순서로 판단합니다.

"접근하는 파일의 경로(path)로 구분할 수 있는가?"
→ YES: paths: 프론트매터 (Frontmatter) (자동 로드)
→ NO: "위반되었을 때 돌이킬 수 없는가?"
...

요약

• CLAUDE.md의 비대화 문제에는 .claude/rules/의 경로 기반 방식이 유효하지만, 의도 기반의 트리거에는 대응할 수 없다 - CLAUDE.md 자체를 "상황별 목차"로 만듦으로써 의도 기반의 규칙 참조가 가능해진다
• 단, 3층은 확률적이며 Claude가 참조하지 않는 경우가 남을 수 있다
• 상황별 목차 방식을 단독으로 사용하는 것이 아니라, 자동 로드·직접 작성된 파수꾼·상황별 목차의 3층 구조로 조합함으로써 치명적인 실패를 방지하면서도 유연성을 확보할 수 있다

이 구성은 .claude/rules/를 부정하는 것이 아니라, 그것이 대응할 수 없는 빈틈을 메우는 것입니다.

저는 현재 다음과 같은 구성으로 운용하고 있습니다.

• 경로로 구분 가능한 것 → .claude/rules/에 paths: 프론트매터로 배치
• 고비용 조작이나 파괴적 조작 규칙 → CLAUDE.md에 직접 작성
• 그 외 → 상황별 목차

Discussion