一个任务做到一半，原来的 Agent 会话太长、工具环境不对，或者你想换一个模型继续。最自然的动作是把聊天记录复制给下一个 Agent，然后说“接着做”。

我实际做过几次这种交接之后，结论是：聊天记录不是任务状态。

最近一次是把 AppPilot 的优化工作从 Claude Desktop 交给 Codex。接收时最重要的信息不是“上一轮聊了什么”，而是代码到底在哪、哪些改动已经提交、哪些测试真的跑过、当前失败点是什么、哪些决定还没有做。

一、交接的第一步是找到真实工作区

一个任务可能在主 checkout、独立 worktree、另一个 Agent 的临时目录，甚至在一个还没合并的分支里。你要交接的不是一个“项目名”，而是一份可以打开的工作区。

完整的交接至少要回答：

  • 仓库地址是什么；
  • 当前 worktree 的绝对路径；
  • 当前分支名；
  • 本地分支和远端分支是什么关系；
  • 基于哪个提交开始；
  • 是否有未提交修改、未跟踪文件或子模块变化。

那次 AppPilot 交接里，主 checkout 还停在比较旧的提交，真正的工作在一个单独的 worktree 分支上。如果接收方只看主目录，看到的是一个与任务无关的旧快照，很容易得出“这些功能根本不存在”的错误结论。

所以交接时不要只说“代码在本地”。要给一条可以直接 cd 进去并执行 git status --short --branch 的路径。

二、提交记录不等于完成，但它是事实

聊天里最不可靠的一句话是“已经做完了”。更可靠的是提交历史。

接收方至少要看：

  1. 最近几次提交分别改了什么；
  2. 是否存在只改了工作区、没有提交的改动；
  3. 是否有生成物、日志、截图或诊断文件没有入 Git；
  4. 当前分支是否已经推送；
  5. 分支与最新主干的差距。

在 AppPilot 那次交接中，上一阶段已经有“后台截图 + 前台输入 + 恢复原应用”的提交，后来又出现任务模块、AppProfile、广告播放、宝箱、饭点补贴等一串提交。每一笔提交都比“优化得差不多了”更能描述当前能力。

但这还不够。提交只说明代码被保存过，不说明测试通过，也不说明实机验证成功。

三、测试证据必须能复现

“测试通过”不能只作为结论出现。至少要带上：

  • 执行的具体命令；
  • 在哪个目录执行；
  • 使用的运行时版本；
  • 通过和失败的数量；
  • 失败是否与当前改动有关；
  • 哪些测试只是模拟，哪些是实机。

AppPilot 这类项目尤其容易混淆：单元测试通过，只能证明规则和状态转换符合预期；真机窗口、OCR、焦点切换和广告页面仍然可能失败。

所以交接文档里应该明确分开：

  • 离线测试；
  • 设备诊断；
  • 实机成功案例；
  • 尚未跑通的端到端路径。

这不是为了让报告更好看，而是为了阻止下一个 Agent 把“模拟测试通过”写成“真实自动完成”。

四、日志和诊断目录是交接资产

开发任务往往会把最重要的信息写在临时日志里：哪一页 OCR 错了，哪一次窗口移动了，哪一回点击后没有回执，哪一个分支返回了未知状态。

这些文件不一定适合入库，但一定要告诉接收方它们在哪里、如何脱敏、是否是当前版本产生的。

那次交接里，接收方需要知道运行记录目录、诊断轮次、日志文件、设备状态文件和模型调用的默认网关。没有这些，接手的人会从干净环境重新跑一遍，重复上一轮的所有失败。

同样重要的是说明哪些内容不要读：包含账号信息的截图、带会话签名的 URL、Cookie、Token、真实设备标识。交接材料里可以写“凭证由当前环境提供”，不能把凭证本身复制进去。

五、环境假设是隐性代码

很多“换了 Agent 就失败”的问题不是代码变了，而是环境假设没有交接：

  • Node 必须用哪个版本；
  • 是否需要 .nvmrc 和特定 PATH；
  • iPhone 镜像是否必须在前台；
  • macOS 需要哪些屏幕录制或辅助功能权限；
  • 测试是否只能在真实设备上跑；
  • 模型网关是否必须可用；
  • 某些路径是否受沙箱限制。

环境假设最好写成一块独立的“开工前检查”，而不是散在聊天记录里。接手 Agent 的第一项工作应该是验证这些假设，而不是直接改代码。

六、未决问题要明确，不要藏在暗示里

一个负责任的任务交接，应该直接列出：

  • 已知失败点；
  • 还没做的验证；
  • 需要人决定的产品问题；
  • 不应该在本次任务里顺手改的东西；
  • 仍有人或其他会话修改的文件；
  • 哪些提交不能动、哪些分支不能删。

那次 AppPilot 交接里，白天推进出的工作区和主 checkout 状态不同，还涉及后续架构边界。接收方不能因为想“整理干净”就 reset、rebase 或删除别人的 worktree。

“不要做什么”与“要做什么”同样重要。

七、我给交接包用的一张模板

目标：
非目标：

仓库：
worktree：
分支：
基线提交：
工作区状态：
已推送：是/否

已验证：
- 命令：
- 结果：
- 证据位置：

未验证/失败：
- 现象：
- 已排除：
- 下一步：

环境前置：
- 运行时：
- 权限：
- 外部服务：

未决决定：
- ...

限制：
- 不修改：
- 不发布：
- 不使用：

这份模板看起来比一句“继续做”麻烦，但它能避免几类最昂贵的错误：在错误分支上重做、忽略未提交改动、把模拟当实机、重复使用过期环境、擅自 revert 别人的修改。

八、接收方先审计，再动手

一个成熟的接手流程，应该以只读审计开始：

  1. 确认仓库、worktree、分支和远端；
  2. 读最近提交和 diff；
  3. 找未提交和未跟踪文件；
  4. 复现最少一组测试；
  5. 检查日志与诊断；
  6. 验证环境；
  7. 把发现与交接包对齐；
  8. 确认没有未知修改后，再编辑。

如果发现当前状态和交接包不一致，第一反应应该是停止并询问，而不是用自己的理解重写。

这套顺序也适用于从 Claude 交给 Codex、从 Codex 交给 Claude、从人交给 Agent。换的是执行者，不是工程纪律。

九、交回来的时候，也要留下状态

任务没有完成的交接同样需要产物：

  • 新提交或明确的未提交 diff；
  • 最新测试结果；
  • 新增的诊断和失败样本；
  • 更新后的未决问题；
  • 哪些文件被修改；
  • 下一个接手者应该从哪里开始。

如果一轮工作只有聊天记录，没有代码和证据，那它更像一次讨论，而不是一次可继续的工程任务。

最后

多 Agent 协作真正需要管理的不是“谁更聪明”，而是任务状态能不能跨会话存活。

好的交接不是把上下文塞得更长，而是把事实放到正确的位置：代码放仓库，日志放诊断目录，验证放命令和结果，决定放文档，授权留在当前用户手里。

这样即使原来的会话消失，任务也不会跟着消失。