write-implementation-plan

实施规划

改编自 commit b36e0829c6d0140e93cfef2ca599b1b07d4a7797 中的 obra/superpowers（MIT）。可验证单元排序和迁移清理改编自 Cursor 的 poteto-mode，对应 commit 93b00b89ef425a9c1bac0d0b317dfc49c930ac99（MIT，Copyright (c) 2026 Cursor）。Tracer-bullet 切片以及大型重构的 expand–contract 例外改编自 Matt Pocock 的 to-tickets，对应 commit 3cca18b368ae95cdbdebbff572ccafa662551015（MIT，Copyright (c) 2026 Matt Pocock）。

面向没有对话上下文的实施者编写。规格说明负责定义行为；根据 planning-contract 中规定的权限范围（Contract version：1），本计划只负责拆解执行工作。本计划是精简的执行路线图，而不是改写后的规格说明。如果未安装该契约技能，请停止并要求安装 planning-contract，不要依据继承或自行臆造的规则进行规划；切勿假设会自动解析依赖项。

产物策略

• 对于由单一负责人处理的一项范围明确的变更，跳过计划文件，直接将已批准的聊天内设计交给 orchestrate-implementation；capture-checkpoint 的结果仍应按比例适用。
• 对于架构性工作或多步骤工作，编写尽可能精简的计划，明确依赖关系、负责人、集成顺序和验证方式。
• 将相互独立的子系统拆分为单独的计划，而不是编写一份庞大的计划。
• 需要计划文件时，使用 planning-contract 的文件名约定 YYYY-MM-DD-NNNN-slug.md。计划应沿用源规格说明的确切前缀；否则，从项目的规格说明和计划目录（project/specs/ 和 project/plans/；旧目录为 docs/specs/ 和 docs/plans/）共享序列中分配下一个编号。
• 只有在用户提出要求、既定跟踪系统要求，或协调工作必须延续到当前运行结束之后时，才创建跟踪任务。将每项任务发布为工单；工单保存任务正文的规范版本，精简的概览可以链接到工单，但绝不可维护重复且可编辑的任务定义。

ADR 说明原因，规格说明定义内容，计划或工单定义可执行的下一步单元。

精简保障原则

规划能够确立验收标准并应对具体重大风险的最小证据集。除非某项测试、验证命令、审查人员或审查边界能够覆盖一种独立且可能发生的故障模式，否则不要添加；若无法指出该故障模式，就省略这项保障工作。

将每个验证单元指定为一条最小链路：其防范的具体故障 → 用于判定预期结果的独立依据（已批准的标准、手工推演的示例、可信参考或真实缺陷）→ 一项有针对性的检查，或明确复用适用的现有证据 → 会使该证据失效的变更。拒绝通用的分层或分阶段矩阵及认证清单；若项目或 CI 有明确规定的强制关卡，则以原样纳入计划为准。

每个验证单元只归为以下一类：

• 低风险 — 文档、机械性修改、生成的输出，或行为不变的内部重构：使用现有检查，或最精简的冒烟测试、解析、构建或差异检查；不添加测试，也不安排独立的任务审查；
• 普通风险 — 常规行为变更和缺陷修复：在成本最低且稳定的切入点使用一项有针对性的回归测试 或 一项现有检查，并进行一次候选审查；不要在单元、集成、API 和浏览器等多个层级重复验证同一行为；或
• 高风险 — 身份验证、权限、机密信息、资金、破坏性数据处理、迁移、并发、分布式行为或公开契约：针对具体威胁或故障模式进行验证，并在后续工作将使用其结果时立即审查。

一个验证单元可以覆盖多个紧密相关的任务。验证应针对变更的行为或风险，而非每个复选项。复用仓库要求的 CI，不要在每项任务中重复列出完整的测试、lint 和类型检查矩阵。要求添加测试本身也需要有依据：指出真实且可能发生的场景，以及被违反的标准；覆盖率百分比和不可能出现的领域状态都不是理由。书面约定具有约束力，未写明的偏好不得成为阻碍。明确实际调用方、输入来源、环境，以及适用的指令、风格和 lint 规则（或注明未发现），以免新加入的工作者或审查者凭空臆造上下文。

只有当任务涉及不可信或外部输入、凭据、身份验证或依赖项变更时，才启动安全审查。明确资产、现实中的攻击者，以及攻击者通过实际使用路径实施攻击的方式。默认不将可信的内部调用方和用户拥有的本地文件视为恶意输入；服务应以真实部署边界为准。机密信息被窃、TLS 失效、恶意管理员以及泛泛的加固情形都不构成审查发现。未触及边界时，标记为 security: n/a；安全工作缺少事实时，标记为 unverified 并提出问题，不要臆造威胁模型。保留书面安全保证。

最多规划一次经父级授权的修复，以及一次仅针对差异的复查；其余阻碍交由人工处理，不再开启新一轮。候选审查应覆盖尚未审查的代码和集成影响，不要重新打开已解决的问题。不要添加证据台账、审查签核或第二套生命周期。

预检

1. 阅读已批准的规范、项目说明、相关代码/测试，以及任何已建立的领域术语表或决策记录。
2. **就绪门槛：**根据 planning-contract，必须有已批准的行为依据——已批准的规范或其范围明确的变更等效文件；研究结果和探测结论属于证据，不是依据。如果缺少该依据，请停止，报告具体缺少的前置条件，并将工作转回 shape-design。
3. 如果需求冲突，或重要的负责人决策尚未解决，请停止。
4. 如果在规划期间发现行为、接口或范围发生重大变化，请转回 shape-design：更新依据，就变更后的范围和修订版本取得批准，并根据契约的就绪规则，在依据与任务分解重新协调一致前，阻止受影响的任务。
5. 将相互独立的子系统拆分为单独的计划。
6. 明确文件、职责、接口、依赖关系和集成顺序。找出阻塞性的首要步骤、独立工作流、共享写入目标和最小安全分解；共享同一行为及验证边界的步骤应合并；如果分解会增加审查或协调开销，则优先由单一负责人按顺序处理。只有满足契约的并行执行规则时，才将任务标记为可并行执行。
7. 遵循既有项目约定；不要在计划中夹带无关的重构。

使用仓库既定的计划存放位置。如果没有，请先提出存放位置或运行时管理的制品方案，并在创建新的文档约定前取得批准。

计划头部

通过链接引用规范内容，而不是重复陈述。包括：

• 目标；
• 源规范路径、其批准参考，以及确切的已批准范围和修订版本；
• 捕获检查点的结果；
• 仅包含安排工作顺序所需的架构约束和非目标；
• 技术/运行时假设；
• 指向规范验收标准的需求到任务映射；以及
• 未被仓库必需的 CI 隐含覆盖的最小全局验证命令。

任务

示踪子弹式切片

分解为垂直切片：每个任务都应贯穿其涉及的每一层（模式、API、UI、测试），形成狭窄但完整的路径，并且能够单独演示或验证。切勿按横向层级拆分任务（先做模式任务，再做 API 任务，最后做 UI 任务），因为这些任务之间的中间状态无法产生可观察的行为。完成每个切片后，代码库仍应保持协调一致且通过检查。

先让改动变得容易，再实施容易的改动：如果某个切片会受当前代码结构掣肘，应先规划明确的预重构任务，再实施行为任务，而不是把预重构藏在行为任务里。

大范围重构是垂直切片的例外。 大范围重构是指一种机械性改动（如重命名列、重新定义共享符号的类型），其影响范围遍及整个代码库，因此无法通过垂直切片以绿色状态合并。应按扩展–收缩的方式排序：在旧形式旁添加新形式；按影响范围分批迁移调用点，每批作为独立任务，依赖扩展任务，并因旧形式仍然存在而保持 CI 通过；当不再有调用者时，在一个依赖所有迁移批次的任务中删除旧形式。如果连各批次都无法单独保持绿色，就应在共享集成分支上按顺序推进，并承诺仅在最终集成与验证任务中达到绿色状态；这类序列中的逐任务协调性以集成分支为准，而非 main。

任务是最小的协调交付单元，用来显露真实的依赖关系、所有权边界或可独立使用的行为。不要仅为增加评审或验证节点而拆分工作。每项任务都必须有可运行的检查覆盖，但相关任务可以共用一个验证单元和一个评审边界。对每项任务，明确说明：

• 要创建或修改的确切文件；
• 使用和提供的接口；
• 前置条件；
• 行为和边界情况；
• 其验证单元和测试义务（new-test、existing-check 或 no-new-test），以及它覆盖的具体失败模式；如果复用证据，还应说明适用的先前结果及其失效条件；
• 仅列出必需 CI 尚未涵盖的聚焦命令和预期证据；以及
• 完成标准。

使用复选框步骤。只有当改动后的行为缺少有意义的覆盖时，才指定 new-test；优先在成本最低且稳定的公共接口上编写一个聚焦测试。对于 new-test，应展示聚焦测试、独立推导出的预期结果和验证命令；只有在复现 Bug，以及重构前固定行为时，才展示先失败后通过的步骤。仅在精确签名或不明显的逻辑会造成歧义时，才加入代码片段；不要在文字描述中臆造大型实现。

内部迁移应在同一个清理任务中完成替换、调用者迁移、验证、旧路径删除和过时引用搜索；任何过渡性兼容名称都应说明其实际使用者及移除条件。

质量门槛

交接前：

1. 将每项需求映射到至少一个任务。
2. 搜索 TBD 或 TODO 等占位符、含糊的错误处理、未命名的测试以及未定义的接口。
3. 检查依赖任务间的名称和类型。
4. 确认每项任务都能让代码库保持协调一致且可测试。
5. 删除重复检查、对相同行为的重复覆盖，以及未指定可触达失败模式的评审或验证步骤。
6. 说明剩余风险，以及仅针对这些风险所需的手动检查。
7. 记录契约版本，以及当前可用的已安装溯源信息；若未知，则记录为 unknown。

提交计划供用户审批。获批后，将其交给 orchestrate-implementation，并记录获批的源引用、捕获检查点的结果和契约溯源信息；不要创建第二个执行路由器。