新 agent 十分钟接手你的仓库：vibe 项目的 agent 交接包七件套

每个 vibe 开发者都经历过这个场景：一个 agent 花了三天把项目搭起来，你换了一个新会话，或者换了一个模型，它像失忆一样重新问一遍——这个项目是干什么的、数据库怎么连、支付走哪条路、哪些文件绝对不能动。你花一上午把上下文重新讲一遍，它还是会在第三次改动时踩进同一个坑。这不是模型的问题，这是交接的问题：你的仓库里没有一份“新 agent 十分钟能读完、读完就能干活”的交接包。

交接包不是文档堆：先定“十分钟”标准

判断一份交接包合不合格，只有一个标准：一个从未见过这个项目的新 agent，只读交接包、不问你任何问题，能不能在十分钟内说出三件事——这个项目给谁解决什么问题、改动应该从哪里下手、改完怎么证明没改坏。如果说不出来，这份包就是装饰品，不管它写了多少页。

这个标准直接排除了两种常见做法。第一种是把 README 写成编年史：从立项灵感写到每一版重构，信息全对，但新 agent 读完只记得一半，另一半在动手时现查。第二种是把所有上下文都塞进对话：上一轮对话里的约定，下一轮对话一律不认，换个模型更是清零。对话是易失存储，仓库才是持久存储。交接包必须住在仓库里，跟代码一起版本化、一起评审、一起过期。

交接包的七件套：每件都有且仅有一个用途

第一件，项目一页纸。半页到一页，写清：给谁、解决什么问题、核心流程是哪三步、技术栈（只写作者与项目实际确认的，不确定的留空）、部署地址与运行状态。不要写愿景，不要写路线图长文。一页纸的读者是“刚进门的 agent”，它只需要定位，不需要被说服。

第二件，架构地图。不是 UML 全家福，而是一张“改动地图”：模块列表、每个模块的职责一句话、模块之间的数据流向、外部服务（数据库、支付、邮件、对象存储）各用在何处。画法不限，文字列表也行，关键是让 agent 在改 A 之前就知道会不会牵连 B。地图里要标出“历史遗留区”：那些因为赶工留下的、明知不合理但暂时不能动的代码，写清为什么不能动、动它的前置条件是什么。

第三件，决策记录。每个重要决策一行：日期、决策、备选方案、为什么选这个、什么情况下可以推翻。决策记录解决的是 agent 最常犯的错：把前人深思熟虑后否决的方案又“创新”一遍。例如“为什么不用某 ORM 的自动迁移”，如果没有记录，新 agent 有一半概率会把它当作改进提出来。

第四件，禁区清单。这是交接包里最有价值的一页：绝对不能碰的文件、不能改的表结构、不能轮换的密钥位置、不能在生产环境跑的命令、法律与合规红线（例如用户数据不能进日志）。禁区清单要写得具体到文件路径与命令原文，笼统的“小心数据库”等于没写。

第五件，验证命令清单。构建、测试、Lint、类型检查、数据库迁移演练，每条命令原文写出，附带“正常输出长什么样”与“常见失败长什么样”。agent 改完代码，第一件事不是问你“这样行吗”，而是跑这张清单。清单里还要有一条黄金路径：从启动到完成一次核心业务操作的最短手动步骤，用来做冒烟验证。

第六件，任务队列与已知坑。当前在做的事、排队的事、已知未修的 bug、偶发失败的测试（flaky test）及重跑办法、被绕过的临时方案与到期日。没有这件，新 agent 会把已知坑当作新发现，把临时方案当作正式设计。

第七件，交接仪式本身。规定新 agent 的第一个任务永远是“小修 + 验证 + 回写”：修一个小问题，跑验证清单，然后把自己在交接过程中发现的过时或错误信息写回交接包。这个仪式有两个作用：用低风险任务检验交接包是否真实可用；让交接包在每一次交接中自我修正，而不是越陈越旧。

一个可直接抄的骨架

docs/agent-handover/
  01-one-pager.md        # 给谁、解决什么、核心三步、技术栈、部署地址
  02-architecture-map.md # 模块、数据流、外部服务、历史遗留区
  03-decisions.md        # 日期、决策、备选、推翻条件
  04-no-go-list.md       # 禁碰文件、禁跑命令、合规红线（精确到路径）
  05-verify.md           # 构建/测试/Lint/迁移命令原文 + 正常与失败输出样例
  06-queue-and-pitfalls.md # 在做/排队/已知坑/临时方案与到期日
AGENTS.md                 # 入口：先读交接包，再动手；第一个任务走交接仪式

AGENTS.md 是入口，不是正文。它只做三件事：指路（先读 docs/agent-handover）、定规矩（禁区清单高于一切建议）、定仪式（第一个任务必须是小修 + 验证 + 回写）。把长篇内容都塞进 AGENTS.md 是最常见的反模式：入口越长，新 agent 越可能跳过。

维护规则：交接包过期比没有更危险

一份过期的交接包比没有交接包更危险，因为它会让 agent 自信地做错事。所以维护规则必须写进流程，而不是靠自觉。第一，任何触及架构、数据流、外部服务、禁区的合并请求，必须同步更新交接包，把这一条写进 PR 模板的检查清单，缺更新就不合并。第二，每月做一次“交接包体检”：随机抽一个没参与过项目的 agent（或同事），只给交接包，让它复述项目定位与验证步骤，复述不出来的部分当天改。第三，每件内容标注“最后验证日期”，超过 30 天未验证的条目标记为“待核实”，agent 读到时就知道这条不能全信。

还有一条铁律：交接包里不放密钥、不放真实用户数据、不放内部聊天记录截图。需要引用的地方写“去哪里取”（例如密钥管理器名称、环境变量名），而不是把值抄进来。交接包会被 agent 全文读入上下文，任何敏感信息一旦写进去，就等于发给了每一次会话。

与站内已有指南的划界

本篇与五篇邻近指南各有分工，读之前先分清。提示词版本管理篇讲的是把提示词当作代码资产做版本控制，对象是提示词本身；本篇讲的是把项目知识打包成交接物，对象是仓库知识，提示词只是其中一小部分。并行 agent 工作流篇讲的是多个 agent 同时干活时的分工与冲突处理，本篇讲的是单个新 agent 接手时的知识传递，一前一后，不重叠。开发环境标准化篇讲的是让任何机器都能一键跑起项目，本篇假设环境已经能跑，解决的是“跑起来之后往哪改”。事故 Runbook 篇讲的是出事后按步骤止血，本篇讲的是出事前就让接手者知道止血阀门在哪里。AI 评估篇讲的是用测试衡量模型输出质量，本篇讲的是用交接仪式衡量交接包本身是否可用。把这五篇混成一篇“agent 最佳实践大全”，每篇都会变薄；分开写，每篇才能被直接照做。

本周就能落地的三步

• 第一步（30 分钟）：按七件套骨架新建目录，先写项目一页纸、禁区清单、验证命令清单这三件最能救命的，其他四件留空标注“待补”，不要为求全拖延上线。
• 第二步（下一次合并时）：在 PR 模板里加一行“是否同步更新交接包”，从下一条架构改动开始执行，让维护变成流程而不是决心。
• 第三步（下一次换 agent 时）：强制走交接仪式——小修 + 验证 + 回写，仪式结束后检查交接包被改了几处，被改得越多，说明这包越有生命力。

反模式画廊：五种看起来像交接、其实不是交接的做法

第一种是“口头交接”：老 agent 在对话里用三段话讲完项目，新 agent 说“明白了”，然后动手。这不叫交接，这叫复述测试——新 agent 的“明白”没有任何可核查的载体，下一轮对话一律清零。检验办法很简单：关掉对话，换一个新会话，只给仓库，看它能不能复述项目定位；复述不出来，口头交接就是零。

第二种是“截图交接”：把架构图、配置页、聊天记录截成图片贴进文档。图片里的文字进不了搜索、进不了 agent 的结构化阅读，改动后图片也不会自己更新。三个月后文档里的截图与现状完全脱节，新 agent 按图索骥必然走错。架构信息必须用文字写，截图只作辅助证据，不能当作正文。

第三种是“全量交接”：把所有文档、所有会议纪要、所有历史决策一股脑塞给新 agent，美其名曰“信息越全越好”。信息过载的后果是新 agent 抓不住重点，把边缘信息当作核心约束，把已废弃的方案当作现行设计。交接包的每一件都要有“为什么新 agent 必须知道”的理由，答不出来的内容就删掉或归档，不要放进交接路径。

第四种是“单人交接”：交接包只有一个人维护、一个人懂，其他人从来不读。维护者一旦离开，交接包立刻变成无人认领的古董。破解办法是把交接包的评审放进常规流程：每个合并请求的评审者都要顺带看一眼相关章节，交接仪式的回写要由评审者确认，而不是由新 agent 自己说了算。

第五种是“静态交接”：交接包写完就封存，项目演进、交接包不动。静态交接的失效是静默的——没有报错、没有提醒，只有新 agent 在某一天按过期信息改坏了生产数据才被发现。对抗静默失效的办法就是前文的三条维护规则：合并请求同步更新、每月体检、最后验证日期标注。没有维护规则的交接包，保质期只有一个月。

交接包评审清单：评审者照着打勾

评审交接包更新时，评审者不需要通读全文，只需要打勾六项。第一，项目一页纸是否仍与现状一致：用户、问题、核心流程、技术栈、部署地址有没有过期项。第二，架构地图是否覆盖了本次改动的全部牵连模块，有没有漏标历史遗留区。第三，决策记录是否写了本次决策的备选方案与推翻条件，还是只写了结论。第四，禁区清单有没有新增的禁碰项，旧的禁碰项是否仍然成立。第五，验证命令清单里的命令是否在本次改动后仍能跑通，正常输出样例是否更新。第六，任务队列与已知坑是否同步了本次改动带来的新坑与新临时方案。六项全勾，交接包更新才能合并；任何一项打叉，退回补写。这张清单本身也应该放进交接包里，让评审标准本身也被版本化。

还有一个评审技巧：让评审者扮演“挑刺的新 agent”。评审时故意问三个问题——如果我要改支付流程，第一步看哪里；如果我要删一张表，禁区清单拦不拦得住我；如果测试全红了，验证清单能不能告诉我先查哪条。这三个问题答不上来，交接包就还缺东西。这个技巧的价值在于，它把评审从“文字通不通顺”变成了“新 agent 能不能干活”，而后者才是交接包存在的意义。

交接包与团队规模的关系：一个人也要写

最常见的反对意见是：“我就一个人开发，写交接包是给谁看？”答案是：给三个月后的你看，也给换了模型的你看。独立开发者的记忆同样会过期，三个月后你自己就是那个“新 agent”——你会忘记当初为什么否决某个方案、哪张表不能动、哪个测试是偶发失败。一个人写交接包时，七件套可以压缩成三件：一页纸、禁区清单、验证命令清单，其他四件随项目长大再补。但压缩不等于省略禁区与验证这两件，因为它们恰恰是独立开发者最容易凭记忆出错的地方。团队越大，交接包越要完整；团队越小，交接包越要先写最救命的三件。

常见问题：四问四答

问：交接包应该放在仓库的什么位置？答：放在 docs/agent-handover 这样的固定目录，入口写进 AGENTS.md。不要放在个人网盘、聊天记录或某个人的本地文件夹里——交接包的价值来自“任何人、任何会话都能在仓库里找到它”，放错位置等于没有。

问：交接包多久更新一次？答：没有固定周期，只有触发条件：架构、数据流、外部服务、禁区任一变化，就同步更新；每月做一次体检；每条内容标注最后验证日期。靠日历驱动的更新一定会过期，靠变更驱动的更新才能跟上项目。

问：小项目也需要七件套吗？答：不需要一次齐全，但一页纸、禁区清单、验证命令清单这三件不能省。七件套是目标形态，不是起步门槛；先写三件救命的，再随项目长大补齐，比“等有空了一次写全”现实得多。

问：新 agent 不读交接包怎么办？答：把“先读交接包”写进 AGENTS.md 的入口，并把交接仪式定为第一个任务的硬性要求。如果 agent 跳过交接直接动手，评审时退回重做。规则不执行，交接包就只是文档；规则执行三次，就会变成团队习惯。

交接包与新人入职手册的区别

有人会问：这不就是一份新人入职手册吗？表面像，实质不同。入职手册的读者是人，读完可以提问、可以追问、可以凭常识补全空白；交接包的读者是 agent，它不会提问，只会按字面执行，空白处会自行脑补。所以交接包要比入职手册更具体：命令要写原文，路径要写全称，禁区要写后果，验证标准要写“正常输出长什么样”。入职手册可以写“注意数据库安全”，交接包必须写“不要在生产库执行删除语句，删表前必须先做逻辑删除演练”。把入职手册直接发给 agent，是交接失败最常见的起点。

一句话总结：vibe 项目真正的资产不是某一次 agent 会话的产出，而是任何一个新 agent 都能在十分钟内接手的能力。把这份能力写进仓库，而不是留在对话里，项目才算真正属于你，而不是属于某一次运气好的会话。