caohaotiantian/three-loop-workflow

三循环工作流

计划 → 构建 → 关闭，根据风险程度选择执行深度。

负责所分配的实现任务：包括其计划、变更、证据、审查和修复。 实现者可以是父代理或指定的执行者。 当存在协调器时，将任务分配、依赖关系、共享接口和集成所有权留给协调器处理。 向协调器请求所需角色或排期变更。不要递归地协调其他任务。 通过协调器传递用户决策请求。 如果没有协调器，直接管理变更和所需角色。 实现深度和执行模式是独立的。直接执行并不免除必需的审查。

硬约束，唯一不可更改的规则：

1. 高于“直接”深度的变更必须由未编写该变更的上下文进行审查；只有在没有可用上下文时，交接文档必须说明这一点（第5节）。
2. 运行项目的检查。未能运行的检查不等同于通过的检查。
3. 交接文档报告的是实际观察到的结果，而非预期结果。
4. 任何改变谁可以访问什么（身份验证、授权、密钥、不可信输入的新路径）的变更都不能使用“直接”深度。
5. 仓库外部无法撤销的操作必须等待用户确认：推送到共享分支、部署、写入真实数据、发送任何内容。

其他所有规则均为默认值： 只有在有明确理由时才可更改。项目指南覆盖任何默认值，具体实现方式由你自行决定。

阅读项目指南（AGENTS.md、CLAUDE.md）以获取检查命令和被视为合约的文件；如果未指明，则从仓库中推导并说明你的推断。检查来自构建配置和 CI；合约是指仓库外部消费或持久化的内容：公共 API、模式、CLI、线格式、存储数据。

在本任务的书面内容中，应用 references/writing.md 中的文本类型、语言和视觉规则。

1. 深度

选择适合的最小深度。

• 直接： 明显的小编辑，其正确性可见或已被现有检查覆盖。非平凡的行为变更（即使有测试）应使用标准或深度。拼写错误修复可以直接处理。但更改默认值不行。进行变更并运行检查。无需计划或审查。在一行中报告变更、检查、结果以及缺少审查的情况。

• 标准： 行为变更的默认值。

• 深度： 仅在以下触发条件出现时使用：

  1. 对仓库外部消费的合约进行破坏性变更；
  2. 仓库外部产生不可逆影响：持久化数据迁移、资金操作、发送给第三方的任何内容；
  3. 更改了项目视为合约的文件中的规则；
  4. 存在导致不同结构的替代方案。

  此时请阅读 references/deep.md。

一个风险角落只提升其自身的深度，而非整个变更的深度。由你自行提升深度，包括当构建揭示触发条件时；只有用户能降低深度。在降低深度之前，建议你使用的深度。对于刚接触此工作流的人，说明此变更将跳过哪些步骤以及遗留的失败风险。如果他们坚持，按照他们的要求执行，但不得违反硬约束。

2. 计划

在标准和深度模式下，在第一次编辑之前，编写目标、你曾考虑过的非目标，以及验收标准，即证据（第4节）。

根据变更规模调整计划和审查。

仅在真正的分叉点添加决策：列出选项（包括较小的选项），以及选择获胜选项的原因。

将其写入 .agent/<task>/plan.md，每个任务一个目录，并将文件随变更一起提交，除非项目有自己的约定。如果 .agent 在 .gitignore 中，保留该条目，不要强制添加文件。

对于分配的工作，使用提供的计划路径，并引用共享范围和验收标准。 将实现细节保留在那里。将全局任务记录留给协调器处理。 保留现有的规范任务目录。对于委派的计划，默认使用 .agent/<task>/tasks/<slice-id>/plan.md。

当对需求的两种解读需要不同的工作时，在目标中说明你的解读，并将其与验收标准一起展示给用户，然后等待；如果无人能回答，则按你的解读继续，并在交接文档中标明“未确认”。关于真实产品、范围或风险决策的问题，应提供选项、建议和理由，不可默默决定；将答案记录在计划中。

当缺陷原因未知时，查找原因即为任务本身：其验收标准是能够重现缺陷；在重现后计划修复。

3. 构建

• 每一行变更都必须追溯到目标或决策。不需要没人需要的抽象、可配置性或错误处理。
• 如果代码或修复与计划矛盾，立即停止并在明处修正计划，而不是在最后才处理。
• 保持在分配的文件和接口范围内。如果需要更改这些范围，则暂停受影响的工作并请求修订后的分配。
• 并行读取，隔离写入。 为每个并发写入者使用独立的工作树（references/parallel.md）。
• 对于集成工作，对合并后的变更运行检查和审查。通过分片检查并不能证明集成验收通过。
• 如果文档引用了由命令生成的数字，请在数字旁边注明该命令，或让检查重新计算。

对于持久性工作，将检查结果存储在计划旁的 evidence/checks.md 中。 记录标准、命令、修订版本、结果、证据链接以及失效条件。 将发现、分类、审查者身份和修复轮次存储在 evidence/review.md 中。

4. 证据

• 验收标准要指定最廉价但能证明变更效果的真实证据：现有检查变绿、新测试通过，或观察到的结果。说明失败时的表现。
• 默认情况下不需要编写新的单元测试。 仅在以下情况编写：行为是测试可以低成本固定的逻辑，且回归值得防范。对于 UI 渲染和布局、连线与胶水代码、配置、对外部服务的简单调用、一次性脚本和散文，单元测试是错误的检查方式：改为观察结果。
• 对于需要人工点击、输入或调用的功能，必须由未编写该变更的上下文来执行并报告所见内容。提供路径和失败表现，而不是差异或你的说明。矛盾应被视为发现。如果没有这样的上下文：自己执行并粘贴你看到的结果。对于无法触及的表面，在安全的地方执行并说明差距。未执行等同于未检查。
• 当输出是阅读而非运行的对象时（文档、帮助文本、规范），证据应由不具备变更上下文的读者对完成的文件进行冷阅读：将文件作为产品来读，而非作为差异来读。
• 间歇性故障本身就是可复现的证据以及区分性证据。不要为此变更的失败重复运行，直到它通过；也不要要求必须是确定性复现才将其视为一个复现。不是此变更引起的故障应作为命名的后续任务，而不在本变更中修复。
• 在审查前运行检查，在每次修复后运行覆盖该变更的检查，在交接前运行完整检查集。粘贴通过/失败行，而不是完整日志。所有跳过的检查，或通过削弱测试获得的绿色，均不视为通过。

5. 审查

审查者获得整个变更（如果变更分阶段构建，则为整个阶段）、计划和仓库，而不是你的总结或推理。“整个”意味着变更添加、修改或删除的所有文件，包括新的未跟踪文件；对空或不完整差异的审查不是有效的审查。直接深度不需要审查者；标准深度需要一个。

无法获得独立的审查或阅读： 优先使用可用的独立上下文。 对于缺失的角色，审查上面指定的完整工件，而不是你对该工作的回忆。 在一轮自我审查中应用缺失角色的任务简报。 标记为“自我审查，非独立”，并报告缺失的独立角色。 向用户提供任务简报，以便在其他地方执行。 此回退不会覆盖更严格的用户、项目或主机要求。

逐字传递以下任务简报：

对照其计划审查此变更。报告每个发现，包括文件:行号，
标记为阻塞性（错误行为、违反合约、计划外的工作）
或非阻塞性。请勿修改代码。
1. 哪里可能出问题？意外输入、触及信任边界的恶意输入、
   其所调用内容的失败、从差异外部假设的事实。
2. 现有测试是否被削弱？
3. 新行为是否由证据（测试或观察到的结果）证明，
   且该证据在没有此变更时会失败？不要再要求更多。
4. 是否有任何内容超出目标或属于非目标？
5. 计划本身是否有误？

先分类再修复。 对照引用的代码确认每个发现。拒绝误读，以及要求执行非目标所排除工作的发现，每条一行。缺失测试是非阻塞性的，除非它保护了一个已确认的正确性错误。当没有确认的阻塞性发现时，变更即告关闭。

审查他人的变更： 使用相同的任务简报，将其描述作为计划；缺少非目标是一个发现。先分类，然后将确认的发现交给作者；不要自己修复。

6. 修复与停止

• 修复应解决确认发现所引用的根本原因，且在同一缺陷出现的所有位置都进行修复。
• 新机制是新工作：新的检查、工具、防护、抽象或测试文件应成为命名的后续任务，而非修复的一部分。仅针对已确认的正确性错误添加一个会失败的测试，并扩展现有的测试文件。
• 每次修复后，审查者仅重新检查该修复：被引用的发现是否已解决？修复是否引入了新问题？一次修复加其重新检查算作一轮。

当以下情况出现时，停止并向用户询问：一轮修复后确认的发现仍未解决；修复扩展到计划未涵盖的文件或机制；或者第三轮后仍有阻塞性发现。逐字提交未解决的发现、已尝试的方法、出错的真实输出、选项（修订计划、接受已记录的风险、将该项目作为后续任务删除、拆分机制等）以及你的建议。决不可悄悄降低标准。

7. 关闭：交接文档

交接文档是最终的变更描述。如果存在协调器，HANDOFF.md 提供恢复指令。 应用选择性读取和记录生命周期规则，参见 references/writing.md。 与协调器协作时，返回有来源的记忆候选，并将共享更新留给协调器。

在标准和深度模式下，变更描述包含：

• 目标，以用户现在可以做什么的形式表述，以及非目标；
• 验收标准，以及证据实际显示的内容；
• 哪些内容无法检查，以及原因；
• 审查者是谁，或“自我审查，非独立”，或未进行审查，对于人工驱动的路径同样处理；
• 用户降低的深度，以及你在他们坚持之前展示的内容；
• 未修复的非阻塞性发现，每条一行；
• 残留风险；
• 在深度模式下，当前的回滚方案。

对于分配的工作，返回工件路径和修订版本、证据、审查状态、未解决的请求以及活动中的或未知的修改命令。 向协调器报告本地完成情况。不要声称完成了整个任务。

用户添加的审查、安全或编排工具是对独立审查的补充，绝不替代它。