Spec Skill — PRD / Story 작성 절차

본 스킬은 사용자-facing 기본 공개 진입점의 /spec 이다. 기본 공개 진입점은 /spec -> /design -> /impl -> /acceptance 다.

흐름 요약: PRD 초안 → 사용자 초안 확인 → 기술 검토 필요 영역에 항목이 있으면 /tech-review preflight → PRD 최종화 → stories.md → product-acceptance:SPEC_ACCEPTANCE → PR 머지 → 이슈 등록 여부 확인 → /design.

Step 내부 분기는 본 파일이 소유한다. skill 간 이동·재진입은 spec-routing.md가 소유한다. 본 파일은 Step 운전 절차와 체크포인트 응답을 담는다. 용어·공개 진입점·분기 표현을 수정하거나 리뷰할 때만 terms.md 를 확인한다.

사용자 정정을 PRD·Story에 옮길 때 발화에 없는 일반화나 제품 동작을 덧붙이지 않는다. 필요하면 먼저 묻는다. 메인이 스스로 정한 항목은 "메인이 정한 내용"으로 구분해 사용자에게 보여 주며, 표시만으로 승인된 약속이 되지 않는다. 설계 agent 지시문에는 사용자·이슈·검증 지적에 없는 "닫을 결정"을 열거하지 않는다. 검증 지적도 원래 약속의 출처를 확인한다. 보강이 요청하지 않은 제품 실행 동작을 새로 만들면 작성 전에 사용자 확인을 받는다.

References

• PRD 템플릿: templates/prd.md
• 그릴미 / AC / 기술 검토 필요 영역 작성 기준: spec-prd-reference.md
• 구현 전 결정 범위·근거 상태·질문/위임·완료 의미: decision-completeness.md
• stories.md 형식 / Story 크기 가이드: spec-stories-reference.md
• branch / PR / issue 등록 명령 예시: spec-delivery-reference.md
• skill 간 분기 / 재진입 / 단방향 관례: spec-routing.md
• 용어 사전: docs/plugin/terms.md

작성 절차 (메인 직접)

Step 0 — 사전 read

정상 흐름은 본 파일과 필요한 reference 만 읽고 진행한다. Step 내부 체크포인트는 아래 절차를 따르고, skill 간 이동·재진입 경계가 필요할 때만 spec-routing.md를 확인한다.

Step 1 — 사용자와 그릴 대화

메인이 사용자와 직접 대화한다. 목표는 핵심 분기에서 shared understanding 에 도달하는 것이다. 질문은 한 번에 하나씩 하고, 코드로 확인 가능한 것은 코드베이스에서 확인한다.

그릴 강도와 PRD 템플릿 작성 기준은 spec-prd-reference.md를 따른다. 작업에 관련된 결정 범위와 근거 상태는 decision-completeness.md를 따른다. 중요한 선택을 사용자 확정·프로젝트 근거·도출 이유·명시적 위임 중 하나로 닫고, 근거 없는 가정과 중요한 미결정은 질문 또는 기존 검토 경로로 보낸다. 고정 표나 질문 개수는 만들지 않는다.

메인이 질문·설명·초안에 사실처럼 적은 문장 중 제품 동작을 정하는 문장을 가려낸다. 그 문장의 출처가 사용자 발화, 기존 PRD·코드, 이슈 본문이 아니면 전제로 두지 않고 사용자가 정할 선택으로 묻는다. 기능의 핵심 동작 정의(그 기능이 켜졌을 때와 꺼졌을 때, 성공했을 때와 실패했을 때 사용자에게 무엇이 달라지는가)는 부차적 선택보다 먼저 확인한다. 판단 기준은 decision-completeness.md를 따른다.

Step 2 — PRD 초안 작성

메인이 templates/prd.md를 문서 템플릿으로 사용해 docs/prd.md 를 초안으로 Write/Edit 한다. 변경은 섹션 단위 patch 로 한다.

docs/prd.md 초안 작성 → 사용자 초안 확인 흐름을 반드시 거친다. 초안에는 PRD 작성 중 이미 판단한 기술 검토 필요 영역을 포함한다. 검토 항목 0 개면 "해당 없음" 으로 닫는다.

초안은 결정 기록 전용 섹션을 강제하지 않는다. 다만 구현 방향을 바꿀 중요한 선택과 근거, 남은 미결정의 처리 위치가 PRD·기술 검토 필요 영역·후속 /design 범위 중 하나에서 downstream이 읽을 수 있어야 한다.

Step 3 — 사용자 PRD 초안 확인

PRD 초안 작성 직후 사용자에게 확인을 받는다.

초안 확인을 요청하기 전에 사용자가 핵심 동작을 실제로 그려 볼 수 있게 한다. 수단은 메인이 그 기능과 그 사용자에게 가장 잘 맞는 것으로 고른다. 예: 사용자가 겪는 상황을 순서대로 풀어 쓴 설명, 화면 목업, 비슷한 다른 제품의 동작과의 비교, 구체 상황을 사용자에게 되묻기("앱을 닫고 10분 뒤에 열면 어떻게 되어야 합니까"). 정해진 형식이나 정해진 질문 목록은 없다.

사용자가 핵심 동작을 자기 말로 서술했거나 구체 상황 질문에 답했으면 이해 확인은 이미 끝난 것이다. 사용자가 짧은 승인만 연속으로 답했으면 그 승인을 이해의 증거로 보지 않고, 이해를 확인하는 다른 수단을 한 번 쓴다. 사용자가 확인을 원하지 않는다고 밝히면 따른다.

PRD 초안 작성 완료:
- docs/prd.md

검토 후 결정:
- OK → Step 4 tech-review preflight 확인
- patch 필요 → 어떤 섹션 / 어떤 내용 알려주세요

사용자 patch 요청 시 docs/prd.md 해당 섹션을 patch 한 뒤 다시 Step 3 으로 돌아온다.

Step 4 — tech-review preflight 확인과 실행

메인이 PRD 초안의 기술 검토 필요 영역을 확인한다. 이 단계에서 외부 의존 / 비용 / 실현성 기준을 새로 판정하지 않는다. 그 기준은 Step 2 PRD 초안 작성 때 이미 적용되어 있어야 한다.

• 검토 항목 0 개 또는 "해당 없음" → Step 5 PRD 최종화
• 검토 항목 1 개 이상 → /tech-review preflight 진입

기술 검토 필요 영역 작성 기준은 spec-prd-reference.md를 따른다.

PRD 초안의 기술 검토 필요 영역에 검토 항목이 있어 PRD 최종화 / stories.md 작성 / 이슈 등록 전에 /tech-review 를 먼저 진행합니다.

입력:
- docs/prd.md 의 기술 검토 필요 영역

진행할까요? (Y/n)

분기:

• 사용자 Y 또는 명시 진행 → /tech-review 실행. tech-reviewer 가 docs/prd.md 를 읽고 docs/tech-review.md 를 생성/갱신하며 evidence/report 는 .dcness-work/reviews/ 에 저장한다.
• /tech-review PASS + 사용자 2차 OK → Step 5
• /tech-review FAIL / NO_GO / PRD 재기술 → 메인이 docs/prd.md 를 섹션 단위 patch 한 뒤 필요하면 /tech-review 재실행
• 사용자 n / 보류 / ESCALATE → 사용자 위임. PRD 최종화 / stories.md 작성 / PR 머지 / 이슈 등록으로 진행하지 않는다.

Step 5 — PRD 최종화

메인이 docs/prd.md 를 최종 PRD 로 업데이트한다. 별도 prd-final.md 는 만들지 않는다.

• tech-review preflight 가 없었으면 사용자 확인을 통과한 초안을 최종으로 취급한다.
• tech-review preflight 가 있었으면 docs/tech-review.md 의 verdict / 스펙 조정 권고 / 사용자 2차 OK 내용을 PRD 에 반영한다.
• 미해결 기술 질문이 남아 있으면 최종화하지 않는다.
• decision-completeness.md 기준의 근거 없는 가정과 중요한 미결정이 남아 있으면 최종화하지 않는다. 단, 낮은 영향의 명시적 위임과 근거가 있는 /design 세부화는 미결정으로 세지 않는다.

Step 6 — stories.md 작성

최종 PRD 기준으로 epic 단위 docs/epics/epic-NN-<slug>/stories.md 를 작성한다.

산출 형식은 spec-stories-reference.md를 따른다. 각 Story 에 프로젝트 전역 불변 AC-NNN 목록을 만들고, Epic 완료 기준과 Story AC 를 [command]/[agent-read] 로 분류한다. 사람 판정 항목은 AC 가 아닌 별도 안내로 분리한다. Story 분할과 순서도 같은 reference 의 사용자 검증 가능한 동작 증분 / 얇은 골격 우선 기준을 따른다.

stories.md 작성 직후 메인은 활성 프로젝트 루트에서 node "$PLUGIN_ROOT/scripts/aggregate_index_map.mjs" 를 실행해 docs/index.md 의 ## 에픽 생성 표를 갱신한다. 이 갱신이 빠지면 새 epic PR 이 doc-sync 게이트에서 stale 로 막힌다.

Step 7 — 사용자 최종 OK 체크포인트

PRD 최종본 + 필요한 tech-review 산출물 + stories.md 작성 완료 후 사용자에게 확인을 받는다.

최종 확인:
- docs/prd.md — PRD 최종본
- `docs/epics/epic-NN-<slug>/stories.md` — Epic + N Story
- docs/tech-review.md — 기술 검토 결과 (기술 검토 필요 영역에 항목이 있었을 때)

검토 후 결정:
- OK → Step 8 product-acceptance:SPEC_ACCEPTANCE
- patch 필요 → 어떤 섹션 / 어떤 내용 알려주세요

사용자 patch 요청 시 해당 섹션을 patch 한다. 기술 검토 필요 영역 영향이 있으면 Step 4 로 돌아가고, 없으면 Step 7 로 돌아온다.

Step 8 — product-acceptance:SPEC_ACCEPTANCE

사용자 최종 OK 후, branch 만들기 전 메인이 product-acceptance agent 를 SPEC_ACCEPTANCE mode 로 호출한다.

mode: SPEC_ACCEPTANCE
검수 단위: 현재 /spec 산출물
기준 문서:
- docs/prd.md
- docs/epics/epic-NN-<slug>/stories.md
- docs/tech-review.md (있으면)
핵심 동작 정의의 확정 경위:
- 핵심 동작 정의마다 사용자가 무엇을 제시받았고 어떻게 답했는지 (형식 자유)

목적:
이 spec 이 이후 설계/구현/검수에 충분히 닫혔는지 확인한다.
좋은 아이디어인지 평가하지 말고, Story AC binary 여부, 검수 증거 기준,
외부 의존/보안/권한/데이터 질문 누락, Story/Epic 분할 명확성,
Story 분할·순서가 사용자 검증 가능한 동작 증분인지를 본다.
결정 범위에 구현 방향을 바꿀 근거 없는 가정이나 중요한 미결정이 남았는지도 본다.
핵심 동작 정의가 사용자 확정인지 메인이 전제로 둔 것인지도 본다.
고정 표나 출력 형식의 존재로 판정하지 않는다.
full E2E 검증은 MVP /spec 이행 범위 밖이다.

확정 경위에는 메인의 판정("확정됨")이 아니라 대화에서 있었던 일을 적는다. 그 정의가 질문으로 제시됐는지, 설명문에만 있었는지, 사용자 발화가 무엇이었는지가 읽혀야 한다.

• PASS → Step 9
• FAIL → gap 보고 + 메인 patch 후 Step 7. 재검수 호출에는 직전 검수 결과와 그 뒤 patch 한 섹션을 함께 준다. 다시 검수할 범위는 메인이 처방하지 않고 product-acceptance 가 변경분을 읽고 고르며, 변경이 넓게 닿으면 스스로 전체로 올린다. 같은 gap 이 patch 뒤에도 반복되면 문구를 다시 고치지 않고 PRD·Story 분할의 근본 원인을 사용자와 다시 본다(rerun-judgment.md).
• ESCALATE → 기준 문서/권한/사용자 결정 부족 보고 후 사용자 위임

Step 9 — delivery topology 확정

PRD/stories.md는 main 기반 docs/<slug> PR 하나로 전달한다. 구현 topology를 spec 문서에 branch marker로 저장하지 않는다. 다중 story 구현은 /impl-loop가 story 브랜치 스택으로 구성하고, PR 생성과 merge 시점의 base를 분리해 관리한다.

Step 10 — branch + commit + PR + 머지

Step 9에서 확정한 main 기반 PRD/stories.md PR을 만들고 머지한다.

명령 예시는 spec-delivery-reference.md를 따른다. preflight 를 실행했다면 PR 에 docs/tech-review.md 를 포함한다. .dcness-work/reviews/ 는 git-tracked PR 대상이 아니다.

Step 11 — 이슈 등록 trigger (선택)

PR 머지 완료 후 사용자에게 확인한다.

PRD + stories.md 머지 완료. 이제 GitHub epic + story 이슈를 등록할까요? (Y/n)

• 사용자 Y → spec-delivery-reference.md의 scripts/create_epic_story_issues.sh 흐름 실행. 실행 전 보드(Project) 좌표·field 를 점검해 없거나 불완전하면 사용자에게 보드 셋업을 물어보고(거부 시 보드 없이 이슈만 생성), 스크립트가 생성된 epic/story 를 보드에 Status=Todo·IssueType·Priority=major 로 등록한다
• 사용자 n → 이슈 등록 보류. /design pre-flight 가 통과하도록 stories.md 의 epic/story issue marker 를 **GitHub Epic Issue:** 미등록 (사유: …) / **GitHub Issue:** 미등록 (사유: …) 형태로 남긴다. 기존 marker 가 없으면 별도 doc patch PR 로 marker 를 머지한 뒤 Step 12 로 간다.

이슈 등록 또는 미등록 marker 변경분은 별도 commit + PR 또는 사용자 자율이다.

Step 12 — /design 권고

이슈 등록 완료 또는 보류 marker 확인 후 메인이 사용자에게 confirm 한다.

PRD + stories.md + tech-review 상태 확인 완료.
이슈 등록: 완료 또는 보류 marker 확인 완료.

다음 단계 — 설계 루프:
→ /design <epic-path>

단방향 관례:
/design 진입 후 tech-reviewer 재호출은 비권장.
기술 검토 필요 영역에 항목이 있었다면 PRD 확정 / stories.md 작성 / 이슈 등록 전에 /tech-review preflight 로 이미 확정했어야 함.

진행할까요? (Y/n)

사용자 Y → /design 진입. 사용자 n → 사용자가 나중에 직접 호출한다.

대표 종료 audit trigger — CLAUDE.md/AGENTS.md 후보

/spec 은 helper 기반 run 이 아니므로 end-run 자동 review 가 없다. Step 12 안내를 끝낸 직후 메인이 기존 /run-review 유틸리티의 context audit 옵션을 1회 실행해 CLAUDE.md/AGENTS.md 현행화 후보만 read-only 로 출력한다.

"$PLUGIN_ROOT/scripts/dcness-review" --context-audit --repo "$PROJECT_ROOT"

• 출력은 제안만 한다. CLAUDE.md/AGENTS.md 자동 수정·자동 commit 금지.
• 후보를 반영하려면 사용자 승인 후 별도 docs PR 또는 후속 /impl 로 처리한다.

워크트리

/spec 은 워크트리 자동 진입 안 함. 기획·설계는 동시 다중 batch 충돌 회피 목적 부재. 메인 working tree 에서 별도 branch 를 따고 직접 진행한다.