spec-driven-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-Driven Development

You are operating in spec-driven development mode. This project uses a 6-phase pipeline with human approval gates between each phase.

你正运行在 spec-driven development模式 下。本项目采用包含6个阶段的流水线，每个阶段之间设置人工审批门。

Pipeline

流水线

Explore → [APPROVE] → Requirements → [APPROVE] → Design → [APPROVE] → Task Plan → [APPROVE] → Implementation → [APPROVE] → Review → [APPROVE] → Done

Each phase has a dedicated prompt template. Read the template for the current phase before generating any output.

Explore → [APPROVE] → Requirements → [APPROVE] → Design → [APPROVE] → Task Plan → [APPROVE] → Implementation → [APPROVE] → Review → [APPROVE] → Done

每个阶段都有专用的提示词模板。生成任何输出前，请先阅读当前阶段对应的模板。

Quick Reference

快速参考

Action	Command
Check state	`sh ./scripts/pipeline.sh status`
Start feature	`sh ./scripts/pipeline.sh init [--branch] <name>`
Register output	`sh ./scripts/pipeline.sh artifact [path]`
Advance phase	`sh ./scripts/pipeline.sh approve` (only after user says "approve")
Mark task done	`sh ./scripts/pipeline.sh task T-N` (implementation phase only)
Check docs	`sh ./scripts/pipeline.sh docs-check`
Multi-feature	Add `--feature <name>` before any command

Hard rules: check status first · never skip phases · never auto-approve · save artifacts to

.spec/features/<feature>/

· max 3 revisions then ask user

Config:

.spec/config.yaml

→

context

(all phases),

rules.<phase>

(per phase),

test_skill

test_reference

docs_dir

auto_branch

branch_prefix

Phase flow: read template → generate artifact → save →

artifact

→ present → wait for "approve" →

approve

操作	命令
检查状态	`sh ./scripts/pipeline.sh status`
启动新功能开发	`sh ./scripts/pipeline.sh init [--branch] <name>`
注册产出物	`sh ./scripts/pipeline.sh artifact [path]`
进入下一阶段	`sh ./scripts/pipeline.sh approve` （仅在用户回复“approve”后执行）
标记任务完成	`sh ./scripts/pipeline.sh task T-N` （仅实现阶段可用）
检查文档	`sh ./scripts/pipeline.sh docs-check`
多功能并行开发	在任意命令前添加 `--feature <name>` 参数

硬性规则： 优先检查状态 · 绝不跳过阶段 · 绝不自动审批 · 产出物保存到

.spec/features/<feature>/

目录 · 最多提交3次修订，之后需询问用户意见

配置项：

.spec/config.yaml

→

context

（全阶段生效）、

rules.<phase>

（对应阶段生效）、

test_skill

、

test_reference

、

docs_dir

、

auto_branch

、

branch_prefix

阶段流程： 读取模板 → 生成产出物 → 保存 → 执行

artifact

命令注册 → 提交给用户 → 等待“approve”回复 → 执行

approve

命令进入下一阶段

Phases

阶段说明


./templates/explore.md
./templates/requirements.md
./templates/design.md
./templates/task-plan.md
./templates/implementation.md
./templates/review.md

#	Phase	Template	Produces
1	Explore	`./templates/explore.md`	Exploration & research document
2	Requirements	`./templates/requirements.md`	Formal requirements document
3	Design	`./templates/design.md`	Architecture & design document
4	Task Plan	`./templates/task-plan.md`	TDD implementation plan
5	Implementation	`./templates/implementation.md`	Implementation report
6	Review	`./templates/review.md`	Code review document


./templates/explore.md
./templates/requirements.md
./templates/design.md
./templates/task-plan.md
./templates/implementation.md
./templates/review.md

#	阶段	模板路径	产出物
1	探索	`./templates/explore.md`	探索与调研文档
2	需求	`./templates/requirements.md`	正式需求文档
3	设计	`./templates/design.md`	架构与设计文档
4	任务规划	`./templates/task-plan.md`	TDD实现计划
5	实现	`./templates/implementation.md`	实现报告
6	评审	`./templates/review.md`	代码评审文档

State Machine

状态机

The pipeline state is managed via a shell script. Use these commands:

undefined

流水线状态通过shell脚本管理，可使用以下命令：

undefined

Check current phase and progress

查看当前阶段和进度

sh ./scripts/pipeline.sh status

Start a new feature pipeline

启动新的功能开发流水线

sh ./scripts/pipeline.sh init <feature-name>

Start with auto-branch (creates git branch <prefix><name>)

启动时自动创建分支（创建格式为 <prefix><name> 的git分支）

sh ./scripts/pipeline.sh init --branch <feature-name>

Register the artifact you generated for the current phase

注册当前阶段生成的产出物

sh ./scripts/pipeline.sh artifact [path]

Advance to the next phase (only after user says "approve")

进入下一阶段（仅在用户回复“approve”后执行）

sh ./scripts/pipeline.sh approve

View revision history for current or specified phase

查看当前或指定阶段的修订历史

sh ./scripts/pipeline.sh revisions [phase]

View all features and their status

查看所有功能及其状态

sh ./scripts/pipeline.sh history

Check project documentation status

检查项目文档状态

sh ./scripts/pipeline.sh docs-check

Mark an implementation task as completed (enables resume)

标记实现任务已完成（支持后续恢复进度）

sh ./scripts/pipeline.sh task <T-N>

undefined

sh ./scripts/pipeline.sh task <T-N>

undefined

Parallel Pipelines

并行流水线

When multiple features are active simultaneously, add

--feature <name>

before the command:

sh ./scripts/pipeline.sh --feature auth-flow status
sh ./scripts/pipeline.sh --feature payment approve

Without the flag, the pipeline auto-detects the active feature. If more than one is active, it will error and prompt you to use

--feature

当同时有多个功能处于开发状态时，在命令前添加

--feature <name>

参数：

sh ./scripts/pipeline.sh --feature auth-flow status
sh ./scripts/pipeline.sh --feature payment approve

如果不添加该参数，流水线会自动检测当前活跃的功能。如果存在多个活跃功能，会报错并提示你使用

--feature

参数指定。

Project Configuration

项目配置

If the file

.spec/config.yaml

exists in the project root, read it before starting any phase.

context
— project-wide background (tech stack, conventions, repo structure). Treat as extra context for ALL phases.
rules.<phase>
— phase-specific rules that supplement (not replace) the template instructions.
test_skill
(optional) — name of an installed skill for test generation. If present, delegate test specification (Design §2.8) and test task creation (Implementation) to this skill. Pass Correctness Properties and Coverage Matrix as input.
test_reference
(optional) — glob or file paths pointing to representative test files. If present, use these as the style reference for all generated tests. If absent, auto-discover adjacent tests.
docs_dir
(optional) — directory for project documentation, default:
```
.spec
```
. The agent reads documentation from this directory for project context and writes generated docs here.
doc_freshness_days
(optional) — number of days after which a generated doc is considered stale, default:
```
30
```
. Used by
```
pipeline.sh docs-check
```
to flag outdated documentation.

rules.docs
(optional) — rules for documentation generation, analogous to

rules.explore

etc. Example:

"Skip FILES.md — no file storage"

"Always include Mermaid diagrams in ARCHITECTURE.md"

auto_branch
(optional) — boolean, default:
```
false
```
. When
```
true
```
,
```
pipeline.sh init
```
automatically creates a git branch
```
<branch_prefix><feature-name>
```
without needing
```
--branch
```
. Use
```
--no-branch
```
to override.
branch_prefix
(optional) — string, default:
```
feature/
```
. Prefix for auto-created branches. Examples:
```
bug/
```
,
```
fix/
```
,
```
hotfix/
```
, or empty string for no prefix.

Phase-specific rule keys:

rules.explore

rules.requirements

rules.design

rules.task-plan

rules.implementation

rules.review

rules.docs

Injection order: context → phase rules → template instructions.

If the file does not exist, skip this step.

如果项目根目录存在

.spec/config.yaml

文件，启动任何阶段前请先读取该文件：

context
— 项目全局背景信息（技术栈、规范、仓库结构），所有阶段都可以将其作为额外上下文参考。
rules.<phase>
— 对应阶段的专属规则，作为模板指令的补充（而非替代）。
test_skill
（可选）— 已安装的用于生成测试的skill名称。如果存在，将测试规范制定（设计阶段§2.8）和测试任务创建（实现阶段）委托给该skill，传入正确性属性和覆盖矩阵作为输入。
test_reference
（可选）— 指向代表性测试文件的glob匹配规则或文件路径。如果存在，将这些文件作为所有生成测试的风格参考；如果不存在，自动查找相邻的测试文件。
docs_dir
（可选）— 项目文档存放目录，默认值：
```
.spec
```
。Agent从该目录读取文档获取项目上下文，同时将生成的文档写入该目录。
doc_freshness_days
（可选）— 生成文档的有效天数，超过该天数即视为过时，默认值：
```
30
```
。
```
pipeline.sh docs-check
```
命令会基于该配置标记过时文档。

rules.docs
（可选）— 文档生成规则，与

rules.explore

等规则类似。示例：

"Skip FILES.md — 不涉及文件存储"

、

"ARCHITECTURE.md中必须包含Mermaid流程图"

。

auto_branch
（可选）— 布尔值，默认值：
```
false
```
。设为
```
true
```
时，
```
pipeline.sh init
```
命令会自动创建格式为
```
<branch_prefix><feature-name>
```
的git分支，无需额外添加
```
--branch
```
参数，可以使用
```
--no-branch
```
参数覆盖该配置。
branch_prefix
（可选）— 字符串，默认值：
```
feature/
```
。自动创建分支的前缀，示例值：
```
bug/
```
、
```
fix/
```
、
```
hotfix/
```
，为空字符串则不添加前缀。

阶段专属规则的键名：

rules.explore

、

rules.requirements

、

rules.design

、

rules.task-plan

、

rules.implementation

、

rules.review

、

rules.docs

。

配置注入顺序：全局上下文 → 阶段规则 → 模板指令

如果配置文件不存在，跳过该步骤。

Pre-flight Checklist

启动前检查清单

Before starting any pipeline work, follow these steps in order:

Check pipeline state: run
```
pipeline.sh status
```
.
- If exactly one active pipeline exists → resume from the current phase. Do NOT run
```
init
```
  again.
- If no active pipeline → proceed to step 2.
- If multiple active pipelines → ask the user which feature to work on, then use
```
--feature <name>
```
  with all subsequent commands.
Read project config: check if
```
.spec/config.yaml
```
exists.
- If yes → read it, apply
```
context
```
  to all phases, note
```
rules.*
```
  for each phase.
- If no → proceed without config (defaults apply).
Check documentation: run
```
pipeline.sh docs-check
```
.
- Docs directory missing → suggest: "Project documentation (<docs_dir>/) not found. I can generate it to better understand your codebase. Say 'generate docs' or 'skip'." This is a soft suggestion — the pipeline works without documentation.
- Docs exist, stale files found → suggest: "Some docs are outdated (<file>: <N> days old). Regenerate before starting? Say 'update docs' or 'skip'." If user agrees, read
```
./templates/docs-maintenance.md
```
  for the Stale doc regeneration workflow.
- Docs exist, all fresh → use as supplementary context for ALL phases. Read
```
<docs_dir>/README.md
```
  for the documentation map.
Start pipeline: run
```
pipeline.sh init <feature-name>
```
.

For documentation generation, staleness checks, and regeneration workflows, read

./templates/docs-maintenance.md

开始任何流水线工作前，按顺序执行以下步骤：

检查流水线状态：运行
```
pipeline.sh status
```
命令。
- 如果仅存在一个活跃流水线 → 从当前阶段恢复工作，不要再次执行
```
init
```
  命令。
- 如果没有活跃流水线 → 继续执行步骤2。
- 如果存在多个活跃流水线 → 询问用户需要开发哪个功能，后续所有命令都添加
```
--feature <name>
```
  参数。
读取项目配置：检查是否存在
```
.spec/config.yaml
```
文件。
- 如果存在 → 读取文件，将
```
context
```
  应用到所有阶段，记录每个阶段的
```
rules.*
```
  规则。
- 如果不存在 → 无需配置，使用默认值继续。
检查文档状态：运行
```
pipeline.sh docs-check
```
命令。
- 文档目录不存在 → 建议用户："未找到项目文档（<docs_dir>/）。我可以生成文档以更好地理解代码库，回复「generate docs」生成或「skip」跳过。" 这是软建议，没有文档流水线也可以正常运行。
- 文档存在，但存在过时文件 → 建议用户："部分文档已过时（<file>：已过期<N>天），是否需要在开始前更新？回复「update docs」更新或「skip」跳过。" 如果用户同意更新，读取
```
./templates/docs-maintenance.md
```
  中的过时文档重生成工作流。
- 文档存在且全部有效 → 作为所有阶段的补充上下文，读取
```
<docs_dir>/README.md
```
  查看文档导航。
启动流水线：运行
```
pipeline.sh init <feature-name>
```
命令。

关于文档生成、有效性检查、重生成工作流的详情，可查阅

./templates/docs-maintenance.md

。

When to Use This Pipeline

流水线适用场景

Use the pipeline for:

New features ("add user authentication", "implement search")
Significant changes to existing features (new behavior, API changes, schema migrations)
Bug fixes that require investigation and design (root cause unknown, multiple components affected)

Do NOT use the pipeline for:

Trivial changes: typo fixes, config tweaks, single-field additions, comment updates
Dependency updates with no code changes
Pure refactors with no behavioral change (unless they are large and risky)

For trivial changes, just make the change directly — no pipeline needed. The skill is designed for work that benefits from structured thinking before coding.

适合使用流水线的场景：

新功能开发（"添加用户认证"、"实现搜索功能"）
现有功能的重大变更（新行为、API变更、schema迁移）
需要调研和设计的Bug修复（根因未知、涉及多个组件）

不适合使用流水线的场景：

琐碎变更：修复错别字、调整配置、添加单个字段、更新注释
无代码变更的依赖更新
无行为变更的纯重构（除非是规模大、风险高的重构）

对于琐碎变更，直接修改即可，不需要走流水线。该skill专为编码前需要结构化思考的工作设计。

Fast-track mode

快速通道模式

For bug fixes with a known reproduction or other small, well-understood changes:

All 6 phases still apply — do not skip phases.
Each phase produces a minimal artifact: 1-paragraph exploration, 1–2 requirements, focused design (CPs only for the bug scenario), 4–5 tasks (RED→GREEN→CODE→VERIFY→GATE), brief implementation report, short review.
Each template contains a "Fast-track mode" section with phase-specific minimums. Follow those rules when fast-track applies.

When to activate: The agent activates fast-track when the user describes a bug with a known reproduction step, or a small, scoped change where investigation is unnecessary. At the start, announce: "Using fast-track mode — all 6 phases, minimal artifacts." If the user says "full pipeline", switch to the standard (non-abbreviated) flow.

Scope: This pipeline is designed for a single project or monorepo. It is not intended for features that span multiple independent repositories. Within a monorepo, use one

.spec/

directory at the repository root.

针对有明确复现步骤的Bug修复或者其他范围清晰的小型变更：

6个阶段仍然全部生效，不可跳过。
每个阶段只需要生成最小化产出物：1段探索说明、1-2条需求、聚焦的设计（仅包含Bug场景的正确性属性）、4-5个任务（红→绿→编码→验证→关卡）、简短的实现报告、精简的评审内容。
每个模板都包含"快速通道模式"章节，说明了对应阶段的最小产出要求，启用快速通道时遵循这些规则。

激活时机： 当用户描述的Bug有明确复现步骤，或者是不需要调研的小型限定范围变更时，Agent自动激活快速通道模式，启动时告知用户："启用快速通道模式 — 保留全部6个阶段，仅生成最小化产出物。" 如果用户回复"full pipeline"，切换为标准（非精简）流程。

适用范围： 该流水线专为单个项目或单仓（monorepo） 设计，不适合跨多个独立仓库的功能开发。在单仓中，在仓库根目录放置一个

.spec/

目录即可。

Rules

规则

MUST check status first. Run
```
pipeline.sh status
```
before doing anything. Never generate phase output without checking status. If multiple active pipelines exist, use
```
--feature <name>
```
with all commands.
Never skip phases. Follow the order: explore → requirements → design → task-plan → implementation → review.
Never auto-approve. Wait for the user to explicitly say "approve" or equivalent.
Read the template. Before generating output for a phase, read the corresponding template file.
Save artifacts. Save generated documents to
```
.spec/features/<feature>/
```
and register them with
```
pipeline.sh artifact
```
.
Each phase produces one artifact that becomes input for the next phase.
Artifacts are cumulative. Each phase reads all prior artifacts.
Revision limit. If the user rejects the same artifact 3 times in a row, stop generating and ask: "We've gone through 3 revisions — could you clarify what's missing or what direction you'd prefer?" Do not continue revising without explicit guidance. The review phase's internal fix cycle has a separate limit: maximum 3 fix cycles (see
```
templates/review.md
```
Iteration Workflow). After 3 fix cycles without
```
PASS
```
, escalate to user.
Surface uncertainty. If you are unsure about intent, scope, or technical approach — say so explicitly. State the assumption you would make and ask the user to confirm or correct it. Never silently assume.
Write in the user's language. Detect the user's language from their first message and use it for ALL pipeline artifacts and conversational replies. What stays in English:
- Formal grammar keywords:
```
WHEN
```
  ,
```
SHALL
```
  ,
```
the system
```
- Requirement IDs:
```
REQ-X.Y
```
- Task IDs:
```
T-N
```
- Instruction keywords:
```
CRITICAL
```
  ,
```
IMPORTANT
```
  ,
```
NOTE
```
  ,
```
DO NOT
```
  ,
```
GOAL
```
- Correctness Property format:
```
Property N
```
  ,
```
Category
```
  ,
```
For all
```
  ,
```
Validates
```
- Code identifiers, file paths, shell commands, Mermaid node labels
- Documentation in
```
<docs_dir>/
```
  (
```
.spec/
```
  ) — always English (see
```
templates/docs/README.md
```
  )
Everything else — prose, section headers, descriptions, interview questions, explanations — is written in the user's language.

必须优先检查状态。 执行任何操作前先运行
```
pipeline.sh status
```
命令，未检查状态绝不生成阶段产出。如果存在多个活跃流水线，所有命令都要添加
```
--feature <name>
```
参数。
绝不跳过阶段。 严格遵循顺序：探索 → 需求 → 设计 → 任务规划 → 实现 → 评审。
绝不自动审批。 必须等待用户明确回复"approve"或同等含义的确认内容。
必须读取模板。 生成某阶段的产出前，先读取对应阶段的模板文件。
必须保存产出物。 将生成的文档保存到
```
.spec/features/<feature>/
```
目录，并通过
```
pipeline.sh artifact
```
命令注册。
每个阶段生成一个产出物，作为下一阶段的输入。
产出物是累积的。 每个阶段都要读取之前所有阶段的产出物。
修订次数限制。 如果用户连续3次驳回同一个产出物，停止生成，询问用户："我们已经提交了3次修订，可以请你明确说明缺少的内容或者你期望的方向吗？" 没有明确指导的情况下不要继续修订。评审阶段的内部修复周期有单独限制：最多3次修复循环（详见
```
templates/review.md
```
迭代工作流），3次修复后仍未通过
```
PASS
```
，升级给用户处理。
明确表达不确定性。 如果你对用户意图、范围、技术方案有疑问，要明确说明，陈述你会采用的假设，并请用户确认或纠正，绝不要默认假设。
使用用户的语言编写内容。 从用户的第一条消息识别其使用的语言，所有流水线产出物和对话回复都使用该语言。以下内容保留英文：
- 正式语法关键词：
```
WHEN
```
  、
```
SHALL
```
  、
```
the system
```
- 需求ID：
```
REQ-X.Y
```
- 任务ID：
```
T-N
```
- 指令关键词：
```
CRITICAL
```
  、
```
IMPORTANT
```
  、
```
NOTE
```
  、
```
DO NOT
```
  、
```
GOAL
```
- 正确性属性格式：
```
Property N
```
  、
```
Category
```
  、
```
For all
```
  、
```
Validates
```
- 代码标识符、文件路径、shell命令、Mermaid节点标签
- ```
<docs_dir>/
```
  （
```
.spec/
```
  ）目录下的文档 — 始终使用英文（详见
```
templates/docs/README.md
```
  ）
其他所有内容 — 正文、章节标题、描述、调研问题、解释说明 — 都使用用户的语言编写。

Error Recovery

错误恢复

Revising an artifact: Overwrite the file, re-register with
```
pipeline.sh artifact
```
, and present the updated version to the user. The previous version is automatically saved as a revision in the feature’s
```
revisions/
```
directory. Use
```
pipeline.sh revisions
```
to view past revisions.

修订产出物： 覆盖原文件，重新执行
```
pipeline.sh artifact
```
注册，将更新后的版本提交给用户。旧版本会自动作为修订版本保存到对应功能的
```
revisions/
```
目录下，可使用
```
pipeline.sh revisions
```
查看历史修订。

Documentation Maintenance

文档维护

After the pipeline reaches

phase=done

, read

./templates/docs-maintenance.md

§ Documentation Maintenance to check if project documentation needs updating.

After the pipeline reaches

phase=done

, read

./templates/docs-maintenance.md

§ 文档维护部分，检查是否需要更新项目文档。

Quick Start (for the agent)

快速入门（面向Agent）

When the user says something like "I want to add feature X":

Follow the Pre-flight Checklist (status → config → docs-check → init)
Read
```
./templates/explore.md
```
— investigate the problem space (use
```
.spec/
```
docs as context if available)
Generate the exploration document → save to
```
.spec/features/<feature>/explore.md
```
Run
```
pipeline.sh artifact
```
Present to user → wait for "approve"
Run
```
pipeline.sh approve
```
→ phase advances to requirements
Read
```
./templates/requirements.md
```
→ follow its interview process
Generate the requirements document → save, register artifact, present, wait for approve
Repeat for design phase
Read
```
./templates/task-plan.md
```
→ generate TDD implementation plan (no code yet)
Save, register artifact, present, wait for approve
Read
```
./templates/implementation.md
```
→ execute the task plan (write tests, write code, mark tasks done)
Save implementation report, register artifact, present, wait for approve
Read
```
./templates/review.md
```
→ review the written code against all prior artifacts
If findings exist → agent fixes code using TDD fix plan (exploration test → fix → re-test) → re-reviews → repeats until verdict is
```
PASS
```
(max 3 fix cycles; escalates to user if not resolved)
Present final review document (verdict
```
PASS
```
) → wait for approve
After review is approved →
```
pipeline.sh approve
```
→ pipeline complete
Check if documentation needs updating (see Documentation Maintenance)

当用户提到类似"我想要添加功能X"的需求时：

遵循启动前检查清单（检查状态 → 读取配置 → 检查文档 → 初始化）
读取
```
./templates/explore.md
```
— 调研问题领域（如果有
```
.spec/
```
目录下的文档可以作为上下文参考）
生成探索文档 → 保存到
```
.spec/features/<feature>/explore.md
```
运行
```
pipeline.sh artifact
```
命令
提交给用户 → 等待"approve"回复
运行
```
pipeline.sh approve
```
命令 → 进入需求阶段
读取
```
./templates/requirements.md
```
→ 遵循其调研流程
生成需求文档 → 保存、注册产出物、提交给用户、等待审批
设计阶段重复上述流程
读取
```
./templates/task-plan.md
```
→ 生成TDD实现计划（暂不编写代码）
保存、注册产出物、提交给用户、等待审批
读取
```
./templates/implementation.md
```
→ 执行任务计划（编写测试、编写代码、标记任务完成）
保存实现报告、注册产出物、提交给用户、等待审批
读取
```
./templates/review.md
```
→ 对照之前所有阶段的产出物评审编写的代码
如果发现问题 → Agent使用TDD修复方案修复代码（探索测试 → 修复 → 重测） → 重新评审 → 重复直到评审结果为
```
PASS
```
（最多3次修复循环，未解决则升级给用户）
提交最终评审文档（结果为
```
PASS
```
） → 等待审批
评审通过后 → 运行
```
pipeline.sh approve
```
命令 → 流水线完成
检查是否需要更新文档（详见文档维护部分）