OpenAI Codex AI编码助手最佳实践

如果你是 Codex 或通用代码代理的新手，本指南将帮助你更快地获得更好的结果。它涵盖了使 Codex 在 CLI、IDE 扩展和 Codex 应用中更有效的核心习惯，包括从提示和规划到验证、MCP、技能和自动化。

Codex 效果最佳时，你将其视为一个可以配置和随着时间改进的队友，而不是一次性助手。

一个有用的思考方式：从正确的任务上下文开始，使用 AGENTS.md 进行持久性指导，配置 Codex 以匹配你的工作流程，通过 MCP 连接外部系统，将重复工作转化为技能，并自动化稳定的工作流程。

强有力的首次使用：上下文和提示

即使你的提示不完美，Codex 也足够强大，足以发挥作用。你通常可以以最少的设置将一个难题交给它，并仍然获得很好的结果。清晰的提示并不是获得价值的必要条件，但它确实使结果更可靠，尤其是在大型代码库或高风险任务中。

如果你在一个大型或复杂的仓库中工作，最大的突破是给 Codex 提供正确的任务上下文和清晰的工作结构。

一个好的默认做法是在你的提示中包含四项内容：

• 目标： 你想要改变或构建什么？
• 上下文： 哪些文件、文件夹、文档、示例或错误对这项任务很重要？你可以使用 @ 提及特定文件作为上下文。
• 约束： Codex 应该遵循哪些标准、架构、安全要求或约定？
• 完成条件： 在任务完成之前，哪些条件应该为真，例如测试通过、行为改变或错误不再重现？

这有助于 Codex 保持范围明确，减少假设，并生成更容易审查的工作。

根据任务的难度选择推理级别，并测试最适合你的工作流程的设置。不同的用户和任务在不同的设置下表现最佳。

• Low 用于更快、范围明确的任务
• Medium 或 High 用于更复杂的更改或调试
• Extra High 用于长时间、代理化、推理繁重的任务

为了更快地提供上下文，尝试在 Codex 应用内使用语音听写来告诉 Codex 你想让它做什么，而不是打字。

针对困难任务先进行规划

如果任务复杂、模糊或难以很好地描述，请在 Codex 开始编码之前要求它进行规划。

有几种方法效果良好：

使用 Plan 模式： 对于大多数用户来说，这是最简单和最有效的选项。Plan 模式允许 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 文件：一个用于个人默认设置的全局 AGENTS.md，它位于 ~/.codex 中；一个用于共享标准的仓库级别文件；以及子目录中用于本地规则的更具体文件。如果你的当前目录附近有更具体的文件，该指导将优先。

保持实用。一个简短、准确的 AGENTS.md 比一个充满模糊规则的长文件更有用。从基础开始，然后只有在你注意到重复的错误后才添加新规则。

如果 AGENTS.md 开始变得太大，请保持主文件简洁，并引用特定任务的 Markdown 文件，例如规划、代码审查或架构。

当 Codex 犯了两次相同的错误时，要求它进行回顾并更新 AGENTS.md。指导保持实用并基于实际的摩擦。

配置 Codex 以保持一致性

配置是使 Codex 在不同会话和界面之间表现更一致的主要方式之一。例如，你可以设置模型选择、推理工作量、沙盒模式、批准策略、配置文件和 MCP 设置的默认值。

一个好的起始模式是：

• 将个人默认设置保存在 ~/.codex/config.toml 中（Codex 应用中的“设置”→“配置”→“打开 config.toml”）
• 将仓库特定的行为保存在 .codex/config.toml 中
• 仅在一次性情况下使用命令行覆盖（如果你使用 CLI）

config.toml 是你定义持久偏好（如 MCP 服务器、配置文件、多代理设置和实验性功能）的地方。你可以直接编辑它，或者要求 Codex 帮你更新。

Codex 附带操作系统级别的沙盒，并有两个你可以控制的关键旋钮。Approval mode 决定 Codex 何时请求你的权限来运行命令，sandbox mode 决定 Codex 是否可以在目录中读写以及代理可以访问哪些文件。

如果你是代码代理新手，请从默认权限开始。默认情况下保持批准和沙盒严格，然后只有在信任的仓库或特定工作流程明确需要时才放宽权限。

请注意，CLI、IDE 和 Codex 应用都共享相同的配置层。在示例配置页面了解更多信息。

尽早为你的真实环境配置 Codex。许多质量问题实际上是设置问题，例如错误的工作目录、缺少写入权限、错误的模型默认值或缺少工具和连接器。

通过测试和审查提高可靠性

不要只要求 Codex 进行更改。要求它在需要时创建测试，运行相关检查，确认结果，并在你接受工作之前审查工作。

Codex 可以为你完成这个循环，但前提是它知道“好”是什么样子。该指导可以来自提示或 AGENTS.md。

这可以包括：

• 为更改编写或更新测试
• 运行正确的测试套件
• 检查 lint、格式或类型检查
• 确认最终行为与请求匹配
• 审查差异以查找错误、回归或风险模式

在 Codex 应用中切换差异面板，直接在本地审查更改。点击特定行以提供反馈，这些反馈将作为上下文输入到下一个 Codex 轮次。

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

• 针对基础分支进行 PR 风格的审查
• 审查未提交的更改
• 审查提交
• 使用自定义审查指令

如果你和你的团队有一个 code_review.md 文件并从 AGENTS.md 引用它，Codex 也可以在审查期间遵循该指导。这对于希望审查行为在不同仓库和贡献者之间保持一致的团队来说是一个强大的模式。

Codex 不仅仅应该生成代码。通过正确的指令，它还可以帮助测试、检查和审查代码。

如果你使用 GitHub Cloud，你可以设置 Codex 为你的 PR 运行代码审查。在 OpenAI，Codex 审查 100% 的 PR。你可以启用自动审查，或者在你 @Codex 时让 Codex 做出反应性审查。

使用 MCP 进行外部上下文

当 Codex 需要的上下文存在于仓库之外时，使用 MCP。它允许 Codex 连接到你已经使用的工具和系统，这样你就不必不断地将实时信息复制粘贴到提示中。

Model Context Protocol (模型上下文协议)，或 MCP，是一个开放标准，用于将 Codex 连接到外部工具和系统。

在以下情况使用 MCP：

• 所需的上下文存在于仓库之外
• 数据频繁变化
• 你希望 Codex 使用工具而不是依赖粘贴的指令
• 你需要跨用户或项目进行可重复的集成

Codex 支持带 OAuth 的 STDIO 和 Streamable HTTP 服务器。

在 Codex 应用中，前往“设置”→“MCP 服务器”以查看自定义和推荐的服务器。通常，Codex 可以帮助你安装所需的服务器。你只需要提出要求。你还可以使用 CLI 中的 codex mcp add 命令添加你的自定义服务器，包括名称、URL 和其他详细信息。

仅当工具能开启实际工作流程时才添加它们。不要一开始就连接你使用的所有工具。从一两个明确能消除你经常手动进行的循环的工具开始，然后从那里扩展。

将可重复的工作转化为技能

一旦工作流程变得可重复，就停止依赖冗长的提示或重复的来回沟通。使用技能将指令、上下文和支持逻辑打包到 SKILL.md 文件中，Codex 应该始终如一地应用这些内容。技能在 CLI、IDE 扩展和 Codex 应用中都适用。

将每个技能的范围限定在一个任务。从 2 到 3 个具体的用例开始，定义清晰的输入和输出，并编写描述，说明技能的作用以及何时使用它。包括用户实际可能会说的触发短语。

不要试图提前涵盖所有边缘情况。从一个代表性任务开始，使其运行良好，然后将该工作流程转化为一个技能并从中改进。仅当脚本或额外资产能提高可靠性时才包含它们。

一个好的经验法则：如果你不断重复使用相同的提示或纠正相同的工作流程，它可能应该成为一个技能。

技能对于以下重复性工作特别有用：

• 日志分类
• 发布说明起草
• 对照清单进行 PR 审查
• 迁移规划
• 遥测或事件摘要
• 标准调试流程

$skill-creator 技能是开始搭建技能的第一个版本并使用 $skill-installer 技能在本地安装它的最佳位置。技能最重要的部分之一是描述。它应该说明技能的作用以及何时使用它。

个人技能存储在 $HOME/.agents/skills 中，共享团队技能可以签入到仓库内的 .agents/skills 中。这对于新队友的入职特别有帮助。

使用自动化来完成重复工作

一旦工作流程稳定，你就可以安排 Codex 在后台为你运行它。在 Codex 应用中，自动化允许你选择项目、提示、节奏和执行环境来完成重复任务。

一旦某个任务对你来说变得重复，你可以在 Codex 应用的“自动化”选项卡中创建一个自动化。你可以选择它运行的项目、它运行的提示（你可以调用技能）以及它运行的频率。你还可以选择自动化是在专用的 git worktree 中运行还是在你的本地环境中运行。了解更多关于 git worktrees。

好的候选项包括：

• 总结最近的提交
• 扫描潜在的错误
• 起草发布说明
• 检查 CI 失败
• 生成站会总结
• 按计划运行可重复的分析工作流程

一个有用的规则是，技能定义了方法，自动化定义了计划。如果一个工作流程仍然需要大量的指导，首先将其转化为一个技能。一旦它变得可预测，自动化就会成为一个倍增器。

将自动化用于反思和维护，而不仅仅是执行。审查最近的会话，总结重复的摩擦，并随着时间的推移改进提示、指令或工作流程设置。

使用会话控件组织长时间运行的工作

Codex 会话不仅仅是聊天历史。它们是随着时间积累上下文、决策和操作的工作线程，因此管理好它们对质量有很大影响。

Codex 应用 UI 使线程管理最容易，因为你可以固定线程并创建 worktrees。如果你使用 CLI，这些斜杠命令特别有用：

• /experimental 用于切换实验性功能并添加到你的 config.toml
• /resume 用于恢复保存的对话
• /fork 用于创建新线程，同时保留原始记录
• /compact 当线程变长时，你想要一个早期上下文的摘要版本。请注意，Codex 会自动为你压缩对话
• /agent 当你运行并行代理并想要在活动代理线程之间切换时
• /theme 用于选择语法高亮主题
• /apps 用于在 Codex 中直接使用 ChatGPT 应用
• /status 用于检查当前会话状态

每个连贯的工作单元保持一个线程。如果工作仍然是同一个问题的一部分，留在同一个线程中通常更好，因为它保留了推理轨迹。仅当工作真正分支时才进行 fork。

使用 Codex 的多代理工作流程来将有界定的工作从主线程卸载。让主代理专注于核心问题，并使用子代理执行探索、测试或分类等任务。

常见错误

首次使用 Codex 时应避免的一些常见错误：

• 用持久规则淹没提示，而不是将它们移到 AGENTS.md 或技能中
• 不让代理看到其工作，即不提供关于如何最好地运行构建和测试命令的详细信息
• 在多步骤和复杂任务中跳过规划
• 在你理解工作流程之前，给 Codex 完全的计算机权限
• 在不使用 git worktrees 的情况下在相同文件上运行实时线程
• 在任务手动可靠之前，将其转化为自动化
• 将 Codex 视为你需要一步一步监视的东西，而不是与你自己的工作并行使用
• 每个项目使用一个线程，而不是每个任务使用一个线程。这会导致上下文膨胀和时间久了结果变差

• 原文链接： developers.openai.com/co...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～