用任务规格协议强制执行一致性，避免 Agent 误解的 7% 奇迹

在构建 Agent 协作系统时，我发现即使 Planner 给出的指令看起来清晰无误，Implementer 仍有约三分之一的执行结果偏离预期。经过多轮优化 Prompt 后，我意识到问题不在于表述的模糊性，而在于缺少结构化的约束机制。于是，我设计了一套任务规格协议（Task Spec），要求 Planner 输出符合特定 YAML 模式的 Schema，而 Implementer 在执行前必须原样回显确认。这一改动将重试率从 31% 降至 7%，效果显著。

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

我的系统中，Planner 将任务拆分后交由多个独立的 Implementer 并行处理，这些 Agent 处于“冷启动”状态，无共享上下文窗口，且可同时处理 4-5 个任务。在这样的设定下，Planner 未明确说明的细节对 Implementer 来说完全不存在。我回顾了 2026 年春季的 120 组任务记录，发现：

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

例如，Planner 指令 “给 Webhook 发送端加重试逻辑，简单点就行” 时，Implementer 却实现了一个包含指数退避和熔断机制的通用工具类，而实际项目中已经存在类似的重试助手。更严重的情况是，Planner 要求 “修复 export 任务中不稳定的日期解析” 时，Implementer 修复了一个旧 CSV 导出任务，而真正的 JSON 导出 Bug 未被触及，导致 CI 后续持续报错。

2020 年，Pioneer Square Labs（PSL）在验证创意时，有九成以上的测试方案被直接淘汰。他们在内部邮件中提到，简单的模板化验证可以确保数据归因于价值主张的共鸣，而不是执行细节的偶然因素。这与我的 Agent 协作问题有相似之处：自然语言指令的模糊性导致 Implementer 误解需求，而结构化协议则能显著降低这种误差。

如何通过任务规格协议降低通信误差？

我将任务传递视为 API 接口调用，而不是简单的信息发送。为此，我设计了任务规格协议（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，若不匹配则系统直接拦截，避免无用的计算。

实践后的关键心得

1. 结构化数据优于自然语言：复杂需求不应依赖 “请尽量只修改 X 文件” 这样的祈使句，而应使用 allowed_paths: [X] 形式的硬性约束。
2. 验证 Agent 需要统一输入：验证 Agent 不再仅检查 Diff，而是比对 “预期结果（expected_outcome）” 和 “实际变更”，标准从 “代码是否正确” 转变为 “需求是否达成”。
3. 成本与效率的权衡：虽然协议增加了 Planner 的 Token 消耗，但相比 31% 的错误率带来的重试和排查成本，这种开销几乎可以忽略不计。
4. 并行处理的稳定性：目前使用的 2026 年 9 月版 Claude Code 2.x 在并行处理任务时表现稳定，建议类似系统直接采用 Schema 契约而非纯文本指令。