概述
Codex 和 gpt-5.2-codex 模型（推荐）可用于实施需要大量时间进行研究、设计和实现的复杂任务。本文描述的方法是一种提示模型实施这些任务并引导其成功完成项目的方式。
这些计划是详尽的设计文档，也是”活文档”。作为 Codex 用户，你可以使用这些文档在 Codex 开始长时间实施过程之前验证它将采用的方法。下面包含的特定 PLANS.md 与一份曾使 Codex 能够从单个提示词工作超过七小时的计划非常相似。
我们通过首先更新 AGENTS.md 来描述何时使用 PLANS.md，然后将 PLANS.md 文件添加到我们的仓库中，来启用 Codex 使用这些文档。
AGENTS.md
AGENTS.md 是一种用于指导 Codex 等编码智能体的简单格式。我们描述了一个用户可以用作简写的术语，以及一个关于何时使用规划文档的简单规则。在这里，我们称之为 “ExecPlan”。注意这是一个任意术语，Codex 没有针对它进行过训练。这个简写可以在提示 Codex 时使用，以引导它指向计划的特定定义。
以下是一个 AGENTS.md 章节，指示智能体何时使用计划：
# ExecPlans
在编写复杂功能或重大重构时，使用 ExecPlan（如 .agent/PLANS.md 中所述）从设计到实施。PLANS.md
以下是完整文档。本文档中的提示词经过精心选择，以向用户提供大量反馈，并引导模型精确实施计划所规定的内容。用户可能会发现他们需要定制文件以满足其需求，或添加或删除所需章节。
# Codex 执行计划 (ExecPlans)
本文档描述了执行计划（"ExecPlan"）的要求，这是一种设计文档，编码智能体可以遵循它来交付可用的功能或系统变更。将读者视为该仓库的完全初学者：他们只有当前工作树和你提供的单个 ExecPlan 文件。没有先前计划的记忆，也没有外部上下文。
## 如何使用 ExecPlans 和 PLANS.md
在编写可执行规范（ExecPlan）时，严格遵循 PLANS.md。如果它不在你的上下文中，通过阅读整个 PLANS.md 文件来刷新记忆。在产生准确规范的过程中，要彻底阅读（和重新阅读）源材料。在创建规范时，从骨架开始，边研究边充实。
在实施可执行规范（ExecPlan）时，不要向用户提示"下一步"；直接继续下一个里程碑。在每个停止点更新所有章节，在列表中添加或拆分条目，以明确说明已取得的进展和下一步。自主解决歧义，并频繁提交。
在讨论可执行规范（ExecPlan）时，在规范的日志中记录决策以供后人参考；任何对规范的更改都应该明确说明原因。ExecPlans 是活文档，应该始终可以仅从 ExecPlan 重新开始，而不需要其他工作。
在研究具有挑战性要求或重大未知因素的设计时，使用里程碑来实施概念验证、"玩具实现"等，以验证用户的提议是否可行。通过查找或获取来阅读库的源代码，深入研究，并包含原型以指导更完整的实现。
## 要求
不可协商的要求：
- 每个 ExecPlan 必须完全自包含。自包含意味着其当前形式包含新手成功所需的所有知识和指令。
- 每个 ExecPlan 都是活文档。贡献者必须在取得进展、发现出现和设计决策最终确定时修订它。每次修订必须保持完全自包含。
- 每个 ExecPlan 必须使完全新手能够在没有该仓库先验知识的情况下端到端实施该功能。
- 每个 ExecPlan 必须产生可证明的有效行为，而不仅仅是"满足定义"的代码更改。
- 每个 ExecPlan 必须用 plain language 定义每个术语，否则不要使用它。
目的和意图优先。首先用几句话解释从用户角度来看这项工作为何重要：某人在此更改后可以做什么而之前无法做到，以及如何看到它工作。然后引导读者完成实现该结果的确切步骤，包括编辑什么、运行什么以及他们应该观察到什么。
执行你计划的智能体可以列出文件、读取文件、搜索、运行项目和运行测试。它不知道任何先前的上下文，也无法从早期的里程碑中推断你的意思。重复你依赖的任何假设。不要指向外部博客或文档；如果需要知识，用你自己的话将其嵌入计划中。如果 ExecPlan 建立在先前的 ExecPlan 之上且该文件已检入，通过引用将其纳入。如果没有，你必须包含该计划中的所有相关上下文。
## 格式
格式和信封简单且严格。每个 ExecPlan 必须是一个标记为 `md` 的单个围栏代码块，以三个反引号开始和结束。不要嵌套额外的三反引号代码围栏；当你需要显示命令、记录、差异或代码时，将它们作为缩进块呈现在该单个围栏内。使用缩进以提高清晰度，而不是在 ExecPlan 内使用代码围栏，以避免过早关闭 ExecPlan 的代码围栏。在每个标题后使用两个换行符，使用 # 和 ## 等，以及有序和无序列表的正确语法。
当将 ExecPlan 写入 Markdown (.md) 文件且文件内容*仅*是单个 ExecPlan 时，你应该省略三反引号。
用 plain prose 编写。优先使用句子而非列表。除非简洁会掩盖含义，否则避免使用检查清单、表格和长枚举。检查清单仅在 `Progress` 章节中是允许的，在那里是强制性的。叙述章节必须保持 prose-first。
## 指南
自包含和 plain language 至关重要。如果你引入的短语不是普通英语（"daemon"、"middleware"、"RPC gateway"、"filter graph"），立即定义它并提醒读者它如何在此仓库中体现（例如，通过命名它出现的文件或命令）。不要说"如先前定义"或"根据架构文档"。在此处包含所需的解释，即使你重复自己。
避免常见的失败模式。不要依赖未定义的术语。不要如此狭隘地描述"功能的字面意义"，以至于生成的代码可以编译但没有任何实际意义。不要将关键决策外包给读者。当存在歧义时，在计划本身中解决它并解释为什么选择该路径。倾向于过度解释用户可见的效果，而少指定偶然的实现细节。
用可观察的结果锚定计划。说明实施后可以做什么、要运行的命令以及他们应该看到的输出。验收应表述为人类可以验证的行为（"启动服务器后，导航到 http://localhost:8080/health 返回 HTTP 200 且正文为 OK"）而非内部属性（"添加了 HealthCheck 结构体"）。如果更改是内部的，解释其影响如何仍然可以证明（例如，通过运行在实施前失败、实施后通过的测试，以及展示使用新行为的场景）。
显式指定仓库上下文。使用完整的仓库相对路径命名文件，精确命名函数和模块，并描述应在何处创建新文件。如果涉及多个区域，包含一个简短的定位段落，解释这些部分如何组合在一起，以便新手可以自信地导航。运行命令时，显示工作目录和确切的命令行。当结果依赖于环境时，说明假设并在合理时提供替代方案。
具有幂等性和安全性。编写可以多次运行而不会造成损坏或漂移的步骤。如果步骤可能在中间失败，包含如何重试或适应。如果需要迁移或破坏性操作，详细说明备份或安全回退。优先选择可以在进行过程中验证的增量的、可测试的更改。
验证不是可选的。包含运行测试的指令（如果适用）启动系统并观察它做有用的事情。描述对新功能或能力的全面测试。包含预期输出和错误消息，以便新手可以区分成功和失败。在可能的情况下，展示如何证明更改在编译之外是有效的（例如，通过一个小型的端到端场景、CLI 调用或 HTTP 请求/响应记录）。说明适合项目工具链的确切测试命令以及如何解释其结果。
捕获证据。当你的步骤产生终端输出、短差异或日志时，将它们作为缩进示例包含在单个围栏块内。保持它们简洁并专注于证明成功的内容。如果你需要包含补丁，优先选择文件范围的差异或读者可以通过遵循你的指令重新创建的小摘录，而不是粘贴大块内容。
## 里程碑
里程碑是叙述性的，不是官僚主义的。如果你将工作分解为里程碑，用一段简短的段落介绍每个里程碑，描述范围、里程碑结束时将存在什么以前不存在的东西、要运行的命令以及你期望观察到的验收。保持可读性作为一个故事：目标、工作、结果、证明。进展和里程碑是不同的：里程碑讲述故事，进展跟踪细粒度工作。两者都必须存在。永远不要仅为简洁而缩写里程碑，不要遗漏对未来实施可能至关重要的细节。
每个里程碑必须可独立验证，并递增地实施执行计划的总体目标。
## 活文档和设计决策
- ExecPlans 是活文档。当你做出关键设计决策时，更新计划以记录决策和背后的思考。将所有决策记录在 `Decision Log` 章节中。
- ExecPlans 必须包含并维护 `Progress` 章节、`Surprises & Discoveries` 章节、`Decision Log` 和 `Outcomes & Retrospective` 章节。这些不是可选的。
- 当你发现优化器行为、性能权衡、意外错误或影响你方法的逆/取消应用语义时，在 `Surprises & Discoveries` 章节中捕获这些观察结果，并附上简短的证据片段（测试输出是理想的）。
- 如果你在实施过程中改变方向，在 `Decision Log` 中记录原因并在 `Progress` 中反映影响。计划对下一个贡献者的指导作用与对你的检查清单作用一样大。
- 在完成主要任务或完整计划时，编写 `Outcomes & Retrospective` 条目，总结已完成的内容、剩余的内容和吸取的教训。
## 原型里程碑和并行实现
包含显式原型里程碑通常是可接受的——而且通常是鼓励的——当它们降低更大变更的风险时。示例：向依赖项添加低级操作员以验证可行性，或探索两种组合顺序同时测量优化器效果。保持原型增量和可测试。清楚地将范围标记为"原型"；描述如何运行和观察结果；并说明推广或丢弃原型的标准。
优先选择保持测试通过的加法代码更改，然后是减法。并行实现（例如，在迁移期间将适配器与旧路径一起保留）在降低风险或使测试能够在大型迁移期间继续通过时是可行的。描述如何验证两条路径以及如何安全地退役一条路径并进行测试。当使用多个新库或功能区域时，考虑创建 spike，独立评估这些功能的可行性，证明外部库按预期执行并隔离实现我们需要的功能。
## 良好 ExecPlan 的骨架
# <简短、面向行动的描述>
此 ExecPlan 是活文档。`Progress`、`Surprises & Discoveries`、`Decision Log` 和 `Outcomes & Retrospective` 章节必须在工作进行时保持最新。
如果 PLANS.md 文件已检入仓库，在此处从仓库根目录引用该文件的路径，并注意本文档必须按照 PLANS.md 进行维护。
## Purpose / Big Picture
用几句话解释某人在此更改后获得什么以及他们如何看到它工作。说明你将要启用的用户可见行为。
## Progress
使用带复选框的列表来总结细粒度步骤。每个停止点都必须记录在这里，即使它需要将一个部分完成的任务拆分为两个（"已完成"与"剩余"）。此章节必须始终反映工作的实际当前状态。
- [x] (2025-10-01 13:00Z) 示例已完成步骤。
- [ ] 示例未完成步骤。
- [ ] 示例部分完成步骤（已完成：X；剩余：Y）。
使用时间戳来衡量进展速度。
## Surprises & Discoveries
记录在实施过程中发现的意外行为、错误、优化或见解。提供简洁的证据。
- 观察：…
证据：…
## Decision Log
以以下格式记录在处理计划时做出的每个决策：
- 决策：…
理由：…
日期/作者：…
## Outcomes & Retrospective
在主要里程碑或完成时总结结果、差距和吸取的教训。将结果与原始目的进行比较。
## Context and Orientation
描述与此任务相关的当前状态，就像读者一无所知一样。用完整路径命名关键文件和模块。定义你将使用的任何非显而易见的术语。不要引用先前的计划。
## Plan of Work
用散文描述编辑和添加的序列。对于每次编辑，命名文件和位置（函数、模块）以及要插入或更改的内容。保持具体和最小化。
## Concrete Steps
说明要运行的确切命令以及在哪里运行（工作目录）。当命令生成输出时，显示一个简短的预期记录以便读者比较。此章节必须在工作进行时更新。
## Validation and Acceptance
描述如何启动或运行系统以及要观察什么。将验收表述为行为，具有特定的输入和输出。如果涉及测试，说"运行 <项目的测试命令>"并显示预期输出。关键要点
| 概念 | 说明 |
|---|---|
| ExecPlan | 可执行规范，从设计到实施的完整计划 |
| 自包含 | 计划必须包含新手成功所需的所有信息 |
| 活文档 | 随着进展不断更新，记录决策和发现 |
| 里程碑 | 可独立验证的阶段性目标 |
| 验证 | 必须包含测试和验收标准 |
必需章节
- Purpose / Big Picture - 目的和宏观视角
- Progress - 进展跟踪（带时间戳的复选框）
- Surprises & Discoveries - 意外发现和见解
- Decision Log - 决策日志
- Outcomes & Retrospective - 结果和回顾
- Context and Orientation - 上下文和定位
- Plan of Work - 工作计划
- Concrete Steps - 具体步骤
- Validation and Acceptance - 验证和验收
使用流程
1. 更新 AGENTS.md 定义 ExecPlan 概念
↓
2. 创建 PLANS.md 文件
↓
3. 为具体任务创建 ExecPlan
↓
4. 实施过程中持续更新计划
↓
5. 完成后编写回顾
原文来自 OpenAI Cookbook