最近我在整理多 Agent 协作开发的流程时，遇到的最大问题并不是“没有 Agent 会写代码”，而是另一件更细碎、也更容易被忽略的事：文档会乱。
一个 Agent 写了计划，另一个 Agent 去审查；计划通过以后，又有 Agent 根据它去开发；开发完成后，还要有人继续 review 实现。每一步都看起来很自然，但只要文件稍微多一点，问题就会悄悄冒出来。
- 已经完成的 plan 又被拿去重新 review。
- 还没有通过 review 的 plan 被直接拿去开发。
- task 已经完成，却还混在待修复列表里。
- reviewer 还没写完的 review，被 resolution agent 提前读取。
- 最麻烦的是：review 文件写完了，并不等于 review 通过了。
这些问题单独看都很小，可它们叠在一起时，就会让协作变得像一张没收好的桌面：东西都在，却很难安心继续往下做。
于是我把流程整理成了一套很朴素的办法：用目录和标记，给文档做一个文件状态机。
核心想法
这套机制只有两个原则。
第一，目录表达生命周期。文件放在哪里，就表示它现在处于哪个阶段。
第二，标记表达处理状态。文件末尾的 HTML 注释告诉 Agent：这个文件是否已经准备好、review 是否已经完成、结论又是什么。
目录负责“阶段”，标记负责“状态”。这两件事分开以后，每个 Agent 都可以少猜一点，多确定一点。
docs/
development-plans/
development/
ready/
complete/
development-tasks/
development/
complete/
它看起来不复杂，甚至有点笨。但对多 Agent 协作来说，这种笨办法反而很可靠。因为文件系统本身已经在告诉大家：这里的东西该不该被处理。
Plan 的生命周期
Plan 是开发前的设计文档。它应该说明目标、范围、实现顺序、边界条件、测试计划和风险。
我把 plan 分成三个阶段：
| 目录 | 含义 |
|---|---|
development | 正在规划，或者等待 plan review / 修复 plan review。 |
ready | plan review 已通过，等待开发。 |
complete | 对应 task 和代码已经完成，task review 也已通过。 |
一个 plan 只能在其中一个阶段里。这样做的好处是，开发 Agent 不需要在一堆文件里判断哪个能做，它只需要看 development-plans/ready。
plan 文件末尾会出现类似这样的状态标记：
<!-- PLAN_STATUS: READY_FOR_REVIEW -->
这表示计划已经写完，可以交给 reviewer 审查。
<!-- PLAN_STATUS: READY_FOR_DEVELOPMENT -->
<!-- PLAN_READY_AT: YYYY-MM-DD -->
这表示计划已经通过 review，可以进入开发。
<!-- PLAN_STATUS: DEVELOPMENT_COMPLETED -->
<!-- PLAN_COMPLETED_AT: YYYY-MM-DD -->
这表示对应开发和实现 review 都已经完成，plan 可以归档。
Task 的生命周期
Task 是真正执行开发时留下的执行说明和记录。它不是提前单独准备好的文档，而是由负责编写代码的 Agent 在读取已经通过 review 的 plan、开始实现功能时同步生成。
它的状态比 plan 更简单：
| 目录 | 含义 |
|---|---|
development | 正在开发，或者等待 task review / 修复 task review。 |
complete | task review 已通过，开发完成归档。 |
task 不需要 ready 层。因为它的起点就是“开发 Agent 正在根据 ready plan 写代码”：只要 task 出现在 development-tasks/development，就代表实现工作已经开始。
task 文件的状态标记也保持简单：
<!-- TASK_STATUS: READY_FOR_REVIEW -->
表示代码和 task 文档都已经完成，可以进入实现 review。
<!-- TASK_STATUS: REVIEW_APPROVED -->
<!-- TASK_COMPLETED_AT: YYYY-MM-DD -->
表示实现 review 已通过，开发任务完成。
Review 为什么需要双标记
这里是我觉得最重要的一点：review 文件需要同时表达两件事。
- review 是否已经写完。
- review 的结论是什么。
如果只用一个 READY_FOR_RESOLUTION，就会混淆“文件写完了”和“结论通过了”。所以我把它拆成两个标记：
<!-- REVIEW_STATUS: READY_FOR_RESOLUTION -->
<!-- REVIEW_RESULT: APPROVED -->
REVIEW_STATUS 只表示 reviewer 已经写完，resolution agent 可以读取。
REVIEW_RESULT 才表示结论。通常有三种：
APPROVED：无阻塞问题，可以进入下一阶段。APPROVED_WITH_NOTES：整体通过，但有非阻塞建议或后续事项。CHANGES_REQUESTED：存在必须修复的问题，不能继续推进。
这个拆分很小，却能避免很多误会。resolution agent 不会因为看到 review 文件存在，就误以为它已经通过；也不会读取 reviewer 还没写完的半成品。
两个 Reviewer
为了降低单个 Agent 漏看问题的概率，我让同一个 plan 或 task 接受两个独立 review。
xxx.claude-review.md
xxx.cline-review.md
两个 review 都完成后，resolution agent 才能决定是否推进。
| Review 结果 | 处理方式 |
|---|---|
两个都是 APPROVED | 进入下一阶段。 |
存在 APPROVED_WITH_NOTES | 进入下一阶段，但把 notes 记录回主文件。 |
任一为 CHANGES_REQUESTED | 留在 development，等待修复。 |
| 任一缺失或缺少结论标记 | 不移动，不处理。 |
这让流程变得慢了一点，但也稳了一点。对需要长期维护的项目来说，我更愿意把这一点时间花在确定性上。
完整流转
把这些规则放在一起，完整流程大概是这样：
Plan generation
-> development-plans/development
-> PLAN_STATUS: READY_FOR_REVIEW
Plan review
-> *.claude-review.md
-> *.cline-review.md
-> REVIEW_STATUS + REVIEW_RESULT
Plan resolution
-> 如果双 review 通过
-> development-plans/ready
-> PLAN_STATUS: READY_FOR_DEVELOPMENT
Task development
-> development-tasks/development
-> TASK_STATUS: READY_FOR_REVIEW
Task review
-> *.claude-review.md
-> *.cline-review.md
-> REVIEW_STATUS + REVIEW_RESULT
Task resolution
-> 如果双 review 通过
-> development-tasks/complete
-> TASK_STATUS: REVIEW_APPROVED
Plan completion
-> 对应 plan 从 ready 移到 complete
-> PLAN_STATUS: DEVELOPMENT_COMPLETED
这就是一个不依赖复杂系统的文件状态机。它只需要目录、命名规则和几行注释。
给 Agent 的工作流边界
在实际使用时，我不会把所有规则都塞进一段巨大的提示词里，而是拆成几类固定工作流。
- Plan generation：只生成计划，不开发代码。
- Plan review：只审查
development-plans/development里已经标记 ready 的计划。 - Plan resolution：只处理已经写完且带结论的 review。
- Task development：只从
development-plans/ready开始开发。 - Task review：只审查带有
TASK_STATUS: READY_FOR_REVIEW的任务和代码。 - Task resolution：只在 review 完成且通过后移动 task，并同步归档对应 plan。
每类 Agent 只看自己该看的目录，只改自己该改的文件。这个边界比“请谨慎一点”更有用，因为它把谨慎变成了可执行的规则。
一个小索引
如果 review 文件越来越多，还可以加一个索引脚本，定期扫描活跃目录：
development-plans/development
development-tasks/development
然后生成一个 docs/review-index.md，把待处理内容分成几类：
Ready For Resolution
Missing Review Result
In Progress
这样 resolution agent 每次先看索引，就能知道哪里可以处理，哪里还应该安静地等一等。
实践之后的感受
这套结构最大的好处，是让每个 Agent 都只处理自己该处理的阶段。
Plan generator 不碰 review 文件。Plan reviewer 不修改 plan。Resolution agent 不读取未完成 review。Development agent 只从 ready plan 开始。Task reviewer 不审查已归档 task。
换句话说，多 Agent 协作不再完全依赖“大家都记得规则”。文件系统本身承担了一部分流程控制能力。
它当然不是什么精巧的系统。它只是把计划、任务和评审放进不同的抽屉里，再给每份文档贴上一张小标签。但正因为它朴素，Agent 才更容易遵守，人也更容易检查。
结尾
如果长期使用 AI Agent 做开发，文档就不只是副产品，而是协作协议。
你需要告诉 Agent 哪些文件可以读，哪些文件不能读；哪些文件可以改，哪些只能保留原文；什么状态可以进入下一阶段，什么状态必须停下来。
用目录表达阶段，用标记表达状态，用 review 双标记表达结论。最后得到的，是一个很小、很安静，但能让多个 Agent 稳定协作的状态机。
plan development
-> plan ready
-> task development
-> task complete
-> plan complete
对人来说清楚，对 Agent 来说也清楚。这样就很好。
No comments yet.