SuperAPI AI 工具集

ft-implement

编程与开发

查看项目

更新于 10-16 14:04

技能介绍

用途

ft-implement 属于 fast-track-ai 工作流,用于把一个已规划好的 track 按任务逐项落地实现。它在目标仓库中读取 fast-track-ai/tracks/NNN-slug/ 下的 intent.md、spec.md 和 tasks.md,并据此执行实现、验证、审查和最终门禁。

主要能力

  • 前置条件检查:要求 intent.md 存在,且 spec.md 与 tasks.md 的 frontmatter 状态为 approved;intent 状态可以保持 draft。
  • 断点续做:恢复时将每个已勾选(- [x])任务视为已通过验证,从依赖顺序中第一个未完成任务继续;不重跑已勾选任务的 Validate,除非后续改动触及该任务的 Files,此时在提供 ship 之前需重跑该任务的 Validate。
  • 边界约束:产品改动仅限 spec Files 与各任务 Files 列出的文件,触及任何其他产品文件前必须停下询问;不得实现 out_of_scope 中的条目。
  • 假设核查:intent 中“用户陈述”的事实视为成立,需在任务依赖之前逐项核实 Unverified assumptions;若陈述事实或假设被证伪,将分歧记录到 track 的 assets/ 中,停止并向用户报告,不得自行调整方案。
  • 方法管理文件的变更受命名转换约束:tasks.md 中的任务复选框、track 的 assets/ 下的文件、通过 owner index 脚本更新的 fast-track-ai/INDEX.md、ship 确认后的 intent status: shipped、fast-track-ai/decisions/ 下的新 ADR,以及在发生实质性变更时把 spec.md 与 tasks.md 退回 draft。
  • 决策记录:实现过程中用户做出符合条件的决策时,依据 ../ft-spec/assets/decisions.md 生成 fast-track-ai/decisions/<NNN-slug>.md,状态仅使用 accepted | superseded;若该决策与已批准的 spec.md 或 tasks.md 冲突或造成实质变更,需停止实现,把两者退回 draft,调和 ADR 与两个规划产物,给出以 . para implementar 结尾的新 spec 摘要,并需重新获得明确批准后才能继续;不构成实质变更的则记录后继续。局部、易回滚或显而易见的选择不创建 ADR。
  • 并行分组:从 tasks.md 的 ## Group <name> 标题与 (depends: <group>) 标注解析分组,按依赖顺序启动;组内任务可并行,每个委派任务使用独立子代理;当运行环境不支持子代理时,组内任务按顺序执行,同时保持分组依赖顺序。依赖组需在其依赖的每个任务均通过 Validate 并勾选后才启动;在此之前不得创建、编辑或删除依赖任务 Files 中列出的任何文件,包括暂存工作或收集证据。前置任务 Validate 失败时,在所有依赖组之前停止并报告。不得并行编辑同一文件。
  • 委派粒度:仅当任务值得独立上下文(涉及多个文件或 Validate 超出单个快速检查)时委派给子代理;简单任务由主代理直接运行。任务子代理使用运行环境提供的执行类代理,会话模型保留给规划、集成、共享文件、审查与最终验证。不硬编码模型名称或供应商标识。主代理负责集成、共享文件和最终验证。当前组的子代理仍在编辑时,不运行项目级检查(如完整测试套件、构建或类型检查),需等组内所有任务返回后再执行。
  • 完成前验证:运行每个开放任务的 Validate 命令以及目标项目实际提供的检查(如已有测试套件或类型检查器),不为项目未配置的工具臆造或假设命令。任务 Validate 即使在项目中是唯一的检查脚本,仍保持任务范围。Validate 通过后立即在 tasks.md 中勾选 - [x],再开始下一依赖组。未验证的改动不得标记完成,Validate 失败则保持未勾选。
  • 发货前验收:所有任务通过 Validate 后,编写 fast-track-ai/tracks/NNN-slug/assets/acceptance.md,使用 Markdown 表格,列为 Criterion | Check | Observed | Result;包含一行 spec Outcome 和每个阶段的 Accept: 行各一行;针对变更最终状态执行每项检查并记录观察输出;Result 设为 met 或 pending。所有行均为 met 才能提供 ship。
  • 完成门禁与审查:全部任务标记为 [x] 后,运行 ../ft-spec/scripts/fast-track-ai-gate.sh --track NNN-slug --root <target>,随后进行包内审查。审查原则:捕获缺陷与边界情况、保持改动可维护、评论代码而非个人、跳过 linter 负责的格式问题。审查阶段:(1)从 intent、spec 和 diff 获取上下文;(2)对照 spec Files 与 Out of scope 做高层契合检查;(3)对列出的文件逐行检查正确性、安全性以及是否存在臆造答案或未列出的改动;(4)总结并给出决定。严重级别:[blocking] 必须修复、[important] 应当修复、[nit] 可选、[suggestion] 替代方案。若存在任何 [blocking] 发现,需修复、重跑受影响任务的 Validate 命令与受影响阶段的验收检查、更新 assets/acceptance.md 中受影响行的 Observed 与 Result、重跑完成门禁,并重复审查直至不存在 [blocking] 发现。每个 [important] 发现需修复或列为开放项。

使用方式

  • 在目标仓库中运行,路径解析规则为:./ 路径与 ../ft-* 同级路径从该技能的安装目录解析,fast-track-ai/ 路径从目标仓库根目录解析。
  • 所有任务预先在运行环境提供的任务跟踪器中创建(如有),并带阶段标签。
  • 完成后输出实现后总结:四条简短要点(已完成任务、验收 N/M met(assets/acceptance.md)、审查结论、门禁结果),以及下一步行 . para ship(将 track 标记为已完成)。使用 ../ft-init/scripts/fast-track-ai-index.sh <target> 重新生成 fast-track-ai/INDEX.md 并停下等待用户审查。仅当所有验收行均为 met 且不存在 [blocking] 发现时才显示 ship 下一步行;若有 pending 行则报告并继续修复或询问如何处理。复选框与绿色门禁本身不会触发 ship,在询问之前不得写入 shipped。
  • 等待用户输入:若用户回复 . 或肯定同义词(如 "sim"、"pode continuar"、"yes"、"continue"),将 intent 状态设为 shipped 并再次生成 INDEX.md;其他输入作为修复或修订指令处理。

适用场景

适用于已通过 fast-track-ai 完成规划(spec.md 与 tasks.md 状态为 approved)、需要按任务逐个实现并附带验证、审查和门禁检查的软件仓库开发流程;也适用于实现中断后的恢复续做。

限制

  • 运行前必须存在 intent.md,且 spec.md 与 tasks.md 的前置元数据状态为 approved,否则不得运行。
  • 产品文件改动限于已列出的 Files,不得触碰 out_of_scope 条目,也不得自行调整方案。
  • 需依赖运行环境是否提供子代理与任务跟踪器;不提供时按顺序执行,任务跟踪器缺省时相关步骤暂未提供。
  • 不得并行编辑同一文件,不得在子代理编辑期间运行项目级检查。
  • 不得在用户确认前写入 shipped。
  • 具体支持的平台、收费方式、价格等信息暂未提供。