spec-driven-propose

你正在帮助用户创建新的规范驱动变更提案。

在提案阶段，不要提出后续问题，也不要要求确认。 根据用户请求、项目上下文和现有规范，尽可能制定最完善的提案。将任何尚未解决的歧义记录在 questions.md 中，供 /spec-driven-apply 在开始实现前提出。

此技能的命令

如果不记得此技能使用的确切命令，请先在此处查阅，再运行。不要猜测。

propose: node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>

先决条件

.spec-driven/ 目录必须位于项目根目录。继续之前，请验证：

ls .spec-driven/

如果验证失败，说明项目尚未初始化。请先运行 /spec-driven-init。

步骤

1. 确定变更名称 — 如果用户已提供 kebab-case 名称，则使用该名称。否则，根据请求和提案范围自行拟定简短的 kebab-case 名称，不要停下来询问。

2. 阅读项目上下文和现有规范 — 生成任何内容之前，请先阅读以下内容：

   • .spec-driven/config.yaml — 使用 context 指导内容；将 rules 视为具有约束力的规则；留意适用于此变更涉及文件的 fileMatch 条目
   • .spec-driven/specs/INDEX.md — 用于识别所有现有规范文件及其范围
   • INDEX.md 中引用的、此变更可能涉及的每个规范文件 — 写入 MODIFIED 或 ADDED 条目之前，先通读其内容以了解现有要求

3. 搭建变更结构 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
   

   这会创建 .spec-driven/changes/<name>/，并生成预置的工件模板。

4. 填写 proposal.md — 编写清晰、简洁的提案，涵盖：

   • 内容：此变更的作用（可观察到的行为，而非实现方式）
   • 原因：动机和背景
   • 范围：纳入范围的内容，以及明确排除的内容
   • 保持不变的行为：列出不得被破坏的现有行为，即与此变更相邻或可能受其影响的行为。如果确实没有任何行为面临风险，则留空。

5. 填写 design.md — 编写技术方案：

   • 方案：高层次说明如何实现
   • 关键决策：重要选择及其理由
   • 已考虑的替代方案：说明哪些方案未采用，以及原因

6. 填写 specs/ 差异文件 — 查看项目的 .spec-driven/specs/ 目录结构。对于此变更涉及的每个规范文件，在 .spec-driven/changes/<name>/specs/ 下创建对应文件，并镜像相同的相对路径（例如：specs/auth/login.md → changes/<name>/specs/auth/login.md）。如果变更新增了规范领域，则创建归档后应出现在 .spec-driven/specs/ 下的相应相对路径。

   精确镜像主规范路径。例如， .spec-driven/specs/skills/planning.md 对应 .spec-driven/changes/<name>/specs/skills/planning.md。

   以下规范示例是格式标准：

   ---
   mapping:
     implementation:
       - path/to/implementation.ts
     tests:
       - test/path/to/test.ts
   ---
   
   ## ADDED Requirements
   
   ### Requirement: new-capability
   The system MUST provide <observable behavior>.
   
   #### Scenario: success
   - GIVEN <precondition>
   - WHEN <action>
   - THEN <result>
   
   ## MODIFIED Requirements
   
   ### Requirement: existing-capability
   Previously: The system MUST <old behavior>.
   The system MUST <new behavior>.
   
   ## REMOVED Requirements
   
   ### Requirement: old-capability
   Reason: This behavior is removed because <reason>.
   

   每个差异文件均使用 ADDED/MODIFIED/REMOVED 章节，并遵循标准格式：

   • YAML frontmatter：当可根据仓库上下文确定相关文件时，包含 mapping.implementation 和 mapping.tests
   • ### Requirement: <name> 标题和 RFC 2119 关键词（MUST/SHOULD/MAY）
   • 适用时使用 #### Scenario: 区块（GIVEN/WHEN/THEN）
   • ADDED：新要求；MODIFIED：变更后的要求（包含 Previously: 说明）；REMOVED：已移除的要求（说明原因）
   • 省略不适用的章节，不要留下空章节
   • 如果此变更不影响任何可观察的规范内容，则将 changes/<name>/specs/ 留空——不要创建会破坏差异规范格式的纯说明文件
   • 如果无法确定相关实现文件或测试文件的路径，不要编造映射路径；将映射留待 /spec-driven-apply 补全

7. 填写 tasks.md — 使用以下规范结构编写具体的实现清单：

   # Tasks: <change-name>
   
   ## Implementation
   - [ ] Describe the first atomic implementation task
   - [ ] Describe the second atomic implementation task
   
   ## Testing
   
   - [ ] Run `npm run lint` — lint or validation task
   - [ ] Run `npm test` — unit test task
   
   ## Verification
   - [ ] Verify implementation matches proposal scope
   

   每项任务都使用 - [ ] 复选框。任务应能独立完成。

   ## Testing 部分必须满足以下验证关键词要求：

   • 至少有一项任务必须包含 lint/validation 关键词：lint、validate、 validation、typecheck、type-check 或 build
   • 至少有一项任务必须包含单元测试关键词：unit test 或 unit tests
   • 两项任务都必须在反引号中写明明确可运行的命令，或使用已知的运行器（npm、pnpm、yarn、bun、node、bash、sh、pytest、jest、vitest、go、cargo、make、uv、poetry）
   • 改述这些关键词（例如用“运行测试”代替“运行单元测试”）会导致 verify 失败

   如果无法根据仓库上下文有把握地确定相关命令，请在 questions.md 中添加一个开放问题，而不是猜测。不要添加“更新规格”任务——specs/ 目录中包含规格产物。

8. 填写 questions.md — 记录所有开放问题或歧义：

   • 对每个不明确之处（动机、范围边界、技术方案等），在 ## Open 下添加一条：

     - [ ] Q: <具体问题>
       Context: <其重要性／受其影响的内容>
     

   • 如果一切都很明确，请将 ## Open 留空，并添加注记：``
   • 不要在任何产物中使用 [NEEDS CLARIFICATION] 行内标记——questions.md 是存放所有开放问题的唯一位置

9. 验证产物格式 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   

   在提交提案前，将其作为最终的结构和格式检查。

   • 如果报告缺少产物、delta 规格部分／标题格式错误，或有可安全修复的未填写占位符，请立即修复并重新运行 verify
   • 如果 verify 仍报告无法有把握修复的格式或结构问题，请停止并向用户报告该问题
   • 如果剩余的唯一错误是 questions.md 中存在开放问题，请将其视为提案阶段的预期情况，并向用户明确说明这些问题

10. 交接 — 向用户展示这五个文件，并概述范围、关键决策和任何开放问题。写完提案后，不要要求用户确认。如果 questions.md 中有开放问题，请明确说明 /spec-driven-apply 会将其作为实施阻碍提出，并要求用户在开始编码前明确解决；/spec-driven-modify 只能作为可选的修订途径提及。

规则

• 不要实施任何内容——此阶段仅进行规划
• 任务应当是原子化且可验证的
• 不要提出后续问题，也不要要求在提案阶段设置确认关卡
• proposal.md 描述做什么以及为什么；design.md 描述如何做；tasks.md 是检查清单；questions.md 用于记录开放问题
• 在 questions.md 中记录歧义——不要猜测不明确的要求，也不要使用 [NEEDS CLARIFICATION] 行内标记
• 写完产物后，不要添加提案后的确认关卡
• 提案交接时允许存在开放问题；将其留在 questions.md 中，以便 /spec-driven-apply 提出并阻止实施
• 完成前，重新运行 verify，直到所有可修复的格式问题都已修复；如果仍有任何非问题类错误，请向用户报告
• 规格与代码的映射应放在 frontmatter 中，而不是需求描述中