AI 编程智能体需要交接合同而非更多提示词

当 AI 编码 Agent 说“完成了”，它并没有真正完成。真正的完成是：下一个接手的人或 Agent 能够无需重新还原“改了什么”“依赖什么”“测了什么”“哪些还不确定”，就能直接接受这份工作。

这个区别催生了交接合同（handoff contract）的需求：一份小巧、结构化的制品，随每个补丁一起流转。它记录范围、假设、证据、集成状态、剩余风险，以及下一轮验收决策的责任人。更好的 prompt 能提升代码生成质量，但无法替代这种责任的转移。

Prompts 解决的是生成，而非验收

团队面对 Agent 结果不理想时，常见的反应是再加一条指令：跑测试、检查边界情况、不要动无关文件、解释 diff。这些指令可能有帮助，但本质上仍在描述“发送方应该做什么”，并没有定义“接收方必须能够验证什么”。

这就是为什么交接应该融入生产软件交付工作流——代码、证据、集成状态、验收条件作为一个整体流转。没有这份上下文的补丁可能在本地正确，但集成成本依然很高。

DORA 对 Google 软件工程师 1,110 份开放式回答的分析发现：在初始创建阶段节省的时间，往往被重新消耗在审计、验证和迭代上。这项研究是针对特定群体的定性证据，并非通用生产力基准，但它描述了一个许多团队都熟悉的模式：更快的产出可能只是把工作推到了下游，而不是真正消除它。

同一份 DORA 分析还报告了一个矛盾：高 AI 采纳率带来更高吞吐量，同时也带来更高的交付不稳定性。其更广义的软件交付指标框架特意同时衡量吞吐量和稳定性。“Agent 生成了更多代码”这句话几乎不说明任何问题——系统能否安全吸收这些代码，才是关键。

一个有效的交接定义

2026 年一项关于 Agentic EDA（电子设计自动化）的调查，从接收方角度定义了有效交接：转移的制品必须满足下一阶段的验收条件，并携带足够的上下文、证据和来源信息，以便该阶段顺利推进。这篇论文讨论的是 EDA，而非通用应用开发，但其交接视角为软件团队提供了一条有用的设计规则：

从接收方视角验证交接，而非仅从发送方视角验证工作。

这条规则将“完成”的定义从“Agent 是否遵循了 prompt”转变为：“下一位消费者能否做出知情的验收决策？”

Agent 交接合同的五个组成部分

1. 范围（Scope）

记录确切的需求、自有文件、禁止修改的文件。“实现认证”不是范围。“在这三个模块中添加 refresh-token 轮换，且不改变公开的 session schema”是。

范围防止两种相反的失败：把不完整的工作藏在宽泛的“已完成”声明背后，以及引入未要求的变更让审查更困难。

2. 假设（Assumptions）

列出补丁依赖的条件：基础 commit、接口版本、环境、fixture、feature flag、数据结构或顺序保证。假设不是耻辱；隐形的假设才是等待集成时刻爆发的缺陷。

3. 证据（Evidence）

包含实际运行的检查及其重要结果。“测试通过了”信息量太少。一份有用的凭证应指明：执行的命令、退出状态、相关用例数量，以及任何刻意未运行的验证。

证据应具备可复现性且与风险成比例。单行配置变更很少需要全系统压力测试。持久化或并发变更则仅靠类型检查远远不够。

4. 集成状态（Integration State）

说明补丁是单独测试的、应用到了预期的基础分支的、与相邻变更合并过的，还是通过了它所修改的共享边界（shared seam）验证的。本地 green 和集成 green 是两种不同的状态。

在生产 AI 评估和监控系统中，这一点更加重要——因为 prompt 版本、评估结果、漂移信号、回滚状态必须在每次模型或工作流变更后都能保持一致。一个本地成功的 prompt 或评估器，还不是一次已接受的生产变更。

5. 剩余风险与验收责任人

指出尚不明确的事项、下一位消费者，以及该消费者拥有的决策权。“无已知风险”只有在证据支持时才可信。否则应如实说明边界：迁移行为未被演练、浏览器兼容性尚未验证、相邻分支尚未合并。

验收责任人可以是人工 reviewer、集成 Agent、发布门禁或 on-call 工程师。关键在于责任人必须是明确的。

将完成消息转化为可验收交接的五个字段。

一份可复制的交接格式

合同不需要新的平台。从 PR、任务制品或 Agent 输出中的版本化 YAML 块开始：

handoff_version: 1
work_item: AUTH-217
producer: coding-agent-session-42
base_commit: 8d31c2a

scope:
  requirement: Rotate refresh tokens after every successful use
  owned_paths:
    - src/auth/refresh.ts
    - tests/auth/refresh.test.ts
  forbidden_paths:
    - src/auth/session-schema.ts

assumptions:
  - The token store provides compare-and-swap semantics
  - Existing session payload fields remain stable

evidence:
  - command: npm test -- tests/auth/refresh.test.ts
    exit_status: 0
    result: 12 passed
  - command: npm run typecheck
    exit_status: 0

integration_state:
  applied_to_base: true
  adjacent_changes_combined: false
  shared_seam_verified: false

residual_risk:
  - Concurrent refresh from two browser tabs was not exercised

acceptance:
  owner: integration-agent
  next_gate: Combine the session-store patch and run the auth integration suite

这种格式让缺失一目了然。如果 shared_seam_verified 为 false，工作流无需猜测是否有人检查过；如果某条命令缺失，接收方可以要求最小化的有效检查，而不是重新跑一遍全部。

“Agent 完成”和“交接有效”是两种不同的状态

想象两个 Agent 并行工作。一个修改了序列化器，另一个在其消费者端添加了验证。两者都跑了针对性测试，都报告成功，且都是真话。但合并后，序列化器输出的值被新验证器拒绝了。

两份本地报告都无法捕获这个失败，因为失败本身就存在于两份工作之间的交接处。交接合同暴露了缺失的状态：

合同并不能神奇地防止不兼容。它防止的是工作流把未集成的工作误标为已接受的工作。

从下一位消费者视角验证合同

一个有效的接收方循环有四个步骤：

1. 检查完整性：五个部分是否都存在，或者缺失的部分被明确标注了？
2. 将声明与制品对照：diff、基础 commit 和测试凭证是否支撑了总结？
3. 运行成本最低的区分门禁：在重新跑整个仓库之前，先测试共享边界。
4. 接受、退回或上报：记录决策及其理由，而不是在下游默默修复补丁后沉默。

最后一步很重要。如果集成者反复修复不完整的交接，却没有退回信号，则生成 Agent 永远不会收到有用的边界约束，组织也在隐藏工作流的真实成本。

不要一上来就建一个交接服务。先在这样一个工作流中加上 YAML 块：并行 Agent 触及共享接口的那种。只要求那些能改变验收决策的字段。跟踪几个真实任务的三类结果：

• 接收方需要重建缺失上下文的频率；
• 本地 green 变成集成 red 的频率；
• 达到验收决策所需的时间。

然后当某个缺失字段导致真实歧义时，再修订合同。交接合同应该随时间变得更小、更精准，而不是变成仪式性的 paperwork。

常见问题

这不就是 PR 模板吗？

它可以存在于 PR 中，但角色更广。PR 模板通常围绕人工 review 组织。交接合同是一种机器可读的交接协议，适用于任何生产者和下一验收阶段之间的传递，包括 PR 存在之前的 Agent 到 Agent 工作流。

Agent 能否自行判断自己的交接是否有效？

Agent 可以验证完整性和附加证据。但最终有效性属于接收方，因为只有接收方才拥有下一阶段验收条件的决策权。

每个任务都需要五个部分吗？

是的，但字段可以很短。对于很小的文档编辑，integration_state 可能就一句话，residual_risk 可能是“未发现风险”。保持 schema 稳定是有用的；让证据与风险成比例可以让它保持实用。

真正的进展单位

代码生成是一种活动。被接受的变更是进展。

一旦团队开始衡量这两者之间的转移，下一步改进往往不是更长的 prompt，而是边界上更清晰的合同：什么移动了、它依赖什么、什么证明了它、还有什么未集成、以及谁能下一步验收它。