📑 이 챕터에서 다룰 내용
9장에서 BUILD.md를 만들고 첫 기능을 TDD로 구현했고, 10장에서 슬래시 명령 풍경을 정리했습니다. 이제 5파일+의 마지막 — CLAUDE.md입니다.
CLAUDE.md는 "AI에게 매 세션마다 자동으로 읽히는 프로젝트 헌법"입니다. 5파일 중 마지막에 만들어지지만, 가장 오래 살아있는 파일입니다. 한 번 잘 써두면 6개월·12개월·24개월 동안 매 세션 자동 입력됩니다.
이 장은 v1.0 9장의 보강 버전입니다. 핵심 추가 내용은 세 가지입니다.
Project-Specific Rules · File Structure · Common Commands · Forbidden Patterns · Compliance Checklist · Quick References가 추가됩니다.
Project-Specific Rules 섹션에 줍줍 두 탭 + TSV 다중 페르소나 사례가 담깁니다.
5파일 + 5확장 모두 갖춰졌는지 최종 확인합니다.
5파일 중 CLAUDE.md를 완성하는 단계입니다.
| SPEC.md (5장) | PLAN.md (6장) | REVIEW.md (8장) | BUILD.md (9장) | CLAUDE.md ◀ 지금 여기 |
|---|---|---|---|---|
| 완성 | 완성 | 완성 | 완성 | 지금 완성 |
Anthropic이 개발한 Constitutional AI: AI에게 고정된 원칙 집합을 부여하면 매번 지시하지 않아도 그 원칙을 따릅니다. CLAUDE.md는 이 원리를 내 프로젝트에 직접 적용한 것입니다.
"헌법"을 한 번 잘 써두면 "NativeWind만 써", "API 키는 Edge Function에서만", "요청 안 한 파일 수정 금지"를 매번 반복할 필요가 없어집니다. Claude Code가 프로젝트를 열 때마다 CLAUDE.md를 읽고 규칙을 자동으로 따릅니다.
| 도구 | 매핑 |
|---|---|
| GSD | STATE.md (결정·차단 메모리) + .clinerules |
| Spec-Kit | /speckit.constitution (프로젝트 헌법) |
| OpenSpec | AGENTS.md (fallback agent context) |
| BMAD | YAML 설정 (페르소나별 룰) |
| Cursor | .cursorrules |
| Cline | .clinerules |
도구마다 파일 이름·형식은 다르지만 본질은 같습니다 — "AI에게 매번 자동 입력될 200줄 컨텍스트".
2장에서 CLAUDE.md를 빈 파일로 만들었고 최소 내용 (절대 금지 + 현재 완성된 것 = 없음)만 넣었습니다. 11장에서 지금까지 진행하면서 확인된 스택·규칙·페르소나·완성된 것을 모두 담은 완성본을 만듭니다.
v1.0의 4개 섹션 (기본 정보·절대 금지·코드 규칙·현재 완성된 것)을 v2에서 10개 섹션으로 확장합니다.
| # | 섹션 | 내용 | 없으면 생기는 문제 |
|---|---|---|---|
| 1 | Project Overview | 앱 이름·기술 스택·아키텍처 | Claude가 엉뚱한 스택으로 코드 작성 |
| 2 | Tech Stack | 프론트·백·결제·배포 명시 | 혼용 (StyleSheet+NativeWind 등) |
| 3 | Critical Constraints | 절대 금지 사항 (스타일·보안·파일) | API 키 노출, 임의 파일 수정 |
| 4 | Code Style | 파일 길이·타입·에러 처리 | 컴포넌트 500줄, 타입 없는 코드 |
| 5 | Project-Specific Rules ★ | E5 콘텐츠 SSOT + 페르소나 규칙 + 회색지대 결정 노출 | 페르소나 사실 환각, 회색지대 위반 |
| 6 | File Structure ★ | 폴더 구조 + 파일별 책임 | 코드 위치 불일치 |
| 7 | Common Commands ★ | 자주 쓰는 명령어 모음 | 매번 검색·반복 |
| 8 | Forbidden Patterns ★ | 절대 쓰면 안 되는 패턴 (정규식 포함) | 반복 위반 |
| 9 | Compliance Checklist ★ | 매 작업 전 자동 점검 항목 | 규칙 망각 |
| 10 | Current State | Phase·완성된 것·작업 중 | /clear 후 이미 만든 것 다시 만들기 |
★ 표시된 5번~9번 섹션이 v1.0 → v2 추가입니다. 특히 5번 (Project-Specific Rules)이 E5 콘텐츠 SSOT의 자리입니다.
아래 템플릿을 Claude Code에게 작성 요청합니다. [대괄호] 부분만 바꾸면 됩니다.
# [앱 이름] # 기술 스택: [스택 요약] # 상태: Phase [N] 진행 중 / 누적 시간 [Nh] / 다음 게이트 G[N] D-[N]일 ## 1. Project Overview - 앱 정의: [한 줄] - 사용자 A: [주 사용자] - 사용자 B: [부 사용자] (해당 시) - 핵심 가치: [E1 회색지대 결정 — 한 줄] ## 2. Tech Stack - 프론트: [Expo 52 + TypeScript + NativeWind] / [Next.js 14 + Tailwind] - 백엔드: Supabase (PostgreSQL + Auth + Storage + Edge Functions) - 결제: Stripe (Edge Function에서만) - 배포: [Vercel / EAS Build] - LLM: Sonnet 4.6 위주, 페르소나 system prompt에 cache_control ## 3. Critical Constraints (어떤 상황에서도 지킵니다) - StyleSheet 사용 금지 → NativeWind(Tailwind)만 - API 비밀 키를 프론트엔드·.env.local에 직접 넣지 않습니다 - 요청하지 않은 기능 임의 추가 금지 - 요청하지 않은 파일 무단 수정 금지 - 작업 전 변경할 파일 목록을 먼저 말합니다 - ⚖️ E1 회색지대 결정 위반 금지 (E1: [한 줄 명시]) ## 4. Code Style - 컴포넌트 파일: 200줄 이하 (초과 시 분리) - 모든 함수에 TypeScript 타입 명시 - 에러 처리 필수 (try/catch 또는 .catch()) - 들여쓰기: 2칸 ## 5. Project-Specific Rules ★ (E5 콘텐츠 SSOT — 해당 시) [줍줍 또는 TSV 같은 콘텐츠 시스템이면 여기에 명시] - [규칙 1: SSOT 인터페이스 위치] - [규칙 2: 페르소나 시스템 프롬프트 환각 방지] - [규칙 3: 자동 일관성 테스트 의무] ## 6. File Structure src/ app/ 라우팅 components/ UI 컴포넌트 lib/ 유틸 + SSOT 인터페이스 api/ 외부 호출 tests/ unit/ 단위 테스트 e2e/ E2E 테스트 .claude/commands/ 커스텀 슬래시 명령 ## 7. Common Commands - npm test - npm run dev - npm run build - npx supabase db push - /daily-review (커스텀) - /spec-evolve (커스텀) ## 8. Forbidden Patterns - /process\.env\.[A-Z_]+/ ← 프론트엔드 코드에 환경변수 직접 사용 금지 - 페르소나 prompt에 환각 유도 표현 금지 ## 9. Compliance Checklist (매 작업 전 자동 점검) - [ ] 변경할 파일 목록 명시했는가 - [ ] 절대 금지 사항 위반 없는가 (E1 회색지대 포함) - [ ] 200줄 이하 유지되는가 - [ ] 타입 명시·에러 처리 있는가 ## 10. Current State (Phase 완성마다 업데이트) - ✅ Phase 0: 5파일+ 구조 + 첫 commit (Day 0) - ✅ Day 1~3: [완성 기능 1] (~Day 3) - 🚧 현재: Day 4 [작업 중인 기능] - 📅 다음 게이트: G1 (Day [N]) - 📊 누적: [Nh] / [예상 총h]
CLAUDE.md는 매 대화마다 전체가 전송됩니다. 500줄짜리 CLAUDE.md는 200줄보다 2.5배 비쌉니다.
핵심 규칙만 남기는 원칙:
- 3번 이상 위반된 적 있는 규칙만 남깁니다
- 당연한 것은 쓰지 않습니다 ("친절하게 답해줘" 같은 것)
- "Current State"는 간결하게 (한 줄 한 항목)
월 1회 정기 점검: /memories 확인 + CLAUDE.md 200줄 이하 정리.
직접 작성이 어려우면 Claude Code에게 요청하세요. 지금까지 만든 파일들을 참조해서 생성합니다.
SPEC.md, PLAN.md, BUILD.md를 읽고 CLAUDE.md를 새 11장의 10개 섹션으로 완성해줘. 특히 §5 Project-Specific Rules에는: - SPEC §[N]의 회색지대 결정 (E1) 을 1~2줄로 요약 - 콘텐츠 시스템이 있다면 SSOT 인터페이스 위치 + 페르소나 환각 방지 규칙 + 자동 일관성 테스트 의무 명시 (E5) - BUILD.md의 LogOnTable 트레이스를 통한 의사결정 패턴 명시 (E4) 200줄 이하로 유지해줘.
# 줄 수 확인 (200 이하) wc -l CLAUDE.md git add CLAUDE.md git commit -m "CLAUDE.md: 10 섹션 + E1·E4·E5 명시 + 5파일+ 체계 완성"
여기가 1장에서 정의한 E5가 처음 등장하는 곳입니다. CLAUDE.md의 §5 Project-Specific Rules 섹션에 박힙니다.
"같은 사실을 여러 페르소나가 다른 톤으로 표현"할 때, 사실 자체는 단일 출처에서 받는 패턴입니다. 코드의 SSOT (Single Source of Truth)를 콘텐츠 영역으로 확장한 것입니다.
9개 표준 도구의 자리: 모두 "코드 명세"에 집중. 콘텐츠 영역 (페르소나 시스템·다중 톤 출력·다국어) 미점유. 사용자 책임으로 떠넘깁니다.
5파일+의 CLAUDE.md는 이 영역을 본문에 박습니다.
E5의 핵심 안전장치는 삼중입니다.
모든 페르소나가 단일 입력 인터페이스에서 사실을 받습니다.
"입력에 없는 사실을 만들지 말라"를 명시합니다.
페르소나마다 다른 출력 시 사실 일치를 자동 검증합니다.
세 안전장치가 CLAUDE.md에 명시되어 매 세션 자동 입력됩니다.
사례 1 — 줍줍의 두 탭 SSOT (B2C)
## 5. Project-Specific Rules — 줍줍 (E5 적용)
원칙: 같은 "지원금 정보"를 두 탭이 다른 톤으로 노출하되, 사실
자체는 단일 출처 (DB의 benefits 테이블) 에서 받습니다.
### Two-Tab Content SSOT 7 규칙
[1] 사실 단일 출처: benefits 테이블의 모든 사실 (마감일·금액·자격
요건) 은 두 탭이 동일하게 표시. 변형 금지.
[2] 톤 분리:
- 🏪 소상공인 탭: "사장님 톤" — 신청 자격 + 매출 영향 강조
- 👤 개인 복지 탭: "시민 톤" — 생애주기 + 가구 상황 강조
summary와 key_requirements 텍스트가 톤에 따라 다를 수 있음.
다만 사실은 동일.
[3] 닉네임 자동 부여 페르소나 풀 분리:
- 소상공인: "[시군구] + [업종] + 운영하는 + [형용사] + 줍줍이"
예: "수원시 카페 운영하는 든든한 줍줍이"
- 개인: "[시군구] + [상황] + [형용사] + 줍줍이"
예: "강남구 취준하는 열정 줍줍이"
형용사 풀 20개 (든든한·열정·꼼꼼한·현명한·부지런한·알뜰한 등)
[4] LLM 분류 프롬프트 분리:
- 소상공인용: target_business_type / target_stage 추출
- 개인 복지용: target_age_min/max / target_household_type / income_criteria
confidence 0.7 미만 필드는 NULL + source_url 보완.
[5] ⚖️ E1 회색지대 일관 노출:
- 모든 노출에 "본 서비스는 정보 제공이 목적이며, 신청 결과를
보장하지 않습니다" 명시
- About 페이지 + 약관 + 콘텐츠 정책 + 어드민까지 일관
[6] 자동 일관성 테스트:
tests/two-tab-consistency.test.ts — 같은 benefit_id에 대해 두 탭
노출 시 사실 일치 (마감일·금액·자격 요건) 자동 검증
실패 시 cron/sync.ts 정지
[7] 환각 방지 명세:
LLM 분류 프롬프트에 "JSON 외 출력 금지" + "추정 금지, 누락은
null 처리" 명시. 페르소나가 입력에 없는 정보를 만들지 않음.
이 7개 규칙이 매 Claude Code 세션에 자동 입력됩니다. 새 LLM 프롬프트 작성, SSOT 인터페이스 변경, 어드민 검수 시점 — 모든 작업에서 자동 점검됩니다.
사례 2 — TSV의 다중 페르소나 SSOT (미디어)
## 5. Project-Specific Rules — TotalSportsView (E5 적용)
원칙: 같은 경기에 대해 여러 페르소나가 다른 톤으로 분석하되,
사실 (스코어·xG·점유율 등) 자체는 단일 출처 (lib/match_facts.ts의
MatchFacts 인터페이스) 에서 받습니다.
### Persona System Rules (Phase 1.0)
[1] 활성 페르소나 2종만:
- STAT (통계학자): 정량·기술적 톤, 수치 강조
- OBSERVER (신중한 관찰자): 균형 어법, "한편으로는 ..., 다만 ..."
Phase 1.1 (Day 34+) 에서 COACH 추가 예정.
[2] SSOT 의무:
모든 페르소나는 lib/match_facts.ts의 MatchFacts 인터페이스를
단일 입력으로 받습니다.
interface MatchFacts {
match_id: string; // league_code:external_id
league_code: string;
league_name_kr: string;
home_team: string;
away_team: string;
kickoff_kst: string; // KST_display 함수 사용
stats?: { // optional — NBA/MLB 데이터 부족 시 환각 방지
xg_home?: number;
xg_away?: number;
possession_home?: number;
possession_away?: number;
};
}
[3] 사실 자체 변경 금지:
페르소나는 해석·표현·강조점만 다름. stats 수치를 추정하거나
변형하지 않습니다.
[4] 자동 일관성 테스트 의무:
tests/persona_consistency.test.ts 5개 케이스:
- 같은 match_id에 대해 STAT + OBSERVER 출력 시 사실 일치
- stats null인 경우 두 페르소나 모두 "통계 미공개" 명시
fail 시 cron/publish.ts 정지.
[5] prompt caching 적용 의무:
페르소나 system prompt 끝에 cache_control: { type: 'ephemeral' }
헤더: ANTHROPIC_API_BETA="prompt-caching-2024-07-31"
[6] 페르소나별 SEO 키워드 분리 (cannibalization 방지):
- STAT: "통계 분석", "xG 분석"
- OBSERVER: "경기 미리보기", "다관점 분석"
Phase 1.1 COACH 추가 시: "전술 분석"
[7] 익명성 유지:
- 가상 인물명 부여 금지 (예: "김STAT", "박OBSERVER")
- 페르소나는 시스템 정체성, 사람으로 의인화하지 않음
- 운영자 패널에서 페르소나 정지 시 5초 내 글 비공개
[8] ⚖️ E1 Position C 일관 노출:
- 모든 페르소나 출력 상단/하단에 "분석 콘텐츠 제공이 목적이며,
베팅 사이트 연결·픽 추천하지 않음" 명시
- About 페이지 + Footer + 콘텐츠 상단 면책 일관
두 사례의 공통 패턴
| 영역 | 줍줍 | TSV |
|---|---|---|
| SSOT 출처 | benefits 테이블 (DB) | lib/match_facts.ts (TypeScript 인터페이스) |
| 페르소나 수 | 2 (소상공인 / 개인) | 2 (STAT / OBSERVER), Phase 1.1에서 +1 |
| 톤 분리 방식 | 사장님 톤 / 시민 톤 | 통계 톤 / 균형 톤 |
| 환각 방지 | LLM 프롬프트 "추정 금지, 누락 null" | system prompt + stats optional 인터페이스 |
| 자동 일관성 테스트 | tests/two-tab-consistency.test.ts | tests/persona_consistency.test.ts |
| E1 일관 노출 | "정보 제공 목적, 결과 보장 없음" 모든 곳에 | "Position C, 베팅 연결·픽 추천 없음" 모든 곳에 |
| 자동 정지 트리거 | cron/sync.ts 정지 | cron/publish.ts 정지 |
두 프로젝트가 다른 도메인 (B2C 정보 앱 vs 미디어 플랫폼)인데도 같은 E5 패턴 — SSOT 인터페이스 + 톤 분리 + 환각 방지 + 자동 일관성 테스트 + E1 일관 노출.
이 패턴이 9개 표준 도구가 모두 다루지 못하는 영역입니다. 콘텐츠 SSOT는 E5의 본질입니다.
11장까지 왔다면 5파일이 모두 완성됐고, 5확장 5개도 모두 등장했습니다. 최종 점검을 합니다.
5파일 점검 표
| 파일 | 완성 기준 | 상태 | |
|---|---|---|---|
| 5장 | SPEC.md | 7항목 + 성공 기준(숫자) + 수익화 + ⚖️ E1 회색지대 | ⬜ 확인 |
| 6장 | PLAN.md | Phase별 DoD(숫자) + 30일 + 게이트 + 리스크 + ★ E2 페이스 | ⬜ 확인 |
| 8장 | REVIEW.md | 15가지 체크 + 3단계 판정 + READY: YES + ⭐ E3 두 검토자 | ⬜ 확인 |
| 9장 | BUILD.md | 일자별 5분 양식 + ⭐ E4 LogOnTable 트레이스 1~3줄 | ⬜ 확인 |
| 11장 | CLAUDE.md | 10 섹션 + 200줄 이하 + ⭐ E5 콘텐츠 SSOT | ⬜ 확인 |
5확장 점검 표
| 확장 | 박힌 위치 | 등장 챕터 | 상태 |
|---|---|---|---|
| E1 회색지대 | SPEC.md § 회색지대 결정 | 5장 | ⬜ 확인 |
| E2 1인 페이스 | PLAN.md (시간 갭·게이트 휴식·R4) | 6장 | ⬜ 확인 |
| E3 두 검토자 | REVIEW.md (12건 4+6+2 패턴) | 8장 | ⬜ 확인 |
| E4 LogOnTable | BUILD.md (일자별 트레이스) | 9장 | ⬜ 확인 |
| E5 콘텐츠 SSOT | CLAUDE.md §5 Project-Specific Rules | 11장 | ⬜ 확인 |
5파일+ 체계 완성 검증
# 5파일 전체 존재 확인 ls *.md # 출력: BUILD.md CLAUDE.md PLAN.md REVIEW.md SPEC.md # 새 세션에서 5파일로 맥락 복원 테스트 /clear SPEC.md, PLAN.md, REVIEW.md, BUILD.md, CLAUDE.md를 읽고 현재 프로젝트 상황을 요약해줘. 그리고 5확장 5개 (E1~E5) 가 각 파일에 어디에 박혔는지 1줄씩 답해줘. # Claude가 즉시 현재 상황 + 5확장 위치를 정확히 답하면 # 5파일+ 체계 완성
이 장의 마지막 메시지: 1탄·2탄·3탄 책 본문 자체가 큰 LogOnTable입니다. 책을 정독하면 "내가 따라할 수 있는 결정 패턴 + 5파일+ 사이클 + 5확장 적용"이 손에 들립니다.
책을 펼친 시점부터 자유 창작 가능 수준까지의 학습 경로가 1탄·2탄·3탄·권7로 이어집니다.
- 1️⃣ 핵심: CLAUDE.md = 10 섹션 + 200줄 + ⭐ E5 콘텐츠 SSOT. 매 세션 자동 입력 = 살아있는 헌법.
- 2️⃣ 10 섹션 (v1.0 4 → v2 10): Project Overview / Tech Stack / Critical Constraints / Code Style / Project-Specific Rules ★ (E5 적용) / File Structure ★ / Common Commands ★ / Forbidden Patterns ★ / Compliance Checklist ★ / Current State
- 3️⃣ 표준 흡수 매핑: GSD
STATE.md+.clinerules/ Spec-Kit/speckit.constitution/ OpenSpecAGENTS.md/ Cursor.cursorrules - 4️⃣ E5 삼중 안전장치: SSOT 인터페이스 (단일 출처) + 시스템 프롬프트 환각 방지 + 자동 일관성 테스트
- 5️⃣ 두 사례 공통 패턴: 줍줍 7 규칙 (B2C 두 탭) + TSV 8 규칙 (미디어 다중 페르소나) — SSOT 출처 + 톤 분리 + 환각 방지 + 자동 테스트 + E1 일관 노출 + 자동 정지 트리거
- 6️⃣ 5파일+ 체계 완성: SPEC+E1(5장) / PLAN+E2(6장) / REVIEW+E3(8장) / BUILD+E4(9장) / CLAUDE+E5(11장)
- 7️⃣ 점검법:
/clear후 "5파일 읽고 현재 상황 + 5확장 위치 답해줘" — Claude가 즉시 답하면 완성.
12장 — Context Engineering (1탄 v1.0 10장 정정렬). AI 협업의 영역이 펼쳐집니다. 그러나 모든 고급 기능이 5파일+의 토대 위에서 작동합니다. 토대가 단단하면 그 위가 단단합니다.