spec-kit-implement

按照 TDD 和 FRAMEWORK.md 变更工作流，执行 tasks.md 中的任务列表。

输入：可选指定变更名称。如果省略，请根据上下文推断，或向用户询问。

步骤

1. 检查清单

   如果 specs/changes/<name>/checklists/ 存在，统计每份清单中已勾选和未勾选的项目，并显示一个表格：

   | Checklist       | Total | Checked | Unchecked | Status |
   |-----------------|-------|---------|-----------|--------|
   | requirements.md | 14    | 14      | 0         | PASS   |
   | security.md     | 8     | 5       | 3         | FAIL   |
   

   requirements.md 是由 spec-kit-specify 和 spec-kit-clarify 维护的规范质量清单；其他清单由 spec-kit-checklist 生成，归审查者所有。勾选表示满足了需求质量标准，而不是表示工作已完成。 这些清单是只读关卡：绝不更改其中的标记。 如果有任何未勾选项，询问用户是否仍要继续；除非用户答应，否则停止。

2. 加载资料

   加载 specs/changes/<name>/tasks.md、plan.md 和 spec.md，以及 FRAMEWORK.md（包括 FRAMEWORK.local.md 和它链接的能力文档），了解工作必须遵循的规则。

   如果缺少 tasks.md 或其内容不完整，请提示先使用 spec-kit-tasks 技能。

3. 显示当前进度

   显示：

   • 变更名称
   • 进度：“已完成 N/M 项任务”
   • 剩余任务概览

4. 按阶段执行任务

   按依赖顺序处理每项待办任务：

   • 宣布即将处理的任务。
   • 开始处理前，根据当前代码树确认任务目标：任务列表可能比其编写时所依据的代码树存在得更久，文件可能已移动，规则也可能已更改。 在勾选任务时，将任何修正写入任务内容，让后续阅读者知道实际完成了什么。
   • 遵循 TDD：先编写会失败的测试，确认它因预期原因失败，然后实现满足测试的最小改动，最后进行重构。
   • 保持改动最小，并限定在任务范围内。
   • 遵守分层边界：domain → application → infrastructure。绝不反向依赖。
   • 运行针对该任务的检查：覆盖相关行为的测试，以及针对所改文件运行项目的代码检查、格式化和类型检查。
   • 任务完成后立即在 tasks.md 中标记：将 - [ ] 改为 - [x]。
   • 完成本阶段并检查通过后，再进入下一阶段。

   标记为 [P] 的任务涉及不同文件，且不依赖任何尚未完成的任务，因此可以并行执行；如果 Agent 支持，也可以使用子 Agent。 这只是许可，并非必须；绝不要将涉及相同文件或存在执行顺序的任务拆分给多个子 Agent，以免编辑冲突。 父 Agent 仍负责整合结果、勾选任务，并继续执行，直至列表完成。 如果并行任务失败，继续处理其他任务，并报告失败情况。

   遇到以下情况时暂停：

   • 任务不明确——在实现前请求澄清。
   • 实现过程中发现设计问题——建议使用 spec-kit-plan 技能更新 plan.md。
   • 测试意外失败——报告情况并等待指示。
   • 用户中断。

5. 处理文档阶段

   任务列表以文档阶段结束：变更导致每份现存规范、决策记录或文档不再准确，都应有一项任务；如果没有，则注明“（无可观察到的行为变化）”。 像处理其他任务一样完成这些任务并勾选：

   • 使用 FRAMEWORK.md 中规定的规范格式（WHEN/THEN 场景、RFC 2119 用语）。
   • 现存规范描述的是已构建的内容，绝不能悄悄降低要求。 如果实现未达到变更 spec.md 中的要求，不要将现存规范改写成与未达标的实现一致。 完成工作，或询问用户；如果用户接受未达标项，须在变更的 spec.md 中记录该决策及理由，以便审查者一并评估。

6. 检查变更是否导致测试过时 未修改文件中的测试仍可能引用该变更删除的函数、选择器或字面值，而被修改文件中的测试无法发现这些问题。 将工作树与该变更起始时所基于的提交进行比较，列出已修改源文件中移除的名称，保留所有其余源文件均不再包含的名称，并在测试文件中搜索它们。 使用 Git，并根据项目布局调整测试匹配模式：

   BASE=$(git merge-base origin/main HEAD)   # or the commit the change started from
   T=(':(glob)**/*_test.*' ':(glob)**/*.test.*' ':(glob)**/*.spec.*' ':(glob)**/tests/**' ':(glob)**/test/**')
   X=("${T[@]/#:(glob)/:(exclude,glob)}")
   git diff -U0 "$BASE" -- . "${X[@]}" | grep '^-' | grep -v '^---' |
     grep -oE '[A-Za-z_][A-Za-z0-9_]{2,}' | sort -u |
     while read -r name; do
       git grep -q -w -F -e "$name" -- . "${X[@]}" || git grep -l -w -F -e "$name" -- "${T[@]}"
     done | sort -u | grep -vxF -f <(git diff --name-only "$BASE"; echo /dev/null)
   

   将列出的每个测试文件都作为针对性检查运行；大多数测试文件都会包含的名称属于套件的术语，而非过时测试。

7. 验证是否完成

   • 每项任务都已勾选；若未勾选，则附注说明由谁负责。
   • 实现的行为符合规范，代码遵循计划。
   • 项目中针对受影响范围的测试和检查均已通过。
   • 架构边界仍然成立。

实施期间的输出

## Implementing: <change-name>

Task 3/7: <description>
[implementation]
✓ Done

Task 4/7: <description>
[implementation]
✓ Done

完成时的输出

## Complete: <change-name>

7/7 tasks complete.
Documentation phase worked: specs/features/<area>/spec.md updated.

Definition of done:
✓ Tests written before implementation
✓ Architecture boundaries hold
✓ Documentation phase's tasks ticked

下一步：“使用 spec-kit-converge 技能，根据 spec.md、plan.md 和 tasks.md 评估工作，并将任何差距转化为任务。”

护栏

• TDD 不容妥协。失败测试通过前，绝不编写实现代码。
• 非并行任务失败时立即停止，不要跳过。
• 任务完成后立即更新任务复选框。
• 优先保护领域模型；围绕它调整基础设施。
• 在认定工作完成之前，必须勾选 Documentation 阶段的任务，并更新 specs/features/。
• 测试必须覆盖生产环境实际采用的调用方式。 如果代码从调用方获取路径、根目录、模式或选项，应覆盖调用方实际使用的值，而不只是方便测试的情况。
• 追踪新值直到它离开系统。 对视图模型或内部对象的测试只能证明值已计算出来，并不能证明它会被输出：如果响应或输出是手动组装的，新字段可能会在过程中丢失。应通过读取实际输出的测试覆盖它。
• 当缺少依赖会导致功能关闭时，验证依赖接线。 如果不设置依赖，应用就会跳过某项检查，那么应编写一个测试，构建真实的组合并断言该依赖已设置。
• 没有布局的组件测试只能证明控件可以渲染，不能证明它可用。 应在真实浏览器中检查此变更新增或重新设置样式的每个交互控件，而非只检查其中一个。
• 删除标记或标识符可能会破坏远处读取它的代码；删除前应搜索所有读取它的代码。
• 确保文本断言确实能够失败。 当测试断言文件文本而非行为时，应在副本中修改该文件，确认修改确实生效，并观察测试失败。使用模式提取时，应断言提取到了内容后再检查其值，否则不匹配任何内容的模式也会通过，检查形同虚设。如果警告文本本身包含测试要查找的内容，则只匹配可执行代码行。应直接写出预期值，而不是从此变更正在编辑的版本中读取。
• 彻底移除所有探测内容，包括其创建的任何目录，并使用绝对路径恢复文件；随后将恢复的文件与预期变更进行比较。
• 绝不能把管道的退出状态当作命令本身的退出状态。 test-suite | tail-20 报告的是 tail 的状态，因此失败的运行可能会被误判为成功。应将输出重定向到日志，并先记录命令本身的状态（<command> > run.log 2>&1; echo "EXIT=$?" >> run.log），再据此判断。
• 长时间运行的命令正在执行某脚本时，绝不要编辑该脚本；应等待命令结束，或编辑副本。