design-first

# Design First

구현 전 점진적 설계 합의. 한 번에 한 차원만 논의하고, 승인 후 다음 Phase로 진행.

> "The purpose of software design is to manage complexity" — John Ousterhout

핵심 철학:
- **Whiteboard before Keyboard**: 코드 생성 전 설계 합의
- **한 번에 한 차원만**: 범위·아키텍처·통신·계약을 동시에 평가하지 않음
- **게이트 리뷰**: 각 Phase 사용자 승인 후 다음 진행
- **견적 기반 캘리브레이션**: Phase 0 견적 결과에 따라 시작점과 깊이가 달라진다

## Instructions

### 복원 (Compaction / 세션 재개 시)

`.claude/designs/{feature}/` 디렉토리를 확인한다:
1. `phase-N-*.md` 파일이 존재하면 해당 Phase까지 완료로 판단
2. 마지막 완료 Phase의 파일을 Read하여 합의 내용 복원
3. 다음 Phase부터 재개 (A. 탐색부터)

---

### Phase 0: 견적 (Estimate)

현행 파악 → Gap 분석 → 규모 산정 → 라우팅. "견적내자"의 실체.

#### 0-A. 메타-견적 (Triage)

견적 자체의 비용을 먼저 판단한다:

| 항목 | 질문 |
|------|------|
| 조사 범위 | 코드베이스 전체? 특정 디렉토리/모듈? |
| 조사 깊이 | 파일 목록만? 라인별 영향도까지? |
| 예상 소요 | Agent 1개 5분? 3개 병렬 15분? |

간단한 요청(단일 파일, 유틸 함수)은 메타-견적 자체를 스킵하고 0-D 라우팅으로 직행.

#### 0-B. 현행 탐색 (As-Is)

Explore subagent로 현재 상태를 수치화한다:

- 대상 파일/모듈 목록 (Glob)
- 현재 수치 (커버리지, 라인 수, 버전, 의존성 수 등)
- 관련 기존 패턴/컨벤션 (Grep)

출력 형식:
```
### 현행 상태
- 대상: {디렉토리/모듈} ({파일 N개}, {라인 N줄})
- 현재 수치: {측정 가능한 값}
- 관련 패턴: {기존 컨벤션/구현 참조}
```

#### 0-C. Gap 분석 + 규모 산정

As-Is와 목표를 대조하여 변경 항목을 열거한다:

- 변경 필요 항목 나열
- 각 항목에 규모 태그: **S** (< 30줄), **M** (30-150줄), **L** (150줄+)
- 리스크 식별: 까다로운 부분, 외부 의존성, 블로커
- 순서 제안: 의존 관계 기반

`.claude/designs/{feature}/phase-0-estimate.md`에 저장한다.

출력 형식:
```markdown
## 견적

### 목표
{목표 상태 한 줄}

### 작업 항목
| # | 항목 | 규모 | 리스크 | 비고 |
|---|------|------|--------|------|
| 1 | ... | S | - | |
| 2 | ... | M | 외부 API 의존 | 블로커 가능 |
| 3 | ... | L | 기존 테스트 깨질 수 있음 | |

### 전체 규모
- 항목 수: N개 (S: x, M: y, L: z)
- 예상 PR: N개
- 주요 리스크: ...
```

#### 0-D. 라우팅 (게이트 리뷰)

견적 결과에 따라 다음 단계를 제안한다:

| 견적 결과 | 라우팅 | 예시 |
|-----------|--------|------|
| S 항목만, 리스크 없음 | **스킵** — 바로 실행 | `formatDate()` 추가 |
| M 이하, 범위 명확 | **Phase 2** 또는 **Phase 3**부터 | 단일 컴포넌트 변경 |
| L 포함 또는 다중 컴포넌트 | **Phase 1** (Capabilities)부터 | 새 기능 도메인 |
| 리스크 높음 / 외부 의존 | **Phase 1**부터 (Phase 3에서 심화) | 시스템 통합 |

AskUserQuestion으로 라우팅을 제안한다:

```
## 견적 결과
{작업 항목 테이블 요약}

전체 규모: S x개, M y개, L z개
→ [라우팅 판단 근거]에 따라 Phase N ([이름])부터 시작을 제안합니다.

1. 동의 (Recommended)
2. Phase N부터 시작 (더 상세히/간단히)
3. 설계 스킵, 바로 실행
4. 견적만 저장, 여기서 종료
```

**견적만 저장 시**: `phase-0-estimate.md`를 저장하고 skill을 종료한다. 나중에 `/design-first`를 다시 호출하면 복원 로직이 Phase 0 완료를 인식하고 Phase 1부터 재개한다.

단일 컴포넌트인 경우, 내부 구조 변경(Phase 2)인지 외부 연결 추가(Phase 3)인지를 추가로 확인한다.

---

### Phase 1: Capabilities (범위 정의)

**목적**: 시스템이 **무엇을** 하는지 합의한다. **어떻게**는 아직 논의하지 않는다.

#### 1-A. 탐색 (Explore subagent)

Phase 0-B 탐색 결과가 있으면 재활용한다. 추가로 필요한 부분만 Explore subagent로 탐색:

- 관련 기존 기능 탐색 (Grep: 관련 키워드)
- 유사 기능 구현 패턴 (Glob: 디렉토리 구조)
- 비기능 요구사항 단서 (설정 파일, 인프라 코드)

프롬프트 입력: 설계 주제 + 프로젝트 경로 + Phase 0 견적 요약
출력 형식:
```
### 기존 관련 기능
- {기능}: {위치} - {설명}
### 패턴
- {패턴명}: {예시 파일}
### 비기능 단서
- {항목}: {근거}
```

#### 1-B. 합의 (Main context)

탐색 결과를 기반으로 Capabilities 산출물을 정리한다:

- 핵심 기능 목록 정의 (동사 중심: "~한다")
- v1 범위 확정: 포함 / 제외 / 미정(defer) 분류
- 성공 기준 정의 (측정 가능한 형태)
- 비기능 요구사항 식별 (성능, 보안, 확장성)

`.claude/designs/{feature}/phase-1-capabilities.md`에 저장한다.

출력 형식:
```markdown
## Capabilities

### 포함 (v1)
- [ ] 기능 A: ...
- [ ] 기능 B: ...

### 제외 (명시적)
- 기능 C: 이유 ...

### 성공 기준
- 기준 1: ...
```

#### 1-C. 게이트 리뷰

Red Flags:
- "모든 것을 다 한다" — 범위가 없는 것과 같다
- 기능 목록이 10개 초과 — v1 범위 축소 필요
- "어떻게" 논의가 끼어듦 — Phase 2로 미룬다

사용자에게 Capabilities 요약을 보여주고 승인을 받는다. 승인 후 Phase 2로 진행.

---

### Phase 2: Components (구성요소)

**목적**: Phase 1의 기능을 구현할 **부품**을 식별한다.

#### 2-A. 탐색 (Explore subagent)

Explore subagent를 스폰하여 아래를 탐색한다:

- 재사용 가능한 기존 모듈/클래스/서비스 (Grep, Glob)
- 기존 디렉토리 구조와 네이밍 컨벤션 (Glob)
- 유사 기능의 컴포넌트 구성 패턴 (Read 샘플)

프롬프트 입력: 설계 주제 + Phase 1 합의 요약
출력 형식:
```
### 재사용 후보
- {모듈}: {위치} - {책임} - {재사용 가능 범위}
### 디렉토리 컨벤션
- {패턴}: {예시}
### 참고 구현
- {파일}: {관련 패턴 설명}
```

#### 2-B. 합의 (Main context)

탐색 결과를 기반으로 Components 산출물을 정리한다:

- 필요한 모듈/클래스/서비스 식별
- 각 컴포넌트의 단일 책임 정의
- 불필요한 추상화 거부 (YAGNI)

`.claude/designs/{feature}/phase-2-components.md`에 저장한다.

출력 형식:
```markdown
## Components

| 컴포넌트 | 책임 | 신규/기존 | 위치 |
|----------|------|-----------|------|
| A | ... | 신규 | src/... |
| B | ... | 기존 재사용 | src/... |
```

#### 2-C. 게이트 리뷰

Red Flags:
- 하나의 컴포넌트가 3개 이상의 책임 — 분리 필요
- 기존 코드와 중복되는 신규 컴포넌트 — 재사용 검토
- "혹시 나중에 필요할" 컴포넌트 — YAGNI 위반

사용자에게 Components 요약을 보여주고 승인을 받는다. 승인 후 Phase 3로 진행.

---

### Phase 3: Interactions (상호작용)

**목적**: 컴포넌트 간 **데이터 흐름과 통신 방식**을 정의한다.

#### 3-A. 탐색 (Explore subagent)

Explore subagent를 스폰하여 아래를 탐색한다:

- 기존 호출 흐름 패턴 (Grep: import/함수 호출 추적)
- 에러 전파 패턴 (Grep: try/catch, throw, Error 클래스)
- 동기/비동기 패턴 (Grep: async/await, callback, Promise)
- 의존성 방향 (import 그래프)

프롬프트 입력: 설계 주제 + Phase 2 합의 요약 (컴포넌트 목록)
출력 형식:
```
### 호출 흐름
- {시나리오}: {흐름 설명}
### 에러 패턴
- {패턴}: {예시 파일}
### 동기/비동기
- {영역}: {방식} - {근거}
```

#### 3-B. 합의 (Main context)

탐색 결과를 기반으로 Interactions 산출물을 정리한다:

- 주요 시나리오별 호출 흐름 (happy path)
- 에러 전파 경로 (failure path)
- 데이터 흐름 방향 (단방향/양방향)
- 동기/비동기 결정
- 의존성 방향 확인 (순환 의존 방지)

`.claude/designs/{feature}/phase-3-interactions.md`에 저장한다.

출력 형식:
```markdown
## Interactions

### 시나리오 1: [이름]
A → B: 요청 (데이터)
B → C: 위임 (변환된 데이터)
C → B: 결과
B → A: 응답

### 에러 경로
C 실패 → B: fallback 처리 → A: 에러 응답
```

#### 3-C. 게이트 리뷰

Red Flags:
- 순환 의존 (A→B→C→A) — 구조 재설계 필요
- 하나의 컴포넌트가 5개 이상과 직접 통신 — 중재자 패턴 검토
- 에러 경로 미정의 — 실패 시나리오 필수

사용자에게 Interactions 요약을 보여주고 승인을 받는다. 승인 후 Phase 4로 진행.

---

### Phase 4: Contracts (계약)

**목적**: 구현에 필요한 **인터페이스와 타입**을 확정한다.

#### 4-A. 탐색 (Explore subagent)

Explore subagent를 스폰하여 아래를 탐색한다:

- 기존 인터페이스/타입 패턴 (Grep: interface, type, class)
- 동일 이름 충돌 확인 (Grep: 타입명/함수명)
- 기존 테스트 패턴 (Glob: *test*, *spec*)
- 에러 타입 컨벤션 (Grep: Error, Exception 패턴)

프롬프트 입력: 설계 주제 + Phase 2-3 합의 요약
출력 형식:
```
### 기존 타입/인터페이스
- {타입}: {위치} - {용도}
### 이름 충돌
- {이름}: {충돌 위치} (있으면)
### 테스트 패턴
- {패턴}: {예시 파일}
### 에러 컨벤션
- {패턴}: {예시}
```

#### 4-B. 합의 (Main context)

탐색 결과를 기반으로 Contracts 산출물을 정리한다:

- 함수 시그니처 / 메서드 정의
- 입출력 타입 / 스키마
- 에러 타입 정의
- TDD 시작점 수준의 테스트 케이스 목록

`.claude/designs/{feature}/phase-4-contracts.md`에 저장한다.

출력 형식:
```markdown
## Contracts

### ComponentA
- `doSomething(input: InputType): OutputType`
- `handleError(err: ErrorType): Recovery`

### 타입 정의
- `InputType`: { field1: string, field2: number }
- `OutputType`: { result: boolean, data?: string[] }

### 테스트 케이스
- [ ] 정상 입력 → 기대 출력
- [ ] 빈 입력 → 에러 반환
- [ ] 경계값 → 올바른 처리
```

#### 4-C. 게이트 리뷰

Red Flags:
- `any` 타입 남용 — 구체적 타입 필요
- 에러 타입 미정의 — 호출자가 에러를 처리할 수 없음
- 테스트 케이스 0개 — 계약이 검증 불가

사용자에게 Contracts 요약을 보여주고 승인을 받는다. 승인 후 Phase 5로 진행.

---

### Phase 5: Implementation (구현 전환)

**목적**: Phase 1-4 합의를 요약하고 구현으로 전환한다.

수행 항목:
1. **설계 합의 요약**: Phase 0-4에서 확정된 내용을 한 곳에 정리 (견적 포함)
2. **구현 전환 선택**: AskUserQuestion으로 다음 단계를 결정

```
설계 합의가 완료되었습니다. 다음 단계를 선택하세요:
1. plan-review로 검증 후 구현 (Recommended)
2. 바로 구현 시작
3. 설계 문서로 저장 (.claude/designs/)
```

**plan-review 연동 시**: 설계 합의 요약을 계획으로 변환하여 `/plan-review`에 전달.
**바로 구현 시**: 설계 합의 요약을 TaskCreate로 태스크화하고 순차 실행한다.
**설계 문서 저장 시**: `.claude/designs/{feature-name}.md`에 Phase 1-4 합의 내용을 저장한다.

Red Flags:
- 설계 합의 없이 바로 구현 선택 — Phase 1-4를 거친 이유가 없어짐
- 설계 문서만 저장하고 구현 미진행 — 합의의 유효기간이 지나면 재검토 필요

---

## 중요 원칙

1. **한 Phase씩만**: 현재 Phase가 승인되지 않으면 다음으로 넘어가지 않는다
2. **되돌아갈 수 있다**: 하위 Phase에서 상위 Phase의 결정을 수정해야 한다면, 사유를 설명하고 해당 Phase로 되돌아가 재승인 후 다시 진행한다
3. **코드베이스 기반**: 기존 코드를 확인(Grep, Glob, Read)한 뒤 설계한다. 추측하지 않는다
4. **과설계 방지**: 현재 필요한 최소한만 설계한다. "나중에 필요할 수도"는 제외한다
5. **설계 ≠ 문서**: 이 skill의 목적은 문서 생성이 아니라 **합의**다. 출력은 합의의 기록일 뿐이다

---

## Examples

### Example 1: 다중 컴포넌트 — 알림 시스템

```
User: /design-first 알림 시스템 설계
```

**Phase 0 (견적)**:
- 0-A: 조사 범위 = notification 관련 모듈 전체, 깊이 = 라인별 영향도, Agent 2개 병렬
- 0-B: 현행 — 알림 관련 코드 없음, UserPreference 모듈 존재 (재사용 가능)
- 0-C: Gap 5건 (S:1, M:2, L:2), 리스크: 이메일 외부 서비스 의존
- 0-D: L 포함 + 다중 컴포넌트 → Phase 1부터

**Phase 1 (Capabilities)**: 포함/제외/성공기준 합의 → **Phase 2 → 3 → 4 → 5**

### Example 2: 단일 컴포넌트 — 캐시 레이어 추가

```
User: /design-first API 응답 캐시 추가
```

**Phase 0 (견적)**:
- 0-A: 조사 범위 = API controller + middleware, 깊이 = 파일 목록, Agent 1개
- 0-B: 현행 — 캐시 레이어 없음, Redis 의존성 이미 존재
- 0-C: Gap 3건 (S:1, M:2), 리스크 없음
- 0-D: M 이하 + 외부 연결 → Phase 3부터

**Phase 3 (Interactions)** → **Phase 4 (Contracts)** → **Phase 5**

### Example 3: 견적만 산출

```
User: 커버리지 5% 올리고 싶은데 견적내자
```

**Phase 0 (견적)**:
- 0-A: 조사 범위 = 전체 모듈 커버리지, 깊이 = 파일별 커버리지 수치, Agent 1개
- 0-B: 현행 — 87.7%, 미커버 모듈: customer(72%), payment(68%), external(45%)
- 0-C: Gap 8건 (S:3, M:4, L:1), 리스크: external 모듈은 mock 필수
- 0-D: 사용자 선택 → "견적만 저장, 여기서 종료" → `phase-0-estimate.md` 저장

### Example 4: 단순 유틸 — 스킵

```
User: /design-first formatDate 유틸 함수
```

**Phase 0 (견적)**: 0-A에서 단일 파일/유틸로 판단 → 0-D 직행 → 스킵, 바로 실행

---

## 연동

```
design-first (설계 합의)  ← 현재 skill
  → plan-review (계획 검증)
    → 실행
      → reflect (사후 회고)
```

| Skill | 관계 | 설명 |
|-------|------|------|
| `plan-review` | 후행 | 설계 완료 후 실행 계획 검증에 사용 |
| `reflect` | 사후 | 구현 후 설계 대비 결과 회고 |