실무에서 CLAUDE.md 하나에 모든 규칙을 쌓다 보면 어느 순간 파일이 수백 줄이 됩니다. 그리고 그때쯤 Claude는 규칙을 잘 따르지 않기 시작합니다.
이유는 단순합니다!
CLAUDE.md는 세션 시작 시 전체가 컨텍스트 윈도우에 올라갑니다. 파일이 길수록 토큰을 낭비하고 준수율이 떨어집니다. 공식 문서도 파일당 200줄 이하를 권장하며, 그 이상이 되면 path-scoped rules로 분리하라고 명시합니다.
공식 문서에서 이 문제의 해법으로 제시하는 게 .claude/rules/입니다.
두 가지 메모리 시스템
CLAUDE.md와 .claude/rules/는 로드 방식 자체가 다릅니다.
CLAUDE.md는 세션이 시작될 때 항상 전체가 로드됩니다. 그래서 여기에는 어떤 파일을 작업하든 항상 알아야 하는 것만 넣어야 합니다. (ex. 빌드 명령, 폴더 구조, "항상 X를 수행한다" 같은 규칙)
.claude/rules/는 다릅니다.
paths frontmatter로 범위를 지정하면, Claude가 해당 패턴과 일치하는 파일을 Read할 때만 로드됩니다.
예를 들어, C 파일 작업할 때 Python 규칙이 올라올 필요가 없고, DB 건드릴 때만 DB 규칙이 올라오면 됩니다.
rules 로드 흐름
주의할 점은, 경로별 규칙은 도구를 사용할 때마다 트리거되는 게 아니라 파일을 Read하는 시점에 트리거됩니다.client/foo.cs를 열면 그때 c-style.md와 client.md가 로드되는 식입니다.
실무 폴더 구조
C/Python 혼합, Git 기반 프로젝트 기준으로 구성하면 이렇습니다.
project/
├── CLAUDE.md
└── .claude/
└── rules/
├── git-workflow.md ← paths 없음, 항상 로드
├── languages/
│ ├── c-style.md ← paths: "**/*.{c,h,cs}"
│ └── python-style.md ← paths: "tool/**/*.py"
└── modules/
├── client.md ← paths: "client/**/*"
├── db.md ← paths: "db/**/*"
└── bin.md ← paths: "bin/**/*"git-workflow.md처럼 paths를 지정하지 않으면 CLAUDE.md와 동일하게 세션 시작 시 항상 로드됩니다.
Git 워크플로우처럼 어떤 파일을 작업하든 항상 지켜야 하는 규칙이 여기 해당합니다.
CLAUDE.md 작성
여기에는 최소한만 넣습니다.
# 프로젝트 개요
C/Python 기반 임베디드 프로젝트
## 폴더 역할
- client/ : 클라이언트 모듈 (C, C#)
- src/ : 핵심 소스 (C)
- bin/ : 빌드 산출물 (수정 금지)
- tool/ : 내부 유틸리티 (Python)
- resources/ : 정적 리소스
- db/ : DB 테이블 정의 (수정 금지)
## 빌드 명령
- 전체 빌드 : make all
- 테스트 : make test
- 클린 : make clean
## 공통 규칙
- main 브랜치 직접 push 금지, PR을 통해 머지
- 커밋 전 make lint 실행
## 민감한 영역
- db/ 수정이 필요할 시, 담당자 확인 후 진행 (.claude/rules/modules/db.md 참고)
- bin/ 직접 수정 금지, 빌드로만 생성db 관련 경고를 CLAUDE.md에도 넣는 이유가 있습니다.
db.md는 db/ 파일을 열 때 로드되지만, CLAUDE.md의 경고는 세션 시작부터 인지합니다. 작업 계획 단계에서부터 건드리지 않도록 하는 이중 안전장치입니다.
paths 패턴 매칭
패턴이 틀리면 rules 자체가 의미 없습니다.
자주 실수하는 부분이니 주의해야할거 같습니다.
# 안 되는 패턴
paths:
- "client/" # 슬래시만으로는 매칭 안 됨
- "*.c" # 루트의 .c 파일만 매칭, 하위 폴더 안 됨
- "client/*.c" # client/ 바로 아래만, 하위 폴더 안 됨
# 올바른 패턴
paths:
- "client/**/*.c" # client/ 하위 모든 .c 파일
- "client/**/*" # client/ 하위 모든 파일확장자가 여러 개면 중괄호로 묶습니다.
paths:
- "src/**/*.{c,h}"
- "client/**/*.{c,h,cs}"
- "**/*.{json,xml}"패턴 설계 전에 실제 확장자 분포를 먼저 확인하는 게 좋습니다.
find . -type f | sed 's/.*\.//' | sort | uniq -c | sort -rndb.md 작성 예시
---
paths:
- "db/**/*"
- "**/*.sql"
---
# DB 규칙
## 절대 금지
- 테이블 정의 파일 직접 수정 금지
- 컬럼 삭제, 타입 변경 금지 (레거시 의존성)
- DROP, TRUNCATE 구문 사용 금지
## 수정이 필요한 경우
- 반드시 담당자에게 먼저 확인
- Claude는 수정안 제안만 하고, 실제 적용은 하지 않음
- 새 컬럼은 반드시 nullable로 추가정리
결국 CLAUDE.md는 "무엇을 조심해야 하는지", .claude/rules/는 "어떻게 다뤄야 하는지"로 역할을 나누는 구조입니다.
이렇게 나누면 얻는 것들이 있습니다.
관계없는 규칙은 컨텍스트에 올라오지 않으니 속도가 붙고,
GitHub 저장소에 커밋해두면 팀 전체가 동일한 규칙을 clone 받습니다. (중앙 관리하기 좋겠죠?)
신규 팀원이 .claude/rules/만 읽어도 프로젝트 규칙 대부분을 파악할 수 있고, Claude가 실수할 때마다 해당 rules 파일에 한 줄 추가하면 팀의 노하우가 코드베이스에 쌓입니다.
결론적으로, AI가 무엇을 알고, 무엇을 모르고, 무엇을 건드리면 안 되는지를 코드베이스 수준에서 버전관리하는 구조입니다.
실전 프로젝트 적용기
Unity 데스크톱 게임 사이드 프로젝트에 Claude Code를 쓰면서, 기존에 CLAUDE.md 하나에 모든 규칙을 넣던 방식을 .claude/rules/로 분리하는 실험을 했습니다.
1. 적용 전 — 한 파일에 모든 규칙이 쌓여있던 상태
CLAUDE.md는 세션 시작 시 항상 전체가 컨텍스트 윈도우에 로드됩니다. 그런데 어느 순간 213줄까지 늘어 있었습니다. 공식 문서 권장치인 200줄을 이미 넘긴 상태였습니다.
안에는 이런 것들이 섞여 있었습니다.
- §1~§3: 프로젝트 개요·폴더 구조·진입점 — 어떤 작업이든 알아야 하는 것
- §4~§5: CLAUDE.md 운영 규칙 — 메타 문서
- §6.1: 파일/폴더 명명 — 문서 작업할 때만 필요
- §6.2 Git 워크플로우, §7 AI 공통 규칙 — 합의 필요로 비어있는 placeholder
- §8.1~§8.4 Behavioral Guidelines — LLM 코딩 공통 가드레일
문제는 .cs 파일을 만질 때도, 문서를 쓸 때도, 씬을 건드릴 때도 위 §1~§8 전체가 매번 컨텍스트에 들어간다는 점입니다.
작업 맥락과 무관한 규칙이 항상 함께 떠 있고, 새 영역(셰이더·사운드 등)을 추가할수록 모든 작업의 비용이 같이 늘어날거 같았습니다.
2. 실제로 쪼갠 구조
.claude/rules/의 핵심은 paths frontmatter로 매칭되는 파일을 Read할 때만 해당 규칙 파일이 시스템 프롬프트에 끼어든다는 점입니다.
이걸 활용해 다음과 같이 나눴습니다.
.claude/rules/
├── git-workflow.md ← paths 없음, 항상 로드
├── behavioral-guidelines.md ← paths 없음, 항상 로드
├── unity/
│ ├── csharp.md ← C# 작업 시에만 로드
│ ├── scenes.md ← 씬 파일 작업 시에만 로드
│ ├── project-settings.md ← ProjectSettings 건드릴 때만 로드
│ └── characters.md ← 캐릭터 에셋 작업 시에만 로드
└── docs-conventions.md ← 문서 작업 시에만 로드써보면서 이 구조가 두 가지 다른 목적으로 작동한다는 걸 알게 됐습니다.
장점 1. CLAUDE.md 슬림화 — 정리 목적
git-workflow.md, behavioral-guidelines.md처럼 paths가 없는 파일들입니다.
로드 시점은 CLAUDE.md와 완전히 동일해서 컨텍스트 절약 효과는 없습니다.
대신 규칙 종류별로 파일이 분리되어 있어서 수정할 때 CLAUDE.md 전체를 뒤지지 않고 파일명으로 바로 찾을 수 있다는 게 장점입니다.
(팀이 합의할 때마다 해당 파일만 열어서 한 줄 추가하면 끝입니다.)
빈 §6.2 / §7 placeholder를 CLAUDE.md 본문 한가운데서 들어내고 git-workflow.md placeholder 파일로 옮긴 것도 같은 목적입니다. (본문이 깔끔해집니다)
장점 2. 컨텍스트 절약 — paths 지정 파일만 해당
csharp.md, scenes.md처럼 paths를 지정한 파일들입니다.
해당 경로의 파일을 Read하는 순간 시스템 프롬프트에 삽입됩니다.
.md 문서 작업 중에는 C# 규칙이 올라오지 않고, .cs 작업 중에는 씬 규칙이 올라오지 않습니다. 매 요청마다 입력 토큰에 포함되는 내용이 작업 맥락에 맞게 줄어드는 구조입니다.
3. 토큰을 재봤습니다
추정은 다음 방식으로 했습니다. Claude 공식 tokenizer는 비공개라 chars / 2.5 추정을 썼습니다(한글+영문+코드 혼합 텍스트 기준, 오차 ±15%).
(정확한 값은 anthropic SDK의 count_tokens API가 필요합니다)
# 원본 CLAUDE.md (슬림화 전 git HEAD)
git show HEAD:CLAUDE.md > /tmp/original.md
python3 -c "print(round(len(open('/tmp/original.md').read())/2.5))"
# → 2513비교 기준 — 무엇과 무엇을 비교해야 공정한가
원본 CLAUDE.md(213줄, ~2,513 tokens)에는 아직 Unity-specific 규칙이 없었습니다. 어차피 Unity 규칙은 어딘가에 적어야 했고, 두 가지 선택지가 있었습니다.
- 선택 A:
CLAUDE.md에 Unity 규칙들을 그대로 이어 적기 (monolithic) - 선택 B:
.claude/rules/로 분리 (지금 한 것)
공정한 비교는 "같은 규칙들을 monolithic으로 가져갔다면 어땠을지" 대 "rules로 나눈 결과"입니다.
만약 .claude/rules/를 안 쓰고 모든 규칙을 CLAUDE.md 본문에 통합했다면:
- 원본 213줄 (~2,513 tokens)
- + Git 워크플로우 (~440 tokens)
- + 문서 컨벤션 추가분 (~230 tokens)
- + Unity C# 규칙 (~422 tokens)
- + 씬 규칙 (~249 tokens)
- + ProjectSettings 규칙 (~352 tokens)
- + Characters 규칙 (~481 tokens)
- = 약 4,676 tokens (어떤 작업이든 매 턴 통째 로드)
반면 .claude/rules/ 시나리오는,
- 항상 로드: 슬림 CLAUDE.md +
behavioral-guidelines.md+git-workflow.md= 약 2,497 tokens - + 매칭되는 1개 룰 (작업에 따라 ~250–481 tokens)
시나리오별 비교
| 작업 종류 | monolithic | .claude/rules/ | 절약 |
|---|---|---|---|
.cs 파일 작업 |
4,676 | 2,919 | −1,757 (−38%) |
.unity 씬 작업 |
4,676 | 2,746 | −1,930 (−41%) |
ProjectSettings/ 작업 |
4,676 | 2,849 | −1,827 (−39%) |
Characters/ 자산 작업 |
4,676 | 2,978 | −1,698 (−36%) |
문서(.md) 작업 |
4,676 | 2,888 | −1,788 (−38%) |
작업당 평균 약 1,800 tokens, 38.5% 절약입니다.
게다가 룰이 늘어날수록 격차는 더 벌어집니다. UI / Sound / Shader 등 영역이 추가되면 monolithic은 항상 그만큼 더 부풀고, .claude/rules/는 그 작업을 할 때만 한 줄 더해집니다.
다만 지금 프로젝트 규모에서는 절대 토큰 수가 그리 크진 않습니다.
rules 파일이 수십 개, 각 파일이 수백 줄씩 쌓일 때 차이가 더 체감될 것입니다.
(지금은 "구조적으로 절약되는 형태로 시작했다"는 정도의 의미로...)
4. 주의할 점
paths 패턴은 "필터"가 아니라 "트리거"
paths 패턴 매칭은 파일 내용을 필터링하는 게 아닙니다!
특정 경로의 파일을 Read하는 순간 해당 rules 파일 전체가 컨텍스트에 올라오는 트리거이고, frontmatter 포함 전체가 다 로드됩니다.
---
paths:
- "**/*.cs"
- "Project_Cozy/Assets/Scripts/Platform/**/*.cs"
---자주 틀리는 패턴을 정리해두면,
"src/"처럼 슬래시만 쓰거나"*.cs"처럼 단순 글로브는 하위 폴더를 잡지 못합니다.- 재귀 매칭은
"src/**/*.cs"처럼**을 써야 합니다.
Claude가 파일을 알아서 읽으러 가지 않습니다
.claude/rules/와 CLAUDE.md 외에 일반 파일은 Claude가 명시적으로 열지 않으면 내용을 모릅니다.git-workflow.md에 "자세한 내용은 Docs/Development/GitWorkflow.md 참고"라고 써도 Claude가 자동으로 읽으러 가지 않습니다.
CLAUDE.md 파일 안에서는 @경로 문법으로 외부 파일을 임포트할 수 있습니다. 예를 들어 @docs/git-instructions.md처럼 쓰면 세션 시작 시 해당 파일이 자동으로 로드됩니다.이 기능을 활용하면 rules 파일 개수를 늘리지 않고도 관련 문서를
CLAUDE.md에서 참조할 수 있습니다.rules 파일 자체에 필요한 규칙은 직접 적거나 @import를 활용하는걸로...!
.claude/는 보호 영역일 수 있습니다
Cowork에서 .claude/ 디렉토리에 직접 쓰기가 막힙니다. 저는 일반 폴더(_claude_rules_stage/)에 만들고 PowerShell Copy-Item으로 옮겼습니다.
로드된 파일 확인은 /memory 커맨드로
/memory를 실행하면 현재 세션에 로드된 모든 CLAUDE.md, rules 파일 목록을 확인할 수 있습니다. path-scoped rules가 기대대로 트리거되는지 디버깅할 때 유용합니다.
마무리
.claude/rules/는 토큰을 자동으로 줄여주는 마법이 아닙니다.
나누는 결정은 사람이 해야 하고, 잘못 나누면 보강하다가 오히려 토큰이 늘 수도 있습니다.
특히 지금처럼 프로젝트 규모가 작을 땐 보강 한 줄의 비중이 커서 위험이 더 큽니다. (저도 처음 나눴을 땐 오히려 늘 뻔했었던...)
결국 .claude/rules/의 진짜 가치는 paths를 가진 파일들에 있고, paths 없는 파일들은 CLAUDE.md가 길어지는 걸 막기 위한 분리 그 이상도 이하도 아닙니다.
참고 문서
'AI 사용기' 카테고리의 다른 글
| [Claude Desktop] Claude MCP로 Windows 입력 제어하기 - 칠전팔기와 실험 후기 (0) | 2026.05.30 |
|---|