什么时候该写
不必每个会话都写，遇到这三种情况值得花十分钟补一份：
- 任务可能要跨多个会话才能完成（比如一次需要跑几天的自动化发布流程）；
- 会话上下文已经明显不够用，需要"换一个干净的会话继续"；
- 工作要交给别人、换机器，或者隔一段时间再回来继续。
判断标准很简单：如果"下次继续"需要依赖记忆而不是文档，就写。另一个信号是上次会话结束时你发现自己说了"下次记得……"——这句话本身就该变成文档里的一行。
五个要素
一份够用的交接文档通常包含五块：
- 交接目标：一句话说清这份工作要达成什么、成功长什么样；
- 当前已知状态：做到哪一步了、最近一次结果、已知的坑（比如"某接口按名称访问正常、按 slug 访问 404"）；
- 必须遵守的流程：按步骤列出的门禁和检查点，比如"先查重、再写稿、门禁不过就停"；
- 已知边界：上次踩过的雷、不能复用的旧值（令牌、快照）、环境限制（代理不可用、接口会限流）；
- 下一步建议：接手者第一件事做什么、第二件事做什么，以及执行前要重新确认什么。
一段骨架示例
以"每天自动发布博客"这种任务为例，交接文档可以长这样：
- 目标：工作日自动产出一篇不重复的中文文章并发布；
- 现状：上次成功发布于某日，最近一次因网络不可用未发布，轮换方向已记录；
- 流程：读记忆查重 → 双来源核验 → 建草稿回读复核 → 发布 → 公开双重验收；
- 边界：某遗留代理曾被沙箱拒绝；公开 API 按 slug 访问会 404，按对象名称访问正常；
- 下一步：先确认网络与 API 可用，再读最近标题定选题，任何门禁失败立即停止。
这份骨架把"接手者要先知道什么"压缩到一分钟内，剩下的细节按需展开。
三条写作纪律
- 写"下一步怎么走"，不写流水账。文档的价值在决策与流程，不在"我做过什么"的过程复述；
- 敏感信息只给位置，不给值。令牌、密钥、内网地址一律不写进文档，写"从某某配置读取"即可；这既是为了文档可分发，也防止交接文档本身变成泄露源；
- 标注时间与验证方式。每条"已知状态"注明日期，写明验证命令或渠道，接手者才知道信息有没有过期、怎么复核。
接手者三件事
拿到交接文档别直接照做，先花三分钟做只读核验：
- 状态是否过期：文档里的链接、接口、路径逐个试一遍，404 或超时的当作"待确认"而不是"已知";
- 结论是否可信：文档说"上次失败是因为网络"，那就先验证当前网络通不通，别带着旧结论开始新操作;
- 先只读后动写：所有写入、发布、删除类操作，都在只读盘点之后进行，与文档描述冲突时以现状为准。
与 AGENTS.md 的分工
很多人分不清交接文档和项目规范：AGENTS.md 描述"这个项目永远怎么干活"（命令、规范、红线），交接文档描述"这件事当前做到哪了"（状态、下一步）。前者低频更新、长期有效，后者高频更新、用过即废。两个都写，但别互相抄：交接文档里可以"按 AGENTS.md 的发布流程执行"，不必重复全文。
收尾
交接文档写完不是终点：每次继续工作后，顺手把状态和下一步更新回去，文档才会越用越准。记住一个反直觉的规律——文档的价值不取决于写的时候多认真，而取决于接手时多敢怀疑。
来源：本文为常青实战技巧整理，基于长期使用 Codex 的实操经验，不依赖外部链接；涉及 Codex 官方功能细节请以 OpenAI 官方文档为准（本文撰写时其官方文档站对自动抓取不可达，未能核验具体页面内容，故不直接引用）。最后更新：2026-08-13。