用任务规格协议解决 Planner 和 Implementer 之间对不上的问题

在构建完全自动化的 Agent 协作系统时，我发现一个很头疼的问题：Planner（规划者）分发任务给 Implementer（执行者）时，即使指令看起来很清晰，依然有大概 1/3 的执行结果是跑偏的。我尝试通过优化 Prompt 来解决，但效果一般。最后我意识到这根本不是 Prompt 的问题，而是缺乏一个结构化的“契约”。通过引入一套 Task Spec 协议，要求 Planner 必须输出特定格式的 Schema，且 Implementer 在动代码前必须原样回显确认，我的重试率直接从 31% 降到了 7%。

为什么自然语言指令在 Agent 协作中会失效

我的系统架构是让一个 Planner 读取代码库和待办列表，将目标拆解为具体任务，然后交给多个独立的 Implementer 子 Agent 执行。为了节省成本并保持专注，我特意让 Implementer 处于“冷启动”状态，它们不共享上下文窗口，且可以并行运行 4-5 个。

在这种设定下，任何 Planner 没写出来的细节，对 Implementer 来说都是不存在的。我回顾了 2026 年春季的 120 组任务记录，数据非常扎心：

• 一次性通过验证： 68 次 (57%)
• 虽完成但范围跑偏或改错文件： 37 次 (31%)
• 直接放弃或产出无用： 15 次 (12%)

最贵的是那 31% 的误差。比如 Planner 简单说一句“给 Webhook 发送端加重试逻辑，简单点就行”，结果 Implementer 信心满满地写了 400 行测试代码，搞了一套包含指数退避和熔断机制的通用重试工具类，而实际上代码库里两层目录之外已经有一个现成的重试助手了。

最让我崩溃的一次实操是，Planner 让 Implementer “修复 export 任务中不稳定的日期解析”。项目里有两个 export 任务，一个是没人碰过一年的旧 CSV 导出，另一个是真正出问题的 JSON 导出。Implementer 搜到了旧的 CSV 文件并将其“修复”了，结果验证 Agent 觉得代码逻辑自洽，直接通过。导致那个真正的 Bug 在接下来的三天里依然在 CI 里随机报错。

这件事给我最大的启发是：在冷启动的任务传递中，发送方认为的“显而易见”，对接收方来说完全是“未知”。

把任务传递变成接口定义

我决定不再把任务指令当成一条消息，而是把它当成一个 API 接口。如果这两个 Agent 是两个微服务，我绝对不会允许它们用纯文本通信。于是我设计了一套任务规格协议（Task Spec Contract），要求 Planner 必须输出一个符合以下 YAML 结构的代码块：

task_id: T-2026-0914-03
goal: >
  使 JSON 导出任务的日期解析具有确定性，
  从而解决 `test_export_dates_across_dst` 随机失败的问题。
why: >
  该不稳定测试每天导致 CI 失败约 2 次；
  根本原因是 DST（夏令时）转换期间的日期时间处理过于简单。
scope:
  allowed_paths:
    - src/export/json_exporter.py
    - tests/test_export_dates.py
  expected_outcome: >
    修改 json_exporter.py 中的解析逻辑，
    确保 `test_export_dates_across_dst` 在所有时区环境下均通过。

这套方案的核心在于三个细节：
1. 强制限定路径（allowed_paths）： 明确告诉 Implementer 只能动哪几个文件，直接杜绝了上面提到的“改错文件”问题。
2. 明确因果（why）： 告知背景能让 Implementer 在遇到多种实现方案时，选择最符合原意的那一个。
3. 回显确认机制： 在 Implementer 开始写代码前，必须把这个 Spec 完整地 echo 回来。如果它回显的内容与 Planner 预期不符，系统直接拦截，不需要浪费 Token 去跑错误的代码。

实操后的几个关键结论

通过这次重构，我总结了 Agent 之间交接任务的几个经验，希望能帮到同样在折腾多 Agent 系统的朋友：

首先，结构化数据比自然语言可靠得多。
当你需要 Agent 严格执行某个范围的操作时，不要用“请尽量只修改 X 文件”这种祈使句，而要用 allowed_paths: [X] 这种硬性约束。

其次，验证 Agent 需要同样的输入。
一个意外的收获是，这套 Spec 成了验证 Agent 的完美输入。验证 Agent 不再仅仅看 Diff，而是对比“预期结果（expected_outcome）”与“实际变更”，判定标准从“代码写得对不对”变成了“需求是否达成”。

最后，关于成本与效率的权衡。
虽然增加这套协议会让 Planner 消耗更多 Token，但相比于 31% 的错误率导致的反复重试和人工排查成本，这点开销几乎可以忽略不计。

目前我的系统运行的是 2026 年 9 月版本的 Claude Code 2.x，这套机制在并行处理任务时表现非常稳定。如果你也在做类似的任务拆解系统，建议直接放弃纯文本指令，尝试建立一套简单的 Schema 契约。