Spec-Driven Development Assistant | 規格驅動開發助手
Create, review, and manage specification documents before writing code.
在撰寫程式碼前，建立、審查和管理規格文件。
When to Use /sdd vs uds spec | 何時使用
| Scenario | /sdd | uds spec |
|---|---|---|
| Formal feature development with review cycle | ✅ | ❌ |
| Full spec lifecycle (Draft → Archived) | ✅ | ❌ |
| Quick prototyping / Vibe coding | ❌ | ✅ |
| Small incremental changes | ❌ | ✅ |
| Stakeholder sign-off required | ✅ | ❌ |
| Micro-spec from natural language intent | ❌ | ✅ |
/sdd= Full specification lifecycle for formal developmentuds spec= Lightweight micro-specs for rapid iteration/sdd= 正式開發的完整規格生命週期uds spec= 快速迭代的輕量微規格
TL;DR Quick Checklist | 快速檢查清單
- Search existing specs: look in
specs/,docs/specs/, or project spec directory - Decide scope: new feature vs modify existing capability
- Pick a unique spec ID:
SPEC-NNNor kebab-case change ID - Write proposal with clear AC (Given/When/Then format)
- Get approval before implementation begins
- Implement tasks sequentially, verify against spec
- Archive spec after completion
Decision Tree | 決策樹
New request? | 新需求？
├─ Bug fix restoring spec behavior? → Fix directly | 直接修復
├─ Typo/format/comment? → Fix directly | 直接修復
├─ Dependency update (non-breaking)? → Fix directly | 直接修復
├─ New feature/capability? → Create proposal | 建立提案
├─ Breaking change? → Create proposal | 建立提案
├─ Architecture change? → Create proposal | 建立提案
└─ Unclear? → Create proposal (safer) | 建立提案（較安全）Workflow | 工作流程
DISCUSS ──► CREATE ──► REVIEW ──► APPROVE ──► IMPLEMENT ──► VERIFY ──► ARCHIVE0. Discuss - Clarify Scope | 釐清範圍
Capture gray areas, establish governing principles, resolve ambiguities before writing spec.
1. Create - Write Spec | 撰寫規格
Define requirements, technical design, acceptance criteria, and test plan.
2. Review - Validate | 審查驗證
Check for completeness, consistency, and feasibility with stakeholders.
3. Approve - Sign Off | 核准
Get stakeholder sign-off before implementation begins.
4. Implement - Code | 實作
Develop following the approved spec, referencing requirements and AC.
5. Verify - Confirm | 驗證
Ensure implementation matches spec, all tests pass, AC satisfied.
6. Archive - Close | 歸檔
Archive completed spec with links to commits/PRs.
Spec States | 規格狀態
| State | Description | 說明 |
|---|---|---|
| Draft | Work in progress | 草稿中 |
| Review | Under review | 審查中 |
| Approved | Ready for implementation | 已核准 |
| Implemented | Code complete | 已實作 |
| Archived | Completed or deprecated | 已歸檔 |
Spec Structure | 規格結構
# [SPEC-ID] Feature: [Name]
## Overview
Brief description of the proposed change.
## Motivation
Why is this change needed? What problem does it solve?
## Requirements
### Requirement: [Name]
The system SHALL [behavior description].
#### Scenario: [Success case]
- **GIVEN** [initial context]
- **WHEN** [action performed]
- **THEN** [expected result]
## Acceptance Criteria
- AC-1: Given [context], when [action], then [result]
## Technical Design
[Architecture, API changes, database changes]
## Test Plan
- [ ] Unit tests for [component]
- [ ] Integration tests for [flow]Scenario Formatting Rules | 場景格式規則
- Use
#### Scenario:(h4 header) for each scenario - Every requirement MUST have at least one scenario
- Use GIVEN/WHEN/THEN format for structured behavior
- Use SHALL/MUST for normative requirements, SHOULD for recommendations
Delta Operations | 變更操作
When modifying existing specs, use delta sections:
| Operation | Description | 說明 |
|---|---|---|
## ADDED Requirements | New capabilities | 新增功能 |
## MODIFIED Requirements | Changed behavior | 修改行為 |
## REMOVED Requirements | Deprecated features | 移除功能 |
## RENAMED Requirements | Name changes | 重新命名 |
Usage | 使用方式
/sdd - Interactive spec creation wizard | 互動式規格建立精靈
/sdd auth-flow - Create spec for specific feature | 為特定功能建立規格
/sdd review - Review existing specs | 審查現有規格
/sdd --sync-check - Check sync status | 檢查同步狀態Next Steps Guidance | 下一步引導
After /sdd completes, the AI assistant should suggest:
規格文件已建立。建議下一步 / Specification document created. Suggested next steps: - 執行/derive從規格推導測試工件 ⭐ Recommended / 推薦 — Derive test artifacts from spec - 執行/derive bdd僅推導 BDD 場景 — Derive BDD scenarios only - 執行/derive tdd僅推導 TDD 骨架 — Derive TDD skeletons only - 審查 AC 完整性，確保所有驗收條件可測試 — Review AC completeness - 檢查 UDS 規範覆蓋率 → 執行/audit --patterns— Check UDS standard coverage → Run/audit --patterns
Reference | 參考
- Detailed guide: guide.md
- Core standard: spec-driven-development.md
AI Agent Behavior | AI 代理行為
完整的 AI 行為定義請參閱對應的命令文件：/sddFor complete AI agent behavior definition, see the corresponding command file:/sdd