# Handoff Spec

> 기획-개발 핸드오프 기획서를 표준 형식으로 인터뷰하여 작성하거나, 작성된 기획서에서 명확화 질문 추출과 Jira 티켓 분할을 수행한다. Use when 사용자가 기능 기획서·핸드오프 문서·스펙 작성을 요청할 때, 스펙을 티켓으로 분할할 때, 기획서 리뷰·명확화를 요청할 때, 또는 handoff-spec을 언급할 때.

- Skill: `cskwork/handoff-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cskwork/handoff-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cskwork/handoff-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cskwork (https://skillmd.com/u/cskwork)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cskwork/handoff-spec

---


# handoff-spec — 기획·개발 핸드오프 표준

기획서를 쓰거나 티켓으로 분할하기 전에 [FORMAT.md](FORMAT.md)를 읽고, 그 마크다운 구조를 그대로 따른다.
사람이 브라우저에서 직접 쓰는 편집형 템플릿은 리포 루트의 `handoff-spec-template.html`, 완성 예시는 `handoff-spec-example.html`.

## 모드 선택

- 사용자가 기획서를 써 달라고 하면 → **작성 모드**
- 이미 작성된 기획서(마크다운/텍스트)를 주면 → **소비 모드** (명확화 추출 + 티켓 분할)

## 작성 모드

1. **경로 결정**: 버튼·문구 수정 수준의 작은 기능은 간이 경로(FORMAT.md에서 **(간이)** 표시된 섹션만), 그 외에는 전체 경로(12개 섹션 전부). 판단이 애매하면 간이로 시작해 확장한다.
2. **인터뷰** — 제공된 자료에서 먼저 채우고, 결정에 필요한 미해결 항목만 한 번에 3개 이하로 질문한다:
   - 한 줄 요약(누가·무엇을·왜), 문제, 성공 기준(측정 시점 포함)
   - 규모·성능 가정: 데이터 최대 건수, 동시 접속, 응답 시간 예산, 지원 환경
   - 이번 범위 / 비범위(제외 사유 포함)
   - 사용자 흐름과 갈림길 (전체 경로일 때)
   - 예외 상황: 빈 값 · 오류 · 오프라인 · 권한 없음 · 중복/동시성 최소 5종 검토
3. **작성 규칙**:
   - 형용사는 합의된 숫자·조건으로 바꾼다. "빠르게"의 목표 시간이 미정이면 1초 같은 값을 만들지 말고 07 명확화 필요 표에 남긴다
   - 전체 경로에서는 화면마다 정상·빈·로딩·오류 4가지 상태를 정의. 해당 없으면 "해당 없음 — 사유"
   - 확신할 수 없는 항목은 전부 07 명확화 필요 표로 보낸다 (spec-kit의 [NEEDS CLARIFICATION] 관행)
   - 인수 조건은 GIVEN/WHEN/THEN 한 문장, A1·A2… 번호 부여
4. FORMAT.md 스키마 그대로 마크다운 파일로 저장한다. 파일명: `<기능명>-기획서.md`
5. 아래 **완료 기준 (작성 모드)**로 자체 검증한 뒤, 남은 명확화 질문을 사용자에게 보고한다.

## 소비 모드

1. **명확화 추출**: 모호하거나 미정이거나 상충하는 항목을 전부 질문 목록으로 만든다.
2. **티켓 분할** (spec-kit /tasks 방식):
   - 티켓 = 독립적으로 테스트·배포 가능한 세로 슬라이스 (UI·API·저장을 관통하는 얇은 조각)
   - 모든 티켓은 인수 조건 번호(A#)와 연결한다. 연결할 A#가 없는 범위는 티켓 대신 1의 명확화 질문으로 보낸다
   - 의존 순서를 명시하고, 동시 진행 가능하면 [P] 표시
   - 크기 S/M/L. 티켓 하나 = PR 하나(1~3일)를 넘지 않게 분할
   - 출력은 FORMAT.md의 "10 티켓 분할" 표 형식
3. 요청 시 Jira 등록용 텍스트(티켓당 제목 + 본문)로 변환한다. 실제 Jira 등록은 사용자가 요청한 경우에만 수행한다.
4. 아래 **완료 기준 (소비 모드)**로 자체 검증한 뒤 결과를 보고한다.

## 완료 기준 (작성 모드)

- [ ] 형용사·모호어 0건 (전부 숫자·조건으로 표현)
- [ ] 비범위가 명시됨
- [ ] 예외 상황 5종 이상 검토됨
- [ ] 인수 조건이 전부 GWT 형식 + A# 번호
- [ ] 미해결 명확화 항목을 전부 그대로 보고

## 완료 기준 (소비 모드)

- [ ] 모든 티켓이 A# 인수 조건에 연결됨
- [ ] 티켓마다 의존 순서 또는 [P] 표시가 있음
- [ ] 남은 모호·미정 항목이 전부 명확화 질문 목록에 있음