https://developers.openai.com/codex/learn/best-practices
翻译：gemini 3 flash
最佳实践
如果你是 Codex 或编程代理的新手，本指南将帮助你更快地获得更好的结果。它涵盖了使 Codex 在 CLI、IDE extension 和 Codex app 中更有效的核心习惯，从提示和规划到验证、MCP、技能和自动化。当你减少将 Codex 视为一次性助手，而更多地将其视为你随时间配置和改进的队友时，它的效果最好。一个有用的思考方式：从正确的任务上下文开始，使用 AGENTS.md 进行持久指导，配置 Codex 以匹配你的工作流，通过 MCP 连接外部系统，将重复性工作转化为技能，并自动化稳定的工作流。
强大的首次使用：上下文和提示
即使你的提示并不完美，Codex 已经足够强大到可以发挥作用。你通常可以交给它一个复杂的问题，只需最少的设置，仍然可以得到强大的结果。清晰的 prompting 并非获得价值所必需的，但它确实能让结果更可靠，特别是在较大的代码库或高风险任务中。如果你在大型或复杂的仓库中工作，最大的突破是为 Codex 提供正确的任务上下文和明确的任务结构。一个好的默认做法是在你的提示中包含四件事：
目标： 你想要更改或构建什么？
上下文： 哪些文件、文件夹、文档、示例或错误对该任务很重要？你可以使用 @ 提及特定文件作为上下文。
约束： Codex 应该遵循哪些标准、架构、安全要求或约定？
完成标准： 在任务完成之前什么应该是真实的，例如测试通过、行为改变或错误不再重现？
这有助于 Codex 保持在范围内，减少假设，并产生更容易审查的工作。根据任务的难度选择推理级别，并测试最适合你工作流的设置。不同的用户和任务在不同的设置下效果最好。
低：用于更快的、范围明确的任务
中或高：用于更复杂的更改或调试
特高：用于冗长的、代理式的、推理繁重的任务
为了更快地提供上下文，尝试在 Codex 应用程序中使用语音听写来口述你想要 Codex 执行的操作，而不是打字。
为困难任务先做规划
如果任务复杂、模糊或难以描述清楚，请在 Codex 开始编码之前要求其制定计划。以下几种方法效果很好：
使用 Plan 模式： 对于大多数用户来说，这是最简单且最有效的选择。计划模式允许 Codex 在实施之前收集上下文、提出澄清问题并制定更完善的计划。使用 /plan 或 Shift+Tab 切换。
让 Codex 面试你： 如果你对自己想要的东西有一个粗略的想法，但不确定如何描述清楚，请先让 Codex 询问你。让它挑战你的假设，并在编写代码之前将模糊的想法转化为具体的内容。
使用 PLANS.md 模板： 对于更高级的工作流，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，以进行长期运行或多步骤工作。有关更多详细信息，请参阅 execution plans guide。
使用 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 犯了两次同样的错误时，要求它进行回顾并更新 AGENTS.md。指导应保持实用并基于实际的摩擦。
配置 Codex 以保持一致性
配置是让 Codex 在不同会话和界面上表现更一致的主要方式之一。例如，你可以设置模型选择、推理工作量、沙盒模式、批准策略、配置文件和 MCP 设置。
一个好的起始模式是：
在 /.codex/config.toml 中保留个人默认设置（设置 → 配置 → 从 Codex 应用打开 config.toml）
在 .codex/config.toml 中保留特定于仓库的行为
仅在一次性情况下使用命令行覆盖（如果你使用 CLI）
config.toml 是你定义持久首选项的地方，例如 MCP 服务器、配置文件、多代理设置和功能标志。你可以直接编辑它或让 Codex 为你更新。
Codex 带有操作层级的沙盒，并有两个你可以控制的关键旋钮。批准模式决定了 Codex 何时请求你运行命令的许可，沙盒模式决定了 Codex 是否可以在目录中进行读写以及代理可以访问哪些文件。如果你是编程代理的新手，请从默认权限开始。默认保持严格的批准和沙箱，仅在需求明确后才为受信任的仓库或特定工作流放宽权限。
请注意，CLI、IDE 和 Codex 应用程序共享相同的配置层。在 sample configuration 页面了解更多信息。尽早为你的真实环境配置 Codex。许多质量问题实际上是设置问题，例如错误的工作目录、缺少写入权限、错误的模型默认值或缺少工具和连接器。
通过测试和审查提高可靠性
不要仅仅停留于要求 Codex 做出更改。要求它在需要时创建测试、运行相关检查、确认结果并在你接受之前审查结果。Codex 可以为你完成这个循环，但前提是它知道“好”的标准是什么。该指导可以来自提示或 AGENTS.md。这可以包括：
为更改编写或更新测试
运行正确的测试套件
检查 lint、格式化或类型检查
确认最终行为与请求匹配
审查 diff 中的 bug、回归或风险模式
在 Codex 应用程序中切换 diff 面板以直接在本地 review changes。点击特定行以提供反馈，该反馈将作为上下文输入到下一个 Codex 回合。
这里一个有用的选项是斜杠命令 /review，它为你提供了几种审查代码的方式：
对比基准分支进行 PR 风格审查
审查未提交的更改
审查一次提交
使用自定义审查指令
如果你和团队有一个 code_review.md 文件并在 AGENTS.md 中引用它，Codex 在审查期间也可以遵循该指导。对于希望在不同仓库和贡献者之间保持审查行为一致的团队，这是一个强大的模式。
Codex 不应仅仅生成代码。有了正确的指令，它还可以帮助测试、检查和审查代码。如果你使用 GitHub Cloud，可以设置 Codex 为你的 PRs 运行代码审查。在 OpenAI，Codex 审查 100% 的 PR。你可以启用自动审查，或在 @Codex 时让 Codex 进行反应式审查。
使用 MCP 获取外部上下文
当 Codex 需要的上下文位于仓库外部时，使用 MCP。它让 Codex 连接到你已经使用的工具和系统，这样你就不必一直将实时信息复制粘贴到提示中。
Model Context Protocol（或 MCP）是将 Codex 连接到外部工具和系统的开放标准。在以下情况下使用 MCP：
所需上下文位于仓库外部
数据频繁更改
你希望 Codex 使用工具而不是依赖粘贴的指令
你需要跨用户或项目的可重复集成
Codex 支持 STDIO 和带有 OAuth 的 Streamable HTTP 服务器。在 Codex App 中，前往设置 → MCP 服务器查看自定义和推荐的服务器。通常，Codex 可以帮助你安装所需的服务器。你只需提出要求即可。你还可以在 CLI 中使用 codex mcp add 命令添加具有名称、URL 和其他详细信息的自定义服务器。
仅在工具能解锁真实工作流时才添加它们。不要从接入你使用的每一个工具开始。从一两个明显能消除你经常进行的手动循环的工具开始，然后从那里扩展。
将可重复的工作转化为技能
一旦工作流变得可重复，停止依赖冗长的提示或重复的来回沟通。使用 Skill 将指令打包在 SKILL.md 文件、上下文和 Codex 应一致应用的配套逻辑中。技能可以在 CLI、IDE 扩展和 Codex 应用程序中跨平台运行。
保持每个技能专注于一项工作。从 2 到 3 个具体的用例开始，定义清晰的输入和输出，并编写描述，说明该技能的作用以及何时使用。包括用户实际会说的各种触发短语。不要试图一开始就涵盖所有边缘情况。从一个具有代表性的任务开始，让它运转良好，然后将该工作流转化为技能并在此基础上改进。仅在能够提高可靠性时才包含脚本或额外资产。
一个经验法则：如果你一直重复使用相同的提示或纠正相同的工作流，它可能应该变成一个技能。技能对于以下经常性工作特别有用：
日志分类
发布说明起草
根据检查清单进行 PR 审查
迁移计划
遥测或事故摘要
标准调试流程
$skill-creator 技能是搭建技能首个版本的最佳起点。在迭代时保持第一个版本是本地的。当准备好广泛分享时，将其打包为 plugin。技能最重要的部分之一是描述。它应该说明技能的作用以及何时使用。个人技能存储在 $HOME/.agents/skills 中，团队共享技能可以签入仓库内的 .agents/skills。这对新队友的入职特别有帮助。
使用自动化处理重复工作
一旦工作流稳定，你可以安排 Codex 在后台为你运行。在 Codex 应用中，automations 让你为重复性任务选择项目、提示、节奏和执行环境。
一旦一项任务对你来说变得重复，你可以在 Codex 应用的“自动化”选项卡中创建一个自动化。你可以选择它运行的项目、它运行的提示（可以调用技能）以及运行的节奏。你还可以选择自动化是在专用的 git worktree 中运行还是在本地环境中运行。了解更多关于 git worktrees 的信息。
合适的候选任务包括：
总结最近的提交
扫描可能的 bug
起草发布说明
检查 CI 失败
生成站会摘要
按计划运行可重复的分析工作流
一个有用的规则是，技能定义方法，自动化定义计划。如果工作流仍然需要大量引导，请先将其转化为技能。一旦它是可预测的，自动化就会成为力量倍增器。将自动化用于反思和维护，而不仅仅是执行。审查最近的会话，总结重复的摩擦，并随着时间的推移改进提示、指令或工作流设置。
使用会话控制组织长期运行的工作
Codex 会话不仅仅是聊天记录。它们是随着时间的推移积累上下文、决策和行动的工作线程，因此管理好它们对质量有很大影响。Codex 应用界面使线程管理最容易，因为你可以固定线程并创建 worktrees。
如果你使用的是 CLI，这些 slash commands 特别有用：
/experimental 切换实验性功能并添加到你的 config.toml
/resume 恢复保存的对话
/fork 创建新线程并保留原始转录
/compact 当线程变长且你想要早期上下文的摘要版本时。请注意，Codex 会自动为你压缩对话
/agent 当你运行并行代理并想在活动代理线程之间切换时
/theme 选择语法高亮主题
/apps 在 Codex 中直接使用 ChatGPT 应用程序
/status 检查当前会话状态
每个连贯的工作单元保持一个线程。如果工作仍然是同一个问题的一部分，留在同一个线程中通常更好，因为它保留了推理轨迹。仅在工作真正出现分支时才执行 Fork。使用 Codex 的 subagent 工作流从主线程卸载有界限的工作。保持主代理专注于核心问题，并使用子代理执行探索、测试或分类等任务。
常见错误
初次使用 Codex 时应避免的几个常见错误：
将持久规则过度加载到提示中，而不是移动到 AGENTS.md 或技能中
不提供如何最好地运行构建和测试命令的详细信息，从而不让代理看到其工作结果
在多步骤和复杂任务上跳过规划
在了解工作流之前给予 Codex 对你计算机的完全权限
在不使用 git worktrees 的情况下在相同文件上运行实时线程
在手动运行尚不可靠之前将经常性任务转化为自动化
将 Codex 视为必须步步监视的对象，而不是与你自己的工作并行使用
每个项目使用一个线程，而不是每个任务一个线程。这会导致上下文臃肿，并随着时间的推移降低结果质量
