2026 AGENTS.md 最佳实践：从模糊建议到精确命令，让 Codex 按你的规矩干活
很多人的 AGENTS.md 是这么写的：“我们重视干净、经过充分测试的代码，请遵循 TDD 原则，提交前确保所有改动都经过测试。”——结果 Codex 该不写测试还是不写测试。GitHub 分析了 2500 个包含 AGENTS.md 的仓库，得出了一个扎心的结论：大多数 Agent 指令文件之所以失败，不是因为技术限制，而是因为它们太“模糊”了。问题不在于你写错了什么，而是你写的是一份给人阅读的说明书，而不是给机器执行的行动指令。这篇文章，就是来帮你迈过这道门槛的。
一、先弄清楚 AGENTS.md 到底是什么
如果你正在使用 Codex，AGENTS.md 是无法绕开的。但很多人对它的定位仍然一知半解。
最直接的定义：AGENTS.md 是写给 AI Agent 的 README，是一份面向机器的操作策略文件。
人类通过 README.md 来理解项目，AI Agent 则需要一份专门的文件来掌握“在这个项目里我该如何工作”——构建命令是什么、测试怎么跑、代码规范有哪些、什么叫“一个任务完成了”。这些信息如果硬塞进 README 会让人类文档变得臃肿难读，因此把它们单独拆出来更合理。
2026 年的新身份：正式开放标准
很多人可能还停留在过去的印象里，这里必须更新一下认知：
| 时间 | 事件 |
|---|---|
| 2025年8月 | OpenAI、Google、Cursor、Claude Code 等联合发布 AGENTS.md 开放标准 |
| 2025年底 | 移交给 Linux Foundation 旗下的 Agentic AI Foundation 进行托管 |
| 2026年6月 | 超过 60,000 个项目 采用，20+ 工具原生支持 |
Agentic AI Foundation 的白金成员名单本身就很能说明问题：Anthropic、Google、Microsoft、OpenAI。四大厂商都在背后，这意味着 AGENTS.md 不是某家公司的私有格式，而是 AI 编程领域的“事实标准”。
来源：AGENTS.md 模式：哪些做法真正改变了智能体行为、面向 AI 开发的软件架构模式（知乎）
它解决的核心痛点：消灭配置文件碎片化
在 AGENTS.md 出现之前，每个工具都得有自己的指令文件：
| 工具 | 各自的配置文件 |
|---|---|
| Cursor | .cursorrules / .cursor/rules |
| Claude Code | CLAUDE.md |
| Aider | .aider.conf.yml / CONVENTIONS.md |
| Gemini CLI | GEMINI.md / .gemini/settings.json |
| Windsurf | .windsurfrules |
一旦你换了工具，所有配置就失效了；团队里不同成员用着不同的 AI 助手，配置根本无法复用。AGENTS.md 的目标就是用一份文件，覆盖所有工具。
二、最关键的一个洞察：它是操作指令，不是文档
这是整篇文章最重要的段落，读懂了它，后面所有的内容都会顺理成章。
国外开发者 Blake Crosley 做过一个非常扎实的实验：他最初的那份 AGENTS.md 足足有 200 行，包含团队风格指南、命名规范、代码审查清单、部署流程和架构原则——结果 Agent 几乎忽略了其中绝大部分内容。
他把同一个任务在“有指令”和“无指令”两种情况下各跑了 10 多次，对比任务完成准确率，总结出一条核心结论：
AGENTS.md 是面向 AI 智能体的操作策略，而不是面向人类的 README。
智能体不需要去“理解”你为什么使用约定式提交，它需要知道的是要运行的确切命令，以及“完成”到底意味着什么。
来看同一个需求——“要求写测试”的两种写法对比：
❌ 文档式写法（会被无视）：
我们重视干净、经过充分测试的代码。团队遵循 TDD 原则，
相信全面的测试覆盖率。请确保所有改动在提交前都经过充分测试。
Agent 读完后，会把它标记成一个“模糊的偏好”，然后依旧不写测试。因为这段话里没有可执行的指令——没有要运行的命令，没有要达成的阈值，也没有“充分测试”的具体定义。
✅ 操作指令式写法（真正有效）：
## 完成定义
一个任务完成，当且仅当以下全部通过：
1. ruff check . 退出码为 0
2. pytest -v 退出码为 0 且无失败
3. mypy app/ --strict 退出码为 0
4. 改动文件已 stage 并提交
5. 提交信息遵循 type(scope): description 格式
通过显式定义“完成”，就能消除 Agent 最常见的一种失败模式：没有验证就报告“我已经完成了”。当“完成”被细化到具体的退出码时，Agent 在汇报完成之前，就不得不老老实实跑完每一个检查项。
请牢记下面这条规律，它适用于整篇文章：没有附带验证命令的指令是“建议”，而不是“规则”。
来源：AGENTS.md 模式：哪些做法真正改变了智能体行为
三、四大致命反模式：你写的这些，Agent 全都当成了空气
Blake Crosley 的实验还识别出了四种“写了也白写”的模式。对照着自查一下，你的 AGENTS.md 中了几条？
反模式 1：没有命令的散文段落
就是上面那种“我们重视干净代码”的例子。散文 = 模糊偏好 = 会被忽略。
反模式 2：模糊不清的指令
<!-- BAD：对 Agent 来说毫无意义 -->
- 数据库迁移要小心一点
- 尽可能优化查询
- 优雅地处理错误
“小心一点”不是约束，“尽可能”不是触发条件，“优雅地”也不是行为规范。这些话听起来像是人与人之间的叮咛，而不像给机器的指令。
正确的做法是把它转化为可被验证的命令：
- 应用迁移前先运行 alembic check。如果缺少降级路径，中止。
反模式 3：相互矛盾的优先级
<!-- BAD：Agent 不知道该听哪一条 -->
- 快速迭代，尽快发布
- 确保全面的测试覆盖率
- 运行时预算控制在 5 分钟以内
- 每次提交前跑完整的集成测试套件
Agent 无法同时满足这四条。当指令相互冲突且没有明确的优先级时，模型就会跳过验证步骤，直接去生成代码。
这里涉及一个很重要的研究结论：ICLR 2026 的一篇论文（AMBIG-SWE）发现，Agent 在指令模糊时会“默认进入非交互模式”——不提问、闷头硬干，这导致任务解决率从 48.8% 暴跌到 28%。
修复的方法是用编号把优先级明确下来：
- 优先级1：测试通过
- 优先级2：5 分钟以内
- 优先级3：快速交付
反模式 4：没有强制执行的风格指南
<!-- BAD：没法验证是否合规 -->
所有代码遵循 Google Python 风格指南。
公开函数使用 numpy 风格的 docstring。
除非你给出确实能强制执行的 lint 命令（比如 ruff check --select D 或 pylint --rcfile=.pylintrc），否则 Agent 没有任何机制去验证自己到底合不合规。
四条反模式提炼成一句话的关键教训：模糊，是 Agent 指令文件的头号杀手。
四、五个真正有效的模式：照着写，行为立刻就会改变
反过来看，哪些写法真的能影响 Agent 的行为？答案同样来自 Blake Crosley 的对比实验。
模式 1：命令优先（最重要的一条）
## 构建和测试命令
- 安装依赖：pip install -r requirements.txt
- Lint：ruff check . --fix
- 格式化：ruff format .
- 测试：pytest -v --tb=short
- 类型检查：mypy app/ --strict
- 完整验证：ruff check . && ruff format --check . && pytest -v
你写下的每一条指令，都应该能回答这样一个问题：“什么命令能证明这件事真的做对了？”
模式 2：完成定义（Definition of Done）
参考上文的例子。把“完成”从“我觉得自己完成了”变成“这些退出码全部为 0”。这一条能挡住 Agent 最爱犯的错——没有验证就交差。
模式 3：按任务组织章节
不要写成一个扁平的规则清单，而是用 When... 前缀，按任务场景来拆分：
## 写代码时
- 每次改动文件后运行 ruff check .
- 给所有新函数加类型注解
- 测试命令：pytest tests/ -v -k "test_<module>"
## 审查代码时
- 检查安全问题：bandit -r app/
- 验证测试覆盖率：pytest --cov=app --cov-fail-under=80
- 列出改动文件：git diff --name-only HEAD~1
## 发布时
- 更新 pyproject.toml 里的版本号
- 跑完整套件：pytest -v && ruff check . && mypy app/
- 打标签：git tag -a v<version> -m "Release v<version>"
When... 前缀能够直接对应 Agent 推理任务上下文的方式，让它能根据当前正在做什么，快速挑出相关指令。
模式 4：升级规则（When Blocked + Never 列表）
这一条很多人不知道要去写，但它特别重要。
## 遇到阻碍时
- 如果测试连续失败 3 次：停下来，附上完整失败输出再报告
- 如果缺少依赖：先查 requirements.txt，再问我
- 如果遇到合并冲突：停下来，展示冲突文件
- 绝对不要：靠删文件来解决报错、强制 push、跳过测试
如果没有升级规则，Agent 在被卡住的时候会变得越来越“有创意”地瞎搞——删锁文件、绕过检查、静默地忽略失败。Never 列表和升级路径一样重要，它可以明确禁止那种破坏性的“自救”行为。
模式 5：单体仓库的目录作用域
AGENTS.md 支持“就近原则”——离工作目录越近的文件优先级越高：
/repo/AGENTS.md ← 全项目规则
└─ /repo/services/AGENTS.md ← 服务层默认
├─ /repo/services/api/AGENTS.md ← API 专属规则
└─ /repo/services/web/AGENTS.md ← 前端专属规则
工具会从项目根目录遍历到当前工作目录，把路径上遇到的每个 AGENTS.md 合并起来。OpenAI 自己的 Codex 仓库，在单体仓库中使用了 88 个独立的 AGENTS.md 文件——每个服务、每个包都有一份。
来源：AGENTS.md 模式：哪些做法真正改变了智能体行为
五、实战：从零开始编写一份 AGENTS.md（包含模板和编写顺序）
不要一上来就去写风格规范。Blake Crosley 总结出了一个经过验证的编写优先级顺序，每一层都以前一层为基础：
| 优先级 | 该写什么 | 为什么 |
|---|---|---|
| 1 | 构建和测试命令 | 没有这些，Agent 什么都干不了 |
| 2 | 完成定义 | 防止“虚假完成” |
| 3 | 升级规则 | 防止卡住时瞎搞 |
| 4 按任务组织的章节 | 写代码/审查/发布 | 减少无关指令的干扰 |
| 5 | 目录作用域（仅单体仓库） | 隔离服务级规则 |
大多数失败的 AGENTS.md，都是因为一上来就写风格指导，却从来没有写过命令。
直接可用的模板
下面是一份面向 Java 后端项目的完整模板，你可以直接改造并使用：
# 项目 AI 编程指南
## 技术栈
- 语言：Java 17
- 框架：Spring Boot 3.x + MyBatis-Plus
- 数据库：MySQL 8 + Redis
- 构建：Maven
## 构建和测试命令
- 编译：mvn clean compile
- 打包（跳过测试）：mvn clean package -DskipTests=true
- 运行测试：mvn test
- 代码检查：mvn checkstyle:check
- 完整验证：mvn clean compile && mvn test
## 完成定义
一个任务完成，当且仅当：
1. mvn clean compile 退出码为 0
2. 涉及改动的模块 mvn test 全部通过
3. mvn checkstyle:check 无违规
4. 改动文件已提交，提交信息遵循 type(scope): description
## 写代码时
- 实体类尽量使用 lombok 简化代码
- 数据库表名遵循 _config/_info/_log 后缀规范（阿里巴巴 Java 开发手册）
- 优先使用 Java Stream API
- 所有表必须包含 id、created_at、updated_at 三个标准字段
## 遇到阻碍时
- 如果编译连续失败 3 次：停下来，附完整报错再报告
- 如果依赖缺失：先检查 pom.xml，再问我
- 绝对不要：删除其他模块代码来消除报错、跳过 checkstyle、强制 push
## PR 规范
- 标题格式：type(scope): description（如 feat(auth): add JWT validation）
- 必须包含：改动的背景、测试方式、影响范围
关于篇幅：别写得太长
| 限制项 | 推荐值 |
|---|---|
| 单个章节 | 50 行以内 |
| 整个文件 | 150 行以内 |
| Codex 默认上限 | 32 KiB（project_doc_max_bytes） |
过长的文件会被上下文窗口截断——你以为已经写进去了，实际上 Agent 根本就没读到。因此，最关键的指令（命令、完成定义）一定要放到最前面。
文件变得太大了怎么办
OpenAI 官方给出的建议是：主文件保持简洁，把规划、代码审查、架构等具体内容拆到独立的 markdown 文件里，然后在主文件中引用它们。
## 详细规范
- 代码审查规范见 code_review.md
- 架构原则见 architecture.md
- 测试策略见 testing.md
这样既能保证不撑爆上下文，又能保留完整的规范体系。
来源：Codex 入门最佳实践（OpenAI 官方）、AGENTS.md 模式
六、三件套的定位：CLAUDE.md / AGENTS.md / SKILL.md 怎么配合
这是 2026 年 AI 编程配置的完整图景，很多人会把这三者搞混。
| 文件 | 定位 | 作用域 |
|---|---|---|
| AGENTS.md | 跨工具通用契约（事实来源） | 所有支持该标准的工具 |
| CLAUDE.md | Claude Code 专属记忆 | Claude Code |
| SKILL.md | 可复用的具体工作流 | 按需加载，所有支持 Skills 的工具 |
用一句话理解三者的关系
- AGENTS.md = 项目宪法：定义全局规则、命令和完成标准
- SKILL.md = 操作手册：把某个具体工作流（如 PR 审查、日志分析）封装成可按需调用的技能
- CLAUDE.md = 方言适配器：Claude Code 专属的额外配置
2026 年的最佳实践是采用双层结构：
维护一份不超过 100 行的 AGENTS.md 作为跨工具的通用上下文
↓
把具体的工作流封装成独立的 SKILL.md 文件，让 Agent 按需加载
这样一来，既保证了上下文的干净（主文件短小），又保留了下来丰富的工作流能力（Skills 按需加载，不会占用常驻上下文）。
2026 年的一个关键更新：Claude Code 已经支持 AGENTS.md
很多旧文章（2025 年年中的）还在说“Claude Code 不支持 AGENTS.md”。这个信息已经过时了。
2026 年的实际情况是：Claude Code 会同时读取 CLAUDE.md 和 AGENTS.md，并把两者的内容合并起来。 如果你的项目需要兼容多个 AI 工具，那么就把 AGENTS.md 当作权威来源，然后在 CLAUDE.md 里只放 Claude 专属的配置即可，不必再去维护两份平行的内容。
来源：InfoQ《2026 年 AI 编码 CLI 工具终极对比》、腾讯云《为什么我的 Claude Code 老是不按我说的做》
七、跨工具兼容性矩阵：一份文件，八大工具通吃
团队最关心的问题来了：我写了 AGENTS.md，到底哪些工具会认它？
| 工具 | 原生文件 | 读取 AGENTS.md？ | 备注 |
|---|---|---|---|
| Codex CLI | AGENTS.md | ✅ 原生 | 完整层级 + override 支持 |
| Cursor | .cursor/rules | ✅ 原生 | 自动发现项目根和子目录 |
| GitHub Copilot | .github/copilot-instructions.md | ✅ 原生 | 编码智能体原生支持 |
| Amp | AGENTS.md | ✅ 原生 | 标准联合创建者 |
| Windsurf | .windsurfrules | ✅ 原生 | 自动发现 |
| Claude Code | CLAUDE.md | ✅ 合并读取 | 同时读 CLAUDE.md 和 AGENTS.md |
| Gemini CLI | GEMINI.md | ⚙️ 可配置 | settings.json 里加 "fileName": ["AGENTS.md"] |
| Aider | CONVENTIONS.md | 📎 手动 | 需要 --read AGENTS.md 标志 |
Codex 独有的能力：AGENTS.override.md
有一个细节只有 Codex 支持：在任意层级放置一个 AGENTS.override.md，它会替换（而不是扩展）父级的指令。这适用于发布冻结期、事故应急，或者有安全约束需要覆盖项目默认值的服务。
<!-- /repo/services/payments/AGENTS.override.md（仅 Codex）-->
# 支付服务规则（覆盖）
本服务有额外安全要求。所有改动必须：bandit -r . -ll 零告警。
未经明确批准，不得更新依赖。
给多工具团队的建议
把 AGENTS.md 作为唯一的事实来源，然后把相关章节镜像到工具专属文件中（如 CLAUDE.md、.cursorrules）。千万不要维护几份会慢慢跑偏的平行指令——维护一份，镜像其余，这才是正确的姿势。
八、三个进阶技巧：让 AGENTS.md 真正发挥作用
技巧 1：用 /init 快速生成初始版本
在 Codex CLI 里输入 /init，它会扫描项目并自动生成一份初始的 AGENTS.md 作为起点。但请一定注意——这只是起点，必须根据团队的实际工作方式再做编辑，不要直接拿来就用。
技巧 2：多层级配置，越具体越优先
Codex 的 AGENTS.md 支持三个层级：
| 位置 | 作用域 | 典型内容 |
|---|---|---|
~/.codex/AGENTS.md | 个人全局默认 | 个人偏好（如代码风格） |
仓库根目录 AGENTS.md | 团队共享标准 | 构建/测试命令、规范 |
子目录 AGENTS.md | 局部规则 | 某个服务/模块的特殊要求 |
越具体的文件优先级越高。把团队级规范放在仓库根目录并提交到 git，而把个人偏好放在 ~/.codex（不要提交）。
技巧 3：怎么验证 Agent 真的读了你的指令？⭐
这是最实用的一招。太多人写完 AGENTS.md 就以为大功告成，实际上它根本就没被读进去。
验证方法：让 Agent 背诵你的构建命令。
# Codex
codex --ask-for-approval never "Summarize your current instructions"
codex --ask-for-approval never "What is your definition of done?"
# Claude Code
claude --print "What instructions are you following for this project?"
关键的测试是：让 Agent 解释你的构建命令。如果它不能逐字复述出来，就说明指令要么没有被读取，要么内容太长已经被挤出了上下文窗口。
Agent 背不出来的规则，它就不会去遵循。
九、检查清单 + OpenAI 官方点名的常见错误
你的 AGENTS.md 合格了吗？对照清单
- 开头就是构建/测试命令，而不是公司价值观
- 有明确的“完成定义”（具体到退出码）
- 有升级规则和 Never 列表
- 按
When...任务场景组织，而不是扁平列表 - 每条规则都附带可执行的验证命令
- 整个文件不超过 150 行
- 没有相互矛盾的优先级
- 用
/init+ “背诵测试”验证过 Agent 真的读进去了
OpenAI 官方点名的 8 个常见错误
这些都是新手最容易踩的坑：
- 把持久性规则一股脑塞进提示词，而不是写进 AGENTS.md
- 没有告诉 Agent 怎么运行构建和测试，导致它看不到自己的工作结果
- 跳过复杂任务的规划阶段就直接开干
- 还没搞清工作流就给 Codex 开放了完整权限
- 同一批文件在多处并行处理却不使用 git worktree（会互相冲突）
- 任务还不稳定就把它做成自动化
- 像监工一样盯着 Codex 一步步执行，而不是让它并行工作
- 一个线程对应一个项目，而不是一个任务，导致上下文膨胀、效果变差
写在最后
用对 AGENTS.md，本质上是一次思维方式的转变：从“给人写文档”切换到“给机器写操作指令”。
请记住这三个核心判断：
- 它不是 README，而是 Agent 的操作策略——命令优先，模糊靠边
- 没有验证命令的指令只是建议，不是规则——每条规则都要能跑出验证结果
- Agent 背不出来的规则等于没写——用“背诵测试”验证，而不是一厢情愿地以为它读进去了
2026 年的完整图景已经非常清晰：AGENTS.md 当宪法（全局规则），SKILL.md 当手册（具体工作流），CLAUDE.md 当方言（工具专属配置）。一份不超过 100 行的 AGENTS.md，再配上几个按需加载的 SKILL.md，就是你给 AI 队友最好的“上岗培训手册”。
Codex 再强，也是一个需要持续配置和调教的队友，而不是一次性助手。而 AGENTS.md，就是你和这个队友之间最重要的“沟通协议”。
写好它，你的 Codex 才会真正按你的规矩干活。
参考来源：
- AGENTS.md 模式：哪些做法真正改变了智能体行为 - Blake Crosley（2026-02-28，含 GitHub 2500 仓库分析与 ICLR 2026 研究）
- Codex 入门最佳实践（OpenAI 官方）- 53AI 转载（2026-05-30）
- AGENTS.md：AI 编程最佳实践的新标准 - 腾讯云
- Codex 使用指南：配置、AGENTS.md 与 Agentic 工作流 - JavaGuide
- 一万字讲透 CLAUDE.md/AGENTS.md：从基础到反直觉
- 2026 年 AI 编码 CLI 工具终极对比 - InfoQ
- OpenAI Codex 官方文档