原文：https://developers.openai.com/codex/learn/best-practices
发布时间按本站要求填写为：2026-03-20。
说明：原文页面当前正文中未包含内嵌配图，因此本译文按原样保留结构与链接，不额外添加插图。

如果你刚开始使用 Codex，或刚接触“编码智能体（coding agents）”，这份指南可以帮助你更快拿到更稳定的结果。它覆盖了在 CLI、IDE 扩展和 Codex App 中都通用的核心习惯：从提示词与规划，到验证、MCP、Skills 与自动化。

与其把 Codex 当成一次性助手，不如把它当成一个会持续配置和迭代的“队友”。

一个实用思路是：先提供正确任务上下文；用 AGENTS.md 固化长期规则；把 Codex 配置成符合你的工作流；通过 MCP 接入外部系统；把重复工作封装成 Skills；再把稳定流程自动化。

1）第一步先做对：上下文与提示词

即使提示词并不完美，Codex 也已经足够强大，能在较少准备下处理难题并给出不错结果。但清晰提示词会让结果更可靠，尤其在大型仓库或高风险任务中。

如果你在复杂代码库里工作，最大收益点是：给 Codex 正确任务上下文 与 清晰任务结构。

一个通用提示模板建议包含四项：

• Goal（目标）：你要改什么、做什么？
• Context（上下文）：哪些文件、目录、文档、样例或报错相关？（可用 @ 指定文件）
• Constraints（约束）：要遵守哪些规范、架构、安全要求或团队约定？
• Done when（完成标准）：满足什么条件才算完成？（例如测试通过、行为变化、Bug 不再复现）

这样能帮助 Codex 保持边界、减少臆测，也让输出更易审查。

推理强度建议按任务难度选择：

• Low：快速、边界清晰的小任务
• Medium / High：复杂改动或调试
• Extra High：长链路、强推理、偏智能体的任务

另外，在 Codex App 里可以用语音输入快速口述任务，比打字更快补全上下文。

2）复杂任务先规划

当任务复杂、模糊或不易描述时，先让 Codex 做计划，再开始编码。

常用方式：

• Plan mode：最易上手且效果好。可先收集上下文、提澄清问题、形成更强计划，再实施。可用 /plan 或 Shift + Tab 切换。
• 让 Codex 先“采访”你：当你只有朦胧想法时，让它先追问并挑战假设，把模糊需求落到可执行层，再写代码。
• 使用 PLANS.md 模板：适合更高级、长周期、多步骤执行流，可配合执行计划模板统一流程。

3）用 AGENTS.md 复用规则

当某类提示词模式开始生效，就不该每次手写重复。AGENTS.md 正是为此而生。

你可以把 AGENTS.md 当成面向智能体的开放格式 README：它会自动进上下文，是沉淀团队协作方式的最佳位置。

一个好的 AGENTS.md 通常包括：

• 仓库结构与关键目录
• 项目运行方式
• 构建、测试、Lint 命令
• 工程规范与 PR 要求
• 约束与禁忌规则
• “完成”的定义与验证方法

CLI 的 /init 可快速生成初版 AGENTS.md，但必须按团队真实工作流改写。

AGENTS.md 可以分层：

• 全局默认：~/.codex/AGENTS.md
• 仓库级规范：仓库根目录
• 子目录局部规则：越靠近当前目录优先级越高

保持务实：短而准确，胜过冗长空泛。先写基础规则，等出现重复问题再增补。如果文件过大，可保留主文件精简，把规划、评审、架构等细则拆到专题文档。

一个高效习惯是：当 Codex 连续两次犯同类错误，让它做复盘，并把结论写回 AGENTS.md。

4）通过配置获得一致性

配置是让 Codex 跨会话、跨终端稳定表现的关键。你可以统一模型、推理级别、沙箱模式、审批策略、Profiles 与 MCP 设置。

推荐起步模式：

• 个人默认放在 ~/.codex/config.toml
• 仓库特定行为放在 .codex/config.toml
• 命令行覆盖只用于一次性场景

config.toml 可定义 MCP 服务、profiles、多智能体、特性开关等持久偏好。

Codex 还有两类关键安全旋钮：

• Approval mode：何时请求你同意执行命令
• Sandbox mode：可读写范围与可访问文件权限

如果你是新手，建议先保持默认、偏收敛的权限，再对可信仓库按需放宽。

很多“质量问题”本质是“环境问题”：工作目录不对、写权限缺失、默认模型不匹配、工具/连接器未配置。

5）用测试与评审提升可靠性

不要停在“让 Codex 改代码”这一步。应让它一并：必要时补测试、跑检查、确认结果、做审查。

前提是 Codex 知道“什么算好”，而这可以来自提示词，也可以来自 AGENTS.md。

可包含的检查闭环：

• 编写/更新测试
• 运行正确测试集
• 检查 lint / format / type
• 核对最终行为是否符合需求
• 审查 diff 中的 bug、回归与风险模式

在 Codex App 里可直接打开 diff 面板做本地审阅；/review 还支持：

• 基于目标分支做 PR 风格审查
• 审查未提交改动
• 审查某次提交
• 使用自定义审查指令

若团队有 code_review.md 并在 AGENTS.md 中引用，Codex 也可按该规则执行评审。

另外，GitHub Cloud 场景可让 Codex 对 PR 自动审查。在 OpenAI 内部，Codex 会审查 100% PR；你也可选择自动审查或 @Codex 触发审查。

6）用 MCP 接入仓库外上下文

当关键上下文不在仓库里，就该用 MCP。这样 Codex 可以直接连接你已有工具和系统，不必反复复制粘贴实时数据。

MCP（Model Context Protocol）是连接外部工具/系统的开放标准。

适合使用 MCP 的场景：

• 所需上下文在仓库外
• 数据变化频繁
• 希望 Codex 直接调用工具而非只看粘贴文本
• 需要跨用户/项目的可复用集成

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

建议先接一两个真正能消除手工回路的工具，不要一开始把所有工具都接上。

7）把可复用流程沉淀为 Skills

当流程已经重复出现，不要再依赖超长提示词或来回对话。应把方法封装成 Skill：以 SKILL.md + 上下文 + 支撑逻辑的形式稳定复用。

实践建议：

• 一个 Skill 只做一件事
• 先从 2～3 个明确场景切入
• 明确输入与输出
• 描述写清“做什么、何时用”
• 加上用户真实会说的触发语

无需一开始覆盖所有边界；先打通一个代表任务，再迭代。

一个经验法则：如果你反复复用同一提示词，或反复纠正同一流程，它就该升级成 Skill。

常见高价值 Skill 场景：

• 日志分诊
• Release Notes 草拟
• 按清单做 PR 审查
• 迁移规划
• 遥测/事故总结
• 标准化调试流程

个人 Skills 通常放在 $HOME/.agents/skills，团队共享 Skills 可纳入仓库 .agents/skills，有助于新成员快速上手。

8）把稳定流程交给自动化

当工作流稳定后，可调度 Codex 在后台按节奏运行。

在 Codex App 中，Automations 可配置：

• 运行项目
• 执行提示词（可调用 skills）
• 执行频率
• 执行环境（专用 git worktree 或本地环境）

典型候选：

• 汇总近期提交
• 扫描潜在 bug
• 草拟发布说明
• 检查 CI 失败
• 生成 standup 摘要
• 定期执行重复分析

一句话：Skill 定义方法，Automation 定义节奏。若流程仍需大量人工引导，先打磨 Skill；稳定后再自动化，收益更大。

9）用会话控制管理长周期任务

Codex 会话不只是聊天记录，而是持续积累上下文、决策与动作的“工作线程”。管理方式会直接影响质量。

在 Codex App 中可 pin 线程并创建 worktree；CLI 下常用命令包括：

• /experimental：切换实验功能并写入 config.toml
• /resume：恢复历史会话
• /fork：分叉新线程并保留原轨迹
• /compact：长会话摘要压缩（系统也会自动压缩）
• /agent：多智能体并行时切换活动线程
• /theme：设置语法高亮主题
• /apps：直接在 Codex 中用 ChatGPT apps
• /status：查看当前会话状态

建议“一任务一线程”。同一问题域内持续在原线程通常更好，因为能保留完整推理轨迹；只有真正分支时才 fork。

也可用 subagent 将边界清晰的子任务（探索、测试、分诊）从主线程卸载。

10）新手常见误区

• 把长期规则都塞进提示词，而不是迁移到 AGENTS.md 或 Skill
• 没告诉智能体如何运行构建与测试，导致它“看不见”自己的结果
• 多步骤复杂任务跳过规划
• 还没摸清工作流就给智能体过高系统权限
• 多条在线线程同时改同一文件，却不使用 git worktree
• 流程尚不稳定就过早自动化
• 把 Codex 当“必须全程盯着”的工具，而非并行协作伙伴
• 一个项目只用一个线程，最终上下文臃肿、结果下降