design-first

name	design-first
description	새 기능, 큰 변경, 아키텍처 결정 전에 구현보다 설계를 먼저 확정할 때 사용한다.
disable-model-invocation	false

design-first

Hard Gate

설계 승인 없이 코드를 작성하지 않는다.

"간단한 건데", "금방이야", "설계할 것도 없어" — 전부 위험 신호다. 간단한 프로젝트일수록 검증되지 않은 가정이 가장 많은 낭비를 만든다.

설계는 짧아도 된다 (단순한 건 2-3문장). 하지만 반드시 사용자 승인을 받는다.

체크리스트

순서대로 수행한다:

1. 컨텍스트 파악 — 파일, 문서, 최근 커밋 확인
2. 영향도 분석 — 기존 코드 변경 시 blast radius 리스크 스코어 산정
3. 명확화 질문 — 한 번에 하나씩, 목적/제약/성공 기준 이해
4. 2-3가지 접근법 제시 — 트레이드오프와 추천 포함
5. 외부 의존 문서 검증 — 라이브러리/API 가정을 실제 문서로 대조
6. 설계 제시 — 복잡도에 비례한 분량, 섹션별 승인
7. 계획 생성 — bite-sized 태스크로 변환
8. 실행 핸드오프 — pipeline-execute 스킬로 이관

프로세스

Phase 1: 이해

searcher 에이전트를 활용하거나 직접 수행:

• 현재 코드베이스 구조 파악 (파일, 패턴, 의존성)
• 관련 문서/이슈 확인
• 한 번에 질문 하나 — 멀티 질문 금지
• 가능하면 객관식, 필요하면 서술형
• 목적, 제약, 성공 기준에 집중

Phase 1.5: 영향도 분석 (Blast Radius)

기존 모듈/심볼/파일을 변경하는 설계라면 수행한다. 의존자가 없는 신규 코드만이면 생략.

1. 의존자 매핑 — rg "<심볼>"로 호출자 검색, rg "<심볼>" -g '*.test.*' -g '*.spec.*'로 테스트 커버리지 확인
2. 리스크 스코어 산정 (0-10점):
   • Fan-in (호출자 수): 0-4점 — ≤2곳: 0-1, 3-10곳: 2-3, >10곳 또는 공유 API/인터페이스: 4
   • Fan-out (변경 대상이 사용하는 의존성 수): 0-3점
   • 최근 churn (git log --oneline -5 -- <파일> 커밋 수): 0-3점
3. 게이트:
   • 7점 초과 → 설계 승인 전 stress-interview 스킬로 압박 검토 필수
   • 3-7점 → 설계 제시에 리스크 등급과 테스트 갭을 명시
   • 3점 미만 → 그대로 진행

"뭐가 깨질지 모르겠다" 상태로 설계를 제시하지 않는다.

Phase 2: 접근법 탐색

• 2-3가지 접근법을 트레이드오프와 함께 제시
• 추천안을 먼저 제시하고 이유를 설명
• 대화체로 자연스럽게 전달

Phase 2.5: 외부 의존 문서 검증

설계가 외부 라이브러리, 서드파티 API, 프레임워크 동작에 의존하면 설계 제시 전에 수행한다:

1. 설계가 기대는 외부 동작 가정을 전부 나열한다
2. 가정마다 실제 문서를 확인한다 — context7-cli 스킬(ctx7) 우선, 없으면 공식 문서 fetch
3. 대조 항목: 메서드 시그니처가 맞나? 사용 중인 버전에 존재하나? deprecated 아닌가?
4. 결과를 분류한다:
   • 확인 ✓ — 그대로 진행
   • 정정 ✗ — 실제 동작을 기록하고 설계 수정
   • 불확실 ? — 최소 프로토타입으로 직접 검증 후 진행

"라이브러리가 아마 이렇게 동작할 것" 상태로 설계를 확정하지 않는다.

Phase 3: 설계 제시

승인된 접근법을 기반으로 설계를 제시한다:

• 섹션별로 나눠서 제시 — 한 번에 전부 쏟지 않는다
• 각 섹션 후 "여기까지 맞나요?" 확인
• 복잡도에 비례한 분량:
  • 단순: 2-3문장
  • 중간: 200-300 단어
  • 복잡: 아키텍처, 컴포넌트, 데이터 흐름, 에러 처리, 테스팅
• 수정 요청 시 돌아가서 재조정

Phase 4: 계획 변환

승인된 설계를 bite-sized 태스크로 변환한다:

### Task N: [컴포넌트명]

**파일:**
- 생성: `정확한/경로/파일.ts`
- 수정: `정확한/경로/기존.ts:123-145`
- 테스트: `tests/정확한/경로/test.ts`

**Step 1: 실패 테스트 작성**
[구체적 코드]

**Step 2: 테스트 실패 확인**
실행: `정확한 명령어`
예상: FAIL — "함수 미정의"

**Step 3: 최소 구현**
[구체적 코드]

**Step 4: 테스트 통과 확인**
실행: `정확한 명령어`
예상: PASS

**Step 5: 커밋**

원칙:

• 태스크당 2-5분 분량
• 정확한 파일 경로 항상 포함
• 구체적 코드 — "유효성 검사 추가" 같은 애매한 지시 금지
• 실행 명령어와 예상 결과 명시
• DRY, YAGNI, TDD

Phase 5: 실행 핸드오프

계획 완료. 실행 방법을 선택하세요:

1. pipeline-execute — 태스크별 worker→verifier→reviewer 자동 파이프라인
2. 수동 실행 — 직접 하나씩 진행
3. 계획만 저장 — 나중에 실행

어떤 방식으로 할까요?

pipeline-execute 선택 시: 해당 스킬로 즉시 이관.

YAGNI 원칙

설계에서 다음을 적극 제거한다:

• "나중에 필요할 수 있는" 기능
• "혹시 모르니까" 추가하는 추상화
• 요청하지 않은 확장 포인트

"You Aren't Gonna Need It" — 지금 필요한 것만.

안티패턴: "이건 너무 단순해서 설계가 필요 없어"

모든 작업이 이 프로세스를 거친다. 설계가 짧으면 짧은 대로 — 하지만 생략하지 않는다.

"단순한" 프로젝트야말로 검증되지 않은 가정이 가장 많은 재작업을 유발한다.

핵심 원칙

• 한 번에 질문 하나 — 질문 폭탄 금지
• 객관식 우선 — 답하기 쉽게
• 영향도 먼저 — 리스크 스코어 7점 초과면 stress-interview 선행
• 문서로 검증 — 외부 라이브러리 가정은 실문서 대조 후 확정
• YAGNI 철저히 — 불필요한 기능 제거
• 대안 탐색 — 항상 2-3가지 제시
• 점진적 검증 — 설계 제시 후 확인, 다음으로
• 유연하게 — 맞지 않으면 돌아가서 재조정