spec-driven-planning

规范驱动规划技能

目的

以以下两种模式之一指导功能规划：

• Quick 模式 — 使用单个 docx/features/[NN-name]/plan.md，其中包含小而具体的任务。不使用 EARS，也不使用 RGR。适用于个人开发、耗时 ≤3 天且无需合规审查或交接的工作。基于 superpowers 编写计划的模式。
• Full 模式 — 使用三个文件（requirements.md EARS + design.md + tasks.md），包含三个审批关卡，并在后续阶段强制执行 TDD。适用于团队工作、持续数周的工作、合规/审计，或需要利益相关者评审的工作。

该技能会选择一种模式（有歧义时会询问），然后运行匹配的操作流程。

激活触发条件

在以下情况下激活此技能：

• 用户说“创建新功能”“规划一项功能”“我需要构建 [X]”
• 用户提到“需求”“规格说明”“规格”“架构”“技术设计”
• 用户使用 /dev-workflow:spec 命令（任意子参数）

---

模式选择（始终先执行）

开始编写任何内容之前，先决定使用 Quick 还是 Full 模式。

符合以下所有条件时，自动选择 Quick 模式：

• 预估工作量 ≤3 天或 ≤8 个任务
• 由个人开发；无需利益相关者审批
• 无合规、审计或监管要求
• 无重大架构决策（无需权衡“X 还是 Y？”）
• 用户的请求已清楚说明需求
• 无跨团队交接
• 用户说了“quick”“lightweight”“simple plan”，或使用 /dev-workflow:spec quick

符合以下任意条件时，自动选择 Full 模式：

• 工作量 >1 周或 >15 个任务
• 除工程师外，利益相关者也必须审批范围
• 需要合规/审计/监管可追溯性
• 架构选择会带来长期影响
• 需求不明确，需要进一步收集
• 可能涉及多位开发人员或交接
• 用户说了“full spec”“EARS”“requirements doc”，或使用 /dev-workflow:spec full

其他情况均视为有歧义

上述阈值刻意留有间隔：工作量为 4-7 天、任务数为 9-15 个，或只符合部分信号的情况，都处于中间区域。如果不完全符合 Quick 模式的所有条件，也不符合 Full 模式的任意条件，则按定义，该功能存在歧义。请询问用户。

有歧义？使用以下选项询问一次：

This feature could go either way. Pick a planning mode:

1. Quick — single plan.md, no EARS, no RGR (recommended for solo, ≤3 days)
2. Full — 3-file spec with EARS + TDD enforcement (recommended for team, >1 week, compliance)

Default if you don't pick: Quick.

宣布所选模式：

“使用 [Quick/Full] 模式。[根据上述信号给出一句理由。]”

然后运行下方对应的操作流程。

---

Quick 模式操作流程

输出： docx/features/[NN-feature-name]/plan.md（单个文件）

步骤 1：创建功能目录

1. 运行 ls docx/features/，查找下一个 NN 编号
2. 运行 mkdir -p docx/features/[NN-feature-name]
3. 阅读 dev-workflow/templates/plan.md
4. 写入 docx/features/[NN-feature-name]/plan.md，将 [Feature Name] 替换为实际名称

步骤 2：填写计划

受众假设：对该代码库毫无了解的工程师。内容务必精确。

必需章节：

• 目标 — 一句话
• 架构 — 2-3 句话，说明各部分放在哪里以及原因
• 技术栈 — 关键库/文件
• 范围之外 — 确保范围合理
• 任务 — 细小具体（每步 2-5 分钟），并包含：
  • 文件： 精确路径（创建/修改，并注明行号范围）
  • 步骤： 使用编号，每步只做一项操作。提供完整代码，不要写“在此添加验证”。包含精确的验证命令及预期输出。最后以提交步骤结束。

粒度规则：如果某一步耗时超过 5 分钟，就拆分该步骤。

步骤 3：一个审批关卡

“Quick 计划已保存到 docx/features/[NN-feature-name]/plan.md。请审阅并批准后再继续实施。准备就绪后运行 /dev-workflow:spec execute。”

到此为止。无需 EARS、设计方案对比或 RGR。实施由 spec-driven-implementation 处理（该流程会自动检测 plan.md 并以 Quick 执行模式运行）。

出现以下情况时，Quick 模式就不合适……

• 编写需要非工程师审批的需求 → 切换到 Full 模式
• 比较 2 种或更多架构方案 → 切换到 Full 模式
• 列出 >15 个任务 → 切换到 Full 模式
• 需要从需求到任务再到测试的可追溯性 → 切换到 Full 模式

升级方式请参阅本技能底部的“升级路径”。

---

完整模式操作手册

三个阶段，三个审批关卡。信号表明应使用完整模式时，请采用此流程。

阶段 1：功能创建

目标： 建立功能结构和占位文件

流程：

1. 从用户输入中解析功能名称
2. 使用 Bash 工具检查现有功能：ls docx/features/
3. 确定功能目录的下一个编号（NN）
4. 使用 Bash 工具创建目录：mkdir -p docx/features/[NN-feature-name]
5. 将模板从插件复制到功能目录：
   • 使用 Read 工具：dev-workflow/templates/requirements.md
   • 使用 Write 工具：docx/features/[NN-feature-name]/requirements.md（将 [Feature Name] 替换为实际名称）
   • 使用 Read 工具：dev-workflow/templates/design.md
   • 使用 Write 工具：docx/features/[NN-feature-name]/design.md（将 [Feature Name] 替换为实际名称）
   • 使用 Read 工具：dev-workflow/templates/tasks.md
   • 使用 Write 工具：docx/features/[NN-feature-name]/tasks.md（将 [Feature Name] 替换为实际名称）

输出：

Created feature: docx/features/[NN-feature-name]/
- requirements.md (from template)
- design.md (from template)
- tasks.md (from template)

Next step: Define requirements using EARS format

用户确认：

“功能结构已创建。准备好定义需求了吗？”

---

阶段 2：需求定义（EARS 格式）

目标： 使用 EARS 方法制定清晰、可测试的需求

范围分解检查（首先执行）：

在收集需求之前，先检查请求。如果请求描述了多个独立子系统（例如，“身份验证 + 计费 + 管理员控制面板”），请停止，并先将其分解为多个独立功能，再细化其中任何一个。不要把需求收集问题浪费在本应拆分为三个功能的事项上。

🗣 说：“此请求涵盖 [N] 个独立子系统。我会先为每个子系统创建单独的功能，再收集需求。”

禁止占位符规则：

需求及其后续计划不得包含：

• “TBD” / “待确定” / “以后再定义”
• “添加适当的 X” / “按需处理错误” / “按要求验证”
• “与 [其他内容] 类似” / 未提供具体内容的“见上文”
• 没有对象的含糊动词：“更新”“改进”“修复”“增强”
• 需求文本中的“等等”或结尾省略号
• 对未定义名称的引用（不存在的 REQ-ID、尚未指定的模块） 如果无法具体描述某项需求，请询问用户。不要写占位内容。

头脑风暴集成（可选）：

• 如果用户只有粗略想法，且需求尚不明确，可使用 Skill 工具调用：dev-workflow:brainstorming
• 帮助明确要构建的内容和范围之外的内容
• 通过协作式提问探索不同的功能范围
• 确定必需项和锦上添花项

如何启用：

Use Skill tool: Skill(skill: "dev-workflow:brainstorming")

EARS 格式说明：

EARS（需求语法简易方法）提供了五种模板，用于编写明确无歧义的需求：

1. 普遍性需求 - 始终成立

   • 模板：“系统 SHALL [需求]”
   • 示例：“系统 SHALL 在处理前验证所有用户输入”

2. 事件驱动需求 - 由事件触发

   • 模板：“WHEN [触发条件] THEN 系统 SHALL [响应]”
   • 示例：“WHEN 用户点击提交 THEN 系统 SHALL 验证表单数据”

3. 状态驱动需求 - 在特定状态期间生效

   • 模板：“WHILE [状态] 系统 SHALL [需求]”
   • 示例：“WHILE 正在处理付款，系统 SHALL 显示加载指示器”

4. 条件需求 - 基于条件

   • 模板：“IF [条件] THEN 系统 SHALL [需求]”
   • 示例：“IF 用户角色是管理员 THEN 系统 SHALL 显示管理面板”

5. 可选需求 - 功能开关

   • 模板：“WHERE [包含的功能] 系统 SHALL [需求]”
   • 示例：“WHERE 高级订阅处于启用状态，系统 SHALL 启用高级分析”

研究流程（收集需求之前）：

在开始询问需求之前，先通过研究收集背景信息：

1. 先前成果研究

   • 使用 WebSearch 查找类似功能/产品
   • 查询：“[功能类型] best practices 2025”
   • 查询：“[功能类型] common requirements”

2. 技术文档

   • 使用 WebFetch 获取相关技术文档、API 或标准
   • 获取竞争产品/类似产品的文档

3. API 研究（如适用）

   • 使用 Bash 和 curl 探索 API 端点
   • 获取 API 文档和架构

4. 记录研究发现

   • 在 requirements.md 的“## Research Summary”下总结关键见解
   • 记录发现的模式、反模式和行业标准

🗣 说：“在定义需求之前，我先研究一下类似的实现。”

---

系统化提问方法：

向用户提出以下问题以收集需求：

1. 核心功能

   • “此功能的主要用途是什么？”
   • “它解决了什么问题？”

2. 事件驱动需求

   • “哪些用户操作会触发此功能？”
   • “涉及哪些系统事件？”

3. 状态驱动需求

   • “是否存在不同的状态或模式？”
   • “每种状态下应该发生什么？”

4. 条件需求

   • “针对不同用户/角色，是否存在不同的行为？”
   • “哪些条件会影响功能？”

5. 性能需求

   • “是否有响应时间要求？”
   • “预期负载/规模是多少？”

6. 安全需求

   • “哪些数据需要保护？”
   • “谁应该有访问权限？”

7. 错误处理

   • “可能出现哪些问题？”
   • “应该如何处理错误？”

8. 边界情况

   • “边界条件是什么？”
   • “在极端情况下会发生什么？”

最佳实践：

• 使用“SHALL”表示强制性需求
• 具体且可衡量（避免使用“快速”，改用“在 2 秒内”）
• 每条陈述只包含一项需求
• 避免使用含糊的词语（如“适当”“合理”“用户友好”）
• 使用主动语态

需求 ID 和可追溯性：

• 为每项需求分配唯一 ID，并使用统一前缀（例如 REQ-001）。
• 所有需求类型（功能性 + 非功能性）使用连续编号。
• 直接在每条需求中记录 ID，以便后续任务引用。
• 添加简短的可追溯性说明，指出任务/设计将如何映射回这些 ID。

输出格式： 更新 docx/features/[NN-feature-name]/requirements.md，包含：

• 概述部分
• 功能需求（按 EARS 类型整理）
• 非功能需求（性能、安全性、可用性）
• 约束
• 验收标准（复选框）
• 范围外事项

用户确认：

“需求已完成。准备进入设计阶段吗？”

---

阶段 3：技术设计

目标： 制定全面的技术设计，并确定架构决策

研究流程（设计前）：

在提出架构方案之前，先研究解决方案：

1. 架构研究

   • 使用 WebSearch 搜索：“[technology] architecture patterns 2025”
   • 使用 WebSearch 搜索：“[problem domain] implementation approaches”

2. 库/框架研究

   • 使用 WebFetch 查阅潜在库的文档
   • 比较类似项目采用的方案

3. API 研究（如适用）

   • 使用 WebFetch 查阅外部 API 文档
   • 使用 Bash 和 curl 测试 API 端点
   • 了解集成要求和限制

4. 记录研究结果

   • 在 design.md 中添加“## 技术研究”部分
   • 包含来源链接和关键见解

🗣 说：“在提出架构选项之前，我先研究一下技术方案。”

---

流程：

1. 集思广益式设计探索

   • 使用 Skill 工具调用：dev-workflow:brainstorming，开展协作式设计探索
   • 探索 2-3 种不同的架构方案
   • 讨论每种方案的权衡

   启用方式：

   Use Skill tool: Skill(skill: "dev-workflow:brainstorming")
   

复杂设计的 UltraThink： 在提出技术方案之前，遇到以下情况时，启用深度思考：

• 架构涉及多个服务或复杂的数据流
• 各方案之间的权衡并不明显
• 设计会影响安全性、性能或可扩展性
• 需求看起来相互矛盾或不完整

🗣 说：“这项设计需要深入思考。在提出方案之前，我先用 ultrathink 深入思考架构的基本原则。”

UltraThink 期间，请思考：

• 我们解决的是正确的问题吗？
• 我们有哪些假设可能是错误的？
• 规模扩大后，什么可能会出问题？
• 能满足需求的最简单架构是什么？
• 每种方案有哪些隐性成本？
• 如果从头开始，我们会做出哪些不同的选择？

UltraThink 之后： 提出方案时，明确说明架构权衡和可扩展性方面的考量。

2. 方案比较 展示各个选项及其权衡：

   选项 A：[方案名称]

   • 优点：[优势]
   • 缺点：[劣势]
   • 复杂度：低/中/高
   • 时间线：[估算]

   选项 B：[方案名称]

   • 优点：[优势]
   • 缺点：[劣势]
   • 复杂度：低/中/高
   • 时间线：[估算]

3. 建议

   • 说明推荐的方案
   • 给出清晰的理由
   • 解释为什么它最符合需求

4. 设计文档结构 创建全面的 design.md，涵盖：

   架构概述

   • 此功能如何融入系统
   • 高层组件图（ASCII 艺术图）

   组件结构

   • 列出组件及其职责
   • 定义组件之间的依赖关系
   • 指定公共接口

   数据流

   • 逐步说明数据流转过程
   • 展示数据流的图示

   API 契约

   • 输入/输出架构
   • 错误响应
   • 请求/响应示例

   错误处理

   • 错误场景和处理策略
   • 回退行为

   安全考量

   • 身份验证/授权
   • 输入验证
   • 数据保护

   性能考量

   • 优化策略
   • 缓存方案
   • 数据库索引需求

   测试策略

   • 单元测试范围
   • 集成测试场景
   • 端到端测试工作流

审批关卡：

“设计已完成。准备好拆分任务了吗？”

等待用户明确批准后再继续。

---

后续步骤

Quick 模式之后（已保存 plan.md）：

运行 /dev-workflow:spec execute。实现技能会自动检测 plan.md 并运行 Quick 执行：遵循步骤、运行验证命令并提交。不强制执行 RGR。

Full 模式之后（design.md 已获批准）：

运行 /dev-workflow:spec tasks，然后运行 /dev-workflow:spec execute。实现技能会检测到 tasks.md，并执行 Full 模式：每个任务都遵循 RED-GREEN-REFACTOR，追溯到需求 ID，并通过质量关卡。

两种模式都与 dev-workflow:review、dev-workflow:git-workflow 和 dev-workflow:test-driven-development 集成（最后一项在 Full 模式下必需，在 Quick 模式下可选）。

---

升级路径：Quick → Full

如果 Quick 功能超出原计划（范围扩大、利益相关者加入、出现架构决策）：

1. 阅读现有的 docx/features/[NN-name]/plan.md
2. 根据该文件创建三个 Full 模式文件：
   • requirements.md — 从任务中提取目标和隐含需求；改写为 EARS 格式；分配 REQ-### ID
   • design.md — 提取架构和技术栈；通过访谈用户补充“考虑过的替代方案”
   • tasks.md — 将任务重新拆分为 RED/GREEN/REFACTOR，并关联需求 ID
3. 将 plan.md 重命名为 plan.archived.md，以便追溯
4. 从 Full 手册的第 2 阶段（需求）或第 3 阶段（设计）继续

不支持降级（Full → Quick）。EARS 需求一旦建立，丢弃它们就是浪费——只需继续使用 Full 模式。

---

示例

示例 A：Quick 模式（自动选择）

用户：“在报表页面添加一个 CSV 导出按钮”

助手：

Signals: solo, ~1 day, no compliance, no architectural decision → Quick mode.

Created docx/features/03-csv-export/plan.md with 4 tasks.
Review and approve, then run /dev-workflow:spec execute.

示例 B：Full 模式（自动选择）

用户：“为 Web 和移动端添加用户身份验证，且必须符合 SOC 2 要求”

助手：

Signals: multi-platform, compliance required, JWT vs session decision → Full mode.

Created docx/features/04-user-authentication/{requirements,design,tasks}.md.
Phase 1 complete. Phase 2: I'll elicit requirements in EARS format.

1. What authentication methods should be supported?
2. What's the session lifetime requirement?
[...]

示例 C：有歧义（询问用户）

用户：“添加一个通知系统”

助手：

Scope is ambiguous between Quick and Full. Pick one:

1. Quick — single plan.md, no EARS, no RGR (≤3 days, solo)
2. Full — 3-file spec with EARS + TDD (>1 week, team, compliance)

Default if you don't pick: Quick.

---

注意事项

• 阶段之间始终请求明确批准
• 严格使用 EARS 格式编写需求
• 聚焦于“是什么”和“怎么做”，而不是“执行”
• 推荐方案前，先探索多个架构选项