在 Codex 新任务中迁移上下文

在 Codex 中处理长期项目时，经常会遇到这样的情况：旧任务已经讨论了几十轮，模型知道项目结构、踩过的坑和下一步计划；但一旦新建任务，这些信息没有自动迁移，新任务又会重新尝试已经失败过的方法。

解决这个问题的关键不是把旧对话完整复制过去，而是把真正需要长期保留的信息写回项目。可以把它理解为：对话是临时工作内存，仓库文件才是项目的长期记忆。

本文提供一套可以直接落地的上下文交接方法，适合持续开发、问题排查、版本发布和多人或多任务协作。

1. 为什么新任务会“失忆”

一个 Codex 任务中的上下文通常包括：

当前对话中的需求、解释和临时决定。
Codex 读取过的代码、日志和命令输出。
项目中的 AGENTS.md 和其他说明文件。
当前工作区状态、Git 差异和测试结果。
系统提示、工具定义以及最近几轮操作记录。

新建任务后，新的任务不会自动获得旧任务的完整对话记录。即使两个任务打开的是同一个项目，它们能够共同看到的也主要是工作区中真实存在的文件和 Git 状态，而不是另一个任务脑中的计划。

因此，下面这类信息如果只存在于聊天记录中，就很容易丢失：

为什么选择当前方案。
哪些方案已经试过但失败了。
哪些文件已经修改，哪些还没完成。
测试执行到了哪里，失败原因是什么。
用户临时提出但尚未写入项目的限制条件。

不建议把几十轮旧对话原样粘贴到新任务。大量无关讨论会占用上下文，也会让新任务更难判断哪些内容仍然有效。

2. 推荐的上下文分层方法

最实用的做法是把信息分成五层，并根据有效期保存到不同位置。

信息类型	推荐位置	适合保存的内容
永久规则	`AGENTS.md`	回复语言、禁止事项、构建命令、提交和发布规范
稳定背景	`docs/agent/PROJECT_CONTEXT.md`	项目用途、目录结构、核心模块、运行方式
方案与经验	`docs/agent/DECISIONS.md`	技术选择、放弃的方案、失败原因和注意事项
当前进度	`docs/agent/HANDOFF.md`	当前目标、已完成内容、测试结果、未解决问题和下一步
真实状态	Git、代码和测试结果	实际改动、提交历史、构建产物和可重复验证的结果

这几类文件的职责不要混在一起：

AGENTS.md 放长期有效、每个任务都应该遵守的规则。
PROJECT_CONTEXT.md 放变化较少的项目说明。
DECISIONS.md 记录“为什么这样做”，尤其是已经失败的路线。
HANDOFF.md 只描述当前任务做到哪里，可以频繁更新或直接覆盖。
Git 和测试结果负责验证文档是否仍与实际工作区一致。

3. 第一次建立交接文件

3.1. 创建目录

在项目根目录中创建 docs/agent/：

1
New-Item -ItemType Directory -Force docs/agent

如果项目已经有固定的文档目录，也可以使用其他位置，但之后每个任务都应使用同一组路径，避免模型到处寻找交接信息。

3.2. 编写项目背景文件

新建 docs/agent/PROJECT_CONTEXT.md，建议使用下面的结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 项目背景

## 项目目标
- 这个项目解决什么问题
- 主要用户是谁

## 技术栈
- 主要语言和框架
- 重要依赖和运行环境

## 目录结构
- `src/`：核心源码
- `tests/`：自动化测试
- `tools/`：构建和维护脚本

## 常用命令
- 安装依赖：`...`
- 启动项目：`...`
- 运行测试：`...`
- 构建发布：`...`

## 重要约束
- 哪些文件是唯一源码
- 哪些生成文件不能手动修改
- 版本号需要同步到哪些位置

这里应尽量记录稳定事实，不要写“今天准备修改某个按钮”之类的临时任务。

3.3. 编写决策记录

新建 docs/agent/DECISIONS.md：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# 决策记录

## 2026-08-16：方案名称

### 背景
为什么需要做出这个选择。

### 决定
最终采用什么方案。

### 原因
为什么选择它，有哪些权衡。

### 已放弃的方案
- 方案 A：放弃原因
- 方案 B：失败现象或风险

### 后续影响
后续修改时必须继续遵守什么约束。

DECISIONS.md 最有价值的部分通常不是“成功方案”，而是失败路线及其原因。这能防止新任务因为不了解历史背景，再次从头踩同一个坑。

3.4. 编写任务交接文件

新建 docs/agent/HANDOFF.md：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 当前任务交接

## 当前目标
- 本轮要解决的问题

## 完成情况
- [x] 已完成事项
- [ ] 未完成事项

## 已修改文件
- `path/to/file`：修改内容和原因

## 验证结果
- `测试命令`：通过或失败
- 失败时记录关键报错和判断

## 已尝试但未采用的方案
- 方案、执行结果和放弃原因

## 未解决问题
- 当前阻塞点或仍需确认的内容

## 推荐下一步
1. 下一步操作
2. 验证方式

## 额外约束
- 仅记录无法从代码和 `AGENTS.md` 直接判断的信息

HANDOFF.md 不需要写成工作日报，也不必保存每一次微小操作。它的目标是让一个完全不了解旧对话的新任务，在几分钟内接上当前工作。

4. 旧任务结束前如何生成交接

准备切换任务时，不要只让 Codex“总结一下对话”，而要让它结合工作区的真实状态生成交接。可以直接发送下面的提示词：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
准备将当前工作交接给一个新的 Codex 任务。

请先检查 AGENTS.md、git status、git diff、最近提交、已经修改的文件以及测试结果，
然后更新 docs/agent/HANDOFF.md。

交接内容至少包括：
1. 当前目标和完成情况；
2. 已修改文件及修改原因；
3. 已运行的验证命令和结果；
4. 已尝试但失败或放弃的方案，以及放弃原因；
5. 尚未解决的问题和当前阻塞点；
6. 推荐的下一步操作；
7. 无法从代码、Git 和 AGENTS.md 直接推断的额外约束。

不要只复述聊天记录，也不要把尚未验证的推测写成事实。
如果发现 PROJECT_CONTEXT.md 或 DECISIONS.md 中有需要长期保留的新信息，也一并更新。

这段提示词有两个重点：

先检查实际文件和 Git 状态，避免交接内容只依赖模型记忆。
区分长期信息和临时进度，不要把所有内容都塞进 HANDOFF.md。

生成后最好快速检查一次，尤其确认文件路径、测试结果、版本号和待办事项是否准确。

5. 新任务开始时如何恢复上下文

新任务打开同一个项目后，可以发送下面的提示词：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
这是一个从旧任务继续的工作。

开始修改前，请先阅读：
- AGENTS.md
- docs/agent/PROJECT_CONTEXT.md
- docs/agent/DECISIONS.md
- docs/agent/HANDOFF.md

然后检查 git status、git diff 和最近提交，确认交接文档是否仍与当前工作区一致。
请先用简短列表说明：
1. 你理解的当前目标；
2. 已完成和未完成的内容；
3. 必须遵守的约束；
4. 准备执行的下一步；
5. 交接文档与实际代码之间是否存在冲突。

在确认这些内容后再继续修改。不要重复尝试 DECISIONS.md 和 HANDOFF.md 中已经确认失败的方案。

交接文档只能帮助理解，不能替代验证。若 HANDOFF.md 说测试已经通过，但当前代码或 Git 状态发生了变化，新任务仍应重新执行必要的测试。

6. 一套适合日常使用的完整流程

将上面的内容简化后，可以形成下面这套工作流：

6.1. 开始任务

阅读 AGENTS.md 和三份上下文文件。
检查 git status、git diff 和最近提交。
对照交接内容确认当前目标。
再开始修改代码。

6.2. 执行任务

重要方案确定后，更新 DECISIONS.md。
项目结构或运行方式发生长期变化时，更新 PROJECT_CONTEXT.md。
通过代码、测试和 Git 保留可验证的真实结果。
不要把每轮对话都写入文档，只记录以后仍有价值的信息。

6.3. 结束或切换任务

运行必要的测试和构建命令。
检查工作区中是否存在未说明的改动。
更新 HANDOFF.md。
在新任务中先验证交接，再继续开发。

如果只是处理一个很小、几分钟内能完成的问题，不一定需要完整维护三份文件；但只要任务会跨多天、跨多个 Codex 任务，或者已经出现重复碰壁，就值得使用这套方法。

7. `AGENTS.md` 应该写什么，不应该写什么

AGENTS.md 会影响项目中的后续任务，因此只适合放稳定、明确、需要持续执行的指令，例如：

所有回复使用中文。
修改后必须运行哪些测试。
禁止自动推送，除非用户明确要求。
唯一源码目录和生成文件目录分别是什么。
构建、发布和版本号同步规则。

下面这些内容不适合长期放在 AGENTS.md：

“当前正在修复登录按钮”。
“下一步先改某个文件”。
某一次命令执行后的临时报错。
已经完成的任务流水账。
只对单次排查有效的猜测。

判断方法很简单：如果三个月后的新任务仍然必须遵守，就写进 AGENTS.md；否则放到交接或决策文件中。

8. 常见问题

8.1. 能不能直接把旧任务的全部对话复制到新任务

可以，但通常不推荐。完整记录里往往包含已经过期的猜测、重复日志和中间讨论。更好的做法是只迁移当前目标、有效结论、失败路线、改动状态和下一步。

8.2. `HANDOFF.md` 会不会很快过期

会，所以它应该在每次任务结束或切换前更新。新任务读取后也必须用 Git 和测试结果验证，不能无条件相信旧交接。

8.3. 所有项目都需要四份文件吗

不需要。小项目可以只使用 AGENTS.md 和 HANDOFF.md。当项目变复杂、方案选择增多或经常重复踩坑时，再增加 PROJECT_CONTEXT.md 和 DECISIONS.md。

8.4. 什么时候适合把流程做成 Skill

如果某套步骤会被频繁重复，而且包含明确的输入、命令、检查项和输出格式，例如固定的发布流程、日志排查流程或代码审查流程，就可以进一步整理成项目级 Skill。项目背景和临时进度仍应保留在文档中，不要全部塞进 Skill。

8.5. Codex Memories 能不能代替交接文档

不能完全代替。Codex Memories 在可用并启用时，可以把部分有用信息带到后续任务，但它更适合保存偏好和可复用经验，不适合作为当前代码状态、测试结果和发布进度的唯一依据。

交接文档的优势是可查看、可修改、可随代码一起审查，并且能通过 Git 和测试验证。因此，可以把 Memories 当作辅助能力，但项目关键状态仍建议写入仓库文件。

9. 总结

在 Codex 新任务中稳定迁移上下文，最重要的不是寻找一个“复制旧任务记忆”的按钮，而是建立可验证的项目交接机制：

用 AGENTS.md 保存永久规则。
用 PROJECT_CONTEXT.md 保存稳定背景。
用 DECISIONS.md 保存方案选择和失败经验。
用 HANDOFF.md 保存当前进度和下一步。
用 Git、代码和测试结果验证交接是否仍然有效。

采用这套方法后，新任务不需要重新阅读几十轮旧对话，也能快速理解项目、避开已经失败的路线，并从正确的位置继续工作。