msbaek-tdd — Claude Code TDD Plugin

Java/Spring Boot 프로젝트를 위한 TDD 워크플로우 Claude Code 플러그인입니다.

Kent Beck의 TDD 원칙을 기반으로, 요구사항(도메인 규칙 + User Story) 작성부터 Gherkin Scenario, Red-Green-Blue 사이클, Cucumber 인수 테스트, Composed Method 지향 리팩토링까지 체계적인 테스트 주도 개발을 지원합니다.

전체 워크플로우 지도 (발표용 시각화) → /tdd 진입부터 계획·구현 파이프라인, 기어별 스킬 라우팅, 독립 진입점까지 한 장으로.

아키텍처 지도 (인터랙티브 HTML) → 스킬 27개·에이전트 9개·정본 references 15개를 실제 코드 스캔 기반으로 — 라이프사이클 흐름 탭과 스킬↔에이전트 의존 그래프 탭, 노드 hover/클릭으로 상세 확인.

설치

방법 1: Claude Code CLI에서 직접 설치

# 1. Marketplace 등록
/plugin marketplace add msbaek/msbaek-claude-plugins

# 2. 플러그인 설치
/plugin install msbaek-tdd@msbaek-claude-plugins

# 3. 설치 확인
/plugin list

방법 2: 팀 프로젝트에 설정 (자동 설치)

프로젝트 루트의 .claude/settings.json에 아래 내용을 추가하면, 팀원이 해당 프로젝트에서 Claude Code를 실행할 때 자동으로 플러그인 설치 안내를 받습니다.

{
  "extraKnownMarketplaces": {
    "msbaek-claude-plugins": {
      "source": {
        "source": "github",
        "repo": "msbaek/msbaek-claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "msbaek-tdd@msbaek-claude-plugins": true
  }
}

요구사항

• Claude Code CLI (최신 버전 권장)
• Java 17+ / Spring Boot 3.x 프로젝트 (web-app 유형)
• Gradle 또는 Maven 빌드 시스템
• 커밋 표준 파일 — RGB 커밋이 참조하는 reviewable-commits.md 표준. 프로젝트 docs/reviewable-commits.md 또는 ~/.claude/docs/reviewable-commits.md 중 하나에 두면 된다. 없으면 아래 "커밋 표준" 섹션의 전문을 복사해 생성하라.

두 가지 사용 방식

이 플러그인은 명시적 호출과 암묵적 적용 두 가지로 쓸 수 있습니다. 숙련도에 따라 골라 쓰거나 섞어 쓰면 됩니다.

초보자 — 조금 느리더라도 명시적으로

TDD가 익숙하지 않다면 슬래시 커맨드로 명시적으로 호출하는 편이 낫습니다. 단계를 건너뛰지 않게 강제되고, 각 단계에서 무엇을 왜 하는지 스킬 문서가 안내하기 때문입니다.

/tdd general com.example.bowling.BowlingGame   # 1. 프로젝트 생성
/tdd-plan                                       # 2. 요구사항 → Gherkin → test 목록
/tdd-rgb --gear=low                             # 3. 매 단계(R/G/B)마다 검토

• low 기어를 쓰면 Red·Green·Blue 각 단계 후 멈춰서 확인할 수 있습니다 — 느리지만 TDD 리듬이 몸에 익습니다
• 한 단계씩 눈으로 확인하면서 "실패하는 테스트 → 최소 구현 → 정리"의 순서가 왜 중요한지 체감하게 됩니다

각 커맨드의 상세 옵션은 사용법, 유형별 전체 흐름은 워크플로우 예시를 참고하세요.

숙련자 — 설치만 해도 이득

Java·TDD에 익숙하다면 매번 커맨드를 칠 필요가 없습니다. 설치만 해두면 Claude가 작업 맥락을 보고 적합한 스킬을 스스로 적용합니다.

• "테스트 없는 이 레거시 클래스 손보려는데" → /tdd-legacy의 안전망 절차(Characterization → Approval → Mutation)
• "이 긴 메서드 이름이 하는 일을 안 드러낸다" → /intent-revealing-names의 이름 주도 관통 리팩토링
• "인수 테스트 도입하고 싶다" → /cucumber-acceptance의 Four Layer 구축
• "이 기능 TDD로 끝까지 구현해줘" → /tdd-feature의 plan 합의 → 자율 RGB

즉, 평소처럼 자연어로 요청해도 검증된 절차와 커밋 규율이 따라옵니다.

단, 자동 적용의 범위: 핵심 워크플로우 스킬은 위처럼 자연어 요청에서 발동하지만, 선택 리팩토링 스킬 18개는 대부분 커맨드로 명시 호출해야 확실합니다(/decompose-conditional, /discover-value-object 등). 특정 기법을 태우고 싶다면 이름을 직접 부르세요.

사용법

핵심 워크플로우

/tdd — TDD 프로젝트 생성

TDD 프로젝트의 진입점입니다. 템플릿 문서와 테스트 클래스를 생성하고 진행 상태를 관리합니다.

/tdd general com.example.bowling.BowlingGame
/tdd web-app com.example.order.CreateOrder

/tdd-plan — TDD 계획 수립

요구사항, Gherkin Scenario, unit test 목록을 순서대로 작성합니다.

/tdd-plan

진행 단계:

1. 요구사항 작성 — 도메인 규칙(0층) + User Story
2. Gherkin Scenario 작성 — Happy path, 경계 조건, 예외 상황을 예제로 (Cucumber 병행 시 실행 가능한 명세가 됨)
3. Unit Test 목록 — Degenerate → Simple → General 순서로 정렬 (Gherkin 병행 시 세밀 분기만)
4. (조건부) Use Case 추가 — 복잡도가 흐름·상태에 있을 때만
5. (web-app) 인수 테스트 셋업 — Gherkin을 .feature + Runner로 (미구현은 @pending)
6. (web-app) Walking Skeleton — 진짜 DB(docker MySQL)까지 관통하는 최소 골격 구현

/cucumber-acceptance — Cucumber 인수 테스트 (주 검증층)

기능의 external behavior를 Cucumber 인수 테스트로 구축합니다. .feature 실행으로 문서↔코드 드리프트를 구조적으로 차단합니다.

/cucumber-acceptance

• Four Layer 축소형: Steps → Protocol Driver → SUT
• 타입 경계: 도메인 타입 ≠ DTO 타입
• 태그 기반 가역 제외 — 미구현 시나리오를 태그로 제외했다가 구현 후 복원
• 기존 JUnit 인수 테스트의 이관도 지원
• 도입 시점: 프로젝트 시작 시 또는 나중에 (tdd-plan의 Gherkin Scenario를 실행 가능한 명세로 승격)

/tdd-rgb — Red-Green-Blue 사이클

테스트 목록의 각 항목에 대해 RGB 사이클을 실행합니다.

/tdd-rgb [--gear=low|mid|high]

Red (실패하는 테스트 작성)
  ↓
Green (최소 구현으로 테스트 통과)
  ↓
Blue (Composed Method 지향 Local Tidying)
  ↓
[다음 테스트로 반복]

기어(Gears) — 검토 밀도 조절 (Kent Beck의 "driving in gears")

이론에 대한 확신에 따라 사용자 검토 지점의 밀도를 조절합니다. TDD 3법칙·한 번에 테스트 하나·테스트 삭제 금지는 모든 기어에서 동일하고, 커밋 단위는 기어를 따라 바뀝니다.

• high에서는 R/G/B 에이전트가 커밋하지 않고 git add까지만 수행하며, use case가 green이 된 뒤 오케스트레이터가 한 번 커밋합니다. 되돌림 단위가 use case로 커지는 대신 커밋 하나가 "동작하는 기능 하나"가 됩니다

• 사이클 사이에 신호(설계 안정·지루함 ↔ revert·불투명)를 점검해 기어 전환을 제안합니다 — 결정은 항상 사용자

• 인증·결제 등 폭발 반경(blast radius)이 큰 영역에서는 한 단 낮은 기어를 권장합니다

• high 기어는 완료 후 적대적 리뷰(adversarial review)가 의무 — green 스위트 + 리뷰 통과가 Definition of Done

• 폭발 반경이 큰 영역(인증·인가, 결제·금액 계산, 데이터 삭제·변경, 외부 API, 동시성)은 기어와 무관하게 완료 시 적대적 리뷰를 1회 실행합니다 — 기어는 검토 밀도를, 폭발 반경은 틀렸을 때의 비용을 정하는 별개 축입니다

• 기어 상태는 템플릿 문서 진행 기록에 남아 세션 재개 시 복원됩니다 (--gear 생략 시 복원, 명시하면 우선)

기어별 호출 — 어떤 스킬을 쓰나

/tdd-feature — 간결 Plan → Feature 단위 자율 구현

/tdd-plan과 /tdd-rgb를 feature(use case) 단위로 묶은 상위 워크플로우입니다. 간결한 plan을 사용자와 합의한 뒤, 하나의 feature를 RGB 사이클로 끝까지 자율 구현합니다.

/tdd-feature [feature 설명 또는 plan 경로]

• Phase A (인터랙티브): 문제 정의 → 기능 분해 → 완료 조건(programmer test) 합의
• Phase B (자율): 합의 후 그 feature의 모든 test에 대해 R→G→B를 피드백 없이 끝까지 진행하고, feature(use case) 전체를 reviewable-commits 표준(Why-body)을 갖춘 커밋 하나로 남김
• WIP = 1: 한 번에 하나의 feature만. 남은 feature는 이어서 호출하거나 다른 세션에서.

/tdd-rgb는 기어가 정한 검토 지점에서 피드백을 받지만, /tdd-feature는 plan 합의 후 feature를 끝까지 자율 진행합니다.

기어 위치: /tdd-feature는 --gear를 받지 않습니다 — Phase B 자율 진행이 곧 feature 범위의 high 기어이기 때문입니다. 따라서 high의 안전장치를 동일하게 적용합니다: 시작 전 폭발 반경 점검, 시작 커밋 해시 기록, 완료 보고 전 적대적 리뷰. low·mid 검토 밀도가 필요하면 /tdd-feature 대신 /tdd-rgb --gear=low|mid를 사용하세요.

완료 보고 시 하드닝 제안(선택)을 함께 제시한다 — CRAP·DRY(빠름)·mutation(느림)을 전역 에이전트(crap4java-analyzer·dry4java-analyzer·mutate4java-runner)로 실행하는 명령을 제안만 하고, 실행 여부는 사용자가 결정한다 (CRAP·mutation은 Maven 프로젝트 한정, DRY는 무관).

/tdd-legacy — 레거시 코드 안전망 구축

테스트 없는 기존 코드의 현재 행위를 고정하는 안전망을 만들고, 개선은 기존 스킬로 넘깁니다.

/tdd-legacy <대상 클래스 FQCN 또는 파일 경로>

• 1단계 Characterization — golden master로 현재 행위 고정, SUT sabotage로 어설션 검증, scrubber로 비결정 출력 정규화
• 2단계 Approval — 조합 폭발 구간은 CombinationApprovals로 확장 (unit vs approval은 설계 품질 트레이드오프)
• 3단계 Mutation 검증 — mutate4java(있으면) 또는 PIT로 안전망 실효성 확인
• 완료 후 /tdd-tidy·/system-wide-refactoring으로 핸드오프 (개선은 범위 밖)

/tdd-tidy — 독립 Tidying

TDD 사이클 없이 git diff 기준 변경 파일을 자동 탐지하여 Composed Method 지향 Tidying Process를 실행합니다. 완료 후 적용 가능한 선택 리팩토링 기법을 제안합니다.

/tdd-tidy          # 최근 변경 파일 대상
/tdd-tidy HEAD~3   # 특정 커밋 기준

Tidying Process:

Guard Clauses → One Pile → Reorder → Normalize Symmetries
  → Chunk → Comment → Extract Variable → Split Loop → Trimming

One Pile 적용 시 항상 별도 커밋(refactor: one-pile [대상])으로 분리합니다.

/system-wide-refactoring — System-wide 리팩토링

코드를 분석하여 리팩토링 후보를 제시하고, 사용자 확인 후 별도 브랜치에서 기법별 커밋을 수행한 뒤 PR을 생성합니다.

/system-wide-refactoring          # 최근 변경 기준
/system-wide-refactoring HEAD~5   # 특정 커밋 기준

선택 리팩토링 스킬 (18개)

/tdd-tidy나 /system-wide-refactoring 완료 후 추가로 적용할 수 있는 개별 리팩토링 기법입니다.

Tidy 계열 — Local Tidying 확장 (9개)

System-wide 계열 — 구조적 리팩토링 (9개)

워크플로우 예시

General TDD — BowlingGame

# 1. 프로젝트 생성
/tdd general com.example.bowling.BowlingGame

# 2. 요구사항, Gherkin Scenario, unit test 목록 작성
/tdd-plan

# 3. RGB 사이클로 구현
/tdd-rgb

# 4. (선택) 추가 리팩토링
/tdd-tidy

Web App TDD — CreateShoppingBasket

# 1. 프로젝트 생성
/tdd web-app com.example.basket.CreateShoppingBasket

# 2. 요구사항, Gherkin Scenario, 인수 테스트 셋업, unit test 목록, Walking Skeleton 작성
/tdd-plan

# 3. RGB 사이클로 구현 (각 Green이 @pending 해제) + JPA 완성 + DSL 개선
/tdd-rgb

기존 코드 리팩토링 (TDD 없이)

# 최근 변경된 Java 파일에 Tidying Process 적용
/tdd-tidy

# 제안된 기법 중 선택하여 추가 적용
/decompose-conditional
/discover-value-object

# 구조적 리팩토링이 필요하면
/system-wide-refactoring

아키텍처

디렉토리 구조

msbaek-claude-plugins/
├── .claude-plugin/
│   └── marketplace.json              # Marketplace 카탈로그
├── msbaek-tdd/                       # TDD 플러그인
│   ├── .claude-plugin/
│   │   └── plugin.json               # 플러그인 매니페스트
│   ├── skills/
│   │   ├── tdd/                      # /tdd 오케스트레이터
│   │   ├── tdd-plan/                 # /tdd-plan 계획 수립
│   │   ├── tdd-rgb/                  # /tdd-rgb 사이클 조율 (step-wise)
│   │   ├── tdd-feature/              # /tdd-feature feature 단위 자율 구현
│   │   ├── cucumber-acceptance/      # /cucumber-acceptance 인수 테스트 구축
│   │   ├── tdd-legacy/               # /tdd-legacy 레거시 안전망 구축
│   │   ├── tdd-tidy/                 # /tdd-tidy 독립 tidying
│   │   ├── system-wide-refactoring/  # /system-wide-refactoring
│   │   ├── decompose-conditional/    # Tidy 계열 (9개)
│   │   ├── consolidate-conditional/
│   │   ├── replace-temp-with-query/
│   │   ├── extract-method-object/
│   │   ├── naming-process/
│   │   ├── intent-revealing-names/
│   │   ├── lift-up-conditional/
│   │   ├── introduce-assertion/
│   │   ├── replace-loop-with-pipeline/
│   │   ├── replace-conditional-with-poly/  # System-wide 계열 (9개)
│   │   ├── discover-value-object/
│   │   ├── introduce-parameter-object/
│   │   ├── first-class-collection/
│   │   ├── encapsulate-collection/
│   │   ├── separate-query-modifier/
│   │   ├── explicit-parameters/
│   │   ├── introduce-special-case/
│   │   └── segregate-functional-core/
│   └── agents/
│       ├── tdd-red.md                # Red phase 전문 에이전트
│       ├── tdd-green.md              # Green phase 전문 에이전트
│       ├── tdd-blue.md               # Blue phase 전문 에이전트
│       ├── tdd-domain-modeler.md     # Plan 단계 1 — 도메인 규칙(0층) + User Story 초안
│       ├── tdd-example-designer.md   # Plan 단계 2 — Gherkin 핵심 예시 + 경계 조건 5종 스캔
│       ├── tdd-test-list.md          # Plan 단계 3 — Unit Test 목록, Degenerate→General
│       ├── tdd-plan-critic.md        # Plan 교차검증 — 정본 부재·모순·중복 탐지 (읽기 전용)
│       ├── tdd-acceptance-builder.md # Web App E-1 — .feature + Four Layer 구축/이관
│       ├── tdd-skeleton-builder.md   # Web App E-2 — Walking Skeleton + 영속성 경계 확정
│       └── references/
│           └── tidying-process.md    # tdd-blue가 참조하는 Tidying 절차 정본
├── README.md
└── PUBLISHING-GUIDE.md               # Marketplace 배포 가이드

아키텍처 지도 (인터랙티브)

전체 스킬 27개·에이전트 9개·정본 references 15개를 한눈에 보려면 docs/architecture-map.html을 열어보세요 (GitHub 클론 없이 바로 렌더링됩니다). 로컬에서는 open docs/architecture-map.html.

• 탭 ① 라이프사이클 흐름 — 사용자 관점. /tdd-plan-input부터 RGB·하드닝 제안까지 전체 흐름을 단계별로 보여줍니다.
• 탭 ② 의존 그래프 — 유지보수 관점. 스킬→에이전트 위임, 스킬/에이전트→정본 references 참조를 실제 파일 스캔 결과대로 표시합니다.
• 노드를 클릭하면 오른쪽에 호출법·model·tools·위임 대상이 표시됩니다.
• 갱신 규칙: 스킬·에이전트·references 추가/삭제 시 이 HTML 파일도 함께 갱신합니다 (파일 상단 주석 참조).

Skills과 Agents 관계

/tdd (오케스트레이터)
 ├── 프로젝트 생성 및 상태 관리
 ├── /tdd-plan 안내
 └── /tdd-rgb 안내

/tdd-plan (계획 수립 — 각 단계 초안은 에이전트, 승인은 메인)
 ├── tdd-domain-modeler agent  → 요구사항 초안 — 도메인 규칙(0층) + User Story
 ├── tdd-example-designer agent → Gherkin Scenario 초안 (경계 조건 5종 스캔 포함)
 ├── tdd-test-list agent       → Unit Test 목록 초안 (Degenerate→General)
 ├── tdd-plan-critic agent     → §1~§3 교차검증 (정본 부재·모순·중복, 읽기 전용)
 └── (조건부) Use Case 추가 — 메인이 직접 작성

/cucumber-acceptance (인수 테스트 구축 — 대상 파악은 메인, 구축은 에이전트 위임)
 └── tdd-acceptance-builder agent → .feature + Four Layer(Steps→Driver→SUT),
     태그 기반 가역 제외, 기존 JUnit 인수 테스트 이관, 완료 후 직접 커밋

Web App 단계 E-2: Walking Skeleton
 └── tdd-skeleton-builder agent → real+thinnest 관통 슬라이스, OSIV·트랜잭션 경계·
     LAZY·DTO 확정, save() 누출 가드(실패 주입 검증), 완료 후 직접 커밋

/tdd-legacy (레거시 안전망)
 ├── Characterization (sabotage 검증 + scrubber)
 ├── Approval (CombinationApprovals)
 └── Mutation 검증 (mutate4java/PIT) → tdd-tidy·system-wide-refactoring 핸드오프

/tdd-rgb (사이클 조율 — 기어가 검토 밀도 결정, 기본 low = 매 단계 피드백)
 ├── tdd-red agent   → 실패하는 테스트 작성
 ├── tdd-green agent → 최소 구현으로 통과
 └── tdd-blue agent  → Composed Method 지향 Local Tidying Process

/tdd-feature (feature 단위 자율 구현)
 ├── Phase A: 간결 plan 합의 (인터랙티브)
 └── Phase B: feature 끝까지 자율 (tdd-red/green/blue 재사용, reviewable 커밋)

/tdd-tidy (독립 tidying)
 ├── git diff로 변경 파일 자동 탐지
 ├── tdd-blue agent  → Local Tidying Process 독립 실행
 └── 완료 후 선택 리팩토링 기법 제안

/system-wide-refactoring (구조적 리팩토링)
 ├── 코드 분석 → 리팩토링 후보 제시
 ├── 별도 브랜치에서 기법별 커밋
 ├── PR 생성
 └── 완료 후 선택 리팩토링 기법 제안

선택 리팩토링 스킬 (18개)
 ├── Tidy 계열 (9개): decompose-conditional, consolidate-conditional,
 │   replace-temp-with-query, extract-method-object, naming-process,
 │   intent-revealing-names, lift-up-conditional, introduce-assertion,
 │   replace-loop-with-pipeline
 └── System-wide 계열 (9개): replace-conditional-with-poly,
     discover-value-object, introduce-parameter-object, first-class-collection,
     encapsulate-collection, separate-query-modifier, explicit-parameters,
     introduce-special-case, segregate-functional-core

전문 에이전트

관측 계층 (에이전트 호출 로그)

9개 에이전트(RGB 3개 + Plan Phase 4개 + Web App E-1·E-2 2개) 호출을 hooks/observe-agent-start.sh(PreToolUse)· observe-agent-end.sh(PostToolUse) 쌍이 토큰 비용 0으로 기록한다. 에이전트 자신의 컨텍스트를 전혀 쓰지 않고, 대상 프로젝트의 .claude/tdd-observability/agent-log.jsonl에 append-only로 남긴다.

{"ts":"2026-08-13T12:28:04Z","session_id":"...","agent":"msbaek-tdd:tdd-domain-modeler","description":"...","duration_s":8,"success":true}

담는 필드는 신뢰성 있게 얻을 수 있는 것만이다 — 에이전트 이름·설명·소요 시간(초)·성공 여부. 토큰 수(input/output/context)는 PostToolUse hook 입력에 없고, 서브에이전트가 별도 격리 컨텍스트라 메인 세션 transcript로도 신뢰성 있게 얻을 수 없어 의도적으로 비워둔다 (없는 데이터를 지어내지 않는다).

이 로그로 답할 수 있는 질문:

# 에이전트별 호출 횟수
jq -r '.agent' .claude/tdd-observability/agent-log.jsonl | sort | uniq -c | sort -rn

# 실패(success=false) 기록만
jq 'select(.success == false)' .claude/tdd-observability/agent-log.jsonl

# 소요 시간 추세(느려지는 에이전트 찾기)
jq -r '[.ts, .agent, .duration_s] | @tsv' .claude/tdd-observability/agent-log.jsonl

대상 프로젝트의 .gitignore에 .claude/tdd-observability/를 추가해 운영 텔레메트리를 커밋 대상에서 제외할 것을 권장한다.

핵심 원칙

• Three Laws of TDD — 실패하는 테스트 없이 프로덕션 코드를 작성하지 않음
• Test Addition Rule — Degenerate(특수)에서 General(일반)으로 점진적 진행
• Programmer Test (FIRST) — Fast, Isolated, Deterministic, Predictive, Specific
• Micro Cycle — 각 단계는 2-3분 이내, 빠른 피드백
• 사용자 피드백 대기 — 기어가 정의하는 검토 지점에서 반드시 사용자 승인을 받고 진행 (기본 low 기어 = 각 단계 완료 후)

Prompt Contracts

모든 Skill과 Agent 문서에 Prompt Contracts 프레임워크의 4섹션 구조를 적용합니다:

커밋 표준 (reviewable-commits)

이 플러그인의 RGB 커밋(test:/feat:/refactor:)은 하나의 커밋 표준을 단일 출처(SSoT)로 참조합니다. 스킬·에이전트는 형식을 재기술하지 않고 경로(docs/reviewable-commits.md → 없으면 ~/.claude/docs/reviewable-commits.md)로만 가리키므로, 규칙이 바뀌어도 표준 파일 1곳만 고치면 됩니다.

배포받은 분(distributee) 설치 방법: 아직 자신의 커밋 표준이 없다면, 아래 전문을 ~/.claude/docs/reviewable-commits.md(전역) 또는 프로젝트 docs/reviewable-commits.md(프로젝트별)에 저장하세요. 이미 자신의 표준이 있으면 같은 경로에 두기만 하면 이 플러그인이 그것을 사용합니다.

아래는 작성자(@msbaek)의 개인 ~/.claude/docs/reviewable-commits.md **사본(snapshot)**입니다. 원본이 갱신되면 이 사본도 함께 갱신됩니다.

# Reviewable Commits & PRs — 의도 전달 표준 (SSoT)

> `/commit`(forward·작은 단위), `reconstruct-commits`(backward·히스토리 교정),
> `/compose-pr`(PR 텍스트 종합) **세 도구가 공유하는 단일 body 표준**이다.

## 핵심 원칙 — Why를 박제하라

**메시지·PR은 What이 아니라 Why를 전달한다.**

- **What**(무엇을 바꿨나)은 diff가 이미 보여준다 → 메시지에서 반복하지 마라.
- 남길 것 셋:
  - **Why** — 이 변경이 왜 필요한가, 무엇을 해결하나.
  - **버린 대안** — 고려했으나 배제한 접근과 그 이유 (있을 때).
  - **결정 순서(추론)** — 어떤 이론·근거로 이 경로를 택했나.

### 같은 diff, 다른 Why — 의도 구분 예시

`null` 체크 한 줄은 두 경우에 What이 똑같이 보이지만 Why가 정반대다. 메시지에
의도를 안 남기면 리뷰어가 옳은지 판단할 수 없다.

```java
// "없음 = 예외" — 없으면 안 되는 상황
if (user == null) throw new UserNotFoundException(orderId);
// → FK로 보장되는 값이라 null은 데이터 무결성 위반 신호
```
```java
// "없음 = 값" — 없는 게 정상
if (avatar == null) avatar = Avatar.DEFAULT;
// → 아바타 부재는 정상 상태, null을 기본값으로 대체
```

## Acceptance Criterion (이 표준의 합격선)

> PR 텍스트 + "Files changed"만 가진 리뷰어가, 각 변경에 대해
> ⓐ 왜 했는지 ⓑ 무엇을 배제했는지 ⓒ 어떤 추론 순서로 도달했는지를 말할 수 있다.

## 커밋 메시지 형식

```
type(scope): subject (50자 이내, 한국어, 의도 표현 — 왜 우선)

<Why — 이 변경이 왜 필요한가 / 무엇을 해결하나. 72자 줄바꿈>
<버린 대안 — 배제한 접근과 그 이유 (있을 때만)>

[Decision-Log: 한 줄 요약]   # 선택 — 결정 로그 trailer
```

- type: `feat`/`fix`/`docs`/`style`/`refactor`/`test`/`chore`.
- body는 항목 수에 집착하지 말고 **Why가 복원되는 데 필요한 만큼**. 사소한 변경은 한 줄도 OK.
- **작은 단위 원칙**: 한 커밋 = 하나의 결정 + 그 검증.
- 한글 메시지는 **임시 파일 + `git commit -F`** (heredoc·`-m "한글"` 금지 — 깨짐).

## 4-Channel 모델 — 무엇을 어디에 남기나

| 채널 | 담는 것 | 안 담는 것 |
|------|---------|-----------|
| **테스트 코드** | 인수조건·엣지 케이스, "이 동작이 왜 중요한가" | 구현 상세 |
| **커밋 메시지** | 이 커밋 **한 개 결정**의 Why + 버린 대안 | 여러 결정 뭉치, What 나열 |
| **PR 메시지** | 커밋 내러티브 **종합** + 결정 로그 + 리뷰 가이드 | 커밋별 What 재나열 |
| **코드 주석** | 코드로 표현 못 하는 근거(왜 이 값·이 순서) | What 재진술 |

라이선스

MIT