AI 编程助手用到飞起：OpenAI Codex 官方最佳实践完全指南

一句话总结

别把 AI 编程助手当一次性工具用，要当长期队友来培养——教它你的习惯，让它越用越顺手。

第一步：给好指令，一次说清楚

AI 编程助手已经很强了，随便丢个问题也能出结果。但要稳定出好结果，特别是在大项目里，你的指令需要包含四样东西：

实操建议：不用每次都写这么全。简单任务一句话就够，复杂任务才需要四要素齐全。

另外，根据任务难度调整 AI 的"思考深度"：

• 简单任务（改个文案、加个字段）：用低推理模式��快
• 复杂任务（调 Bug、重构）：用中高推理模式
• 超复杂任务（跨文件重构、设计架构）：用最高推理模式

第二步：复杂任务先规划，别急着写代码

遇到不好描述、有多个步骤、或者你自己也没完全想清楚的任务，先让 AI 出方案，别直接让它动手。

三种好用的做法：

方法 1：用规划模式

大多数 AI 编程工具都有"规划模式"（Codex 用 /plan，Claude Code 用 Plan mode）。开启后 AI 会先了解情况、提问澄清、再出方案，而不是直接写代码。

方法 2：让 AI 反问你

如果你有个模糊的想法但说不清楚，直接跟 AI 说：

"我想做 XXX，但还没想清楚。你先问我几个问题，帮我把需求理清楚，再动手。"

方法 3：写一个计划模板

对于经常做的复杂任务（比如版本发布、大型重构），可以写一个 PLANS.md 模板，让 AI 每次按这个模板来拆解步骤。

第三步：把好用的指令"固化"下来

同一句话说了两次，就该写进配置文件。

Codex 用 AGENTS.md，Claude Code 用 CLAUDE.md，道理一样——把你对 AI 的要求写成一个文件，每次会话自动加载，不用反复交代。

一个好的指导文件应该包含：

# 项目结构
- src/ 是主代码目录
- tests/ 是测试目录

# 怎么跑项目
npm install && npm run dev

# 测试和检查命令
npm test
npm run lint

# 代码规范
- 用 TypeScript，不用 any
- 组件用函数式写法
- 提交信息用中文

# 禁止事项
- 不要改 package.json 的依赖版本
- 不要删除现有的测试用例

# 什么算"做完了"
- 测试全部通过
- 没有 lint 错误
- 相关的测试已更新

关键原则：

• 短而准 > 长而泛。10 条精确规则比 50 条模糊规则有用
• 先写基础的，等 AI 犯了错再补新规则
• AI 同一个错误犯了两次？让它做个复盘，把教训写进指导文件

第四步：统一配置，每次都一样

通过配置文件设定默认行为，而不是每次都在对话里交代：

• 个人配置（你自己的偏好）：放在 ~/.codex/config.toml 或 ~/.claude/CLAUDE.md
• 项目配置（团队共享的规范）：放在项目目录的 .codex/config.toml 或 .claude/CLAUDE.md

能配置的东西很多：模型选择、推理深度、权限策略、工具连接等。

新手建议：刚开始用的时候，权限收紧（默认要求确认），等你熟悉 AI 的行为模式后，再逐步放开权限。

很多时候你觉得"AI 不好用"，其实是配置没搞对——工作目录错了、写入权限没开、模型没选对、工具没连上。先检查环境配置，再怀疑 AI 能力。

第五步：让 AI 测试自己的工作

不要只让 AI 改代码，要让它自己验证改得对不对。

一个完整的流程应该是：

写代码 → 写测试 → 跑测试 → 检查格式 → 确认行为 → 自审代码

怎么做到？在你的指导文件里写清楚：

# 完成任务后的检查清单
1. 运行 npm test 确保测试通过
2. 运行 npm run lint 确保没有格式问题
3. 检查改动是否引入了新的安全风险
4. 确认改动符合最初的需求

还可以用 /review 命令让 AI 专门做代码审查：

• 对比分支差异（像 PR 审查一样）
• 审查未提交的修改
• 按照自定义的审查标准检查

第六步：用 MCP 连接外部工具

当 AI 需要的信息不在代码仓库里时（比如在 Jira、Notion、数据库、API 文档里），用 MCP（Model Context Protocol）把这些工具连上来。

适合用 MCP 的场景：

• 需要的信息在代码之外（Issue 跟踪、文档平台）
• 数据经常变化（线上日志、监控数据）
• 你经常要手动复制粘贴某些信息给 AI

实操建议：不要一上来就把所有工具都接上。先接 1-2 个你最常手动复制粘贴的工具，有用了再加。

第七步：重复的工作做成"技能"

当一个工作流你已经用了好几次，每次都要交代同样的话，是时候把它变成技能了。

技能就是一个 SKILL.md 文件，把指令、上下文、执行逻辑打包在一起，以后一句话触发。

做技能的原则：

• 一个技能只做一件事
• 写清楚什么时候该用这个技能（触发条件）
• 定义明确的输入和输出
• 先从 2-3 个典型场景开始，不要试图覆盖所有边界情况

适合做成技能的工作：

• 日志排查
• 写发布说明
• 按清单做代码审查
• 迁移方案规划
• 故障分析报告
• 标准化的调试流程

判断标准：如果你发现自己在反复用同一个提示词，或者反复纠正 AI 的同一个行为——它就该变成技能了。

第八步：稳定的任务设成自动化

当一个技能已经跑得很稳，不需要你盯着，就可以设成定时自动执行。

适合自动化的任务：

• 每天总结最近的代码提交
• 定期扫描可能的 Bug
• 自动起草发布说明
• 检查 CI 构建失败
• 生成每日站会摘要

关键原则：技能定义"怎么做"，自动化定义"什么时候做"。

⚠️ 重要：一个工作流如果手动执行都还不稳定，就不要自动化。先当技能用稳了，再上自动化。

第九步：管好你的会话

AI 的会话不只是聊天记录，它是一个积累了上下文和决策的工作线程。管好它对输出质量影响很大。

几个实用的命令

命令作用什么时候用/resume恢复之前保存的会话第二天继续昨天的工作/fork从当前会话分出一个新线程想试另一个方案但不想丢掉现在的进度/compact压缩过长的会话对话太长、AI 开始"忘事"/agent切换子 Agent让子 Agent 做探索、测试、排查等独立任务

核心原则

• 一个会话做一件事。不要把整个项目塞在一个会话里
• 如果工作还在同一个问题上，继续用同一个会话（保留推理过程）
• 真正分支了再 fork，不要随便开新会话
• 用子 Agent分担独立的小任务，让主线程专注核心问题

常见错误清单

学会避开这些坑，你就超过了 90% 的 AI 编程工具用户：

❌ 错误做法✅ 正确做法每次都在对话里重复相同的规则写进 AGENTS.md / CLAUDE.md不告诉 AI 怎么跑测试和构建在指导文件里写清楚命令复杂任务直接让 AI 开干先规划、先讨论、再动手一上来就给 AI 所有权限先收紧，熟悉后再逐步放开多个任务改同一批文件，不做隔离用 git worktree 隔离手动跑都不稳的流程就自动化先手动跑稳再自动化全程盯着 AI 每一步操作当队友用——分配任务，并行工作一个超长会话干所有事一个会话一个任务，避免上下文膨胀

总结：从工具到队友的进化路径

第 1 阶段：直接提问，拿到结果
    ↓
第 2 阶段：学会给好指令（四要素）
    ↓
第 3 阶段：写指导文件，不再重复交代
    ↓
第 4 阶段：做成技能，一句话触发
    ↓
第 5 阶段：设成自动化，完全不用管

每一步都在减少你的重复劳动，增加 AI 的可靠性。不是 AI 变聪明了，是你教会了它你的工作方式。

---

附录：原文全文翻译

原文地址：https://developers.openai.com/codex/learn/best-practices

最佳实践

Codex 入门指南与经过验证的高效用法

Codex 用得最好的方式，不是把它当一次性助手，而是把它当成一个你可以持续配置和改进的队友。

一个有用的思考框架是：从正确的任务上下文开始，用 AGENTS.md 固化持久指导，配置 Codex 以匹配你的工作流，用 MCP 连接外部系统，把重复工作变成技能，并将稳定的工作流自动化。

良好的首次使用：上下文与提示词

Codex 已经足够强大，即使你的提示词不够完美也能派上用场。你经常可以用最少的准备就给它一个难题，仍然能得到不错的结果。清晰的提示词不是获取价值的必要条件，但确实能让结果更可靠，尤其是在大型代码库或高风险任务中。

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

一个好的默认做法是在提示词中包含四样东西：

• 目标：你想改变或构建什么？
• 上下文：哪些文件、文件夹、文档、示例或错误信息与这个任务相关？你可以用 @ 提及特定文件作为上下文。
• 约束：Codex 应该遵循哪些标准、架构要求、安全规范或惯例？
• 完成标准：任务完成前应该满足什么条件，比如测试通过、行为发生变化、或 Bug 不再复现？

这有助于 Codex 保持专注、减少假设，并产出更容易审查的工作成果。

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

• 低：适用于更快速、范围明确的任务
• 中或高：适用于更复杂的修改或调试
• 超高：适用于长时间、需要代理推理的重型任务

💡 为了更快地提供上下文，可以尝试在 Codex 应用内使用语音听写来口述你想让 Codex 做的事情，而不是打字。

复杂任务先规划

如果任务是复杂的、模糊的或难以描述的，先让 Codex 做规划再开始写代码。

几种好用的方法：

使用规划模式：对大多数用户来说，这是最简单也最有效的选择。规划模式让 Codex 先收集上下文、提出澄清问题、构建更完善的方案，然后再实施。用 /plan 或 Shift+Tab 切换。

让 Codex 采访你：如果你对想要什么有个大概想法但不确定怎么描述，让 Codex 先问你问题。告诉它质疑你的假设，把模糊的想法变成具体的东西，然后再写代码。

使用 PLANS.md 模板：对于更高级的工作流，你可以配置 Codex 遵循一个 PLANS.md 或执行计划模板，用于较长时间运行或多步骤的工作。更多细节请参阅执行计划指南。

用 AGENTS.md 让指导可复用

一旦某个提示词模式有效了，下一步就是停止手动重复它。这就是 AGENTS.md 的用武之地。

把 AGENTS.md 想象成一个开放格式的 README，专门给 AI 代理看。它会自动加载到上下文中，是编码你和团队希望 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 应用共享相同的配置层。更多信息请参阅示例配置页面。

💡 尽早为你的真实环境配置 Codex。许多质量问题其实是配置问题，比如工作目录错了、缺少写入权限、模型默认值不对、或工具和连接器缺失。

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

不要止步于让 Codex 做修改。让它在需要时创建测试、运行相关检查、确认结果，并在你接受之前审查工作。

Codex 可以为你完成这个循环，但前提是它知道什么是"好的"。这些指导可以来自提示词或 AGENTS.md。

这可以包括：

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

💡 在 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 连接到你已经在使用的工具和系统，这样你就不必不断将实时信息复制粘贴到提示词中。

MCP，即模型上下文协议（Model Context Protocol），是一个将 Codex 连接到外部工具和系统的开放标准。

在以下情况使用 MCP：

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

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

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

💡 只在工具真正解锁了某个工作流时才添加。不要一开始就把你使用的每个工具都接上。从一两个明显能消除你经常手动重复的循环的工具开始，然后从那里扩展。

将重复工作变成技能

一旦某个工作流变得可重复，就不要再依赖长提示词或反复的来回沟通了。使用技能（Skill）将指令打包到 SKILL.md 文件中，包括上下文和 Codex 应该一致应用的支持逻辑。技能在 CLI、IDE 扩展和 Codex 应用中都能工作。

保持每个技能专注于一项工作。从 2 到 3 个具体用例开始，定义清晰的输入和输出，编写描述使其说明技能做什么以及何时使用。包含用户实际会说的那种触发短语。

不要试图一开始就覆盖每个边缘情况。从一个代表性任务开始，把它做好，然后将该工作流转化为技能并持续改进。只有当脚本或额外资源能提高可靠性时才加入它们。

一个好的经验法则：如果你一直在重复使用同一个提示词，或一直在纠正同一个工作流，它可能应该变成一个技能。

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

• 日志分类排查
• 发布说明起草
• 按检查清单做 PR 审查
• 迁移规划
• 遥测或事故总结
• 标准调试流程

$skill-creator 技能是搭建技能初版的最佳起点，$skill-installer 技能用于本地安装。技能最重要的部分之一是描述，它应该说明技能做什么以及何时使用。

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

用自动化处理重复工作

一旦某个工作流稳定了，你可以安排 Codex 在后台自动运行它。在 Codex 应用中，自动化让你选择项目、提示词、运行频率和执行环境来设置重复任务。

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

好的候选任务包括：

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

一个有用的规则是：技能定义方法，自动化定义时间表。如果一个工作流仍然需要大量人工干预，先把它变成技能。一旦它变得可预测，自动化就成为力量倍增器。

💡 用自动化做反思和维护，而不仅仅是执行。审查最近的会话，总结反复出现的摩擦，并随时间改进提示词、指导或工作流设置。

用会话控制组织长期工作

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

Codex 应用的 UI 使线程管理最为便捷，因为你可以固定线程和创建 worktree。如果你使用 CLI，以下斜杠命令特别有用：

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

保持每个线程对应一个连贯的工作单元。如果工作仍然是同一个问题的一部分，留在同一个线程中通常更好，因为它保留了推理脉络。只有当工作真正分支时才分叉。

💡 使用 Codex 的多代理工作流将有界的工作从主线程中分离出去。让主代理专注于核心问题，使用子代理处理探索、测试或分类排查等任务。

常见错误

刚开始使用 Codex 时需要避免的几个常见错误：

• 把持久规则全部塞进提示词里，而不是移到 AGENTS.md 或技能中
• 没有让代理看到自己的工作成果——不告诉它如何运行构建和测试命令的详细信息
• 在多步骤和复杂任务上跳过规划
• 在你了解工作流之前就给 Codex 对你电脑的完全权限
• 在同一批文件上运行多个活跃线程而不使用 git worktree
• 在一个重复任务手动运行都还不可靠的时候就把它变成自动化
• 把 Codex 当成需要你一步一步盯着看的东西，而不是与你自己的工作并行使用
• 每个项目只用一个线程，而不是每个任务一个线程。这会导致上下文膨胀，结果随时间变差