最佳实践

如果你刚开始接触 Codex 或编程助手，本指南将帮你更快地获得更好的结果。涵盖从提示和规划到验证、MCP、Skill 和自动化等核心习惯。

将 Codex 视为一个你可以配置和持续改进的队友，而不是一次性助手。

提供好的上下文和提示

即使提示不完美，Codex 也足够强大。清晰的提示可以让结果更可靠，尤其是在大型代码库或高难度任务中。

一个好的提示应包含四个要素：

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

根据任务难度选择推理级别：

• 低：适用于快速、范围明确的任务
• 中/高：适用于更复杂的变更或调试
• 极高：适用于长期、自主性高、推理密集的任务

困难任务先规划

如果任务复杂、模糊或难以描述，让 Codex 先制定计划：

• 使用 Plan 模式：使用 /plan 或 Shift+Tab 切换。让 Codex 收集上下文、提出澄清问题并制定计划
• 让 Codex 先提问：如果你对需求还不清晰，让 Codex 先挑战你的假设
• 使用 PLANS.md 模板：为长期或多步骤工作配置执行计划模板

用 AGENTS.md 复用指导

一旦提示模式有效，下一步是停止重复手动输入。AGENTS.md 是存放持久化指导的最佳位置。

好的 AGENTS.md 涵盖：仓库布局、如何运行项目、构建/测试/lint 命令、工程约定、约束和禁止规则。

在 CLI 中使用 /init 命令可快速生成初始 AGENTS.md。

配置 Codex 以保持一致性

通过配置让 Codex 在会话和不同使用方式间保持行为一致。可以在 config.toml 中设置模型选择、推理力度、沙箱模式、审批策略等默认值。

• 个人默认值存于 ~/.codex/config.toml
• 仓库特定配置存于 .codex/config.toml
• 一次性场景使用命令行覆盖

用测试和审查提高可靠性

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

使用 /review 斜杠命令可以审查代码：

• 基于基准分支进行 PR 式审查
• 审查未提交的更改
• 审查某次提交
• 使用自定义审查指令

使用 MCP 获取外部上下文

当 Codex 需要的上下文存在于仓库之外时，使用 MCP（Model Context Protocol）连接你已经在使用的工具和系统。

将重复性工作转为 Skill

当工作流变得可重复时，将其打包为一个 Skill，包含 SKILL.md 文件中的指令、上下文和支持逻辑。Skill 在 CLI、IDE 扩展和桌面应用中均可使用。

用自动化的处理重复任务

一旦工作流稳定，你可以在桌面应用中使用自动化的让它按计划在后台运行。

常见错误

• 在提示中包含持久性规则而不是移到 AGENTS.md 或 Skill 中
• 在没有给出如何运行构建和测试命令的细节的情况下让 Agent 工作
• 在多步骤和复杂任务上跳过规划
• 在理解工作流之前给 Codex 完全权限
• 不使用 Git worktree 而在同一文件上运行多个活跃线程
• 在工作流手动操作足够可靠之前就将其转为自动化的
• 一个项目只用一个线程而不是一个任务一个线程