Appearance
Codex 最有价值的用法不是"一次性问答助手"，而是一个你持续配置、持续改进的编程搭档。本文从 8 个维度讲如何让 Codex 在大型代码库里持续产出高质量结果：写好 Prompt 四要素、用 AGENTS.md 沉淀规则、统一配置、加测试验证、用 MCP 接入外部系统、把重复流程变成 Skills、自动化稳定任务、高效管理会话。
OpenAI Codex 最佳实践
Codex 和其他 AI 工具最大的区别：它值得你去配置、去持续改进，而不是只用来做一次性问答。
把它当成队友：先给对的上下文，用 AGENTS.md 写下持久规则，用 Skills 打包重复流程，用自动化跑稳定任务。
一、好 Prompt 的四要素
Codex 足够强，模糊的 Prompt 也能给出不错的结果。但清晰的指令能让结果更可靠——尤其是在大型代码库或高风险任务里。
在 Prompt 里包含这四样东西：
- 目标（Goal）：你要做什么改动或构建什么？
- 上下文（Context）：哪些文件、目录、文档、报错信息与这个任务有关？可以用
@引用文件 - 约束（Constraints）：有什么规范、架构、安全要求或约定 Codex 必须遵守？
- 完成标准（Done when）：什么状态算完成？测试通过？行为改变？Bug 不再复现？
这四要素帮 Codex 锁定范围、少做假设、产出更容易 review 的代码。
选对推理强度：
- 低（Low）：快速、范围明确的任务
- 中/高（Medium/High）：复杂改动或调试
- 超高（Extra High）：长时间运行的、推理密集的 agent 任务
试试在 Codex App 里用语音输入指令，比手打快很多。
二、复杂任务先规划
任务复杂、模糊或难以描述时，让 Codex 先规划，再动手写代码。
三种规划方式：
Plan 模式：大多数人最简单的选择。Codex 先收集上下文、问清楚问题、做好计划再动手。在 Codex CLI 里用 /plan 或 Shift+Tab 切换。
让 Codex 先问你：如果你有个大概想法但说不清楚，让 Codex 先质疑你的假设，把模糊想法变成可操作的需求：
text
在写任何代码之前，先问我足够多的问题，让你能完全理解我的需求。帮我把这个模糊的想法变得具体。用 PLANS.md 模板：对于多步骤的长期工作，配置 Codex 遵循 PLANS.md 执行计划模板。
三、把有效的规则沉淀到 AGENTS.md
一个 Prompt 模式有效之后，下一步是把它固化——不要反复手动输入。这就是 AGENTS.md 的价值。
把 AGENTS.md 当成一个面向 AI 的 README：它自动加载到上下文，是告诉 Codex 你和团队希望怎么工作的最佳位置。
一个好的 AGENTS.md 应该包含：
- 仓库目录结构和关键目录
- 如何启动项目
- 构建、测试、lint 命令
- 工程规范和 PR 要求
- 约束和禁止事项
- "完成"意味着什么，如何验证工作
用 CLI 的 /init 命令可以快速生成一个起点 AGENTS.md，然后手动编辑成你们团队真实的工作方式。
分层管理：
~/.codex/AGENTS.md：个人全局默认值- 仓库根目录
AGENTS.md：团队共享规范 - 子目录
AGENTS.md：局部专项规则（靠近工作目录的文件优先级更高）
保持简洁：简短准确的 AGENTS.md 比冗长的规则文件更有效。遇到问题先加规则，不要预先猜测所有可能情况。
当 Codex 犯了同样的错误两次，让它做一次复盘并更新 AGENTS.md。基于真实摩擦更新规则，保持实用性。
四、统一 Codex 配置
配置是让 Codex 在不同会话和接入方式里保持一致行为的关键。可以配置的内容包括：模型选择、推理强度、沙箱模式、审批策略、Profiles 和 MCP 设置。
推荐的配置分层：
- 个人默认值放
~/.codex/config.toml（或在 Codex App 里进 Settings → Configuration → Open config.toml） - 仓库专属行为放
.codex/config.toml - 只用命令行参数覆盖一次性情况
沙箱和审批权限：Codex 内置沙箱机制，有两个核心控制点：
- 审批模式（Approval mode）：Codex 什么时候需要你批准才能运行命令
- 沙箱模式（Sandbox mode）：Codex 能读写哪些文件和目录
如果你刚开始用 coding agent，从默认权限开始。了解清楚工作流之后，再针对可信仓库或特定工作流适当放开权限。
早点把 Codex 配置到你的真实环境。很多质量问题其实是配置问题：工作目录错了、写入权限不够、模型默认值不对、工具或连接器缺失。
五、用测试和 Review 提升可靠性
不要只让 Codex 做改动，要让它同时写测试、跑检查、确认结果、review 改动。
Codex 能帮你完成这整个循环，但前提是它知道"好"是什么样。这个标准可以来自 Prompt 或 AGENTS.md。
可以要求 Codex：
- 为改动写或更新测试
- 跑对应的测试套件
- 检查 lint、格式化或类型检查
- 确认最终行为符合需求
- 检查 diff 中的 Bug、退化或风险模式
用 /review 命令做代码审查：
text
/review # 审查未提交改动
/review Focus on edge cases and security issues # 自定义关注点支持多种模式：
- 对比基础分支做 PR 风格的 review
- 审查未提交改动
- 审查某个 commit
- 自定义 review 指令
如果你用 GitHub Cloud，可以配置 Codex 自动为 PR 做 code review，或者在 PR 里 @codex 触发审查。
六、用 MCP 接入外部系统
当 Codex 需要的上下文在代码仓库之外时，用 MCP 接入。
适合用 MCP 的情况：
- 需要的数据在仓库外（issue tracker、设计工具、文档系统）
- 数据频繁变化，不适合手动复制粘贴
- 需要 Codex 直接调用工具，而不是依赖粘贴的指令
- 需要在多个用户或项目之间复用同一个集成
在 Codex App 里：Settings → MCP servers，可以看到内置推荐的服务端，也可以直接让 Codex 帮你安装。CLI 里用 codex mcp add 命令添加自定义服务端。
只在 MCP 能真正解锁某个工作流时才加。不要一开始就接入所有工具。先选 1~2 个能明显减少手动操作的工具，再逐步扩展。
七、把重复工作变成 Skills
一旦某个工作流可以重复，停止依赖长 Prompt 或反复来回沟通。用 Skill 把指令、上下文和辅助逻辑打包成 SKILL.md 文件。
什么时候该做成 Skill：
- 日志分类
- Release notes 起草
- 按 checklist 做 PR review
- 迁移规划
- 遥测或故障摘要
- 标准化调试流程
从 $skill-creator 开始，用内置的 skill 创建工具生成第一个版本。先在本地迭代，稳定后再打包成 Plugin 分享给更多人。
每个 Skill 只做一件事。从 2~3 个具体用例出发，定义清晰的输入输出，写好 description（说明 Skill 做什么、什么时候触发）。
个人 Skills 放在 $HOME/.agents/skills，团队 Skills 签入到仓库的 .agents/skills，非常适合新成员入职使用。
八、自动化稳定的工作流
工作流稳定之后，可以安排 Codex 在后台定期跑。在 Codex App 的 Automations 标签里，选择项目、Prompt（可以调用 Skills）和执行频率。
适合自动化的任务：
- 汇总最近的 commits
- 扫描潜在 Bug
- 起草 Release notes
- 检查 CI 失败
- 生成 standup 摘要
- 定期运行分析工作流
原则：Skills 定义方法，Automations 定义节奏。一个工作流还需要大量引导时，先做成 Skill；可预测了，再自动化。
用自动化做反思和维护，而不只是执行。定期回顾会话、汇总重复的摩擦点，持续改进 Prompt、指令或工作流配置。
九、管理长期工作会话
Codex 会话不只是聊天记录，它是积累了上下文、决策和行动的工作线程。管理好会话对输出质量影响很大。
常用的 CLI slash 命令：
| 命令 | 作用 |
|---|---|
/plan | 切换 Plan 模式 |
/resume | 恢复已保存的会话 |
/fork | 新建线程，保留原始记录 |
/compact | 压缩上下文（Codex 也会自动做） |
/agent | 在多个并行 agent 线程之间切换 |
/review | 代码审查 |
/status | 检查当前会话状态 |
每个工作单元开一个线程。同一个问题的延续就在同一个线程里聊，保留完整推理链。只在工作真正分叉时才 fork 新线程。
用 Subagents 把有边界的工作从主线程剥离出去：让主 agent 专注于核心问题，把探索、测试、分类等工作交给子代理。
常见错误
- 把持久化规则堆在 Prompt 里，而不是移到
AGENTS.md或 Skill - 不告诉 agent 怎么跑构建和测试命令，让它看不到自己的工作效果
- 多步骤复杂任务跳过规划
- 在理解工作流之前就给了 Codex 太多权限
- 在同一批文件上同时跑多个线程，没用 git worktrees 隔离
- 工作流还不稳定就设置自动化
- 把 Codex 当成需要盯着看的工具，而不是并行工作的队友
- 一个项目只开一个线程，导致上下文越来越臃肿、质量越来越差
常见问题
Q: AGENTS.md 写多长合适？
A: 越短越好，以能准确描述项目规范为准。太长的 AGENTS.md 会占用更多上下文窗口，并且规则越多 Codex 越容易混淆。从基础开始（构建/测试命令、核心约定），遇到反复出现的问题再添加对应规则。
Q: MCP 和 Skills 都能做外部集成，应该用哪个？
A: 两者互补：MCP 负责实时连接和调用外部系统（拉取 Linear issue、查 Figma 设计）；Skills 负责封装工作流程（定义一套 PR review 的步骤）。通常是 Skill 定义流程，在流程里调用 MCP 工具。
Q: 自动化任务失败了怎么办？
A: 先把工作流做成稳定的 Skill 手动验证，确认可预测之后再自动化。自动化任务出问题通常说明这个工作流还需要更多引导，还没到自动化的时机。