Codex 长任务状态交接方法

一个跨几十个文件的重构任务，Codex 跑到一半上下文用满、或者中途需要中断去处理别的事，回来时新开的会话对之前做了什么、卡在哪一无所知，只能靠翻 git log 现场重建上下文。这类”长任务状态丢失”是用 Codex 处理大型任务时最容易踩的坑之一。本文给出一套实测有效的状态交接方法。

一、为什么不能只靠对话历史

直觉上”多留点上下文不就行了”，但两个现实原因让这条路走不通：

上下文窗口终究有限，长任务的中间产物（读过的文件、跑过的命令输出）会持续占用窗口，越往后可用空间越少，模型表现也会随上下文变长而下降
会话不总能保证连续，进程崩溃、网络断开、主动切换任务都会打断当前会话，重新连接后对话历史不一定完整保留

结论是：长任务的状态必须落地到文件，而不是寄希望于对话记忆。这样无论会话以什么方式中断，新会话都能从文件里恢复上下文，而不依赖对话历史是否完整。

二、HANDOFF 文件应该包含什么

不是把整个对话记录倒进一个文件就够了——那样新会话读起来和原会话一样费上下文。有效的 HANDOFF 文件应该是提炼后的状态，建议固定结构：

# HANDOFF: <任务名称>

## 目标
一句话说清楚这个任务要达成什么效果，做到什么程度算完成。

## 已完成
- [x] 步骤 1：具体做了什么，改了哪些文件（附路径）
- [x] 步骤 2：...

## 进行中 / 卡住的地方
- 正在做步骤 3，卡在 xxx 问题，已尝试 A 方案（失败原因）、B 方案（部分生效）
- 相关文件：path/to/file.ts:120

## 待办
- [ ] 步骤 4：...
- [ ] 步骤 5：...

## 关键决策记录
- 为什么选了方案 X 而不是方案 Y（一句话原因，避免新会话重新纠结一遍）

## 环境/前提
- 分支名、依赖的服务是否已启动、测试账号等新会话需要的最小上下文

“关键决策记录”这一节容易被忽略，但价值很大——没有它，新会话很可能重新评估一遍已经被否决的方案，浪费一整轮探索。

三、检查点：什么时候该写 HANDOFF

不要等到上下文快耗尽才手忙脚乱地写，应该在几个自然节点主动检查点：

完成一个可验证的子任务后（比如一个模块的重构跑通了测试）——这是状态最干净的时刻，此时写 HANDOFF 信息密度最高
切换到一个新的、独立的子问题前——避免两个子任务的上下文混在一起
预感当前会话上下文快不够用时——与其等报错，不如提前几轮主动收尾

一个实用的判断标准：如果这一步的产出值得单独 commit，那也值得同步更新一次 HANDOFF。两者节奏基本一致。

四、把 HANDOFF 和 git commit 绑在一起

单纯的 HANDOFF 文件描述的是”应该是什么状态”，真正可验证的状态是 git 历史。两者脱节是常见错误来源——HANDOFF 里写”已完成步骤 2”，但对应改动其实没提交，新会话据此判断的现状就是错的。实战中建议的组合动作：

git add -A
git commit -m "wip: 完成步骤 2，xxx 模块可通过测试"
# 提交之后再更新 HANDOFF.md，并引用这次的 commit

HANDOFF 里的”已完成”条目最好附上对应的 commit hash 或简述改动范围，新会话可以用 git log --oneline 和 git diff <hash> 快速核实描述是否属实，而不是盲目相信文字描述。

五、新会话恢复流程

新会话开始时，不要直接把 HANDOFF.md 整个丢给模型就开始干活，按顺序走三步：

读 HANDOFF.md，理解目标、已完成、卡点
核实关键声明：跑一下”已完成”部分提到的测试，确认状态和文档一致，不一致的地方以实际代码为准，不以文档为准
确认待办优先级，如果待办有多项，先问清楚（如果是交互场景）或按 HANDOFF 里的顺序（如果是无人值守场景）继续执行

第 2 步经常被跳过，但代价是新会话可能在一个实际上已经出问题的”已完成”步骤上继续往下叠加工作，等发现时返工成本更高。

六、任务完成后清理 HANDOFF

任务彻底完成、变更已经合并后，HANDOFF.md 应该删除，不要留在仓库里长期存在——它是过程文件，不是文档。如果任务里有值得沉淀的经验（比如踩过的坑、选型理由），应该转化为正式的项目文档或代码注释，而不是让 HANDOFF.md 一直躺在根目录变成事实上的”过期笔记”。

七、和其他 Codex 长任务实践的配合

状态交接主要解决”上下文连续性”问题，它和另外两个问题相关但不同：任务本身该不该拆成多个并行 Agent 执行，参考《Codex 多 Agent 任务拆分边界》；任务要在无人值守场景下自动跑，参考《Codex 后台自动化任务设计》。三者结合的典型场景是：用 worktree 隔离并行任务（见《Codex Worktree 隔离开发实战》），每个 worktree 内部再用 HANDOFF 做单任务的状态交接。

八、相关阅读

如果长任务里包含大量 API 调用，交接过程中也值得把当前的调用配额和账单状态记进 HANDOFF，避免新会话对成本情况一无所知——用 YoTradeApi 的话，控制台里的用量统计可以直接截图或摘要贴进交接文档。