Agent 干到一半，上下文满了。或者你想换个模型试试，或者干脆想开三个并行跑。
新开一个窗口，第一件事是把前因后果重讲一遍。
讲完你发现漏了三件事：哪个分支是活的、线上跑的是哪个版本、上次那个测试到底跑没跑过。
重讲一遍的成本不是时间，是讲到一半你自己也记不清了。
这篇讲一套让这个动作消失的机制。跑通之后，换 agent 只需要给两样东西：仓库地址，和任务号。
一句话版本
仓库保存状态，Issue 认领任务，PR 留下交付证据。
三件事各有分工。
仓库回答“现在什么情况”。Issue 回答“谁在做什么，做到什么算完”。PR 回答“到底做了没有，凭什么说做了”。
这三个问题原来都存在你脑子里和聊天记录里，所以每换一次人就得重新装载一遍。挪进仓库之后，新 agent 自己读就行。
说实话这套东西没什么新东西，就是人类团队交接那一套。有意思的是，人类团队可以靠口头补齐文档的空白，agent 不行。agent 只能读到写下来的部分。
所以这套机制对 agent 的要求，比对人严格得多。
一、每类信息只维护一个地方
先定文档分工。这一步看着琐碎，但后面所有问题都从这儿来。
文件 | 负责回答什么 |
规则文件（如 AGENTS.md） | 长期不变的：技术栈、边界、部署授权、禁止事项 |
各家 agent 的入口文件 | 一句话指向规则文件，不重复内容 |
交接文件（如 docs/handoff.md） | 当前状态：做到哪、线上哪版、下一步是什么 |
待办文件 | 任务优先级、范围、验收条件 |
UI 规则 | 菜单、排版、组件、移动端适配 |
数据约定 | 数据来源、统计口径、缺失值怎么处理 |
发布记录目录 | 历史版本与验证证据 |
别这么干。写一句“规则见 AGENTS.md”就够了。
原因很简单：同一件事写在两个地方，早晚会不一致，而 agent 不会问你该信哪个。
它会挑一个信。挑哪个取决于读取顺序，不取决于哪个是对的。
踩坑：交接文件里同时躺着新旧两份
这是我见过最容易犯、代价也最直接的错。
交接文件写着写着就变成了流水账。这周的交接追加在上周下面，两份都在，都写着“当前状态”。
人扫一眼就知道哪份是旧的——看日期，看语气，看哪个更靠下。
agent 看不出来。
它会把上周已经做完的任务当成这周的目标，然后兴致勃勃地把一个已经合并的功能重新实现一遍。
旧记录必须移走，不是标注“已过期”。
标注其实没用。agent 读到“已过期”三个字，也读到了下面的任务描述，两者在它眼里权重差不多。移到版本记录目录里去，交接文件永远只有一份当前状态。
二、交接必须写没完成的部分
大部分人的交接长这样：“这版做完了，可以部署。”
这句话信息量约等于零。
固定成模板，每次结束工作照着填：
字段有点多，不过每一条都是被坑出来的。
其中最关键的是把这五个状态分开：
代码写完 → 测试通过 → PR 合并 → 部署成功 → 线上验收通过。
这五个不能互相替代，一个都不能省。
大多数交接翻车都是同一个模式：agent A 报“做完了”，实际意思是代码写完了。agent B 读到“做完了”，理解成已经上线，于是从下一个任务开始接。
中间三个状态全被跳过。等发现的时候，线上跑的还是三天前那版，而两个人都以为已经发布了。
我现在的习惯是，交接里凡是出现“完成”两个字，后面必须跟一个限定词。完成到哪一步，写清楚。
中途换人怎么办
不用为了交接强行合并。
先把有效代码提交并推送到任务分支，没做完的开一个 Draft PR 挂着。
Draft PR 的价值在于它是个公开的、带 diff 的、可以被下一个 agent 直接读到的现场。比在交接文件里用文字描述“我改了 utils 里的三个函数”精确一百倍。
三、新 Agent 开工前先核对事实
这条是给 agent 的规则，写进规则文件里，让它每次开工自己执行。
顺序固定：
- 读入口文件、规则文件、最新交接、当前任务
- 检查工作区状态、远端主分支、开放的 PR 和任务认领情况
- 核对线上版本是不是文档里说的那个
- 用两三句话说清“现在什么状态、我准备做什么、哪些不能动”，然后再动手
第 4 步别省。它看着像形式主义，实际是个廉价的对齐检查——如果 agent 的复述跟你的理解不一样，你能在它写第一行代码之前就发现。
踩坑：agent 的默认行为是相信文档
文档和实际状态冲突的时候，agent 会信文档。
这个默认值在大多数时候是对的，但在交接场景里非常危险。文档说“已部署到生产”，实际没有；文档说“main 分支是干净的”，实际有人推了三个提交上去。
agent 按文档动手，就会覆盖掉别人的工作。
所以规则里要写死一条：发现文档和 GitHub 或线上状态对不上，先核实并修正文档，不能直接按文档覆盖已有工作。
顺序是先查、后改文档、再干活。三步都不能跳。
四、多个 Agent 同时跑，先划责任
并行是这套机制最大的收益，也是最容易翻车的地方。
对个人项目这个规模，我的划法是：
- 一个主 agent 负责整合、合并和部署
- 其他 agent 各自认领独立 Issue，用独立分支或者 worktree
- Issue 里写明涉及哪些文件，避免两个 agent 同时改同一个模块
- 同一时间只有一个 agent 能动生产环境
性能优化和文档审计可以完全并行，互不干扰。
两个 agent 同时改首页布局就是灾难，一定会互相覆盖，而且冲突解决出来的东西大概率两边的意图都保不住。
worktree 值得单说一句。同一个仓库开多个工作目录，各自独立分支，互不干扰。比让 agent 反复 checkout 切分支安全得多——切分支的时候如果有未提交的改动，出事的方式非常难查。
五、能自动检查的别靠人盯
交接质量靠自觉是靠不住的，尤其是 agent 的自觉。
能进 CI 的检查：
- 测试与构建通过
- 版本号在各处保持一致（
VERSION、package 文件、版本说明）
- 文档内部链接有效
- 应用类 PR 必须包含交接更新和验证记录
- 部署记录必须包含源码提交、运行时版本、验收结果和回退方式
其中“PR 必须包含交接更新”这条最有用。它把“记得更新交接文件”从一个需要提醒的习惯，变成了一个不做就合不了的硬约束。
习惯会忘，约束不会。
六、权限不能通过文档继承
这条单独拎出来说，因为它是唯一一条错了就不可逆的。
账号登录状态不能写进交接文档。
不管是 API key、token 还是 session，都不行。交接文件是会被提交、被同步、被下一个 agent 完整读取的东西，凭证放进去等于公开。
交接里只写两件事：这个任务需要什么权限，怎么检查权限有没有生效。
真正的密钥放在平台的安全配置里，agent 通过环境变量拿，读不到明文。
落地顺序
不用一次全上。按这个顺序做，每一步都能立刻见效：
第一步，清理交接文件的新旧状态。 这是成本最低、收益最直接的一件。花十分钟，把历史记录移到版本目录，交接文件只留当前。
第二步，加 Issue 和 PR 模板。 把上面那份字段清单做成 PR 模板，agent 提 PR 的时候自动带出来，比在规则文件里写一百遍“记得填交接”有用。
第三步，加版本一致性和交接完整性检查。 让 CI 帮你盯，别靠人眼。
三步做完，你可以把这段话直接甩给任何一个新 agent：
接手这个仓库。先读规则文件和最新交接，再核对远端主分支、工作区、开放的 Issue 和 PR、以及生产版本。按交接里的当前执行指针继续。完成后更新交接、提交 PR，按项目约定完成合并、部署和线上验证。没完成的部分必须留下准确的分支、提交和下一步。
跑了一段时间之后我发现，这套东西真正改变的其实不是交接效率。
是我自己终于说得清项目现在到底什么状态了。
以前那些“大概做完了”“应该上线了吧”，都是因为状态只存在脑子里，而脑子会自动把不确定的地方填成确定的。写进仓库就填不了了，缺什么一目了然。
agent 只是把这个问题暴露得更早、更狠而已。