seonghyeonkimm avatar

my-claude-code-config

Personal Claude Code settings sync - commands, skills, hooks, configuration

version
1.0.0

Install

/plugin install my-claude-code-config@my-claude-code-workflows

Run it inside Claude Code after adding the marketplace with /plugin marketplace add seonghyeonkimm/agents.

Contents

Discovered from source

Skills 11

BE TechSpec

관련 스킬: entity-object-pattern - 구현 시 반복되는 도메인 로직을 Entity Object로 그룹화하는 패턴 대응 스킬: fe-techspec - 프론트엔드 TechSpec (동일 구조, FE 관점)

BE TechSpec은 프로젝트의 백엔드 기술 구현 방향을 정의하는 문서. PRD(요구사항)와 API Spec을 기반으로 Solution, Acceptance Criteria, Test Cases를 도출한다.

문서 구조

Summary → Solution → Acceptance Criteria → Non-Functional Requirements → Functional Requirements (Given/When/Then) → Design → Component & Code - Server → Verification

전체 템플릿은 references/template.md 참조.

섹션별 작성 가이드

Summary

프로젝트 배경과 맥락. PRD/API Spec 링크 포함.

## Summary

{프로젝트 배경 1-3문장}

- **PRD**: {Notion URL}
- **API Spec**: {Swagger/OpenAPI URL} (있으면)

Solution

비즈니스 관점에서 핵심 변경사항을 요약. 기술 용어 없이 "무엇이 어떻게 바뀌는가"에 집중.

## Solution

### 핵심 변경사항

1. **{변경1}**: {설명}
2. **{변경2}**: {설명}
3. **{변경3}**: {설명}

작성 규칙:

  • 코드, 테이블명, 타입명 사용 금지
  • 사용자/비즈니스 관점에서 서술
  • 3-5개 핵심 변경사항을 번호 매기기 형식으로 나열

Acceptance Criteria

기능 동작의 최소 기준. 테스트 가능한 형태로 작성.

## Acceptance Criteria

1. {주어} 상태에서 {동작}하면 {결과}가 발생한다
2. ...
  • 측정 가능하고 검증 가능한 문장으로 작성
  • "빠르게", "잘" 같은 모호한 표현 금지
  • 핵심 API 플로우별 1개 이상

Non-Functional Requirements

SLA/SLO 기준의 시스템 요구사항.

카테고리:

  • Performance: 응답 시간 p95 < 200ms, 처리량 > N RPS
  • Reliability: 가용성 99.9%, 장애 복구 시간 (RTO/RPO)
  • Security: 인증/인가, 입력 검증, OWASP Top 10
  • Scalability: 수평 확장, DB 샤딩/파티셔닝 (해당 시)

해당 프로젝트에 관련 없는 카테고리는 생략 가능.

Functional Requirements (Given/When/Then)

테스트 케이스를 구조화된 테이블로 정의.

## Functional Requirements (Test cases / Given, When, Then)

| # | Given | When | Then |
|---|-------|------|------|
| 1 | {초기 상태/조건} | {API 호출/이벤트} | {기대 결과} |
| 2 | ... | ... | ... |

작성 팁:

  • 정상 케이스 → 에러 케이스 → 엣지 케이스 순서
  • Given은 DB/시스템 상태, When은 API 호출/이벤트, Then은 응답/상태 변경
  • Entity/Command 식별은 Design 섹션에서 수행, FR에는 테이블만 작성

Design

테스트 케이스 기반으로 백엔드 설계를 진행.

작성 순서:

  1. 데이터 모델: DB 스키마 중심 설계
    • 테이블, 컬럼, 타입, 제약조건, 인덱스 정의
    • 엔티티 간 관계 (FK, 1:N, N:M)
    • 마이그레이션 전략 (기존 데이터 변환 필요 시)
  2. Usecase: 주요 사용 시나리오 테이블 (Input → Output) 2.5. Interface Contract: API 엔드포인트 + 서비스 간 계약
    • External API: method, path, params, body, response, 상태 코드, 에러 코드
    • Internal API: 서비스 간 호출, 메시지 큐, 이벤트
    • TC 번호로 추적
  3. Module & Layer Structure: Clean Architecture (호출 흐름 + DI 주입)
    • 호출: Presentation → Application → Domain
    • 주입: Infrastructure가 Application의 Port를 구현 (DI)
    • Presentation: Controller, DTO — HTTP 진입점, UseCase 호출 (프레임워크 결합 허용, 얇게 유지)
    • Application: UseCase 조율, Port interface 정의, 트랜잭션 경계
    • Domain: Entity, Value Object, Domain Service — 외부 의존 없음
    • Infrastructure: Repository 구현체, Adapter — Port 구현, DI로 주입
  4. Usecase-Module Integration: 연결 지점 정의
  5. Optimization Checklist: TC/NFR에서 도출된 최적화 항목만 기록

데이터 모델 가이드:

  • DB 스키마(테이블/컬럼)가 Primary. Domain Entity는 비즈니스 규칙을 표현하며 스키마와 분리될 수 있다 (규칙이 없으면 생략)
  • enum/상수값은 DB enum 또는 애플리케이션 상수로 정의
  • 인덱스는 쿼리 패턴에서 도출 (FR의 When/Then에서 어떤 조회가 필요한지)
  • 마이그레이션: 기존 데이터가 있으면 zero-downtime 전략 고려

Component & Code - Server

  • Test cases 기반으로 모듈, 서비스, 레포지토리 구조 추출
  • 레이어 분리, 파일 구조, 인터페이스 정의

Verification

테스트 케이스 검증 전략.

우선순위:

  1. Integration Tests (필수): TC 기반 API 통합 테스트
  2. Unit Tests (필요 시): 복잡한 도메인 로직만
  3. E2E Tests (필요 시): 전체 API 플로우 검증

흔한 실수와 해결책

문제원인해결
AC가 모호함"빠르게", "잘" 같은 추상적 표현측정 가능한 기준 사용 (예: "p95 < 200ms")
Given/When/Then 불명확상태/호출/결과 구분 없음Given=DB 상태, When=API 호출, Then=응답+상태 변경
Test Case 누락정상 케이스만 작성에러/엣지 케이스 반드시 포함
NFR 생략선택사항이라 무시공개 API면 Performance/Security 필수 검토
Solution에 코드 포함"기술적 해결책"으로 오해비기술 요약으로 작성
스키마 과잉 설계미래 요구사항 예측YAGNI. 현재 TC에서 필요한 컬럼만
인덱스 누락쿼리 패턴 미분석FR의 When/Then에서 조회 패턴 도출 → 인덱스 결정
Controller에 비즈니스 로직레이어 책임 혼재Presentation(검증/라우팅)과 Application UseCase(조율) 분리
Infrastructure → Domain 의존Dependency Rule 위반Domain은 순수 비즈니스 규칙만. DB/프레임워크 타입 import 금지
Optimization Checklist 전부 채움RADIO 원칙 오해TC/NFR에서 도출된 항목만. "해당없음"이 대부분이어도 정상
Verification 누락선택사항으로 오인Integration Test 필수

Claude Config Patterns

.claude/ 디렉토리 내 파일 작성 시 따라야 할 패턴과 템플릿입니다.


식별 기준

대화에서 추출할 내용의 타입을 결정하는 기준입니다.

타입식별 기준예시
Agent여러 단계로 구성된 자동화 작업, 특정 도구 조합이 필요한 워크플로우"프로젝트 초기화", "배포 파이프라인"
Skill필요시 참조하는 패턴, 템플릿, 도메인 지식"API 에러 처리 패턴", "TechSpec 작성 템플릿"
Command사용자가 자주 요청하는 작업, 인자를 받아 실행되는 반복 작업"/deploy", "/test-coverage"
Rules세션 시작 시 자동 로드되어야 하는 프로젝트 지침/정책"보안 규칙", "코딩 스타일", "테스트 컨벤션"
CLAUDE.md프로젝트 개요, 구조, 주요 명령어"환경변수 추가", "디렉토리 구조"

타입 구분 플로우차트

Q: 도구(Read, Write, Bash 등)를 사용해야 하는가?
├─ Yes → Q: 사용자가 직접 호출하는가?
│         ├─ Yes → Command
│         └─ No → Agent
└─ No → Q: 세션 시작 시 자동 로드되어야 하는가?
          ├─ Yes → Rules (프로젝트 지침, 자동 로드)
          └─ No → Q: 명시적 호출 시에만 참조되는가?
                    ├─ Yes → Skill (재사용 패턴/컨벤션)
                    └─ No → CLAUDE.md (프로젝트 개요)

Rules vs Skills 선택 기준:

  • Rules: 항상 적용되어야 하는 지침 (보안, 코딩 스타일, 테스트 규칙)
  • Skills: 필요할 때만 참조하는 패턴 (템플릿, 워크플로우, 도메인 지식)

디렉토리 구조

.claude/
├── agents/           # 자동화 워크플로우 실행자
│   └── {name}.md
├── skills/           # 재사용 패턴 및 규칙 (명시적 참조)
│   └── {name}/
│       └── SKILL.md
├── commands/         # 사용자 명령어 (진입점)
│   └── {name}.md 또는 {category}/{name}.md
└── rules/            # 프로젝트 지침/정책 (자동 로드)
    ├── {name}.md
    └── {category}/   # 하위 디렉토리 지원
        └── {name}.md

Agent 템플릿

위치: .claude/agents/{name}.md

용도: 특정 도구를 사용해 자동화 작업을 수행하는 실행자

---
name: {agent-name}
description: {한 줄 역할 설명}
allowed-tools:        # 선택사항
  - Read
  - Write
  - Bash
---

# {Agent Name}

{상세 설명}

## Prerequisites
- 필요한 스킬: `{skill-name}`
- 필요한 환경: {환경 요구사항}

## Workflow

### Phase 1: {단계명}
{단계 설명}

### Phase 2: {단계명}
{단계 설명}

## Error Handling
- {에러 상황}: {대응 방법}

## Example
{사용 예시}

Agent Tools 가이드

도구용도예시
Read파일 읽기스크립트, 설정 파일 읽기
Write파일 생성JSON, 설정 파일 생성
Edit파일 수정기존 파일 일부 수정
Bash명령 실행npm, npx, 시스템 명령
Glob파일 검색패턴으로 파일 찾기
Task서브에이전트 위임다른 에이전트 호출
WebFetch웹 요청API 호출, 문서 조회
AskUserQuestion사용자 입력확인, 선택 요청

Agent 네이밍 규칙

  • kebab-case 사용: script-writer, audio-generator
  • 역할을 명확히 표현: {동작}-{대상} 패턴
  • 짧고 명확하게: 2-3 단어

Skill 템플릿

위치: .claude/skills/{name}/SKILL.md

용도: 필요시 참조하는 문서 (규칙, 패턴, 예제, 템플릿)

---
name: {skill-name}
description: {한 줄 설명}
globs:                # 선택사항: 파일 패턴에 따라 자동 활성화
  - "{glob-pattern-1}"
  - "{glob-pattern-2}"
---

# {Skill Name}

{개요 설명}

## 핵심 규칙

### 규칙 1: {규칙명}
{규칙 설명}

```{lang}
// ✅ 올바른 예시
{good example}

// ❌ 잘못된 예시
{bad example}

템플릿/스키마

{재사용 가능한 코드/구조}

흔한 실수와 해결책

문제원인해결
{문제}{원인}{해결책}

### Globs 패턴 가이드

| 패턴 | 매칭 대상 |
|------|-----------|
| `**/*.ts` | 모든 TypeScript 파일 |
| `src/**` | src 디렉토리 내 모든 파일 |
| `.claude/agents/**` | 에이전트 파일들 |
| `**/test*/**` | test가 포함된 경로 |

### Skill 네이밍 규칙

- kebab-case 사용: `remotion-patterns`, `api-error-handling`
- `{도메인}-{타입}` 패턴 권장: `video-script-rules`
- 디렉토리명 = name 필드값

---

## Command 템플릿

**위치:** `.claude/commands/{name}.md` 또는 `.claude/commands/{category}/{name}.md`

**용도:** 사용자가 `/name` 또는 `/{category}/{name}`으로 호출하는 진입점

```yaml
---
name: {command-name 또는 category/command-name}
description: {사용자에게 보여지는 설명}
arguments:
  - name: {arg-name}
    description: {인자 설명}
    required: true|false
    default: {기본값 (optional)}
allowed-tools:
  - {사용할 도구 목록}
---

# {Command Name}

{명령어 개요}

## Input
- `$ARGUMENTS.{arg-name}`: {설명}

## Execution Flow

### 1. {단계명}
{단계 설명}

### 2. {단계명}
{단계 설명}

## Example

/command-name --arg1 "value1" --arg2 value2

Command 네이밍 규칙

  • 단일 단어 또는 카테고리/이름: wrap, video/generate
  • 동사로 시작: generate, render, validate
  • 사용자 관점에서 직관적으로

Rules 템플릿

위치: .claude/rules/{name}.md (하위 디렉토리 지원)

용도: 세션 시작 시 자동 로드되는 프로젝트 지침, 코딩 컨벤션, 정책

로딩: 모든 .md 파일이 .claude/CLAUDE.md와 동일한 우선순위로 자동 로드됨

무조건 적용 규칙

Frontmatter 없이 작성하면 모든 파일 작업에 적용됩니다:

# Security Rules

## 시크릿 관리
- 환경변수 사용 필수
- .env 파일 gitignore 확인
- 하드코딩된 API 키 금지

## 인증/인가
- JWT 토큰 만료 시간 설정
- 민감한 엔드포인트에 인증 필수

조건부 적용 규칙

paths frontmatter로 특정 파일 패턴에만 적용할 수 있습니다:

참고: Skill의 globs와 동일한 glob 패턴 문법을 사용하지만, Rules에서는 paths라는 키를 사용합니다.

---
paths:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"
---

# API Development Rules

- 모든 API 엔드포인트에 입력 검증 필수
- 표준 에러 응답 형식 사용
- OpenAPI 문서 주석 포함

Paths 패턴 가이드

패턴매칭 대상
**/*.ts모든 디렉토리의 TypeScript 파일
src/**/*src 디렉토리 하위 모든 파일
*.md프로젝트 루트의 마크다운 파일
src/**/*.{ts,tsx}src 하위 ts/tsx 파일 (brace expansion)
{src,lib}/**/*.tssrc 또는 lib 하위 ts 파일

Rules 네이밍 규칙

  • 단일 단어 또는 kebab-case: security.md, code-style.md
  • 도메인/주제 명확히: testing.md, api-design.md
  • 하위 디렉토리 활용: frontend/react.md, backend/api.md

Rules 예시 구조

.claude/rules/
├── security.md           # 보안 정책
├── code-style.md         # 코딩 스타일
├── testing.md            # 테스트 컨벤션
├── git-workflow.md       # Git 워크플로우
├── frontend/
│   ├── react.md          # React 컨벤션
│   └── styles.md         # 스타일링 규칙
└── backend/
    ├── api.md            # API 설계
    └── database.md       # DB 규칙

CLAUDE.md 업데이트 가이드

위치: 프로젝트 루트 CLAUDE.md

용도: 프로젝트 컨텍스트, 제약사항, 규칙

추가할 내용 유형

  1. 프로젝트 구조 - 새 디렉토리, 파일 구조
  2. 환경 변수 - 새 API 키, 설정값
  3. 핵심 패턴 - 반드시 따라야 할 규칙
  4. 명령어 - 새 CLI 명령, 스크립트

추가 위치 가이드

내용 유형추가 위치
디렉토리 구조## 저장소 구조 섹션
CLI 명령어## 주요 명령어 섹션
API 사용 규칙## 핵심 패턴 섹션
환경 변수## 환경 변수 섹션

작성 스타일

  • 간결하게 (한 항목당 1-2줄)
  • 코드 예시 포함
  • ✅/❌ 로 올바른/잘못된 예시 구분

체크리스트

Agent 생성 시

  • name이 kebab-case인가?
  • allowed-tools에 필요한 도구만 포함했는가? (선택사항)
  • Workflow가 단계별로 명확한가?
  • Error Handling이 있는가?

Skill 생성 시

  • globs가 정확한 패턴인가? (선택사항: 자동 활성화가 필요한 경우만)
  • 규칙에 ✅/❌ 예시가 있는가?
  • 흔한 실수 섹션이 있는가?

Command 생성 시

  • arguments가 명확히 정의되었는가?
  • allowed-tools가 최소한인가?
  • Example이 있는가?

Rules 생성 시

  • 파일명이 kebab-case인가?
  • 한 파일에 하나의 주제만 다루는가?
  • 조건부 규칙인 경우 paths 패턴이 정확한가?
  • 명확한 섹션 구분이 있는가?
  • Rules vs Skills 구분이 적절한가? (자동 로드 vs 명시적 참조)

Code Dojo: Interactive Code Learning

Turn any codebase or concept into hands-on exercises where the learner writes the code.

Core Principle

The learner must write the code, not read it. Claude provides:

  • Skeleton files with // TODO blanks for core logic
  • Tests or type checks that verify correctness
  • Conceptual hints (never answers)

Workflow

Phase 1: Explore

Analyze the target codebase to identify teachable concepts. Use the Explore agent to understand:

  • Architecture and key abstractions
  • Dependency order between concepts (what must be understood first)
  • Core algorithms vs. boilerplate

Produce a learning path: ordered list of concepts, smallest-first.

Phase 2: Generate Exercises

For each step in the learning path, create two files:

Skeleton file (mini/stepN.ts or appropriate extension):

  • Working surrounding code (imports, types, exports)
  • // TODO: ... at each location the learner must implement
  • A conceptual hint block above each TODO (see Hint Guidelines below)

Test file (mini/stepN.test.ts or appropriate):

  • Covers both happy path and edge cases
  • Tests are ordered from simple to complex
  • Each test name describes the expected behavior in the learner's language

Phase 3: Interactive Loop

1. Present the step: explain what concept this covers and why
2. Learner edits the skeleton
3. Run tests (or type check), show results
4. If failures: point to the failing test name and the relevant concept, not the fix
5. If all pass: give brief feedback on their approach, then present next step

Hint Guidelines

Hints must teach the concept, not give the answer.

Bad hint (too direct):

// Hint: T extends string ? true : false

Good hint (teaches the tool):

// Key concept: conditional types use the same structure as ternary operators.
//   A extends B ? C : D
//   "If A is assignable to B, then C, else D"

Bad hint (gives the code):

// Hint: return Object.keys(pattern).every(k => k in value && matchPattern(...))

Good hint (points to the building blocks):

// You need to check every key in the pattern.
// Useful tools: Object.keys(), the `in` operator, Array.every()

Rules for hints:

  • Name the relevant APIs/types/operators, but do not show how to compose them
  • For type-level exercises, explain the behavior of a feature, not the syntax to use
  • If a step builds on a previous step, reference that: "This has the same structure as Step N"
  • Maximum 3 lines per hint

Step Design Rules

  1. One concept per step. Never combine unrelated ideas.
  2. Each step builds on the previous. Import or copy from earlier steps when needed.
  3. Start with runtime, then types. Concrete behavior before abstract type machinery.
  4. Skeleton compiles. The TODO version must not have syntax errors. Use return false, return undefined as any, or type X = unknown as placeholders.
  5. Tests run against the skeleton. They should fail (not error) so the learner sees red-to-green.
  6. 3-8 TODOs per step. Fewer than 3 is trivial; more than 8 is overwhelming.
  7. Edge case tests last. Put the simplest, most illustrative test first.

Feedback Style

When the learner submits their implementation:

  • Run tests immediately, show the output
  • If all pass: one sentence of specific feedback (not generic praise), then move on
  • If some fail: quote the failing test name, explain what concept it is testing, let them try again
  • If stuck (asked for help): give one more conceptual hint. If still stuck, show the approach in pseudocode (not real code). Only show real code as a last resort.

Adapting Difficulty

  • If the learner solves steps quickly with no failures: combine steps or skip ahead
  • If the learner struggles: break the current step into smaller sub-steps
  • If the learner asks "why": pause exercises and explain the design decision, then resume

Exercise File Organization

Place all exercise files in a mini/ directory within the project:

project/
  mini/
    step1.ts        # Skeleton
    step1.test.ts   # Tests
    step2.ts
    step2.test.ts
    ...

Language Support

The skeleton/test format adapts to the project language:

  • TypeScript: Jest tests + tsc --noEmit for type exercises
  • Python: pytest tests
  • Go: go test with table-driven tests
  • Rust: cargo test with #[test] functions

For type-level exercises (TypeScript), use compile-time assertions:

type Expect<T extends true> = T;
type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
// Test: type _t = Expect<Equal<MyType<Input>, Expected>>;

Verify with tsc --noEmit --strict instead of Jest.

Design DDD — 도메인 모델링 판단 기준

/design command의 D step에서 도메인이 복잡할 때 참조하는 판단 기준.

사용 방법:

  • /design command의 D step에서 자동 참조됨
  • 단독 참조도 가능 (도메인 모델 리뷰 시)

DDD 딥다이브 진입 조건

아래 중 2개 이상 해당하면 DDD 딥다이브가 필요하다:

  • 상태 전이가 있다 (예: Draft → Active → Expired)
  • 비즈니스 규칙이 3개 이상이다
  • 여러 엔티티 간 불변식이 존재한다
  • "~할 수 없다" 형태의 제약이 많다

설계 Phase 개요

Phase 1: 용어와 규칙을 모은다 (비즈니스 이해)
         ↓
Phase 2: 의미가 달라지는 경계를 긋는다 (Bounded Context)
         ↓
Phase 3: 경계 안에서 구체적으로 설계한다
         - 함께 변해야 하는 것을 묶고 (Aggregate)
         - 대표를 세우고 (Aggregate Root)
         - ID가 필요한 것(Entity)과 값인 것(VO)을 구분하고
         - 깨지면 안 되는 규칙을 정하고 (Invariant)
         - Aggregate 간 통신 방법을 정한다 (Domain Event)

Phase 1: 용어와 규칙 (비즈니스 이해)

1-1. 유비쿼터스 언어 (Ubiquitous Language)

"도메인 전문가와 개발자가 같은 단어를 같은 뜻으로 쓴다"

도출 방법:

  1. 요구사항에서 핵심 명사(개념)와 핵심 동사(행위)를 뽑는다
  2. 용어집 테이블로 정리한다
용어정의예시
{명사}{한 문장 정의}{구체적 예}
{동사}{어떤 상태를 어떻게 바꾸는가}{구체적 예}

검증 질문:

  • 이해관계자가 실제로 쓰는 단어인가?
  • 같은 것을 다른 이름으로 부르고 있지 않은가? (동의어 → 하나로 통일)
  • 하나의 단어가 문맥에 따라 다른 의미를 가지지 않는가? (동음이의어 → 분리)

동음이의어 발견 시:

  • 각각에 고유한 이름을 부여한다
  • 이 구분이 Phase 2 Bounded Context 분리의 단서가 된다

1-2. 비즈니스 규칙과 제약

요구사항에서 규칙을 수집한다.

발견 방법:

  • "~할 수 없다", "~이어야 한다", "~인 경우에만" 형태를 찾는다
  • 명시된 규칙과 암묵적 규칙 모두 포함

Phase 2: Bounded Context (경계 긋기)

"같은 단어라도 맥락에 따라 의미가 달라지는 경계"

경계 판단 기준

Q: 같은 용어가 서로 다른 의미/관심사로 쓰이는 곳이 있는가?
├─ Yes → 별도 Bounded Context
└─ No  → 같은 Bounded Context

예시: "상품(Product)"

  • 카탈로그 Context: 이름, 설명, 이미지, 카테고리
  • 주문 Context: 가격, 재고, 배송 무게
  • 리뷰 Context: 평점, 리뷰 수

같은 "상품"이지만 각 맥락에서 관심 있는 속성과 행위가 다르다.

Context 간 관계

관계설명예시
직접 설계우리가 모델링하는 영역쿠폰 Context
외부 시스템ID + 최소 정보만 참조주문 Context (orderId만)

판단 질문:

  • 우리가 직접 설계할 영역은?
  • 외부 시스템으로 취급할 영역은?
  • 외부에서 필요한 최소 정보는 무엇인가?

Phase 3: 경계 안 설계 (전술적 설계)

3-1. Aggregate 경계

"하나의 트랜잭션으로 일관성을 보장해야 하는 단위"

판단 기준:

Q: A를 변경할 때 B도 반드시 함께 변경되어야 하는가?
├─ Yes → 같은 Aggregate
└─ No  → 다른 Aggregate (이벤트로 연결)

Aggregate Root:

  • Aggregate의 대표. 외부에서는 Root를 통해서만 내부에 접근한다.
  • Root가 내부 요소의 일관성을 보장하는 책임을 진다.

Aggregate가 너무 클 때:

  • 서로 다른 생명주기를 가진 부분이 있나?
  • 서로 다른 변경 빈도를 가진 부분이 있나?
  • 분리해도 불변식을 보장할 수 있는가?

Aggregate가 너무 작을 때:

  • 불변식을 보장하기 위해 여러 Aggregate를 동시에 변경해야 하는가?
  • 그렇다면 하나로 합쳐야 한다

3-2. Entity vs Value Object

기준EntityValue Object
식별자고유 ID 필요값 자체로 비교
가변성시간에 따라 상태 변함불변 (immutable)
동등성ID로 비교모든 필드로 비교
예시User, Order, CouponMoney, Address, DateRange

결정 트리:

Q: 이 개념에 고유 식별자가 필요한가?
├─ Yes → Q: 시간에 따라 상태가 변하는가?
│         ├─ Yes → Entity
│         └─ No  → 정말 ID가 필요한지 재검토
└─ No  → Q: 같은 값이면 같은 것으로 취급해도 되는가?
          ├─ Yes → Value Object
          └─ No  → Entity (식별이 필요한 것)

Value Object로 만들 수 있으면 Value Object가 낫다. 이유:

  • 불변이므로 부작용 없음
  • 테스트가 쉬움
  • 공유해도 안전

3-3. 불변식 (Invariant)

"Aggregate가 항상 보장해야 하는 조건"

형식: {Aggregate}의 {조건}은 항상 {보장}이어야 한다

발견 방법:

  • Phase 1에서 수집한 비즈니스 규칙에서 "~할 수 없다", "~이어야 한다" 찾기
  • 각 불변식이 어느 Aggregate의 책임인지 할당
  • 불변식이 Aggregate 경계를 넘으면 → 경계 재검토

검증:

  • 이 불변식을 Aggregate Root의 메서드 안에서 보장할 수 있는가?
  • 외부 정보 없이 Aggregate 내부만으로 판단할 수 있는가?

3-4. 책임 할당

"정보 전문가 원칙: 그 판단에 필요한 정보를 누가 갖고 있는가?"

판단 흐름:

Q: 이 행위에 필요한 정보를 누가 갖고 있는가?
├─ 단일 Entity/VO가 가짐 → 그 Entity/VO의 메서드
├─ Aggregate Root가 관리 → Aggregate Root의 메서드
├─ 여러 Aggregate에 걸침 → Domain Service
└─ 외부 시스템 정보 필요 → Application Service (Port를 통해)

3-5. Domain Event

"Aggregate 간 비동기 통신 수단"

필요한 경우:

  • Aggregate A의 행위 성공 → Aggregate B가 반응해야 할 때
  • 같은 트랜잭션에 있을 필요 없는 후속 처리

이벤트 설계 기준:

  • 이름: 과거형 동사 (Created, Updated, Deleted)
  • 페이로드: 수신자가 필요한 최소 정보만
  • 수신자가 발신자의 내부 구조를 알 필요 없어야 함

흔한 실수

실수문제해결
Phase 2 건너뛰기경계 없이 모든 것이 한 덩어리동음이의어가 있으면 Context 분리
모든 것을 Entity로VO가 적합한 것까지 ID 부여"정말 ID가 필요한가?"
Aggregate가 하나God Object변경 빈도와 생명주기로 분리
불변식 누락비즈니스 규칙 위반 허용규칙마다 "누가 보장?" 질문
Domain Event에 너무 많은 정보결합도 증가수신자 기준 최소 정보
외부 의존을 Domain에Dependency Rule 위반Port interface로 역전

Design Library — API/라이브러리 설계 판단 기준

/design command의 D step에서 기술 라이브러리를 설계할 때 참조하는 판단 기준.

사용 방법:

  • /design command의 D step에서 자동 참조됨
  • 단독 참조도 가능 (라이브러리 API 리뷰 시)

Library Design 딥다이브 진입 조건

아래 중 2개 이상 해당하면 Library Design 딥다이브가 필요하다:

  • 다른 개발자가 소비하는 코드이다 (패키지, SDK, 내부 공유 모듈)
  • 공개 API surface를 설계해야 한다
  • 하위 호환성/버전 관리를 고려해야 한다
  • 추상화 레벨 선택이 설계의 핵심이다

설계 Phase 개요

Phase 1: 소비자의 멘탈 모델을 정의한다 (누가, 어떻게 쓰는가)
         ↓
Phase 2: 공개할 것과 숨길 것의 경계를 긋는다 (API Surface)
         ↓
Phase 3: 경계 안에서 구체적으로 설계한다
         - 타입으로 잘못된 사용을 막고 (Type Contract)
         - 확장 방법을 정하고 (Extension Point)
         - 안정성 약속을 정한다 (Stability Commitment)

Phase 1: Consumer Mental Model (소비자 이해)

"이 라이브러리를 쓰는 개발자가 머릿속에 가져야 할 개념은?"

1-1. 소비자 정의

질문예시
누가 쓰는가?앱 개발자 / 라이브러리 개발자 / 내부 팀
숙련도는?초급 → 간결한 API, 상급 → 세밀한 제어
한 문장 정의"{X}를 하기 위한 라이브러리"

검증 질문:

  • "README의 한 줄 소개를 적을 수 있는가?"
  • 적을 수 없으면 아직 범위가 명확하지 않은 것.

1-2. 핵심 개념 (Concept Glossary)

소비자가 알아야 할 개념을 3~5개로 정리한다.

개념정의코드에서의 표현
{명사}{한 문장 정의}{class/type/function 이름}

검증 질문:

  • 이 개념들만 알면 기본 사용이 가능한가?
  • 너무 많으면 → 추상화 경계를 재검토

1-3. 사용 예시 (README-Driven)

구현 전에 사용 예시를 먼저 작성한다.

Simple (1줄):  가장 흔한 사용법. 80%의 케이스.
Advanced:      설정을 바꾸거나 동작을 커스터마이즈. 19%.
Escape Hatch:  추상화를 우회해 내부에 직접 접근. 1%.

검증 질문:

  • Simple 예시가 1줄(또는 최소한의 코드)인가?
  • 잘못된 사용이 이 예시보다 더 쉽지는 않은가?

Phase 2: API Surface (공개 경계)

"무엇을 공개하고, 무엇을 숨기는가?"

2-1. Public vs Internal

Q: 이 심볼을 공개해야 하는가?
├─ 소비자의 use case에 필요하다 → Public
└─ 내부 구현 편의를 위한 것이다 → Internal

핵심 원칙: "확신이 없으면 빼라" (Bloch)

  • 나중에 추가는 가능하지만, 제거는 breaking change
  • Public으로 공개한 모든 심볼은 영원한 약속

2-2. Progressive Disclosure

3계층으로 API를 설계한다:

계층설명설계 기준
Layer 1: Simple가장 흔한 케이스최소 파라미터, 좋은 기본값
Layer 2: Configurable커스터마이즈 필요options object, 선택적 파라미터
Layer 3: Escape Hatch추상화 우회 필요내부 primitive 노출

검증 질문:

  • Layer 1만으로 80%의 use case를 해결하는가?
  • Layer 1을 배운 뒤 Layer 2로 자연스럽게 전환되는가? (호환되는가?)
  • 추상화가 실패할 때 escape hatch가 존재하는가?

2-3. Naming

판단 기준:

  • 이름 짓기가 어려우면 추상화 경계가 잘못된 것 (Bloch)
  • 관련 메서드는 일관된 이름 패턴을 따르는가? (대칭성)
  • 코드 샘플이 산문처럼 읽히는가?
  • 파라미터 순서가 모든 메서드에서 일관적인가?

2-4. Module 구조

Q: import 경로가 깊은가?
├─ 3단계 이상 → flat하게 재구성 고려
└─ 2단계 이하 → OK
  • Flat is better than nested (자동완성과 발견 용이)
  • 단, 논리적으로 독립된 하위 모듈이면 분리 가능

Phase 3: Contract & Extension (계약과 확장)

3-1. Type Contract

"타입으로 잘못된 사용을 컴파일 타임에 막을 수 있는가?"

결정 트리:

Q: 유효하지 않은 상태가 타입으로 표현 가능한가?
├─ Yes → Q: 그 상태가 조용한 오동작을 유발하는가?
│         ├─ Yes → 타입으로 방지 (discriminated union, branded type)
│         └─ No  → 런타임 검증 + 명확한 에러 메시지로 충분
└─ No  → 문서화로 안내

기법:

기법언제예시
Discriminated Union상호 배타적 상태{ kind: "email"; email: string } | { kind: "postal"; address: Address }
Smart Constructor생성 시 검증 필요EmailAddress.parse(raw) → Result<EmailAddress, Error>
Branded Type같은 원시 타입이지만 의미가 다름UserId vs OrderId (둘 다 string이지만 혼용 방지)
Non-empty Collection빈 입력이 의미 없음[T, ...T[]]

적용하지 않을 때:

  • 타입 시그니처가 이해 불가능하게 복잡해질 때
  • 제약이 문서로 충분히 전달될 때 ("양수여야 한다" 수준)

3-2. Error Model

Q: 호출자가 에러를 프로그래밍적으로 분기해야 하는가?
├─ Yes → typed exception 또는 Result type
└─ No  → 메시지만 포함된 일반 에러

원칙:

  • 에러는 문자열이 아닌 머신 리더블 구조를 가져야 한다
  • 에러는 잘못 사용한 지점에서 즉시 발생해야 한다 (fail fast)
  • 정상 흐름에 예외를 사용하지 않는다

3-3. Extension Point

"소비자가 동작을 확장해야 하는 지점은 어디인가?"

패턴 선택:

패턴제어 흐름결합도적합한 경우
Plugin라이브러리가 호출낮음전체 기능 추가 (파서, 포매터, 백엔드)
Middleware체인, 각각 next() 호출중간요청/응답 파이프라인, 전후 처리
Hook/EventPub-Sub, fire-and-forget매우 낮음관찰만 필요, 동작 변경 불필요
Adapter인터페이스 변환낮음외부 구현 주입 (HTTP 클라이언트, 로거)

판단 흐름:

Q: 확장이 동작을 변경하는가, 관찰만 하는가?
├─ 관찰만 → Hook/Event
└─ 변경 → Q: 전후 처리 파이프라인인가?
            ├─ Yes → Middleware
            └─ No  → Q: 기능 단위로 교체 가능한가?
                      ├─ Yes → Plugin
                      └─ No  → Adapter (외부 의존 주입)

Extension interface 설계 원칙:

  • interface는 최소화한다 (메서드 1~3개)
  • Extension 간에 서로를 알 필요 없어야 한다
  • 등록 방법이 명시적이어야 한다

3-4. Stability Commitment

"공개한 모든 것은 영원한 약속이다"

Hyrum's Law: "충분한 사용자가 있으면, 문서화하지 않은 관측 가능한 행위에도 누군가 의존한다"

체크리스트:

  • 관측 가능한 행위를 최소화했는가? (불필요한 정보 노출 금지)
  • 의존성(dependency)은 최소한인가? (각 dep는 소비자의 짐)
  • SemVer 전략은? (PATCH: 버그 수정 / MINOR: 추가 / MAJOR: 제거·변경)
  • Deprecation 정책은? (MINOR에서 deprecated 표시 → 다음 MAJOR에서 제거)
  • Tree-shaking / 모듈별 import가 가능한가?

흔한 실수

실수문제해결
구현부터 시작API가 내부 구조를 반영사용 예시(README)를 먼저 작성
모든 것을 public모든 변경이 breaking change기본 private, 필요한 것만 공개
string/any 파라미터 남용런타임 에러, 문자열 파싱전용 타입, enum, value object
nullable return호출자가 null 체크 누락빈 컬렉션, Option/Result 타입
긴 positional 파라미터인자 순서 실수options object 또는 builder
escape hatch 없음추상화 실패 시 막힘Layer 3 raw access 제공
무거운 의존성번들 비대, 버전 충돌dep 최소화, 주입 허용
global mutable 설정복수 인스턴스 간 간섭인스턴스 기반 설정 (class/closure)
에러에 문자열만호출자가 에러 문자열 파싱typed exception + 머신 리더블 필드

Design RADIO — 체크리스트

GreatFrontEnd의 RADIO Framework를 실무 확장한 설계 체크리스트. /design command가 C → RADIO → V 각 단계에서 이 스킬을 참조한다.

사용 방법:

  • /design command의 각 Step에서 자동 참조됨
  • 단독 참조도 가능 (설계 리뷰, 체크리스트 확인 시)

C → RADIO → V

Gate In ─ C  Context        기존 코드·패턴·컨벤션 파악

          R  Requirements   문제 정의 + 기능/비기능 + 스코프 아웃
 RADIO    A  Architecture   주요 컴포넌트 + 책임 할당
          D  Data Model     엔티티, 필드, 데이터 출처/생명주기
          I  Interface      경계를 넘는 계약 (API, props, 이벤트)
          O  Optimizations  NFR에서 도출된 항목만 (YAGNI)

Gate Out ─ V  Verification  Given/When/Then 핵심 3~5개

라디오를 켜기 전에 주파수를 맞추고(C), 끝나면 수신을 확인한다(V).

각 단계의 상세 체크리스트:

  • 공통: references/checklist-common.md (항상 참조)
  • FE 작업: references/checklist-fe.md (공통 + FE)
  • BE 작업: references/checklist-be.md (공통 + BE)

사용법

1. 항상 C부터 시작한다

기존 코드와 컨벤션을 먼저 파악한다. 그 다음 R에서 "X를 하면 Y가 된다"를 한 문장으로 적을 수 없으면, 아직 설계할 준비가 안 된 것. PRD를 다시 읽거나 PM에게 질문한다.

2. 깊이를 작업 크기에 맞춘다

작업 크기Gate (C/V)RADIO 단계
버그 수정 / 1일 작업C, V (항상)R
기능 추가 / 1주 작업C, V (항상)R, D, I
시스템 설계 / 1달+C, V (항상)R, A, D, I, O

Gate(C/V)는 항상 수행한다. RADIO 단계는 작업 크기에 맞춰 선택한다.

3. 각 단계의 핵심 질문 (요약)

C — Context (Gate In)

"지금 코드베이스에서 재사용하거나 변경할 것은?"

  • 재사용 가능한 기존 코드
  • 기존 패턴과 컨벤션
  • 변경이 필요한 기존 코드

R — Requirements

"무엇을 해야 하고, 무엇을 하지 않는가?"

  • 한 문장 문제 정의
  • 기능 요구사항 (핵심 유저 플로우)
  • 비기능 요구사항 (성능, 보안, 접근성)
  • 스코프 아웃 (명시적으로 하지 않는 것)

A — Architecture

"주요 조각은 무엇이고, 각각 무슨 책임을 가지는가?"

  • 주요 컴포넌트 식별
  • 컴포넌트 간 관계도
  • 계산이 일어나는 위치 (서버 vs 클라이언트)

D — Data Model

"어떤 데이터가 존재하고, 어디서 오고, 어디에 저장되는가?"

  • 엔티티 정의 (필드, 타입, 제약조건)
  • 데이터 출처 (서버/클라이언트)
  • 엔티티 간 관계

I — Interface Definition

"컴포넌트 간 경계에서 무엇이 오고 가는가?"

  • 각 경계의 Input/Output 계약
  • 에러 처리 계약
  • 타입 정의

O — Optimizations

"NFR에서 도출된 최적화는 무엇인가?"

  • R 단계의 NFR에서 직접 도출된 항목만
  • 추측성 최적화 금지

V — Verification (Gate Out)

"이것이 완료되었다는 것을 어떻게 증명하는가?"

  • Given/When/Then 핵심 3~5개
  • 정상 → 에러 → 엣지 순서
  • 이것이 "완료의 정의"

안티패턴

안티패턴문제해결
C 없이 R부터 시작기존 코드를 모르고 요구사항부터 정의C(Gate In)부터 시작
C를 건너뜀이미 있는 걸 새로 만듦Gate는 항상 수행
D와 I를 동시에 생각데이터와 계약이 뒤섞임D(무엇이 존재하는가) 먼저, I(어떻게 주고받는가) 다음
O에서 추측성 최적화YAGNI 위반R의 NFR에 없으면 안 함
V 없이 구현 시작"완료"가 정의되지 않음최소 3개 Given/When/Then
Domain이 Infrastructure를 importDependency Rule 위반Domain은 순수 비즈니스 규칙만. 외부 의존은 Port interface로 역전

Entity Object Pattern

사용 시점: TDD Refactor 단계에서 참조합니다. Given/When/Then 테스트 케이스에서 반복되는 도메인 로직을 식별하고, 이 패턴을 적용하여 Entity Object로 그룹화합니다.

TypeScript의 companion object 패턴을 활용하여, Entity interface와 같은 이름의 const 객체에 도메인 로직 함수를 그룹화하는 패턴.

핵심 원리

TypeScript는 타입과 값이 별도 네임스페이스에 존재하므로, interface와 const에 같은 이름을 사용할 수 있다:

export interface AdGroup { /* 타입 */ }
export const AdGroup = { /* 값 (도메인 로직 함수들) */ } as const;

// 사용처에서:
import { AdGroup } from './AdGroup';
const ag: AdGroup = ...;              // 타입으로 사용
AdGroup.canEditDailyBudget(ag);       // 값으로 사용

함수 유형

접두사용도반환 타입예시
is*상태 조건 체크booleanAdGroup.isMaximizeConversionsBidding()
get*파생값 계산도메인 타입AdGroup.getDailyBudget()
can*행동 가능 여부booleanAdGroup.canEditDailyBudget()
should*조건부 동작 체크booleanAdGroup.shouldShowBudgetWarning()
count*집계numberPostAdDisplayItem.countActive()

Given/When/Then에서 추출

Given 분석 → is* (상태 조건)
When 분석  → can* (가능 조건)
Then 분석  → get*, should*, count* (파생값, 동작 조건, 집계)

예시:

#GivenWhenThenEntity Object 함수
1입찰 전략이 "전환수 최대화"일예산 수정 시도필드 비활성화AdGroup.isMaximizeConversionsBidding, AdGroup.canEditDailyBudget
2일예산 < 일소진액×3대시보드 진입경고 표시AdGroup.shouldShowBudgetWarning

의존성 순서 (Layer)

Layer 1 (Base): is* 함수들 (의존성 없음)
    ↓
Layer 2 (Derived): can*, get* (is* 의존)
    ↓
Layer 3 (Composite): should* (여러 함수 조합)

파일 구조

Entity 파일 내부에 interface와 같은 이름의 const 객체를 정의:

// src/domain/AdGroup.ts (또는 _models/AdGroup.ts)

// Entity 타입
export interface AdGroup {
  id: string;
  biddingType: BiddingType;
  dailyBudget: number;
}

// Entity Object — interface와 같은 이름
export const AdGroup = {
  // Layer 1: Base
  isMaximizeConversionsBidding: (adGroup: AdGroup): boolean =>
    adGroup.biddingType === 'MAXIMIZE_CONVERSIONS',

  // Layer 2: Derived (Layer 1 사용)
  canEditDailyBudget: (adGroup: AdGroup): boolean =>
    !AdGroup.isMaximizeConversionsBidding(adGroup),

  getDailyBudget: (adGroup: AdGroup): number | null =>
    AdGroup.isMaximizeConversionsBidding(adGroup) ? null : adGroup.dailyBudget,

  // Layer 3: Composite (Layer 1, 2 사용)
  shouldShowBidSettings: (adGroup: AdGroup, campaign: Campaign): boolean =>
    AdGroup.canEditDailyBudget(adGroup) && campaign.status !== 'PAUSED',
} as const;

사용 위치별 예시

UI 렌더링

import { AdGroup } from '../domain/AdGroup';

function DailyBudgetField({ adGroup }: { adGroup: AdGroup }) {
  const disabled = !AdGroup.canEditDailyBudget(adGroup);
  const value = AdGroup.getDailyBudget(adGroup);

  return (
    <NumberInput
      value={value}
      disabled={disabled}
      placeholder={disabled ? "자동 설정" : "금액 입력"}
    />
  );
}

API 요청 Body

import { AdGroup } from '../domain/AdGroup';

function buildUpdateRequest(adGroup: AdGroup): UpdateRequest {
  return {
    id: adGroup.id,
    dailyBudget: AdGroup.getDailyBudget(adGroup),
  };
}

테스트 코드

import { AdGroup } from '../domain/AdGroup';

describe('AdGroup', () => {
  it('전환수 최대화 입찰이면 일예산 수정 불가', () => {
    const adGroup = createAdGroup({ biddingType: 'MAXIMIZE_CONVERSIONS' });

    expect(AdGroup.canEditDailyBudget(adGroup)).toBe(false);
    expect(AdGroup.getDailyBudget(adGroup)).toBeNull();
  });
});

흔한 실수와 해결책

문제원인해결
함수 중복UI/API에서 각각 구현Entity Object에 정의하여 재사용
조건 불일치같은 규칙을 다르게 해석Single Source of Truth (Entity Object)
테스트 누락Entity Object 함수를 테스트 안 함함수별 단위 테스트 필수
의존성 순환is* 함수가 can* 함수 호출Layer 구조 준수
과도한 추상화모든 조건을 Entity Object에 추출2곳 이상 재사용되는 경우만 추출
standalone 함수 산재Entity와 무관하게 함수 정의Entity Object에 그룹화하여 응집도 확보

FE TechSpec

관련 스킬: entity-object-pattern - 구현 시 반복되는 도메인 로직을 Entity Object로 그룹화하는 패턴

FE TechSpec은 프로젝트의 기술적 구현 방향을 정의하는 문서. PRD(요구사항)와 Figma(디자인)를 기반으로 Solution, Acceptance Criteria, Test Cases를 도출한다.

문서 구조

Summary → Solution → Acceptance Criteria → Non-Functional Requirements → Functional Requirements (Given/When/Then) → Design → Component & Code → Verification

전체 템플릿은 references/template.md 참조.

섹션별 작성 가이드

Summary

프로젝트 배경과 맥락. PRD/Figma 링크 포함.

## Summary

{프로젝트 배경 1-3문장}

- **PRD**: {Notion URL}
- **Figma**: {Figma URL}

Solution

비즈니스 관점에서 핵심 변경사항을 요약. 기술 용어 없이 "무엇이 어떻게 바뀌는가"에 집중.

## Solution

### 핵심 변경사항

1. **{변경1}**: {설명}
2. **{변경2}**: {설명}
3. **{변경3}**: {설명}

작성 규칙:

  • ❌ 코드, API명, 타입명 사용 금지
  • ✅ 사용자/광고주 관점에서 서술
  • 3-5개 핵심 변경사항을 번호 매기기 형식으로 나열

Acceptance Criteria

기능 동작의 최소 기준. 테스트 가능한 형태로 작성.

## Acceptance Criteria

1. {주어} 상태에서 {동작}하면 {결과}가 발생한다
2. ...
  • 측정 가능하고 검증 가능한 문장으로 작성
  • "빠르게", "잘" 같은 모호한 표현 금지
  • 핵심 유저 플로우별 1개 이상

Non-Functional Requirements

SLA/SLO 기준의 시스템 요구사항.

카테고리:

  • Performance: LCP < 2.5s, FID < 100ms, CLS < 0.1
  • Accessibility: WCAG AA
  • SEO: 메타 태그, OG 태그, 시맨틱 마크업

해당 프로젝트에 관련 없는 카테고리는 생략 가능.

Functional Requirements (Given/When/Then)

테스트 케이스를 구조화된 테이블로 정의.

핵심 개념:

  • 기능 요구사항을 Test cases (Given, When, Then) 형태로 정의해요.
## Functional Requirements (Test cases / Given, When, Then)

| # | Given | When | Then |
|---|-------|------|------|
| 1 | {초기 상태/조건} | {사용자 행동/이벤트} | {기대 결과} |
| 2 | ... | ... | ... |

작성 팁:

  • 정상 케이스 → 에러 케이스 → 엣지 케이스 순서
  • Given은 상태, When은 행동, Then은 검증 가능한 결과
  • ⚠️ Entity/Command 식별은 Design 섹션에서 수행, FR에는 테이블만 작성

Design

테스트 케이스 기반으로 도메인 설계를 진행.

작성 순서:

  1. 데이터 모델: API 응답 기반 interface 정의
    • API 응답 모델을 기반으로 interface를 정의하고, 컴포넌트는 이 interface에만 의존
    • 대부분 API 타입 참조로 충분. 별도 클라이언트 Entity는 정말 필요한 경우에만 추가
    • 필요한 경우: 여러 API 응답 조합, 클라이언트 고유 상태, API와 다른 구조가 필요한 경우
  2. Usecase: 주요 사용 시나리오 테이블 (Input → Output) 2.5. Interface Contract: Server-Client API (hooks/endpoints) + Client-Client API (component props)
    • Server-Client: query hook, mutation hook, 파라미터, 응답 타입, 캐시 전략
    • Client-Client: 모듈 경계를 형성하는 핵심 Props Interface와 Callback 시그니처
    • TC 번호로 추적
  3. Component & Visual Contract: 컴포넌트 계층 설계. 두 유형으로 분류:
    • Container: Usecase 연결, 서버 상태 구독, 데이터 가공 → 하위 Presentational에 전달. Visual Contract 없음
    • Presentational: Props/Callbacks 기반 순수 UI. Visual Contract 필수 (Layout, States, Interactions)
    • Figma가 있으면 get_design_context/get_variable_defs에서 추출, 없으면 테스트 케이스에서 도출
  4. Usecase-Component Integration: 연결 지점 정의
  5. Optimization Checklist: TC/NFR에서 도출된 최적화 항목만 기록
    • Performance, UX, Network, A11y 카테고리
    • 해당 없는 항목은 기록하지 않음

데이터 모델 가이드:

  • ✅ API 응답 타입을 기반으로 interface 정의 → 컴포넌트는 interface만 의존
  • ✅ enum/상수값은 constants/에 별도 정의 가능
  • ❌ API 응답과 동일한 구조를 클라이언트 Entity로 재정의
  • ⚠️ 별도 클라이언트 Entity가 필요하면 사유를 명시 (예: "여러 API 응답 조합 필요")

Component & Code - Client

  • Test cases 기반으로 module, usecase, 컴포넌트 구조 추출
  • 컴포넌트 분해, 파일 구조, Props 인터페이스.
  • interface는 API 타입 기반으로 정의하되, 컴포넌트가 API 모델에 직접 의존하지 않도록 레이어 분리

(Optional) Context & Container Diagram / Component & Code - Server

필요한 경우에만 작성.

Verification

테스트 케이스 검증 전략.

우선순위:

  1. Integration Tests (필수): TC 기반 컴포넌트 통합 테스트
  2. Unit Tests (필요 시): 복잡한 파생 상태 로직만
  3. E2E Tests (필요 시): 전체 사용자 플로우 검증

Integration Test 테이블 형식:

TC#테스트 명검증 내용
TC1......

흔한 실수와 해결책

문제원인해결
AC가 모호함"빠르게", "잘" 같은 추상적 표현측정 가능한 기준 사용 (예: "3초 이내")
Given/When/Then 불명확상태/행동/결과 구분 없음Given=상태, When=행동, Then=검증 가능한 결과
Test Case 누락정상 케이스만 작성에러/엣지 케이스 반드시 포함
NFR 생략선택사항이라 무시공개 페이지면 SEO/A11y 필수 검토
Solution에 코드 포함"기술적 해결책"으로 오해비기술 요약으로 작성
클라이언트 Entity 과잉 설계API 응답을 재정의하려 함API 타입 기반 interface로 충분. 별도 Entity는 사유 필요
UI 문구 가정Figma 미확인variants에서 실제 문구 추출
FR에 Entity/Command 헤더지침 오해Design에서만 사용, FR은 테이블만
Verification 누락선택사항으로 오인Integration Test 필수
규칙 중복 구현UI/API에서 같은 규칙을 각각 구현구현 시 entity-object-pattern 스킬 참조
Container/Presentational 혼합하나의 컴포넌트가 Usecase 호출 + UI 렌더링Container(데이터 흐름)와 Presentational(Props/Callbacks)을 분리
모든 Props를 Interface Contract에 기록과잉 명세모듈 경계를 형성하는 핵심 인터페이스만 정의. 내부 컴포넌트 Props는 Component 섹션에서
Optimization Checklist 전부 채움RADIO 원칙 오해TC/NFR에서 도출된 항목만. "해당없음"이 대부분이어도 정상

Browser Automation with playwright-cli

Quick start

# open new browser
playwright-cli open
# navigate to a page
playwright-cli goto https://playwright.dev
# interact with the page using refs from the snapshot
playwright-cli click e15
playwright-cli type "page.click"
playwright-cli press Enter
# take a screenshot (rarely used, as snapshot is more common)
playwright-cli screenshot
# close the browser
playwright-cli close

Commands

Core

playwright-cli open
# open and navigate right away
playwright-cli open https://example.com/
playwright-cli goto https://playwright.dev
playwright-cli type "search query"
playwright-cli click e3
playwright-cli dblclick e7
playwright-cli fill e5 "user@example.com"
playwright-cli drag e2 e8
playwright-cli hover e4
playwright-cli select e9 "option-value"
playwright-cli upload ./document.pdf
playwright-cli check e12
playwright-cli uncheck e12
playwright-cli snapshot
playwright-cli snapshot --filename=after-click.yaml
playwright-cli eval "document.title"
playwright-cli eval "el => el.textContent" e5
playwright-cli dialog-accept
playwright-cli dialog-accept "confirmation text"
playwright-cli dialog-dismiss
playwright-cli resize 1920 1080
playwright-cli close

Navigation

playwright-cli go-back
playwright-cli go-forward
playwright-cli reload

Keyboard

playwright-cli press Enter
playwright-cli press ArrowDown
playwright-cli keydown Shift
playwright-cli keyup Shift

Mouse

playwright-cli mousemove 150 300
playwright-cli mousedown
playwright-cli mousedown right
playwright-cli mouseup
playwright-cli mouseup right
playwright-cli mousewheel 0 100

Save as

playwright-cli screenshot
playwright-cli screenshot e5
playwright-cli screenshot --filename=page.png
playwright-cli pdf --filename=page.pdf

Tabs

playwright-cli tab-list
playwright-cli tab-new
playwright-cli tab-new https://example.com/page
playwright-cli tab-close
playwright-cli tab-close 2
playwright-cli tab-select 0

Storage

playwright-cli state-save
playwright-cli state-save auth.json
playwright-cli state-load auth.json

# Cookies
playwright-cli cookie-list
playwright-cli cookie-list --domain=example.com
playwright-cli cookie-get session_id
playwright-cli cookie-set session_id abc123
playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
playwright-cli cookie-delete session_id
playwright-cli cookie-clear

# LocalStorage
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear

# SessionStorage
playwright-cli sessionstorage-list
playwright-cli sessionstorage-get step
playwright-cli sessionstorage-set step 3
playwright-cli sessionstorage-delete step
playwright-cli sessionstorage-clear

Network

playwright-cli route "**/*.jpg" --status=404
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
playwright-cli route-list
playwright-cli unroute "**/*.jpg"
playwright-cli unroute

DevTools

playwright-cli console
playwright-cli console warning
playwright-cli network
playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
playwright-cli tracing-start
playwright-cli tracing-stop
playwright-cli video-start
playwright-cli video-stop video.webm

Open parameters

# Use specific browser when creating session
playwright-cli open --browser=chrome
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge
# Connect to browser via extension
playwright-cli open --extension

# Use persistent profile (by default profile is in-memory)
playwright-cli open --persistent
# Use persistent profile with custom directory
playwright-cli open --profile=/path/to/profile

# Start with config file
playwright-cli open --config=my-config.json

# Close the browser
playwright-cli close
# Delete user data for the default session
playwright-cli delete-data

Snapshots

After each command, playwright-cli provides a snapshot of the current browser state.

> playwright-cli goto https://example.com
### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)

You can also take a snapshot on demand using playwright-cli snapshot command.

If --filename is not provided, a new snapshot file is created with a timestamp. Default to automatic file naming, use --filename= when artifact is a part of the workflow result.

Browser Sessions

# create new browser session named "mysession" with persistent profile
playwright-cli -s=mysession open example.com --persistent
# same with manually specified profile directory (use when requested explicitly)
playwright-cli -s=mysession open example.com --profile=/path/to/profile
playwright-cli -s=mysession click e6
playwright-cli -s=mysession close  # stop a named browser
playwright-cli -s=mysession delete-data  # delete user data for persistent session

playwright-cli list
# Close all browsers
playwright-cli close-all
# Forcefully kill all browser processes
playwright-cli kill-all

Local installation

In some cases user might want to install playwright-cli locally. If running globally available playwright-cli binary fails, use npx playwright-cli to run the commands. For example:

npx playwright-cli open https://example.com
npx playwright-cli click e1

Example: Form submission

playwright-cli open https://example.com/form
playwright-cli snapshot

playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
playwright-cli snapshot
playwright-cli close

Example: Multi-tab workflow

playwright-cli open https://example.com
playwright-cli tab-new https://example.com/other
playwright-cli tab-list
playwright-cli tab-select 0
playwright-cli snapshot
playwright-cli close

Example: Debugging with DevTools

playwright-cli open https://example.com
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli console
playwright-cli network
playwright-cli close
playwright-cli open https://example.com
playwright-cli tracing-start
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli tracing-stop
playwright-cli close

Specific tasks

Seed Design React 컴포넌트

@seed-design/react 컴포넌트를 사용할 때 아래 LLM 참고 문서를 조회하여 올바른 API와 사용법을 따른다.

참고 문서

활용 방법

컴포넌트의 props, 사용 예시, 마이그레이션 가이드가 필요하면 위 URL을 WebFetch로 조회한다.

Skill Creator

This skill provides guidance for creating effective skills.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

  1. Specialized workflows - Multi-step procedures for specific domains
  2. Tool integrations - Instructions for working with specific file formats or APIs
  3. Domain expertise - Company-specific knowledge, schemas, business logic
  4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Core Principles

Concise is Key

The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.

Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.

Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.

Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
SKILL.md (required)

Every SKILL.md consists of:

  • Frontmatter (YAML): Contains name and description fields. These are the only fields that Claude reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
  • Body (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
Bundled Resources (optional)
Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

  • When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
  • Example: scripts/rotate_pdf.py for PDF rotation tasks
  • Benefits: Token efficient, deterministic, may be executed without loading into context
  • Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments
References (references/)

Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.

  • When to include: For documentation that Claude should reference while working
  • Examples: references/finance.md for financial schemas, references/mnda.md for company NDA template, references/policies.md for company policies, references/api_docs.md for API specifications
  • Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
  • Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
  • Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
  • Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
Assets (assets/)

Files not intended to be loaded into context, but rather used within the output Claude produces.

  • When to include: When the skill needs files that will be used in the final output
  • Examples: assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typography
  • Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
  • Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context
What to Not Include in a Skill

A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:

  • README.md
  • INSTALLATION_GUIDE.md
  • QUICK_REFERENCE.md
  • CHANGELOG.md
  • etc.

The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

  1. Metadata (name + description) - Always in context (~100 words)
  2. SKILL.md body - When skill triggers (<5k words)
  3. Bundled resources - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
Progressive Disclosure Patterns

Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.

Key principle: When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.

Pattern 1: High-level guide with references

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.

Pattern 2: Domain-specific organization

For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

When a user asks about sales metrics, Claude only reads sales.md.

Similarly, for skills supporting multiple frameworks or variants, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

When the user chooses AWS, Claude only reads aws.md.

Pattern 3: Conditional details

Show basic content, link to advanced content:

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude reads REDLINING.md or OOXML.md only when the user needs those features.

Important guidelines:

  • Avoid deeply nested references - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
  • Structure longer reference files - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.

Skill Creation Process

Skill creation involves these steps:

  1. Understand the skill with concrete examples
  2. Plan reusable skill contents (scripts, references, assets)
  3. Initialize the skill (run init_skill.py)
  4. Edit the skill (implement resources and write SKILL.md)
  5. Package the skill (run package_skill.py)
  6. Iterate based on real usage

Follow these steps in order, skipping only if there is a clear reason why they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

For example, when building an image-editor skill, relevant questions include:

  • "What functionality should the image-editor skill support? Editing, rotating, anything else?"
  • "Can you give some examples of how this skill would be used?"
  • "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
  • "What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

  1. Considering how to execute on the example from scratch
  2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:

  1. Rotating a PDF requires re-writing the same code each time
  2. A scripts/rotate_pdf.py script would be helpful to store in the skill

Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:

  1. Writing a frontend webapp requires the same boilerplate HTML/React each time
  2. An assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skill

Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:

  1. Querying BigQuery requires re-discovering the table schemas and relationships each time
  2. A references/schema.md file documenting the table schemas would be helpful to store in the skill

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.

Step 3: Initializing the Skill

At this point, it is time to actually create the skill.

Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.

When creating a new skill from scratch, always run the init_skill.py script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.

Usage:

scripts/init_skill.py <skill-name> --path <output-directory>

The script:

  • Creates the skill directory at the specified path
  • Generates a SKILL.md template with proper frontmatter and TODO placeholders
  • Creates example resource directories: scripts/, references/, and assets/
  • Adds example files in each directory that can be customized or deleted

After initialization, customize or remove the generated SKILL.md and example files as needed.

Step 4: Edit the Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.

Learn Proven Design Patterns

Consult these helpful guides based on your skill's needs:

  • Multi-step processes: See references/workflows.md for sequential workflows and conditional logic
  • Specific output formats or quality standards: See references/output-patterns.md for template and example patterns

These files contain established best practices for effective skill design.

Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.

Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.

Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.

Update SKILL.md

Writing Guidelines: Always use imperative/infinitive form.

Frontmatter

Write the YAML frontmatter with name and description:

  • name: The skill name
  • description: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
    • Include both what the Skill does and specific triggers/contexts for when to use it.
    • Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
    • Example description for a docx skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"

Do not include any other fields in YAML frontmatter.

Body

Write instructions for using the skill and its bundled resources.

Step 5: Packaging a Skill

Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:

scripts/package_skill.py <path/to/skill-folder>

Optional output directory specification:

scripts/package_skill.py <path/to/skill-folder> ./dist

The packaging script will:

  1. Validate the skill automatically, checking:

    • YAML frontmatter format and required fields
    • Skill naming conventions and directory structure
    • Description completeness and quality
    • File organization and resource references
  2. Package the skill if validation passes, creating a .skill file named after the skill (e.g., my-skill.skill) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.

If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.

Step 6: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

Iteration workflow:

  1. Use the skill on real tasks
  2. Notice struggles or inefficiencies
  3. Identify how SKILL.md or bundled resources should be updated
  4. Implement changes and test again

Commands 14

Config Trim Command

프로젝트의 AI 관련 설정 파일에서 중복·불필요 콘텐츠를 찾아 보고하고, 승인된 항목만 제거한다.

Redundancy Pattern Catalog

분석 시 아래 8가지 패턴을 체크한다.

ID패턴감지 방법
P1Auto-loaded rule 중복rules/ 내용이 agent/command에 반복됨. Rules는 세션 시작 시 자동 로드되므로 agent에서 반복하면 100% 중복
P2인라인 template 블록skills/*/references/ 등의 참조 파일 내용이 agent에 인라인됨. Read 참조로 대체 가능
P3재요약 섹션"참고", "요약" 등 레이블의 섹션이 같은 파일 본문의 내용을 재서술
P4자명한 프로세스 단계"(Human) Review" 등 판단 기준 없이 "승인/거절"만 있는 phase
P5Verbose 예시Example 섹션에서 결정 지점(AskUserQuestion/응답) 외 중간 trace가 과다
P6인라인 절차 복사rule 파일에 정의된 절차를 command에 통째로 복사 (1줄 참조로 대체 가능)
P7하드코딩된 도구명특정 MCP/CLI 도구명이 일반 설명으로 대체 가능한 경우
P8CLAUDE.md 코드베이스 설명다른 설정 파일(skill 등)에 이미 있는 구조·형식 설명을 CLAUDE.md에서 반복. 또는 에이전트가 탐색으로 더 빠르게 파악할 수 있는 디렉토리 구조·파일 형식 설명

제외 조건 (정당한 중복)

다음은 분석 대상에서 제외한다:

  • Command의 task description template 내 내용: workspace에 전달되므로 self-contained 필수
  • 사람용 문서 (Linear issue template 등): 에이전트 지시와 다른 용도
  • Agent의 분석 방법론/설계 규칙: agent는 skill을 직접 호출 불가 — 분석 로직은 agent에 필수

Execution Flow

Phase 1: 파일 탐색

프로젝트의 AI 설정 파일 구조를 탐색한다.

1-1. 설정 파일 위치 감지:

다음 경로를 순서대로 확인하여 설정 파일이 있는 위치를 파악한다:

구조감지 방법설명
프로젝트 .claude/Glob(".claude/agents/*.md"), Glob(".claude/commands/**/*.md") 등프로젝트 로컬 설정
플러그인 repoGlob("plugins/*/agents/*.md"), Glob("plugins/*/commands/**/*.md") 등플러그인 마켓플레이스 저장소
CLAUDE.mdGlob("**/CLAUDE.md")프로젝트 루트 또는 하위 디렉토리

1-2. 대상 파일 수집:

agents/*.md
commands/**/*.md
CLAUDE.md (모든 위치)

1-3. 비교 참조 파일 수집 (중복 감지용):

rules/*.md
skills/*/references/*.md
skills/*/SKILL.md

모든 파일을 Read하여 내용을 파악한다.

Phase 2: 분석

각 대상 파일에 대해 P1~P8 패턴을 순서대로 체크한다.

P1/P2 (기계적 비교):

  • 각 rule 파일의 핵심 내용 블록을 추출
  • agent/command 파일에서 동일·유사 블록을 Grep으로 탐색
  • 각 reference 파일의 구조(테이블 헤더, 코드블록)를 agent 파일과 비교

P3~P8 (의미론적 판단):

  • 파일 내용을 읽고 각 패턴의 해당 여부를 판단
  • 제외 조건에 해당하면 건너뜀

발견 항목마다 기록:

{번호, 파일명, 라인 범위, 패턴 ID, 설명, 제안 액션}

Phase 3: 보고 & 승인

분석 결과를 파일별로 그룹화하여 AskUserQuestion으로 제시한다.

AskUserQuestion:
  question: "## Config Trim 분석 결과

  분석: {N}개 파일 / 발견: {M}건 (예상 제거: ~{lines}줄)

  ### {파일명}
  1. [P1 Rule Dup] L{start}-{end}: {설명} → {제안 액션}
  2. [P5 Verbose] L{start}-{end}: {설명} → {제안 액션}

  ### {파일명}
  3. [P6 Procedure] L{start}-{end}: {설명} → {제안 액션}

  선택: 전체 승인 / 부분 승인 (번호 지정) / 수정 요청 / 중단"

Phase 4: 적용

승인된 항목만 Edit으로 적용한다.

패턴별 변환 방법:

패턴변환
P1 Rule Dup중복 블록 삭제
P2 Template코드블록을 참조 파일 경로의 Read 참조 1줄로 교체
P3 Restate섹션 전체 삭제
P4 Self-evidentphase 삭제 또는 1줄로 축소
P5 Verbose결정 지점(AskUserQuestion/응답)만 남기고 중간 trace 삭제
P6 Procedure인라인 절차를 rule 파일 참조 1줄로 교체
P7 Hardcode구체적 도구명을 일반 설명으로 교체
P8 Description코드베이스 설명 삭제 또는 skill/문서 참조로 교체

Phase 5: 동기화 & 보고

  1. sync 스크립트 감지: Glob("**/sync.sh")로 동기화 스크립트가 있으면 실행하여 repo↔local 동기화

  2. sync 스크립트가 없으면 이 단계를 건너뜀

  3. 결과 보고:

    ## Config Trim 완료
    
    적용: {N}건 / 제거: ~{lines}줄
    
    변경된 파일:
    - {파일명} (-{N} lines)
    
    커밋은 생성하지 않았습니다. 확인 후 커밋하세요.
    

Error Handling

상황대응
AI 설정 파일 없음"AI 설정 파일을 찾을 수 없습니다. (.claude/, CLAUDE.md 등)" 출력 후 종료
발견 항목 없음"모든 파일이 최적화되어 있습니다." 출력 후 종료
적용 중 Edit 실패해당 항목 건너뛰고 실패 보고, 나머지 계속 적용

Example

사용자: /config-trim

Claude: AI 설정 파일을 탐색합니다...
  → .claude/agents/ (7개), .claude/commands/ (10개), CLAUDE.md (1개)
  → .claude/rules/ (3개), .claude/skills/ (6개) — 비교 참조용

Claude: 8가지 중복 패턴으로 분석합니다...

Claude: [AskUserQuestion]
  ## Config Trim 분석 결과
  분석: 18개 파일 / 발견: 3건 (예상 제거: ~20줄)

  ### .claude/agents/tdd-red.md
  1. [P1 Rule Dup] L46-49: test-file-location.md 규칙 내용 중복 → 삭제

  ### .claude/commands/pr.md
  2. [P6 Procedure] L25-38: gh-auth.md 절차 인라인 복사 → 1줄 참조로 교체

  ### CLAUDE.md
  3. [P8 Description] L5-50: 디렉토리 구조 설명이 skill과 중복 → 행동 지침만 유지

  선택: 전체 승인 / 부분 승인 (번호) / 중단

사용자: 전체 승인

Claude: Config Trim 완료!
  적용: 3건 / 제거: ~20줄
  → 확인 후 커밋하세요

Design — C → RADIO → V

RADIO 프레임워크 기반 대화형 설계 도구. C(Context)로 시작해 RADIO를 거쳐 V(Verification)로 마무리한다. D step에서 비즈니스 제품은 DDD로, 기술 라이브러리는 Library Design으로 딥다이브한다.

Gate In ─ C  Context        기존 코드·패턴·컨벤션 파악

          R  Requirements   문제 정의 + 기능/비기능 + 스코프 아웃
 RADIO    A  Architecture   주요 컴포넌트 + 책임 할당
          D  Data Model     엔티티 + 딥다이브(제품→DDD / 라이브러리→Library Design)
          I  Interface      경계를 넘는 계약 (API, props, 이벤트)
          O  Optimizations  NFR에서 도출된 항목만 (YAGNI)

Gate Out ─ V  Verification  Given/When/Then 핵심 3~5개

참조 스킬

  • design-radio — FE/BE별 RADIO 체크리스트
  • design-ddd — DDD 판단 기준 (비즈니스 도메인이 복잡할 때)
  • design-library — Library Design 판단 기준 (기술 라이브러리를 설계할 때)

핵심 원칙

  1. C(Gate In)와 V(Gate Out)는 항상 수행
  2. RADIO 깊이는 작업 규모에 맞춘다 — 아래 표 참조
  3. 한 단계씩 확정 — 이전 단계 합의 후 다음으로
  4. 함께 토론 — Claude는 대안/트레이드오프를 제시하고, 사용자가 결정
작업 규모Gate (C/V)RADIO 단계
소 (버그/1일)C, V (항상)R
중 (기능/1주)C, V (항상)R, D, I
대 (시스템/1달+)C, V (항상)R, A, D, I, O

Input

  • $ARGUMENTS.context: 설계할 기능 설명 (선택)

Execution Flow

Phase 0: 입력 수집

  1. 입력 파싱:

    입력 타입감지 방법처리
    없음$ARGUMENTS.context 비어있음AskUserQuestion: "어떤 기능을 설계할까요?"
    텍스트URL 아님그대로 작업 설명으로 사용
    Linear URLlinear.app 포함ToolSearch로 Linear MCP fetch
    GitHub URLgithub.com 포함gh issue view
    파일 경로로컬 경로 패턴Read로 기존 코드/문서 읽기
  2. 트랙 판별: FE / BE / 풀스택 — design-radio skill의 해당 체크리스트 참조에 사용

  3. 작업 규모 판별:

AskUserQuestion:
  "작업 규모는 어느 정도인가요?

  - 소 (버그 수정, 1일 작업) → C, R, V
  - 중 (기능 추가, 1주 작업) → C, R, D, I, V
  - 대 (시스템 설계, 1달+) → C, R, A, D, I, O, V 전체"

Step C: Context (Gate In)

design-explorer agent에 위임하여 코드베이스를 자율 탐색한다.

Task(subagent_type: "general-purpose", prompt: "
  design-explorer agent로 동작한다.

  ## 작업
  {$ARGUMENTS.context 또는 사용자 입력}

  ## 탐색 항목
  1. 재사용 가능한 기존 모듈/함수/컴포넌트 (파일 경로 포함)
  2. 프로젝트의 기존 패턴과 컨벤션
  3. 변경이 필요한 기존 코드 범위
  4. 관련 테스트 파일과 테스트 패턴

  ## 출력 형식
  ### 재사용
  - {모듈명}: {파일 경로} — {설명}

  ### 컨벤션
  - {패턴 요약}

  ### 변경 대상
  - {파일}: {변경 이유}
")

agent 결과를 사용자에게 공유하고 확인:

AskUserQuestion:
  "코드베이스를 파악했습니다.

  ## Context
  {agent 결과}

  빠진 것이나 수정할 부분이 있나요?"

Step R: Requirements

"무엇을 해야 하고, 무엇을 하지 않는가?"

AskUserQuestion:
  "요구사항을 정리합시다.

  1. 한 문장 정의: 'X를 하면 Y가 된다'
  2. 기능 요구사항: 핵심 유저 플로우
  3. 비기능 요구사항: 성능, 보안, 접근성 중 해당 항목
  4. 스코프 아웃: 이번에 하지 않는 것

  이미 정리한 것이 있으면 공유해주세요."

Claude의 역할 (design-radio skill 참조):

  • 한 문장 정의를 적을 수 없으면 → "아직 설계 준비가 안 된 것. PRD를 다시 확인합시다"
  • FE: 지원 디바이스/브라우저, 접근성 수준, Figma URL 확인
  • BE: API 소비자, 예상 트래픽, 데이터 일관성, 인증 모델 확인
  • 스코프 아웃 누락 시 → "이번에 하지 않는 것을 명시하지 않으면 범위가 늘어납니다"

작업 규모가 소이면 여기서 Step V로 건너뛴다.

Step A: Architecture (대 규모만)

"주요 조각은 무엇이고, 각각 무슨 책임을 가지는가?"

AskUserQuestion:
  "아키텍처를 잡아봅시다.

  주요 컴포넌트(3~7개)를 식별하고, 각 책임과 관계를 적어주세요.

  - {컴포넌트}: {한 줄 책임}
  - {컴포넌트} → {컴포넌트}: {통신 방식}

  이미 생각한 구조가 있으면 공유해주세요."

Claude의 역할 (design-radio skill 참조):

  • FE: Container/Presentational 구분, 상태 관리 전략, CSR/SSR 경계
  • BE: 서비스 경계, 호출 흐름(Presentation→Application→Domain), Port 추상화

Step D: Data Model

"어떤 데이터가 존재하고, 어디서 오고, 어디에 저장되는가?"

AskUserQuestion:
  "데이터 모델을 정의합시다.

  핵심 엔티티, 필드, 타입, 제약조건을 적어주세요.
  엔티티 간 관계도 포함해주세요.

  이미 정의한 것이 있으면 공유해주세요."

프로젝트 성격 판단 — 먼저 비즈니스 제품인지, 기술 라이브러리인지 판단한다:

Q: 이 코드의 주요 소비자는?
├─ 최종 사용자 (비즈니스 제품) → 도메인 복잡도 판단 → DDD 딥다이브
└─ 다른 개발자 (라이브러리/SDK/공유 모듈) → Library Design 딥다이브
경로 A: DDD 딥다이브 (비즈니스 제품)

도메인 복잡도 판단 — 아래 중 2개 이상 해당하면 DDD 딥다이브:

  • 상태 전이가 있다 (예: Draft → Active → Expired)
  • 비즈니스 규칙이 3개 이상이다
  • 여러 엔티티 간 불변식이 존재한다
  • "~할 수 없다" 형태의 제약이 많다

DDD 딥다이브 시 (design-ddd skill 참조):

추가 질문을 순서대로 진행한다:

  1. Aggregate 경계: "A를 변경할 때 B도 반드시 함께 변경되어야 하는가?"
  2. Entity vs Value Object: "고유 ID가 필요하고 상태가 변하는가?"
  3. 불변식: "각 Aggregate가 항상 보장해야 하는 조건은?"
  4. 책임 할당: "이 판단에 필요한 정보를 누가 갖고 있는가?"
  5. Domain Event: "A 성공 후 B가 알아야 할 때 어떤 이벤트?"

각 질문은 사용자와 AskUserQuestion으로 하나씩 확정한다.

경로 B: Library Design 딥다이브 (기술 라이브러리)

Library 복잡도 판단 — 아래 중 2개 이상 해당하면 Library Design 딥다이브:

  • 다른 개발자가 소비하는 코드이다 (패키지, SDK, 내부 공유 모듈)
  • 공개 API surface를 설계해야 한다
  • 하위 호환성/버전 관리를 고려해야 한다
  • 추상화 레벨 선택이 설계의 핵심이다

Library Design 딥다이브 시 (design-library skill 참조):

추가 질문을 순서대로 진행한다:

  1. Consumer Mental Model: "이 라이브러리의 소비자는 누구이고, 알아야 할 핵심 개념은?"
  2. API Surface: "무엇을 공개하고, 무엇을 숨기는가? Progressive Disclosure 3계층은?"
  3. Type Contract: "타입으로 잘못된 사용을 막을 수 있는가?"
  4. Extension Point: "소비자가 동작을 확장해야 하는 지점과 패턴은?"
  5. Stability: "하위 호환성, 의존성 관리, deprecation 정책은?"

각 질문은 사용자와 AskUserQuestion으로 하나씩 확정한다.

Step I: Interface Definition

"컴포넌트 간 경계에서 무엇이 오고 가는가?"

AskUserQuestion:
  "인터페이스를 정의합시다.

  각 경계의 Input/Output과 에러 처리를 적어주세요.

  이미 정의한 것이 있으면 공유해주세요."

Claude의 역할 (design-radio skill 참조):

  • FE: Component props, Hook API, 이벤트 핸들러, Route params
  • BE: 엔드포인트, Request/Response, 상태 코드, 인증
  • D와 일관성 검증

Step O: Optimizations (대 규모만)

"NFR에서 도출된 최적화는 무엇인가?"

AskUserQuestion:
  "R에서 식별한 NFR에서 최적화 항목을 도출합시다.

  형식: [{카테고리}] {항목} (NFR-{N}에서 도출)
  해당 없으면 '없음'."
  • 추측성 최적화 차단 → "R의 NFR에 없었습니다. 정말 필요한가요?"

Step V: Verification (Gate Out)

"이것이 완료되었다는 것을 어떻게 증명하는가?"

AskUserQuestion:
  "완료 조건을 정의합시다.

  Given/When/Then 형식으로 핵심 3~5개.
  순서: 정상 → 에러 → 엣지

  | # | Given | When | Then |

  이 TC를 모두 통과하면 '완료'입니다."

Claude의 역할 (design-radio skill 참조):

  • 정상/에러 케이스 1개 이상 확인
  • FE: 네트워크 실패, 빈 상태, 반응형, 접근성
  • BE: 4xx/5xx, 동시 요청, 권한 경계
  • 중복 TC 제거

설계 종합

모든 Step 완료 후 설계 문서를 생성한다.

  1. 파일: .claude/docs/{project-name}/design.md
  2. 구조: C → R → (A) → D → I → (O) → V 각 산출물 정리
  3. 딥다이브 결과 (해당 시):
    • DDD: Aggregate 구조, 불변식, Domain Event
    • Library Design: API Surface, Type Contract, Extension Point, Stability
AskUserQuestion:
  "설계를 정리했습니다.

  파일: .claude/docs/{project-name}/design.md

  선택:
  - 완료
  - TDD로 구현 진행 (/tdd:start)
  - 수정 필요"

넘어가기 처리

모든 Step에서 사용자가 "넘어가자", "네가 해줘"면:

  1. 지금까지 맥락으로 초안 작성
  2. "이대로 갈까요?" 확인
  3. 확인 후 다음 Step 진행

안티패턴

안티패턴문제해결
C 없이 R부터 시작기존 코드를 모르고 설계C(Gate In)부터
D와 I를 동시에데이터와 계약 뒤섞임D 먼저, I 다음
O에서 추측성 최적화YAGNI 위반R의 NFR에 없으면 안 함
V 없이 구현"완료" 미정의최소 3개 Given/When/Then
Domain이 Infra를 importDependency Rule 위반Port interface로 역전

Error Handling

상황대응
context 인자 없음AskUserQuestion으로 작업 설명 요청
Linear/GitHub fetch 실패텍스트로 직접 입력 요청
새 프로젝트 (기존 코드 없음)C에서 "컨벤션 없음" 기록 후 진행
한 문장 정의 불가PRD 재확인 안내

Example

사용자: /design 게시글에 좋아요 기능 추가

Claude: 작업 규모는? [AskUserQuestion: 소/중/대]

사용자: 중

Claude: [C] 코드베이스를 탐색합니다... (design-explorer agent 위임)
  → 재사용: ArticleEntity, reaction-api-client
  → 컨벤션: Entity Object 패턴, react-query
  빠진 것이 있나요? [AskUserQuestion]

사용자: 없음

Claude: [R] 요구사항을 정리합시다. [AskUserQuestion]

사용자: "좋아요 토글, 좋아요 수 표시"
  스코프 아웃: 알림, 좋아요 사용자 목록

Claude: NFR도 확인합시다 — 낙관적 업데이트 필요? 동시성?
  ... (D, I 진행) ...

Claude: [D] 데이터 모델 — 복잡도 판단: 단순 (DDD 불필요)
  → 인라인으로 데이터 모델링

  ... (I, V 진행) ...

Claude: 설계 정리 완료.
  .claude/docs/article-like/design.md
  선택: 완료 / TDD / 수정

Do Review Command

다른 사람의 PR을 P1/P2/P3 우선순위별로 코드 리뷰하고, 상호작용을 거쳐 GitHub에 리뷰를 게시한다.

  • P1 시스템 결함/오류: 런타임 에러, 보안 취약점, 데이터 손실, 경쟁 조건, 누락된 에러 처리
  • P2 설계 피드백: 아키텍처, 추상화(깊은 모듈/정보 누출), 인지 부하, 네이밍(오해 유발), 타입/API 설계, 성능
  • P3 컨벤션 피드백: 스타일, 마이너 네이밍, import 순서, 파일 구조, 코멘트 품질

Execution Flow

Phase 0: GitHub 계정 확인

~/.claude/rules/gh-auth.md의 "gh 명령어 실행 전 필수 확인" 절차를 따른다.

Phase 1: PR 입력 해석

$ARGUMENTS.pr_url 분석:

입력감지처리
없음비어있음AskUserQuestion: "리뷰할 PR URL 또는 번호를 입력하세요."
숫자만^\d+$현재 repo의 PR 번호로 사용
전체 URLgithub.com 포함owner/repo/number 파싱

다른 repo의 PR인 경우 --repo {owner}/{repo} 플래그를 사용한다.

Phase 2: PR 데이터 수집

  1. PR 메타데이터 수집:

    gh pr view {number} --repo {owner/repo} --json title,body,author,baseRefName,headRefName,files,additions,deletions,commits,state
    
  2. PR 상태 확인:

    • MERGED → AskUserQuestion: "이미 merge된 PR입니다. 리뷰를 계속할까요?"
    • CLOSED → "닫힌 PR입니다." 안내 후 종료
  3. 전체 diff 수집:

    gh pr diff {number} --repo {owner/repo}
    
  4. 변경 통계:

    gh pr diff {number} --repo {owner/repo} --stat
    
  5. 기존 리뷰 코멘트 조회 (중복 피드백 방지):

    gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[].body'
    
  6. 대규모 PR 처리 (변경 >5000줄):

    • "대규모 PR입니다 ({lines}줄). 핵심 파일 위주로 분석합니다." 안내
    • 생성 파일(lock, generated), 테스트 파일의 분석 우선순위를 낮추고 비즈니스 로직에 집중
  7. PR 개요 출력:

    ## PR 개요
    
    - PR: #{number} - {title}
    - Author: @{author}
    - Base: {base} <- {head}
    - 변경: +{additions} -{deletions}, {file_count}개 파일
    - 커밋: {commit_count}개
    
    ### 변경 파일
    {파일 목록 + 변경 통계}
    

Phase 3: 코드 분석 - P1/P2/P3 분류

diff와 변경 파일을 분석하여 발견 사항을 분류한다. 필요하면 변경 파일의 전체 컨텍스트를 Read로 확인한다.

각 finding 구조:

  • file: 파일 경로
  • line: 라인 번호 또는 범위 (diff 기준)
  • priority: P1/P2/P3
  • title: 한 줄 요약
  • body: 상세 설명
  • suggestion: (선택) 제안 코드

P1 시스템 결함/오류 체크리스트:

  • 런타임 에러 가능성 (null/undefined 접근, 타입 불일치)
  • 보안 취약점 (인젝션, 인증 우회, 노출된 시크릿)
  • 데이터 손실/손상 위험
  • 경쟁 조건, 데드락
  • API 계약 위반 (breaking change)
  • 핵심 경로의 누락된 에러 처리
  • off-by-one, 무한 루프

P2 설계 피드백 체크리스트:

  • 결합도/응집도 문제
  • 정보 누출 (한 모듈 수정 시 관련 없는 다른 파일까지 변경이 필요한가?)
  • 추상화 수준 — 얕은 모듈 (인터페이스 복잡도 > 내부 로직), 과도한 레이어 (단순 패스스루), 누수, YAGNI (이 추상화는 현재 문제를 위한 것인가, 혹시 모를 미래를 위한 것인가?)
  • 인지 부하 — 변수/조건이 과도한가? 몰라도 되는 옵션이 기본값 없이 노출되어 있진 않은가? (의도적 생략: "이 파라미터를 몰라도 기본 동작이 안전한가?")
  • 데이터 흐름 및 상태 관리
  • 에러 복구 전략 — 에러 발생 시 시스템이 안전한 상태를 유지하는가? 사용자 피드백과 상태 롤백이 설계되어 있는가?
  • 오해를 유발하는 네이밍 — 도메인 용어(Ubiquitous Language)와 코드 용어가 불일치하여 설계 문서 ↔ 코드 간 인지 전환 비용이 발생하는가?
  • 타입 정의 누락/부정확
  • API 설계 (함수 시그니처, 반환 타입)
  • 테스트 용이성 — 구현 세부사항이 아닌 클라이언트에 노출된 공개 인터페이스를 테스트하는 구조인가?
  • 도메인 순수성 — 도메인 로직이 UI/API/외부 의존성 없이 순수 함수로 분리되어 있는가?
  • 성능 영향이 있는 설계 선택

P3 컨벤션 피드백 체크리스트:

  • 코드 스타일 불일치
  • 마이너 네이밍 선호도 (오해 유발은 아니지만 개선 가능)
  • 코멘트 품질 (과도/부족)
  • import 순서
  • 파일 구조 선호도
  • 마이너 리팩토링 제안 (틀리진 않지만 더 깔끔할 수 있음)

Phase 4: P1 리뷰 - 시스템 결함/오류

AskUserQuestion:
  question: "## P1: 시스템 결함/오류 ({N}건)

  이 단계에서는 시스템 안정성에 직접 영향을 주는 문제에 집중합니다.

  {N > 0:}
  1. [{file}:{line}] {title}
     {body}
     ```suggestion (optional)
     {code}
     ```

  2. ...

  {N == 0:}
  P1 수준의 결함은 발견되지 않았습니다.

  선택:
  - 전체 승인: 모든 P1 코멘트 채택
  - 부분 승인: 번호 지정 (예: '1,3')
  - 수정: 특정 코멘트 수정 (예: '2번 톤 완화')
  - 추가: 직접 발견한 P1 항목 추가
  - 우선순위 변경: 항목을 P2/P3로 이동 (예: '3번 → P2')
  - P2로 건너뛰기: P1 전체 스킵"

사용자가 수정 또는 추가를 선택하면:

  • 수정: 해당 코멘트 내용을 변경 → 수정된 목록 다시 제시 → 승인 루프
  • 추가: 사용자 입력 받기 → 목록에 추가 → 다시 제시 → 승인 루프

사용자가 우선순위 변경을 선택하면:

  • 해당 항목을 지정된 우선순위로 이동 (Phase 5/6에서 표시됨)
  • 현재 목록에서 제거 → 다시 제시

Phase 5: P2 리뷰 - 설계 피드백

AskUserQuestion:
  question: "## P2: 설계 피드백 ({N}건)

  이 단계에서는 코드의 구조와 설계에 집중합니다:
  - 모듈이 복잡성을 충분히 숨기고 있는가? (깊은 모듈 지향)
  - 한 곳을 고칠 때 다른 곳까지 건드려야 하진 않는가?
  - 데이터 흐름이 명확한가?
  - 이름이 의도를 정확히 전달하는가?

  {findings list - Phase 4에서 이동된 항목 포함}

  선택:
  - 전체 승인 / 부분 승인 / 수정 / 추가 / 우선순위 변경 / P3로 건너뛰기"

Phase 4와 동일한 상호작용 패턴.

Phase 6: P3 리뷰 - 컨벤션 피드백

AskUserQuestion:
  question: "## P3: 컨벤션 피드백 ({N}건)

  이 단계에서는 스타일과 일관성에 집중합니다.
  (참고: P3는 nit 수준이므로 게시 여부를 신중히 판단하세요)

  {findings list - 이전 Phase에서 이동된 항목 포함}

  선택:
  - 전체 승인 / 부분 승인 / 수정 / 추가 / 전체 건너뛰기"

Phase 7: 리뷰 요약 및 게시

모든 우선순위 리뷰가 완료되면 최종 요약을 제시한다.

AskUserQuestion:
  question: "## 리뷰 요약

  ### 채택된 코멘트
  | 우선순위 | 건수 |
  |----------|------|
  | P1 시스템 결함 | {n}건 |
  | P2 설계 피드백 | {n}건 |
  | P3 컨벤션 피드백 | {n}건 |
  | 합계 | {total}건 |

  ### Review 이벤트 추천
  {P1 > 0: 'REQUEST_CHANGES 권장 — P1 결함이 있습니다.'}
  {P1 == 0 && P2 > 0: 'COMMENT 또는 REQUEST_CHANGES'}
  {P3만: 'COMMENT 또는 APPROVE'}
  {total == 0: '코멘트 없이 APPROVE 가능'}

  선택:
  - 일괄 게시 (REQUEST_CHANGES): 변경 요청과 함께 게시
  - 일괄 게시 (COMMENT): 코멘트로 게시
  - 일괄 게시 (APPROVE): 승인과 함께 게시
  - 저장만: 결과를 출력하고 게시하지 않음
  - 수정 후 게시: 전체 목록 재편집
  - 취소: 아무것도 하지 않음"

일괄 게시 선택 시 gh api로 단일 리뷰 이벤트를 생성한다:

gh api repos/{owner}/{repo}/pulls/{number}/reviews \
  --method POST \
  -f event="{APPROVE|COMMENT|REQUEST_CHANGES}" \
  -f body="{review summary}" \
  --input comments.json

Review body 형식:

## Code Review

| Priority | Count |
|----------|-------|
| P1 | {n} |
| P2 | {n} |
| P3 | {n} |

각 인라인 코멘트 형식:

**[P1]** {title}

{body}

저장만 선택 시 전체 리뷰 내용을 콘솔에 출력한다.

Phase 8: 완료 보고

## 리뷰 게시 완료

- PR: #{number} - {title}
- Review 이벤트: {event type}
- 게시 코멘트: P1({n}) + P2({n}) + P3({n}) = {total}건
- PR URL: {url}

Error Handling

상황대응
PR 없음"PR #{number}을 찾을 수 없습니다. URL과 권한을 확인하세요."
이미 merge/close된 PRAskUserQuestion으로 계속 여부 확인
대규모 diff (>5000줄)핵심 파일 위주 분석, 안내 메시지 출력
발견 사항 없음"리뷰할 항목이 없습니다. Approve 하시겠습니까?"
gh api 실패에러 표시, 재시도 또는 로컬 저장 제안
잘못된 PR URL 형식파싱 실패 시 AskUserQuestion으로 재입력 요청

Paper — 논문 학습 워크플로우

논문 발견 → 구조화된 요약 → 대화형 Q&A 학습 → 노트 저장.

Phase 0 ─ 입력 수집     URL/주제/없음 분기
Phase 1 ─ Discovery     WebSearch로 논문 탐색 → 선택
Phase 2 ─ Summary       목차 + 섹션별 요약 제공
Phase 3 ─ Q&A           인터랙티브 학습 루프
Phase 4 ─ Notes         학습 노트 마크다운 저장

핵심 원칙

  1. 한 Phase씩 진행 — 이전 Phase 확인 후 다음으로
  2. 사용자 수준에 맞춤 — 빠르면 심화, 어려우면 기초부터
  3. 논문 내용 기반 답변 — 추측 금지, 모르면 WebSearch로 보충
  4. 저작권 준수 — 논문 원문을 그대로 복사하지 않고 자신의 언어로 요약

Input

  • $ARGUMENTS.context: 논문 URL, DOI, 또는 검색 주제 (선택)

Execution Flow

Phase 0: 입력 수집

  1. 입력 파싱:

    입력 타입감지 방법처리
    없음$ARGUMENTS.context 비어있음AskUserQuestion: "어떤 주제의 논문을 읽고 싶으세요?"
    주제/키워드URL 패턴 아님Phase 1(Discovery)로
    arXiv URLarxiv.org 포함Phase 2(Summary)로 직행
    Semantic Scholarsemanticscholar.org 포함Phase 2로 직행
    DOIdoi.org 또는 10. 패턴WebFetch로 논문 페이지 접근 → Phase 2
    기타 URLURL 패턴WebFetch 시도 → Phase 2

Phase 1: Discovery (발견)

  1. WebSearch로 관련 논문 검색:

    • 쿼리 전략: {주제} research paper site:arxiv.org OR site:semanticscholar.org
    • 추가 쿼리: {주제} survey paper (서베이 논문 포함)
  2. 검색 결과에서 논문 5~8개 리스트 제시:

| # | 제목 | 저자 | 연도 | 출처 | 한 줄 요약 |
|---|------|------|------|------|------------|
| 1 | ... | ... | ... | arXiv | ... |
  1. AskUserQuestion으로 읽을 논문 선택:
AskUserQuestion:
  questions:
    - question: "어떤 논문을 읽어볼까요?"
      multiSelect: true
      options:
        - "{제목 1}"
        - "{제목 2}"
        - ...
        - "다른 키워드로 다시 검색"
  • "다른 키워드로 다시 검색" 선택 시 → Phase 0로 복귀
  • 여러 논문 선택 시 → 첫 번째 논문부터 순서대로 Phase 2 진행

Phase 2: Summary (요약)

  1. WebFetch로 논문 페이지 내용 수집:

    • arXiv: arxiv.org/abs/{id} 페이지 fetch → abstract, 메타데이터 추출
    • arXiv HTML 버전이 있으면: arxiv.org/html/{id} 도 fetch하여 본문 구조 파악
    • Semantic Scholar: API 또는 페이지에서 abstract, citations 추출
    • 일반 URL: WebFetch로 본문 추출 시도
    • PDF만 있는 경우: abstract 페이지나 Semantic Scholar에서 메타데이터 수집, 본문은 제한적
  2. 구조화된 요약 생성:

## {논문 제목}

- **저자**: {저자 목록}
- **연도/학회**: {연도, 학회 또는 저널}
- **링크**: {URL}

### 핵심 요약 (3문장)
{논문의 목적, 방법, 결과를 각 1문장으로}

### 목차
1. {섹션명} — {한 줄 설명}
2. {섹션명} — {한 줄 설명}
...

### 주요 기여 (Contributions)
- {기여 1}
- {기여 2}
- {기여 3}

### 핵심 키워드
{키워드1}, {키워드2}, ...
  1. AskUserQuestion으로 다음 단계 결정:
AskUserQuestion:
  questions:
    - question: "요약을 확인했습니다. 어떻게 진행할까요?"
      options:
        - "Q&A 학습 시작"
        - "특정 섹션을 더 자세히 보고 싶어요"
        - "다른 논문 선택"
  • "Q&A 학습 시작" → Phase 3
  • "특정 섹션을 더 자세히 보고 싶어요" → 어떤 섹션인지 추가 질문 → 해당 섹션 심화 요약 → 다시 이 질문
  • "다른 논문 선택" → Phase 1로 복귀

Phase 3: Interactive Q&A (학습)

인터랙티브 학습 루프 진입. 아래를 반복한다:

AskUserQuestion:
  questions:
    - question: "논문에 대해 궁금한 점이 있으세요?"
      options:
        - "특정 섹션을 자세히 설명해줘"
        - "핵심 개념을 쉽게 풀어줘"
        - "이 논문의 한계점은?"
        - "관련 논문/후속 연구는?"
        - "실무에 어떻게 적용할 수 있을까?"
        - "학습 종료"

답변 가이드라인:

  • 논문 내용을 기반으로 답변. 필요시 WebSearch로 추가 맥락 확보
  • 비유와 예시로 복잡한 개념 설명
  • 관련 섹션 번호 참조 표시 (예: "섹션 3.2에서 설명하는...")
  • 한 번에 너무 많은 정보를 주지 않고, 단계적으로 설명

난이도 적응:

  • 사용자가 빠르게 이해하면 → 더 심화된 질문 유도 ("이 부분을 더 깊이 파볼까요?")
  • 사용자가 어려워하면 → 기초 개념부터 단계적 설명
  • "왜?"라고 물으면 → 논문의 motivation과 배경부터 설명

"학습 종료" 선택 시 → Phase 4로 이동

Phase 4: Notes (학습 노트 저장)

학습 종료 시 자동으로 마크다운 파일 생성.

  1. 파일 위치: .claude/docs/paper-notes/{논문-slug}.md

    • slug: 논문 제목에서 kebab-case 변환 (예: attention-is-all-you-need)
  2. 노트 구조:

# {논문 제목}

- **저자**: {저자 목록}
- **연도**: {연도}
- **링크**: {URL}
- **학습일**: {오늘 날짜, YYYY-MM-DD}

## 핵심 요약
{Phase 2에서 생성한 3문장 요약}

## 목차 & 섹션 요약
{Phase 2에서 생성한 목차 + 섹션별 설명}

## Q&A 학습 노트
### Q: {사용자 질문 1}
{답변 핵심 내용 요약}

### Q: {사용자 질문 2}
{답변 핵심 내용 요약}
...

## 핵심 인사이트
- {학습 세션에서 도출된 주요 깨달음 3~5개}

## 관련 논문 / 후속 학습
- {Q&A 중 언급된 관련 논문이나 키워드}
  1. 파일 저장 후:
AskUserQuestion:
  questions:
    - question: "학습 노트를 저장했습니다. 다른 논문도 읽어볼까요?"
      options:
        - "네, 다른 논문 탐색"
        - "아니요, 종료"
  • "네, 다른 논문 탐색" → Phase 1로 복귀
  • "아니요, 종료" → 세션 종료

Error Handling

상황대응
context 인자 없음AskUserQuestion으로 주제 요청
WebSearch 결과 부족키워드 변경 제안, 일반 웹 검색으로 대체
WebFetch 실패Semantic Scholar API로 대체, 또는 다른 소스 시도
PDF만 있고 HTML 없음abstract/메타데이터 위주로 요약, 본문 상세 분석 한계 안내
논문 내용 접근 불가사용자에게 로컬 PDF 경로 제공 요청 (Read로 읽기)

Example

사용자: /paper attention mechanism in transformers

Claude: [Phase 1] WebSearch로 관련 논문을 검색합니다...

  | # | 제목 | 저자 | 연도 |
  |---|------|------|------|
  | 1 | Attention Is All You Need | Vaswani et al. | 2017 |
  | 2 | BERT: Pre-training of... | Devlin et al. | 2019 |
  | ...

  어떤 논문을 읽어볼까요? [AskUserQuestion, multiSelect]

사용자: 1번 선택

Claude: [Phase 2] 논문을 분석합니다...

  ## Attention Is All You Need
  - 저자: Vaswani et al.
  - 핵심 요약: ...
  - 목차:
    1. Introduction — 기존 seq2seq의 한계
    2. Background — attention 메커니즘 배경
    ...

  어떻게 진행할까요? [AskUserQuestion]

사용자: Q&A 학습 시작

Claude: [Phase 3] 논문에 대해 궁금한 점이 있으세요? [AskUserQuestion]

사용자: self-attention이 뭐야?

Claude: Self-attention은... (비유와 예시로 설명)
  논문에 대해 또 궁금한 점이 있으세요?

사용자: 학습 종료

Claude: [Phase 4] 학습 노트를 저장합니다...
  파일: .claude/docs/paper-notes/attention-is-all-you-need.md
  다른 논문도 읽어볼까요?

PR Review Command

현재 작업 브랜치에 연결된 PR의 리뷰 코멘트를 확인하고, 필요한 변경사항을 반영한 뒤 push하고, 처리된 코멘트를 resolve합니다.

Execution Flow

Step 0: GitHub 계정 확인 (gh auth)

~/.claude/rules/gh-auth.md의 "gh 명령어 실행 전 필수 확인" 절차를 따른다.

Step 1: 현재 PR 식별

  1. gh pr view --json number,url,title,headRefName 실행하여 현재 브랜치의 PR 정보 확인
  2. PR이 없으면 에러 메시지 출력 후 종료

Step 2: 리뷰 코멘트 수집

  1. gh api repos/{owner}/{repo}/pulls/{pr_number}/comments 로 PR review comments 수집
  2. gh pr view {pr_number} --json comments 로 일반 코멘트도 수집
  3. 이미 resolved된 코멘트는 제외 (outdated이거나 resolved인 것)
  4. 수집된 코멘트 목록을 정리

Step 3: 코멘트 분류

각 코멘트를 분석하여 두 그룹으로 분류:

반영 필요 (actionable):

  • 코드 수정을 요구하는 코멘트 (버그 지적, 로직 개선 제안, 네이밍 변경 등)
  • 구체적인 변경사항이 명확한 코멘트
  • suggestion 코드 블록이 포함된 코멘트

반영 불필요 (non-actionable):

  • 단순 질문이나 확인 요청 (코드 변경 없음)
  • 칭찬/승인 코멘트
  • 이미 반영된 내용에 대한 코멘트
  • 의견 차이로 논의가 필요한 코멘트 (코드 변경보다 답변이 필요)
  • 사소한 스타일 취향 차이 (프로젝트 컨벤션에 위배되지 않는 경우)

분류 결과를 사용자에게 표시:

## 리뷰 코멘트 분류 결과

### 반영 예정 (N건)
1. @reviewer - file.ts:42 - "변수명을 더 명확하게 변경해주세요" → 반영 이유: ...
2. ...

### 반영 불필요 (M건)
1. @reviewer - "LGTM!" → 사유: 승인 코멘트
2. ...

Step 4: 코드 변경 반영

각 actionable 코멘트에 대해:

  1. 해당 파일과 위치를 확인
  2. 코멘트의 요청사항을 반영하여 코드 수정
  3. suggestion 블록이 있으면 해당 내용을 그대로 적용

Step 5: Push

모든 변경사항 반영 후 /pr {pr_number} command를 사용하여 커밋 & push

Step 6: 코멘트 Resolve

반영 완료된 코멘트들을 resolve 처리:

  1. 각 반영된 review comment의 thread를 gh api 를 사용하여 resolve
    • GraphQL mutation 사용: resolveReviewThread
    • gh api graphql -f query='mutation { resolveReviewThread(input: { threadId: "..." }) { thread { isResolved } } }'
  2. resolve할 thread ID는 gh api graphql 쿼리로 PR의 review threads를 조회하여 획득

Step 7: 완료 보고

## PR 리뷰 반영 완료

- PR: #{pr_number} - {title}
- 반영된 코멘트: N건
- 반영하지 않은 코멘트: M건
- 커밋: {commit_hash}
- PR URL: {url}

### 반영 상세
1. {파일}:{라인} - {변경 요약}
...

### 미반영 코멘트 (필요시 수동 확인)
1. @{reviewer} - "{코멘트 요약}" - 사유: {미반영 이유}
...

PR 생성 Command

현재 작업 브랜치의 변경사항을 커밋하고 GitHub PR을 생성합니다.

인자

  • 인자 없음: draft PR 생성
  • ready: ready-for-review PR 생성
  • PR URL 또는 번호: 해당 PR에 변경사항 push (새 PR 생성하지 않음)

Execution Flow

Step 0: GitHub 계정 확인 (gh auth)

~/.claude/rules/gh-auth.md의 "gh 명령어 실행 전 필수 확인" 절차를 따른다.

Step 1: 상태 확인

  1. git status로 변경사항 확인
  2. git diff --stat로 변경 파일 확인
  3. git log --oneline -5로 최근 커밋 스타일 확인
  4. 변경사항이 없으면 "커밋할 변경사항이 없습니다." 출력 후 종료

Step 1.5: Pre-flight Checks

변경사항을 커밋하기 전에 코드 품질 검사를 실행한다. 문제가 발견되면 자동 수정을 시도하고, 수정 불가 시 사용자에게 결정을 요청한다.

1. 프로젝트 도구 감지

패키지 매니저:

  • pnpm-lock.yaml 존재 → PM="pnpm"
  • yarn.lock 존재 → PM="yarn"
  • 그 외 → PM="npx"

타입 체커:

  • Glob("tsconfig.json") 존재 → {PM} tsc --noEmit

린터:

  • Glob("biome.json") 또는 Glob("biome.jsonc") → biome
    • 검사: {PM} biome check .
    • 자동수정: {PM} biome check --write .
  • Glob(".eslintrc.*") 또는 Glob("eslint.config.*") → eslint
    • 검사: {PM} eslint .
    • 자동수정: {PM} eslint --fix .

테스트 프레임워크:

  • Glob("vitest.config.*") → {PM} vitest run
  • Glob("jest.config.*") 또는 package.json jest → {PM} jest
  • Glob("pytest.ini") 또는 Glob("pyproject.toml") → pytest
  • Glob("go.mod") → go test ./...

감지된 도구가 하나도 없으면 이 Step을 건너뛰고 Step 2/3으로 진행한다.

2. 검사 실행 및 자동 수정

검사 순서: typecheck → lint → tests (앞 단계 수정이 뒷 단계 오류를 줄인다)

최대 재시도: 전체 수정 사이클 3회

retry = 0
while retry < 3:
  1. TypeScript 타입 체크 (감지된 경우)
     → 실패 시: 에러 출력 분석, Read로 파일 확인, Edit로 수정 → retry++, 루프 처음부터

  2. 린트 (감지된 경우)
     → 실패 시 첫 시도: --write/--fix 자동수정 실행
     → 이후 시도: Read/Edit로 수동 수정
     → retry++, 루프 처음부터 (typecheck 재실행하여 회귀 방지)

  3. 테스트 (감지된 경우)
     → 실패 시: 소스 코드 수정 (테스트 파일은 건드리지 않음)
     → retry++, 루프 처음부터 (typecheck, lint 재실행하여 회귀 방지)

  모두 통과 → break
3. 자동 수정 실패 시 사용자 결정

3회 재시도 후에도 실패하면:

AskUserQuestion:
  "Pre-flight check 실패: {실패한 검사}

  오류:
  {핵심 에러 메시지}

  선택:
  - 무시하고 진행: 현재 상태로 커밋 & PR 생성
  - 중단: PR 생성을 중단하고 수동 수정
  - 재시도: 추가 컨텍스트 제공 후 다시 시도"
  • 무시하고 진행 → Step 2/3으로 진행 (자동 수정으로 변경된 파일도 함께 staging)
  • 중단 → 명령어 종료
  • 재시도 → 사용자 컨텍스트 반영하여 추가 3회 시도
4. 검사 결과 기록

모든 검사가 완료되면 결과를 기록해 둔다. Step 3에서 PR 본문에 포함한다.

Step 2: 기존 PR Push 모드 (PR URL/번호가 인자로 제공된 경우)

  1. 변경된 파일을 staging
  2. 변경 내용을 분석하여 커밋 메시지 작성
  3. git push로 기존 PR 브랜치에 push
  4. PR URL 출력 후 종료

Step 3: 새 PR 생성 모드

  1. 변경된 파일을 staging (.env, credentials 등 민감파일 제외)
  2. 변경 내용을 분석하여 커밋 메시지 작성
  3. 커밋 생성
  4. 원격에 push (git push -u origin HEAD)
  5. gh pr create 실행:
    • --draft (기본) 또는 ready 모드
    • 제목: 70자 이내, 변경 핵심 요약
    • 본문: Summary bullet points + Test plan
  6. PR URL 출력

커밋 메시지 규칙

  • 변경 성격을 정확히 반영 (add/update/fix/refactor)
  • 1-2문장, "why" 중심
  • Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

PR 본문 형식

## Summary
- {변경사항 1}
- {변경사항 2}

## Pre-flight Checks
- [x] TypeScript type check       ← 통과 시
- [x] Biome lint                   ← 통과 시
- [x] Tests (vitest)               ← 통과 시
- [ ] Tests (not detected)         ← 감지 안 된 항목
- ⚠️ Lint (skipped by user)        ← 사용자가 건너뛴 항목

## Test plan
- [ ] {테스트 항목}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

TDD Design Command

/tdd:spec의 결과물을 기반으로 데이터 모델(API 기반 interface)과 클라이언트 컴포넌트를 설계한다.

Prerequisites

  • 필수: /tdd:spec 실행 완료 → .claude/docs/{project-name}/meta.yaml 존재
  • 필수 스킬: fe-techspec - 설계 패턴 참조
  • 선택 스킬: entity-object-pattern - 구현 시 Refactor 단계에서 참조
  • 필수 MCP: Linear plugin (문서 읽기/업데이트)
  • 선택 MCP: Figma plugin (컴포넌트 상세 분석 시)

Execution Flow

Phase 1: 메타데이터 로드 및 Linear 문서 조회

  1. .claude/docs/ 하위에서 프로젝트 메타데이터 파일을 찾는다:
    Glob(pattern: ".claude/docs/*/meta.yaml")
    
  2. 여러 프로젝트가 있으면 AskUserQuestion으로 선택 요청
  3. meta.yaml에서 document.id, document.url, sources.figma 등 메타데이터를 읽는다
  4. Linear에서 TechSpec 문서 내용을 조회한다:
    ToolSearch(query: "select:mcp__plugin_linear_linear__get_document")
    → mcp__plugin_linear_linear__get_document(id: "{document.id}")
    
    • 문서 내용에서 Functional Requirements (Given/When/Then) 섹션 추출
    • 문서 내용에서 Non-Functional Requirements 섹션 추출 (있는 경우)
    • get_document 도구가 없으면, 사용자에게 Linear URL을 안내하고 수동 확인 요청

Phase 1.5: 설계 초안 수집 (필수)

tdd-designer agent에 위임하기 전에 인간의 설계 초안을 수집한다. 초안이 제공될 때까지 Phase 2-3으로 진행하지 않는다.

AskUserQuestion:
  question: "설계 초안을 공유해주세요. 이 초안을 기반으로 설계를 발전시킵니다.

  예시 형식:
  ### 핵심 결정
  - 컴포넌트: CartPage → CartList + CartItem으로 분리
  - 데이터: 기존 useCartQuery 훅 재사용

  ### 열린 질문
  - 수량 변경 UI를 인라인으로 할지 모달로 할지?

  자유 형식도 괜찮습니다.

  설계 시 고려하면 좋은 포인트:
  - 모듈 경계: 이 구조에서 한 모듈을 수정할 때 다른 파일까지 함께 고쳐야 하진 않는가?
  - 추상화 깊이: 모듈이 내부 복잡성을 충분히 숨기는가, 아니면 인터페이스만 복잡한 얕은 모듈인가?
  - 인지 부하: 이 설계를 이해하려면 한 번에 기억해야 할 개념이 몇 개인가? 몰라도 되는 옵션은 기본값으로 숨겼는가?
  - 데이터 흐름: 상태가 어디서 생성되고, 어떻게 흘러가며, 누가 변경하는가?
  - 에러 복구: 에러 발생 시 사용자에게 어떤 피드백을 주고, 상태를 어떻게 안전하게 되돌리는가?
  - 도메인 순수성: 도메인 로직이 UI/API/외부 의존성 없이 순수 함수로 분리되는가?
  - 테스트 경계: 테스트가 구현 세부사항이 아닌, 클라이언트에 노출된 공개 인터페이스를 검증하는 구조인가?
  - API 계약: 서버 데이터를 어떤 hook/endpoint로 조회하고, 어떤 hook으로 변경하는가?
  - 데이터 분류: 이 데이터는 서버에서 오는가, 클라이언트에서만 존재하는가? 영속적인가 휘발성인가?
  - 컴포넌트 계약: 이 컴포넌트의 Props Interface를 외부 소비자 관점에서 정의할 수 있는가?
  - 도메인 언어: 코드의 변수명/함수명이 팀의 비즈니스 용어와 일치하는가?
  - YAGNI: 이 구조에 현재 요구사항이 필요로 하지 않는 확장 포인트나 레이어가 있진 않은가?"

Phase 2-3: 설계 (tdd-designer agent 위임)

데이터 모델, Usecase, Component, Visual Contract 설계를 tdd-designer agent에 위임한다.

Task(
  subagent_type: "tdd-designer",
  prompt: """
  다음 설계 초안과 TechSpec을 기반으로 Domain Model + Interface Contract + Client Architecture를 설계해주세요.

  ## 설계 초안 (인간 제공, 필수)
  {Phase 1.5에서 수집한 인간의 설계 초안}

  ## TechSpec Functional Requirements
  {Linear 문서에서 추출한 Given/When/Then 섹션 전문}

  ## Non-Functional Requirements (있는 경우)
  {Linear 문서에서 추출한 NFR 섹션, 없으면 "없음"}

  ## Figma URL (있는 경우)
  {meta.yaml의 sources.figma 값, 없으면 "없음"}

  ## 기존 Design 섹션 (업데이트 시)
  {기존 Design 내용, 최초 생성이면 "없음"}
  """
)

agent 반환 결과: 아래 섹션이 포함된 마크다운

  • ## Design (데이터 모델, Usecase, Interface Contract, Component & Visual Contract, Usecase-Component Integration, Optimization Checklist)
  • ## Component & Code - Client
  • ## Verification

Phase 4: Linear 문서 업데이트

⚠️ 로컬 파일 수정 없음 - Linear 문서만 업데이트한다 (Single Source of Truth)

meta.yaml의 document.id로 TechSpec 문서에 Design 섹션을 추가한다:

ToolSearch(query: "select:mcp__plugin_linear_linear__update_document")
→ mcp__plugin_linear_linear__update_document(
    id: "{document.id}",
    content: "{기존 내용 + 아래 섹션 추가}"
  )

tdd-designer agent가 반환한 마크다운(Design, Component & Code, Verification 섹션)을 Linear 문서에 그대로 업데이트한다.

Phase 5: 결과 보고

Design 완료!

Domain Model:
- 데이터 모델: {interface list} (Server-origin: {N}개, Client-only: {N}개)
- Usecases: {usecase list}

Interface Contract:
- Server-Client: {N}개 hooks (query: {N}, mutation: {N})
- Client-Client: {N}개 핵심 Props Interfaces

Client Architecture:
- Pages: {page list}
- Components: {N}개
- Shared: {shared component list}

Optimization: {N}개 항목 적용 (해당 시)

Linear Document: {document URL} (Design 섹션 업데이트됨)
* 로컬 파일 수정 없음 - Linear가 Single Source of Truth

다음 단계:
1. Linear에서 설계를 리뷰하세요
2. /tdd:issues 로 Linear 이슈를 생성하세요

Error Handling

상황대응
meta.yaml이 없음/tdd:spec을 먼저 실행하라고 안내
Linear 문서 조회 실패사용자에게 Linear URL 안내, 수동 확인 요청
Linear 문서에 테스트 케이스가 없음최소한의 데이터 모델/Usecase를 제안하고 확인 요청
Figma URL이 없음테스트 케이스만으로 컴포넌트 설계 진행
Linear 문서 업데이트 실패에러 메시지 출력, 재시도 안내

Example

사용자: /tdd:design

Claude: .claude/docs/에서 메타데이터 파일을 찾고 있습니다...
  → .claude/docs/my-feature/meta.yaml 발견

Claude: Linear에서 TechSpec 문서를 조회합니다...
  → document.id: abc123

Claude: 설계 초안을 공유해주세요. 이 초안을 기반으로 설계를 발전시킵니다.
  [AskUserQuestion]

사용자:
  ### 핵심 결정
  - 컴포넌트: CartPage → CartContainer + CartList + CartItem으로 분리
  - 데이터: 기존 useCartQuery 훅 재사용, CartData는 API 타입 참조
  - 상태: React Query로 서버 상태, 수량 편집은 로컬 useState

  ### 열린 질문
  - QuantitySelector를 공용 컴포넌트로 뺄지 도메인 전용으로 둘지?

Claude: 초안을 기반으로 TC와 교차 검증하며 설계합니다...

Claude: Design 완료!
  Domain Model:
  - 데이터 모델: CartData (API 참조), ProductData (API 참조) (Server-origin: 2개, Client-only: 1개)
  - Usecases: AddToCart, RemoveFromCart, UpdateQuantity

  Interface Contract:
  - Server-Client: 3개 hooks (query: 1, mutation: 2)
  - Client-Client: 2개 핵심 Props Interfaces

  Client Architecture:
  - Pages: CartPage
  - Components: 8개
  - Shared: Button, QuantitySelector

  Optimization: 3개 항목 적용 (캐시 전략, Optimistic update, 에러/로딩 상태)

  초안 반영:
  - 반영: CartContainer/CartList/CartItem 분리, useCartQuery 재사용, React Query + useState
  - 충돌: 없음
  - 열린 질문 → 제안: QuantitySelector는 다른 도메인에서도 재사용 가능하므로 공용 추천

  Linear Document: https://linear.app/daangn/document/fe-techspec-xxx (Design 섹션 추가됨)

TDD Implement Command

/tdd:spec, /tdd:design, /tdd:issues의 결과물을 기반으로 구현을 시작한다.

핵심 원칙: 단일 Task 생성 후 Workspace가 자율 실행, Phase 사이 Human Review

각 issue당 하나의 vk task를 생성한다. Task description에 Red→Green→Refactor 전체 워크플로우와 Review Gate를 포함한다. Workspace agent가 이를 순차적으로 실행하며, 각 phase 완료 시 AskUserQuestion으로 인간 리뷰를 받는다.

Workspace 내부 흐름:
Red      → 테스트 작성 & commit                        → 🔍 Review Gate 1: 인간 리뷰
Green    → 구현 코드 commit                           → 🔍 Review Gate 2: 인간 리뷰
Visual   → Figma 비교 & Storybook/Preview (Figma URL 있을 시) → 🔍 Review Gate 2.5: 인간 리뷰
Refactor → 리팩토링 commit & push → Draft PR 생성 → Linear 동기화 → 🔍 Review Gate 3: 최종 리뷰
최종 승인 → Draft PR → Ready for Review (open)

implement command는 task를 생성하고 session을 시작하는 역할만 한다. 재실행 시에는 vk issue 상태를 확인하여 다음 batch 진행 여부를 결정한다.

Usage

/tdd:implement [--base <branch>]

Parameters

ParameterDescriptionExample
--base <branch>PR의 target branch를 직접 지정. implement.yaml 설정을 override함--base feature/new-cart

Examples

# 기본 실행 (첫 실행이면 Batch 1 task 생성, 재실행이면 상태 확인)
/tdd:implement

# base branch 직접 지정
/tdd:implement --base feature/checkout

Prerequisites

  • 필수: .claude/docs/{project-name}/meta.yaml 존재 (/tdd:spec 실행 결과)
  • 필수: Linear TechSpec 문서에 /tdd:design 결과물 포함 (Design 섹션)
  • 필수: meta.yaml의 project.id로 Linear에서 "tdd" label issue 조회 가능 (/tdd:issues)
  • 필수 MCP: vibe_kanban, Linear plugin

Execution Flow

Phase 1: 메타데이터 로드 및 상태 확인

  1. 파라미터 파싱: --base <branch> 파라미터 저장

  2. .claude/docs/{project-name}/implement.yaml 존재 여부 확인:

    • 파일이 없으면 → 첫 실행: Phase 2로 진행
    • 파일이 있으면 → vk issue 상태 조회:
    현재 batch의 모든 task_id에 대해:
      ToolSearch(query: "select:mcp__vibe_kanban__get_issue")
      get_issue(issue_id: "{task_id}")
      → status 확인
    
    모든 task completed →
      다음 batch 있으면 batch+1로 진행
      없으면 → qa_verified 필드 확인:
        - qa_verified: true → "done" (모든 구현 및 QA 완료)
        - qa_verified 없음 또는 false → Phase 6.5 (QA) 진행
    일부 task 미완료 → 진행 상황 보고:
      - 각 task의 현재 상태 표시
      - "진행 중인 워크스페이스를 완료시켜주세요" 안내
    
    • --base 파라미터가 있으면 implement.yaml의 base_branch override
  3. .claude/docs/{project-name}/meta.yaml에서 project.id를 추출한다

  4. Linear에서 issue를 조회한다:

    ToolSearch(query: "select:mcp__plugin_linear_linear__list_issues")
    list_issues(project: "{project-id}", labels: ["tdd"])
    
    • 응답에서 각 issue의 id (Linear API용)와 url을 추출하여 저장
  5. 조회된 issue 목록을 Blocker/Related로 분류한다

  6. 병렬 실행 가능한 issue 배치를 결정한다:

병렬화 규칙:

  • Batch 1: Blocker issues (서로 의존성 없는 Blocker끼리는 병렬 가능)
  • Batch 2: Related issues (Blocker 완료 후 병렬 실행)
Batch 1 (병렬): [Blocker A] [Blocker B] [Blocker C]
  ↓ 완료 대기
Batch 2 (병렬): [Related D] [Related E] [Related F]
  1. AskUserQuestion으로 실행할 배치를 확인:
    question: "다음을 실행합니다. 진행할까요?"
    
    Batch 1 (Red→Green→Refactor, 각 phase 후 리뷰)
    - {issue title} → workspace session
    - {issue title} → workspace session
    

Phase 2: Vibe Kanban 프로젝트, Base Branch, 참여 Repo 설정

재실행(implement.yaml 존재) 시 이 Phase는 저장된 값을 사용하여 건너뜀

  1. vibe kanban 프로젝트를 확인한다:

    ToolSearch(query: "select:mcp__vibe_kanban__list_projects")
    
  2. 프로젝트가 없거나 매칭되지 않으면 AskUserQuestion으로 선택 요청

  3. Base Branch 지정 (우선순위: 파라미터 > implement.yaml > 대화형 입력):

    3-1. 파라미터 확인 (최우선)

    • --base <branch> 파라미터가 제공되었으면 → 해당 branch 사용

    3-2. implement.yaml 존재 여부 확인

    • 파일이 있으면 → vibe_kanban.base_branch 읽음 (재실행)

    3-3. 첫 실행 시 사용자에게 base branch 물어보기:

    question: "이 implementation의 base branch를 지정하세요."
    
    현재 git branch: feature/new-cart
    기본값: feature/new-cart
    또는 다른 branch: [main / develop / feature/new-api / ...]
    
  4. 참여할 repo 선택:

    ToolSearch(query: "select:mcp__vibe_kanban__list_repos")
    → list_repos(project_id: "{project_id}")
    

    AskUserQuestion으로 참여 repo 선택:

    question: "이 feature에 참여할 repo를 선택하세요. (복수 선택 가능)"
    
    [ ] Frontend (repo-1-id)
    [ ] Backend API (repo-2-id)
    

Phase 3: Issue별 Repo & Package 매핑

Linear issue description의 "작업 대상" 섹션에서 패키지 정보를 추출한다:

  1. Repo 매핑: Issue 설명의 패키지 경로로 repo 식별
  2. Package 정보 추출: Linear issue의 "작업 대상" 섹션에서 package_name, package_path, target_directory, reference_pattern 추출
  3. 정보가 없으면 TechSpec Design 섹션의 "Component & Code" 파일 구조에서 직접 추출
  4. 명확하지 않으면 AskUserQuestion으로 확인

Phase 3.5: 현재 Batch의 Base Branch 결정

현재 batch에 따라 workspace session과 PR의 base branch를 결정한다:

Batch 1 (첫 배치):

  • base_branch = implement.yaml의 vibe_kanban.base_branch (프로젝트 base branch)

Batch 2+ (이전 배치 존재):

  1. 이전 batch의 task_id들로 vk issue를 조회하여 관련 PR 정보 파악
  2. 또는 gh pr list 등으로 GitHub에서 직접 branch 정보 조회
  3. 이전 batch에 issue가 1개면: 해당 issue의 branch를 base로 사용
  4. 이전 batch에 issue가 여러 개면: 프로젝트 base branch를 사용 (이전 batch PR들이 이미 merge되었어야 함)
  5. ⚠️ 판단이 어려우면: AskUserQuestion으로 사용자에게 base branch 확인

결정된 base branch를 이후 모든 workspace session과 task description에 사용.

Phase 4: Task 생성 및 Session 시작

현재 batch의 각 issue에 대해 vk task를 생성하고 workspace session을 시작한다.

핵심: task를 한번 생성하면 update하지 않는다. Workspace agent가 Red→Green→Refactor를 자체 처리.

각 issue에 대해:

  1. Task 생성 (배치당 1회):

    mcp__vibe_kanban__create_issue(
      project_id: "{project_id}",
      title: "{issue title}",
      description: "{아래 통합 Task Description}"
    )
    

    → task_id를 implement.yaml에 저장

  2. Workspace Session 시작:

    mcp__vibe_kanban__start_workspace_session(
      task_id: "{task_id}",
      executor: "CLAUDE_CODE",
      repos: [{ repo_id: "{task의-repo-id}", base_branch: "origin/{base_branch}" }]
    )
    

통합 Task Description 템플릿

하나의 task에 Red→Green→Visual→Refactor 전체 워크플로우를 포함한다. Workspace agent는 전문 agent에 위임하여 각 phase를 실행하고, Review Gate에서 AskUserQuestion으로 인간 리뷰를 받는다.

🚫 **금지 사항 — 아래 규칙을 반드시 준수하세요:**
- **작업 시작 전** 반드시 `git fetch origin {base_branch} && git merge origin/{base_branch}`를 실행하세요. local branch가 remote보다 뒤쳐져 있으면 이전 batch 작업물이 누락됩니다.
- PR 생성 시 `--base` 플래그를 반드시 아래 Context의 **Base Branch** 값으로 지정하세요. `main`을 base로 사용하지 마세요.
- 아래 Step 1부터 순서대로 실행하세요. 각 Step 완료 후 Review Gate에서 반드시 멈추고 인간의 리뷰를 받으세요.

## Context

- Linear Issue: {linear_issue_url}
- TechSpec Document: {meta.yaml의 document.url}
- **Base Branch**: `{base_branch}`
- **작업 대상 패키지**: `{package_name}` (`{package_path}`)
- **작업 디렉토리**: `{package_path}/{target_directory}`
- **기존 패턴 참조**: `{package_path}/{reference_pattern}` (같은 패키지 내 유사 모듈)
- **Linear Issue ID**: `{issue_id}` (Refactor 완료 시 Linear 동기화용)
- **Figma URL**: `{figma_url_or_null}` (TechSpec Summary에서 추출, Visual Verification용)

## 관련 테스트 케이스

{Linear TechSpec 문서에서 해당 issue의 Given/When/Then 테이블}

## 관련 설계

{Linear TechSpec 문서의 Design 섹션에서 해당 데이터 모델(Interface)/Usecase/Component 정보}

---

## Step 1: 🔴 RED — `tdd-red` agent에 위임

```
Task(subagent_type: "tdd-red", prompt: "
  ## Context
  - test_cases: {위 '관련 테스트 케이스' 전체}
  - target_files: {위 '관련 설계'에서 파일 경로}
  - branch_name: {issue title 기반 kebab-case}
  - base_branch: {base_branch}
  - existing_test_patterns: {package_path}/{reference_pattern} 참조
")
```

### 🔍 Review Gate 1

agent 완료 후, **반드시 여기서 멈추고 AskUserQuestion으로 인간에게 리뷰를 요청하세요.**

```
AskUserQuestion:
  question: "🔴 Red Phase 완료.

  브랜치: {branch_name}
  테스트 파일: {파일 경로 목록}
  실패하는 테스트: {N}개

  리뷰 포인트:
  - 테스트 이름이 구현이 아닌 행동을 설명하는가?
  - 엣지 케이스가 포함되어 있는가?
  - TechSpec TC와 일치하는가?

  선택: 진행 (Green으로) / 수정 요청 / 중단"
```

- **수정 요청** 시 → 피드백에 따라 테스트 수정 → 커밋 → 다시 Review Gate 1
- **진행** 시 → Step 2로
- **중단** 시 → 작업 중지

---

## Step 2: 🟢 GREEN — `tdd-green` agent에 위임

```
Task(subagent_type: "tdd-green", prompt: "
  ## Context
  - test_files: {Step 1에서 생성된 테스트 파일 경로}
  - failing_tests: {실패한 테스트 목록}
  - target_files: {관련 설계에서 파일 경로}
")
```

### 🔍 Review Gate 2

agent 완료 후, **반드시 여기서 멈추고 AskUserQuestion으로 인간에게 리뷰를 요청하세요.**

```
AskUserQuestion:
  question: "🟢 Green Phase 완료.

  변경 파일:
  - {file} - {변경 요약}

  테스트: {통과}/{전체} (신규 {N}개, 기존 {N}개)

  다음 단계: {Figma URL이 있으면 → Visual Verification / 없으면 → Refactor}

  선택: 진행 / 수정 요청 / Refactor 건너뛰기 / 중단"
```

- **수정 요청** 시 → 피드백에 따라 구현 수정 → 테스트 재실행 → 커밋 → 다시 Review Gate 2
- **진행** 시 → Figma URL이 있으면 Step 2.5로, 없으면 Step 3로
- **Refactor 건너뛰기** 시 → Draft PR 생성 + Linear 동기화 (상태 "In Review" + PR 코멘트) + `gh pr ready` 실행
- **중단** 시 → 작업 중지

---

## Step 2.5: 🎨 VISUAL — `tdd-visual` agent에 위임

> **Figma URL이 있으면 반드시 실행한다.** Figma URL이 없는 경우에만 Step 3으로 건너뜀.
> 에러 발생 시 자동 건너뛰기 금지 — 반드시 AskUserQuestion으로 사용자에게 선택을 요청한다.

```
Task(subagent_type: "tdd-visual", prompt: "
  ## Context
  - figma_url: {Context의 Figma URL}
  - components: {관련 설계의 [Presentational] 컴포넌트 목록}
  - visual_contract: {관련 설계의 Visual Contract 정보}
  - test_mock_data: {Step 1 테스트의 mock data}
")
```

### 🔍 Review Gate 2.5

agent 완료 후, **반드시 여기서 멈추고 AskUserQuestion으로 인간에게 리뷰를 요청하세요.**

```
AskUserQuestion:
  question: "🎨 Visual Verification 완료.

  비교 결과:
  - {component}: Figma 매칭 상태

  ralph-loop: {N}회 반복

  선택: 진행 (Refactor로) / 수정 요청 / 중단"
```

- **수정 요청** 시 → 추가 수정 → 커밋 → 다시 Review Gate 2.5
- **진행** 시 → Step 3로
- **중단** 시 → 작업 중지

---

## Step 3: 🔵 REFACTOR — `tdd-refactor` agent에 위임

```
Task(subagent_type: "tdd-refactor", prompt: "
  ## Context
  - source_files: {Step 2에서 변경된 소스 파일}
  - test_files: {Step 1에서 생성된 테스트 파일}
  - branch_name: {현재 브랜치}
  - task_summary: {issue title}
  - base_branch: {base_branch}
  - test_cases_summary: {관련 테스트 케이스 요약}
  - linear_issue_id: {issue_id}
")
```

### 🔍 Review Gate 3

agent 완료 후, **반드시 여기서 멈추고 AskUserQuestion으로 인간에게 최종 리뷰를 요청하세요.**

```
AskUserQuestion:
  question: "🔵 Refactor Phase 완료. Draft PR을 생성했습니다.

  PR: {pr_url}
  tsc: ✅ 통과
  biome: ✅ 통과
  테스트: {통과}/{전체}

  선택: 승인 (PR을 Ready for Review로 전환) / 수정 요청"
```

- **수정 요청** 시 → 피드백에 따라 수정 → 체크 재실행 → 커밋 & 푸시 → 다시 Review Gate 3
- **승인** 시 → `gh pr ready {pr_number}` 실행 → 작업 완료

Phase 5: 실행 상태 저장

.claude/docs/{project-name}/implement.yaml에 실행 상태를 저장한다:

# .claude/docs/{project-name}/implement.yaml
executor: "vibe_kanban"
project:
  id: "{project-id}"
  name: "{project-name}"
document:
  url: "{linear-document-url}"  # meta.yaml에서 참조
vibe_kanban:
  project_id: "{vibe-project-id}"
  base_branch: "{selected_base_branch}"  # Phase 2에서 선택한 base branch
  repos:
    - id: "{frontend-repo-id}"
      name: "frontend"
    - id: "{backend-repo-id}"
      name: "backend"
current_step:
  batch: 1                       # 현재 batch 번호만 추적
batches:
  - batch: 1
    type: blocker
    issues:
      - issue_id: "{linear-issue-id}"
        issue_url: "{linear-issue-url}"
        repo_id: "{frontend-repo-id}"
        title: "{title}"
        package_name: "{package-name}"          # Phase 3에서 추출
        package_path: "{package-path}"          # Phase 3에서 추출
        target_directory: "{target-dir}"        # Phase 3에서 추출
        reference_pattern: "{ref-path}"         # Phase 3에서 추출
        task_id: "{vibe-task-id}"  # Task 생성 시 기록, 상태 조회에 사용
  - batch: 2
    type: related
    issues:
      - issue_id: "{linear-issue-id}"
        issue_url: "{linear-issue-url}"
        repo_id: "{backend-repo-id}"
        title: "{title}"
        package_name: "{package-name}"
        package_path: "{package-path}"
        target_directory: "{target-dir}"
        reference_pattern: "{ref-path}"
        task_id: null              # 다음 batch 실행 시 생성됨
qa_verified: false                   # Phase 6.5 QA 통과 후 true
qa_report:                           # Phase 6.5 완료 시 기록
  total: null
  passed: null
  failed: null
  follow_up_issues: []
  verified_at: null
created_at: "{ISO-8601}"

상태 저장 시점:

  • Task 생성 후: issues[].task_id 기록, current_step.batch 업데이트
  • Batch 완료 확인 후 (재실행 시): current_step.batch → 다음 batch 번호로 업데이트

Phase별 상태(Red/Green/Refactor)는 workspace가 내부적으로 관리하므로 implement.yaml에서 추적하지 않는다. Branch, PR 정보도 workspace가 관리하므로 저장하지 않는다.

Phase 6: 결과 보고

Batch 시작 시
Batch 1 시작

Project: {Project Name}
TechSpec: {document URL}

워크스페이스 생성됨:
- [Frontend] Cart UI Component → task 생성 + session 시작
- [Backend] Cart Interface → task 생성 + session 시작

각 워크스페이스가 Red→Green→Refactor를 순차 처리합니다.
각 Phase 사이에 Review Gate에서 리뷰 요청이 옵니다.
재실행 시 (상태 확인)
Batch 1 상태 확인

vk issue 상태:
- [Frontend] Cart UI Component → ✅ completed
- [Backend] Cart Interface → ⏳ in_progress

다음 단계:
- 진행 중인 워크스페이스의 Review Gate에 응답해주세요
- 모든 task 완료 후 /tdd:implement 로 Batch 2를 시작합니다
Batch 전환 시
Batch 1 모든 task 완료!

다음: Batch 2 (Related issues)
- [Frontend] Wishlist 저장 기능
- [Backend] Cart 미니 뷰

진행할까요?
모든 Batch 완료 시 (QA 진입)
모든 batch 완료! QA Phase로 진입합니다.

QA를 진행하려면 모든 Draft PR을 base branch에 merge해주세요.
Base branch: {base_branch}

Phase 6.5: QA (Integration Verification)

모든 batch가 완료된 후, TechSpec의 AC/TC를 평가기준으로 통합된 코드가 실제로 동작하는지 검증한다.

전제조건: 사용자가 모든 Draft PR을 base branch에 merge한 상태에서 진행한다. Agent가 직접 브랜치를 merge하지 않는다.

Step 1: merge 상태 확인

사용자에게 merge 완료 여부를 확인한다:

AskUserQuestion:
  question: "모든 batch가 완료되었습니다. QA를 진행하려면 모든 Draft PR을 base branch에 merge해주세요.

  Base branch: {base_branch}

  merge 완료 후 '진행'을 선택해주세요.
  선택: 진행 / 중단"

진행 선택 시 git fetch origin && git merge origin/{base_branch}로 최신 코드 동기화.

Step 2: TechSpec 로드
ToolSearch(query: "select:mcp__plugin_linear_linear__get_document")
→ get_document(id: "{document.id from meta.yaml}")
Step 3: tdd-integrate agent 위임
Task(subagent_type: "tdd-integrate", prompt: "
  ## TechSpec
  {Linear 문서 전문}

  ## Base branch: {base_branch}
  ## Project ID: {project.id}
")
Step 4: Human Review Gate

agent 결과를 AskUserQuestion으로 사용자에게 보고한다:

AskUserQuestion:
  question: "🔍 QA 완료.

  {agent가 반환한 QA Report}

  선택:
  - 승인: 모든 평가기준 통과, 구현 완료
  - 바로 수정: 이 세션에서 바로 수정 후 QA 재진행
  - Follow-up issue 생성: 실패 항목을 Linear issue로 생성하여 추가 batch
  - 중단"
Step 5: Follow-up 처리

승인 시:

implement.yaml 업데이트:

qa_verified: true
qa_report:
  total: {N}
  passed: {N}
  failed: 0
  verified_at: "{ISO-8601}"

→ "모든 QA 평가기준을 통과했습니다. 구현 완료!" 보고

바로 수정 시:

  1. 실패 항목을 현재 세션에서 즉시 수정한다 (Red-Green-Refactor 없이 직접 수정)
  2. 수정 완료 후 commit & push
  3. Step 3부터 다시 진행 (tdd-integrate agent 재위임 → QA 재실행)
  4. 이 루프는 승인 또는 Follow-up issue 생성을 선택할 때까지 반복 가능

Follow-up issue 생성 시:

  1. 각 실패 항목을 Linear issue로 생성:

    ToolSearch(query: "select:mcp__plugin_linear_linear__create_issue")
    → create_issue(
        title: "[QA] {평가기준에서 드러난 문제}",
        team: "{team}",
        labels: ["tdd"],
        project: "{project name or id}",
        description: "## QA에서 발견된 문제\n{상세}\n\n## 관련 평가기준\n{AC/TC 참조}"
      )
    
  2. implement.yaml에 새 batch 추가:

    - batch: {next_batch_number}
      type: qa-fix
      issues:
        - issue_id: "{new-linear-issue-id}"
          issue_url: "{url}"
          title: "[QA] {문제 설명}"
          package_name: "{package-name}"
          package_path: "{package-path}"
          target_directory: "{target-dir}"
          reference_pattern: "{ref-path}"
          task_id: null
    
  3. qa_verified 필드는 false 유지

  4. "QA fix batch가 생성되었습니다. /tdd:implement를 재실행하세요." 보고

재실행 시 흐름:

/tdd:implement → qa-fix batch의 task 생성 → Red-Green-Refactor
  → 완료 → 사용자가 PR merge → 다시 Phase 6.5 (QA) 진입
  → 통과 → 완료

Error Handling

상황대응
meta.yaml 없음/tdd:spec을 먼저 실행하라고 안내
Linear issue 조회 실패/tdd:issues를 먼저 실행하라고 안내
"tdd" label issue 없음/tdd:issues를 먼저 실행하라고 안내
Vibe Kanban 프로젝트 없음AskUserQuestion으로 프로젝트 선택 또는 생성 안내
Repo 정보 없음AskUserQuestion으로 repo 선택 요청
Session 시작 실패에러 로그 출력, 수동 재시도 안내
vk issue 상태 조회 실패에러 로그 + 수동 확인 안내
모든 구현 + QA 완료 (done)"모든 배치 및 QA가 완료되었습니다" 안내
Visual Verification 에러tdd-visual agent가 자체 처리 (AskUserQuestion으로 사용자 확인)
TechSpec AC/TC 없음 (QA)/tdd:spec을 먼저 실행하라고 안내 + 사용자에게 직접 평가기준 입력 요청
ralph-loop 실패 (QA)재시도/건너뛰기 선택
QA 평가기준 전체 통과qa_verified: true 마킹, 완료 보고

Example: 첫 실행

사용자: /tdd:implement

Claude: [AskUserQuestion] base branch를 지정하세요. (추천: feature/new-cart)
사용자: feature/new-cart

Claude: [AskUserQuestion] 참여 repo를 선택하세요.
사용자: Frontend, Backend API

Claude: [AskUserQuestion] Batch 1 실행:
  - [Backend] Cart Interface 및 상수 정의
  - [Frontend] Cart UI Component
사용자: 진행

Claude: task 생성 + session 시작 완료. 각 workspace가 Red→Green→Refactor를 순차 처리합니다.

Example: 재실행

사용자: /tdd:implement

Claude: Batch 1 상태: 모든 task completed ✅
Claude: [AskUserQuestion] Batch 2 시작할까요?
  - [Frontend] Wishlist 저장 기능
  - [Backend] Cart 미니 뷰
사용자: 진행

Claude: task 생성 + session 시작 완료.

Example: QA Phase

사용자: /tdd:implement

Claude: 모든 batch 완료! QA Phase로 진입합니다.
Claude: [AskUserQuestion] 모든 Draft PR을 base branch에 merge해주세요.
  Base branch: feature/new-cart
  선택: 진행 / 중단
사용자: 진행

Claude: TechSpec에서 QA 평가기준을 도출합니다...
Claude: [AskUserQuestion] QA 평가기준 확인:
  1. [ ] 상품 추가 후 미니카트 수량 반영
  2. [ ] 빈 장바구니에서 상품 추가 시 아이템 표시
  3. [ ] 수량 변경 시 총액 실시간 갱신
  선택: 진행 / 수정
사용자: 진행

Claude: ralph-loop으로 QA 검증 중... (3회 반복)
Claude: [AskUserQuestion] 🔍 QA 완료.
  평가기준: 3개 중 2개 통과, 1개 실패
  실패: 수량 변경 시 총액 갱신 — CalculateTotal usecase 미연결
  선택: 승인 / 바로 수정 / Follow-up issue 생성 / 중단
사용자: 바로 수정

Claude: CalculateTotal usecase를 CartContainer에 연결합니다...
  commit & push 완료. QA를 재실행합니다.
Claude: ralph-loop으로 QA 검증 중... (1회 반복)
Claude: [AskUserQuestion] 🔍 QA 완료.
  평가기준: 3개 중 3개 통과 ✅
  선택: 승인 / 바로 수정 / Follow-up issue 생성 / 중단
사용자: 승인

Claude: 모든 QA 평가기준을 통과했습니다. 구현 완료!

TDD Issues Command

/tdd:spec과 /tdd:design의 결과물을 기반으로 Linear 프로젝트에 issue를 생성한다.

Prerequisites

  • 필수: .claude/docs/{project-name}/meta.yaml 존재 (/tdd:spec 실행 결과)
  • 필수: Linear TechSpec 문서에 /tdd:spec 결과물 포함 (Functional Requirements 섹션)
  • 필수: Linear TechSpec 문서에 /tdd:design 결과물 포함 (Design, Component & Code, Verification 섹션)
  • 필수 MCP: Linear plugin 활성화

Execution Flow

Phase 1: 메타데이터 로드 및 Linear 문서 검증

  1. .claude/docs/ 하위에서 프로젝트 메타데이터 파일을 찾는다:
    Glob(pattern: ".claude/docs/*/meta.yaml")
    
  2. 여러 프로젝트가 있으면 AskUserQuestion으로 선택 요청
  3. meta.yaml에서 document.id, project.id 등 메타데이터를 읽는다
  4. Linear에서 TechSpec 문서 내용을 조회한다:
    ToolSearch(query: "select:mcp__plugin_linear_linear__get_document")
    → mcp__plugin_linear_linear__get_document(id: "{document.id}")
    
  5. Linear 문서에서 필수 섹션 존재 여부를 검증한다:

검증 체크리스트:

섹션출처필수 여부
## Functional Requirements/tdd:spec필수
## Design/tdd:design필수
### 1. 데이터 모델/tdd:design필수
### 2. Usecase/tdd:design필수
## Component & Code - Client/tdd:design필수
## Verification/tdd:design필수

검증 실패 시:

  • ## Functional Requirements 없음 → /tdd:spec을 먼저 실행하라고 안내
  • ## Design 없음 → /tdd:design을 먼저 실행하라고 안내
  1. 검증 통과 시 Linear 문서에서 다음 정보를 추출한다:
    • Functional Requirements: Given/When/Then 테스트 케이스
    • Design: domain model, usecases, component tree

Phase 2: Issue 분류 (tdd-issue-planner agent 위임)

TechSpec 문서를 분석하여 Blocker/Related 분류, 패키지 매핑, issue description 생성을 tdd-issue-planner agent에 위임한다.

Task(
  subagent_type: "tdd-issue-planner",
  prompt: """
  다음 TechSpec 문서를 분석하여 Blocker/Related issue를 분류하고 description을 생성해주세요.

  ## TechSpec 전체 내용
  {Linear 문서에서 조회한 전체 내용}

  ## Project Info
  - project_id: {project.id from meta.yaml}
  - team: {team from meta.yaml}
  """
)

agent 반환 결과: Blocker/Related issue 목록 (title, description, priority, package 매핑, TC 커버리지)

Phase 3: 사용자 확인

분류 결과를 AskUserQuestion으로 제시하여 확인받는다:

question: "다음 issue 구조로 생성합니다. 수정할 항목이 있나요?"

Blocker Issues:
1. [Blocker] {issue title} - {description}
2. [Blocker] {issue title} - {description}

Related Issues:
3. [Related] {issue title} - {description}
4. [Related] {issue title} - {description}

사용자가 수정을 요청하면 반영 후 다시 확인.

Phase 3.5: Label 확인/생성

Issue 생성 전에 "tdd" label을 확인한다:

ToolSearch(query: "select:mcp__plugin_linear_linear__list_issue_labels")
list_issue_labels(team: "{team}", name: "tdd")

조회 결과:

  • "tdd" label 있음 → Phase 4로 진행
  • "tdd" label 없음 → 사용자에게 안내:
    ⚠️ "tdd" label이 Linear에 없습니다.
    Linear에서 다음 단계를 수행하세요:
    1. Project Settings → Labels
    2. "tdd" label 생성 (또는 생성 확인)
    3. 다시 /tdd:issues 실행
    

Phase 4: Linear Issue 생성

CRITICAL: 모든 issue 생성 시 반드시 labels: ["tdd"]를 포함해야 합니다.

  • 이 label이 없으면 /tdd:implement에서 issue를 찾을 수 없습니다
  • label 누락 시 전체 TDD 워크플로우가 실패합니다
  • 절대 생략하지 마세요!

MCP 도구를 로드하고 Phase 2 agent 결과물의 issue 목록을 순서대로 생성한다.

ToolSearch(query: "select:mcp__plugin_linear_linear__create_issue")
ToolSearch(query: "select:mcp__plugin_linear_linear__list_issue_labels")

생성 순서:

  1. Blocker issue 먼저 생성
  2. Related issue 생성

생성 파라미터: agent가 반환한 각 issue의 title, description, priority를 그대로 사용하되, 반드시 labels: ["tdd"]와 project: "{project id}" 포함.

Phase 4.5: Label 검증 (필수)

Issue 생성 완료 후, 모든 issue에 "tdd" label이 붙었는지 검증한다:

ToolSearch(query: "select:mcp__plugin_linear_linear__list_issues")
list_issues(project: "{project-id}", labels: ["tdd"])

검증:

  • 생성한 issue 수 == 조회된 issue 수 → Phase 5로 진행
  • 불일치 시 → 누락된 issue 식별 후 label 추가:
    ToolSearch(query: "select:mcp__plugin_linear_linear__update_issue")
    update_issue(id: "{issue-id}", labels: ["tdd"])
    

Phase 4.7: TC → Issue 커버리지 검증

Phase 2 agent 결과의 tc_coverage 요약을 확인한다. 미할당 TC가 있으면 관련 이슈에 추가하거나 새 이슈를 생성한다.

Phase 5: 결과 보고

Issue 생성 완료!

Project: {Project Name}
Linear: {project url}
Label: tdd

Blocker Issues ({N}개):
- {issue title} ({linear url})

Related Issues ({N}개):
- {issue title} ({linear url})

Total: {total}개 issues

---

📋 TDD 안내:
- 각 issue에는 Red-Green-Refactor 워크플로우가 포함되어 있습니다
- 테스트 먼저 작성 → 최소 구현 → 리팩토링 순서로 진행하세요

조회: list_issues(project: "{project-id}", labels: ["tdd"])

다음 단계:
- /tdd:implement: 병렬 워크스페이스로 자동 구현 시작
- 또는 Linear에서 담당자 배정 후 수동 TDD 진행

Error Handling

상황대응
meta.yaml 없음/tdd:spec을 먼저 실행하라고 안내
Linear 문서 조회 실패사용자에게 Linear URL 안내, 수동 확인 요청
## Functional Requirements 섹션 없음/tdd:spec을 먼저 실행하라고 안내
## Design 섹션 없음/tdd:design을 먼저 실행하라고 안내
Linear team 식별 불가AskUserQuestion으로 팀 선택 요청
Issue 생성 중 실패성공한 issue 목록을 보고하고, 실패 건 재시도 안내
Label 'tdd'가 없음label 생성 안내
Issue 생성 시 label 누락update_issue로 "tdd" label 즉시 추가
Phase 4.5 검증 실패누락된 issue에 label 추가 후 재검증

Example

사용자: /tdd:issues

Claude: .claude/docs/my-feature/ 에서 메타데이터를 로드합니다...
  → meta.yaml 로드 (document.id: abc123)

Claude: Linear에서 TechSpec 문서를 조회합니다...
  → Functional Requirements (12개 테스트 케이스)
  → Design (데이터 참조: Cart API, Product API / usecases: 4개 / components: 8개)

Claude: [AskUserQuestion] 다음 issue 구조로 생성합니다:

  Blocker Issues:
  1. [Blocker] Cart Interface 및 상수 정의
  2. [Blocker] Cart API 인터페이스 설계
  3. [Blocker] 공통 컴포넌트 (QuantitySelector, Button)

  Related Issues:
  4. [Related] CartPage 구현 (AddToCart, RemoveFromCart Usecase 포함)
  5. [Related] CartItem 컴포넌트 구현

  작업 대상: `@daangn/cart-ui` (`packages/cart-ui`)
  작업 디렉토리: `packages/cart-ui/src/modules/cart/`
  참조 패턴: `packages/cart-ui/src/modules/product/`

사용자: 좋습니다

Claude: Linear에 issue를 생성합니다...

Claude: Issue 생성 완료!

  Blocker Issues (3개):
  - [Blocker] Cart Interface 및 상수 정의 (https://linear.com/issue/PROJ-1)
  - [Blocker] Cart API 인터페이스 설계 (https://linear.com/issue/PROJ-2)
  - [Blocker] 공통 컴포넌트 (QuantitySelector, Button) (https://linear.com/issue/PROJ-3)

  Related Issues (2개):
  - [Related] CartPage 구현 (https://linear.com/issue/PROJ-4)
  - [Related] CartItem 컴포넌트 구현 (https://linear.com/issue/PROJ-5)

  Total: 5개 issues

  조회 방법: Linear에서 직접 확인하세요.
  다음 단계: /tdd:implement으로 병렬 워크스페이스 생성

TDD Spec Command

Linear 프로젝트에 FE TechSpec 문서를 생성한다. PRD와 Figma 컨텍스트를 기반으로 Solution, Acceptance Criteria, Test Cases를 자동 작성.

Prerequisites

  • 필수 스킬: fe-techspec - 템플릿 구조와 섹션별 작성 가이드 참조
  • 필수 MCP: Linear plugin 활성화

Execution Flow

Phase 1: 입력 수집

  1. 사용자로부터 Linear Project 링크 또는 이름을 받는다
  2. PRD (Notion URL)가 제공되지 않은 경우, AskUserQuestion으로 명시적으로 묻는다:
    question: "PRD (Notion URL)가 있나요? 없으면 비워두세요."
    
  3. Figma URL이 제공되지 않은 경우, AskUserQuestion으로 명시적으로 묻는다:
    question: "Figma 디자인 URL이 있나요? 없으면 비워두세요."
    

PRD와 Figma가 모두 없는 경우: 정말로 없는지 한 번 더 확인한다.

Phase 2: 컨텍스트 수집

ToolSearch로 MCP 도구를 로드한 뒤 컨텍스트를 수집한다.

  1. Linear 프로젝트 조회:

    ToolSearch(query: "select:mcp__plugin_linear_linear__get_project")
    → mcp__plugin_linear_linear__get_project(query: "{project identifier}")
    
  2. PRD 내용 조회 (URL 제공 시, ⚠️ 반드시 실행):

    ToolSearch(query: "select:mcp__plugin_Notion_notion__notion-fetch")
    → mcp__plugin_Notion_notion__notion-fetch(url: "{notion_url}")
    
    • PRD URL이 있으면 반드시 fetch하여 컨텍스트 수집
    • 핵심 요구사항, 유저 스토리, 성공 지표를 추출
    • fetch 실패 시에만 PRD 없이 진행
  3. Figma 디자인 컨텍스트 (URL 제공 시):

    ToolSearch(query: "select:mcp__plugin_figma_figma__get_design_context")
    → mcp__plugin_figma_figma__get_design_context(url: "{figma_url}")
    
    • 컴포넌트 구조, UI 흐름을 추출
    • ⚠️ UI 표시 문구 검증: 테이블 컬럼명, 버튼 라벨, 상태 표시 텍스트 확인
    • 가정하지 말고 피그마 variants에서 실제 문구 추출

Phase 3: TechSpec 작성

  1. fe-techspec 스킬의 섹션별 작성 가이드를 참조한다
  2. fe-techspec/references/template.md에서 문서 구조를 로드한다

수집된 컨텍스트를 기반으로 전체 문서를 작성한다.

작성 순서:

  1. Summary: 프로젝트 배경 + PRD/Figma 링크
  2. Solution: ⚠️ 기술 용어 없이 비즈니스 관점에서 핵심 변경사항 요약
    • 번호 매기기 형식으로 3-5개 핵심 변경사항 나열
    • 코드, API, 타입명 사용 금지
  3. Acceptance Criteria: PRD 유저 스토리에서 테스트 가능한 기준 도출
  4. Non-Functional Requirements: 해당되는 경우에만 작성 (Performance, A11y, SEO)
  5. Functional Requirements (Given/When/Then):
    • ⚠️ Entity/Command 헤더 없이 테이블만 작성
    • 정상 → 에러 → 엣지 케이스 순서로 테스트 케이스 테이블 작성

Phase 3.5: AC ↔ TC 추적성 검증

작성 완료 후 Acceptance Criteria와 Functional Requirements의 대응 관계를 검증한다.

  • 각 AC 항목에 대응하는 TC(Given/When/Then 행)가 최소 1개 존재하는지 확인
  • 대응 TC가 없는 AC → TC를 추가하거나 AC를 제거
  • TC가 어떤 AC에도 속하지 않으면 → AC를 추가하거나 해당 TC의 필요성 재검토

Phase 4: Linear 문서 생성

ToolSearch(query: "select:mcp__plugin_linear_linear__create_document")
→ mcp__plugin_linear_linear__create_document(
    title: "FE TechSpec: {Feature Name}",
    project: "{project ID or name}",
    content: "{full markdown content}"
  )

Phase 5: 메타데이터 저장

.claude/docs/{project-name}/meta.yaml에 메타데이터만 저장한다. {project-name}은 Linear 프로젝트 이름을 kebab-case로 변환한 값.

⚠️ TechSpec 전문은 저장하지 않는다 - Linear 문서가 Single Source of Truth.

# .claude/docs/{project-name}/meta.yaml
project:
  id: "{project-id}"
  name: "{project-name}"
  url: "{linear-project-url}"
  tdd_label: "tdd"
document:
  id: "{document-id}"
  url: "{linear-document-url}"
  title: "FE TechSpec: {Feature Name}"
sources:
  prd: "{notion-url-or-null}"
  figma: "{figma-url-or-null}"
created_at: "{ISO-8601}"

이 파일은 후속 command (/tdd:design 등)에서 Linear 리소스를 참조하는 데 사용된다.

Phase 6: 결과 보고

FE TechSpec 생성 완료!

Linear Document: {Linear Document URL}
Project: {Project Name}
Metadata: .claude/docs/{project-name}/meta.yaml

작성된 섹션:
- Summary (PRD/Figma 링크 포함)
- Solution (핵심 변경사항)
- Acceptance Criteria ({N}개)
- Non-Functional Requirements
- Functional Requirements ({N}개 테스트 케이스)

⚠️ TechSpec 전문은 Linear 문서에만 저장됩니다 (Single Source of Truth)

다음 단계:
1. Linear에서 문서를 리뷰하세요
2. /tdd:design 으로 Domain/Usecase/Component 설계를 추가하세요

Phase 7: (Human) Review

사용자가 Linear에서 문서를 리뷰한다.

Error Handling

상황대응
Linear 프로젝트를 찾을 수 없음프로젝트 목록을 보여주고 선택 요청
Notion PRD fetch 실패PRD 없이 진행, Summary에 명시
Figma fetch 실패Figma 없이 진행, Design 섹션 스킵
Linear 문서 생성 실패에러 메시지 출력, 재시도 안내 (로컬 저장 없음)
MCP 도구 로드 실패에러 메시지와 함께 플러그인 활성화 방법 안내

Example

사용자: /tdd:spec

Claude: Linear Project 링크 또는 이름을 알려주세요.
사용자: https://linear.app/daangn/project/my-feature-123

Claude: [AskUserQuestion] PRD (Notion URL)가 있나요?
사용자: https://www.notion.so/my-prd-page

Claude: [AskUserQuestion] Figma 디자인 URL이 있나요?
사용자: https://www.figma.com/file/xxx

Claude: [컨텍스트 수집 중...]
Claude: [TechSpec 작성 중...]
Claude: [Linear 문서 생성 중...]

Claude: FE TechSpec 생성 완료!
  Linear Document: https://linear.app/daangn/document/fe-techspec-xxx
  Metadata: .claude/docs/my-feature/meta.yaml
  ...

TDD Start Command

간단한 버그 수정이나 작은 기능 추가를 TDD로 진행한다. 분석→설계→Red→Green→Refactor 전체 사이클을 한 세션에서 처리하며, 각 phase마다 사용자 리뷰를 받는다. Refactor 완료 후 Draft PR을 생성한다.

heavyweight flow(/tdd:spec → /tdd:design → /tdd:issues → /tdd:implement)와 달리 Linear, Notion, Figma, Vibe Kanban 등 외부 서비스가 불필요하다.

Usage

/tdd:start [task description or URL]

Examples

# 텍스트로 작업 설명
/tdd:start 장바구니에 수량 음수가 입력되는 버그 수정

# GitHub 이슈 URL
/tdd:start https://github.com/org/repo/issues/42

# Linear 이슈 URL
/tdd:start https://linear.app/team/issue/TEAM-123

# 인자 없이 실행 (대화형으로 입력)
/tdd:start

Prerequisites

  • 필수: 프로젝트에 테스트 프레임워크가 설정되어 있어야 함 (자동 감지)
  • 필수 아님: Linear, Notion, Figma, Vibe Kanban (외부 서비스 불필요)

세션 상태 관리

.claude/docs/{project_name}/tdd-session.yaml에 세션 상태를 저장한다. context가 압축되거나 세션이 길어져도 상태를 유지할 수 있다.

상태 파일 구조

# .claude/docs/{project_name}/tdd-session.yaml
task: "버그 수정: 장바구니 수량 음수 허용됨"
branch: "fix/cart-negative-quantity"
pr:
  number: 42
  url: "https://github.com/org/repo/pull/42"
phase: "plan"  # plan | red | green | visual | refactor | done
design:
  human_draft: |
    ### 핵심 결정
    - src/domain/cart.ts의 addItem()에 validation 추가
    ### 열린 질문
    - 에러 타입을 ValidationError로 할지 RangeError로 할지?
  test_cases:
    - "Given 수량 -1 / When 장바구니 추가 / Then 에러"
  approach:
    - file: "src/domain/cart.ts"
      change: "addItem()에 수량 validation 추가"
test_files:
  - src/domain/cart.test.ts
source_files:
  - src/domain/cart.ts
commits:
  red: null
  green: null
  visual: null
  refactor: null
visual_verification:
  enabled: false
  figma_url: null
  story_files: []
  iterations: 0
  status: null  # skipped | completed | partial
created_at: "2026-02-11T10:00:00Z"
updated_at: "2026-02-11T10:00:00Z"

상태 파일 규칙

  • Phase 전환 시마다 업데이트: phase 필드, 파일 목록, 커밋 해시 등
  • 커맨드 시작 시 존재 확인: 있으면 이전 세션 이어서 진행
  • Phase 10 완료 후 삭제: 워크플로우 정상 종료 시 정리
  • context 압축 후 복구: 파일을 Read하여 현재 상태 복원

project_name 결정

  • 태스크 설명에서 핵심 키워드를 추출하여 kebab-case로 변환
  • 예: "장바구니 수량 음수 버그" → cart-negative-quantity
  • 기존 .claude/docs/ 하위 디렉토리가 있으면 재사용 가능

Execution Flow

Phase 0: 세션 복구 확인

  1. Glob(".claude/docs/*/tdd-session.yaml")로 기존 세션 파일 탐색

  2. 파일이 존재하면 → Read하여 상태 로드 후 AskUserQuestion:

    question: "이전 TDD 세션이 발견되었습니다.
    
    작업: {task}
    브랜치: {branch}
    PR: {pr_url 또는 '아직 생성되지 않음'}
    현재 단계: {phase}
    상태 파일: .claude/docs/{project_name}/tdd-session.yaml
    
    선택:
    - 이어서 진행: 현재 단계부터 계속합니다
    - 처음부터 다시: 상태 파일을 삭제하고 새로 시작합니다
    - 취소: 아무것도 하지 않습니다"
    
  3. 파일이 없으면 → Phase 1로 진행

Phase 1: 입력 수집 및 컨텍스트 파악

  1. 입력 파싱: $ARGUMENTS.task 분석

    입력 타입감지 방법처리
    없음$ARGUMENTS.task 비어있음AskUserQuestion: "어떤 작업을 TDD로 진행할까요?"
    일반 텍스트URL 패턴 아님그대로 작업 설명으로 사용
    Linear URLlinear.app 포함ToolSearch로 Linear MCP fetch (best-effort)
    GitHub URLgithub.com/.*/issues/ 패턴gh issue view {url} --json title,body
    • Linear/GitHub URL fetch 실패 시 → AskUserQuestion으로 텍스트 입력 요청
  2. 프로젝트 컨텍스트 수집:

    테스트 프레임워크 감지:

    Glob("vitest.config.*") → vitest
    Glob("jest.config.*") 또는 package.json의 jest 섹션 → jest
    Glob("pytest.ini") 또는 Glob("pyproject.toml") → pytest
    Glob("go.mod") → go test
    
    • 감지 실패 시 AskUserQuestion으로 질문

    기존 테스트 패턴 파악:

    • Grep로 describe(, it(, test( 등 검색하여 테스트 파일 위치, 네이밍 컨벤션 파악
    • 대표 테스트 파일 1-2개 Read하여 import 패턴, 구조 확인

    린터/타입체커 감지:

    Glob("biome.json") → biome
    Glob(".eslintrc.*") 또는 Glob("eslint.config.*") → eslint
    Glob("tsconfig.json") → tsc
    

    Figma URL 확인:

    • 작업 설명에 Figma URL (figma.com 포함)이 포함되어 있으면 추출하여 저장
    • 없으면 AskUserQuestion: "Figma 디자인 URL을 입력하세요. (Visual Verification에 사용됩니다. UI 작업이 아닌 경우 '없음'이라고 답해주세요)"
    • '없음' 응답 시 null로 저장 (Visual Verification 비활성화)
  3. 스코프 판단: 10개 이상의 테스트 케이스가 필요하거나 다수 모듈에 걸치는 작업이면 AskUserQuestion으로 heavyweight flow 추천

  4. 세션 상태 파일 초기 생성:

    • project_name 결정 (태스크에서 키워드 추출, kebab-case)
    • .claude/docs/{project_name}/ 디렉토리가 없으면 생성
    • .claude/docs/{project_name}/tdd-session.yaml 작성 (phase: "plan")

Phase 2: 분석 & 설계

/tdd:spec의 테스트 케이스 설계 + /tdd:design의 구현 방향을 경량화하여 하나의 phase로 합침.

  1. 문제 분석:

    • 버그인 경우: 원인 파악, 재현 조건 정리
    • 기능 추가인 경우: 요구사항 정리, 기존 코드와의 관계 파악
    • 영향 범위 파악 (어떤 파일/모듈에 영향)
    • 관련 코드 읽기 (Grep/Read로 현재 구현 확인)
  2. 설계 초안 수집 (필수):

    문제 분석 결과를 공유한 뒤 인간의 설계 초안을 요청한다. 초안이 제공될 때까지 TC 설계로 진행하지 않는다.

    AskUserQuestion:
      question: "문제를 분석했습니다.
    
      ## 문제 분석
      {문제 요약}
    
      구현 방향에 대한 설계 초안을 공유해주세요.
      (컴포넌트 구조, 데이터 흐름, 기술 선택 등)
    
      예시:
      ### 핵심 결정
      - 컴포넌트: ...
      - 데이터: ...
      ### 열린 질문
      - ...?
    
      자유 형식도 괜찮습니다.
    
      설계 시 고려하면 좋은 포인트:
      - 모듈 경계: 이 구조에서 한 모듈을 수정할 때 다른 파일까지 함께 고쳐야 하진 않는가?
      - 추상화 깊이: 모듈이 내부 복잡성을 충분히 숨기는가, 아니면 인터페이스만 복잡한 얕은 모듈인가?
      - 인지 부하: 이 설계를 이해하려면 한 번에 기억해야 할 개념이 몇 개인가? 몰라도 되는 옵션은 기본값으로 숨겼는가?
      - 데이터 흐름: 상태가 어디서 생성되고, 어떻게 흘러가며, 누가 변경하는가?
      - 에러 복구: 에러 발생 시 사용자에게 어떤 피드백을 주고, 상태를 어떻게 안전하게 되돌리는가?
      - 도메인 순수성: 도메인 로직이 UI/API/외부 의존성 없이 순수 함수로 분리되는가?
      - 테스트 경계: 테스트가 구현 세부사항이 아닌, 클라이언트에 노출된 공개 인터페이스를 검증하는 구조인가?
      - 도메인 언어: 코드의 변수명/함수명이 팀의 비즈니스 용어와 일치하는가?
      - YAGNI: 이 구조에 현재 요구사항이 필요로 하지 않는 확장 포인트나 레이어가 있진 않은가?"
    
  3. 테스트 케이스 설계 (← /tdd:spec의 경량 버전):

    • Given/When/Then 형식으로 테스트 케이스 목록 작성
    • 정상 → 에러 → 엣지 케이스 순서로 나열
    • 초안의 핵심 결정을 TC 설계에 반영
  4. 구현 접근 방식 (← /tdd:design의 경량 버전):

    • 어떤 파일을 수정/생성할지
    • 어떤 함수/컴포넌트를 변경할지
    • 주의할 점 (부작용, 호환성 등)
    • 초안의 기술 결정을 구현 접근에 반영
    • 초안과 TC 분석이 충돌하면 충돌 사항을 기록
  5. 세션 상태 업데이트: design 섹션에 테스트 케이스 & 구현 접근 & 초안 반영 기록

  6. AskUserQuestion으로 설계 리뷰 요청:

    question: "분석 & 설계가 완료되었습니다.
    
    ## 초안 반영
    - 반영: {반영된 결정}
    - 충돌: {충돌 사항 + 권장안} (없으면 생략)
    
    ## 열린 질문 → 제안
    - Q: {인간의 질문} → A: {제안 + 근거} (없으면 생략)
    
    ## 테스트 케이스
    1. Given {조건} / When {행동} / Then {결과}
    2. Given {조건} / When {행동} / Then {결과}
    
    ## 구현 접근
    - {file}: {변경 내용}
    - {file}: {변경 내용}
    
    선택: 진행 / 수정 요청 / 중단"
    

    수정 요청 시 → 설계 수정 후 상태 파일 업데이트 → 다시 리뷰 요청 (루프)

Phase 3: Red - 실패하는 테스트 작성

  1. 작업 디렉토리 확인: git status로 미커밋 변경사항 확인

    • 변경사항이 있으면 AskUserQuestion: "커밋되지 않은 변경이 있습니다. stash / commit / 중단 중 선택하세요"
    • stash 선택 시 git stash push -m "tdd-start: before {task}"
  2. tdd-red agent에 위임:

    Task(subagent_type: "tdd-red", prompt: "
      ## Context
      - test_cases: {Phase 2에서 설계한 Given/When/Then TC 목록}
      - target_files: {Phase 2에서 식별한 대상 소스 파일 경로}
      - branch_name: {branch 이름} (규칙: 버그 fix/{keywords}, 기능 feat/{keywords})
      - test_framework: {Phase 1에서 감지한 프레임워크}
      - existing_test_patterns: {Phase 1에서 파악한 기존 테스트 패턴 요약}
    ")
    
  3. agent 결과에서 test_files, branch, commit, failing_tests 수집

  4. 세션 상태 업데이트: phase → "red", branch, test_files, commits.red 기록

Phase 4: (Human) Red 리뷰

AskUserQuestion:
  question: "Red Phase 완료.

  브랜치: {branch-name}
  테스트 파일: {path}
  테스트 케이스:
  1. {test name} - {description}
  2. {test name} - {description}

  리뷰 포인트:
  - 테스트 이름이 구현이 아닌 행동을 설명하는가?
  - 엣지 케이스가 포함되어 있는가?
  - Phase 2 설계의 TC와 일치하는가?

  선택: 진행 / 수정 요청 / 중단"

수정 요청 시 → 테스트 수정 → 재실행(실패 확인) → commit → 다시 리뷰 요청 (루프)

Phase 5: Green - 최소 구현

  1. tdd-green agent에 위임:

    Task(subagent_type: "tdd-green", prompt: "
      ## Context
      - test_files: {Phase 3에서 생성된 테스트 파일 경로}
      - failing_tests: {실패한 테스트 목록}
      - target_files: {Phase 2에서 식별한 대상 소스 파일 경로}
    ")
    
  2. agent 결과에서 source_files, test_result, commit 수집

  3. 세션 상태 업데이트: phase → "green", source_files, commits.green 기록

Phase 6: (Human) Green 리뷰

AskUserQuestion:
  question: "Green Phase 완료.

  변경 파일:
  1. {file} - {변경 요약}
  2. {file} - {변경 요약}

  테스트: {통과}/{전체} (신규 {N}개, 기존 {N}개)

  리뷰 포인트:
  - 구현이 정말 최소한인가? (불필요한 추상화 없는가?)
  - 기존 테스트 회귀가 없는가?

  다음 단계: {Figma URL이 있으면 → Visual Verification / 없으면 → Refactor}

  선택: 진행 / 수정 요청 / Refactor 건너뛰기 / 중단"
  • 수정 요청 시 → 구현 수정 → 테스트 재실행 → commit → 다시 리뷰 (루프)
  • 진행 시 → Figma URL이 있으면 Phase 5.5로, 없으면 Phase 7(Refactor)로
  • Refactor 건너뛰기 선택 시 → Draft PR 생성 + gh pr ready 실행 후 Phase 8로 직행

Phase 5.5: Visual Verification — Figma 디자인 매칭

Figma URL이 있으면 반드시 실행한다. Figma URL이 없는 경우에만 Phase 7(Refactor)로 건너뜀. 에러 발생 시 자동 건너뛰기 금지 — 반드시 AskUserQuestion으로 사용자에게 선택을 요청한다.

  1. tdd-visual agent에 위임:

    Task(subagent_type: "tdd-visual", prompt: "
      ## Context
      - figma_url: {Phase 1에서 수집한 Figma URL}
      - components: {Phase 2에서 식별한 Presentational 컴포넌트 이름 목록}
      - visual_contract: {Phase 2 설계의 Visual Contract 정보}
      - test_mock_data: {Phase 3 테스트에서 사용한 mock data}
    ")
    
  2. agent 결과 확인:

    • Figma URL 미제공으로 건너뜀 → Phase 7(Refactor)로 이동
    • 완료 → story_files, iterations, match_status, commit 수집
  3. 세션 상태 업데이트: phase → "visual", visual_verification 섹션 업데이트 (story_files, iterations, status), commits.visual 기록

Phase 5.6: (Human) Visual Verification 리뷰

AskUserQuestion:
  question: "🎨 Visual Verification 완료.

  비교 결과:
  - {component}: Figma 매칭 상태 (✅ 일치 / ⚠️ 잔여 차이: {목록})

  생성된 파일:
  - {story/preview file path}

  ralph-loop: {N}회 반복

  선택: 진행 (Refactor로) / 수정 요청 / 중단"
  • 수정 요청 시 → ralph-loop 재시작하여 추가 수정 → commit → 다시 리뷰
  • 진행 시 → Phase 7(Refactor)로
  • 중단 시 → 작업 중지

Phase 7: Refactor - 코드 개선

  1. tdd-refactor agent에 위임:

    Task(subagent_type: "tdd-refactor", prompt: "
      ## Context
      - source_files: {Phase 5에서 변경된 소스 파일 목록}
      - test_files: {Phase 3에서 생성된 테스트 파일 목록}
      - branch_name: {현재 작업 브랜치}
      - task_summary: {작업 설명}
      - base_branch: {현재 브랜치의 base (기본: main)}
      - test_cases_summary: {Phase 2의 Given/When/Then TC 요약}
    ")
    
  2. agent 결과에서 pr_url, pr_number, precommit_result, refactoring_summary, commit 수집

  3. 세션 상태 업데이트: phase → "refactor", pr 정보, commits.refactor 기록

Phase 8: 최종 보고

세션 상태 파일에서 정보를 읽어 최종 보고를 작성한다:

## TDD 완료 보고

### 작업: {task description}
### PR: {pr_url}

### 분석 & 설계
- 테스트 케이스: {N}개 설계
- 구현 접근: {summary}

### Red Phase
- 테스트 파일: {path}
- 커밋: {commit hash} - test: add failing tests

### Green Phase
- 변경 파일: {file list with summaries}
- 커밋: {commit hash} - feat: minimal implementation

### Visual Verification
- 상태: {완료/건너뜀/부분완료}
- Story 파일: {path} (해당 시)
- ralph-loop: {N}회 반복 (해당 시)
- 커밋: {commit hash} (해당 시)

### Refactor Phase
- 리팩토링: {items or "건너뛰기됨"}
- 커밋: {commit hash} (해당 시)

### 최종 검증
- 타입 체크: 통과/해당없음
- 린트: 통과/해당없음
- 테스트: {passed}/{total} 통과

### 변경된 파일 전체
- {file} (신규/수정)

Phase 9: (Human) 최종 리뷰

AskUserQuestion:
  question: "TDD 워크플로우가 완료되었습니다.

  PR: {pr_url}

  선택: 승인 (PR을 Ready for Review로 전환) / 수정 요청"

수정 요청 시 → 수정 → commit & push → 다시 최종 리뷰 (루프)

Phase 10: PR Ready for Review & 정리

  1. 사용자 승인 후 Draft PR을 Ready for Review로 전환:

    gh pr ready {pr_number}
    
  2. 세션 상태 파일 삭제: .claude/docs/{project_name}/tdd-session.yaml 제거

  3. 완료 메시지 출력:

    PR이 Ready for Review로 전환되었습니다: {pr_url}
    TDD 세션이 정리되었습니다.
    

Error Handling

상황대응
테스트 프레임워크 감지 실패AskUserQuestion으로 어떤 프레임워크를 사용하는지 질문
Linear/GitHub URL fetch 실패텍스트로 작업 내용 직접 입력 요청
Red Phase에서 import 에러import/mock 설정 수정 후 assertion 실패 상태로 맞춤
Green Phase 3회 시도 후 실패AskUserQuestion으로 접근 방법 논의
전체 테스트 회귀어떤 기존 테스트가 깨졌는지 표시, 대응 방법 논의
git push 실패에러 표시, 수동 해결 안내
태스크가 너무 큰 경우/tdd:spec → /tdd:design → /tdd:issues → /tdd:implement 추천
사용자 중단변경 파일 & PR URL 표시, tdd-session.yaml 유지 (나중에 재개 가능)
세션 상태 파일 손상tdd-session.yaml 삭제 후 처음부터 시작 안내
작업 디렉토리에 미커밋 변경 있음AskUserQuestion으로 stash / commit / 중단 선택
Visual Verification 에러tdd-visual agent가 자체 처리 (AskUserQuestion으로 사용자 확인)

Example

사용자: /tdd:start 장바구니에 수량 음수가 입력되는 버그 수정

Claude: 프로젝트 컨텍스트를 수집합니다...
  테스트 프레임워크: vitest
  린터: biome
  타입 체커: tsc

Claude: [Phase 2] 문제를 분석했습니다.

  ## 문제 분석
  Cart.addItem()에서 수량 validation이 없어 음수 입력이 가능

  구현 방향에 대한 설계 초안을 공유해주세요.
  [AskUserQuestion]

사용자:
  ### 핵심 결정
  - src/domain/cart.ts의 addItem()에 수량 validation 추가
  - ValidationError를 던지도록 처리
  ### 열린 질문
  - 수량 0도 에러로 처리해야 하는지?

Claude: [Phase 2 계속] 분석 & 설계가 완료되었습니다.

  ## 초안 반영
  - 반영: addItem()에 validation 추가, ValidationError 사용

  ## 열린 질문 → 제안
  - Q: 수량 0도 에러로 처리해야 하는지?
    → A: 장바구니에 수량 0인 아이템은 의미 없으므로 에러 처리 권장

  ## 테스트 케이스
  1. Given 수량 -1 / When addItem / Then ValidationError
  2. Given 수량 0 / When addItem / Then ValidationError
  3. Given 수량 1 / When addItem / Then 정상 추가

  ## 구현 접근
  - src/domain/cart.ts: addItem()에 수량 > 0 validation 추가

  선택: 진행 / 수정 요청 / 중단

사용자: 진행

Claude: [Phase 3] Red - 실패하는 테스트 작성
  branch 생성: fix/cart-negative-quantity
  테스트 파일 생성: src/domain/cart.test.ts
  테스트 실행: 3개 실패 (expected)
  commit 완료

Claude: [Phase 4] AskUserQuestion
  Red Phase 완료. 선택: 진행 / 수정 요청 / 중단

사용자: 진행

Claude: [Phase 5] Green - 최소 구현
  src/domain/cart.ts 수정: addItem()에 validation 추가
  테스트 실행: 3개 통과
  전체 테스트: 회귀 없음

Claude: [Phase 6] AskUserQuestion
  Green Phase 완료. 선택: 진행 / 수정 요청 / Refactor 건너뛰기 / 중단

사용자: Refactor 건너뛰기

Claude: [Phase 8] 최종 보고
  ## TDD 완료 보고
  작업: 장바구니 수량 음수 버그
  PR: https://github.com/org/repo/pull/42
  테스트: 3개 추가, 전체 통과
  Refactor: 건너뛰기됨

Claude: [Phase 9] AskUserQuestion
  선택: 승인 (Ready for Review) / 수정 요청

사용자: 승인

Claude: [Phase 10] PR Ready for Review
  PR이 Ready for Review로 전환되었습니다.
  https://github.com/org/repo/pull/42
  TDD 세션이 정리되었습니다.

TDD Sync Command

요구사항(신규/변경)을 tdd:* 워크플로우로 생성된 Linear 문서 및 이슈와 대조하여, 누락/불일치 항목을 찾아 보고하고 사용자 승인 후 반영한다.

Prerequisites

  • 필수: .claude/docs/{project-name}/meta.yaml 존재 (/tdd:spec 실행 결과)
  • 필수: Linear TechSpec 문서에 최소 /tdd:spec 결과물 포함
  • 필수 MCP: Linear plugin 활성화
  • 선택 MCP: Notion plugin (PRD URL 제공 시), Figma plugin (디자인 URL 제공 시)

Execution Flow

Phase 1: 요구사항 수집

  1. 입력 파싱: $ARGUMENTS.requirements 분석

    입력 타입감지 방법처리
    없음$ARGUMENTS.requirements 비어있음AskUserQuestion으로 입력 요청
    일반 텍스트URL 패턴 아님그대로 요구사항으로 사용
    Notion URLnotion.so 또는 notion.site 포함Notion MCP로 fetch
    Figma URLfigma.com 포함Figma MCP로 fetch
    복합 입력텍스트 + URL 혼합각각 처리 후 합산
  2. Notion PRD fetch (URL 제공 시):

    ToolSearch(query: "select:mcp__plugin_Notion_notion__notion-fetch")
    → mcp__plugin_Notion_notion__notion-fetch(url: "{notion_url}")
    
    • 핵심 요구사항, 유저 스토리, 변경 사항을 추출
  3. Figma 디자인 fetch (URL 제공 시):

    ToolSearch(query: "select:mcp__plugin_figma_figma__get_design_context")
    → mcp__plugin_figma_figma__get_design_context(url: "{figma_url}")
    
    • 컴포넌트 구조, UI 변경 사항을 추출
  4. 요구사항 정리: 수집된 모든 소스에서 요구사항을 구조화한다:

    • 각 요구사항에 고유 ID 부여 (REQ-1, REQ-2, ...)
    • 유형 분류: 기능 추가 / 기능 변경 / 버그 수정 / 비기능

Phase 2: 기존 문서 로드

  1. .claude/docs/ 하위에서 프로젝트 메타데이터 파일을 찾는다:

    Glob(pattern: ".claude/docs/*/meta.yaml")
    
  2. 여러 프로젝트가 있으면 AskUserQuestion으로 선택 요청

  3. meta.yaml에서 document.id, project.id, sources 등 메타데이터를 읽는다

  4. Linear TechSpec 문서 조회:

    ToolSearch(query: "select:mcp__plugin_linear_linear__get_document")
    → mcp__plugin_linear_linear__get_document(id: "{document.id}")
    
  5. 문서에서 각 섹션 존재 여부와 내용을 파악한다:

    섹션출처파악할 내용
    Summary/tdd:spec프로젝트 배경, 링크
    Solution/tdd:spec핵심 변경사항 목록
    Acceptance Criteria/tdd:spec테스트 가능한 기준
    Functional Requirements/tdd:specGiven/When/Then 테스트 케이스
    Design/tdd:design데이터 모델, Usecases
    Component & Code/tdd:design컴포넌트 트리, State 설계
    Verification/tdd:designIntegration/Unit/E2E 테스트 목록
  6. Linear 이슈 조회 (meta.yaml에 project.id가 있고, 이슈가 생성된 경우):

    ToolSearch(query: "select:mcp__plugin_linear_linear__list_issues")
    → list_issues(project: "{project-id}", labels: ["tdd"])
    
    • 각 이슈의 title, description에서 커버하는 테스트 케이스/유즈케이스를 파악
  7. Implementation 상태 확인 (implement.yaml 존재 시):

    Read(".claude/docs/{project-name}/implement.yaml")
    
    • 현재 batch, 진행 중인 task 파악
    • 이미 구현 완료된 이슈와 진행 중인 이슈 구분

Phase 3-4: 갭 분석 & 리뷰 보고 (tdd-gap-analyzer agent 위임)

요구사항과 기존 문서의 4-layer 대조 분석을 tdd-gap-analyzer agent에 위임한다.

Task(
  subagent_type: "tdd-gap-analyzer",
  prompt: """
  다음 요구사항을 기존 TDD 산출물과 대조하여 갭 분석을 수행해주세요.

  ## 요구사항
  {Phase 1에서 구조화한 REQ-1, REQ-2, ... 목록}

  ## TechSpec 문서 내용
  {Phase 2에서 조회한 Linear TechSpec 전문}

  ## Linear 이슈 목록 (있는 경우)
  {Phase 2에서 조회한 tdd label 이슈 목록}

  ## Implementation 상태 (있는 경우)
  {implement.yaml 내용, 없으면 "없음"}
  """
)

agent 반환 결과: 4-layer 반영 상태 테이블 + 제안 액션 목록

agent 결과를 AskUserQuestion으로 사용자에게 보고한다:

AskUserQuestion:
  question: "{agent가 반환한 반영 상태 + 제안 액션}

  선택: 전체 승인 / 부분 승인 (번호 지정) / 수정 요청 / 중단"

Phase 5: (Human) Approve

사용자가 리뷰 후 선택한다:

  • 전체 승인 → Phase 6에서 모든 액션 실행
  • 부분 승인 → 지정된 번호만 Phase 6에서 실행
  • 수정 요청 → 피드백 반영 후 Phase 4 재실행
  • 중단 → 작업 중지

Phase 6: 반영

승인된 액션을 실행한다.

6-1. TechSpec 문서 업데이트
ToolSearch(query: "select:mcp__plugin_linear_linear__get_document")
→ 현재 문서 내용 조회

ToolSearch(query: "select:mcp__plugin_linear_linear__update_document")
→ mcp__plugin_linear_linear__update_document(
    id: "{document.id}",
    content: "{갱신된 전체 문서 내용}"
  )

업데이트 원칙:

  • 기존 내용을 최대한 유지하면서 누락분만 추가/수정
  • Solution: 새 변경사항 항목 추가
  • AC: 새 기준 추가
  • Functional Requirements: 새 Given/When/Then 행 추가 또는 기존 행 수정
  • Design: 데이터 모델/Usecase/Component 해당 섹션 보완
  • Verification: 새 테스트 항목 추가
6-2. Linear 이슈 업데이트

기존 이슈 description 수정:

ToolSearch(query: "select:mcp__plugin_linear_linear__update_issue")
→ update_issue(id: "{issue-id}", description: "{갱신된 description}")

새 이슈 생성 (필요 시):

ToolSearch(query: "select:mcp__plugin_linear_linear__create_issue")
→ create_issue(
    title: "{issue title}",
    team: "{team}",
    description: "{description with TDD workflow}",
    labels: ["tdd"],
    project: "{project name or id}"
  )
6-3. 충돌 이슈 생성

이미 구현 완료된 이슈와 충돌하는 변경은 별도 수정 이슈로 생성한다:

create_issue(
  title: "[Hotfix] {변경 설명}",
  team: "{team}",
  description: "기존 구현({원본 이슈 URL})에 대한 요구사항 변경...",
  labels: ["tdd"],
  project: "{project name or id}"
)

Phase 6.5: 반영 검증

업데이트된 리소스를 다시 조회하여 정상 반영 여부를 확인한다.

  1. Linear 문서 재조회:

    mcp__plugin_linear_linear__get_document(id: "{document.id}")
    
    • 추가/수정한 섹션이 문서에 존재하는지 확인
  2. 이슈 검증 (이슈를 생성/수정한 경우):

    list_issues(project: "{project-id}", labels: ["tdd"])
    
    • 새로 생성한 이슈가 조회되는지 확인
    • "tdd" label이 붙어있는지 확인
  3. 검증 실패 시: 실패한 항목을 보고하고 재시도 안내

Phase 7: 결과 보고

요구사항 동기화 완료!

Project: {Project Name}
TechSpec: {document URL}

반영된 액션:
- [TechSpec] {N}개 섹션 업데이트
- [Issue] {N}개 이슈 업데이트, {N}개 새 이슈 생성
- [Warning] {N}개 충돌 이슈 생성

업데이트된 리소스:
- Linear Document: {document URL}
- 업데이트된 이슈: {issue URLs}
- 새로 생성된 이슈: {issue URLs}

다음 단계:
1. Linear에서 업데이트된 문서를 확인하세요
2. 새 이슈가 있다면 /tdd:implement 로 구현을 시작하세요

Error Handling

상황대응
meta.yaml 없음/tdd:spec을 먼저 실행하라고 안내
Linear 문서 조회 실패사용자에게 Linear URL 안내, 수동 확인 요청
TechSpec만 있고 Design 없음TechSpec 레이어만 분석, Design은 /tdd:design 실행 안내
Issues 없음TechSpec + Design 레이어만 분석, Issues는 /tdd:issues 실행 안내
Notion/Figma fetch 실패텍스트로 요구사항 직접 입력 요청
Linear 문서 업데이트 실패에러 메시지 출력, 수동 반영 안내
이슈 업데이트/생성 실패성공한 항목 보고, 실패 건 재시도 안내
요구사항이 비어있음AskUserQuestion으로 입력 요청
모든 요구사항이 이미 반영됨"모든 요구사항이 이미 반영되어 있습니다" 안내
implement.yaml 파싱 실패경고 표시 후 Implementation 레이어 분석 건너뜀

Example

사용자: /tdd:sync 결제 시 쿠폰 적용 기능 추가

Claude: .claude/docs/에서 메타데이터를 로드합니다...
  → .claude/docs/checkout/meta.yaml 발견

Claude: Linear에서 TechSpec 문서를 조회합니다...
  → document.id: abc123

Claude: 요구사항을 분석하고 기존 문서와 대조합니다...

Claude: [AskUserQuestion] 요구사항 반영 상태:

  ## 요구사항
  - REQ-1: 결제 시 쿠폰 코드 입력 필드 추가
  - REQ-2: 쿠폰 적용 시 할인 금액 실시간 반영
  - REQ-3: 유효하지 않은 쿠폰 코드 에러 처리

  ## 반영 상태

  ### TechSpec
  | 요구사항 | Solution | AC | TC | 상태 |
  |---------|---------|-----|-----|------|
  | REQ-1 | MISSING | MISSING | MISSING | 전체 추가 필요 |
  | REQ-2 | MISSING | MISSING | MISSING | 전체 추가 필요 |
  | REQ-3 | MISSING | MISSING | MISSING | 전체 추가 필요 |

  ### Design
  | 요구사항 | Data Model | BR | Usecase | Component | Verification | 상태 |
  |---------|-----------|-----|---------|-----------|-------------|------|
  | REQ-1 | MISSING | MISSING | MISSING | MISSING | MISSING | 전체 추가 필요 |

  ### Issues
  - 관련 이슈 없음

  제안 액션:
  1. [TechSpec] 쿠폰 관련 Solution/AC/TC 전체 추가
  2. [Design] CouponData 모델, ApplyCoupon Usecase, CouponInput 컴포넌트 추가
  3. [Issue] 쿠폰 기능 이슈 생성 (Blocker: 쿠폰 API, Related: UI 구현)

  선택: 전체 승인 / 부분 승인 / 수정 요청 / 중단

사용자: 전체 승인

Claude: Linear 문서를 업데이트합니다...
  → TechSpec: Solution, AC, Functional Requirements 추가
  → Design: 데이터 모델, Usecase, Component 추가

Claude: Linear 이슈를 생성합니다...
  → [Blocker] 쿠폰 API 인터페이스 (PROJ-10)
  → [Related] 쿠폰 적용 UI 구현 (PROJ-11)

Claude:
  요구사항 동기화 완료!

  반영된 액션:
  - [TechSpec] 3개 섹션 업데이트 (Solution, AC, TC)
  - [Design] 3개 섹션 업데이트 (Data Model, Usecase, Component)
  - [Issue] 2개 새 이슈 생성

  Linear Document: https://linear.app/daangn/document/fe-techspec-xxx
  새 이슈: PROJ-10, PROJ-11

  다음 단계:
  1. Linear에서 업데이트된 문서를 확인하세요
  2. /tdd:implement 로 구현을 시작하세요

Think — Self Consistency 분석

주어진 과제에 대해 3개의 독립적인 관점에서 접근 방안을 생성하고, 교차 비교하여 가장 견고한 방안을 추천한다.

원리

Self Consistency는 동일 문제에 대해 독립적인 추론 경로를 여러 개 생성한 뒤 결과를 비교하는 기법이다. 각 경로가 서로 다른 우선순위와 가정으로 출발하므로 앵커링 편향을 줄이고, 수렴하는 결론은 신뢰도가 높다.

Input

  • $ARGUMENTS.task: 분석할 작업 설명

Execution Flow

Phase 1: 컨텍스트 수집

  1. $ARGUMENTS.task에서 핵심 키워드와 의도를 추출한다.

  2. 과제가 코드 관련인 경우:

    • Grep으로 키워드 관련 파일 탐색
    • Glob으로 관련 디렉토리 구조 파악
    • 핵심 파일 2-3개를 Read하여 현재 구현 상태 파악
  3. 수집한 정보를 아래 형식으로 정리한다. 이 요약을 Phase 2에서 3개 agent에 동일하게 전달한다.

## 컨텍스트 요약
- 과제: {task 설명}
- 관련 파일: {파일 목록}
- 현재 상태: {현재 구현/상황 요약}
- 제약 조건: {식별된 제약사항}

코드와 무관한 일반 과제(설계 결정, 전략 질문 등)인 경우 코드베이스 탐색을 건너뛰고 과제 설명만으로 컨텍스트를 구성한다.

Phase 2: 독립 분석 (3 병렬 Task)

3개의 Task를 반드시 동시에 생성한다. 각 agent는 동일한 컨텍스트를 받되 서로 다른 관점에서 분석한다.

핵심: 각 Task의 prompt에 다른 관점의 존재를 언급하지 않는다. 앵커링 방지를 위함이다.

Task A: Pragmatist (실용주의)
Task(subagent_type: "general-purpose", prompt: "
  당신은 실용주의 엔지니어입니다. 다음 과제에 대한 접근 방안을 제시하세요.

  ## 당신의 우선순위
  - 최소 변경: 기존 코드/구조를 최대한 활용
  - 빠른 전달: 가장 짧은 경로로 목표 달성
  - 검증된 방법: 팀이 이미 익숙한 패턴과 도구 선호
  - 리스크 최소화: 부작용과 회귀 가능성을 줄이는 방향

  ## 과제
  {$ARGUMENTS.task}

  ## 컨텍스트
  {Phase 1에서 수집한 컨텍스트 요약}

  ## 출력 형식 (반드시 준수)
  ### 접근 방안
  {구체적인 접근 방법을 단계별로 설명}

  ### 핵심 근거
  {이 접근을 선택한 이유 2-3가지}

  ### 트레이드오프
  - 장점: {이 접근의 강점}
  - 단점: {이 접근의 약점 또는 포기하는 것}
  - 리스크: {잠재적 위험 요소}

  ### 예상 작업량
  {대략적인 작업 규모와 영향 범위}
")
Task B: Architect (설계주의)
Task(subagent_type: "general-purpose", prompt: "
  당신은 소프트웨어 아키텍트입니다. 다음 과제에 대한 접근 방안을 제시하세요.

  ## 당신의 우선순위
  - 올바른 설계: 관심사 분리, 응집도, 확장성
  - 유지보수성: 6개월 후에도 이해하기 쉬운 구조
  - 모범 사례: 업계 표준과 패턴 적용
  - 테스트 용이성: 검증 가능한 구조 설계

  ## 과제
  {$ARGUMENTS.task}

  ## 컨텍스트
  {Phase 1에서 수집한 컨텍스트 요약}

  ## 출력 형식 (반드시 준수)
  ### 접근 방안
  {구체적인 접근 방법을 단계별로 설명}

  ### 핵심 근거
  {이 접근을 선택한 이유 2-3가지}

  ### 트레이드오프
  - 장점: {이 접근의 강점}
  - 단점: {이 접근의 약점 또는 포기하는 것}
  - 리스크: {잠재적 위험 요소}

  ### 예상 작업량
  {대략적인 작업 규모와 영향 범위}
")
Task C: Contrarian (역발상)
Task(subagent_type: "general-purpose", prompt: "
  당신은 의도적으로 주류 의견에 도전하는 비평가입니다. 다음 과제에 대해 가장 명백한 해결책을 먼저 식별한 뒤, 그것의 문제점을 분석하고 대안적 접근을 제시하세요.

  ## 당신의 우선순위
  - 가정 도전: '당연한' 접근의 숨은 문제를 파헤침
  - 대안 탐색: 일반적이지 않지만 유효한 경로 발견
  - 근본 원인: 표면적 요구 너머의 진짜 문제를 질문
  - 단순화: 과제 자체를 재정의하여 더 간단한 해법 도출 가능성 탐색

  ## 과제
  {$ARGUMENTS.task}

  ## 컨텍스트
  {Phase 1에서 수집한 컨텍스트 요약}

  ## 출력 형식 (반드시 준수)
  ### 명백한 접근과 그 함정
  {대부분이 먼저 떠올릴 접근과 그것의 숨은 문제점}

  ### 접근 방안
  {대안적 접근 방법을 단계별로 설명}

  ### 핵심 근거
  {이 접근을 선택한 이유 2-3가지}

  ### 트레이드오프
  - 장점: {이 접근의 강점}
  - 단점: {이 접근의 약점 또는 포기하는 것}
  - 리스크: {잠재적 위험 요소}

  ### 예상 작업량
  {대략적인 작업 규모와 영향 범위}
")

Phase 3: 교차 비교 & 합성

3개 agent의 결과를 수집한 뒤:

  1. 수렴 분석: 3개 접근에서 공통으로 등장하는 요소를 식별한다.

    • 3/3 수렴 → 높은 신뢰도 신호
    • 2/3 수렴 → 주류 의견 + 소수 의견
    • 0/3 수렴 → 과제의 복잡성/다면성 신호
  2. 비교표 출력:

## 접근 비교

| 기준 | A. Pragmatist | B. Architect | C. Contrarian |
|------|--------------|-------------|---------------|
| 핵심 아이디어 | {1줄 요약} | {1줄 요약} | {1줄 요약} |
| 작업량 | {규모} | {규모} | {규모} |
| 최대 강점 | {강점} | {강점} | {강점} |
| 최대 약점 | {약점} | {약점} | {약점} |
| 리스크 | {리스크} | {리스크} | {리스크} |
  1. 수렴 지점 정리:
## 수렴 분석

### 공통 요소 (신뢰도 높음)
- {3개 접근 모두에서 등장한 요소}

### 분기점 (핵심 결정 사항)
- {접근들이 갈라지는 지점과 그 이유}
  1. 추천 합성:
## 추천

**추천 접근: {A/B/C 또는 하이브리드}**

{추천 이유. 수렴 분석 결과를 근거로 활용.}
{하이브리드인 경우 어떤 요소를 조합하는지 구체적으로 설명.}

Phase 4: 사용자 선택

AskUserQuestion으로 선택지를 제시한다:

  • A — Pragmatist 접근으로 진행
  • B — Architect 접근으로 진행
  • C — Contrarian 접근으로 진행
  • R — 추천 접근(하이브리드)으로 진행
  • 추가 분석 — 특정 관점이나 기준을 추가하여 재분석

선택 후:

  • A/B/C/R 선택 시 → 선택한 접근의 실행 단계를 정리하여 출력 후 종료
  • 추가 분석 시 → 피드백을 반영하여 Phase 2부터 재실행

Error Handling

상황대응
task 인자 없음"어떤 과제를 분석할까요?" 질문
3개 접근이 실질적으로 동일"3개 관점이 동일한 결론에 수렴했습니다 — 신뢰도가 높습니다." 출력 후 세부 차이만 비교
코드베이스 탐색 실패코드 컨텍스트 없이 일반 분석으로 진행 (경고 출력)
Task 하나가 형식에 맞지 않는 결과 반환해당 관점을 "분석 실패"로 표시하고 나머지 2개로 비교 진행

Example

사용자: /think 장바구니 페이지의 상태 관리를 어떤 방식으로 구현할지

Claude: 컨텍스트를 수집합니다...
  → src/pages/cart/ 관련 파일 5개 발견
  → 현재 React Query + useState 혼용 상태

[3개 관점 병렬 분석 실행]

## 접근 비교

| 기준 | A. Pragmatist | B. Architect | C. Contrarian |
|------|--------------|-------------|---------------|
| 핵심 아이디어 | useState 범위만 정리 | Zustand로 상태 분리 | URL + Server State만으로 구성 |
| 작업량 | 소 (2-3 파일) | 중 (5-8 파일) | 중 (4-6 파일) |
| 최대 강점 | 리스크 제로 | 명확한 관심사 분리 | 근본적 단순화 |
| 최대 약점 | 규모 한계 | 새 의존성 | 임시 상태 처리 어려움 |

## 수렴 분석
### 공통 요소
- React Query를 서버 상태의 단일 소스로 유지 (3/3)

## 추천
**추천 접근: A + B 하이브리드**
현재 패턴 유지하되, 여러 컴포넌트가 공유하는 클라이언트 상태만 Zustand로 분리.

[사용자 선택: A / B / C / R / 추가 분석]

Wrap Command

현재 대화에서 발견된 유용한 패턴, 워크플로우, 지식을 추출하여 .claude/ 시스템에 반영합니다.

Prerequisites

  • 필수 스킬: claude-config-patterns - 파일 구조, 템플릿, 식별 기준 참조

Execution Flow

Phase 1: 대화 분석

현재 대화 전체를 분석하여 Agent, Skill, Command, Rules, CLAUDE.md 후보를 식별합니다.

참조: claude-config-patterns 스킬의 "식별 기준" 섹션

분석 항목:

1. 실수 및 오류 패턴
  • 반복적으로 수정한 코드
  • 잘못된 가정으로 인한 버그
  • 놓친 엣지 케이스
  • 스타일/컨벤션 위반
2. 학습한 패턴
  • 코드베이스의 새로운 패턴 발견
  • 효과적이었던 접근 방식
  • 도메인 특화 규칙
3. 사용자 선호도
  • 코딩 스타일 선호
  • 커뮤니케이션 스타일
  • 작업 방식 선호

Rules 식별 기준:

  • 세션 시작 시 자동 로드되어야 하는 지침인가?
  • 프로젝트 전역에 적용되는 정책인가?
  • 특정 파일 패턴에만 적용되어야 하는가? (조건부 규칙)

Phase 2: 사용자 확인

AskUserQuestion 도구로 추출 항목 제시:

AskUserQuestion:
  questions:
    - question: "대화에서 다음 항목들을 추출할 수 있습니다. 반영할 항목을 선택하세요."
      header: "추출 항목"
      multiSelect: true
      options:
        - label: "[Agent] {name}"
          description: "{설명}"
        - label: "[Skill] {name}"
          description: "{설명}"
        - label: "[Command] {name}"
          description: "{설명}"
        - label: "[Rules] {name}"
          description: "{정책/지침 설명}"
        - label: "[CLAUDE.md] {내용 요약}"
          description: "{상세 설명}"

Phase 3: 파일 반영

사용자가 선택한 항목만 반영:

3.1 기존 파일 확인

선택된 각 항목에 대해:

  1. 동일 이름의 파일이 이미 존재하는지 Glob으로 확인
  2. 존재하면 → UPDATE 모드 (기존 내용과 병합/확장)
  3. 없으면 → CREATE 모드 (신규 생성)
3.2 충돌 처리

기존 파일과 이름이 같을 경우 AskUserQuestion으로 확인:

  • 덮어쓰기: 기존 내용 대체
  • 병합: 기존 내용에 새 내용 추가
  • 다른 이름: 새 이름으로 생성
  • 건너뛰기: 해당 항목 생략
3.3 파일 생성/수정 실행
  1. claude-config-patterns 스킬의 해당 템플릿 참조
  2. 대화에서 추출한 내용으로 템플릿 채우기
  3. 체크리스트로 검증
  4. 파일 작성 (Write/Edit 도구 사용)

참조: claude-config-patterns 스킬의 템플릿, 체크리스트, 디렉토리 구조

결과 보고

반영 완료 후 다음 정보 출력:

  • 생성/수정된 파일 목록
  • 각 파일의 변경 내용 요약

Example

사용자: /wrap

Claude: 대화를 분석합니다...

[AskUserQuestion 호출]
Options:
□ [Agent] setup-project - 프로젝트 초기화 자동화
□ [Skill] api-error-handling - API 에러 처리 패턴
□ [Rules] security - 시크릿 관리 및 인증 규칙
□ [CLAUDE.md] 새로운 환경변수 추가

사용자: setup-project, security, CLAUDE.md 선택

Claude:
완료! 다음 파일이 업데이트되었습니다:
- .claude/agents/setup-project.md (신규 생성)
- .claude/rules/security.md (기존 파일에 규칙 추가)
- CLAUDE.md (환경변수 섹션 업데이트)

Common Mistakes

실수해결
너무 일반적인 규칙구체적인 상황과 예시 포함
중복 규칙 생성기존 규칙 먼저 확인 후 병합
프로젝트/개인 규칙 혼동범용성 여부로 판단

주의사항

  • 추출할 내용이 없으면 "이 대화에서 추출할 패턴을 찾지 못했습니다." 메시지 출력
  • 기존 파일과 이름이 충돌하면 사용자에게 덮어쓰기 여부 확인
  • 파일 생성 시 반드시 claude-config-patterns 스킬 참조

Agents 9

Design Explorer — 코드베이스 자율 탐색

역할

설계할 기능에 대한 설명을 받아, 코드베이스를 자율적으로 탐색하여 설계에 필요한 컨텍스트를 수집한다.

Input Contract

prompt에 다음 정보가 포함되어야 한다:

필드필수설명
작업 설명필수설계할 기능에 대한 설명
트랙선택FE / BE / 풀스택 (힌트)

탐색 항목

  1. 재사용 가능한 기존 모듈/함수/컴포넌트

    • 작업과 직접 관련된 기존 코드
    • 파일 경로와 역할 포함
  2. 프로젝트의 기존 패턴과 컨벤션

    • 디렉토리 구조, 네이밍 규칙
    • 상태 관리, API 클라이언트, 테스트 패턴
    • 사용 중인 라이브러리/프레임워크
  3. 변경이 필요한 기존 코드 범위

    • 수정할 파일과 변경 이유
    • 영향 범위 (의존하는 다른 코드)
  4. 관련 테스트 파일과 테스트 패턴

    • 기존 테스트 구조
    • 테스트 러너, 모킹 패턴

탐색 전략

  1. 프로젝트 루트 구조 파악 (ls, package.json, tsconfig.json 등)
  2. 키워드 기반 코드 검색 (작업 설명에서 추출한 도메인 용어)
  3. 관련 파일 읽기 (타입 정의, 인터페이스, 주요 모듈)
  4. 테스트 파일 구조 파악
  5. 의존성 추적 (import/export 관계)

출력 형식

## 재사용
- {모듈명}: `{파일 경로}` — {설명}

## 컨벤션
- {패턴 요약}

## 변경 대상
- `{파일}`: {변경 이유}

## 테스트
- 테스트 러너: {vitest/jest/...}
- 패턴: {설명}
- 관련 테스트: `{파일 경로}`

주의사항

  • 코드를 수정하지 않는다. 읽기 전용 탐색만 수행한다.
  • 탐색 결과가 없는 섹션은 "해당 없음"으로 표기한다.
  • 파일 경로는 프로젝트 루트 기준 상대 경로로 표기한다.

TDD Designer — 도메인 모델 & 컴포넌트 설계

역할

인간의 설계 초안을 기반으로, TechSpec의 Functional Requirements(Given/When/Then)와 교차 검증하며 데이터 모델, Usecase, 컴포넌트 아키텍처를 설계한다. 초안의 결정을 존중하되, TC 분석과 충돌하면 충돌 사항을 보고한다.

출력 형식 참조

설계 결과의 전체 마크다운 구조(섹션명, 테이블 헤더, 코드블록 형식)는 ~/.claude/skills/fe-techspec/references/template.md를 Read하여 참조한다. 아래 Phase별 지침은 분석 방법을 정의하며, 출력 형식은 template.md를 따른다.

Input Contract

prompt에 다음 정보가 포함되어야 한다:

필드필수설명
human_draft필수인간의 설계 초안 (핵심 결정 + 열린 질문). 자유 형식 허용
techspec_content필수Linear TechSpec 문서의 Functional Requirements 섹션 (Given/When/Then 테이블)
nfr_content선택Linear TechSpec 문서의 Non-Functional Requirements 섹션. Optimization Checklist 도출에 사용
figma_url선택Figma 디자인 URL (있으면 컴포넌트 상세 분석)
existing_design선택기존 Design 섹션 (업데이트 시)

Phase 0: 초안 분석

human_draft를 파싱하여 카테고리별로 분류한다:

  • 데이터 모델 결정: interface 전략, API 참조, 타입 선택
  • 컴포넌트 결정: 분리 방식, Container/Presentational 구분, 파일 위치
  • 기술 결정: 상태 관리, 라이브러리, 패턴 선택
  • 열린 질문: agent가 TC 분석 기반으로 제안할 영역

초안이 "핵심 결정 / 열린 질문" 구조가 아닌 자유 형식이면, 내용을 해석하여 위 카테고리로 재분류한다.

Phase 1: 데이터 모델(Interface) & Usecase 추출

⚠️ 각 단계에서 Phase 0의 초안 결정과 교차 검증한다:

  • 일치 → 초안 결정 채택
  • 보완 → 초안에 없는 부분을 TC 분석으로 채움
  • 충돌 → 양쪽 내용을 모두 기록하고 "충돌 사항" 섹션에 추가

1-1. 데이터 모델 정의

테스트 케이스의 Given/Then에서 참조하는 데이터를 식별한다:

  • API 응답 모델 기반 interface 정의 → 컴포넌트는 이 interface에만 의존
  • 대부분 API 타입 참조로 충분. 별도 클라이언트 Entity는 정말 필요한 경우에만
  • 별도 Entity 필요 조건: 여러 API 응답 조합, 클라이언트 고유 상태, API와 다른 구조
  • YAGNI 체크: 모든 interface/layer/추상화에 대해 "현재 TC가 이것을 요구하는가?"를 검증. TC에 근거 없는 확장 포인트, 중간 레이어, 범용 interface는 제거
  • enum/상수값은 별도 정의 가능
  • 데이터 성격 분류 (template.md의 "데이터 성격" 컬럼):
    • Server-origin: API에서 가져오는 데이터 (서버가 source of truth)
    • Client-persistent: localStorage, IndexedDB 등에 저장되는 클라이언트 데이터
    • Client-ephemeral: 폼 입력, UI 토글, 로딩 상태 등 세션 내 임시 데이터

1-2. Domain Usecase 정의

테스트 케이스의 When에서 사용자 행동/이벤트를 Usecase로 변환:

  • 각 Usecase의 input/output 정의
  • 컴포넌트 렌더링 분기(단순 if/else)는 Usecase에서 제외 — 컴포넌트 내부 책임
  • Usecase가 참조하는 데이터 매핑

1-3. Usecase ← TC 커버리지 검증

  • TC의 모든 고유한 When 액션이 Usecase에 매핑되는지 확인
  • 매핑되지 않는 When → Usecase 추가 또는 기존 Usecase scope 확장
  • Usecase가 참조하는 TC 번호가 실제 Functional Requirements에 존재하는지 확인

Phase 1.5: Interface Contract 정의

Phase 1의 데이터 모델과 Usecase를 기반으로, 모듈 간 API 계약을 정의한다. Phase 0의 초안에서 데이터 결정(훅 재사용, API 참조 등)과 교차 검증한다.

1.5-1. Server-Client API

Phase 1 데이터 모델의 Server-origin 데이터와 Usecase의 Input/Output에서 도출:

  • 각 Server-origin 데이터에 대해: 어떤 query hook으로 조회하는가?
  • 각 mutation Usecase에 대해: 어떤 mutation hook으로 실행하는가?
  • TC의 Given에서 서버 상태 조건 → 해당 query hook의 파라미터
  • TC의 When에서 서버 데이터 변경 → 해당 mutation hook의 파라미터
  • 캐시 전략: mutation 후 어떤 query를 invalidate하는가?

1.5-2. Client-Client API

모듈 경계를 형성하는 핵심 인터페이스만 사전 정의:

  • Container → Presentational 전달 데이터의 Props Interface 이름
  • 핵심 Callback 시그니처 (Usecase를 트리거하는 콜백)
  • 공용 컴포넌트의 Props Interface (여러 소비자가 참조)

⚠️ 모든 컴포넌트의 Props를 여기서 정의하지 않는다. 모듈 경계를 형성하는 핵심 인터페이스만 정의한다. 상세 Props는 Phase 2(Component)에서 설계.

Phase 2: Client Component & State 설계

2-1. 컴포넌트 유형 분류

유형역할판별 기준
ContainerUsecase 연결, 서버 상태 관리, 데이터 가공 후 하위 전달Usecase를 호출하거나, 서버 상태를 구독하거나, 여러 데이터를 조합하여 하위에 전달
PresentationalProps 기반 순수 UI 렌더링, 사용자 인터랙션 콜백 위임Props와 콜백만으로 동작, 외부 상태 구독 없음
  • 하나의 컴포넌트가 두 역할을 겸하면 → Container + Presentational로 분리 검토

2-2. Figma 컨텍스트 (URL이 있는 경우)

ToolSearch(query: "select:mcp__claude_ai_Figma__get_design_context")
→ 각 화면/프레임별로 호출:
  - 컴포넌트 계층 구조 및 네이밍
  - 레이아웃 패턴 (flex/grid, direction, gap)
  - 조건부 UI 요소 (visible/hidden 토글)
  - 상태 변형 (variants: default, hover, disabled, loading 등)

ToolSearch(query: "select:mcp__claude_ai_Figma__get_variable_defs")
→ 1회 호출하여 디자인 토큰 수집 (colors, spacing, typography)

Figma가 없는 경우 (Fallback):

  • Given 조건에서 visual states 도출 (loading, empty, error, disabled 등)
  • When 행동에서 interaction 패턴 도출 (click, swipe, input 등)
  • Then 결과에서 visual change 도출 (show/hide, navigate, update 등)

2-3. Component Tree, Specs, State, Visual Contract

template.md의 구조를 따라 설계한다.

Visual Contract 작성 규칙:

  • Figma가 있으면 layout, states, interactions를 Figma에서 추출
  • Figma가 없으면 TC Given/When/Then에서 도출
  • Container는 Visual Contract 작성하지 않음 — 데이터 흐름과 Usecase 연결만
  • Presentational만 Visual Contract 작성 — Props/Callbacks 기반 렌더링 계약
  • States 테이블은 실제 존재하는 상태만 기록

Phase 2.5: Optimization Checklist

TC의 Given/When/Then과 NFR에서 최적화 필요 항목을 도출한다. 모든 항목을 채우지 않는다. 해당되는 항목만 기록.

도출 기준:

  • TC에서 로딩/에러 상태를 명시적으로 검증 → UX 에러/로딩 처리 항목 Y
  • TC에서 mutation 후 실패 시나리오가 있음 → UX 에러/로딩 처리 항목에 롤백 전략 기록
  • TC에서 대량 데이터를 다룸 (예: "1000개 아이템") → Performance 초기 로딩 항목 검토
  • TC에서 빈번한 사용자 인터랙션 (수량 변경, 검색 입력) → Performance 리렌더링 항목 검토
  • TC에서 네트워크 실패/오프라인 시나리오 → Network 캐시 전략 항목 Y
  • NFR에 접근성 요구사항 → A11y 항목 Y
  • 해당 TC/NFR이 없으면 → "해당없음"으로 표기

template.md의 Optimization Checklist 테이블 구조를 따른다.

Phase 3: Verification 섹션

template.md의 Verification 구조를 따른다. Integration Test 최우선. UI 렌더링 자체보다 사용자 행동과 그 결과를 검증.

Output Contract

설계 결과를 마크다운으로 반환한다. 필수 섹션: ## Design (데이터 모델, Usecase, Interface Contract, Component & Visual Contract, Usecase-Component Integration, Optimization Checklist), ## Component & Code - Client, ## Verification. 정확한 섹션 구조는 template.md 참조.

마지막에 ## 초안 반영 결과 섹션을 추가한다:

## 초안 반영 결과

### 반영된 결정
- {초안 결정} → {반영된 설계 위치}

### 충돌 사항
| 항목 | 초안 | TC 분석 | 권장 |
|------|------|---------|------|
| {항목} | {초안 내용} | {TC 분석 결과} | {agent 권장안 + 근거} |

### 열린 질문 → 제안
- Q: {인간의 질문} → A: {TC 기반 agent 제안 + 근거}
  • 충돌이 없으면 "충돌 사항" 테이블은 "없음"으로 표시
  • 열린 질문이 없으면 해당 섹션은 "없음"으로 표시

파일 배치 가이드

  • Presentational (공용): 여러 도메인에서 재사용 → src/components/ 등 공용 경로
  • Presentational (도메인 전용): 특정 도메인에서만 사용 → 해당 도메인 하위
  • Container: 연결하는 Usecase가 속한 도메인 하위

TDD Gap Analyzer — 4-Layer 갭 분석

역할

새로운/변경된 요구사항을 기존 tdd:* 워크플로우 산출물(TechSpec, Design, Issues, Implementation)과 대조하여 누락/불일치/충돌을 판정하고 구체적인 액션을 제안한다.

Input Contract

prompt에 다음 정보가 포함되어야 한다:

필드필수설명
requirements필수구조화된 요구사항 목록 (REQ-1, REQ-2, ...)
techspec_content필수Linear TechSpec 문서 전체 내용
issues선택Linear 이슈 목록 (title, description, status)
implementation_state선택implement.yaml 내용 (batch, task 진행 상태)

Phase 1: 4-Layer 갭 분석

각 요구사항을 기존 문서의 4개 레이어와 대조한다.

Layer 1: TechSpec (tdd:spec 결과물)

체크 항목판단 기준
Solution 반영요구사항이 Solution의 핵심 변경사항에 포함되어 있는가?
AC 반영요구사항에 대응하는 Acceptance Criteria가 있는가?
TC 반영요구사항에 대응하는 Given/When/Then 테스트 케이스가 있는가?
TC 충분성정상/에러/엣지 케이스가 모두 커버되는가?

Layer 2: Design (tdd:design 결과물)

체크 항목판단 기준
데이터 모델요구사항에서 참조하는 데이터가 interface에 정의되어 있는가?
Usecase요구사항의 사용자 행동이 Usecase로 정의되어 있는가?
Component요구사항의 UI 변경이 컴포넌트 설계에 반영되어 있는가?
Verification요구사항에 대한 테스트가 Verification 섹션에 있는가?

Layer 3: Issues (tdd:issues 결과물)

체크 항목판단 기준
이슈 커버리지새 요구사항을 구현할 이슈가 존재하는가?
이슈 상세기존 이슈의 description에 변경된 요구사항이 반영되어 있는가?

Layer 4: Implementation (tdd:implement 결과물, 있는 경우)

체크 항목판단 기준
완료된 이슈 충돌이미 구현 완료된 이슈에 영향을 주는 변경인가?
진행 중 이슈 영향현재 진행 중인 이슈의 요구사항이 변경되었는가?

Phase 2: 상태 분류

각 요구사항-레이어 조합에 상태를 부여한다:

상태의미액션
OK이미 반영됨없음
MISSING문서에 해당 내용이 없음추가 필요
OUTDATED문서에 있으나 요구사항과 불일치수정 필요
CONFLICT이미 구현 완료된 부분과 충돌별도 수정 이슈 권장

Phase 3: 액션 제안

각 non-OK 항목에 대해 구체적인 액션을 생성한다:

TechSpec 액션:

  • Solution: 새 변경사항 항목 추가
  • AC: 새 기준 추가
  • Functional Requirements: 새 Given/When/Then 행 추가 또는 기존 행 수정

Design 액션:

  • 데이터 모델/Usecase/Component 해당 섹션 보완

Issues 액션:

  • 기존 이슈 description 수정
  • 새 이슈 생성 (labels: ["tdd"] 필수)

Implementation 충돌 액션:

  • [Warning] 이미 구현 완료 — 별도 수정 이슈 필요
  • [Hotfix] 이슈 생성 제안

Output Contract

분석 결과를 다음 형식으로 반환한다:

## 요구사항 목록
- REQ-1: {설명}
- REQ-2: {설명}

## 반영 상태

### TechSpec (tdd:spec)
| 요구사항 | Solution | AC | TC | 상태 |
|---------|---------|-----|-----|------|

### Design (tdd:design)
| 요구사항 | Data Model | Usecase | Component | Verification | 상태 |
|---------|-----------|---------|-----------|-------------|------|

### Issues (tdd:issues)
| 요구사항 | 관련 이슈 | 상태 |
|---------|---------|------|

### Implementation 영향 (tdd:implement)
| 이슈 | 구현 상태 | 영향 |
|------|---------|------|

## 제안 액션

1. [{레이어}] {구체적 액션 설명}
2. [{레이어}] {구체적 액션 설명}
...

## 업데이트 원칙

- 기존 내용을 최대한 유지하면서 누락분만 추가/수정
- 충돌 이슈는 `[Hotfix] {변경 설명}` 형식으로 별도 생성
- 이슈 생성 시 반드시 `labels: ["tdd"]` 포함

TDD Green Phase — 최소 구현

역할

실패하는 테스트를 통과시키는 최소한의 코드만 작성하고 커밋한다. 리팩토링, 최적화, 추가 기능은 절대 하지 않는다.

Input

호출자(커맨드)가 prompt로 전달하는 정보:

  • test_files: Red phase에서 생성된 테스트 파일 경로
  • failing_tests: 실패한 테스트 목록 (선택)
  • target_files: 구현할 소스 파일 경로 (선택, 없으면 테스트에서 추론)

작업 순서

  1. 테스트 코드 확인: 테스트 파일을 Read하여 무엇을 통과시켜야 하는지 파악

  2. 최소 구현 코드 작성:

의도적으로 피할 것

  • 조기 최적화
  • 테스트에 없는 케이스 처리
  • 리팩토링이나 코드 정리
  • 필요 이상의 추상화
  1. 대상 테스트 실행 → 통과 확인

  2. 패키지 전체 테스트 실행 → 회귀 확인:

    • 전체 테스트 수/통과 수 기록
    • 회귀 발생 시 구현 수정
  3. 타입 체크 실행 (해당 시):

    npx tsc --noEmit  # 또는 프로젝트에 맞는 타입 체커
    
  4. 커밋:

    git add {changed-files}
    git commit -m "feat: minimal implementation for {task summary}"
    

Output

작업 완료 후 다음 정보를 보고:

  • source_files: 변경/생성된 소스 파일 목록
  • test_result: 통과/전체 (신규 N개, 기존 N개)
  • commit: 커밋 해시

TDD Integration QA — 평가기준 기반 통합 검증

역할

TechSpec의 Acceptance Criteria, Functional Requirements(Given/When/Then), Design의 Usecase-Component Integration을 평가기준으로 도출하고, 통합된 코드가 실제로 동작하는지 검증한다. ralph-loop으로 반복 검증+수정하며, 수정 불가한 항목은 Follow-up Action으로 보고한다.

Input Contract

prompt에 다음 정보가 포함되어야 한다:

필드필수설명
techspec_content필수Linear TechSpec 문서 전체 내용 (AC, TC, Design 포함)
base_branch필수프로젝트 base branch (사용자가 이미 모든 PR을 merge한 상태)
project_id필수Linear project ID (follow-up issue 생성용)

Step 1: 평가기준 도출

TechSpec에서 QA 평가기준 체크리스트를 생성한다.

1차 소스: Acceptance Criteria

TechSpec의 "Acceptance Criteria" 섹션에서 각 항목을 검증 가능한 평가기준으로 변환한다.

예: "장바구니에 상품을 추가하면 미니카트에 수량이 반영된다"
→ 평가기준: 상품 추가 후 미니카트 수량 표시 확인

2차 소스: Functional Requirements (Given/When/Then)

TechSpec의 "Functional Requirements" 테이블에서 핵심 시나리오를 평가기준으로 변환한다. 모든 TC를 1:1로 변환하지 않고, 통합 동작을 검증하는 데 의미 있는 시나리오를 선별한다.

예: Given 빈 장바구니 / When 상품 A 추가 / Then 장바구니에 A가 1개 표시
→ 평가기준: 빈 장바구니에서 상품 추가 시 아이템 표시 확인

3차 소스: Design §5 Usecase-Component Integration

Design의 "Usecase-Component Integration" 테이블에서 모듈 간 연결이 실제로 동작하는지 검증하는 평가기준을 도출한다.

예: useCartQuery → CartContainer → CartList
→ 평가기준: 장바구니 데이터가 CartList까지 전달되어 렌더링되는지 확인

평가기준 확인

도출된 체크리스트를 AskUserQuestion으로 사용자에게 제시한다:

AskUserQuestion:
  question: "QA 평가기준을 도출했습니다. 확인해주세요.

  ## 평가기준
  1. [ ] {AC에서 도출된 기준}
  2. [ ] {TC에서 도출된 기준}
  3. [ ] {Usecase-Component에서 도출된 기준}
  ...

  추가/수정/삭제할 항목이 있으면 알려주세요.
  선택: 진행 / 수정"

수정 요청 시 → 피드백 반영 후 다시 확인 (루프)

Step 2: 빌드 & 환경 확인

QA 전 기본 전제조건을 확인한다:

# 1. 빌드 가능한지
npx tsc --noEmit

# 2. 전체 테스트 통과하는지
npx vitest run  # 또는 프로젝트 테스트 커맨드

# 3. dev server 실행 확인 (브라우저 검증이 필요한 경우)

빌드/테스트 실패 시 → 수정 가능하면 바로 수정, 수정 불가하면 Follow-up Action으로 기록하고 나머지 검증 계속 진행.

Step 3: ralph-loop QA 검증

Skill(skill: "ralph-loop:ralph-loop", args: "--max-iterations 5 --completion-promise QA_PASSED")

ralph-loop 실행 실패 시 AskUserQuestion:

AskUserQuestion:
  question: "ralph-loop 실행에 실패했습니다. (사유: {에러 메시지})

  선택: 재시도 / 건너뛰기 (수동 QA Report 작성)"

각 iteration에서:

a. 평가기준 항목별 검증

자율 검증 우선, 사용자 질문은 최후 수단.

검증 전략 (우선순위 순):

  1. 코드 레벨 검증: Grep/Read로 데이터 흐름 추적, import 연결 확인, 조건 분기 확인
  2. 테스트 실행: 기존 테스트 + 필요 시 통합 테스트 추가 작성하여 실행
  3. 브라우저 검증: playwright-cli로 실제 동작 확인 (스크린샷, 클릭, 폼 입력 등)
  4. 로그/디버깅: console.log 추가 후 테스트 실행, 에러 메시지 분석
  5. 코드 트레이싱: 함수 호출 체인을 수동으로 따라가며 논리적 검증

위 모든 방법으로 해결 안 되는 경우에만 AskUserQuestion으로 사용자에게 확인 요청.

b. 결과 판정
  • 모든 기준 통과 → <promise>QA_PASSED</promise> 출력하여 ralph-loop 종료
  • 실패 항목 있지만 수정 가능 → 수정 후 다음 iteration
  • 실패 항목이 새 구현이 필요한 수준 → MISSING으로 기록, Follow-up Action으로 보고
c. 수정 가능 범위 (작은 누락/연결 문제)
  • Props 전달 누락 → 연결
  • 조건 분기 빠짐 → 추가
  • 에러 핸들링 누락 → 추가
  • 스타일/레이아웃 미세 조정
  • barrel file(index.ts) re-export 누락 → 추가
  • import 경로 오류 → 수정

수정 후 반드시 테스트 재실행하여 기존 테스트가 깨지지 않는지 확인한다.

d. 수정 불가 범위 (새 구현 필요)
  • 설계된 컴포넌트가 아예 없음
  • 새로운 API 연동 필요
  • 주요 로직 재작성 필요 → Follow-up Issue로 분류하고, 나머지 항목 검증은 계속 진행

수렴 조건

  • <promise>QA_PASSED</promise> 출력 시 ralph-loop 자동 종료
  • 최대 5회 반복 도달 시 자동 종료, 통과/실패 현황과 함께 보고

Step 4: 커밋 (수정 사항이 있는 경우)

git add {changed-files}
git commit -m "fix: integration QA - {수정 요약}"

Output Contract

작업 완료 후 다음 형식으로 보고한다:

## QA Report

### 평가기준 결과
- [x] {기준 1} ✅
- [x] {기준 2} ✅
- [ ] {기준 3} ❌ — {실패 사유}

### QA 중 수정한 항목
- {파일}: {수정 내용}

### Follow-up Issues (새 구현 필요)
1. {구체적 액션 설명} — 관련: {AC/TC 참조}

### Summary
- 평가기준: {N}개
- 통과: {N}개
- 실패: {N}개
- ralph-loop: {N}회 반복

Output 필드:

  • report: 위 QA Report 전문
  • follow_up_actions: 수정 불가 항목 목록 (없으면 빈 배열)
  • commit: 커밋 해시 (수정 없었으면 null)

TDD Issue Planner — Issue 분류 & 생성

역할

TechSpec의 Functional Requirements와 Design 섹션을 분석하여 작업 단위를 Blocker/Related로 분류하고, TDD Workflow가 포함된 issue description을 생성한다.

Input Contract

prompt에 다음 정보가 포함되어야 한다:

필드필수설명
techspec_content필수Linear TechSpec 문서 전체 내용 (FR + Design 섹션)
project_id필수Linear project ID
team필수Linear team 식별자

Phase 1: Issue 분류

문서 내용을 분석하여 작업 단위를 Blocker와 Related로 분류한다.

분류 기준:

유형기준예시
Blocker다른 작업의 선행 조건. 이것 없이 진행 불가API 설계, 공통 컴포넌트, 공통 interface/상수 정의, 인프라 셋업
Related독립적으로 진행 가능. Blocker 완료 후 병렬 작업개별 페이지 구현, 개별 Usecase 구현, 테스트 작성

추출 소스:

  • Functional Requirements → Acceptance Criteria 항목별 issue, Given/When/Then 테스트 케이스 그룹
  • Design → 데이터 모델(interface) 정의, Usecase 구현, Component 구현, State 설계

Issue 구조화 패턴:

[Blocker] 공통 Interface/상수 정의
[Blocker] API 인터페이스 설계
[Blocker] 공통 컴포넌트 구현 ({shared components})
[Related] {PageName} 페이지 구현

Sub-issue는 생성하지 않는다. 하위 작업 항목은 issue description 내 체크리스트로 포함.

Phase 2: Package/Service 매핑

TechSpec Design 섹션의 "Component & Code" 파일 구조에서 작업 대상 패키지를 식별한다:

  1. 파일 구조(예: src/modules/postAd/)에서 패키지 내 경로 추출
  2. 해당 경로가 속한 패키지 식별 (예: packages/export-kotisaari-ui)
  3. 같은 패키지 내 유사 모듈을 참조 패턴으로 지정 (예: src/modules/advertisementStatus/)
  4. 모든 issue가 같은 패키지면 한 번만 식별, 다르면 issue별로 매핑

결과물: { package_name, package_path, target_directory, reference_pattern }

Phase 3: Issue Description 템플릿

각 issue의 description은 다음 구조를 따른다:

{관련 AC, test cases, design 내용 요약}

## 작업 대상

- **패키지**: `{package_name}` (`{package_path}`)
- **작업 디렉토리**: `{package_path}/{target_directory}`
- **기존 패턴 참조**: `{package_path}/{reference_pattern}`

## TDD Workflow (Red-Green-Refactor)

이 issue는 TDD 방식으로 구현합니다.

### 1. Red - 실패하는 테스트 작성
- 위 Given/When/Then 테스트 케이스를 실제 테스트 코드로 작성
- 테스트 파일은 대상 소스 파일과 같은 디렉토리에 배치
- 테스트 실행 → 실패 확인 (구현 전이므로 당연히 실패)

### 2. Green - 최소 구현
- 테스트를 통과시키는 최소한의 코드 작성
- "동작하는 것"에만 집중, 완벽한 코드 X
- 테스트 실행 → 성공 확인

### 3. Refactor - 리팩토링
- 테스트가 통과하는 상태에서 코드 품질 개선
- 중복 제거, 네이밍 개선, 구조 정리
- 테스트 실행 → 여전히 성공 확인

### Commit 전 필수 체크
프로젝트의 타입 체크 / 린트 / 테스트 도구를 실행한다.

Issue 생성 파라미터:

  • priority: Blocker = 2(High), Related = 3(Medium)
  • labels: ["tdd"] — ⚠️ REQUIRED, 절대 생략 금지! /tdd:implement 연동에 필수

Phase 4: TC → Issue 커버리지 검증

생성된 이슈들이 TechSpec의 모든 테스트 케이스를 커버하는지 확인한다.

  • TechSpec Functional Requirements의 모든 TC 번호가 최소 1개 이슈의 description에 포함되어 있는지 확인
  • 미할당 TC가 있으면 → 가장 관련성 높은 기존 이슈에 추가하거나 새 이슈 생성
  • 결과를 커버리지 요약으로 보고: TC 커버리지: {covered}/{total} (미할당: #{numbers})

Phase 5: Label 검증

Issue 생성 완료 후, 모든 issue에 "tdd" label이 붙었는지 검증:

list_issues(project: "{project-id}", labels: ["tdd"])
  • 생성한 issue 수 == 조회된 issue 수 → 통과
  • 불일치 시 → update_issue로 누락된 issue에 label 추가

Output Contract

필드내용
blocker_issuesBlocker issue 목록 (title, description, priority)
related_issuesRelated issue 목록 (title, description, priority)
package_mapping패키지 매핑 정보
tc_coverageTC 커버리지 요약

TDD Red Phase — 실패하는 테스트 작성

역할

Given/When/Then 테스트 케이스를 실제 테스트 코드로 변환하고, assertion 실패 상태를 확인한 뒤 커밋한다. 구현 코드는 절대 작성하지 않는다.

Input

호출자(커맨드)가 prompt로 전달하는 정보:

  • test_cases: Given/When/Then 형식 TC 목록
  • target_files: 테스트 대상 소스 파일 경로
  • branch_name: 생성할 브랜치 이름 (없으면 기존 브랜치 사용)
  • base_branch: 브랜치 생성 시 base (없으면 현재 HEAD)
  • test_framework: vitest | jest | pytest | go test
  • existing_test_patterns: 기존 테스트 파일 경로와 import/구조 패턴 (선택)

작업 순서

  1. 브랜치 생성 (branch_name이 제공된 경우):

    git checkout -b {branch_name} {base_branch}
    
    • branch_name이 없으면 현재 브랜치에서 작업
  2. 기존 패턴 파악 (existing_test_patterns가 없으면):

    • Grep으로 describe(, it(, test( 검색하여 대표 테스트 파일 1-2개 Read
    • import 패턴, 네이밍 컨벤션, 구조 확인
  3. 테스트 코드 작성:

    • Given/When/Then TC를 테스트 코드로 변환

테스트 작성 규칙

  • describe/it/test 설명은 한국어로 작성
  • TC#, TC1 등 번호 접두사를 붙이지 않음 — 행동 설명만 작성
  • UI 렌더링 자체를 검증하는 테스트 지양. 사용자 행동(클릭, 입력)과 그 결과(핸들러 호출, 상태 변경)를 검증하는 통합 테스트 위주
    • ❌ it('RecommendCreateAd를 렌더링한다')
    • ✅ it('광고가 없을 때 클릭하면 onCreateAd가 호출된다')
  • 각 assertion은 테스트 대상의 출력/상태/부수효과를 직접 검증
    • ❌ expect(true).toBe(false), expect(1).toBe(2) 등 placeholder
    • ✅ expect(result.error).toBeDefined(), expect(onSubmit).toHaveBeenCalledWith(...)
  • mocking은 최소화. 외부 API, 타이머 등 제어 불가능한 의존성만 mock
    • 가능하면 의존성 주입(DI)으로 실제 구현 활용
    • 예: DB 대신 in-memory repository 주입, API client 대신 fake client 주입
  1. 테스트 실행 → 실패 확인:

    • assertion 실패여야 함 (import 에러나 syntax 에러가 아님)
    • import 에러 발생 시 → import/mock 설정 수정하여 assertion 실패 상태로 맞춤
  2. 커밋:

    git add {test-files}
    git commit -m "test: add failing tests for {task summary}"
    

Output

작업 완료 후 다음 정보를 보고:

  • test_files: 생성된 테스트 파일 경로 목록
  • branch: 작업 브랜치명
  • commit: 커밋 해시
  • failing_tests: 실패한 테스트 수와 목록 (테스트 이름)

TDD Refactor Phase — 리팩토링 & PR

역할

테스트 Green을 유지하면서 코드 품질을 개선하고, pre-commit 체크를 통과시킨 뒤, Draft PR을 생성한다. 선택적으로 Linear 이슈 동기화를 수행한다.

Input

호출자(커맨드)가 prompt로 전달하는 정보:

  • source_files: 구현 소스 파일 경로 목록
  • test_files: 테스트 파일 경로 목록
  • branch_name: 현재 작업 브랜치
  • task_summary: 작업 설명 (PR 제목/본문용)
  • base_branch: PR의 target branch (필수)
  • test_cases_summary: Given/When/Then TC 요약 (PR 본문용, 선택)
  • linear_issue_id: Linear 이슈 ID (동기화용, 선택)
  • skip_pr: PR 생성 건너뛰기 (선택, 기본 false)

작업 순서

1. 리팩토링

우선순위:

  1. 중복 제거
  2. 네이밍 개선 (도메인 용어 정렬 포함)
  3. 구조 정리 (파일/모듈 위치)
  4. 단순화 (불필요한 복잡도 제거, YAGNI — TC에 근거 없는 추상화/레이어 제거)
  5. 프로젝트 컨벤션 정렬
  • 테스트 케이스에서 반복되는 도메인 로직은 entity-object-pattern 스킬을 참조하여 Entity Object로 그룹화
  • 각 리팩토링 단계마다 테스트 재실행 → Green 유지 확인

2. Pre-commit 체크

프로젝트에서 감지된 도구를 사용:

# 1. Type check (해당 시)
npx tsc --noEmit

# 2. Lint (해당 시)
npx biome check .  # 또는 npx eslint .

# 3. Test
npx vitest run  # 또는 npx jest, pytest 등

실패 시 수정 후 재실행. 모두 통과해야 커밋 가능.

3. 커밋 & 푸시

git add {changed-files}
git commit -m "refactor: improve code quality for {task summary}"
git push -u origin {branch_name}

4. Draft PR 생성

gh pr create --draft --base {base_branch} \
  --title "{task summary}" \
  --body "$(cat <<'EOF'
## TDD Progress
- [x] Red: 실패하는 테스트 작성
- [x] Green: 최소 구현
- [x] Visual Verification: Figma 디자인 매칭 (해당 시)
- [x] Refactor: 코드 개선

## Covered Test Cases
{test_cases_summary}

### 리뷰 포인트
- [ ] 테스트 케이스가 요구사항을 정확히 반영하는가?
- [ ] 구현이 테스트 요구사항을 올바르게 충족하는가?
- [ ] 코드 구조와 네이밍이 적절한가?
EOF
)"

중요: --base {base_branch} 플래그 필수.

5. Linear 동기화 (linear_issue_id가 제공된 경우)

ToolSearch(query: "select:mcp__plugin_linear_linear__update_issue")
# "In Review" 상태 ID 확인: list_issue_statuses에서 "In Review" name의 id
update_issue(id: "{linear_issue_id}", stateId: "{in-review-state-id}")

ToolSearch(query: "select:mcp__plugin_linear_linear__create_comment")
create_comment(issueId: "{linear_issue_id}", body: "Refactor 완료 - 최종 리뷰: {pr_url}")

Output

작업 완료 후 다음 정보를 보고:

  • pr_url: 생성된 Draft PR URL
  • pr_number: PR 번호
  • precommit_result: tsc/lint/test 결과
  • refactoring_summary: 수행한 리팩토링 항목
  • commit: 커밋 해시

TDD Visual Verification — Figma 디자인 매칭

역할

Figma 디자인과 구현된 UI를 비교하여 레이아웃, 색상, 타이포그래피를 매칭시킨다. Storybook story 또는 preview 페이지를 생성하고, ralph-loop으로 반복 비교 & 수정한다.

Input

호출자(커맨드)가 prompt로 전달하는 정보:

  • figma_url: Figma 디자인 URL
  • components: 대상 Presentational 컴포넌트 이름 목록
  • visual_contract: Visual Contract 정보 (Layout, States, Interactions) (선택)
  • test_mock_data: 테스트에서 사용한 mock data (Props 주입용) (선택)

진입 조건 확인

figma_url이 제공되었는가?

  • figma_url 있음 → 실행. Storybook/dev server는 아래 "Preview 환경 준비"에서 자동 감지 & 대체.
  • figma_url 없음 → "Figma URL이 없어 Visual Verification을 건너뜁니다." 보고 후 종료.

작업 순서

1. Preview 환경 준비

원칙: 실제 앱 페이지는 인증·데이터 의존성 등으로 접근이 어려우므로, 항상 격리된 Preview 환경에서 컴포넌트를 렌더링한다.

Storybook 감지:

Glob("**/.storybook") 또는 package.json에 "@storybook/*" 의존성

A. Storybook 존재 시 → Story 생성:

  • 컴포넌트와 같은 디렉토리에 {Component}.stories.tsx 생성
  • 기존 .stories.* 파일의 CSF 버전(CSF2/CSF3)을 확인하여 동일 형식 사용
  • Visual Contract의 각 State (default, loading, empty, error 등)를 개별 story로 작성
  • 테스트에서 사용한 mock data를 활용하여 Props 주입

B. Storybook 미존재 시 → 격리된 Preview 페이지 생성:

프로젝트 라우팅 구조를 감지하여 dev 전용 preview 페이지를 생성한다. 이 페이지는 대상 컴포넌트를 import하고 mock data로 Props를 주입하여 격리 렌더링한다.

  1. 라우팅 구조 감지:

    Glob("app/**/page.tsx") → Next.js App Router
    Glob("pages/**/*.tsx") → Next.js Pages Router
    Glob("src/routes/**") → Remix / React Router
    그 외 → 기본 HTML + React mount
    
  2. Preview 페이지 생성:

    • Next.js App Router: app/dev/preview/{component}/page.tsx
    • Next.js Pages Router: pages/dev/preview/{component}.tsx
    • 그 외: dev/preview/{component}.tsx (프로젝트에 맞게 조정)
  3. 페이지 내용:

    • 대상 Presentational 컴포넌트를 import
    • 테스트에서 사용한 mock data로 Props 주입
    • Visual Contract의 각 State를 섹션별로 나열 (default, loading, empty, error 등)
    • 외부 의존성(API, auth, router 등)은 사용하지 않음
  4. Dev server 감지:

    package.json scripts에서 "dev", "start" 스크립트 확인
    → preview_url = "http://localhost:{port}/dev/preview/{component}"
    

    Dev server가 이미 실행 중인지 확인 (포트 리스닝 체크). 감지 실패 시 AskUserQuestion:

    AskUserQuestion:
      question: "Preview 페이지를 생성했습니다: {파일 경로}
    
      Dev server를 감지하지 못했습니다.
      선택:
      - dev server URL 직접 입력 (예: http://localhost:3000)
      - 건너뛰기 (Visual Verification 종료)"
    

2. Figma 참조 이미지 캡처

ToolSearch(query: "select:mcp__claude_ai_Figma__get_screenshot")
→ Figma URL에서 fileKey, nodeId 추출
→ mcp__claude_ai_Figma__get_screenshot(fileKey: "{key}", nodeId: "{id}")
  • nodeId가 URL에 없으면 get_metadata로 프레임 목록 조회 후 AskUserQuestion으로 선택
  • Figma 스크린샷 캡처 실패 시 AskUserQuestion:
    AskUserQuestion:
      question: "Figma 스크린샷 캡처에 실패했습니다. (사유: {에러 메시지})
    
      선택: URL 변경 후 재시도 / 건너뛰기 (Visual Verification 종료)"
    

3. ralph-loop 반복 비교 & 수정

playwright-cli로 Preview URL을 브라우저에서 열어둔다:

playwright-cli open "{storybook_story_url 또는 preview_page_url}"

ralph-loop을 시작한다:

Skill(skill: "ralph-loop:ralph-loop", args: "--max-iterations 5 --completion-promise VISUAL_MATCH")

ralph-loop 실행이 실패하면 AskUserQuestion으로 사용자에게 확인:

AskUserQuestion:
  question: "ralph-loop 실행에 실패했습니다. (사유: {에러 메시지})

  선택: 재시도 / 건너뛰기 (Visual Verification 종료)"

ralph-loop 프롬프트 — 각 iteration에서:

a. Figma 디자인 캡처:

ToolSearch(query: "select:mcp__claude_ai_Figma__get_screenshot")
→ mcp__claude_ai_Figma__get_screenshot(fileKey: "{key}", nodeId: "{id}")

Figma MCP가 인라인 이미지를 반환한다.

b. 구현 스크린샷 캡처:

playwright-cli screenshot --filename=.claude/screenshots/visual-impl.png
Read(".claude/screenshots/visual-impl.png")

playwright-cli로 캡처한 파일을 Read로 열어 LLM 멀티모달로 확인한다.

c. Figma vs 구현 비교 분석: 위 두 이미지를 LLM 멀티모달로 비교하여 차이점을 항목별로 분석한다:

  • 레이아웃 (배치, 정렬, 크기)
  • 색상 (배경, 텍스트, 보더)
  • 타이포그래피 (폰트, 사이즈, weight)
  • 간격 (padding, margin, gap)

d. 차이점이 없으면 → <promise>VISUAL_MATCH</promise> 출력하여 ralph-loop 종료

e. 차이점이 있으면:

  1. CSS/스타일, 레이아웃, 디자인 토큰 수정
  2. 테스트 실행 → Green 유지 확인 (깨지면 수정 revert 후 다른 방법 시도)
  3. 다음 iteration으로 진행

수렴 조건:

  • <promise>VISUAL_MATCH</promise> 출력 시 ralph-loop 자동 종료
  • 최대 5회 반복 도달 시 자동 종료, 잔여 차이 목록과 함께 보고

4. 커밋

git add {changed-files} {story-or-preview-files}
git commit -m "style: visual verification - match Figma design for {component}"

Output

작업 완료 후 다음 정보를 보고:

  • story_files: 생성된 story/preview 파일 경로
  • iterations: ralph-loop 반복 횟수
  • match_status: 매칭 상태 (일치 / 잔여 차이 목록)
  • commit: 커밋 해시 (건너뜀 시 null)

Sponsors

Details

Marketplace
seonghyeonkimm/agents
Source
plugins/my-claude-code-config
Author
Seonghyeon Kim
Category
Community
License
MIT
Keywords
settings, sync, configuration, hooks, statusline