spec-driven-dev
/spec-driven-dev
[UDS] 在写代码之前建立并审查规格文档——规格格式、状态与差异操作。 Use when: 某项变更需要先有书面规格、审查规格的完整性、用 delta 区段修订既有规格。 Not for: 执行带关卡的 SDD 生命周期——该部分已移至采用层(XSPEC-095);快速迭代用的轻量微规格——请用 uds spec 命令。 Keywords: SDD, spec, specification, design document, delta operation, spec review, 规格驱动开发, 规格文档, 变更操作, 规格审查.
- Author
- AsiaOstrich ↗
- Repository
- universal-dev-standards ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 3
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (3). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
[UDS] 在写代码之前建立并审查规格文档——规格格式、状态与差异操作。 Use when: 某项变更需要先有书面规格、审查规格的完整性、用 delta 区段修订既有规格。 Not for: 执行带关卡的 SDD 生命周期——该部分已移至采用层(XSPEC-095);快速迭代用的轻量微规格——请用 uds spec 命令。 Keywords: SDD, spec, specification, design document, delta operation, spec review, 规格驱动开发, 规格文档, 变更操作, 规格审查.
Original author description
[UDS] 在写代码之前建立并审查规格文档——规格格式、状态与差异操作。 Use when: 某项变更需要先有书面规格、审查规格的完整性、用 delta 区段修订既有规格。 Not for: 执行带关卡的 SDD 生命周期——该部分已移至采用层(XSPEC-095);快速迭代用的轻量微规格——请用 uds spec 命令。 Keywords: SDD, spec, specification, design document, delta operation, spec review, 规格驱动开发, 规格文档, 变更操作, 规格审查.
How it works
- When to Use /sdd vs uds spec | 何时使用
- TL;DR Quick Checklist | 快速检查清单
- Decision Tree | 决策树
- Workflow | 工作流程
- Spec States | 规格状态
- Spec Structure | 规格结构
- Delta Operations | 变更操作
- Cross-Artifact Analysis (/sdd analyze) | 跨 artifact 一致性检查
- Spec-vs-Code Convergence Check | 规格与实作漂移侦测(2026-07-10,spec-kit /converge 借鉴)
- Usage | 使用方式
SKILL.md preview
--- source: ../../../../skills/spec-driven-dev/SKILL.md source_version: 1.2.0 translation_version: 1.3.0 last_synced: 2026-08-17 source_hash: 989b50cd2147 status: current description: | [UDS] 在写代码之前建立并审查规格文档——规格格式、状态与差异操作。 Use when: 某项变更需要先有书面规格、审查规格的完整性、用 delta 区段修订既有规格。 Not for: 执行带关卡的 SDD 生命周期——该部分已移至采用层(XSPEC-095);快速迭代用的轻量微规格——请用 uds spec 命令。 Keywords: SDD, spec, specification, design document, delta operation, spec review, 规格驱动开发, 规格文档, 变更操作, 规格审查. --- <!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28): SDD 生命周期编排(7 阶段状态机、阶段转换、闸门检查)已迁移至 采用层(XSPEC-095, 2026-04-28)。本 Skill 保留:spec 格式定义、状态 描述、delta 操作、决策树。 如需强制执行的生命周期,请使用你采用层的工具链。 --> # Spec-Driven Development Assistant | 规格驱动开发助手 在编写代码前,建立、审查和管理规格文件。 在编写代码前,建立、审查和管理规格文件。 ## When to Use `/sdd` vs `uds spec` | 何时使用 | 场景 | `/sdd` | `uds spec` | |----------|--------|------------| | 带审查周期的正式功能开发 | ✅ | ❌ | | 完整 spec 生命周期(Draft → Archived) | ✅ | ❌ | | 快速原型 / Vibe coding | ❌ | ✅ | | 小幅增量改动 | ❌ | ✅ | | 需要利益相关方签核 | ✅ | ❌ | | 从自然语言意图生成 micro-spec | ❌ | ✅ | > **`/sdd`** = 用于正式开发的完整 spec 生命周期 > **`uds spec`** = 用于快速迭代的轻量 micro-spec > > **`/sdd`** = 正式开发的完整规格生命周期 > **`uds spec`** = 快速迭代的轻量微规格 ## TL;DR Quick Checklist | 快速检查清单 - 搜索已有 spec:查看 `specs/`、`docs/specs/` 或项目的 spec 目录 - 确定范围:新增功能 vs 修改既有能力 - 选取唯一的 spec ID:`SPEC-NNN` 或 kebab-case 变更 ID - 撰写提案,包含清晰的 AC(Given/When/Then 格式) - 在实作开始前取得批准 - 按顺序实作各任务,对照 spec 进行验证 - 完成后归档 spec ## 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 | 建立提案 ├─ Agent/role definition (spans multiple features)? → Use spec-type: agent | 使用 Agent SPEC template └─ Unclear? → Create proposal (safer) | 建立提案(较安全) ``` ## Workflow | 工作流程 ``` DISCUSS ──► CREATE ──► REVIEW ──► APPROVE ──► IMPLEMENT ──► VERIFY ──► ARCHIVE ``` ### 0. Discuss - Clarify Scope | 厘清范围 捕捉灰色地带、建立指导原则,并在撰写 spec 前消解歧义。 ### 1. Create - Write Spec | 撰写规格 定义需求、技术设计、验收条件与测试计划。 ### 2. Review - Validate | 审查验证 与利益相关方一起检查完整性、一致性与可行性。 ### 3. Approve - Sign Off | 核准 在实作开始前取得利益相关方签核。 ### 4. Implement - Code | 实作 依据已核准的 spec 进行开发,参照需求与 AC。 ### 5. Verify - Confirm | 验证 确保实作与 spec 相符、所有测试通过、AC 满足。 ### 6. Archive - Close | 归档 将完成的 spec 归档,并附上指向 commit/PR 的链接。 ## Spec States | 规格状态 | 状态 | Description | 说明 | |-------|-------------|------| | **Draft** | Work in progress | 草稿中 | | **Review** | Under review | 审查中 | | **Approved** | Ready for implementation | 已核准 | | **Implemented** | Code complete | 已实作 | | **Archived** | Completed or deprecated | 已归档 | ## Spec Structure | 规格结构 ```markdown # [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] ``` ### Agent SPEC Structure | Agent 规格结构(`spec-type: agent`) ```markdown # [SPEC-ID] Agent: [Role Name] <!-- spec-type: agent --> <!-- agent-id auto-referenced by feature SPECs --> ## Role Definition - **Role**: [Agent Name] - **Responsibility**: [One sentence] - **Autonomy Level**: L[1-5] (per DEC-065) ## Capability Scope **Owns:** - [Capability 1] - [Capability 2] **Does NOT own:** - [Explicit exclusion] ## Interface Contract ### Input | Message Type | Required Fields | Optional Fields | |---|---|---| | [Type] | [fields] | [fields] | ### Output | Artifact Type | Success Condition | Failure Condition | |---|---|---| | [Type] | [condition] | [condition] | ## Agent Interactions - **Upstream**: [Who calls this agent] - **Downstream**: [Who this agent calls] - **Parallel**: [Agents working alongside] ## Related Feature SPECs - [SPEC-NNN] — [This agent's role in that spec] ``` ### Scenario Formatting Rules | 场景格式规则 - 每个场景使用 `#### Scenario:`(h4 标题) - 每条 requirement 必须至少有一个场景 - 使用 **GIVEN/WHEN/THEN** 格式描述结构化行为 - 规范性需求使用 **SHALL/MUST**,建议性使用 **SHOULD** ## Delta Operations | 变更操作 修改既有 spec 时,使用 delta 区段: | Operation | Description | 说明 | |-----------|-------------|------| | `## ADDED Requirements` | New capabilities | 新增功能 | | `## MODIFIED Requirements` | Changed behavior | 修改行为 | | `## REMOVED Requirements` | Deprecated features | 移除功能 | | `## RENAMED Requirements` | Name changes | 重新命名 | ## Cross-Artifact Analysis (`/sdd analyze`) | 跨 artifact 一致性检查 The **executable face** of the acceptance-criteria-traceability standard + forward-derivation single-spine principle (XSPEC-262). Validates that every test is a faithful projection of the AC spine across specs. 本命令是 acceptance-criteria-traceability + forward-derivation single-spine 的**可执行面**,验证每个测试是否忠实投影 AC 主干。 | Signal | Meaning | Gate | |--------|---------|------| | **orphan test** | `@SPEC-NNN @AC-N` references an AC no spec defines / 引用不存在的 AC | 🔴 BLOCKING | | **uncovered** | an AC has no `@SPEC-NNN @AC-N` reference / AC 无测试引用 | report only / 仅报告 | | **not_implemented** | AC marked so in its `.ac.yaml` / `.ac.yaml` 标记 | 🔴 BLOCKING before UAT | | **cross-spec conflict** | same AC id defined in >1 spec / 同 AC id 跨多 spec | 🔴 BLOCKING | | **orphan .feature** | Gherkin `@AC-N` tag referencing a non-existent AC / @AC-N 引用不存在 | 🔴 BLOCKING | | **AC w/o scenario** | AC has no `.feature` scenario (when BDD in use) / AC 无 BDD scenario | report only / 仅报告 | | **user-guide drift** | user-guide `T-N` with no matching journey/E2E test id / 手册 T-N 无对应测试 | 🔴 BLOCKING | Coverage % uses the acceptance-criteria-traceability formula (not_implemented excluded). `--json` for CI. ``` npm run sdd:analyze -- --specs specs --tests tests [--userguide docs] [--json] ``` `--userguide <dir>` enables user-guide↔E2E drift detection (T-NNN, XSPEC-260/257). / 启用手册↔E2E drift 侦测。 **vs `/ac-coverage`**: ac-coverage = per-spec detailed AC↔test matrix;`/sdd analyze` = cross-spec/batch consistency + orphan detection(互补、不取代)。 ## Spec-vs-Code Convergence Check | 规格与实作漂移侦测(2026-07-10,spec-kit `/converge` 借鉴) **vs `/sdd analyze`**:`/sdd analyze` 问「测试有没有正确引用 AC」(引用完整性,deterministic script);convergence check 问「代码的实际行为是否真的符合 spec 描述」(语意漂移,需要读码判断,走 `sdd.flow.yaml` verify 阶段的 `spec-match-check` ai-check step)——两者互补、检查的是不同层次的问题,不重叠。 虽然定义在 7-phase 状态机的 `verify` 阶段(一次性 gate),**这个检查可以在任何时间点对已归档的 spec 独立重跑**——用于侦测 spec 归档后、code 持续演进累积出的漂移(例如后续 commit 改了行为但没回头更新 spec)。重跑时: - 落差分类:`missing`(spec 要求但没做)/`partial`(做一半)/`contradicts`(行为与描述不同)/`unrequested`(做了没被要求的事) - 严重度:`CRITICAL`(违反 spec 明确 MUST)/`HIGH`/`MEDIUM`/`LOW` - 唯读比对——只列出发现,不自动修改 spec 或代码 - 适合定期(如季度)对重要 spec 抽查,或怀疑特定 spec 已过时时针对性执行 ## Usage | 使用方式 ``` /sdd - Interactive spec creation wizard | 互动式规格建立向导 /sdd auth-flow - Create spec for specific feature | 为特定功能建立规格 /sdd review - Review existing specs | 审查现有规格 /sdd analyze - Cross-artifact consistency check | 跨 artifact 一致性检查 /sdd --sync-check - Check sync status | 检查同步状态 ``` ## Next Steps Guidance | 下一步引导 `/sdd` 完成后,AI 助手应建议: > **规格文件已建立。建议下一步 / 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](./guide.md) - Core standard: [spec-driven-development.md](../../core/spec-driven-development.md) ## AI Agent Behavior | AI 代理行为 > 完整的 AI 行为定义请参阅对应的命令文件:[`/sdd`](../../../../skills/commands/sdd.md#ai-agent-behavior--ai-代理行為) > > For complete AI agent behavior definition, see the corresponding command file: [`/sdd`](../../../../skills/commands/sdd.md#ai-agent-behavior--ai-代理行為)
Files in this package (2)
- SKILL.md 11 KB
- guide.md 12 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · AsiaOstrich/universal-dev-standards | 84 | MIT |
| wecii/sdkit | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| AsiaOstrich/universal-dev-standards | 100 | MIT |
| lichamnesia/lich-skills | 100 | MIT |
| Aquarius-mu/spec-to-ship | 90 | MIT |
Database snapshot: 13.11.2026 · package version debe6b2cfbbd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95sdd
[UDS] Create and review specification documents before writing code — spec format, states, and delta operations. Use when: a change needs a written spec first, reviewing a spec for completeness, amending an existing spec with delta sections. Not for: executing a gated SDD… - 95sdd
[UDS] 在寫程式碼之前建立並審查規格文件——規格格式、狀態與差異操作。 Use when: 某項變更需要先有書面規格、審查規格的完整性、用 delta 區段修訂既有規格。 Not for: 執行帶關卡的 SDD 生命週期——該部分已移至採用層(XSPEC-095);快速迭代用的輕量微規格——請用 uds spec 指令。 Keywords: SDD, spec, specification, design document, delta operation, spec review, 規格驅動開發, 規格文件, 變更操作, 規格審查. - 90sdd
Implements the Spec-Driven Development lifecycle (Intent, Requirements, Design, Tasks, Build) for structured feature development. Use when the user wants to scaffold a new feature spec, generate EARS requirements, create a technical design, break work into tasks, or check spec… - 100sdd
Use this skill when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow. Triggers: user says "/sdd", "spec", "specification", "task graph", "SDD", "acceptance criteria". - 100sdd-spec
Create a PRD for a new feature or change (agent PRD .md; language per LANGUAGE.md + preferences under features/). Feeds sdd-plan. Use when creating a spec or invoking /sdd-spec. - 90sdd-workflow
Guide a project with Spec-Driven Development (SDD) discipline - idea, approved spec, consistent plan, tasks, a gate that verifies approval and consent, implementation, validation, and logbook. Bilingual EN/ES. Use when the user wants to start, spec, plan, implement, or validate…