前言
Codex 是 OpenAI 推出的编程智能体，想用好它，关键在于把它当作可持续优化的团队伙伴。本指南从提示词编写、AGENTS.md 规范沉淀、环境配置、MCP 外部集成、技能封装到工作流自动化，系统梳理了提升 Codex 使用效果的核心方法，帮助你从第一次使用就建立高效的协作模式。
今日前端早读课文章由 @openAI 分享，@飘飘编译。
译文从这开始～～
如果你刚刚接触 Codex 或编程智能体，这份指南将帮助你更快获得更好的结果。本指南涵盖了在 CLI、IDE 扩展和 Codex 应用中提升使用效果的核心方法，涉及提示词编写、任务规划、结果验证、MCP、技能库和自动化等方面。 【第3665期】WebMCP：让每个网站都能与智能代理互动的新标准
把 Codex 当作一个可以持续调教和优化的团队伙伴，而非一次性的问答助手 —— 这样才能发挥它的最大价值。
一个有用的思考方式：从准确的任务上下文入手，用 AGENTS.md 沉淀长期有效的指导规范，根据你的工作流配置 Codex，通过 MCP 接入外部系统，将反复出现的工作抽象为技能，并将成熟的工作流设为自动化任务。
#### 良好的第一步：上下文与提示词
Codex 已经足够强大，即使你的提示词不完美，依然能给出有价值的结果。很多时候，你只需简单描述一个棘手的问题，无需过多准备，就能获得不错的输出。清晰的提示词并非获取价值的必要条件，但它能让结果更加稳定可靠 —— 尤其是在大型代码库或高风险任务中。
如果你的项目仓库规模较大或结构复杂，最关键的突破口在于：为 Codex 提供准确的任务上下文，并清晰地描述你期望完成的工作结构。
一个好的默认做法是在提示词中包含以下四个要素：
* 目标：你想要更改或构建什么？
* 上下文：哪些文件、文件夹、文档、示例或错误信息与本次任务相关？你可以@提及特定文件作为上下文。
* 约束条件：Codex 需要遵守哪些标准、架构要求、安全规范或编码惯例？
* 完成标准：任务完成时应满足什么条件？比如测试通过、行为发生变化，或某个 Bug 不再复现。
这样做能帮助 Codex 聚焦范围、减少臆测，并产出更容易审查的成果。 【第3670期】AI 工程实战：Claude Code 团队总结的六条反直觉缓存法则
根据任务难度选择合适的推理级别，并测试哪种最适合你的工作流程。不同的用户和任务适合不同的配置：
* Low（低）：适用于快速、范围明确的任务
* Medium（中）或 High（高）：适用于较复杂的代码变更或调试
* Extra High（超高）：适用于长周期、智能体驱动、需要深度推理的任务
为了更快地提供上下文，你可以在 Codex 应用中使用语音输入来口述任务需求，而不必逐字敲键盘。
#### 任务规划
如果任务复杂、模糊或难以精确描述，请在 Codex 开始编码之前要求它先规划。
几种方法效果很好： 1、使用计划模式：
对于大多数用户，这是最简单且最有效的选项。计划模式让 Codex 先收集上下文、提出澄清性问题，在动手实现之前构建更完善的方案。使用/plan或Shift+Tab切换。
2、让 Codex 反过来采访你：
如果你对想要的内容有一个粗略的想法，但不确定如何很好地描述它，可以让 Codex 先向你提问。告诉它质疑你的假设，把模糊的想法打磨成具体方案后再开始编码。 3、使用 PLANS.md 模板：
对于更高级的工作流程，你可以配置 Codex 遵循 PLANS.md 或执行计划模板，用于长时间运行或多步骤工作。
#### AGENTS.md：沉淀可复用的规范
当某个提示词模式被验证有效后，下一步就是不再每次手动重复它 —— 这正是 AGENTS.md 的用武之地。
你可以把 AGENTS.md 理解为一份面向智能体的开放格式 README。它会自动加载到上下文中，是记录你和团队希望 Codex 在仓库中如何工作的最佳载体。 Agent 入门书《Hello-Agents》导读
一个好的 AGENTS.md 涵盖：
* 仓库结构和重要目录说明
* 项目的运行方式
* 构建、测试和 lint 命令
* 工程约定和 PR 期望
* 约束和禁止规则
* 完成意味着什么以及如何验证工作
##### AGENTS.md 的使用细节
CLI 中的/init斜杠命令是快速启动命令，可以在当前目录下生成一份初始的 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。 许多质量问题实际上是配置问题 —— 比如错误的工作目录、缺少写入权限、模型默认值不对，或者缺少工具和连接器。 【第3211期】使用现代的 Node.js 构建简单的CLI工具
#### 验证、测试和审查
不要仅仅让 Codex 做出修改就结束了。让它在需要时创建测试、运行相关检查、确认结果，并在你接受之前审查工作成果。
Codex 可以为你执行这个完整循环，但前提是它知道 "好的结果" 长什么样。这些指导可以来自提示词或 AGENTS.md。
具体包括：
* 为变更编写或更新测试
* 运行正确的测试套件
* 检查代码规范、格式化或类型检查
* 确认最终行为符合请求
* 审查 diff 以排查 Bug、回归问题或高风险模式
在 Codex 应用中切换 diff 面板可以直接在本地审查变更。点击特定行可以提供反馈，这些反馈会作为上下文传入下一轮 Codex 交互。
##### /review 命令
一个非常实用的选项是/review斜杠命令，它提供了几种审查代码的方式：
* 对比基准分支进行 PR 风格的审查
* 审查未提交的变更
* 审查某次提交
* 使用自定义审查指令
如果你和你的团队有 一份 code_review.md 文件并从 AGENTS.md 引用它，Codex 也可以在审查期间遵循该指导。这对于希望在不同仓库和贡献者之间保持审查行为一致的团队来说，是一个非常强大的模式。
Codex 不应该只是生成代码。通过正确的指令，它还能帮你测试代码、检查代码和审查代码。
#### 使用 MCP 进行外部上下文
当 Codex 需要的上下文存在于仓库外部时，请使用 MCP 来解决。它让 Codex 连接到你已经在使用的工具和系统，所以你不必反复将实时信息复制和粘贴到提示词中。
模型上下文协议，或 MCP，是连接 Codex 到外部工具和系统的开放标准。
适合使用 MCP 的场景：
* 所需上下文存在于仓库之外
* 数据频繁变化
* 你希望 Codex 直接调用工具，而不是依赖粘贴进来的指令
* 你需要一个可在用户或项目间复用的集成方案
Codex 通过 OAuth 支持标准 STDIO 和可流式 HTTP 服务器。
在 Codex 应用中，前往 设置 → MCP 服务器即可查看自定义和推荐的服务器。通常，Codex 可以帮助你安装所需的服务器。你只需开口问它就好。你也可以在 CLI 中使用 codex mcp add 命令添加带有名称、URL 和其他详细信息的自定义服务器。
只在真正能打通工作流时才接入工具。 不要一上来就把你用的所有工具都接进来。先从一两个能明确消除你常做的手动操作的工具开始，然后再逐步扩展。
#### 将重复工作转换为技能
当一个工作流程变得可重复，就不要再依赖冗长的提示词或反复的来回对话了。使用技能 将指令打包在 SKILL.md 文件中，包含上下文和 Codex 应一致执行的辅助逻辑。技能在 CLI、IDE 扩展和 Codex 应用之间工作。
让每个技能只专注于一件事。 先从 2 到 3 个具体的使用场景入手，定义清晰的输入和输出，描述中要说明这个技能做什么以及何时使用它。还要包含用户实际会说的触发短语。
不要试图一开始就覆盖所有边界情况。先从一个典型任务开始，把它调到好用，然后将该工作流转化为技能，再逐步迭代改进。只有当脚本或额外资源确实能提升可靠性时，才把它们加进去。
一个简单的判断标准：如果你发现自己不断复用同一个提示词，或反复纠正同一个工作流，那它大概率应该成为一个技能。 【第3533期】Cursor AI 最佳实践：使用“金标准文件”工作流以获得更精确的结果
技能特别适用于以下类型的周期性工作：
* 日志分类筛查
* 发布说明起草
* 按检查清单进行 PR 审查
* 迁移方案规划
* 遥测数据或事故摘要
* 标准化调试流程
$skill-creator技能是创建首个技能版本的最佳起点，而$skill-installer技能可以帮你在本地安装它。技能中最重要的部分之一是描述 —— 它应该说明这个技能做什么以及何时使用。
个人技能存储在$HOME/.agents/skills中，共享团队技能可以检入到仓库内的.agents/skills中。这特别有助于引导新团队成员。
#### 自动化成熟的工作流
当一个工作流趋于稳定后，你可以安排 Codex 在后台自动执行。在 Codex 应用中，自动化功能让你为周期性任务选择项目、提示词、执行频率和运行环境。
当某项任务对你来说已经变得重复，你可以在 Codex 应用的「自动化」标签页中创建自动化任务。你可以选择它在哪个项目中运行、运行什么提示词（可以调用技能），以及执行频率。你还可以选择自动化任务是在专用的 git worktree 中运行，还是在本地环境中运行。
适合自动化的场景包括：
* 汇总近期提交记录
* 扫描潜在 Bug
* 起草发布说明
* 检查 CI 失败原因
* 生成每日站会摘要
* 按计划运行可重复的分析工作流
一个实用的原则是：技能定义方法，自动化定义节奏。 如果一个工作流仍需大量人工干预，先把它打磨成技能。一旦它的表现变得稳定可预期，自动化就能成为效率的倍增器。
善用自动化来做反思和维护，而不仅仅是执行任务。定期回顾近期会话，总结反复出现的摩擦点，持续改进提示词、指令和工作流配置。
#### 管理会话和线程
Codex 会话不仅仅是聊天历史。它们是随时间积累上下文、决策和操作的工作线程，因此良好的管理对输出质量有着显著影响。
Codex 应用的界面让线程管理变得最为便捷，因为你可以置顶线程并创建 worktree。如果你使用 CLI，以下斜杠命令尤其实用：
* /experimental
— 切换实验性功能并添加到 config.toml
* /resume
— 恢复已保存的对话
* /fork
— 创建新线程，同时保留原始对话记录
* /compact
— 当线程过长时，生成此前上下文的精简摘要。需要注意的是，Codex 会自动为你压缩对话
* /agent
— 在并行运行多个智能体时，切换当前活跃的智能体线程
* /theme
— 选择语法高亮主题
* /apps
— 在 Codex 中直接使用 ChatGPT 应用
* /status
— 查看当前会话状态
每个连贯的工作单元保持一个线程。 如果工作仍属于同一个问题的一部分，留在同一个线程中通常更好，因为它保留了完整的推理脉络。只有当工作真正分叉时，才去创建新线程。
善用 Codex 的子智能体工作流，将边界明确的工作从主线程中剥离出去。让主智能体专注于核心问题，将探索、测试或问题分类等任务交给子智能体处理。
#### 避免常见错误
初次使用 Codex 时，有几个常见的误区需要注意：
* 把持久性规则堆在提示词里，而不是将它们迁移到 AGENTS.md 或技能中
* 不让智能体看到自己的工作成果 —— 没有详细说明如何运行构建和测试命令
* 在多步骤的复杂任务中跳过规划阶段
* 在尚未理解工作流之前就给 Codex 完全的系统权限
* 在同一批文件上运行多个活跃线程，而没有使用 git worktree 隔离
* 在手动执行尚不稳定时就急于将任务自动化
* 把 Codex 当成需要逐步盯着看的东西，而不是将它与自己的工作并行推进
* 一个项目只用一个线程，而不是一个任务一个线程 —— 这会导致上下文臃肿膨胀，随着时间推移效果越来越差
关于本文
译者：@飘飘
原文：https://developers.openai.com/codex/learn/best-practices/