11장 — CLAUDE.md + E5
1탄 11장
CLAUDE.md + E5 콘텐츠 SSOT
AI에게 매일 읽히는 헌법 — 한 번 잘 써두면 6개월이 편합니다
📑 이 챕터에서 다룰 내용

9장에서 BUILD.md를 만들고 첫 기능을 TDD로 구현했고, 10장에서 슬래시 명령 풍경을 정리했습니다. 이제 5파일+의 마지막 — CLAUDE.md입니다.

CLAUDE.md는 "AI에게 매 세션마다 자동으로 읽히는 프로젝트 헌법"입니다. 5파일 중 마지막에 만들어지지만, 가장 오래 살아있는 파일입니다. 한 번 잘 써두면 6개월·12개월·24개월 동안 매 세션 자동 입력됩니다.

이 장은 v1.0 9장의 보강 버전입니다. 핵심 추가 내용은 세 가지입니다.

1
4개 섹션 → 10개 섹션으로 확장

Project-Specific Rules · File Structure · Common Commands · Forbidden Patterns · Compliance Checklist · Quick References가 추가됩니다.

2
E5 콘텐츠 SSOT 처음 등장

Project-Specific Rules 섹션에 줍줍 두 탭 + TSV 다중 페르소나 사례가 담깁니다.

3
5파일+ 체계 완성 점검

5파일 + 5확장 모두 갖춰졌는지 최종 확인합니다.

5파일 중 CLAUDE.md를 완성하는 단계입니다.

SPEC.md (5장)PLAN.md (6장)REVIEW.md (8장)BUILD.md (9장)CLAUDE.md ◀ 지금 여기
완성완성완성완성지금 완성
📘 이론적 배경 — Constitutional AI (Anthropic, 2022)

Anthropic이 개발한 Constitutional AI: AI에게 고정된 원칙 집합을 부여하면 매번 지시하지 않아도 그 원칙을 따릅니다. CLAUDE.md는 이 원리를 내 프로젝트에 직접 적용한 것입니다.

"헌법"을 한 번 잘 써두면 "NativeWind만 써", "API 키는 Edge Function에서만", "요청 안 한 파일 수정 금지"를 매번 반복할 필요가 없어집니다. Claude Code가 프로젝트를 열 때마다 CLAUDE.md를 읽고 규칙을 자동으로 따릅니다.

📘 표준 도구의 자리
도구매핑
GSDSTATE.md (결정·차단 메모리) + .clinerules
Spec-Kit/speckit.constitution (프로젝트 헌법)
OpenSpecAGENTS.md (fallback agent context)
BMADYAML 설정 (페르소나별 룰)
Cursor.cursorrules
Cline.clinerules

도구마다 파일 이름·형식은 다르지만 본질은 같습니다 — "AI에게 매번 자동 입력될 200줄 컨텍스트".

2장에서 CLAUDE.md를 빈 파일로 만들었고 최소 내용 (절대 금지 + 현재 완성된 것 = 없음)만 넣었습니다. 11장에서 지금까지 진행하면서 확인된 스택·규칙·페르소나·완성된 것을 모두 담은 완성본을 만듭니다.

11-1 CLAUDE.md 10개 섹션 구조 🔗

v1.0의 4개 섹션 (기본 정보·절대 금지·코드 규칙·현재 완성된 것)을 v2에서 10개 섹션으로 확장합니다.

#섹션내용없으면 생기는 문제
1Project Overview앱 이름·기술 스택·아키텍처Claude가 엉뚱한 스택으로 코드 작성
2Tech Stack프론트·백·결제·배포 명시혼용 (StyleSheet+NativeWind 등)
3Critical Constraints절대 금지 사항 (스타일·보안·파일)API 키 노출, 임의 파일 수정
4Code Style파일 길이·타입·에러 처리컴포넌트 500줄, 타입 없는 코드
5Project-Specific Rules ★E5 콘텐츠 SSOT + 페르소나 규칙 + 회색지대 결정 노출페르소나 사실 환각, 회색지대 위반
6File Structure ★폴더 구조 + 파일별 책임코드 위치 불일치
7Common Commands ★자주 쓰는 명령어 모음매번 검색·반복
8Forbidden Patterns ★절대 쓰면 안 되는 패턴 (정규식 포함)반복 위반
9Compliance Checklist ★매 작업 전 자동 점검 항목규칙 망각
10Current StatePhase·완성된 것·작업 중/clear 후 이미 만든 것 다시 만들기
💡 ★ 표시 5개 섹션이 v2 추가

★ 표시된 5번~9번 섹션이 v1.0 → v2 추가입니다. 특히 5번 (Project-Specific Rules)이 E5 콘텐츠 SSOT의 자리입니다.

11-2 CLAUDE.md 완성 템플릿 (200줄 이하) 🔗

아래 템플릿을 Claude Code에게 작성 요청합니다. [대괄호] 부분만 바꾸면 됩니다.

💻 CLAUDE.md 완성 템플릿
# [앱 이름]
# 기술 스택: [스택 요약]
# 상태: 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는 200줄 이하로 유지하세요

CLAUDE.md는 매 대화마다 전체가 전송됩니다. 500줄짜리 CLAUDE.md는 200줄보다 2.5배 비쌉니다.

핵심 규칙만 남기는 원칙:

  • 3번 이상 위반된 적 있는 규칙만 남깁니다
  • 당연한 것은 쓰지 않습니다 ("친절하게 답해줘" 같은 것)
  • "Current State"는 간결하게 (한 줄 한 항목)

월 1회 정기 점검: /memories 확인 + CLAUDE.md 200줄 이하 정리.

11-3 CLAUDE.md 자동 생성 방법 🔗

직접 작성이 어려우면 Claude Code에게 요청하세요. 지금까지 만든 파일들을 참조해서 생성합니다.

💻 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파일+ 체계 완성"
11-4 E5 콘텐츠 SSOT — 처음 등장 🔗

여기가 1장에서 정의한 E5가 처음 등장하는 곳입니다. CLAUDE.md의 §5 Project-Specific Rules 섹션에 박힙니다.

💡 E5의 정의

"같은 사실을 여러 페르소나가 다른 톤으로 표현"할 때, 사실 자체는 단일 출처에서 받는 패턴입니다. 코드의 SSOT (Single Source of Truth)를 콘텐츠 영역으로 확장한 것입니다.

9개 표준 도구의 자리: 모두 "코드 명세"에 집중. 콘텐츠 영역 (페르소나 시스템·다중 톤 출력·다국어) 미점유. 사용자 책임으로 떠넘깁니다.

5파일+의 CLAUDE.md는 이 영역을 본문에 박습니다.

E5의 핵심 안전장치는 삼중입니다.

1
SSOT 인터페이스

모든 페르소나가 단일 입력 인터페이스에서 사실을 받습니다.

2
시스템 프롬프트 환각 방지

"입력에 없는 사실을 만들지 말라"를 명시합니다.

3
자동 일관성 테스트

페르소나마다 다른 출력 시 사실 일치를 자동 검증합니다.

세 안전장치가 CLAUDE.md에 명시되어 매 세션 자동 입력됩니다.

사례 1 — 줍줍의 두 탭 SSOT (B2C)

💻 CLAUDE.md §5 — 줍줍 (E5 적용) 예시
## 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 (미디어)

💻 CLAUDE.md §5 — TotalSportsView (E5 적용) 예시
## 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.tstests/persona_consistency.test.ts
E1 일관 노출"정보 제공 목적, 결과 보장 없음" 모든 곳에"Position C, 베팅 연결·픽 추천 없음" 모든 곳에
자동 정지 트리거cron/sync.ts 정지cron/publish.ts 정지
🎉 E5의 본질

두 프로젝트가 다른 도메인 (B2C 정보 앱 vs 미디어 플랫폼)인데도 같은 E5 패턴 — SSOT 인터페이스 + 톤 분리 + 환각 방지 + 자동 일관성 테스트 + E1 일관 노출.

이 패턴이 9개 표준 도구가 모두 다루지 못하는 영역입니다. 콘텐츠 SSOT는 E5의 본질입니다.

11-5 5파일+ 체계 완성 — 전체 점검 🔗

11장까지 왔다면 5파일이 모두 완성됐고, 5확장 5개도 모두 등장했습니다. 최종 점검을 합니다.

5파일 점검 표

파일완성 기준상태
5장SPEC.md7항목 + 성공 기준(숫자) + 수익화 + ⚖️ E1 회색지대⬜ 확인
6장PLAN.mdPhase별 DoD(숫자) + 30일 + 게이트 + 리스크 + ★ E2 페이스⬜ 확인
8장REVIEW.md15가지 체크 + 3단계 판정 + READY: YES + ⭐ E3 두 검토자⬜ 확인
9장BUILD.md일자별 5분 양식 + ⭐ E4 LogOnTable 트레이스 1~3줄⬜ 확인
11장CLAUDE.md10 섹션 + 200줄 이하 + ⭐ E5 콘텐츠 SSOT⬜ 확인

5확장 점검 표

확장박힌 위치등장 챕터상태
E1 회색지대SPEC.md § 회색지대 결정5장⬜ 확인
E2 1인 페이스PLAN.md (시간 갭·게이트 휴식·R4)6장⬜ 확인
E3 두 검토자REVIEW.md (12건 4+6+2 패턴)8장⬜ 확인
E4 LogOnTableBUILD.md (일자별 트레이스)9장⬜ 확인
E5 콘텐츠 SSOTCLAUDE.md §5 Project-Specific Rules11장⬜ 확인

5파일+ 체계 완성 검증

💻 새 세션에서 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파일+ 체계 완성
🎉 책 본문 자체가 큰 LogOnTable

이 장의 마지막 메시지: 1탄·2탄·3탄 책 본문 자체가 큰 LogOnTable입니다. 책을 정독하면 "내가 따라할 수 있는 결정 패턴 + 5파일+ 사이클 + 5확장 적용"이 손에 들립니다.

책을 펼친 시점부터 자유 창작 가능 수준까지의 학습 경로가 1탄·2탄·3탄·권7로 이어집니다.

📌 11장 정리
  • 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 / OpenSpec AGENTS.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파일+의 토대 위에서 작동합니다. 토대가 단단하면 그 위가 단단합니다.

📘
1탄 도우미
질문하기 OK
안녕하세요! CLAUDE.md와 E5 콘텐츠 SSOT에 대해 무엇이든 물어보세요. 본문에서 찾아 답변해드릴게요. 👇