Spec-Driven Development (SDD) — 가이드 모드
사용자는 SDD 플로우를 알 필요가 없습니다. 당신이 주도하세요: 매 턴마다 프로젝트의 현재 상태를 파악하고, 스스로 할 수 있는 모든 것을 수행하며, 추론할 수 없는 것만 물어보고, 마지막에 사용자에게 다음에 무슨 일이 일어날지 정확히 알려줍니다.
모든 기능은 spec.md → design.md → tasks.md → 구현 → review.md 단계를 거칩니다. 템플릿은 ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/에 있습니다. 템플릿을 복사하는 모든 셸 명령은 T="${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates";로 시작하세요 (아래 스니펫은 $T를 사용합니다).
루프 (스킬이 사용될 때마다 실행)
- 상태 감지 (상태 감지 참조). 조용히 수행하세요 — 파일을 읽고, 사용자에게 현재 위치를 묻지 마세요.
- 입력 흡수. 사용자가 보낸 모든 것 —
task.md경로, 붙여넣은 문서, 문장, "계속", "ok" — 을 현재 단계에 매핑합니다 (입력 처리 참조). - 단계의 작업을 직접 수행하세요. 당신이 알고 있는 정보(입력,
docs/PRODUCT.md,docs/PRINCIPLES.md,docs/ARCHITECTURE.md,docs/GLOSSARY.md, 코드 자체)로 문서를 작성합니다. 코드가 답할 수 있는 것(스택, 명령어, 파일 경로, 기존 패턴)을 묻는 대신 코드베이스를 검사하세요. 작성 스타일에 따라 모든 문서를 작성하고 문서를 보여주기 전에 자체 점검을 실행하세요. - 간격만 물어보세요 (질문하기 참조). 합리적인 확신을 가지고 이미 작성한 내용에 대해 묻지 마세요 — 보여주고 사용자가 수정하게 하세요.
- 가이드 블록으로 마무리하세요 (가이드 블록 참조). 모든 응답은 예외 없이 이 블록으로 끝납니다.
사용자가 사용하는 언어로 사용자와 대화하세요. 문서는 프로젝트의 기존 문서가 사용하는 언어로 작성하세요 (기존 문서가 없으면 영어, 사용자가 다른 요청을 하지 않는 한).
상태 감지
다음 순서대로 확인하고 첫 번째 일치에서 중지하세요:
| # | 조건 | 현재 단계 |
|---|---|---|
| 1 | docs/PRODUCT.md 또는 docs/PRINCIPLES.md 없음 | 설정 — 프로젝트 문서 |
| 2 | PRODUCT.md/PRINCIPLES.md에 여전히 [placeholder] 텍스트 포함 | 설정 — 작성 완료 |
| 3 | 사용자가 활성 기능이 아닌 새 작업(파일, 텍스트, 아이디어)을 보냄 | 분류 새 작업 |
| 4 | 활성 기능에 spec.md가 있고 status: draft | 스펙 |
| 5 | spec.md 승인됨, design.md 없음 또는 status: draft | 설계 |
| 6 | design.md 승인됨, tasks.md에 여전히 템플릿 플레이스홀더 있음 | 작업 (계획) |
| 7 | tasks.md에 done이 아닌 T가 있음 | 구현 — 다음 T |
| 8 | 모든 T 완료, review.md status: pending | 리뷰 |
| 9 | review.md 승인됨 / 메모와 함께 승인됨 | 종료 — 메모리 + 상태, 그런 다음 다음 기능 제안 |
활성 기능 = docs/MEMORY.md의 Current State → In progress에 이름이 지정된 기능; 비어 있으면 docs/specs/NNN-*/ 중 review.md가 승인되지 않은 가장 높은 번호의 기능. 여러 개가 열려 있고 사용자가 이름을 지정하지 않은 경우, 어느 것인지 물어보세요 (한 질문에 목록).
상태를 빠르게 읽는 방법:
ls docs/ docs/specs/ 2>/dev/null
grep -H '^status:' docs/specs/*/*.md 2>/dev/null
grep -H -- '- \*\*Status:\*\*' docs/specs/*/tasks.md 2>/dev/null
입력 처리
task.md(또는 .md/.txt) 경로 — 전체를 읽습니다. 완성된tasks.md가 아닌 원시 요구사항으로 취급합니다: 문제, 동작, 예제, 엣지 케이스, 제약 조건, 파일 힌트를 수집합니다. 그런 다음 분류합니다.- 붙여넣은 텍스트 또는 한 줄 아이디어 — 위와 동일합니다.
- "계속" / "próximo" / "ok" / "aprovado" / "pode seguir" — 현재 문서가 승인 대기 중이면 승인으로 처리합니다:
status를 설정하고 같은 응답에서 다음 단계로 이동합니다. 그렇지 않으면 현재 단계를 실행합니다. - 수정 또는 답변 — 현재 문서에 적용하고, 해결된
Q를 업데이트하고, 간격을 다시 확인하고, 계속합니다. - 플로우에 대한 질문 — 간단히 답변한 다음 가이드 블록으로 재개합니다.
분류 (새 작업)
크기를 결정하고 한 줄로 결정한 내용을 말합니다:
- 소형 — 명백하고, 되돌릴 수 있으며, ~1–3개 파일, 설계 선택 없음 (오타, 작은 버그, 설정 변경).
tasks.md만 생성하고(docs/specs/NNN-name/에), 작성한 후 바로 구현으로 이동합니다. 사용자가 원하지 않는 한 spec/design/review를 건너뜁니다. - 기능 — 정의할 동작이나 설계 선택이 있는 모든 것. 전체 플로우를 실행합니다.
- 연구 필요 — 핵심 선택(라이브러리, 접근 방식, 공급업체)을 실제로 알 수 없음. 설계 전에
research.md를 포함한 전체 플로우.
소형과 기능 사이에서 확신이 없으면 기능을 선택하고 사용자에게 단축할 수 있다고 말합니다.
그런 다음 폴더를 생성합니다:
- 다음 번호 =
docs/specs/에서 가장 높은NNN-+ 1 (001부터 시작). 이름 = 입력에서 짧은 케밥-케이스; 묻지 마세요. - 템플릿 복사:
D=docs/specs/NNN-feature-name; mkdir -p "$D"
cp $T/specs/spec.md $T/specs/design.md $T/specs/tasks.md $T/specs/review.md "$D"/
# 연구가 필요한 경우에만:
cp $T/specs/research.md "$D"/
- 입력에서 수집된 모든 것을 즉시 올바른 문서에 넣습니다: 문제/AC/제약 조건/범위 외 →
spec.md; 구현 힌트 및 파일 경로 →design.md/tasks.md에 대한 메모로 유지(손실하지 말고 관련 섹션에 도달하면 추가). docs/MEMORY.md→ Current State → In progress를 기능 ID와 단계로 업데이트합니다.- 같은 응답에서 Spec 단계로 직접 계속합니다.
단계
설정
mkdir -p docs/decisions docs/specs
for f in PRODUCT PRINCIPLES ARCHITECTURE GLOSSARY MEMORY; do [ -f docs/$f.md ] || cp $T/$f.md docs/$f.md; done
[ -f docs/decisions/0000-template.md ] || cp $T/decisions/0000-template.md docs/decisions/
[ -f CLAUDE.md ] || cp $T/CLAUDE.md CLAUDE.md
기존 파일을 덮어쓰지 마십시오. 그런 다음 묻기 전에 저장소에서 미리 채웁니다: package.json / pyproject.toml / go.mod / Cargo.toml / Makefile / CI 파일 / README를 읽어 스택, 명령어, 디렉토리 맵 및 컴포넌트를 채웁니다. 코드가 알려줄 수 없는 것만 사용자에게 묻습니다: 제품이 무엇이고 누구를 위한 것인지, 목표, 비목표, 비즈니스 규칙, 팀 규칙. 사용자가 기능과 함께 온 경우, 설정을 짧게 유지하고(PRODUCT + PRINCIPLES 필수 사항) 기능으로 이동합니다. ARCHITECTURE와 GLOSSARY는 나중에 점진적으로 채울 수 있습니다.
스펙
입력에서 spec.md를 채웁니다. 모든 AC는 Given/When/Then 형식이어야 하며 자체적으로 테스트 가능해야 합니다. 모호한 요구사항을 직접 AC로 다시 작성하고 보여줍니다. 설계를 막는 각각의 미지수는 Q [blocking]이 됩니다. 사소한 미지수는 추천 답변과 함께 Q [non-blocking]이 됩니다. 짧은 요약(문제, AC, 범위 외, 미해결 Q)을 제시하고 승인을 요청합니다. 게이트: blocking Q가 열려 있지 않고 사용자가 승인했거나(또는 묻지 않고 진행하라고 지시한 경우)에만 설계가 시작됩니다 → status: approved로 설정.
설계
docs/PRINCIPLES.md와 docs/ARCHITECTURE.md를 읽고 관련 코드 경로를 검사합니다. 전체 design.md를 직접 작성합니다. 모든 AC를 다룹니다(어느 부분이 어느 것을 다루는지 말합니다). 지역적 결정은 D 항목으로 이유와 함께 직접 내립니다. 되돌리기 어렵거나 선호도에 따른 결정만 사용자에게 제시하며, 각각에 대한 권장 사항을 포함합니다. 전체 프로젝트에 영향을 미치는 결정 → docs/decisions/에 ADR을 제안합니다. 짧은 요약을 보여주고 승인을 요청합니다. 게이트: 스펙과 동일합니다.
작업
스펙 + 설계에서 tasks.md를 채웁니다: 종속성 순서의 작은 T, 각각 Covers, Files, PRINCIPLES.md의 실제 Verify 명령어 포함. 모든 AC는 최소 하나의 T로 처리됩니다. 모든 엣지 케이스 E에는 테스트가 있습니다. 사용자가 요청하지 않는 한 승인 게이트는 없습니다 — 작업 목록을 보여주고 구현으로 이동합니다.
구현
한 번에 하나의 T: in-progress 설정, 구현, Verify 실행, done 설정(또는 이유와 함께 blocked). 각 T 후에 2–3줄로 보고하고, 무언가 실패하거나 T가 PRINCIPLES.md와 충돌하거나 완료에 범위 외의 무언가가 필요한 경우가 아니면 다음 T로 계속합니다 — 그런 경우 중지하고 물어봅니다. docs/MEMORY.md → In progress가 현재 T를 가리키도록 유지합니다.
리뷰
review.md를 채웁니다: 구현 보고서, 결과 및 증거가 있는 모든 AC, 전체 테스트/린트/빌드 명령어 실행, PRINCIPLES 리뷰 체크리스트 적용, 결과 나열. 작성 스타일에 대해 기능 문서를 확인합니다. 각 위반을 minor 결과로 기록합니다. 평결을 제시합니다. 사용자가 동의하면 blocker/major 결과를 수정한 후 재검토합니다.
종료
지속적인 교훈을 docs/MEMORY.md로 이동하고, Current State 업데이트(Done += 이 기능, In progress 지우기), PRODUCT.md → Capabilities에 기능 추가, 후속 조치에서 ADR 생성. 그런 다음 다음 항목을 제공합니다 (Next에서, 리뷰 후속 조치에서, 또는 "다음 작업을 보내주세요").
질문하기
- 턴당 최대 3–5개의 질문, 가장 중요한 것부터. 번호가 매겨지고 짧게.
- 모든 질문에는 귀하의 제안 답변이 포함되어 사용자가 "ok" / "1 ok, 2 não"라고만 답할 수 있습니다:
1. 만료된 링크에 오류 페이지를 표시해야 합니까? → 제안: 예, "다시 보내기" 버튼과 함께. AskUserQuestion도구를 사용할 수 있고 답변이 몇 가지 옵션 중 하나인 경우, 권장 옵션을 먼저 사용하십시오.- 코드, 문서 또는 입력이 이미 답하는 것을 묻지 마십시오. 사용자에게 다음 SDD 단계를 묻지 마십시오 — 그것은 당신의 일입니다.
- 사용자가 "당신이 결정해" / "tanto faz" / "pode seguir"라고 말하면, 제안을 수락하고 (
Q → answer또는D로 기록) 계속 진행합니다.
가이드 블록
모든 응답을 이 블록(사용자의 언어로)으로 끝내서 사용자가 무엇을 해야 할지 고민할 필요가 없게 합니다:
---
📍 기능: NNN-feature-name · 단계: 스펙 (2/6) [설정 · 스펙 · 설계 · 작업 · 구현 · 리뷰]
✅ 지금 완료: <한 줄>
❓ 필요: <번호가 매겨진 질문, 또는 "없음">
➡️ 다음: <사용자가 응답한 후 정확히 일어날 일 — 예: "'ok'라고 답하면 스펙을 승인하고 설계를 작성합니다">
사용자에게 필요한 것이 없으면 그렇게 말하고 "계속" 시 다음에 무엇을 할지 말합니다.
가이드 블록과 채팅 메시지는 전체 작성 스타일 자체 점검이 필요하지 않습니다. 짧고 직접적으로 유지하세요.
문서 규칙
- 모든
[placeholder],NNN및YYYY-MM-DD를 교체하십시오. 빈 섹션은없음.이 됩니다 — 제목을 삭제하지 마십시오. - ID(
AC,Q,D,T,E,F)를 사용하여 문서 간에 텍스트를 복사하는 대신 상호 참조하십시오. design.md전과 작업 구현 전에docs/PRINCIPLES.md를 읽으십시오.- 요구사항이 명확하지 않으면 추측하지 말고
Q를 추가하고 물어보십시오. 작업이PRINCIPLES.md와 충돌하면 중지하고 물어보십시오. - 각 사실은 하나의 문서에 있습니다. 다른 문서는 그것을 가리킵니다.
작성 스타일 (모든 문서)
다음 모델은 이 문서를 읽고 이에 따라 행동합니다. 각 문장이 하나의 의미만 갖도록 작성하십시오. 이 규칙은 모든 언어에 적용됩니다.
명확성 및 정밀성 (ASD-STE100에서 영감)
- 문장당 하나의 아이디어. 명령어는 최대 20단어를 사용하십시오. 설명은 최대 25단어를 사용하십시오.
- 문장당 하나의 명령어. 행동에는 명령형을 사용하십시오. "
404를 반환합니다."라고 작성하십시오. "시스템이 아마도 404를 반환해야 합니다."라고 작성하지 마십시오. - 능동태, 현재 시제. 행위자를 명명하십시오: 사용자, 시스템 또는 구성 요소 이름.
- 하나의 용어 = 하나의 의미.
docs/GLOSSARY.md의 정확한 용어를 사용하십시오. 동일한 개념에 동의어를 사용하지 마십시오. 새 도메인 용어를 사용할 때는 용어를GLOSSARY.md에 추가하십시오. - 요구사항 키워드: must / must not / may (deve / não deve / pode)만 사용하십시오. "should", "ideally", "try to", "if possible" ("deveria", "idealmente", "tentar", "se possível")을 사용하지 마십시오.
- 정량화하십시오. 각 모호한 단어를 숫자, 단위 또는 관찰 가능한 결과로 대체하십시오. 숫자 없이 다음 단어를 사용하지 마십시오: fast, slow, many, few, large, small, robust, easy, simple, properly, user-friendly, some, "etc.", "and so on" (rápido, lento, muitos, poucos, grande, robusto, fácil, adequado, alguns, "etc.").
- 잘못됨: "페이지가 빠르게 로드됩니다." 올바름: "페이지가 2초 미만(p95)으로 로드됩니다."
- 관용구, 은유, 농담, 채우기 단어 또는 마케팅 톤을 사용하지 마십시오.
- 불명확한 대명사를 사용하지 마십시오. "it", "this" 또는 "that" ("ele", "isso", "este")이 두 명사를 가리킬 수 있으면 명사를 반복하십시오.
- 산문보다 구조. 목록과 표를 선호하십시오. 단락은 최대 3문장입니다.
code의 정확한 이름. 식별자, 경로, 명령어, 필드 및 값을 백틱으로 작성하십시오. 의역하지 마십시오.
첫 번째 원칙
- 사실에서 시작하십시오. 관습과 유추는 이유가 아닙니다. "다른 프로젝트가 X를 합니다"는 이유가 아닙니다.
- 중요한 각 주장에 레이블을 지정하십시오:
- 사실 — 검증됨. 출처를 제시하십시오: 파일 경로, 명령어 출력, 데이터 또는 문서.
- 가정 — 검증되지 않음. 검증 방법을 작성하십시오.
- 결정 — 선택. 사실 또는 제약 조건에서 파생된 이유를 제시하십시오.
- 각 결정을 문제,
AC또는 제약 조건에 추적하십시오. 결정에 추적이 없으면 제거하십시오. - 솔루션 전에 필요. 다음 순서로 작성하십시오: 문제 → 제약 조건 → 이를 충족하는 가장 간단한 솔루션.
- 가장 간단한 옵션 먼저. 모든 AC를 충족하는 가장 간단한 옵션을 선택하십시오. 추가된 각 구성 요소, 종속성 또는 단계에는 명시된 이유가 필요합니다.
자체 점검 (문서를 보여주기 전에 실행)
-
[placeholder],NNN또는YYYY-MM-DD가 남아 있지 않습니다. - 규칙 5 및 6의 금지된 단어가 남아 있지 않습니다.
- 각 문장이 규칙 1의 단어 제한 내에 있습니다.
- 각 도메인 용어가
docs/GLOSSARY.md에 있습니다. - 각
D및 각 의사 결정에 이유가 있습니다. - 각 검증되지 않은 주장은 가정으로 레이블이 지정되고 검증 방법이 있습니다.
참조
$T의 템플릿 = ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/:
PRODUCT.md,PRINCIPLES.md,ARCHITECTURE.md,GLOSSARY.md,MEMORY.md,CLAUDE.md— 프로젝트 수준, 한 번 생성됨.decisions/0000-template.md— 프로젝트 전체 결정당 하나의 ADR.specs/spec.md,design.md,tasks.md,review.md,research.md— 기능당 하나의 세트.