Sdd

SDD — Spec-Driven Development

사용자의 표준 개발 워크플로우. 딥인터뷰로 요구사항을 구조화하고, 승인 게이트를 거쳐 spec 문서를 만들고, 태스크 단위로 구현·검증한다. 사용자는 해당 도메인의 비전문가일 수 있다 — 모든 승인 요청에는 판단에 필요한 설명이 선행된다.

산출물 위치 (프로젝트 루트 기준)

.claude/specs//requirements.md   # 요구사항 (Overview + EARS 인수 조건)
.claude/specs//design.md         # 기술 설계
.claude/specs//tasks.md          # 실행 태스크 체크리스트
.claude/specs/adr/NNNN-.md               # 아키텍처 결정 기록 — 기능이 아닌 프로젝트 단위로 누적

• `은 kebab-case (예: payment-module, user-auth`).
• 템플릿은 이 스킬의 templates/ 디렉토리에 있다. 문서 생성 시 반드시 템플릿 구조를 따른다.

핵심 규칙

1. 승인 게이트: requirements → design → tasks 각 문서가 완성되면 반드시 사용자 승인을 받은 뒤 다음 단계로 넘어간다. 승인 없이 두 단계를 연속 진행하지 않는다. 실행(Phase 5) 진입도 tasks.md 승인이 선행되어야 한다.
2. 설명 책임 (비전문가 전제): 승인 게이트는 사용자가 내용을 이해해야 성립한다. 구조·기술·패턴 선택은 문서에 적는 것으로 끝내지 않고 — 무엇인지 → 왜 이걸 쓰는지 → 대안 대비 무엇을 얻고 잃는지 — 를 전제 지식 없이 읽히는 말로 설명한다. 전문 용어는 처음 등장할 때 한 줄 풀이를 붙인다. 승인 요청은 "문서 요약 + 승인?"이 아니라 판단 근거를 먼저 제공하는 워크스루로 한다. 사용자의 "왜?"에 문서 인용이 아니라 설명으로 답할 수 있어야 한다.
3. 문서 언어: 한국어. 코드 식별자·기술 용어는 영어 그대로 둔다.
4. 상태 추적: 각 문서 frontmatter에 status: draft | approved를 기록한다. 승인 즉시 approved로 갱신한다. 실행 진행 상태는 tasks.md의 체크박스가 단일 진실 공급원(source of truth)이다.
5. 인터뷰 방식: 구조화된 선택지 질문 도구(Claude Code의 AskUserQuestion 등)가 있으면 사용하고, 없으면 채팅으로 번호 붙인 선택지를 제시한다. 한 라운드에 최대 4문항, 모호함이 해소될 때까지만 라운드를 반복한다. 대화나 코드베이스에서 이미 답이 명확한 것은 묻지 않는다. 뻔한 질문으로 라운드를 채우지 말 것.
6. 탐색 우선: 기존 코드베이스가 있는 프로젝트라면 design 작성 전에 반드시 관련 코드를 탐색한다 (explore 에이전트 위임 권장). 기존 패턴·스택·컨벤션을 설계에 반영한다.
7. 범위 준수: spec에 없는 기능을 임의로 추가하지 않는다. 실행 중 spec 변경이 필요해지면 사용자에게 확인 후 해당 문서를 먼저 갱신한다.

실행 흐름

Phase 0 — 시작 / 재개 판단

1. 인자가 있으면 (/sdd 결제모듈) 그것을 feature-name 후보로 쓴다.
2. .claude/specs/*/를 스캔한다:

• 진행 중인 spec(문서가 draft이거나 tasks.md에 미완료 체크박스가 있는 것)이 있으면 목록을 보여주고 재개할지 새로 시작할지 묻는다.
• 재개 시: status와 체크박스를 보고 멈춘 지점의 Phase부터 이어간다. 이전 문서들을 읽고 맥락을 복원한 뒤 진행한다.

1. 새 시작인데 feature-name이 없으면 인터뷰 후 내용에 맞게 제안하고 확정받는다.

Phase 1 — 딥인터뷰

소크라테스식으로 구조를 잡아간다. 다음 항목의 모호함이 해소될 때까지 AskUserQuestion으로 라운드를 반복한다:

• 문제/목표: 왜 만드는가, 지금 뭐가 불편한가
• 사용자와 핵심 시나리오: 누가, 어떤 흐름으로 쓰는가
• 스코프와 non-goals: 이번에 뺄 것은 무엇인가
• 기술 제약: 스택, 외부 연동, 성능/보안 요구
• 엣지케이스/실패 시나리오: 잘못되면 어떻게 되어야 하는가
• 완료 기준: 무엇이 되면 "됐다"고 할 수 있는가

각 라운드 후 알게 된 것을 한두 문장으로 요약하고, 남은 모호함이 있을 때만 다음 라운드를 진행한다.

기술적인 질문(스택, 연동, 성능/보안)은 사용자가 답을 모르는 게 정상이다 — 선택지마다 그 선택이 뜻하는 바와 영향을 설명에 담고, "모르겠다/추천해줘"를 유효한 답으로 받아 근거와 함께 추천안을 낸다. 사용자를 시험하는 질문이 아니라 결정을 돕는 질문이어야 한다.

Phase 2 — requirements.md

templates/requirements.md 구조로 작성:

• Overview: 문제 정의, 목표, non-goals, 성공 기준 (PRD의 핵심을 여기에 흡수)
• 요구사항: 번호 붙은 요구사항(R1, R2, …) 각각에 유저스토리 + EARS 형식 인수 조건(R1.1, R1.2, …)

인수 조건은 검증 가능한 문장으로만 쓴다 — "WHEN , THE SYSTEM SHALL ". 작성 후 핵심 내용을 요약해 보여주고 승인/수정을 묻는다. 수정 요청은 반영 후 다시 승인을 받는다.

Phase 3 — design.md (+ ADR)

1. 코드베이스 탐색 (기존 프로젝트인 경우 — 규칙 6).
2. templates/design.md 구조로 작성: 아키텍처 개요, 기술 선택과 이유, 컴포넌트와 인터페이스, 데이터 모델, 에러 처리, 테스트 전략. 각 설계 항목은 근거가 되는 요구사항 ID(R1.2 등)를 참조한다. "기술 선택과 이유"에는 주요 구조·기술·라이브러리마다 역할과 선택 이유(대안 대비)를 비전문가가 읽어도 이해되게 적는다.
3. 중대한 결정 처리: 실질적 대안이 여럿이고 번복 비용이 큰 결정(DB 선택, 통신 방식, 인증 구조 등)은 —

• 대안·트레이드오프를 비전문가 언어로 설명하고 추천안을 명시해 사용자가 결정하게 하고 (규칙 5의 질문 방식),
• 결정을 templates/adr.md 형식으로 .claude/specs/adr/NNNN-.md에 기록한다. NNNN은 기존 ADR을 스캔해 다음 번호를 쓴다.

1. 설계 워크스루 → 승인 게이트: 문서를 던져놓고 승인을 묻지 않는다. ① 전체 구조가 어떻게 돌아가는지 흐름 중심으로 설명 ② 주요 기술 선택마다 무엇/왜/대안 (규칙 2) ③ 사용자가 실제로 판단해야 할 지점만 좁혀서 질문. 그 뒤에 승인을 받는다.

Phase 4 — tasks.md

templates/tasks.md 구조로 작성. 태스크 원칙:

• 순서대로 실행 가능하게 정렬 (의존성 고려)
• 각 태스크는 독립적으로 검증 가능한 크기 (커밋 하나 수준)
• 각 태스크에 관련 요구사항 ID와 완료 조건 명시
• 테스트 작성도 태스크에 포함

승인 게이트 통과 후 Phase 5로.

Phase 5 — 실행

태스크를 위에서부터 하나씩:

1. 구현한다. 서브에이전트 기능이 있는 환경이면 크거나 독립적인 태스크를 위임할 수 있다.
2. 검증한다: 해당 태스크의 완료 조건 + 연결된 인수 조건 충족 확인, 관련 테스트 실행. 통과 못 하면 통과할 때까지 수정한다.
3. tasks.md의 체크박스를 갱신하고 다음 태스크로.
4. 실행 중 spec과 어긋나는 상황(설계 결함 발견, 요구사항 충돌)이 나오면 멈추고 사용자에게 확인 — 문서 갱신 후 재개.

최종 마무리: 전체 태스크 완료 후 —

• 전체 테스트 스위트 실행
• requirements.md의 모든 인수 조건을 전수 점검해 충족 여부 표로 보고
• 미충족 항목이 있으면 완료 선언하지 않고 해결한다

Phase 6 — 체인 마무리 (self-review → 커밋 → 회고)

검증 통과로 끝내지 않는다. 사용자가 다음 단계를 따로 시키지 않아도 이어간다:

1. Self-review: 전체 diff를 보안·엣지케이스·API 호환성 관점으로 검토한다 (Claude Code에서는 /code-review 활용 가능). 발견된 문제는 수정 후 해당 태스크의 검증을 다시 돈다.
2. 커밋 제안: Conventional Commits + 한국어 제목으로 커밋을 제안하고 승인받아 실행한다. spec 문서(.claude/specs/)도 함께 커밋한다.
3. 회고 반영: 이번 기능에서 반복된 실수나 새로 확정된 관례가 있으면 프로젝트 CLAUDE.md 또는 spec 템플릿에 반영을 제안한다. 없으면 생략.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tmdry4530
• Source: tmdry4530/chamdom-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.