spec-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-Driven Development

规格驱动开发（Spec-Driven Development）

Overview

概述

Think First, Prompt Second. Enforces a structured 5-phase cycle that prevents vibe coding: Analyze -> Plan -> Ask -> Execute -> Review. Every implementation starts from a spec, respects existing codebase patterns, and delivers small, reviewable, committed phases.

先思考，再编码。 强制遵循结构化的5阶段周期，避免凭感觉编码：Analyze（分析）-> Plan（规划）-> Ask（询问）-> Execute（执行）-> Review（审查）。所有实现均从规格说明出发，遵循现有代码库模式，交付可审查、已提交的小型阶段性成果。

When to Use

适用场景

Feature implementation from a spec or requirements doc
Multi-phase work spanning multiple files or architectural layers
Any task where "just start coding" leads to drift, over-scoping, or pattern violations

Do NOT use for: single-line fixes, typos, config changes, pure research, or tasks with very specific line-level instructions. If the user asks a direct question or gives a specific fix, respond directly — don't invoke this workflow.

根据规格说明或需求文档实现功能
跨多个文件或架构层的多阶段工作
任何“直接开始编码”会导致偏离需求、范围过度或违反模式的任务

不适用场景： 单行修复、拼写错误、配置变更、纯研究，或有非常具体行级指令的任务。如果用户提出直接问题或给出具体修复方案，请直接响应——不要启用此工作流。

Required Input

必要输入

You need a spec — not loose tickets or vague descriptions. Minimum viable spec:

What to build (feature description, acceptance criteria)
Why it matters (context, user value)
Constraints (tech stack, patterns to follow, performance requirements)

If the user provides a loose request, ask them to clarify into a spec before proceeding.

你需要一份规格说明（spec）——而非模糊的工单或描述。最低要求的规格说明应包含：

要构建什么（功能描述、验收标准）
为什么重要（背景、用户价值）
约束条件（技术栈、需遵循的模式、性能要求）

如果用户提供的请求模糊不清，请要求他们明确为规格说明后再继续。

The 5-Phase Workflow

5阶段工作流

dot

digraph sdd {
  rankdir=TB;
  node [shape=box];

  Analyze [label="1. Analyze"];
  Plan [label="2. Plan"];
  Ask [label="3. Ask"];
  Execute [label="4. Execute"];
  Review [label="5. Review"];
  Stop [label="STOP\nwait for approval" shape=doublecircle];
  Commit [label="Commit phase" shape=diamond];
  MorePhases [label="More phases?" shape=diamond];
  NeedsReanalysis [label="Scope changed?" shape=diamond];
  NeedsReplan [label="Plan still valid?" shape=diamond];

  Analyze -> Plan;
  Plan -> Stop;
  Stop -> Ask [label="approved"];
  Ask -> NeedsReanalysis;
  NeedsReanalysis -> Analyze [label="yes — new requirements"];
  NeedsReanalysis -> Execute [label="no"];
  Execute -> Commit;
  Commit -> Review;
  Review -> NeedsReplan;
  NeedsReplan -> Plan [label="no — replan remaining"];
  NeedsReplan -> MorePhases [label="yes"];
  MorePhases -> Execute [label="next phase"];
  MorePhases -> "Done" [label="all phases complete"];
}

dot

digraph sdd {
  rankdir=TB;
  node [shape=box];

  Analyze [label="1. Analyze"];
  Plan [label="2. Plan"];
  Ask [label="3. Ask"];
  Execute [label="4. Execute"];
  Review [label="5. Review"];
  Stop [label="STOP\nwait for approval" shape=doublecircle];
  Commit [label="Commit phase" shape=diamond];
  MorePhases [label="More phases?" shape=diamond];
  NeedsReanalysis [label="Scope changed?" shape=diamond];
  NeedsReplan [label="Plan still valid?" shape=diamond];

  Analyze -> Plan;
  Plan -> Stop;
  Stop -> Ask [label="approved"];
  Ask -> NeedsReanalysis;
  NeedsReanalysis -> Analyze [label="yes — new requirements"];
  NeedsReanalysis -> Execute [label="no"];
  Execute -> Commit;
  Commit -> Review;
  Review -> NeedsReplan;
  NeedsReplan -> Plan [label="no — replan remaining"];
  NeedsReplan -> MorePhases [label="yes"];
  MorePhases -> Execute [label="next phase"];
  MorePhases -> "Done" [label="all phases complete"];
}

Phase 1 — Analyze

阶段1 — 分析（Analyze）

Goal: Understand the spec AND the codebase before touching anything.

Understand the spec — read it fully, restate in your own words, list acceptance criteria (explicit and implied), note gaps
Analyze the codebase — map architecture, directory structure, key modules, conventions (naming, error handling, test patterns), tech stack
Find similar implementations — search for existing code doing something similar. Note file paths + line numbers for anything to reuse or follow. Check if the feature partially exists already. This is critical — search before writing.
Identify integration points — where does this connect to existing code? APIs, schemas, shared state, internal/external dependencies
Assess risks — what could break? Performance, security, breaking changes, missing test coverage

Output — Analysis Summary:

undefined

目标： 在编写任何代码前，理解规格说明和代码库。

理解规格说明——完整阅读，用自己的话重述，列出验收标准（明确和隐含的），标注空白点
分析代码库——梳理架构、目录结构、核心模块、约定（命名、错误处理、测试模式）、技术栈
查找类似实现——搜索现有代码中功能类似的部分。标注可复用或需遵循的文件路径+行号。检查功能是否已部分实现。这一步至关重要——先搜索再编写。
识别集成点——该功能与现有代码的连接点在哪里？API、 schema、共享状态、内部/外部依赖
评估风险——哪些部分可能出问题？性能、安全、破坏性变更、测试覆盖缺失

输出——分析摘要：

undefined

Spec Understanding

规格说明理解

[Restated spec + acceptance criteria list]

[重述的规格说明 + 验收标准列表]

Codebase Findings

代码库发现

Architecture: [overview]
Conventions: [naming, patterns, structure]
Tech stack: [frameworks, tools]

架构：[概述]
约定：[命名、模式、结构]
技术栈：[框架、工具]

Similar Implementations Found

找到的类似实现

[file:line] — [what it does, relevance]

[文件:行号] — [功能、相关性]

Integration Points

集成点

[module/file] — [how the feature connects]

[模块/文件] — [功能连接方式]

Risks & Concerns

风险与关注点

[risk] — [severity, mitigation]

[风险] — [严重程度、缓解方案]

Open Questions

待澄清问题

[questions needing clarification]


**Rules:**
- DO NOT write implementation code
- DO NOT suggest solutions — that's for the planning phase
- DO search thoroughly — find existing patterns before anything else
- DO note file paths with line numbers

---

[需要澄清的问题]


**规则：**
- 不要编写实现代码
- 不要建议解决方案——这是规划阶段的任务
- 务必彻底搜索——先找到现有模式再做其他
- 务必标注文件路径和行号

---

Phase 2 — Plan

阶段2 — 规划（Plan）

Goal: Break work into small, ordered, committable phases.

Define phases — each must change <200 lines, be independently committable (no broken state), build on previous phases, have a testable outcome. Order by dependency: foundational first, integration last.
Detail each phase — scope (one sentence), files to modify/create (exact paths), patterns to follow (reference file:line from analysis), tests to write/update, pre-written commit message
Identify dependencies — which phases block which? Any parallelizable?

Keep the plan concise. One-line scope per phase. No prose.

Output — Implementation Plan:

undefined

目标： 将工作拆分为小型、有序、可提交的阶段。

定义阶段——每个阶段的代码变更不得超过200行，可独立提交（无损坏状态），基于前一阶段构建，有可测试的成果。按依赖关系排序：基础优先，集成最后。
细化每个阶段——范围（一句话）、需修改/创建的文件（精确路径）、需遵循的模式（引用分析阶段的文件:行号）、需编写/更新的测试、预写的提交信息
识别依赖关系——哪些阶段相互阻塞？是否有可并行的阶段？

保持规划简洁。 每个阶段一句话描述范围，不要冗长文字。

输出——实现规划：

undefined

Overview

概述

[1-2 sentence summary. Total phases: N]

[1-2句话总结。总阶段数：N]

Phase 1: [Short Title]

阶段1: [简短标题]

Scope: [one sentence]
Files: modify [path], create [path]
Pattern: [path:line] — [follow this for...]
Tests: [what to test]
Commit:
```
feat(scope): description (phase 1/N)
```

范围：[一句话]
文件：修改 [路径]，创建 [路径]
模式：[路径:行号] — [需遵循的内容]
测试：[测试内容]
提交：
```
feat(scope): description (phase 1/N)
```

Phase 2: [Short Title]

阶段2: [简短标题]

...

Dependencies

依赖关系

Phase 2 depends on Phase 1
Phases 3-4 can run in parallel


**Rules:**
- DO NOT write implementation code — only describe what to do
- DO reference existing patterns by file path + line
- DO keep phases small — >200 lines means split
- DO pre-write commit messages (subject line only)
- Plan must cover the full spec — no acceptance criteria left unaddressed
- If the analysis has open questions, flag them — don't plan around assumptions

**STOP and wait for user approval before executing.**

---

阶段2依赖阶段1
阶段3-4可并行


**规则：**
- 不要编写实现代码——仅描述要做的事情
- 务必通过文件路径+行号引用现有模式
- 务必保持阶段小型——超过200行则拆分
- 务必预写提交信息（仅主题行）
- 规划必须覆盖完整的规格说明——不要遗漏任何验收标准
- 如果分析阶段有待澄清问题，需标注——不要基于假设做规划

**停止并等待用户批准后再执行。**

---

Phase 3 — Ask

阶段3 — 询问（Ask）

No special process — this is a natural conversation pause.

Surface:

Spec ambiguities or contradictions
Architectural decisions with multiple valid approaches (present options)
Missing acceptance criteria
Edge cases the spec doesn't cover

Rule: Never assume. If uncertain, ask. If nothing is ambiguous, state "No open questions" and proceed.

Loop-back rule: If the user's answers reveal new requirements or significantly change scope, go back to Phase 1 — Analyze to re-assess the codebase with the new context. If answers only affect the plan (not the analysis), go back to Phase 2 — Plan to adjust.

无特殊流程——这是自然的对话暂停环节。

需提出：

规格说明中的歧义或矛盾点
有多种可行方案的架构决策（给出选项）
缺失的验收标准
规格说明未覆盖的边缘情况

规则：永远不要假设。如有不确定，务必询问。 如果没有歧义，说明“无待澄清问题”后继续。

循环规则： 如果用户的回答揭示了新需求或显著改变了范围，回到阶段1 — 分析，结合新背景重新评估代码库。如果回答仅影响规划（不影响分析），回到阶段2 — 规划进行调整。

Phase 4 — Execute

阶段4 — 执行（Execute）

Goal: Implement one phase at a time, following existing patterns.

Review the phase — re-read scope, files, pattern references. Check referenced pattern files before writing
Implement — follow existing codebase patterns (naming, structure, error handling, style). Before writing new code, verify no existing utility already does it. Write only what the phase requires. Write tests as specified
Self-check — does implementation match phase scope? Did I follow referenced patterns? Tests passing? Only planned files changed? Unintended side effects?

Commit — subject-line only:

feat(<scope>): <description> (phase N/M)

Rules:

ONE phase only — do not bleed into the next phase
Follow existing patterns — read referenced files first, match their style
Minimal changes — if it's not in the phase scope, don't touch it
No refactoring — unless the plan explicitly includes it
Search before writing — check if a utility/helper already exists
If you discover something outside phase scope, note it but don't do it — flag for a future phase

目标： 一次实现一个阶段，遵循现有模式。

回顾阶段内容——重新阅读范围、文件、模式引用。编写前检查引用的模式文件
实现——遵循现有代码库模式（命名、结构、错误处理、风格）。编写新代码前，确认没有现有工具类已实现该功能。仅编写该阶段所需的代码。按要求编写测试
自我检查——实现是否符合阶段范围？是否遵循了引用的模式？测试是否通过？仅修改了规划中的文件？有无意外副作用？

提交——仅主题行：

feat(<scope>): <description> (phase N/M)

规则：

仅处理一个阶段——不要涉及下一阶段的内容
遵循现有模式——先阅读引用文件，匹配其风格
最小变更——如果不在阶段范围内，不要修改
不要重构——除非规划中明确包含
先搜索再编写——检查是否已有可用的工具类/辅助函数
如果发现阶段范围外的内容，仅做标注不要处理——标记为未来阶段的任务

Phase 5 — Review

阶段5 — 审查（Review）

Goal: Verify the phase against spec acceptance criteria.

Spec compliance — does this phase meet its acceptance criteria? Does implementation match spec intent, not just the letter?
Code quality — bugs, edge cases (empty inputs, boundaries, error states), error handling, type safety, naming consistency
Architecture — follows referenced patterns? No drift from plan? Code in right layer/module? Dependencies flowing correctly?
Test coverage — tests cover new behavior? Edge cases tested? Tests follow existing patterns? Tests are meaningful?
Scope — changes stayed within phase scope? Files match the plan? No bonus refactors?

Output — Phase Review:

undefined

目标： 根据规格说明的验收标准验证阶段成果。

规格合规性——该阶段是否满足其验收标准？实现是否符合规格说明的意图，而非仅字面意思？
代码质量——bug、边缘情况（空输入、边界值、错误状态）、错误处理、类型安全、命名一致性
架构——是否遵循了引用的模式？是否偏离了规划？代码是否放在正确的层/模块？依赖关系是否正确？
测试覆盖——测试是否覆盖了新行为？是否测试了边缘情况？测试是否遵循现有模式？测试是否有意义？
范围——变更是否在阶段范围内？文件是否与规划一致？有无额外重构？

输出——阶段审查报告：

undefined

Status: PASS | ISSUES FOUND

状态：通过（PASS）| 发现问题（ISSUES FOUND）

Spec Compliance

规格合规性

[criterion]: PASS/FAIL — [details]

[标准]: 通过/未通过 — [详情]

Issues (if any)

问题（如有）

[severity]: [description] — [file:line] — [fix]

[严重程度]: [描述] — [文件:行号] — [修复方案]

Scope: [OK | drift details]

范围: [正常 | 偏离详情]

Recommendation: PROCEED | FIX [list]

建议：继续（PROCEED）| 修复 [列表]


**Rules:**
- Be specific — cite file paths and line numbers
- Prioritize — critical first, notes last
- Don't nitpick style that matches codebase conventions
- Review against the plan, not personal preference
- Flag any scope creep as an issue
- Critical issues must be fixed before proceeding

**Loop-back rule:** If review reveals architectural issues or plan assumptions that were wrong, go back to **Phase 2 — Plan** to re-plan the remaining phases. Don't force a broken plan — adjust it.

**Multi-agent review (on request):** If the user asks for thorough review, assess from three perspectives sequentially — architecture (patterns, separation of concerns, API design), code quality (bugs, edge cases, test coverage), and security (auth, input validation, injection, OWASP top 10). Synthesize into a single report.

---


**规则：**
- 务必具体——标注文件路径和行号
- 按优先级排序——先严重问题，后备注
- 不要挑剔与代码库约定一致的风格
- 基于规划而非个人偏好进行审查
- 标记任何范围蔓延为问题
- 严重问题必须修复后才能继续

**循环规则：** 如果审查发现架构问题或规划假设错误，回到**阶段2 — 规划**重新规划剩余阶段。不要强行执行有问题的规划——进行调整。

**多Agent审查（按需）：** 如果用户要求全面审查，依次从三个角度评估——架构（模式、关注点分离、API设计）、代码质量（bug、边缘情况、测试覆盖）、安全（认证、输入验证、注入、OWASP十大风险）。将结果整合为一份报告。

---

Anti-Patterns This Skill Prevents

该技能预防的反模式

Anti-Pattern	Prevention
Vibe coding	Mandatory Analyze + Plan before any code
Over-scoping	Phase boundaries enforce <200 lines, minimal changes
Pattern violations	Analyzer searches for existing patterns first
Reinventing the wheel	Analyzer finds similar implementations to reuse
Big-bang commits	Phase-by-phase commits enforced
Spec drift	Reviewer checks against spec acceptance criteria
Assuming requirements	Ask phase surfaces ambiguities before coding

反模式	预防措施
凭感觉编码（Vibe coding）	强制要求在编码前完成分析+规划
范围过度	阶段边界强制变更不超过200行，最小化变更
模式违反	分析阶段先搜索现有模式
重复造轮子	分析阶段查找类似实现以便复用
大爆炸式提交	强制分阶段提交
规格偏离	审查阶段对照规格说明验收标准检查
假设需求	询问阶段在编码前揭示歧义

Red Flags — STOP and Recheck

危险信号——停止并重新检查

Writing code before completing analysis
Skipping the plan approval step
Changing files not listed in the current phase
Committing more than one phase's work
Not searching for existing patterns before writing new code
Assuming what the user wants instead of asking

在完成分析前编写代码
跳过规划批准步骤
修改当前阶段未列出的文件
提交多个阶段的工作
编写新代码前未搜索现有模式
假设用户需求而不询问

Failure Diagnostics

故障诊断

Symptom	Cause	Fix
Doesn't match spec	Rushed Phase 1	Redo analysis, restate spec
Inconsistent patterns	Skipped pattern search	Run analysis again
Too many files changed	Phases too large	Re-split into smaller phases
User surprised by approach	Skipped approval	Always stop for plan review
Major issues in review	Phase scope too large	Smaller phases

症状	原因	修复方案
与规格说明不符	阶段1仓促完成	重新进行分析，重述规格说明
模式不一致	跳过了模式搜索	重新执行分析阶段
修改文件过多	阶段划分过大	拆分为更小的阶段
用户对实现方式感到意外	跳过了批准步骤	始终等待规划审查通过
审查中发现重大问题	阶段范围过大	划分更小的阶段