| disable-model-invocation | true |
| name | design-first |
| description | 견적 산정 + 점진적 설계 합의 (견적→범위→구조→상호작용→계약→구현). Use when 견적내자, 견적 내줘, estimate effort, scope is unclear for multi-component work, new feature domain with undefined boundaries, or system integration requiring architectural decisions. 견적, 설계 먼저, 구조 설계, 범위 정의. Do NOT use for single-component changes where scope is already clear, or when a plan already exists (use plan-review instead). |
| argument-hint | [design topic] |
| user-invocable | true |
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}/ 디렉토리를 확인한다:
phase-N-*.md 파일이 존재하면 해당 Phase까지 완료로 판단- 마지막 완료 Phase의 파일을 Read하여 합의 내용 복원
- 다음 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에 저장한다.
출력 형식:
## 견적
### 목표
{목표 상태 한 줄}
### 작업 항목
| # | 항목 | 규모 | 리스크 | 비고 |
|---|------|------|--------|------|
| 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에 저장한다.
출력 형식:
## 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에 저장한다.
출력 형식:
## 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에 저장한다.
출력 형식:
## 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에 저장한다.
출력 형식:
## 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 합의를 요약하고 구현으로 전환한다.
수행 항목:
- 설계 합의 요약: Phase 0-4에서 확정된 내용을 한 곳에 정리 (견적 포함)
- 구현 전환 선택: 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를 거친 이유가 없어짐
- 설계 문서만 저장하고 구현 미진행 — 합의의 유효기간이 지나면 재검토 필요
중요 원칙
- 한 Phase씩만: 현재 Phase가 승인되지 않으면 다음으로 넘어가지 않는다
- 되돌아갈 수 있다: 하위 Phase에서 상위 Phase의 결정을 수정해야 한다면, 사유를 설명하고 해당 Phase로 되돌아가 재승인 후 다시 진행한다
- 코드베이스 기반: 기존 코드를 확인(Grep, Glob, Read)한 뒤 설계한다. 추측하지 않는다
- 과설계 방지: 현재 필요한 최소한만 설계한다. "나중에 필요할 수도"는 제외한다
- 설계 ≠ 문서: 이 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 | 사후 | 구현 후 설계 대비 결과 회고 |
