SuperAPI AI 工具集

implementation-plan

编程与开发

查看项目

更新于 10-17 16:13

技能介绍

用途

该技能用于把一份已评审通过的规范文档转成实施计划,让实施者能在新会话中直接按计划工作。规范由用户控制范围并评审,计划细节在已批准规范内自主起草。技能独立于生成规范的工作流。

语言规则

所有输出(含聊天、提问和产物)使用 ASD-STE100 简化技术英语,采用主动语态和一致术语,指令句不超过 20 词,描述句不超过 25 词。引用的输入、标识符、必需签名和命令保持原样。

输入与输出

需要带有 artifact: spec 的规范文件。若存在未关闭的台账行或未解决的阻塞问题,视为阻塞。在 quickie 的委托自动模式下,还要求 status: validated 和已记录的关卡批准。接受任何具备必需 artifact 字段的规范,不要求固定章节编号。未提供规范时询问其路径或主题文件夹;规范缺失、阻塞或不一致时说明原因并停止,不代为解决规范阻塞,也不自动启动其他技能。计划保存为规范旁的 plan.md,使用 assets/plan-template.md 模板。写入前先读取已有计划;替换已批准内容前需询问。保持规范及其意图不变。

边界与交互

不实施任务,不修改生产代码、测试、依赖或项目配置;不执行 git commit、创建分支或推送。提问前先检查仓库证据。区分仓库事实、用户决策、推断和未知项。只问会阻塞起草或影响已批准决策的问题。有 AskUserQuestion 时优先使用,否则在聊天中提问。仅当问题主题相同且答案互相独立时才合并提问。用证据、后果和最小可行替代方案说明顾虑。不编造替代方案,无新证据不重开已批准选项。沉默、取消和事实性回答均不构成批准。在委托自动模式下,只有全部检查通过后,才将 quickie 的调用作为完整计划的批准证据,不得声称用户直接评审。仓库调查仅只读,不因计划中包含命令就去执行。区分计划中建议执行的命令与规划期间实际执行的检查。

工作流

  1. 校验来源:读取完整规范和相关支撑文件(含适用的已批准 UI 参考),检查无未解决阻塞问题及批准记录;收集纳入范围的功能与非功能需求及其标识、验收条件和设计引用;排除提议、排除、推迟和搁置的需求;选择字段缺失时以已批准的 FR 与 NFR 章节为纳入集;在起草依赖任务前解决选择歧义和缺失验收条件;计算规范精确字节的 SHA-256 作为 spec_sha256;记录批准设计所用本地支撑文件的路径与哈希;支撑文件审批不明时先确认;按来源规则检查上游意图新鲜度。
  2. 检查当前仓库:只读检查与规范相关的实现、调用方、测试、公共接口、脚本和工作区改动;从入口点追踪每个纳入行为到受影响组件和可观察输出;记录当前提交为 repository_baseline(无 Git 元数据时记为不可用);记录既有工作区改动但不修改;从仓库证据识别现有测试命令、构建命令、验证方法和前置条件;记录已知基线失败和不可用的验证设施,未执行不得声称检查通过;将当前证据与规范假设对比,重大冲突先按纠正规则处理。
  3. 起草完整计划:先读模板、备好完整计划再呈现,不逐节请求例行批准;计划需足以支撑新会话且无需复制完整规范;每个任务用稳定的 Task N 标识并对应一个可独立验证结果;行为任务小到可完成一轮红-绿-重构,不为同一结果的分离层单独设任务;每个任务给一个入口点(现有 file:symbol、必需新符号或文件路径),要求实施者从入口点向下追踪,不冻结详尽的下游文件清单;为每个任务引用纳入需求标识和相关规范章节;为必要支撑任务给出纳入需求或既有仓库约束的理由;在 Depends on 下声明确切任务标识或写 none;任务顺序满足依赖且完成后保持可构建和既有测试通过;单独记录已知基线失败,未经批准不加入无关修复;保留必需签名、契约、不变量、架构和验收条件;私有辅助函数、类拆分和附带接线留给实施;优先复用既有代码、标准库、原生能力和已装依赖;将重大新技术选型交回规范评审,不把新设计决策藏在任务中;不包含生产代码清单,正确性需要时给出确切契约引用;规范要求时规划迁移、回滚、安全、无障碍和运维验证;通过受支持入口点规划测试(导出函数、注册工具、HTTP 端点或 CLI 命令),断言可观察返回值、错误或副作用,期望结果取自需求而非实现;不为便于测试而测试私有辅助函数或模拟内部协作者。每个生产行为任务写明:RED(要新增或修改的测试、命令及因行为缺失导致的预期失败)、GREEN(通过测试的最小行为)、REFACTOR(批准约束内允许的清理且测试保持通过)、验证(确切命令或可观察检查、前置条件和预期结果);非行为任务用不适用 TDD 的理由替代上述字段并保留可观察验证;使用现有验证设施,不虚构脚本;命令需要新测试或脚本时,注明其创建任务和依赖;无自动化验证时给出可复现观察并说明限制;每个纳入的 FR 和 NFR 至少映射到一个任务及其验证;隔离任务检查不足以确立验收条件时加入集成或端到端检查;不得用“代码已写”或“任务已完成”作为验证。
  4. 评审:完成全部检查后,在首次评审或委托验证时保存完整计划;呈现保存路径、任务顺序、依赖、需求覆盖和主要关注点,摘要简洁,可展开任一任务而不替换已保存的完整计划;非委托自动模式下邀请用户评审完整计划并就地修正;修正后重新检查来源新鲜度和仓库证据,说明自起草以来的变化;委托自动模式下记录有限批准,全部检查通过后才设 status: validated,并将路径返回 quickie,否则报告计划路径后停止,不启动实施。

来源新鲜度与续作

相对规范路径按计划文件夹解析,相对意图路径按规范文件夹解析;接受既有绝对路径,但须校验来源存在且哈希相等;新规范与支撑文件路径按计划文件夹存储,计划旁的规范用 spec.md;基于文件的意图需在规划前和修正后提供源文件与匹配的 intent_sha256;对话提供的意图仅在规范记录该意图时才接受 intent_sha256: not applicable;缺少必需来源或哈希时说明阻塞,不编造哈希或跳过检查。续作或对话分支变化时,重读计划、源规范和支撑文件,比较保存的 spec_sha256 与当前来源,复查上游意图新鲜度,校验支撑文件哈希,将缺失或变更文件视为来源陈旧;对照记录的基线检查相关仓库改动(含未提交改动),重新评估受影响任务;无 Git 元数据时说明限制并直接检查相关文件;使用已保存计划而非缺失的对话历史,替换已有计划前先询问;计划保存前的规划中断从规范和当前仓库证据重新开始;报告写入失败并停止,不声称未保存工作可续作。

纠正规则

来源哈希不同即停止并指出发生变化的假设或章节;不得仅为掩盖陈旧而刷新哈希,需先评审变更来源并获得对受影响内容的批准;意图变化时先请求意图评审;范围、验收、UI、契约或架构变化时通过 design-specs 或其原始工作流请求规范评审;不自动编辑上游产物或启动其他技能,规范修正后再继续;仅任务顺序、分组或验证变化时修订计划并提交评审;批准约束内的私有结构选择无需规范批准;修订已保存计划前说明影响,委托自动模式下仅破坏性变更才询问。

完成检查

来源规范为最新且无阻塞实施的问题;仅纳入需求出现在覆盖中,每个纳入的 FR 和 NFR 都映射到任务和可观察验证;每个任务有稳定标识、单一结果、入口点、依赖和规范或仓库依据;依赖标识存在、无环且位于依赖任务之前;行为任务含 RED、GREEN、REFACTOR 和验证,其他任务说明不适用 TDD 的原因;验证命令有证据支持或明确为计划中,每项检查注明前置条件和预期结果;既有改动、已知失败、未执行检查和不可用证据区分清楚;任务保留已批准范围、契约、不变量和架构而不冻结附带私有结构;计划中没有伪装成实施工作的未解决重大设计决策;保存的计划含来源哈希、仓库发现、实施自由度、纠正规则和委托自动模式下的批准证据;产物与摘要符合语言规则,无未使用占位符;未开始任何实施工作。