spec-driven-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABOUTME: Spec-driven development orchestrator with subcommand interface

关于我：带子命令接口的规格驱动开发编排工具

ABOUTME: Manages lifecycle: /spec.plan -> /spec.refine -> /spec.clarify -> /spec.tasks -> /spec.run

关于我：管理完整生命周期：/spec.plan -> /spec.refine -> /spec.clarify -> /spec.tasks -> /spec.run

Spec-Driven Development

规格驱动开发

Iterative feature development framework ensuring zero ambiguity before execution.

可迭代的功能开发框架，确保执行前完全没有歧义。

Quick Reference

快速参考

Command	Purpose	Input
`/spec.plan <intent>`	Create spec from "I want to build/add X"	Feature description
`/spec.refine [section]`	Improve spec with research/Gemini	Optional section focus
`/spec.clarify <response>`	Answer clarification questions	Your response
`/spec.tasks`	Break spec into executable tasks	None (uses active spec)
`/spec.run [task#]`	Execute tasks with TDD	Optional task number

命令	用途	输入
`/spec.plan <意图>`	根据"I want to build/add X"创建规格	功能描述
`/spec.refine [章节]`	通过调研/Gemini优化规格	可选的章节聚焦
`/spec.clarify <回复>`	解答澄清问题	你的回复
`/spec.tasks`	将规格拆解为可执行任务	无（使用当前激活的规格）
`/spec.run [任务编号]`	采用TDD方式执行任务	可选的任务编号

Core Principle

核心原则

Iterate until clarity: No task execution begins until ALL questions are resolved and the spec is unambiguous. Claude must be able to execute without interruptions.

迭代直至清晰: 所有问题解决、规格完全明确前，不得开始任何任务执行。Claude必须能够无中断地执行任务。

Phase 1:

/spec.plan

- Create Specification

阶段1：

/spec.plan

- 创建规格

Trigger:

/spec.plan <description>

or "I want to build/add X"

触发条件:

/spec.plan <描述>

或 "I want to build/add X"

Workflow

工作流程

Check
specs/
folder:
- If missing: Create
```
specs/
```
  and
```
specs/README.md
```
- If exists: Read
```
specs/README.md
```
  for project overrides
Detect project context:
- Scan repo for language indicators (go.mod, pyproject.toml, package.json, etc.)
- Note primary language(s) for later skill invocation
- Check
```
specs/README.md
```
  for language overrides
Generate spec file:
- Filename:
```
specs/{feature-slug}.md
```
  (kebab-case)
- Use template from
```
references/templates.md
```
Fill initial sections:
- Parse user intent into Objective
- List initial requirements (functional/non-functional)
- Mark status as
```
DRAFT
```
Generate clarifying questions:
- Identify ambiguities, edge cases, unknowns
- List as numbered questions in "Open Questions" section
- STOP and present questions to user

检查
specs/
文件夹:
- 若不存在：创建
```
specs/
```
  目录及
```
specs/README.md
```
  文件
- 若已存在：读取
```
specs/README.md
```
  中的项目自定义配置
检测项目上下文:
- 扫描代码仓库，识别语言标识文件（如go.mod、pyproject.toml、package.json等）
- 记录主要开发语言，以便后续调用对应技能
- 检查
```
specs/README.md
```
  中的语言自定义配置
生成规格文件:
- 文件名：
```
specs/{feature-slug}.md
```
  （短横线分隔格式）
- 使用
```
references/templates.md
```
  中的模板
填充初始章节:
- 将用户意图解析为目标（Objective）
- 列出初始需求（功能需求/非功能需求）
- 将状态标记为
```
DRAFT
```
  （草稿）
生成澄清问题:
- 识别歧义、边缘情况及未知点
- 在“未解决问题”章节中以编号形式列出
- 停止流程并向用户展示问题

Output

输出结果

Created: specs/feature-name.md (DRAFT)

Questions requiring clarification:
1. [Question about scope]
2. [Question about behavior]
3. [Question about constraints]

Use `/spec.clarify` to answer, or `/spec.refine` to research solutions.

已创建：specs/feature-name.md（草稿）

需要澄清的问题：
1. [关于范围的问题]
2. [关于行为的问题]
3. [关于约束的问题]

使用`/spec.clarify`回复问题，或使用`/spec.refine`调研解决方案。

Phase 2:

/spec.refine

- Research & Improve

阶段2：

/spec.refine

- 调研与优化

Trigger:

/spec.refine [section]

(e.g.,

/spec.refine solution

/spec.refine requirements

)

触发条件:

/spec.refine [章节]

（例如：

/spec.refine solution

、

/spec.refine requirements

）

Workflow

工作流程

Load active spec: Find most recent DRAFT spec in
```
specs/
```
Check project conventions:
- Read
```
specs/README.md
```
  for behavior overrides
- Load relevant language skill (auto-detected or overridden)
- Load
```
design-patterns
```
  skill for architectural guidance
Research phase:
- If user requests Gemini:
```
gemini -m gemini-3-pro-preview "Analyze spec..." .
```
- Search codebase for similar patterns
- Check skill references for best practices
Update spec:
- Fill "Technical Strategy" with concrete approach
- Add architecture decisions with rationale
- Update requirements based on findings
Re-evaluate clarity:
- Are there new questions?
- Are existing questions resolved?
- If questions remain: STOP and present them

加载当前激活的规格: 在
```
specs/
```
目录中找到最新的草稿规格
检查项目约定:
- 读取
```
specs/README.md
```
  中的行为自定义配置
- 加载相关的语言技能（自动检测或自定义配置的）
- 加载
```
design-patterns
```
  技能以获取架构指导
调研阶段:
- 若用户请求Gemini：
```
gemini -m gemini-3-pro-preview "Analyze spec..." .
```
- 搜索代码库中的相似模式
- 查阅技能参考文档获取最佳实践
更新规格:
- 在“技术策略”章节中填充具体实现方案
- 添加架构决策及理由
- 根据调研结果更新需求
重新评估清晰度:
- 是否出现新的问题？
- 现有问题是否已解决？
- 若仍有问题：停止流程并向用户展示

Gemini Integration (User-Invoked)

Gemini集成（用户触发）

bash

undefined

bash

undefined

For design validation

用于设计验证

/spec.refine --gemini "Review architecture approach"

For alternative exploration

用于探索替代方案

/spec.refine --gemini "What are alternatives to this solution?"

---

/spec.refine --gemini "What are alternatives to this solution?"

---

Phase 3:

/spec.clarify

- Answer Questions

阶段3：

/spec.clarify

- 解答问题

Trigger:

/spec.clarify <response>

/spec.clarify Q1: answer, Q2: answer

触发条件:

/spec.clarify <回复>

或

/spec.clarify Q1: answer, Q2: answer

Workflow

工作流程

Load active spec with open questions
Parse user response:
- Match answers to numbered questions
- Accept free-form responses for single questions
Update spec:
- Move answered questions to relevant sections
- Add decisions/constraints to Requirements or Strategy
- Remove resolved questions from "Open Questions"
Check for new questions:
- Does the answer introduce new ambiguities?
- If questions remain: present them
- If no questions: announce spec is ready for
  /spec.tasks

加载带有未解决问题的当前激活规格
解析用户回复:
- 将答案与编号问题匹配
- 单个问题接受自由格式回复
更新规格:
- 将已解答的问题移至相关章节
- 将决策/约束添加至需求或策略章节
- 从“未解决问题”中移除已解决的问题
检查是否有新问题:
- 回复是否引入新的歧义？
- 若仍有问题：展示问题
- 若无问题：通知规格已准备好进入
  /spec.tasks
  阶段

Example

示例

User: /spec.clarify Q1: We need OAuth2 with Google provider only. Q2: No, admin can also delete.

Updated specs/auth-system.md:
- Added OAuth2/Google to Technical Strategy
- Updated permissions: admin can delete

Remaining questions: None
Spec is ready. Use `/spec.tasks` to create task breakdown.

用户：/spec.clarify Q1: We need OAuth2 with Google provider only. Q2: No, admin can also delete.

已更新specs/auth-system.md：
- 在技术策略中添加了OAuth2/Google
- 更新权限：管理员可删除

剩余问题：无
规格已准备就绪。使用`/spec.tasks`创建任务拆解。

Phase 4:

/spec.tasks

- Task Breakdown

阶段4：

/spec.tasks

- 任务拆解

Trigger:

/spec.tasks

触发条件:

/spec.tasks

Prerequisites

前置条件

Active spec must have status
```
DRAFT
```
or
```
APPROVED
```
"Open Questions" section must be empty
If questions exist: STOP and redirect to
/spec.clarify

当前激活的规格状态必须为
```
DRAFT
```
（草稿）或
```
APPROVED
```
（已批准）
“未解决问题”章节必须为空
若存在未解决问题：停止流程并引导至
/spec.clarify

Workflow

工作流程

Validate spec readiness:

If open_questions > 0:
    ERROR: Spec has unresolved questions. Use /spec.clarify first.

Mark spec as APPROVED
Generate task file:
```
specs/{feature-slug}.tasks.md
```
Break down by component:
- Group tasks by logical component/module
- Each task = one logical unit (not TDD-granular)
- TDD practice enforced during
```
/run
```
  , not here
Add task metadata:
- Link back to spec
- Context summary
- Acceptance criteria per task
Final review:
- Present task list to user
- Ask: "Any tasks missing or need splitting?"

验证规格就绪状态:

若未解决问题数量 > 0:
    错误：规格存在未解决问题，请先使用/spec.clarify。

将规格标记为APPROVED（已批准）
生成任务文件:
```
specs/{feature-slug}.tasks.md
```
按组件拆解:
- 按逻辑组件/模块分组任务
- 每个任务对应一个逻辑单元（无需细化到TDD粒度）
- TDD实践在
```
/run
```
  阶段执行，而非此阶段
添加任务元数据:
- 关联回原规格
- 上下文摘要
- 每个任务的验收标准
最终审核:
- 向用户展示任务列表
- 询问：“是否有遗漏的任务或需要拆分的任务？”

Task Granularity

任务粒度

Tasks should be high-level logical units:

"Implement authentication middleware"
"Create user model and repository"
"Add API endpoints for user CRUD"

TDD cycle (Red-Green-Refactor) happens WITHIN each task during

/spec.run

任务应为高层逻辑单元:

“实现认证中间件”
“创建用户模型与仓库”
“添加用户CRUD的API端点”

TDD循环（红-绿-重构）在

/spec.run

阶段的每个任务内部执行。

Phase 5:

/spec.run

- Execute Tasks

阶段5：

/spec.run

- 执行任务

Trigger:

/spec.run [task#]

(e.g.,

/spec.run

/spec.run 3

)

触发条件:

/spec.run [任务编号]

（例如：

/spec.run

、

/spec.run 3

）

Prerequisites

前置条件

Task file must exist:
```
specs/{feature}.tasks.md
```
If no task file: STOP and redirect to
/spec.tasks

任务文件必须存在：
```
specs/{feature}.tasks.md
```
若无任务文件：停止流程并引导至
/spec.tasks

Workflow

工作流程

Load task file and find next unchecked task (or specified task#)
Load context:
- Read linked spec for requirements
- Read
```
specs/README.md
```
  for project overrides
- Invoke appropriate language skill
Execute with TDD (per CLAUDE.md rules):
- RED: Write failing test first
- GREEN: Minimal code to pass
- REFACTOR: Clean up
- COMMIT: After each phase
Update task file:
- Mark task as
```
[x]
```
  complete
- Add notes if needed
Continue or pause:
- If more tasks: Ask "Continue to next task?"
- If blocked: Document blocker, ask for input
- If all done: Mark spec as
```
COMPLETED
```

加载任务文件并找到下一个未勾选的任务（或指定编号的任务）
加载上下文:
- 读取关联规格中的需求
- 读取
```
specs/README.md
```
  中的项目自定义配置
- 调用合适的语言技能
采用TDD方式执行（遵循CLAUDE.md规则）:
- 红: 先编写失败的测试用例
- 绿: 编写最小化代码使测试通过
- 重构: 优化代码
- 提交: 每个阶段完成后提交代码
更新任务文件:
- 将任务标记为
```
[x]
```
  已完成
- 必要时添加备注
继续或暂停:
- 若有更多任务：询问“是否继续执行下一个任务？”
- 若遇到阻塞：记录阻塞原因，请求用户输入
- 若所有任务完成：将规格标记为
```
COMPLETED
```
  （已完成）

Execution Rules

执行规则

No interruptions: If questions arise during execution, the spec was not ready
Invoke skills: Auto-invoke
```
/python
```
,
```
/golang
```
, etc. based on file type
Respect hooks: Pre-commit hooks must pass before marking complete
Gemini review: Follow CLAUDE.md thresholds (>100 lines or >3 files)

无中断: 若执行过程中出现问题，说明规格未准备就绪
调用技能: 根据文件类型自动调用
```
/python
```
、
```
/golang
```
等技能
遵守钩子: 标记任务完成前必须通过预提交钩子检查
Gemini审核: 遵循CLAUDE.md中的阈值（超过100行代码或3个文件）

Project Configuration:

specs/README.md

项目配置：

specs/README.md

Override default behaviors per-project:

markdown

undefined

按项目自定义默认行为：

markdown

undefined

Spec Configuration

规格配置

Language Override

语言自定义

Primary: golang Secondary: python

主语言：golang 副语言：python

Conventions

约定

All specs require security section
Tasks must include rollback plan
Use feature branches: feature/{spec-name}

所有规格需包含安全章节
任务必须包含回滚计划
使用特性分支：feature/{spec-name}

Templates

模板

Use custom templates from: ./templates/

使用自定义模板路径：./templates/

Auto-invoke

自动调用

Always run /trivy before marking complete
Require /gemini-review for all specs

---

标记完成前始终运行/trivy
所有规格需执行/gemini-review

---

State Management

状态管理

Spec Status Flow

规格状态流转

DRAFT -> APPROVED -> IN_PROGRESS -> COMPLETED
          |              |
          v              v
       (questions?)   (blocked?)
          |              |
          v              v
        DRAFT      IN_PROGRESS

DRAFT（草稿） -> APPROVED（已批准） -> IN_PROGRESS（进行中） -> COMPLETED（已完成）
          |              |
          v              v
       (存在问题?)   (遇到阻塞?)
          |              |
          v              v
        DRAFT（草稿）      IN_PROGRESS（进行中）

File Structure

文件结构

project/
└── specs/
    ├── README.md           # Project overrides
    ├── auth-system.md      # Spec (APPROVED)
    ├── auth-system.tasks.md # Task breakdown
    ├── user-dashboard.md   # Spec (DRAFT)
    └── ...

项目/
└── specs/
    ├── README.md           # 项目自定义配置
    ├── auth-system.md      # 规格（已批准）
    ├── auth-system.tasks.md # 任务拆解
    ├── user-dashboard.md   # 规格（草稿）
    └── ...

Cross-Skill Integration

跨技能集成

When	Invoke
Writing `.py` files	`/python` skill
Writing `.go` files	`/golang` skill
Writing `.sh` files	`/bash` skill
Writing `Makefile`	`/make` skill
Writing `.tf` files	`/terraform` skill
Architecture decisions	`/design-patterns` skill
User-requested review	`gemini -m gemini-3-pro-preview ...`

场景	调用技能
编写 `.py` 文件时	`/python` 技能
编写 `.go` 文件时	`/golang` 技能
编写 `.sh` 文件时	`/bash` 技能
编写 `Makefile` 时	`/make` 技能
编写 `.tf` 文件时	`/terraform` 技能
架构决策时	`/design-patterns` 技能
用户请求审核时	`gemini -m gemini-3-pro-preview ...`

Session Resume

会话恢复

On context compaction or session resume:

Check
```
specs/
```
for files with status
```
IN_PROGRESS
```
Check
```
.tasks.md
```
files for unchecked items
Report: "Found in-progress spec: X with Y tasks remaining"
Ask: "Continue with
```
/spec.run
```
?"

当上下文压缩或会话恢复时：

检查
```
specs/
```
目录中是否存在状态为
```
IN_PROGRESS
```
（进行中）的文件
检查
```
.tasks.md
```
文件中是否存在未勾选的任务
报告：“发现进行中的规格：X，剩余Y个任务”
询问：“是否使用
```
/spec.run
```
继续执行？”

Error Handling

错误处理

Situation	Response
`/spec.tasks` with open questions	"Spec has N unresolved questions. Use `/spec.clarify` first."
`/spec.run` without task file	"No task file found. Use `/spec.tasks` first."
`/spec.clarify` without active spec	"No active spec. Use `/spec.plan` to create one."
Ambiguity during `/spec.run`	"Execution blocked: [issue]. Spec needs refinement. Use `/spec.refine` ."

场景	响应
`/spec.tasks` 执行时存在未解决问题	“规格存在N个未解决问题，请先使用 `/spec.clarify` 。”
`/spec.run` 执行时无任务文件	“未找到任务文件，请先使用 `/spec.tasks` 。”
`/spec.clarify` 执行时无激活规格	“无当前激活的规格，请先使用 `/spec.plan` 创建。”
`/spec.run` 执行时出现歧义	“执行阻塞：[问题描述]。规格需要优化，请使用 `/spec.refine` 。”

Templates

模板

See

references/templates.md

for:

Spec file template
Task file template
README.md template

请查看

references/templates.md

获取：

规格文件模板
任务文件模板
README.md模板

spec-driven-dev

Original

Translation

ABOUTME: Spec-driven development orchestrator with subcommand interface

关于我：带子命令接口的规格驱动开发编排工具

ABOUTME: Manages lifecycle: /spec.plan -> /spec.refine -> /spec.clarify -> /spec.tasks -> /spec.run

关于我：管理完整生命周期：/spec.plan -> /spec.refine -> /spec.clarify -> /spec.tasks -> /spec.run

Spec-Driven Development

规格驱动开发

Quick Reference

快速参考

Core Principle

核心原则

Phase 1: /spec.plan - Create Specification

阶段1：/spec.plan - 创建规格

Workflow

工作流程

Output

输出结果

Phase 2: /spec.refine - Research & Improve

阶段2：/spec.refine - 调研与优化

Workflow

工作流程

Gemini Integration (User-Invoked)

Gemini集成（用户触发）

For design validation

用于设计验证

For alternative exploration

用于探索替代方案

Phase 3: /spec.clarify - Answer Questions

阶段3：/spec.clarify - 解答问题

Workflow

工作流程

Example

示例

Phase 4: /spec.tasks - Task Breakdown

阶段4：/spec.tasks - 任务拆解

Prerequisites

前置条件

Workflow

工作流程

Task Granularity

任务粒度

Phase 5: /spec.run - Execute Tasks

阶段5：/spec.run - 执行任务

Prerequisites

前置条件

Workflow

工作流程

Execution Rules

执行规则

Project Configuration: specs/README.md

项目配置：specs/README.md

Spec Configuration

规格配置

Language Override

语言自定义

Conventions

约定

Templates

模板

Auto-invoke

自动调用

State Management

状态管理

Spec Status Flow

规格状态流转

File Structure

文件结构

Cross-Skill Integration

跨技能集成

Session Resume

会话恢复

Error Handling

错误处理

Templates

模板

Phase 1:
`/spec.plan`
- Create Specification

阶段1：
`/spec.plan`
- 创建规格

Phase 2:
`/spec.refine`
- Research & Improve

阶段2：
`/spec.refine`
- 调研与优化

Phase 3:
`/spec.clarify`
- Answer Questions

阶段3：
`/spec.clarify`
- 解答问题

Phase 4:
`/spec.tasks`
- Task Breakdown

阶段4：
`/spec.tasks`
- 任务拆解

Phase 5:
`/spec.run`
- Execute Tasks

阶段5：
`/spec.run`
- 执行任务

Project Configuration:
`specs/README.md`

项目配置：
`specs/README.md`