使用 PLANS.md 进行数小时级问题解决

来源: https://developers.openai.com/cookbook/articles/codex_exec_plans 抓取时间: 2026-07-21 16:20:04

Codex 和 gpt-5.2-codex 模型（推荐）可用于实现需要大量时间进行研究、设计和实施的复杂任务。此处描述的方法是提示模型实施这些任务并引导其成功完成项目的一种方式。

这些计划是详尽的设计文档，也是"活文档"。作为 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 必须用简单的语言定义每个专业术语，否则不使用它。

目的和意图是第一位的。首先用几句话解释，从用户的角度来看这项工作为什么重要：在此更改之后，人们可以做以前不能做的事情，以及如何看到它工作。然后引导读者完成实现该结果的确切步骤，包括要编辑的内容、要运行的内容以及他们应该观察到的内容。

执行您的计划的智能体可以列出文件、读取文件、搜索、运行项目和运行测试。它不知道任何先前的上下文，也无法从早期的里程碑中推断您的意思。重复您依赖的任何假设。不要指向外部博客或文档；如果需要知识，请用自己的话将其嵌入计划本身。如果 ExecPlan 建立在先前的 ExecPlan 之上并且该文件已签入，请通过引用合并它。如果没有，您必须包含该计划的所有相关上下文。

## 格式化

格式和包装简单且严格。每个 ExecPlan 必须是一个标记为 `md` 的单个围栏代码块，以三个反引号开始和结束。不要在其中嵌套额外的三个反引号代码围栏；当需要显示命令、记录、差异或代码时，将它们作为该单个围栏内的缩进块呈现。使用缩进提高清晰度，而不是在 ExecPlan 内使用代码围栏以避免过早关闭 ExecPlan 的代码围栏。每个标题后使用两个换行符，使用 # 和 ## 等以及有序和无序列表的正确语法。

在将 ExecPlan 写入 Markdown（.md）文件时，如果文件的内容**仅**是单个 ExecPlan，则应省略三个反引号。

用简单的散文书写。偏爱句子而非列表。避免清单、表格和冗长的枚举，除非简洁会掩盖意义。清单仅允许在 `Progress` 部分中使用，在那里它们是强制性的。叙述部分必须保持以散文为先。

## 指导方针

自包含和简洁的语言是最重要的。如果您引入一个不是普通英语的短语（"守护进程"、"中间件"、"RPC 网关"、"过滤器图"），请立即定义它并提醒读者它如何在这个仓库中体现（例如，通过命名它出现的文件或命令）。不要说"如前所述"或"根据架构文档"。在这里包含所需的解释，即使您重复自己。

避免常见的失败模式。不要依赖未定义的行话。不要过于狭隘地描述"功能的字面意思"，以致生成的代码可以编译但没有任何有意义的作用。不要将关键决策外包给读者。当存在歧义时，在计划本身中解决它并解释为什么选择该路径。宁可过度解释用户可见的效果，也不要过度指定偶然的实现细节。

用可观察的结果锚定计划。说明用户在实现后可以做什么，要运行的命令，以及他们应该看到的输出。验收应该表述为人类可以验证的行为（"启动服务器后，导航到 [http://localhost:8080/health](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` 条目，总结已实现的内容、剩余内容以及经验教训。

# 原型里程碑和并行实现

可以——并且通常鼓励——包含明确的原型里程碑，当它们可以降低更大变更的风险时。示例：向依赖项添加低级运算符以验证可行性，或在测量优化器效果的同时探索两种组合顺序。保持原型是增量的和可测试的。明确将范围标记为"原型设计"；描述如何运行和观察结果；并说明推广或丢弃原型的标准。

优先选择增量代码更改，然后是保持测试通过的减法。并行实现（例如，在迁移期间将适配器与旧路径一起保留）在它们可以降低风险或使测试在大型迁移期间继续通过时是可以的。描述如何验证两个路径，以及如何使用测试安全地停用一个。在使用多个新库或功能区域时，考虑创建尖峰（spikes），**独立**评估这些功能的可行性，证明外部库按预期执行并在隔离中实现我们需要的功能。

## 好的 ExecPlan 的框架

    # <简短的、面向行动的描述>

    此 ExecPlan 是一个活文档。`Progress`、`Surprises & Discoveries`、`Decision Log` 和 `Outcomes & Retrospective` 部分必须在工作进行时保持更新。

    如果 PLANS.md 文件已签入仓库，请在此处从仓库根目录引用该文件的路径，并注意本文档必须按照 PLANS.md 进行维护。

    ## 目的 / 概况

    用几句话解释在此更改后人们获得了什么，以及他们如何看到它工作。说明您将启用的用户可见行为。

    ## 进度

    使用带有复选框的列表来总结细粒度的步骤。每个停止点都必须在此记录，即使需要将部分完成的任务拆分为两个（"已完成"与"剩余"）。此部分必须始终反映工作的实际当前状态。

    - [x] (2025-10-01 13:00Z) 示例已完成的步骤。
    - [ ] 示例未完成的步骤。
    - [ ] 示例部分完成的步骤（已完成：X；剩余：Y）。

    使用时间戳来衡量进度率。

    ## 意外与发现

    记录在实施过程中发现的意外行为、错误、优化或见解。提供简洁的证据。

    - 观察：…
      证据：…

    ## 决策日志

    按照以下格式记录在处理计划时做出的每个决策：

    - 决策：…
      理由：…
      日期/作者：…

    ## 结果与回顾

    在主要里程碑或完成时总结结果、差距和经验教训。将结果与原始目的进行比较。

    ## 上下文与定位

    描述与该任务相关的当前状态，就好像读者一无所知。通过完整路径命名关键文件和模块。定义您将使用的任何非明显术语。不要参考先前的计划。

    ## 工作计划

    用散文描述编辑和添加的顺序。对于每个编辑，命名文件和位置（函数、模块）以及要插入或更改的内容。保持具体和最小化。

    ## 具体步骤

    说明要运行的确切命令以及在哪里运行它们（工作目录）。当命令生成输出时，显示简短的预期记录，以便读者可以比较。此部分必须在工作进行时更新。

    ## 验证与验收

    描述如何启动或运行系统以及要观察什么。将验收表述为行为，包含具体的输入和输出。如果涉及测试，请说"运行 <项目的测试命令>，期望 <N> 个通过；新测试 <名称> 在更改前失败，在更改后通过"。

    ## 幂等性与恢复

    如果步骤可以安全地重复，请说明。如果步骤有风险，请提供安全的重试或回滚路径。完成后保持环境清洁。

    ## 工件与注释

    将最重要的记录、差异或片段作为缩进示例包含在内。保持简洁并专注于证明成功的内容。

    ## 接口与依赖项

    要有规定性。命名要使用的库、模块和服务以及原因。指定在里程碑结束时必须存在的类型、特征/接口和函数签名。优先选择稳定的名称和路径，例如 `crate::module::function` 或 `package.submodule.Interface`。例如：

    在 crates/foo/planner.rs 中，定义：

        pub trait Planner {
            fn plan(&self, observed: &Observed) -> Vec<Action>;
        }

如果您遵循上述指导，单个无状态智能体——或人类新手——可以从头到尾阅读您的 ExecPlan 并产生可用的、可观察的结果。这就是标准：自包含、自足、新手引导、结果导向。

当您修订计划时，您必须确保您的更改在所有部分（包括活文档部分）中得到全面反映，并且您必须在计划底部写一个注释，描述更改和原因。ExecPlans 必须不仅描述"是什么"，而且描述几乎所有事情的"为什么"。