CLAUDE.md · AGENTS.md 설계 패턴 — 200 라인 원칙과 모듈화
CLAUDE.md와 AGENTS.md를 설계하는 실용 원칙. 200 라인 권장 근거, 필수 포함 항목, 피해야 할 안티패턴, @import를 활용한 모듈화, 검증 루프까지 — 본 저장소의 실제 사용 예를 발췌해 설명한다.
들어가며
Claude Code를 팀이나 개인 프로젝트에서 운용하다 보면 어느 시점에 이 질문을 마주친다.
“CLAUDE.md가 400줄인데 왜 에이전트가 자꾸 같은 실수를 할까?”
지시가 많다고 효과가 높아지지 않는다. CLAUDE.md와 AGENTS.md는 AI의 행동을 결정론적으로 조형하는 구조 문서다. 이 글은 그 두 파일을 어떻게 설계할 것인가에 초점을 맞춘다.
이 글에서 다루는 것:
- CLAUDE.md와 AGENTS.md의 역할 분리 기준
- Anthropic이 권장하는 200 라인 원칙의 근거
- 반드시 포함해야 하는 항목과 그 이유
- 자주 보이는 안티패턴과 개선 방법
@임포트 기반 모듈화 패턴- 지시가 실제로 작동하는지 검증하는 루프
- 본 저장소의 실제 CLAUDE.md 발췌 예시
관련 배경 지식은 이 블로그의 다른 포스트에서 보강할 수 있다:
- Claude Code Hooks 완전 가이드 — 라이프사이클 이벤트 자동화
- Claude Code 서브에이전트 설계 패턴 — 에이전트 분리 기준
- Claude Code Plan Mode 실전 활용 — 승인 게이트 설계
- Claude Code 스킬 작성 완전 가이드 — 재사용 가능한 워크플로우
- Claude Code MCP 서버 구축 완전 가이드 — 외부 도구 통합
1. CLAUDE.md vs AGENTS.md — 역할 분리
두 파일은 자주 혼용되지만 적용 범위와 목적이 다르다.
CLAUDE.md — 세션 전역 컨텍스트
CLAUDE.md는 Claude Code 세션이 시작될 때 자동으로 로드된다. 프로젝트 루트에 놓으면 해당 저장소 전체에 적용되고, ~/.claude/CLAUDE.md에 놓으면 모든 프로젝트에 전역으로 적용된다.
로드 우선순위:
1
2
3
~/.claude/CLAUDE.md ← 전역 (모든 세션)
└── {project}/CLAUDE.md ← 프로젝트 루트 (해당 저장소)
└── {subdir}/CLAUDE.md ← 서브디렉터리 (탐색 시)
CLAUDE.md의 역할은 세션 초기화 컨텍스트 주입이다. “이 프로젝트에서 항상 알아야 할 것”을 담는다.
AGENTS.md — 에이전트별 지역 컨텍스트
AGENTS.md는 특정 디렉터리에서 에이전트가 동작할 때 로드된다. 서브에이전트가 src/api/ 폴더를 탐색하면 그 경로의 AGENTS.md가 컨텍스트에 추가된다.
핵심 차이:
| 항목 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 로드 시점 | 세션 시작 | 에이전트가 해당 디렉터리 탐색 시 |
| 적용 범위 | 전역 또는 프로젝트 전체 | 특정 디렉터리 및 하위 |
| 주요 용도 | 프로젝트 개요, 빌드 명령, 전역 규칙 | 모듈별 아키텍처, 지역 규칙, 금지 사항 |
| 파일 크기 권장 | 짧고 간결 (커뮤니티 운영 기준 200줄 안팎) | 더 짧게 (50~100줄 안팎) |
CLAUDE.md를 “온보딩 문서”로, AGENTS.md를 “팀별 운영 매뉴얼”로 비유하면 구분이 쉽다.
2. “짧게 유지하라” — 공식 원칙과 커뮤니티의 200줄 기준
Anthropic의 Best practices for Claude Code 문서는 CLAUDE.md에 대해 “keep it short and human-readable”, “keep it concise” 를 권장하며, 각 줄에 대해 “Would removing this cause Claude to make mistakes?” 라는 질문을 던져 가지치기하라고 안내한다.1 공식 문서가 명시한 절대 수치는 없지만, 실무 커뮤니티에서는 이 원칙을 약 200줄 안팎의 운영 기준으로 자리 잡혀 있다 — 이 글에서도 그 200줄 기준을 작업 잣대로 사용한다.
왜 짧게 유지해야 하는가
CLAUDE.md는 모든 요청마다 컨텍스트에 포함된다. 500줄짜리 CLAUDE.md는 간단한 질문 하나에도 그 500줄이 통째로 주입된다. 이는 두 가지 문제를 만든다.
문제 1 — 신호 대 잡음비 저하: 길수록 중요한 지시가 덜 중요한 내용 사이에 묻힌다. 에이전트는 전체를 읽지만, 중요도를 균등하게 가중한다.
문제 2 — 컨텍스트 윈도우 낭비: 지시가 길어질수록 실제 작업에 쓸 수 있는 공간이 줄어든다. 특히 장기 세션에서 압축(compaction) 임계값에 더 빨리 도달한다.
graph LR
A["CLAUDE.md\n500줄"] -->|매 요청마다 주입| B["컨텍스트 윈도우"]
C["CLAUDE.md\n150줄"] -->|매 요청마다 주입| D["컨텍스트 윈도우"]
B --> E["작업 공간: 협소"]
D --> F["작업 공간: 충분"]
style E fill:#ef4444,color:#fff
style F fill:#10b981,color:#fff
200 라인을 초과할 때
이미 200 라인을 넘었다면 두 가지 전략을 택할 수 있다.
삭제 우선: “Claude가 이미 알고 있는 것”을 제거한다.
console.log 대신 logger 사용처럼 Claude가 기본적으로 잘 따르는 지시는 빠져도 된다.모듈화: 범용 규칙은 루트 CLAUDE.md에 두고, 모듈별 세부 규칙은 각 디렉터리의 AGENTS.md로 분리한다. 섹션 5에서 자세히 다룬다.
3. 필수 포함 항목
CLAUDE.md가 없으면 에이전트가 코드베이스를 탐색하며 스스로 추론한다. 추론은 비용이 들고 오류가 생긴다. 다음 항목들은 명시적으로 제공해야 추론 비용을 줄일 수 있다.
3-1. 프로젝트 개요 (3~5줄)
1
2
3
4
5
## 프로젝트 개요
- 언어/프레임워크: Ruby on Rails 7.1, PostgreSQL
- 목적: 사내 청구 관리 시스템 (외부 공개 없음)
- 주요 진입점: `app/controllers/`, `app/models/`
- 빌드 도구: Bundler, Foreman
에이전트는 이 5줄만으로 파일을 탐색하는 방향을 잡는다. 없으면 README.md를 읽거나 디렉터리 구조를 추론하는 데 토큰을 쓴다.
3-2. 빌드 · 테스트 · 실행 명령
1
2
3
4
5
## 빌드 및 실행
- 설치: `bundle install`
- 개발 서버: `foreman start -f Procfile.dev`
- 테스트: `bundle exec rspec` (전체) / `bundle exec rspec spec/models/` (단위)
- 린트: `bundle exec rubocop`
명령어는 복사-붙여넣기 가능한 형태로 작성한다. 에이전트가 실행해야 할 때 추론 없이 바로 쓸 수 있어야 한다.
3-3. 변경 범위 제한 규칙
무엇을 건드리면 안 되는지를 명확히 한다. “이 파일들은 gem이 제공하므로 수정 금지”처럼 에이전트가 모를 수 있는 제약을 담는다.
1
2
3
## 수정 금지 파일
- `_includes/`, `_layouts/` — jekyll-theme-chirpy gem이 제공, 재정의 시 동일 경로 신규 파일 사용
- `.github/workflows/pages-deploy.yml` — 유일한 배포 워크플로우, 복제 금지
3-4. 코드 컨벤션 (핵심만)
프로젝트 전반의 코드 스타일 중 도구가 강제하지 않는 것만 적는다. Rubocop이 강제하는 들여쓰기를 CLAUDE.md에 쓸 필요는 없다.
1
2
3
4
## 코드 컨벤션
- `any` 타입 사용 금지 — `unknown` + 타입 가드로 좁힐 것
- ESM import에 반드시 `.js` 확장자 포함
- `console.log` 대신 `getLogger()` 사용
3-5. 알려진 함정과 이전 실패 이력
“이 설정을 바꾸면 배포가 깨진다”처럼 git history나 코드에서 유추하기 어려운 맥락을 담는다.
1
2
3
## 알려진 함정
- `_config.yml`의 `future: true` 제거 금지 — 미래 날짜 포스트가 빌드에서 제외됨
- `pages-deploy.yml` 외 워크플로우 추가 금지 — 이전에 중복 워크플로우로 배포 충돌 발생
이 항목이 없으면 에이전트는 “합리적으로 보이는” 변경을 시도하다가 알려진 문제를 재발시킨다.
4. 안티패턴
안티패턴 1 — 소설 쓰기
1
2
3
4
5
6
7
8
9
10
11
# 나쁜 예
## 컨벤션
이 프로젝트는 TypeScript를 사용하며, 타입 안전성을 최우선으로 합니다.
모든 변수는 명시적으로 타입을 지정해야 하며, any 타입은 코드 품질 저하를
유발하므로 절대 사용하지 않아야 합니다. 특히 외부 API 응답을 처리할 때는
더욱 주의가 필요합니다...
# 좋은 예
## 컨벤션
- `any` 금지 — `unknown` + 타입 가드 사용
- 외부 API 응답: `z.parse()` (Zod 스키마 강제)
CLAUDE.md는 산문이 아니라 참조 문서다. 에이전트는 글을 읽는 것이 아니라 지시를 파싱한다.
안티패턴 2 — Claude가 이미 아는 것 반복
1
2
3
4
# 불필요한 내용
- 함수는 단일 책임 원칙을 따를 것
- 변수명은 의미 있게 지을 것
- 매직 넘버는 상수로 추출할 것
이런 지시들은 Claude가 훈련을 통해 이미 따르는 기본 원칙이다. CLAUDE.md에 적어도 행동이 바뀌지 않고, 라인만 소모된다.
안티패턴 3 — 루트 CLAUDE.md에 모든 것 몰아넣기
1
2
3
4
5
6
7
8
9
# 나쁜 예: 루트 CLAUDE.md가 모든 모듈 규칙을 담음
## API 모듈 규칙
...50줄...
## 데이터베이스 마이그레이션 규칙
...40줄...
## 프론트엔드 컴포넌트 규칙
...60줄...
모듈별 규칙은 해당 디렉터리의 AGENTS.md로 분리한다. 에이전트가 src/api/를 탐색할 때만 API 규칙이 로드되면 충분하다.
안티패턴 4 — 검증 없는 지시
1
2
# 검증 안 된 지시의 문제
- "항상 에러를 명시적으로 처리할 것" (← 기존 코드의 70%가 에러를 무시함)
지시와 실제 코드베이스가 충돌하면 에이전트는 혼란에 빠진다. 지시를 추가하기 전에 기존 코드와 일치하는지 확인해야 한다. 섹션 6에서 검증 루프를 다룬다.
안티패턴 5 — 모호한 금지
1
2
3
4
5
6
# 나쁜 예
- 민감한 파일을 수정하지 말 것
# 좋은 예
- `.env`, `config/credentials.yml.enc`, `db/schema.rb` 직접 수정 금지
수정 필요 시 먼저 사용자에게 확인 요청
“민감한”이 무엇인지 에이전트는 판단할 수 없다. 금지 대상은 구체적인 경로나 패턴으로 명시한다.
5. 모듈화 패턴
CLAUDE.md가 200 라인을 초과하거나, 모듈별로 다른 규칙이 필요할 때 모듈화를 적용한다.
@ 임포트 문법
Claude Code는 CLAUDE.md 내에서 다른 파일을 참조하는 @ 문법을 지원한다.2
1
2
3
4
5
6
7
# 루트 CLAUDE.md
## 프로젝트 개요
- ...핵심 항목만...
## 참조
@docs/conventions.md
@.claude/security-rules.md
이 방식을 쓰면 루트 CLAUDE.md는 짧게 유지하면서, 세부 규칙은 별도 파일로 관리할 수 있다.
디렉터리별 AGENTS.md 구조
1
2
3
4
5
6
7
8
9
10
11
project/
├── CLAUDE.md ← 전체 프로젝트 개요, 빌드 명령, 전역 규칙
├── src/
│ ├── api/
│ │ └── AGENTS.md ← API 레이어 규칙, 인증 패턴, 에러 처리
│ ├── db/
│ │ └── AGENTS.md ← 마이그레이션 규칙, 스키마 변경 절차
│ └── frontend/
│ └── AGENTS.md ← 컴포넌트 구조, 상태 관리 규칙
└── tests/
└── AGENTS.md ← 테스트 작성 기준, 픽스처 사용 방법
graph TD
Root["CLAUDE.md\n프로젝트 개요 · 빌드 명령\n전역 금지 사항 (50줄)"]
Root --> API["src/api/AGENTS.md\nAPI 규칙 · 인증 패턴 (60줄)"]
Root --> DB["src/db/AGENTS.md\n마이그레이션 절차 (40줄)"]
Root --> FE["src/frontend/AGENTS.md\n컴포넌트 규칙 (70줄)"]
Root --> Test["tests/AGENTS.md\n테스트 기준 (50줄)"]
style Root fill:#3b82f6,color:#fff
style API fill:#10b981,color:#fff
style DB fill:#10b981,color:#fff
style FE fill:#10b981,color:#fff
style Test fill:#10b981,color:#fff
에이전트가 src/db/를 탐색할 때만 마이그레이션 규칙이 로드된다. 전체 규칙이 항상 주입되는 방식보다 노이즈가 줄어든다.
전역 vs 지역 기준
루트 CLAUDE.md에 놓아야 하는 것:
- 프로젝트 개요 및 기술 스택
- 빌드·테스트·실행 명령
- 저장소 전체에 적용되는 금지 사항
- 배포 관련 주의 사항
각 디렉터리 AGENTS.md에 놓아야 하는 것:
- 해당 모듈의 아키텍처 설명
- 모듈별 코딩 컨벤션
- 이 디렉터리에서만 적용되는 금지 사항
- 지역적 함정 및 알려진 이슈
6. 검증 루프
CLAUDE.md를 작성한 뒤 “이게 실제로 작동하는가”를 검증하는 절차가 필요하다.
기본 검증: 새 세션에서 직접 확인
가장 단순하지만 확실한 방법이다.
1
2
3
4
5
6
7
# 새 Claude Code 세션 시작
claude
# 지시 준수 여부를 직접 물어보기
> CLAUDE.md에 어떤 규칙들이 있어? 핵심 3가지를 말해줘.
> 이 프로젝트의 테스트 명령은 무엇이야?
> `any` 타입을 써도 되는 상황이 있어?
에이전트가 CLAUDE.md의 내용을 정확히 반영해서 답하면 지시가 제대로 로드된 것이다.
실전 검증: 안티패턴 유발 작업 요청
지시가 엣지 케이스에서도 작동하는지는 직접 유발해봐야 안다.
1
2
3
4
5
6
7
# 금지된 파일 수정 시도
> `_config.yml`의 `future` 설정을 `false`로 바꿔줘.
# 기대: 에이전트가 CLAUDE.md의 금지 사항을 언급하며 거부 또는 확인 요청
# 금지된 패턴 사용 시도
> 이 함수의 반환 타입을 `any`로 지정해줘.
# 기대: 에이전트가 `unknown` + 타입 가드를 제안
지속적 검증: 훅 기반 자동 리마인더
Hooks를 활용하면 지시 준수 여부를 자동으로 점검할 수 있다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "scripts/check-conventions.sh $CLAUDE_FILE_PATHS"
}
]
}
]
}
}
파일이 수정될 때마다 컨벤션 검사 스크립트를 실행하는 방식이다. 지시를 문서로 두는 것보다 도구로 강제하는 편이 더 안정적이다.
CLAUDE.md 자체 검토 체크리스트
지시를 추가하기 전 다음을 확인한다:
- 이 지시가 없으면 에이전트가 실제로 틀리는가? (Claude가 이미 잘 따르는 것이면 불필요)
- 기존 코드베이스와 이 지시가 일치하는가? (불일치 시 에이전트가 혼란)
- 구체적인 경로나 명령어로 표현되었는가? (모호한 표현은 해석이 갈림)
- 이 지시가 어느 모듈에만 해당하는가? (해당하면 루트가 아니라 AGENTS.md로)
- 이 지시를 제거했을 때 빠지는 것이 있는가? (없다면 제거 후보)
7. 본 저장소 실 사용 예시
이 블로그 저장소(sirdeath.github.io)의 CLAUDE.md를 발췌해 실제 적용 사례를 살펴본다.
예시 1 — Front Matter 필수 규칙
1
2
3
4
5
6
### Front Matter 주의사항
- **`date` 필수 형식**: `YYYY-MM-DD HH:MM:SS +0900` — 타임존 오프셋 `+0900` 반드시 포함
- **`author`**: 항상 `sirdeath`
- **`tags`**: 숫자만으로 된 태그는 반드시 따옴표로 감싸기 (예: `"2026"`)
— YAML이 Integer로 파싱하여 Liquid slugify 에러 발생
- 한국어 날짜(`오후 10:40` 등) 절대 사용 금지
이 규칙의 특징:
- 이유가 함께 있다: “YAML이 Integer로 파싱하여 Liquid slugify 에러 발생”이라는 맥락이 있어야 에이전트가 예외 상황을 올바르게 판단한다.
- 구체적인 예시가 있다:
"2026"처럼 올바른 형태를 보여준다. - 과거 실패에서 유래했다: 실제로 발생한 빌드 에러가 이 규칙의 근거다.
예시 2 — 수정 금지 파일 목록
1
2
3
4
5
## 추가/수정 금지 (gem이 제공)
- `_includes/`, `_layouts/`, `_sass/addon|colors|layout/`, `_javascript/`
- `_data/locales/`, `_data/origin/`
- `assets/css/`, `assets/js/`, `assets/404.html`, `assets/feed.xml`, `assets/robots.txt`
- 커스터마이즈 필요 시: 같은 경로에 동일 이름 파일을 만들면 gem 파일을 덮어씀 (override)
이 규칙의 특징:
- glob 패턴처럼 명확하다: 경로가 구체적이어서 에이전트가 판단 없이 적용할 수 있다.
- 대안을 제시한다: “커스터마이즈 필요 시 override 방법”을 함께 담아 에이전트가 다른 경로를 찾을 수 있다.
- 이유가 담겨 있다: “gem이 제공”이라는 이유가 있어야 에이전트가 왜 이 파일들을 건드리면 안 되는지 이해한다.
예시 3 — 배포 관련 경고
1
2
3
4
## GitHub Actions 배포
- 유일한 배포 워크플로우: `.github/workflows/pages-deploy.yml`
- 다른 워크플로우 추가 금지 (이전에 중복 워크플로우 3개로 배포 충돌 발생한 이력 있음)
- htmlproofer가 `_site/` 내 모든 내부 링크를 검증함
이 세 줄은 이 저장소 특유의 이력을 담고 있다. “중복 워크플로우 3개로 배포 충돌 발생”이라는 구체적인 사고 이력은 git blame이나 코드에서 추론하기 어렵다. 이런 내용이 CLAUDE.md에 있어야 에이전트가 같은 실수를 반복하지 않는다.
정리
CLAUDE.md와 AGENTS.md는 AI 에이전트의 행동을 결정하는 구조 문서다. 길이보다 밀도가 중요하고, 모든 곳에 적용하는 전역 규칙보다 필요한 곳에만 적용하는 지역 규칙이 효과적이다.
핵심 원칙을 요약하면:
- 200 라인 원칙: Anthropic이 권장하는 상한선이다. 넘으면 삭제하거나 모듈화한다.
- Claude가 이미 아는 것은 쓰지 않는다: 기본 클린 코드 원칙은 지시 없이도 따른다.
- 이유를 함께 쓴다: 규칙의 근거가 있어야 에이전트가 예외를 올바르게 처리한다.
- 구체적인 경로와 명령을 쓴다: 모호한 표현은 해석이 갈리고 오류를 낳는다.
- 지시보다 도구가 더 강력하다: Hooks나 린터로 강제하는 편이 문서 지시보다 안정적이다.
- 검증 루프를 실행한다: 새 세션에서 직접 물어보거나 안티패턴을 유발해 지시가 실제로 작동하는지 확인한다.
참고 자료
A등급 — 공식 문서 및 1차 자료
- Anthropic, “Best practices for Claude Code” — CLAUDE.md 200 라인 권장, @import 문법, 모듈화 전략 근거
- Anthropic, “Claude Code 공식 문서” — CLAUDE.md 로드 메커니즘, AGENTS.md 동작 방식
B등급 — 블로그 및 커뮤니티 자료 (링크·요약만)
- HumanLayer Blog, “How to write a good CLAUDE.md” — 실무자 관점의 CLAUDE.md 작성 팁, 업계 사례 포함
- Hivetrail, “CLAUDE.md Best Practices” — 모듈화 패턴과 팀 협업 시 CLAUDE.md 관리 사례
관련 포스트 (본 블로그)
- Claude Code Hooks 완전 가이드
- Claude Code 서브에이전트 설계 패턴
- Claude Code Plan Mode 실전 활용
- Claude Code 스킬 작성 완전 가이드
- Claude Code MCP 서버 구축 완전 가이드
Anthropic, “Best practices for Claude Code” — Claude Code Docs. CLAUDE.md를 “short and human-readable / concise”로 유지하고, 각 줄에 대해 “Would removing this cause Claude to make mistakes?” 라고 자문해 가지치기하라고 권장한다. https://code.claude.com/docs/en/best-practices ↩︎
Anthropic, “Claude Code Best Practices”. CLAUDE.md에서
@path/to/file문법으로 외부 파일을 컨텍스트에 포함할 수 있다. ↩︎