Codex Best Practices | Prompts 与上下文

如果你刚接触 Codex，或者刚开始使用编码智能体，这份指南可以帮助你更快得到更好的结果。它覆盖了让 Codex 在 CLI、 IDE 扩展 和 Codex App 中都更有效的核心习惯，包括提示词、规划、验证、MCP、技能和自动化。

当你不把 Codex 当作一次性的助手，而是把它当作一个会随着时间被你不断配置和优化的队友时，它通常表现最好。

一个很有用的思路是：先提供正确的任务上下文；用 AGENTS.md 保存持久指导；把 Codex 配置成适合你工作流的样子；通过 MCP 连接外部系统；把重复工作沉淀成技能；再把稳定流程自动化。

首次上手的重点：上下文与提示词

即使你的提示词还不够完美，Codex 已经足够强大，仍然能给出有价值的结果。很多时候，你只要给它一个困难问题，即便准备工作很少，也能得到不错的输出。清晰的 提示词 不是获得价值的前提，但它确实会让结果更可靠，尤其是在大型代码库或高风险任务中。

如果你在大型或复杂仓库中工作，最大的提效点往往是：给 Codex 正确的任务上下文，并把你希望它完成什么描述得足够清楚。

一个很实用的默认模板，是在提示词中包含四件事：

  • 目标（Goal）： 你想改什么，或者想构建什么？
  • 上下文（Context）： 这项任务相关的文件、目录、文档、示例或报错是什么？你也可以用 @ 提及特定文件作为上下文。
  • 约束（Constraints）： Codex 需要遵守哪些标准、架构约束、安全要求或团队约定？
  • 完成条件（Done when）： 在任务完成前，应该满足什么条件？例如测试通过、行为发生预期变化，或某个问题不再复现。

这样可以帮助 Codex 保持范围清晰、减少臆测，并产出更容易评审的工作结果。

推理强度应根据任务难度来选，并结合你的实际工作流测试哪种设置最好。不同用户、不同任务，最优设置往往并不相同。

  • Low：适合追求速度、范围明确的任务。
  • Medium 或 High：适合更复杂的改动或调试任务。
  • Extra High：适合长时间运行、更依赖智能体执行、推理负担更重的任务。

对复杂任务，先做计划

如果任务复杂、含糊，或者很难一次性描述清楚，先让 Codex 规划，再让它开始写代码。

几种常见做法都很有效：

使用计划模式： 对多数用户来说，这是最简单也最有效的方式。计划模式让 Codex 在实现之前先收集上下文、提出澄清问题，并建立更扎实的计划。可通过 /plan 或 Shift+Tab 切换。

让 Codex 先"采访"你： 如果你只知道自己想要什么的大概方向，却说不清楚细节，可以先让 Codex 反过来问你问题。告诉它挑战你的假设，把模糊想法打磨成具体方案，然后再开始写代码。

使用 PLANS.md 模板： 对于更进阶的工作流，你可以让 Codex 遵循 PLANS.md 或执行计划模板，来处理更长、更分阶段的任务。更多细节参见 执行计划指南。

用 AGENTS.md 让指导可复用

当某种提示词模式开始稳定有效，下一步就是不要每次都手动重复它。这时就该使用 AGENTS.md 了。

你可以把 AGENTS.md 理解成面向智能体的开放格式 README。它会自动进入上下文，也是编码你和团队希望 Codex 在仓库中如何工作的最佳位置。

一个好的 AGENTS.md 应该覆盖：

  • 仓库结构和重要目录
  • 如何运行这个项目
  • 构建、测试和 lint 命令
  • 工程约定与 PR 预期
  • 约束条件和禁止事项
  • 什么才算完成，以及如何验证结果

CLI 中的 /init 斜杠命令是快速起手命令，它会在当前目录生成一个基础版 AGENTS.md。这是很好的起点，但你仍然应该按团队真实的构建、测试、评审和交付方式来修改它。

你可以在不同层级创建 AGENTS.md：一个位于 ~/.codex 的全局 AGENTS.md 用于个人默认偏好；一个仓库级文件用于团队共享标准；还可以在子目录中放更具体的局部规则。如果当前目录附近存在更具体的文件，它会拥有更高优先级。

保持务实。一个短小、准确的 AGENTS.md，远比一个冗长却空泛的文件有用。先从最基础的规则开始，只有当你发现某类错误反复出现时，再把新规则写进去。

如果 AGENTS.md 变得太大，就把主文件保持精简，并引用一些任务专用的 markdown 文件，例如规划、代码评审或架构指南。

通过配置让 Codex 更稳定

配置是让 Codex 在不同会话和不同使用端上行为更一致的主要手段之一。例如，你可以为模型选择、推理强度、沙箱模式、审批策略和 MCP 设置默认值，也可以把配置档案专属覆盖值放进独立的 $CODEX_HOME/profile-name.config.toml 文件。

一个常见的起步模式是：

  • 把个人默认配置放在 ~/.codex/config.toml（可在 Codex App 中通过 Settings（设置） → Configuration → Open config.toml 打开）
  • 把仓库专属行为放在 .codex/config.toml
  • 只有在一次性场景下才使用命令行覆盖参数（如果你使用 CLI）

config.toml 是你定义持久偏好的地方，例如 MCP server、多智能体设置和功能开关。配置档案专属覆盖值放在独立的 $CODEX_HOME/profile-name.config.toml 文件中。

Codex 自带操作系统级的沙箱，并且有两个关键旋钮可控：审批模式决定 Codex 什么时候必须向你请求执行权限；沙箱模式决定 Codex 能否在目录中读写，以及智能体可以访问哪些文件。

如果你刚开始接触编码智能体，建议先使用默认权限。默认情况下尽量收紧审批和沙箱，只有当某个受信任仓库或工作流确实需要更高权限时，再逐步放开。

CLI、IDE 和 Codex App 共用同一套配置层。更多信息见 示例配置。

通过测试与评审提高可靠性

不要只停留在"让 Codex 改代码"这一步。还要让它在需要时补测试、运行相关检查、确认结果，并在你接受改动前先做评审。

Codex 可以替你执行这个循环，但前提是它知道什么叫"做好了"。这种标准既可以来自提示词，也可以来自 AGENTS.md。

这可以包括：

  • 为这次改动编写或更新测试
  • 运行合适的测试套件
  • 检查 lint、格式化或类型检查结果
  • 确认最终行为符合需求
  • 审查 diff，查找 bug、回归或高风险模式

另一个有用的选项是 /review 斜杠命令，它提供了几种评审代码的方式：

  • 基于某个基准分支做类似 PR 的评审
  • 评审未提交的改动
  • 评审某个 commit
  • 使用自定义评审指令

在合适的指令下，Codex 不只会生成代码，也能帮你测试它、检查它、审查它。

如果你和团队拥有一个 code_review.md 文件，并在 AGENTS.md 中引用它，那么 Codex 在评审时也会遵循那份指导。这是很适合希望在多个仓库和贡献者之间保持评审一致性的团队模式。

如果你使用 GitHub Cloud（云端版 GitHub），还可以让 Codex 为你的 PR 运行 代码评审。在 OpenAI，Codex 会评审 100% 的 PR。你既可以开启自动评审，也可以在需要时通过 @Codex 触发。

用 MCP 获取外部上下文

当 Codex 需要的上下文不在仓库内部时，就应该使用 MCP。这样 Codex 就可以连接你已经在用的工具和系统，而不必每次都靠你手动复制粘贴实时信息。

Model Context Protocol，也就是 MCP，是一个把 Codex 连接到外部工具和系统的开放标准。

以下情况尤其适合使用 MCP：

  • 需要的上下文不在仓库里
  • 数据变化频繁
  • 你希望 Codex 直接使用工具，而不是依赖你手动粘贴说明
  • 你需要一套可在多人或多项目间复用的稳定集成

Codex 支持带 OAuth 的 STDIO 和 Streamable HTTP servers。

在 Codex App 中，可以前往 Settings（设置） → MCP servers 查看自定义和推荐的 MCP servers。很多时候，Codex 甚至能帮你把所需的 MCP server 安装好，你只需要提出需求即可。在 CLI 中，你也可以使用 codex mcp add 命令，用名称、URL 等信息把 MCP server 加入配置。

把可重复工作沉淀成技能

当某个工作流开始反复出现，就不要继续依赖超长提示词或来回反复沟通了。使用 技能 把说明、上下文和辅助逻辑打包进 SKILL.md，让 Codex 能稳定复用。技能可以同时工作在 CLI、IDE 扩展和 Codex App 中。

让每个技能只做一件事。先从 2 到 3 个具体用例开始，定义清楚输入和输出，并把描述写成"这个技能做什么、什么时候该用"的形式。描述中最好直接包含用户现实中可能会说出的触发语句。

不要一开始就试图覆盖所有边界情况。先拿一个代表性任务跑通，再把它沉淀成技能，然后逐步迭代。只有当脚本或额外资源真的能提升可靠性时，再把它们加入技能。

一个很好的经验法则是：如果你一再复用同一个提示词，或者一再纠正同一套流程，那它大概率就该变成一个技能了。

Skills 特别适合处理这类反复出现的工作：

  • 日志分诊
  • 发布说明草稿撰写
  • 按检查清单评审 PR
  • 迁移方案规划
  • 遥测数据或事故摘要整理
  • 标准化调试流程

$skill-creator 技能是生成第一个技能骨架的最佳起点。第一版先保持在本地迭代；当它适合更广范围分享时，再把它打包成 插件。技能最重要的部分之一就是描述，它必须清楚说明技能做什么，以及何时使用它。

用自动化处理重复工作

当某个工作流已经稳定，你就可以让 Codex 在后台按计划替你运行它。在 Codex App 中， 自动化 允许你为重复任务选择项目、提示词、执行频率和运行环境。

一旦某个任务对你来说已经变成重复劳动，就可以在 Codex App 的 Automations 标签中创建自动化。你可以选择它运行在哪个项目、运行哪个提示词（也可以调用技能）、多久运行一次，以及它是在专用 Git 工作树里跑，还是在你的本地环境中跑。更多信息见 Git 工作树。

适合自动化的任务包括：

  • 汇总最近的提交
  • 扫描可能存在的问题
  • 起草发布说明
  • 检查 CI 失败原因
  • 生成站会摘要
  • 按计划运行可重复的分析流程

一个有用的经验法则是：技能定义方法，自动化负责调度。如果某个流程还需要大量人工引导，先把它沉淀成技能；当它变得可预测之后，自动化才会真正放大效果。

用会话控制组织长时间工作

Codex 会话不只是聊天记录。它们是会不断积累上下文、决策和动作的工作线程，因此如何管理会话，会直接影响输出质量。

Codex App 的界面最适合管理线程，因为你可以固定线程，并创建工作树。如果你在使用 CLI，下列 斜杠命令 特别有用：

  • /experimental：切换实验性功能，并把设置写入 config.toml
  • /resume：恢复一段已保存的会话
  • /fork：在保留原始对话记录的同时创建一个新线程
  • /compact：当线程变长、你希望把前文压缩成摘要时使用。注意 Codex 也会自动为你压缩会话
  • /agent：当你在并行运行多个智能体，并想切换当前活动的智能体线程时使用
  • /theme：选择语法高亮主题
  • /apps：在 Codex 中直接使用 ChatGPT apps
  • /status：查看当前会话状态

尽量让一个线程只对应一个完整的工作单元。如果任务仍然属于同一个问题，继续留在同一个线程里通常更好，因为它能保留推理轨迹。只有当任务真正分叉时，才去 fork。

常见错误

刚开始使用 Codex 时，最好避免下面这些常见错误：

  • 把那些应该长期生效的规则都塞进提示词，而不是沉淀到 AGENTS.md 或技能里
  • 没有告诉智能体应该怎样运行构建和测试命令，导致它无法真正"看到"自己的工作结果
  • 面对多步骤或复杂任务时跳过规划
  • 在还没理解工作流之前，就把整台电脑的完整权限交给 Codex
  • 在同一批文件上同时跑多个活跃线程，却不使用 Git 工作树
  • 某个重复任务还没被手动验证为稳定，就急着把它做成自动化
  • 把 Codex 当成必须一步步盯着看的工具，而不是让它与你的工作并行推进
  • 以项目为单位开线程，而不是以任务为单位开线程。这会让上下文越来越臃肿，结果也会随时间变差