SOUL.md 도입과 CLAUDE.md 재설계: 2026 베스트 프랙티스로 AI 코딩 에이전트 최적화하기
Claude Code의 글로벌 CLAUDE.md가 234줄로 비대해지면서 구조 부재, PR 템플릿 장황함, 도구 선택 모호함 등의 문제가 발생했습니다. SOUL.md를 새로 만들어 AI의 정체성을 분리하고, CLAUDE.md를 3단계 구조(원칙→워크플로우→참조)로 재설계한 과정을 공유합니다.
1. 문제 상황
Claude Code를 몇 달간 사용하면서 글로벌 CLAUDE.md가 점점 비대해졌습니다. 새로운 규칙이 필요할 때마다 아래에 추가하다 보니, 234줄짜리 평면적 나열 파일이 되어 있었습니다.
구체적으로 느꼈던 문제는 다음과 같았습니다:
# 최적화 전 CLAUDE.md 구조 (234줄)
# Global Claude Instructions ← 제목만 있고 원칙 없음
불확실하면 질문 ← 한 줄짜리 원칙이 맨 위에 덩그러니
## Git Commit (20줄)
## Git Merge / PR (68줄) ← PR 템플릿만 52줄
## Code Quality (9줄)
## Implementation Approach (15줄)
## Tool Usage (19줄) ← 추상적 나열
## Package Managers (11줄)
## Security (16줄)
## Error Handling (11줄)
## Documentation (11줄)
## Language-Specific (29줄) ← 4개 언어만
첫 번째 문제는 구조의 부재였습니다. 모든 섹션이 같은 레벨(##)에 평면적으로 나열되어 있었습니다. "핵심 원칙"과 "언어별 가이드" 같은 서로 다른 성격의 내용이 동일한 우선순위로 취급되고 있었습니다.
두 번째 문제는 장황한 PR 템플릿이었습니다. 간단한 PR, 복잡한 PR, 기술적 PR 등 세 가지 양식이 각각 풀 템플릿으로 작성되어 있어서 52줄을 차지하고 있었습니다. 실제로는 하나의 통합 템플릿이면 충분했습니다.
# 최적화 전: PR 템플릿 3종 (52줄)
## 기본 양식 (간단한 PR) → 12줄
## 확장 양식 (복잡한 PR) → 18줄
## 기술적 PR (Usage 추가) → 16줄
## 중요 사항 → 6줄
세 번째 문제는 도구 선택 가이드의 모호함이었습니다. 기존 Tool Usage 섹션은 이런 식이었습니다:
# 최적화 전: 추상적 나열
### 전용 도구 우선 사용 (Bash 사용 금지)
Read > cat/head/tail # 파일 읽기
Edit > sed/awk # 파일 수정
Write > echo/cat # 파일 생성
Glob > find/ls # 파일 검색
Grep > grep/rg # 내용 검색
"Read를 써라"라고만 되어 있지, 언제 Read를 쓰고 언제 Glob을 먼저 써야 하는지에 대한 판단 기준이 없었습니다. 경로를 아는 경우와 패턴으로 찾아야 하는 경우의 구분이 필요했습니다.
네 번째 문제는 누락된 섹션들이었습니다. 에러 복구 패턴(pre-commit hook 실패 시 --amend 금지 등), EnterPlanMode를 언제 사용할지의 판단 기준, Dart/Flutter나 Prisma 같은 언어 가이드가 빠져 있었습니다.
그리고 가장 근본적인 문제가 있었습니다: Claude Code에 "정체성"이 없었습니다. 규칙만 나열되어 있을 뿐, 이 에이전트가 어떤 가치관을 가지고 의사결정을 하는지에 대한 철학이 정의되어 있지 않았습니다.
2. 원인 분석
CLAUDE.md는 왜 비대해지는가
CLAUDE.md는 시간이 지날수록 자연스럽게 비대해집니다. 새로운 프로젝트를 진행하거나, AI 에이전트와 작업하면서 발견한 문제를 해결하기 위해 규칙을 하나씩 추가하게 됩니다. 문제는 추가는 쉽지만 정리는 하지 않는다는 것입니다.
2026년 초, AI 코딩 에이전트의 설정 파일에 대한 여러 베스트 프랙티스 글이 나왔습니다. GitHub Blog에서 2,500개 이상의 저장소를 분석한 결과와 Anthropic의 Claude Code 개발자 Boris Cherny의 워크플로우가 공개되면서, 몇 가지 명확한 트렌드가 보였습니다.
2026 베스트 프랙티스 트렌드
간결성 원칙: 각 섹션을 최대 200단어로 제한하고, 헤딩 깊이를 h3까지만 사용하는 것이 권장됩니다. 장황한 설명보다 구체적인 파일명, 명령어, 라인 번호가 더 효과적이라는 분석입니다.
Plan-based 워크플로우: Anthropic의 Boris Cherny는 자신의 워크플로우에서 Plan 모드를 강조했습니다. 계획을 먼저 세우고 검토한 후에 실행하는 방식이 결과물 품질을 크게 높인다는 것입니다.
Team Knowledge 축적: CLAUDE.md를 단순한 규칙 파일이 아니라, 팀의 실수와 학습을 축적하는 지식 기반으로 활용하는 방식입니다. Anthropic 팀의 CLAUDE.md는 약 2.5k 토큰 정도의 축적된 학습 내용을 담고 있다고 합니다.
AI Identity: AI 에이전트를 단순한 도구가 아닌, 투명하고 책임있는 개발 파트너로서 정체성을 부여하는 접근이 주목받고 있습니다.
정체성(SOUL.md)과 규칙(CLAUDE.md)의 분리가 필요한 이유
규칙 파일 하나에 "왜 이렇게 해야 하는가(가치관)"와 "어떻게 해야 하는가(실행 규칙)"를 섞으면, 파일이 커질수록 핵심 원칙이 묻히게 됩니다. 마치 소프트웨어 설계에서 "관심사의 분리"가 중요하듯이, AI 에이전트 설정도 계층이 필요합니다:
| 계층 | 파일 | 역할 | 변경 빈도 |
|---|---|---|---|
| 철학 | SOUL.md |
가치관, 정체성, 커뮤니케이션 스타일 | 거의 안 바뀜 |
| 규칙 | CLAUDE.md |
워크플로우, 도구 사용법, 코딩 컨벤션 | 프로젝트마다 조정 |
| 기억 | MEMORY.md |
세션 간 학습, 실수 기록 | 매 세션 갱신 |
이 분리를 통해 각 파일의 책임이 명확해지고, CLAUDE.md를 프로젝트별로 커스터마이징할 때 핵심 가치관을 건드리지 않아도 됩니다.
3. 해결 방법
Step 1: SOUL.md 신규 생성 - AI에게 정체성 부여하기
SOUL.md는 완전히 새로 만든 파일입니다. Claude Code에게 "너는 어떤 존재인가"를 정의하는 개발 철학 문서입니다.
# 개발 철학 - Claude의 정체성
## Who I Am
나는 신중하고 체계적인 개발 파트너다.
빠르게 추측하기보다 정확하게 이해하는 것을 우선한다.
형식적인 도움이 아닌, 실질적인 가치를 제공한다.
핵심 설계 원칙 1: Identity as First-Class Principle
2026 트렌드를 반영하여, AI 에이전트의 정체성을 최우선 원칙으로 정의했습니다:
## Identity as First-Class Principle
나는 단순한 도구가 아닌, 투명하고 책임있는 개발 파트너다:
- **투명성**: 모든 결정과 행동을 명확히 설명
- **책임성**: 실수를 인정하고 즉시 수정
- **지속성**: SOUL.md, CLAUDE.md, MEMORY.md를 통한 연속성
여기서 "지속성"이 중요합니다. SOUL.md(가치관) → CLAUDE.md(규칙) → MEMORY.md(기억) 세 파일이 하나의 시스템으로 작동하면서, 세션 간 연속성을 만들어냅니다.
핵심 설계 원칙 2: 가치관은 의사결정 우선순위로 표현
추상적인 가치 나열 대신, 실제 충돌 상황에서의 우선순위로 표현했습니다:
## Core Values
### 확실성 > 속도
추측으로 실수하는 것보다 질문으로 확인하는 것이 낫다.
### 이해 > 행동
코드를 보기 전에 제안하지 않는다.
탐색하고 이해한 후에 실행한다.
### 최소주의
요청받지 않은 기능을 추가하지 않는다.
필요한 만큼만, 하지만 제대로 구현한다.
"확실성 > 속도"라는 표현은 Claude Code가 빠르게 답변하려다 추측으로 틀린 제안을 하는 상황을 방지합니다. "이해 > 행동"은 코드를 읽지도 않고 수정 제안을 하는 것을 막습니다.
핵심 설계 원칙 3: Success Metrics를 원칙 형식으로
기존에 흔히 볼 수 있는 체크박스 형태 대신, 선언적 원칙 형태로 바꿨습니다:
# Before: 체크박스 나열
- ✅ 올바른 질문을 했는가?
- ✅ 코드를 더 나은 상태로 남겼는가?
- ✅ 예상치 못한 부작용을 방지했는가?
- ✅ 사용자의 시간을 절약했는가?
- ✅ 신뢰를 구축했는가?
# After: 원칙 선언
성공은 다음으로 측정된다:
- 명확한 요구사항 확인 후 구현
- 코드를 이전보다 나은 상태로 유지
- 예상치 못한 부작용 사전 방지
5개 항목을 3개로 줄이면서, "시간 절약"과 "신뢰 구축"은 위 세 가지가 달성되면 자연스럽게 따라오는 결과이므로 제거했습니다.
SOUL.md와 CLAUDE.md의 교차 참조
두 파일이 독립적이면서도 연결되도록, 각 파일 끝에 참조를 넣었습니다:
# SOUL.md 끝
실행 규칙은 CLAUDE.md 참조.
프로젝트별 기술 명세는 각 프로젝트의 AGENTS.md 참조.
# CLAUDE.md 끝
**참조**:
- AI 정체성 및 가치관: `~/.claude/SOUL.md`
- 프로젝트별 기술 명세: 각 프로젝트의 `AGENTS.md`
Step 2: CLAUDE.md 3단계 구조로 재설계
SOUL.md를 추가하면서, 기존 CLAUDE.md도 함께 정리했습니다. 핵심 변경은 평면 구조를 3단계 계층 구조로 바꾼 것입니다:
# Claude Code: 개발 원칙 및 워크플로우
## 1. 핵심 원칙 (Decision Principles) ← 의사결정 기준
## 2. 워크플로우 (Workflow) ← 실행 방법
## 3. 참조 (Reference) ← 필요할 때 찾아보는 정보
이 구조의 의도는 읽는 순서가 곧 우선순위가 되도록 하는 것입니다. Claude Code가 CLAUDE.md를 로드할 때, 가장 먼저 핵심 원칙을 인식하고, 그다음 워크플로우를 따르며, 세부 참조는 필요할 때 찾아봅니다.
핵심 원칙 섹션 신설 (Plan-Act-Reflect)
기존 CLAUDE.md에는 명시적인 원칙 섹션이 없었습니다. 맨 위에 "불확실한 사항은 항상 사용자에게 먼저 질문할 것" 한 줄만 있었습니다. 이것을 2026 Plan-based 워크플로우를 반영한 4대 원칙으로 확장했습니다:
## 1. 핵심 원칙 (Decision Principles)
### 확실성 우선
**불확실하면 항상 질문한다.**
- 추측 < 질문
- "아마도", "~인 것 같다" 금지
### Plan-Act-Reflect (2026 워크플로우)
**탐색 → 계획 → 검토 → 실행** 순서 엄수
- 코드 읽기 전 제안 금지
- 복잡한 작업은 EnterPlanMode로 계획 먼저
- 계획 승인 후 실행
- 완료 후 반성 (MEMORY.md 기록) # ← MEMORY.md와 연결
### 품질 책임
- 테스트 전 커밋 금지
- 빌드 경고 무시 금지
- 더 나은 상태로 남기기
### 최소주의
- 요청받지 않은 기능 추가 금지
- 필요한 것만, 제대로 구현
Plan-Act-Reflect 패턴이 핵심입니다. 이전에는 "탐색 → 계획 → 구현" 정도의 가이드만 있었는데, "Reflect(반성)" 단계를 추가해서 완료 후 학습을 MEMORY.md에 기록하도록 했습니다. 이를 통해 세션 간 학습이 축적됩니다.
PR 템플릿 간소화 (52줄 → 29줄)
가장 체감이 큰 변화입니다. 기존에는 세 가지 PR 양식(기본/확장/기술적)이 각각 풀 템플릿으로 있었습니다:
# Before: 3종 분리 템플릿 (52줄)
**기본 양식 (간단한 PR)**:
gh pr create --title "PR 제목" --body "$(cat <<'EOF'
## Summary
- [핵심 변경사항]
## Test plan
- [ ] [테스트 항목]
Closes #<issue_number>
EOF
)"
**확장 양식 (복잡한 PR - Changes 카테고리 추가)**:
gh pr create --title "PR 제목" --body "$(cat <<'EOF'
## Summary
...
## Changes
### [카테고리명]
- [상세 내용]
## Test plan
...
EOF
)"
**기술적 PR (Usage/Behavior 추가)**:
# API 변경, CLI 추가 등의 경우
## Usage
...
이것을 조건부 섹션이 포함된 단일 템플릿으로 통합했습니다:
# After: 통합 템플릿 (29줄)
gh pr create --title "type: subject" --body "$(cat <<'EOF'
## Summary
- [핵심 변경 2-5개]
## Changes (복잡한 PR만) # ← 조건부
### Category
- details
## Usage (API/CLI 변경 시) # ← 조건부
\`\`\`bash
# example
\`\`\`
## Test plan
- [ ] test items
Closes #N
EOF
)"
"(복잡한 PR만)", "(API/CLI 변경 시)" 같은 조건문을 섹션 제목에 넣어서, Claude Code가 상황에 맞게 필요한 섹션만 포함하도록 했습니다. 불필요한 반복을 줄이면서도 모든 케이스를 커버합니다.
Tool Usage를 결정 트리로 변환
기존의 "A > B" 나열을 상황별 결정 트리로 바꿨습니다:
# Before: 추상적 대응표
Read > cat/head/tail
Edit > sed/awk
Write > echo/cat
Glob > find/ls
Grep > grep/rg
# After: 상황별 결정 트리
**파일 읽기**:
- 정확한 경로 알고 있음 → `Read`
- 파일 패턴으로 찾기 → `Glob` 후 `Read`
- 내용으로 파일 찾기 → `Grep` (files_with_matches)
**파일 수정**:
- 기존 파일 수정 → `Edit` (정확한 문자열 대체)
- 새 파일 생성 → `Write`
- 절대 사용 금지 → sed/awk/echo
**검색**:
- 파일 이름 패턴 → `Glob` (예: "**/*.ts")
- 파일 내용 → `Grep` (정규식 지원)
- 복잡한 탐색 → `Explore` agent
차이점은 명확합니다. "Read > cat"은 "cat 대신 Read를 써라"라는 규칙일 뿐이지만, 결정 트리는 "파일 경로를 아는가?"라는 질문에서 시작해서 상황에 맞는 도구로 안내합니다. Claude Code가 실제로 도구를 선택할 때 더 정확한 판단을 내릴 수 있게 됩니다.
EnterPlanMode 복잡도 매트릭스 추가
"언제 계획 모드를 쓸까?"에 대한 기존 가이드는 리스트 나열뿐이었습니다:
# Before: 단순 나열
### When to use EnterPlanMode
- 새로운 기능 구현
- 3개 이상 파일 수정 예상
- 아키텍처 결정 필요
- 여러 접근 방식 가능
이것을 4가지 요소의 복잡도 매트릭스로 바꿨습니다:
# After: 복잡도 매트릭스
| 요소 | Low | Medium | High |
|------|-----|--------|------|
| 파일 개수 | 1-2개 | 3-5개 | 6개+ |
| 아키텍처 영향 | 없음 | 부분 | 전체 |
| 접근 방식 | 명확 | 2-3가지 | 다수 |
| 위험도 | 낮음 | 중간 | 높음 |
**판단**: Medium 이상 2개 → EnterPlanMode 사용 # ← 명확한 기준
**예시**:
- ✅ 새 인증 시스템 추가 (High 아키텍처 + High 접근)
- ✅ 3개 파일 리팩토링 (Medium 파일 + Medium 위험)
- ❌ 타이포 수정 (Low 모든 요소)
핵심은 "Medium 이상 2개"라는 구체적인 임계값입니다. 이전에는 "파일 3개 이상이면 Plan 모드"라고만 되어 있어서, 파일 1개짜리 작업이지만 아키텍처 영향이 큰 경우(예: DB 스키마 변경)를 놓쳤습니다.
에러 복구 패턴 섹션 추가
기존 CLAUDE.md에 완전히 빠져있던 내용입니다. 특히 pre-commit hook 실패 후 --amend 사용 금지는 실제로 겪었던 문제에서 나온 규칙입니다:
#### 에러 복구
**Pre-commit hook 실패**:
- ❌ `--amend` 사용 금지 (이전 커밋 덮어씀) # ← 핵심!
- ✅ 문제 수정 → 새 커밋 생성
**빌드 실패**:
- 즉시 수정 시도
- 복잡하면 TODO 등록 + 사유 기록
- 절대 무시하지 않음
**Git 충돌**:
- 양쪽 변경 이해 후 해결
- 불확실하면 사용자 확인
**의존성 문제**:
- lock 파일 우선 신뢰
- `node_modules` 삭제 후 재설치
- 패키지 매니저 일관성 확인
pre-commit hook이 실패하면 커밋이 만들어지지 않습니다. 이 상태에서 --amend를 사용하면 이전의 정상 커밋을 덮어쓰게 되는 문제가 있습니다. AI 에이전트는 이 맥락을 놓치기 쉬워서, 명시적으로 금지 규칙을 넣었습니다.
Team Knowledge Management 섹션 추가
2026 트렌드의 핵심인 "팀 지식 축적" 섹션을 추가했습니다:
### Team Knowledge Management
#### 실수와 학습 문서화
- PR에서 발견한 실수 → CLAUDE.md에 기록
- 반복되는 문제 → 명시적 DON'T 추가
- 프로젝트별 패턴 → AGENTS.md에 누적
#### 정기 리뷰 (몇 주마다)
# CLAUDE.md 최적화 요청
"Review this CLAUDE.md and suggest improvements"
이 섹션의 핵심 아이디어는 CLAUDE.md를 "한 번 쓰고 끝"이 아니라, 계속 진화하는 지식 기반으로 만드는 것입니다. 실제로 Anthropic 팀도 이런 방식으로 운영하고 있다고 합니다.
프로젝트별 CLAUDE.md 가이드 추가
글로벌 CLAUDE.md와 프로젝트별 CLAUDE.md의 역할 분리에 대한 가이드도 추가했습니다:
### 프로젝트별 CLAUDE.md/AGENTS.md
#### 글로벌 vs 프로젝트
- 글로벌: 모든 프로젝트 공통 원칙
- 프로젝트: 해당 프로젝트만의 특수사항
#### AGENTS.md 핵심 (2026 베스트 프랙티스)
- 1줄 설명 (role-based prompt)
- 패키지 매니저 (npm 아니면 명시)
- Explicit Dos and Don'ts
GitHub Blog의 2,500개 저장소 분석에서 나온 핵심 인사이트는, 효과적인 설정 파일일수록 구체적인 명령어를 초반에 배치한다는 것입니다. 긴 설명보다 실행 가능한 명령어 하나가 더 효과적입니다:
# 프로젝트별 CLAUDE.md 예시
## 빌드
- Dev: `flutter run` # ← 구체적 명령어 먼저
- Build: `flutter build apk`
## 아키텍처
- BLoC 패턴 사용
- `lib/features/` 기능별 구조
## DON'T # ← 명시적 금지 사항
- Riverpod 사용하지 않음 (BLoC만)
- `setState()` 직접 사용 금지
Language-Specific 확장 (4개 → 8개)
기존에 TypeScript, Python, Go, Rust만 있던 언어 가이드에 Dart/Flutter, Shell Scripts, YAML, Prisma를 추가했습니다:
# Dart/Flutter
flutter format . # 커밋 전
flutter analyze # 커밋 전
flutter test # 커밋 전
# Shell Scripts
shellcheck script.sh # 커밋 전
# Prisma
npx prisma format # schema.prisma 수정 시
npx prisma generate # 스키마 변경 시
npx prisma migrate dev # 마이그레이션
각 언어의 커밋 전 체크 명령어를 명시함으로써, Claude Code가 커밋 전 빌드/테스트 단계에서 프로젝트의 기술 스택에 맞는 검증을 수행할 수 있게 됩니다.
Destructive Operations를 Safety 섹션으로 재배치
기존에는 "Git Merge / PR" 섹션 하단에 "Destructive Operations"가 묻혀 있었습니다. 이것을 Git 워크플로우의 독립적인 Safety 서브섹션으로 승격했습니다:
# Before: PR 섹션 하단에 묻혀 있음
## Git Merge / PR
### PR 생성 ...
### PR 머지 ...
### Destructive Operations ← 여기에 묻혀 있었음
# After: Git 워크플로우의 독립 Safety 섹션
### 2.1 Git 워크플로우
#### Commit ...
#### PR 생성 ...
#### PR 머지 ...
#### Safety - Destructive Operations # ← 독립 서브섹션으로 승격
위치를 바꾼 것만으로도 가시성이 높아집니다. 특히 git checkout .과 git restore .를 Destructive 목록에 명시적으로 추가했습니다. 이 두 명령어는 작업 중인 변경사항을 전부 날릴 수 있지만, "파괴적"이라는 인식 없이 사용되는 경우가 많습니다.
4. 핵심 개념 정리
파일 역할 분리 체계
| 파일 | 위치 | 역할 | 특징 |
|---|---|---|---|
SOUL.md |
~/.claude/ |
개발 철학, 정체성 | 거의 변경 안 함, 가치관 정의 |
CLAUDE.md (글로벌) |
~/.claude/ |
모든 프로젝트 공통 규칙 | 원칙 + 워크플로우 + 참조 3단계 |
CLAUDE.md (프로젝트) |
각 프로젝트 루트 | 프로젝트별 특수 규칙 | 빌드 명령, 아키텍처, DO/DON'T |
AGENTS.md |
각 프로젝트 루트 | 에이전트 전문화 설정 | 1줄 설명 + 명령어 + 금지사항 |
MEMORY.md |
~/.claude/projects/ |
세션 간 학습 기록 | 매 세션 갱신 |
CLAUDE.md 3단계 구조
| 단계 | 섹션 | 목적 | 읽는 시점 |
|---|---|---|---|
| 1 | 핵심 원칙 | 의사결정 기준 | 항상 |
| 2 | 워크플로우 | 실행 방법 | 작업 수행 시 |
| 3 | 참조 | 세부 정보 | 필요할 때 |
EnterPlanMode 복잡도 매트릭스
| 요소 | Low | Medium | High |
|---|---|---|---|
| 파일 개수 | 1-2개 | 3-5개 | 6개+ |
| 아키텍처 영향 | 없음 | 부분 | 전체 |
| 접근 방식 | 명확 | 2-3가지 | 다수 |
| 위험도 | 낮음 | 중간 | 높음 |
규칙: Medium 이상 요소가 2개 이상이면 EnterPlanMode 사용
Before/After 비교
| 항목 | Before | After |
|---|---|---|
| SOUL.md | 없음 | 46줄 (신규 생성) |
| CLAUDE.md 구조 | 평면 나열 | 3단계 계층 |
| PR 템플릿 | 52줄 (3종) | 29줄 (통합 1종) |
| 도구 선택 | 대응표 | 결정 트리 |
| EnterPlanMode 기준 | 리스트 | 복잡도 매트릭스 |
| 에러 복구 | 없음 | 4가지 패턴 |
| 언어 지원 | 4개 | 8개 |
| Team Knowledge | 없음 | 문서화 + 정기 리뷰 |
| 정체성 정의 | 없음 | SOUL.md로 분리 |
5. 베스트 프랙티스
CLAUDE.md 작성 체크리스트
- [ ] 3단계 구조 사용 (원칙 → 워크플로우 → 참조)
- [ ] 각 섹션 200단어 이내로 유지
- [ ] 헤딩 깊이 h3까지만 (h4는 예외적으로만)
- [ ] 추상적 설명보다 구체적 명령어 우선 배치
- [ ] PR 템플릿은 조건부 섹션으로 통합
- [ ] 도구 선택에 결정 트리 패턴 사용
- [ ] 에러 복구 패턴 반드시 포함
- [ ] Destructive Operations 별도 Safety 섹션으로 분리
- [ ] Claude 메타정보(
Generated with Claude Code) 추가 금지 명시
SOUL.md 작성 체크리스트
- [ ] 가치관은 우선순위 형태로 표현 ("A > B")
- [ ] CLAUDE.md와 중복 제거 (규칙은 CLAUDE.md에만)
- [ ] Success Metrics는 원칙 형태로 (체크박스 아님)
- [ ] Identity as First-Class Principle 섹션 포함
- [ ] 끝에 CLAUDE.md 교차 참조 포함
유지보수 체크리스트
- [ ] 몇 주마다 CLAUDE.md 리뷰 및 최적화
- [ ] PR에서 발견한 실수는 즉시 DON'T로 기록
- [ ] 새 프로젝트 시작 시 프로젝트별 CLAUDE.md 생성 검토
- [ ] MEMORY.md에 세션별 학습 기록
6. FAQ
Q: SOUL.md와 CLAUDE.md를 왜 분리해야 하나요?
A: SOUL.md는 AI의 가치관과 정체성(변경 거의 없음)을 정의하고, CLAUDE.md는 실행 규칙(프로젝트마다 조정)을 정의합니다. 관심사를 분리하면 CLAUDE.md를 프로젝트별로 커스터마이징할 때 핵심 가치관을 건드리지 않아도 됩니다.
Q: CLAUDE.md가 200줄이 넘어도 괜찮나요?
A: 전체 줄 수보다 각 섹션이 200단어 이내인지가 더 중요합니다. 3단계 구조를 유지하면 Claude Code가 필요한 정보를 빠르게 찾을 수 있습니다. 다만, 불필요하게 길어지고 있다면 정기 리뷰 시점입니다.
Q: EnterPlanMode 복잡도 매트릭스에서 "아키텍처 영향: 부분"의 기준은 무엇인가요?
A: 기존 모듈의 인터페이스를 변경하거나, 새로운 의존성을 추가하는 수준입니다. "전체"는 디렉토리 구조 변경이나 데이터 흐름 전체 재설계 같은 경우입니다.
Q: 이미 CLAUDE.md가 있는 프로젝트에 AGENTS.md도 필요한가요?
A: CLAUDE.md가 프로젝트 전체 규칙이라면, AGENTS.md는 특정 에이전트(테스트 전문, 리뷰 전문 등)의 전문화된 설정입니다. 단일 에이전트로 작업하는 경우 CLAUDE.md만으로 충분합니다.
Q: pre-commit hook 실패 후 --amend를 쓰면 안 되는 이유가 무엇인가요?
A: pre-commit hook이 실패하면 커밋이 생성되지 않습니다. 이 상태에서 --amend를 사용하면 이전의 정상 커밋이 수정되어, 의도하지 않은 변경이 이전 커밋에 섞이거나 이전 작업이 덮어쓰여질 수 있습니다. 항상 새 커밋을 생성해야 합니다.
7. 참고 자료
- How to write a great agents.md - GitHub Blog - 2,500개 저장소 분석 기반 에이전트 설정 작성 가이드
- CLAUDE.md Concise Agent Optimization 2026 - SmartScope - CLAUDE.md 간결성 최적화 방법론
- Inside the Development Workflow of Claude Code's Creator - InfoQ - Boris Cherny의 Claude Code 워크플로우
- Improve your AI code output with AGENTS.md - Builder.io - AGENTS.md 작성 실전 가이드