msbaek-tdd — Claude Code TDD Plugin

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

Kent Beck의 TDD 원칙을 기반으로, 앵커 작성(규칙 + 예제 검산표 + Gherkin)부터 Red-Green-Blue 사이클, Cucumber 인수 테스트, Composed Method 지향 리팩토링까지 체계적인 테스트 주도 개발을 지원합니다.

플러그인	설명
msbaek-tdd	Java + Spring Boot TDD workflow with requirements input drafting, RGB cycle, feature-level autonomous implementation, Cucumber acceptance testing, local tidying, system-wide refactoring, and 18 optional refactoring skills

현재 버전은 msbaek-tdd/.claude-plugin/plugin.json이 정본입니다(README에는 버전을 적지 않습니다).

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

아키텍처 지도 (인터랙티브 HTML) → 스킬 28개·에이전트 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 빌드 시스템
• 커밋 표준 파일 — 플러그인에 동봉(msbaek-tdd/references/reviewable-commits.md). 별도 생성 불필요. 프로젝트별로 바꾸려면 docs/reviewable-commits.md를 두면 우선 적용된다.

두 가지 사용 방식

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

방식	어떻게	누구에게
명시적 호출	/tdd-plan, /tdd-rgb --gear=low처럼 슬래시 커맨드로 직접 지정	TDD·Java가 아직 낯선 개발자
암묵적 적용	설치만 해두면, 작업이 스킬에 맞을 때 Claude가 알아서 해당 스킬을 적용	TDD·Java에 익숙한 개발자

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

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

/tdd general com.example.bowling.BowlingGame   # 1. 프로젝트 생성
/tdd-plan                                       # 2. 앵커 작성(규칙+예제+미확정) → 리뷰
/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

유형	설명	단계
general	일반 TDD	앵커 작성 → RGB 사이클 (2단계)
web-app	Web App TDD	앵커 작성 → 인수 셋업(.feature) → Walking Skeleton → RGB 사이클 → JPA 완성 → DSL → 적대적 리뷰 → 하드닝 게이트 (8단계)

/tdd-plan — TDD 계획 수립 (Spec Anchored)

얇은 앵커 문서(규칙 + 예제 검산표 + 미확정)를 작성합니다 — CancelOrder급 도메인 기준 100줄 이하가 목표입니다. 시나리오의 실행되는 정본은 .feature이고 (/cucumber-acceptance), 구현 중 배움은 앵커에 먼저 반영됩니다(msbaek-tdd/references/anchor-update.md).

Spec Anchored 원칙: 앵커는 한 번 쓰고 끝나는 문서가 아니라 구현 내내 살아 있는 문서입니다. 구현 중 규칙·예제와 어긋나는 배움을 발견하면 코드부터 고치지 않고 앵커를 먼저 갱신한 뒤, 앵커 갱신과 코드 변경을 같은 커밋에 담습니다 — 규칙이 바뀌는 배움만 사용자에게 질문하고 나머지는 배움 로그에 자율 기록합니다. 정본은 msbaek-tdd/references/anchor-update.md.

/tdd-plan

기본 플로우 (경량):

1. tdd-anchor-drafter 에이전트 1회 호출 — 규칙·예제 검산표·미확정을 채우고 Gherkin DRY 자가 점검(중복·값 변형·유사 표현 정규화)을 거친 .feature용 Gherkin 초안을 반환
2. 사용자 리뷰 1회 — 앵커 내용 + Gherkin 초안 + DRY 점검 결과 + 미확정 질문을 한 번에 제시
3. (web-app) E-1 인수 테스트 셋업 — /cucumber-acceptance 호출, 승인된 Gherkin이 .feature가 됨 (미구현 시나리오 @pending)
4. (web-app) E-2 Walking Skeleton — tdd-skeleton-builder 위임, 진짜 DB(docker MySQL)까지 관통하는 최소 골격 구현

--full 플로우 (high-stakes·대형·다팀, 사용자 명시 선택 시): tdd-domain-modeler → tdd-example-designer → tdd-test-list → tdd-plan-critic 을 단계별 승인으로 진행합니다. 정본은 skills/tdd-plan/references/full-plan.md.

/tdd-plan --full

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

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

/cucumber-acceptance

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

/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법칙·한 번에 테스트 하나·테스트 삭제 금지는 모든 기어에서 동일하고, 커밋 단위는 기어를 따라 바뀝니다.

기어	검토 지점	커밋 단위	대응 상황
low (기본)	Red 후 · Green 후 · Blue 후	R/G/B 각각 별도 커밋	확신 없음, 낯선 도메인, 학습 목적
mid	테스트 1개의 R→G→B 완료 후 1회	테스트 1개의 RGB가 한 커밋	유사 문제 경험, 이론을 빠르게 확보할 것으로 기대
high	전체 목록 완료 + 적대적 리뷰 통과 후 1회	use case를 3-phase로 나눠 커밋: 전체 Red→test:, 전체 Green→feat:, 전체 Blue→refactor:	이론이 상용구(boilerplate) 수준

• high에서는 R/G/B 에이전트가 커밋하지 않고 git add까지만 수행합니다. 테스트 단위가 아니라 phase 단위로 use case 전체를 관통합니다 — 모든 test의 Red를 다 마친 뒤 커밋(test:), 모든 test의 Green을 채운 뒤 커밋(feat:), 마지막에 Blue를 한 번 적용한 뒤 커밋(refactor:, tidying 불필요 시 생략). 테스트 단위 되돌림은 여전히 불가능하지만 phase 단위(구현만, 또는 tidying만) 되돌림은 가능해졌습니다

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

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

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

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

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

• 전체 완료 시 기어와 무관하게 하드닝 제안(선택)이 최종 검토 보고에 함께 제시됩니다 — crap4java·dry4java·mutate4java로 실행하는 명령을 제안만 하고, 실행 여부는 사용자가 결정합니다. 네 도구(외부 3종 + 동봉 gherkin-mutate)는 선택 사항이며 설치 방법은 msbaek-tdd/references/hardening-tools.md에 있습니다(미설치 도구의 제안은 생략). 블록 안의 순서는 비용순이 아니라 파이프라인순입니다: ① CRAP·DRY로 정리할 곳 찾기 → ② /system-wide-refactoring으로 정리 → ③ 정리된 코드에 mutation → ④ .feature가 있으면 인수 테스트 연결 확인(gherkin-mutate, 값 1개당 빌드 1회). ②의 메서드 추출이 뮤테이션 지점을 바꾸므로 ③은 ② 다음에 옵니다 (Uncle Bob의 Coder→Cleaner→Hardener 파이프라인과 같은 순서). (v1.40.0부터 — 이전에는 /tdd-feature에만 연결돼 있었습니다)

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

상황	기어	호출
낯선 도메인·학습 목적	low	/tdd-rgb --gear=low
유사 경험 있음, 설계 안정화 중	mid	/tdd-rgb --gear=mid
이론 명확, 테스트 목록 전체 자율	high	/tdd-rgb --gear=high
이론 명확, feature 하나 plan 합의 후 자율	high	/tdd-feature

/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에 대해 전체 Red→전체 Green→전체 Blue 3-phase로 피드백 없이 끝까지 진행하고, feature(use case) 전체를 reviewable-commits 표준(Why-body)을 갖춘 **phase별 커밋(최대 3개: test:/feat:/refactor:)**으로 남김
• 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를 사용하세요.

완료 보고 시 하드닝 제안(선택)을 함께 제시한다 — crap4java·dry4java·mutate4java로 실행하는 명령을 제안만 하고(설치는 msbaek-tdd/references/hardening-tools.md), 실행 여부는 사용자가 결정한다. 순서는 ① CRAP·DRY → ② /system-wide-refactoring → ③ mutation → ④ .feature의 값 연결 확인 (/tdd-rgb와 동일한 정본을 참조하므로 위 설명이 그대로 적용된다. CRAP·mutation은 Maven 프로젝트 한정, DRY와 gherkin-mutate는 무관).

/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 [대상])으로 분리합니다.

/tdd-profile — 세션 병목 분석

TDD 세션이 끝난 뒤 "어느 단계·에이전트에서 시간과 토큰이 많이 들었나"를 세션 transcript로 집계하고, 병목 3개 이내와 model/effort 조정안을 보고합니다. 코드를 바꾸지 않습니다.

/tdd-profile                       # 현재 프로젝트의 최근 TDD 세션
/tdd-profile ~/.claude/projects/<slug>/<session>.jsonl

내부는 bin/tdd-profile.py이며, 단계 경계는 Skill 호출입니다.

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

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

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

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

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

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

스킬	설명
/decompose-conditional	복잡한 if/then/else의 조건식과 분기를 의미 있는 메서드로 추출
/consolidate-conditional	동일한 결과를 내는 여러 조건문을 하나로 통합하고 의미 있는 메서드로 추출
/replace-temp-with-query	임시 변수를 메서드 호출로 치환하여 중복 제거 및 가독성 향상
/extract-method-object	지역 변수가 얽힌 거대 메서드를 별도 클래스(Method Object)로 추출
/naming-process	Arlo Belshee의 6단계 네이밍 프로세스로 코드 가독성 향상
/intent-revealing-names	긴 메서드 하나를 grouping·comment로 정돈해 책임을 드러낸 뒤, 6단계 네이밍으로 extract를 유도하며 관통 리팩토링
/lift-up-conditional	여러 곳에 중복된 조건문을 상위로 끌어올려 중복 제거
/introduce-assertion	암묵적 가정을 Assert/Validate로 명시하여 가정 위반 시 즉시 발견
/replace-loop-with-pipeline	명령형 루프를 Stream API/Collection Pipeline으로 변환

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

스킬	설명
/replace-conditional-with-poly	반복되는 switch/if-else 조건문을 다형성으로 치환
/discover-value-object	Primitive Obsession 제거 — primitive 타입을 Value Object로 치환
/introduce-parameter-object	반복되는 파라미터 그룹을 객체로 치환 (Preserve Whole Object 포함)
/first-class-collection	컬렉션과 관련 로직을 전용 클래스로 추출
/encapsulate-collection	컬렉션 getter의 내부 상태 노출 방지 (unmodifiable + add/remove)
/separate-query-modifier	값 반환과 부수효과가 혼재된 메서드를 Query와 Modifier로 분리 (CQS)
/explicit-parameters	암묵적 의존성(전역변수, 클래스 필드)을 명시적 파라미터로 전환
/introduce-special-case	반복되는 null 검사를 Special Case(Null Object) 클래스로 대체
/segregate-functional-core	순수 비즈니스 로직(Functional Core)과 부수효과(Imperative Shell)를 분리

워크플로우 예시

General TDD — BowlingGame

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

# 2. 앵커 작성(규칙+예제 검산표+미확정) → 사용자 리뷰
/tdd-plan

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

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

Web App TDD — CreateShoppingBasket

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

# 2. 앵커 작성 → 리뷰 → 인수 테스트 셋업(E-1) → Walking Skeleton(E-2)
/tdd-plan

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

전체 절차를 하드닝 게이트까지 포함해 그리면 다음과 같습니다:

flowchart TD
    A["0. 원천 자료 준비<br>/tdd-plan-input (선택)"] --> B["/tdd-plan"]
    subgraph PLAN["/tdd-plan — 기본은 앵커 1회 + 리뷰 1회, --full은 단계별 승인"]
        B --> C["tdd-anchor-drafter 에이전트 1회<br>규칙 + 예제 검산표 + 미확정 + Gherkin 초안"]
        C --> D["사용자 리뷰 1회<br>앵커 + Gherkin 초안 + DRY 점검 + 미확정 질문"]
        D --> FULL{"--full 선택?"}
        FULL -->|"아니오 (기본)"| G["단계 E-1. 인수 테스트 셋업<br>/cucumber-acceptance → .feature + Runner"]
        FULL -->|"예 (high-stakes)"| C1["tdd-domain-modeler"]
        C1 --> C2["tdd-example-designer"]
        C2 --> C3["tdd-test-list"]
        C3 --> C4["tdd-plan-critic 적대적 검증"]
        C4 --> G
        G --> H["단계 E-2. Walking Skeleton<br>tdd-skeleton-builder"]
    end
    H --> I{"구현 방식"}
    I -->|"feature 단위 자율<br>(간결 plan 직접 합의)"| J["/tdd-feature<br>Red→Green→Blue 전체, 3커밋"]
    I -->|"단계별 검토<br>(plan 문서 기반)"| K["/tdd-rgb --gear=low|mid|high"]
    J --> M["web-app-finish<br>인수 테스트 전체 green · JPA 완성 · DSL 개선"]
    K --> M
    M --> R["완료 보고 + 적대적 리뷰<br>(high 기어 또는 폭발 반경 high-stakes 시)"]
    subgraph HG["하드닝 게이트 (제안만 — 실행은 사용자 결정)"]
        R --> S["① 정리할 곳 찾기<br>crap4java (복잡도×커버리지)<br>dry4java (구조적 중복)"]
        S --> T["② 구조 정리<br>/system-wide-refactoring"]
        T --> U["③ 테스트 강화<br>mutate4java (대표 파일 1개)"]
        U --> V["④ 인수 테스트 연결 확인<br>gherkin-mutate (.feature가 있을 때)"]
    end
    V --> L{"다음 feature?"}
    L -->|있음| I
    L -->|없음| Z["완료"]

• 하드닝 게이트의 순서는 비용순이 아니라 파이프라인순입니다 — ②의 구조 정리가 뮤테이션 지점을 바꾸므로 ③은 ② 다음에, ④는 마지막에 옵니다. 적용 조건·제안 블록 형식의 정본은 skills/tdd-rgb/references/hardening-gate.md입니다.
• CRAP·mutate4java는 Maven 전용이므로 Gradle 프로젝트에서는 ①의 DRY 점검, ②, ④(.feature가 있을 때)만 제안됩니다.
• web-app-finish가 적대적 리뷰보다 앞서는 이유: 리뷰 diff가 JPA 완성·DSL 개선까지 포함한 전체 구현을 덮어야 하기 때문입니다 (skills/tdd-rgb/references/web-app-finish.md).

기존 코드 리팩토링 (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
│   │   ├── tdd-profile/              # /tdd-profile 세션 병목 분석 (bin/tdd-profile.py)
│   │   ├── 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-anchor-drafter.md     # Plan 기본 플로우 — 앵커(규칙+예제+미확정) + Gherkin 초안
│       ├── tdd-domain-modeler.md     # Plan --full 단계 1 — 도메인 규칙(0층) + User Story 초안
│       ├── tdd-example-designer.md   # Plan --full 단계 2 — Gherkin 핵심 예시 + 경계 조건 5종 스캔
│       ├── tdd-test-list.md          # Plan --full 단계 3 — Unit Test 목록, Degenerate→General
│       ├── tdd-plan-critic.md        # Plan --full 교차검증 — 정본 부재·모순·중복 탐지 (읽기 전용)
│       ├── 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 배포 가이드

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

전체 스킬 28개·에이전트 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 (기본: 앵커 초안은 에이전트 1회, 승인은 메인 리뷰 1회)
 ├── tdd-anchor-drafter agent  → 앵커 초안 — 규칙 + 예제 검산표 + 미확정 + Gherkin 초안
 └── --full (high-stakes 선택 시, 단계별 승인)
     ├── 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 교차검증 (정본 부재·모순·중복, 읽기 전용)

/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 독립 실행
 └── 완료 후 선택 리팩토링 기법 제안

/tdd-profile (세션 사후 분석 — tdd-rgb·tdd-feature 완료 보고가 안내)
 ├── bin/tdd-profile.py → transcript + subagents/ 집계 (Skill 호출 = 단계 경계)
 └── 병목 3개 이내 + model/effort 조정안

/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

전문 에이전트

에이전트	역할	핵심 원칙
tdd-red	실패하는 테스트 작성	TDD 1법칙: "Write NO production code except to pass a failing test"
tdd-green	최소 구현으로 테스트 통과	TPP (Transformation Priority Premise), Make-it-Work 전략 (Obvious / Fake it / Triangulation)
tdd-blue	Composed Method 지향 리팩토링	Tidying Process: Guard Clauses → One Pile → Reorder → Normalize Symmetries → Chunk → Comment → Extract Variable → Split Loop → Trimming
tdd-anchor-drafter	Plan 기본 플로우 — 앵커(규칙+예제 검산표+미확정) + Gherkin 초안 1회 작성	산문 계층·Gherkin 사본 금지, Gherkin DRY 자가 점검, 배움 반영은 references/anchor-update.md (앵커 100줄 이하 목표는 /tdd-plan GOAL)
tdd-domain-modeler (--full 전용)	Plan 단계 1 초안 — 도메인 규칙(0층) + User Story	검산 전개 = 숫자의 정본, So that이 비면 작업 지시
tdd-example-designer (--full 전용)	Plan 단계 2 초안 — Gherkin 핵심 예시	경계 조건 5종 스캔(특히 집계 경계), Specification by Example
tdd-test-list (--full 전용)	Plan 단계 3 초안 — Unit Test 목록	Gherkin과 두 계층 중복 금지, Degenerate→General 도출 절차
tdd-plan-critic (--full 전용, 읽기 전용)	Plan 문서 교차검증	§1~§3 동시 대조, 정본 부재·모순·집계 경계 누락 탐지, 재현 시나리오 기반 보고
tdd-acceptance-builder	Web App E-1 — 인수 테스트 구축/이관	Four Layer(Protocol Driver 분리), 인수 조건에 없는 쓰기 API를 지어내지(invent) 않음, 완료 후 직접 커밋
tdd-skeleton-builder	Web App E-2 — Walking Skeleton	real≠thinnest 두 축, OSIV 항상 off, 가드가 경계보다 먼저, 실패 주입으로 가드 비공허성 확인

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

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}

담는 필드는 hook 입력에서 신뢰성 있게 얻을 수 있는 것만이다 — 에이전트 이름·설명·소요 시간(초)·성공 여부. 토큰 수는 PostToolUse hook 입력에 없으므로 여기서는 비워두고, 아래 tdd-profile.py가 사후에 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/를 추가해 운영 텔레메트리를 커밋 대상에서 제외할 것을 권장한다.

병목 프로파일 — bin/tdd-profile.py

"어느 단계에서 시간·토큰이 많이 드는가"는 hook 로그가 아니라 세션 transcript로 답한다. Claude Code는 메인 컨텍스트의 API 턴마다 usage(input/output/cache)를, 서브에이전트는 <session>/subagents/agent-*.jsonl(+ .meta.json: agentType·model)을 남긴다. 스크립트는 이 둘을 읽어 Skill 호출을 단계 경계로 삼아 단계별로 집계한다 (의존성 없음, 읽기 전용).

# 세션 하나
python3 ~/.claude/plugins/cache/msbaek-claude-plugins/msbaek-tdd/<ver>/bin/tdd-profile.py \
  ~/.claude/projects/<cwd-slug>/<session-id>.jsonl

# 프로젝트 디렉터리를 주면 msbaek-tdd 활동이 가장 많은 세션을 고른다
python3 .../tdd-profile.py ~/.claude/projects/-Users-me-git-my-app

# 옵션: --json (기계 판독), --idle 600 (이 초 이상 공백은 사용자 대기로 보고 wall-clock에서 제외)

출력 절: 단계별 wall/turns/토큰/도구/에이전트 표 → 에이전트별(모델·시간·토큰) → 컨텍스트가 가장 많이 커진 턴 10개(cache+) → 단계별 실제 사용 model/effort → model·effort 제안(휴리스틱: out/turn이 작고 Edit·Bash 비율이 높으면 sonnet/medium, 출력이 길거나 설계·이력 작업이면 opus/high) → 단계별 도구 호출.

읽는 법: in(total)은 턴마다 API에 실린 컨텍스트의 합(과금 기준)이라 턴 수 × 컨텍스트 크기로 커진다 — 이 값이 큰 단계는 "턴이 많다"이지 "많이 읽었다"가 아니다. 새로 읽은 양은 cache+.

핵심 원칙

• 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섹션 구조를 적용합니다:

섹션	역할
GOAL	성공 기준을 1분 내 검증 가능하게 정의
CONSTRAINTS	Hard Rules(비협상 경계)와 Principles(설계 원칙)
OUTPUT FORMAT	작업 절차, 워크플로우, 템플릿
FAILURE CONDITIONS	"이것이 있으면 수용 불가" 목록 (가드레일)

커밋 표준 (reviewable-commits)

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

• 해석 순서: 프로젝트 docs/reviewable-commits.md가 있으면 그것을 우선(프로젝트별 오버라이드), 없으면 플러그인 동봉 파일. 별도 설치 작업은 없습니다.
• 본문 길이는 msbaek-tdd/references/commit-style.md의 간결성 규칙이 우선합니다 — 제목 1줄 + 핵심 bullet 2~4줄(각 1줄). 표준의 Why·버린 대안 채널을 장문 서술로 풀지 않습니다.
• 자신의 표준이 이미 있으면 프로젝트 docs/reviewable-commits.md에 두면 이 플러그인이 그것을 사용합니다.

라이선스

MIT