AGENTS.md 模板：让 Codex 按项目规矩干活

声明：依据 OpenAI 公开的 AGENTS.md / 配置说明整理，非官方译本。字段与行为以 Custom instructions with AGENTS.md 为准。

更新核验：2026.09

栏目概览仍见：写好 AGENTS.md。

它是干什么的

Codex 在动手前会读取 AGENTS.md（及相关覆盖文件），把项目约定塞进当次任务的上下文。写好它，等于给每次协作固定「怎么验收、什么不能碰、测什么」。

AGENTS.md 模板：让 Codex 按项目规矩干活的入口、目标与准备条件操作示意图 — 图 1 · 进入任务前先确认目标、范围和准备条件

发现顺序

全局：~/.codex/AGENTS.override.md（若有）否则 ~/.codex/AGENTS.md
项目：从仓库根走到当前目录；每一层最多用一个文件（优先 AGENTS.override.md，再 AGENTS.md，再 fallback 名）
合并：从上到下拼接；离当前目录越近，越后出现、越优先

默认合计大约 32 KiB（project_doc_max_bytes）；太大就拆到子目录或提高上限。详见 config.toml 速查。

仓库根模板（复制即用）

把下面存成仓库根目录的 AGENTS.md，按项目改：

# AGENTS.md

## 项目目标
- 用一两句话说明这个仓库做什么、交付长什么样。

## 技术约束
- 包管理器：pnpm / npm / bun（选一）
- 语言/框架版本：…
- 禁止引入未讨论的新生产依赖

## 怎么改代码
- 先只读摸清结构，再小范围改
- 公共 API 变更必须同步文档或注释
- 不要提交密钥、`.env`、本地绝对路径

## 验证（每次相关改动后）
- 运行：`…`（填真实命令）
- 手动检查：`…`
- 失败时：先贴命令与退出码，再继续改

## 代码审查关注点（可选）
- 安全：鉴权、注入、密钥
- 正确性：边界条件与回归
- 不要把格式问题当审查重点（交给 CI）

## 不要做
- 大规模无关重构
- 删除无把握的文件
- 跳过验证直接声称完成

全局偏好模板（可选）

~/.codex/AGENTS.md：

# ~/.codex/AGENTS.md

## Working agreements
- Prefer small, reversible diffs
- After JS/TS changes, run the project’s test or typecheck script
- Ask before adding new production dependencies
- Never paste secrets into chat or commits

临时全局覆盖用 ~/.codex/AGENTS.override.md，用完删掉即可回到原文件。

AGENTS.md 模板：让 Codex 按项目规矩干活的三步关键操作与请求骨架示意图 — 图 2 · 把关键操作拆成三步，并给每一步留下可观察结果

子目录覆盖示例

例如支付服务需要不同测试命令，在 services/payments/AGENTS.override.md：

# services/payments/AGENTS.override.md

## Payments service rules
- Use `make test-payments` instead of the root test script
- Never rotate API keys without notifying the security channel

从该目录启动 Codex 时，应能看到：全局 → 仓库根 → 子目录覆盖。

怎么验收写没写对

在仓库根：

codex --ask-for-approval never "Summarize the current instructions."

期望：回答里出现你刚写的条目。

在子目录：

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

期望：来源顺序正确，子目录规则生效。

AGENTS.md 模板：让 Codex 按项目规矩干活的结果验收与交付证据清单示意图 — 图 3 · 用结果、检查与交付证据确认任务真的完成

常见坑

现象	处理
完全没加载	文件是否为空；是否在预期仓库；工作区根对不对
规则不对	是否被上层/同层 `AGENTS.override.md` 盖住
被截断	提高 `project_doc_max_bytes` 或拆文件
想读 `TEAM_GUIDE.md`	在 config 里设 `project_doc_fallback_filenames`

和 CodexNav 学习线的衔接

装好环境后，用本模板固定项目规矩，再跑第一次真实任务。配置项对照：config.toml。入口选型：入口对照。

参考资料

Custom instructions with AGENTS.md