Codex Best Practices

zyz 收录于 AI Engineering 开发工具

2026-04-05 约 400 字预计阅读 2 分钟

核心思想为：

为每次任务提供正确的上下文
将复杂任务进行拆解
将持久的指导写入AGENTS.md
将重复工作转换为siklls
使用MCP与外部系统连接
自动化稳定的流程

Context and prompts

一个好的prompt应该包括以下4点：

Goal: 你想要修改或建立什么？
Context: 哪些文件、文件夹、文档、示例或错误对这项任务有帮助？推荐通过@这些文件来提供上下文。
Constraints: 本次任务应遵循哪些标准、架构、安全要求或惯例？
Done when: 本次任务完成的标准。比如测试通过、行为改变，或者某个漏洞被修复。

此外，注意选择合适的推理能力：

低：适用于范围明确且要求快速响应的任务
中和高： 适用于复杂的任务
超高： 适用于长时间、复杂、推理繁重的任务

Plan first for difficult tasks

对于复杂、模糊的任务，应该在进行编码前先做plan

可以采用以下方式来制作plan：

使用计划模式： 输入 /plan 或按下 shift + tab 即可切换为 plan 模式。（这是最简单有效的方式，强力推荐）
让Codex主动询问： 让codex主动对任务不清楚，描述模糊的地方对你进行提问，把你模糊的想法变成具体的东西，然后才开始写代码
使用 PLANS.md： 对于特别特别复杂的任务，可以按照官方提供的模板编写 PLANS.md

Make guidance reusable with `AGENTS.md`

AGENTS.md 就是面向 agents 的 README，它可以让我们不用重复写相同的提示，让anget行为更稳定。Codex每次执行任务前会自动读取该文件，作为系统级指导。

一个好的 AGENTS.md 应该包括以下内容：

仓库结构和重要目录
构建、测试、运行命令
代码规范（使用什么标准，函数和变量命名规则等）
工作流程（如何提交PR，commit规范，review要求）
特殊注意事项

刚开始的 AGENTS.md 应该简洁准确，然后再慢慢将 agent 反复犯的错制作为规则添加进去。需要注意的是 AGENTS.md 中的规则尽量不要超过 20 条（规则越多，规则之间发生冲突的可能性旧越大，且浪费tokens）。此外，写入的每条规则应该 简洁准确 （明确路径，明确命令，明确术语）且是长期需要遵守的。

一定要记住 AGENTS.md 是 执行约束，不是详细文档！！！

The “hierarchical system” of AGENTS.md

Codex 会按层级逐层发现并加载 AGENTS.md，加载顺序为：全局层（~/.codex/AGENTS.md）➜ 项目根目录（repo/AGENTS.md）➜ 子目录（路径上所有 AGENTS.md）➜ 当前文件所在目录的 AGENTS.md（最近）

这些 AGENTS.md 中的规则是叠加的！！！所以，不要编写互斥的规则！！！当存在互斥规则时，最底层的规则优先级大（即离文件所在目录越近的AGENTS.md中的规则优先级越大, 但是 prompt中的约束是最大的）。

一个核心原则就是：

越上层越通用，越下层越具体，每层只写该层能决定的事情

Turn repeatable work into Skills

官方推荐：当一个任务满足以下3个条件时就应该抽象成 Skill：

可重复
有固定步骤
可以标准化输入输出

SKILL目录的命名应该简短明确，单词之间用-连接，比如：code-review, benchmark-analysis等。SKILL.md应该放在.agents/skills/下（这样codex就能自动发现了），比如：

1
2
3
4
.agents/
└── skills/
    ├── code-review/
    └── benchmark-analysis/

每个SKILL目录的具体结构为：

1
2
3
4
5
skills/<skill-name>/
├── SKILL.md        # 必须
├── scripts/        # 可选（脚本）
├── references/     # 可选（文档）
└── examples/       # 可选（示例）

SKILL.md推荐结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
---
name: <skill-name>
description: <What this skill does and when to use it.>
---

# When to use

Use this skill when:
- <condition 1>
- <condition 2>

# Inputs

Required inputs:
- <input 1>
- <input 2>

# Steps

1. Understand the request.
2. Inspect the relevant context.
3. Perform the task.
4. Validate the result.
5. Summarize clearly.

# Output format

- Summary:
- Details:
- Validation:
- Risks / Notes:

# Constraints

- Stay within scope.
- Follow project rules.
- State assumptions clearly.

调用skill有两种方式：

显示调用： 在 prompt 中指定（使用 skill: code-review）
隐式调用： Codex 会根据任务描述和Skill 描述自动选择合适的 Skill（该方式更常见）

需要记住的是：一个 Skill 只做一件事 ！！！

Configure Codex for consistency

在实际开发中，Codex 最大的问题往往不是能力，而是结果不稳定：

同样的任务，不同结果
同一项目，不同行为
不同环境，输出差异很大

官方给出的确保一致性的核心思路是：

“固定环境 + 固定规则 + 固定流程”

AGENTS.md 用于固定规则，SKILL.md 用于固定流程，config.toml 用于固定环境。

config.toml控制：

使用哪个模型
推理强度
是否允许执行命令
是否需要用户确认
sandbox 权限范围

config.toml的具体样例，可以参考官方模板。此外，Codex也支持分层配置：

1
2
3
~/.codex/config.toml        ← 全局默认
repo/.codex/config.toml     ← 项目配置
CLI 参数                    ← 临时覆盖

优先级：

1
CLI > 项目配置 > 全局配置

总结

以上内容只是Codex最佳实践的部分内容，由于我对其他内容（MCP，automations）目前还没有使用的需求，就不在文章中写了，有需要者可以自行查阅官方文档。