短任务靠一句 prompt 也能跑完：加个接口、修一处样式、补几条测试。任务一旦跨几个小时，情况就变了。[2] agent 会查资料、读代码、试方案、改实现；中途可能压缩上下文，甚至换一个会话。[2] 最难受的不是它偶尔写错，而是你回来看不到它为什么这么改、还有哪些假设没验证，于是只能重新解释一遍。

我现在会给这类任务准备一份 ExecPlan。它不是待办清单，而是一份可以执行的工作说明：任何接手的人或新会话只读这一个文件，也该能明白要交付什么、仓库现在是什么样、下一步跑什么命令、看到什么结果才算完成。OpenAI 的示例把 ExecPlan 定义为面向复杂长任务的设计文档，强调它必须自包含、持续更新，并以可观察的行为作为验收标准。[2]

关键在于把“计划”从开工前一次性产物，改成工作过程中的状态机。开头先写用户能得到的结果，不写“重构订单模块”，而写“后台可按状态筛选订单，筛选条件刷新后仍保留”。接着写当前代码的入口、数据流和限制。agent 不该把“在 service 里改一下”当作上下文；计划里要点出文件、函数、已有测试，以及不能动的接口。这样中断之后，下一位执行者不会从 Git diff 里猜剧情。[2]

四块内容，少写废话#

第一块是 Purpose / Big Picture，只交代用户可感知的结果和观察方式。第二块是 Progress，按里程碑记录完成、未完成和半完成项，并写时间。第三块是 Decision Log：例如为什么继续用现有缓存而不引入 Redis，为什么先做只读接口。第四块是 Validation and Acceptance，把“应该没问题”改成可重复的命令、输入和预期输出。官方示例还要求记录意外发现和最终回顾；这两块很实用，前者防止踩过的坑被下一轮再踩一遍，后者让计划在收尾时不只剩一串勾。[2]

不要把架构图、十个备选方案和每个函数的伪代码都塞进去。计划需要足够具体，但不能替实现者预写实现。一个判断方法很简单：删掉这段以后，新会话会不会做出不同的关键决定？会，就保留；不会，多半是噪声。长任务里最稀缺的不是 token，而是每次恢复工作时重新建立判断依据的时间。计划也不该假装所有风险都已解决：把尚未验证的外部依赖、权限前提和性能假设单独列出来，下一轮先验证它们。[2]

把规则挂到 AGENTS.md 里也很重要。Codex 会在启动时建立指令链：先读全局配置，再从项目根目录一路读到当前目录；更靠近当前目录的文件会排在后面，从而覆盖前面的指令。[1] 根目录可以明确规定“复杂功能或大重构必须使用 .agent/PLANS.md 中定义的 ExecPlan”；某个高风险子目录再加一条“开始写入前先补全回滚和验收”。这样计划不是靠每次临时提醒才出现，而是进入任务的默认协议。

快速上手#

下面的做法不需要改生产代码，先在仓库根目录落一份模板：

mkdir -p .agent plans
cat >> AGENTS.md <<'EOF'
# Long-running work
复杂功能、跨模块改动或预计超过一小时的任务，
先在 plans/ 创建 ExecPlan，并按 .agent/PLANS.md 更新进度和验收证据。
EOF

再创建 .agent/PLANS.md，把以下骨架保存进去：

# ExecPlan

## Purpose / Big Picture
用户完成什么操作；如何亲眼验证。

## Progress
- [ ] 阅读入口代码和现有测试
- [ ] 写最小失败测试
- [ ] 实现并记录验证结果

## Decision Log
- Decision: 
  Rationale: 

## Validation and Acceptance
在仓库根目录运行：
    <真实测试命令>
预期：退出码 0，并说明一个用户可见结果。

然后让 agent 先写 plans/order-filter.md，不要立刻编码。第一次评审只看三件事：目标是否可观察，改动范围是否写到文件或模块，验收是否真的能跑。通过后才让它实现。每完成一个里程碑，要求它先更新 Progress、Decision Log 和实际命令输出，再进入下一步。计划中的进度必须是事实，不是乐观预测；遇到未知依赖或验收失败，就把它写成未完成项，而不是悄悄换目标。

这套方法并不会让 agent 更聪明，但会让它的工作可恢复、可审查。真正有价值的是那条硬边界：没有可运行的验收记录，就不能把任务标成完成。对于两分钟的小修复，这样做嫌重；对跨会话、跨模块、要交接的改动，它比一段很长的 prompt 靠谱得多。

Sources#

[1] https://developers.openai.com/codex/agent-configuration/agents-md [2] https://developers.openai.com/cookbook/articles/codex_exec_plans