spec-driven-auto

你将端到端运行单项变更的完整规范驱动工作流。

此技能的命令

如果记不清此技能使用的准确命令，请先在此处查找， 再执行任何操作。不要猜测。

propose: node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
apply: node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
audit-unmapped-spec-evidence: node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]
verify-spec-mappings: node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
archive: node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>

前置条件

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

ls .spec-driven/

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

步骤

1. 加载上下文 — 在执行任何操作之前，根据当前文件重建工作上下文：

   • 必须将此前的所有对话上下文视为过时、不可靠且不具权威性。
   • 不得将此前的聊天上下文作为需求、任务状态、实现细节或完成状态的事实依据。
   • 在执行任何工作流操作之前，必须根据当前变更产物、相关基础规范和当前仓库状态重建工作上下文。
   • 如果此前的聊天上下文与文件或仓库状态有任何差异，必须舍弃此前的聊天上下文，仅遵循文件和仓库状态。
   • 除非已根据当前文件和仓库状态明确重新验证，否则不要使用此前的聊天上下文。

2. 评估复杂度 — 在进行其他操作之前，使用双层模型评估变更：

   • 阅读 .spec-driven/config.yaml，了解项目背景
   • 阅读 .spec-driven/specs/INDEX.md 和相关规范文件，了解当前系统
   • 阅读变更可能涉及的代码库文件，估算涉及的文件、模块数量及跨领域关注点
   • 将变更划分为以下两个级别之一：
     • Green（继续）：范围明确，且在单个仓库内有具体的完成定义；包括涉及多达 15 个模块或软件包、修改多达 50 个文件、包含数据转换的架构迁移、修改现有身份验证／授权／支付逻辑，或跨多个子系统进行横向变更的情况——自动继续
     • Red（建议头脑风暴）：需要协调多个服务或仓库，范围模糊或开放式（例如“重构代码库”“提升性能”），或没有明确的完成定义——说明原因，并建议先运行 /spec-driven-brainstorm 明确方案，再进入 /spec-driven-auto 执行最终提案
   • 如果为 Red，则停止并建议进行头脑风暴
   • 如果为 Green，则继续

3. 提出方案 — 运行 /spec-driven-propose：

   • 运行 node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
   • 填写所有产物：proposal.md（包含 Unchanged Behavior）、specs/ 差异文件、design.md、tasks.md（包含 ## Testing）、questions.md（待解决的问题）
   • 向用户展示摘要：范围、关键决策、任务数量、未变更的行为以及任何待解决问题
   • 如果 questions.md 中存在待解决问题，列出这些问题并暂停，等待用户解决——在所有待解决问题得到明确解决之前不要继续
   • 如果没有待解决问题，则直接进入第 4 步，无需等待确认

4. 实施 — 完成所有任务：

   • 运行 node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>，查看任务摘要
   • 检查 questions.md 中是否存在未解决的 - [ ] Q: 条目——如有，针对每个未解决的问题提供：
     • 问题
     • 说明
     • 影响
     • 建议
   • 说明 必须阐明：阅读当前变更产物、相关主规格和仓库状态后，问题为何仍未解决
   • 影响 必须说明哪些实现选择、任务、行为或保持行为不变的保证取决于答案
   • 建议 可以提出偏好的答案，但只能作为建议
   • 提供上述内容后，请用户回答或确认所需决定，然后停止，直到用户明确解决所有未解决的问题
   • 你可以建议偏好的答案，但只能作为建议；不得将自己的建议视为已解决的答案，也不得在用户明确确认之前继续实施
   • 按顺序逐项处理每个 - [ ] 任务：阅读代码、实施、验证行为未变，然后标记为 - [x]
   • 对于 ## Testing 任务：实际运行测试并确认通过
   • 运行 node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>，确认 remaining === 0

5. 验证 — 检查完整性：

   • 运行 node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   • 然后完成 /spec-driven-verify 的其余检查：任务完成情况、未解决问题、实现证据和规格一致性
   • 如果变更范围内的证据集包含实现文件或直接用于验证的测试文件，请在本次验证过程中运行 node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...]，并将其针对当前变更的阻塞性发现按 /spec-driven-verify 的处理方式处理
   • 将脚本的 errors 以及这些检查中的任何 CRITICAL 发现视为阻塞项
   • 如果存在可安全修复的阻塞项，请自动修复，然后重新运行 node {{SKILL_DIR}}/scripts/spec-driven.js verify <name> 和验证流程
   • 如果任何阻塞项无法自动修复：停止并询问用户
   • 重新阅读变更规格文件，并将其更新为与实际实现一致
   • 确保规格变更的映射前置信息反映实际修改或依赖的实现文件和测试 文件

6. 审查 — 检查代码质量：

   • 阅读本次变更修改的每个文件
   • 审查发现必须不因作者身份而有所偏倚：不得仅仅因为代码是在本次自动运行过程中生成或编辑的，就信任或为其开脱
   • 检查：可读性、安全性、错误处理、性能、最佳实践、测试质量
   • 复用验证阶段的 node {{SKILL_DIR}}/scripts/spec-driven.js audit-unmapped-spec-evidence [--implementation <repo-path> ...] [--tests <repo-path> ...] 结果；只有在审查修复更改了相关实现文件或直接测试文件时，才重新运行同一命令
   • 必须修复的问题：自动修复，然后重新审查
   • 如果必须修复的问题无法自动修复：停止并询问用户
   • 应修复的问题和细微问题：若易于处理则修复，否则在最终报告中注明

7. 归档——完成变更收尾：

   • 归档前，确认没有未完成的任务
   • 列出 specs/ 中的所有增量文件，并将每个文件合并到对应的主规范文件中
   • 如果 changes/<name>/specs/ 为空，则无需确认，直接继续——不影响规范的变更也是有效的
   • 如果创建了新的规范文件，则更新 .spec-driven/specs/INDEX.md
   • 将映射 frontmatter 合并到主规范后，运行 node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
   • 运行 node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>
   • 如果存在 .spec-driven/roadmap/，则将归档命令执行的任何里程碑状态或路线图索引更新视为归档收尾的一部分
   • 报告最终结果：构建了什么、变更了哪些文件、哪些测试通过、归档位置，以及归档导致的任何路线图状态变更
   • 如果用户想要提交并推送已完成归档的变更，则提供 /spec-driven-ship <name> 作为下一步的明确交接。该交接仅作建议：除非用户明确选择，否则不要暂存文件、检查推送条件、进入该工作流、提交或推送。

规则

• 步骤 1 中的上下文重置是强制要求——绝不可跳过
• 步骤 2 中的复杂度检查是强制要求——绝不可跳过
• 工作流全程自动运行——除非 questions.md 中的待解决问题需要用户处理，否则不要暂停等待确认
• 每当未解决的问题导致工作流受阻时，都需要额外确认
• 除非遇到无法解决的问题，否则所有其他步骤都自动运行
• 全程遵循所有 config.yaml 规则（规范、变更、代码、测试）
• 如果流程中途出错，请停止并说明原因——不要悄悄继续
• 一次只将一个任务标记为完成，不要批量标记
• 未经用户明确确认，推荐答案不算问题已解决
• 将实现和测试映射保留在 frontmatter 中，不要放在需求说明文字中
• 不要自动提交或推送。只有成功完成归档收尾后，才通过明确的 /spec-driven-ship <name> 工作流处理发布。