HANDOFF.md 是什么？让新 AI 会话无缝接手旧任务

Fri, 24 Jul 2026 17:39:00 +0800

在 Codex、Claude Code 或 Cursor 中连续工作很久后，常见问题是：

对话上下文快满了；
AI 开始忘记早期要求；
新建会话后又要重新解释项目；
已完成的工作、踩过的坑和后续计划容易丢失。

HANDOFF.md 就是一份 AI 交接文档。

它把当前会话中的关键信息整理成 Markdown 文件，让下一次新会话先阅读这份文档，再继续工作。

使用后有什么效果？

它不能增加模型额度，也不能让 AI 永久记住所有内容，但可以明显改善长任务的连续性：

新会话更快理解项目；
减少重复介绍背景；
保留已经完成的工作；
记录当前卡点和错误尝试；
避免新 AI 重复踩坑；
让 Codex、Claude Code、Cursor 之间也能互相交接。

这种方法本质上是把聊天记录中最重要的信息，压缩成一份可长期保存的项目说明。已有 handoff 工具和实践也采用类似思路：把目标、决定、当前状态、关键文件和下一步写入 Markdown，再由新会话读取。

什么时候使用？

比较适合以下情况：

当前对话即将达到上下文上限；
一个项目需要分多次完成；
准备关闭 Codex 或 Claude Code；
想换一个 AI 工具继续处理；
当前 AI 开始遗忘前面的要求；
任务中已经做过很多测试和修改。

不要等到 AI 已经严重混乱后再生成，最好在当前会话仍能准确回忆全部过程时使用。

可直接复制的交接指令

本次对话即将结束，请在当前项目根目录生成一份交接文档，并命名为 HANDOFF.md。

文档必须包含以下内容：

1. 整体任务目标
2. 用户的核心要求和限制条件
3. 当前项目环境、技术栈和目录位置
4. 现阶段已经完成的工作
5. 已修改、新增或删除的关键文件
6. 当前尚未完成的工作
7. 当前遇到的卡点、报错和阻碍
8. 已经尝试过但没有成功的方法
9. 本轮对话中踩过的坑
10. 后续必须规避的雷区
11. 后续完整执行方案
12. 下一步最优先执行的具体任务
13. 验证工作是否完成的方法
14. 运行、测试、构建和部署命令
15. 其他新会话必须知道的重要信息

要求：

- 不要只写简单摘要。
- 必须写清楚为什么这样做，以及当前结果是什么。
- 涉及文件时写出完整或相对路径。
- 涉及命令时使用代码块完整记录。
- 涉及报错时保留关键报错内容。
- 明确区分已经确认的事实、推测和待验证事项。
- 不要隐瞒失败过程和未解决问题。
- 整篇文档必须做到：即使新会话完全没有当前聊天记录，也能仅通过 HANDOFF.md 理解项目并继续工作。
- 生成完成后，请检查文档是否遗漏关键要求，不要继续执行其他任务。

新会话中发送的指令

请先完整读取当前项目根目录中的 HANDOFF.md。

读取后不要立即修改代码，先完成以下工作：

1. 总结当前项目目标；
2. 说明已经完成的工作；
3. 列出尚未完成的任务；
4. 指出当前卡点和需要规避的雷区；
5. 给出你准备执行的下一步方案。

确认已经正确理解 HANDOFF.md 后，再继续处理项目。

使用时需要注意

HANDOFF.md 的质量取决于当前 AI 是否真正掌握项目状态。

如果交接文档只写“已经修改页面，后续继续优化”，新会话仍然无法接手。好的交接文档应该写清：

改了哪个文件；
为什么修改；
修改后的结果；
哪个方案失败；
下一步具体做什么；
怎样判断任务完成。

另外，交接文档只是记录状态，不会自动保存未提交代码。重要项目仍然需要配合 Git 提交、测试和备份。

总结

这段指令的真正价值，不是让 AI 获得永久记忆，而是人为建立一套可靠的“项目交接机制”。

对于需要多轮完成的网站开发、代码修复、服务器配置和大型项目，它可以减少大量重复沟通，并降低新会话错误接手的风险。