implement-spec

实现规范

逐个评审、一次完成一个环节，直到完整实现当前规范。规范是实施计划；即使架构发生变化，用户约束和已接受的实验依据仍然具有约束力。

一个环节（通常是一个切片）是提交检查点，而不是停止点。目标是完成整个规范——每个切片、每项全局 TODO——而不只是拿下第一个绿色提交。完成一个环节后，就开始下一个环节，而不是把工作交还给用户。只有在规范全部实现完毕时（或遇到必须由用户作出决定的真正阻碍时）才能停止。

只要依赖关系允许，就并行推进。 切片互相独立时，不要一次只沿着阶梯推进一个切片。要把规范的依赖关系图看作波前，将相互独立的环节委派给并发运行的子 Agent（见“规则”）——由你负责统筹和集成；只有确实依赖前序工作的部分才串行执行。

工作流

1. 编辑前，先阅读仓库 README、规范 README 和下一个切片。加载规范中列出的所有技能。确认当前接手点、全局 TODO、必需的门禁，以及必须保持通过的部分。如果多切片规范没有有效的交接提示，请在首个环节结束前添加。对于已验证的 Spike，编辑前先遵循下方的保留胜出方案。

2. 根据当前代码核对计划。如果切片会保留仅用于开发的垫片、重复类型、薄弱封装或过时路径，就用更简单的架构替换它，并更新规范交接内容。

3. 实现一个连贯的环节：通常是一个切片、一个纵向检查点或一次架构修正。让评审范围保持精简，便于审查。

4. 验证实际契约。行为变更先运行针对性测试；浏览器可见的工作要使用真实浏览器或测试框架并检查截图，确保主体取景合理且清晰易读，而不只是页面非空。视觉变更在宣称完成前还需额外通过两项验证：在生产路由上与变更前基线进行字节／像素差异对比（所有静态检查和重新锚定的断言都必须通过；空操作也能全部通过，因此某次配色调整曾在生产画面字节完全相同时仍被宣称“已验证”）；以及未经预先提示的 screenshot-critique——如果该环节是为了解决用户报告的视觉问题，就要按照用户报告中的取景进行评审——然后才能宣称问题已修复。实施者的视线已被修复方案预先影响，反复检查也可能错过新鲜视角能发现的问题。 切勿削弱现有默认门禁，也不要在未证明旧契约有误的情况下重新固定一个失败的契约。

5. 每个环节提交前，先检查变更清单并完成清理。 逐行查看 git status／git diff --stat，确认每个路径的去留：临时探测文件、截图脚本、临时文件、nohup.out、临时截图目录，以及一次性 SPIKE／调试笔记都不得进入提交——临时文件应留在工作树之外。在项目的参考资料或规范资源目录中保留冻结的参考资料、固定测试数据和研究证据。没有长期用途的文件不应提交。 委派的 Agent 可能会遗留这些文件；负责集成的评审者必须以同样的标准重新检查合并后的工作树。 评估这次实现的规模——衡量它耗费了多少成本，并在代码行数与实现行为不成比例时重新设计——属于第 6 步中的结构检查，详见 refactor-clean。

6. 每次实现结束时、提交之前，都要运行 review。 它会按顺序完成三个收尾检查——通过 refactor-clean 检查结构，通过 code-review 检查已定稿的差异，通过 write-docs 检查变更涉及的内容——并落实三者提出的修正。长规格容易不断积累沉淀，因此结构检查只针对本次实现的产出：本次引入的仅供开发使用的垫片、重复概念、并行抽象和兼容性封装，都应收敛为由单一所有者负责的清晰契约，让代码体现当下的设计，而非一层层补丁。最后，对清理后的实现运行 audit-choices——这是一项纯审计，会将规格未明确说明时做出的每项决策（包括你自己的决策，以及整合时各委派子 Agent 的决策）及其判定，追加到规格的 choices ledger（specs/<feature>/choices.md），但不会自行修改代码。你需要根据审计结果采取行动：根据修正后的决策重做不合理的选择；对于仅能由用户决定的条目，则采用审计记录的暂定方案——审计不会阻止流程继续。重新运行受影响的检查，然后只提交本次实现中的聚焦变更。

7. 更新规格 README 中的“Next Agent Prompt”：状态、已完成工作、下一步接手位置、阻碍因素、变更的检查门槛，以及任何改变计划的架构决策。

8. 将维护检查点纳入循环，而不是留到最后清理。在红色实现之后、每两三次切片提交之后、变基/恢复/压缩之后、切换功能区域之前、证据推翻计划时、交接内容与 TODO/图不一致时、choices ledger 中的条目集中在某个切片附近时，或当前提示词变得难以快速浏览时，都应触发检查点。长规格会反复膨胀；清理是常规实现步骤，而非表面功夫。

   在继续实现功能之前，检查点会同时清理计划和代码：

   • 将 README 交接内容缩短为一个当前接手点、一份优先级顺序和一份精简的证据记录；将详细过程移至切片文件或资源中。
   • 修正已完成/已否决/下一步标记；删除过时的 TODO、过时的验收声明、重复的状态章节和废弃的提示词。
   • 重新排列剩余工作的优先级，明确下一项红色/高风险契约，并将不在该路径上的分支降级。
   • 在继续实现之前，将仍处于红色、负担过重或定义模糊的切片重新拆分为更小且可独立验证的实现步骤。
   • 当早期实现留下的脚手架不再负责真实契约时，予以删除或合并。
   • 如果工作似乎偏离方向，请让新的审查者/子 Agent 审计规格结构和优先级顺序，然后落实修正。 当清理工作对规范、代码结构或交接内容造成足够大的影响，以至于后续 Agent 否则会继承过时的上下文时，应将检查点作为独立且目标明确的提交提交。只有当一个全新的 Agent 无需对话历史，仅阅读 README 交接内容、TODO 和切片图，就能选出相同的下一步行动时，才算完成。

9. 继续。 如果仍有任何切片或全局 TODO 未完成，立即返回步骤 1，处理下一个——保持在同一会话中，不要停下来等待确认。持续循环，直到所有 TODO 都已完成。

10. 再次对整个规范运行 review。 每轮评审都根据当时的代码，评估了一个切片；这一次评审的是已完成的功能。评审范围应涵盖规范的完整差异，而不是最后一轮的范围——只有在这个范围内，才能发现跨切片蔓延的重复内容、只有所有切片完成后才显得不妥的结构，以及描述增量而非功能本身的文档。应用修复，重新运行检查门，提交。

11. 整合决策记录，然后收尾。 最后一个切片完成后，逐轮追加的 choices.md 已成了构建顺序留下的沉积物：早期记录的条目带有“暂定——在切片 N 中重新审视”的结论，后续轮次已悄然解决这些问题；后续轮次已推翻的条目仍留在其中；同一项决策也可能出现两次。逐轮规则“记录后即为定案，绝不重复列出”正是造成这种偏移累积的原因，因此最终整合是对此规则的刻意例外。归档前，从头重写 choices.md，将其整理为最终决策记录：根据最终交付的代码（而非该决策出现时所在的轮次），重新审查每一项已记录的决策；将每个暂定／待后续处理的条目改为其最终状态；删除已被后续轮次取代或推翻的内容，并合并重复项。记录中只保留决策——不要包含检查门结果、e2e 证据或评审问题的叙述；这些内容会在其他地方报告，不属于用户现在需要负责的决策。按照 audit-choices 的要求呈现：按结论分组，按信心从低到高排序，每个条目都应能让五岁孩子听懂，且脱离上下文也能独立理解。 然后使用 close-spec 结束规范。

保留胜出版本

• 阅读冻结的胜出代码、配置、提示词／技能和证据。保留实际行为，包括那些贡献尚不明确的怪癖。重写的规范或更整洁的设计都不能取代实测结果。
• 先移植，再单独试验。向受委派者提供相同的参考资料和约束。记录用户要求的差异；采纳其他行为变更前，先根据胜出版本验证。
• 使用匹配的输入和受控的外部响应，通过生产入口证明行为一致性。比较计算出的请求、决策、完整输出和相关恢复路径，而不只是模板或组件测试。仅规范化有文档说明的预期差异。在进行成本高昂的确认前，先运行这些低成本检查，同时保留原有质量检查门。
• 缺少行为一致性的证据，就意味着工作尚未完成。保留参考版本并继续独立工作，不要宣称二者等效。

规则

• 将互不依赖的工作委派给子 Agent 并行执行。 规范中的依赖图就是行动指南：只要两个或多个切片、分支（例如前端与后端）、子切片、复现探索或侦察任务之间不存在未满足的依赖，就应在一条消息中同时启动子 Agent 并行处理，而不是自己按顺序完成。并行处理文件时，为每个受委派的工作单元分配独立的 git worktree，避免 diff 冲突；共享文件或 API 接口的工作则交由同一个 Agent 处理，避免合并混乱。每个受委派的工作单元都要负责完整流程——实现、验证、审查并提交专注的变更——然后由你集成结果、解决冲突、在合并后的代码树上重新运行受影响的检查，并确保 Next Agent Prompt 保持连贯。只有依赖图要求串行的工作才串行处理；绝不让某条工作线闲等不相关的工作。
• 对尚未发布或仍在开发中的脚手架，不以向后兼容为目标。新架构取代旧架构时，删除旧路径、包装器、别名、回退模式和过时测试。
• 不要意外降低测试难度。拆分测试框架或引入新运行器时，除非规范明确要求更改，否则必须保留原有默认覆盖范围。
• 每完成一个通过检查的工作阶段就提交，然后立即开始下一阶段。绿色提交只是一个检查点，不代表可以停止。若某个阶段未通过检查，就不要将其作为已完成内容提交；应报告未通过的约定及准确证据。
• 只要还有工作未完成，就不要停下。“切片 N 已完成并提交”并不代表任务结束，后续切片或 TODO 仍未处理时更是如此——完成一个切片是继续推进的理由，绝不是交还任务的理由。唯一合理的提前停止情况是：需要用户做出决定的硬性阻碍、无法通过诚实修复使检查通过，或用户中断。上下文不足不是停止的理由——更新交接说明并继续。不得不停下时，要明确说明接下来要处理哪个切片，以及暂停的原因。
• 保持视觉证据真实：联系表、GIF、截图和基线必须展示待评对象，并使用预期的摄像机角度和取景。
• 检查切片涉及的所有用户可见界面。如果主视图、卡片、菜单、报告和验证夹具呈现的内容不一致，就不能算完成模型、状态或数据变更。
• 如果实现涉及共享行为，应遵循 write-docs 的原则，补充文档或规范说明：记录持久有效的不变量和指引，而不是照搬清单。
• 对于较长的规范，要让规范本身始终便于审查，并作为不变量。不要把 README 变成每次尝试的流水账；只保留一份当前交接说明、一份 TODO/依赖图和一份简明证据记录，详情放在切片文件或资源中。
• 人工检查点绝不应成为阻碍。 在切片的审查或签核关卡，使用 preview-shots 打开相关截图，说明待做决定和可选方案，并给用户约 5 分钟发表意见；与此同时继续推进其他不受阻碍的工作，绝不空等。如果用户没有回复，就根据证据自行决定，在规范中记录该决定及其依据（即检查点的处理结果），然后继续推进；同时关闭打开的截图（preview-shots 会清理 Preview），避免长时间无人值守的运行不断堆积窗口。目标或实现绝不能停下来等用户；记录所采用的假设、确保它可撤销，并让用户之后仍能纠正方向。

完成

当代码、规范交接、验证证据、审查清理和一次聚焦提交都与当前事实一致时，一个开发轮次才算完成——然后开始下一轮。

只有当所有切片和全局 TODO 都已关闭、所有门禁均通过、已完成整份规范的审查且修复已合入、交接内容显示没有遗留待处理项，并且已通过 close-spec 归档规范时，规范才算完成；只有到那时，这项技能才算完成。 未达到这些条件，就仍处于实施过程中：继续推进。

最终交接应呈现选择记录，而不是差异，具体要求见 audit-choices——历时数天的无人值守运行要凭这份记录赢得合并；这是用户审查所有未经其参与而作出的决策的界面。交付第 11 步中的汇总记录（最终状态，已对照已发布代码核实，仅包含选择），切勿交付逐轮追加的原始记录——如果记录中仍有“将在后续切片完成”的结论，就说明你从未回头确认它是否完成。

**交接的最后部分必须说明新增内容的规模，始终放在记录之后。**记录说明作出了哪些决定；规模说明为此付出了多少代价。用一个表格总结整个运行：

	新增	删除	净增
生产代码（不含注释）
注释
测试 / 测试框架
规范与文档

然后用一段话列出本次运行新增的结构性内容——新 cron、表列、索引、端点、配置标志、依赖项等——因为这些是用户今后需要负责维护的部分，仅看行数会掩盖它们。 排除本次运行未以其他方式改动的文件中的格式化变更；如果排除了任何内容，也要说明。

无论数字是多少，都要明确写出。如果行为改动很小，但净增内容很多，这就是应该报告的发现，而不是应该掩盖的数字；如果直到此时才注意到这一点，而非在导致它的开发轮次中发现，就要说明是哪个开发轮次。

**切片并非唯一的范围单位。**规范还记录了决策——记录条目、决策表条目、不变量——而某个决策可能在规划时已获认可，却从未转化为切片，尤其是当它与各切片的主题无关时。此时，“所有切片均已关闭”看起来像是工作已完成，但该决策实际上仍未实现。在宣布规范完成前，必须将每项已记录的决策与已发布代码逐一核对，而不仅仅是检查切片列表：每项决策要么已实现，要么已明确标记为“无需编写代码”。没有所属切片的决策是最常见的遗漏——close-spec 审计是最后的保障，而不是第一道防线。