AGENTS.md 模式：什么才真正改变智能体的行为

我写的第一个 AGENTS.md，是把团队风格指南原封不动粘贴进去的 200 行内容。里面有命名规范、代码审查清单、部署流程，还有架构原则。智能体几乎全都忽略了。原因不是这些说明写错了，而是它们是文档，不是操作规程。

AGENTS.md 应当包含命令优先的说明（写明确切的调用方式）、按任务组织的章节（编码、审查、发布），以及智能体能够自行验证的明确”完成”标准。 请写运维策略，而不是给人看的文档。把智能体必须执行的具体 shell 命令、linter 配置和测试命令都写进去。避免大段散文、”小心一点”这类含糊指令，以及没有明确排序的相互冲突的优先级。AGENTS.md 是一项开放标准，已被超过 6 万个项目采用，并可在 Codex、Cursor、Copilot 等多种智能体工具中通用。

这一区分比本文中任何一条具体模式都更重要。AGENTS.md 是给 AI 智能体用的运维策略，不是给人看的 README。智能体不需要理解您为什么使用约定式提交，它需要知道的是该执行哪条确切的命令，以及”完成”究竟是什么样子。

要点速览

AGENTS.md 的大多数问题，都源于写成了给人看的文档，而不是给智能体用的操作规程。有效的文件具备三个特征：命令优先（写确切的调用方式，而非描述）、按任务组织（编码、审查、发布等章节）、明确定义收尾条件（清晰的”完成”标准）。必然被忽略的反模式包括：大段散文、含糊指令（”小心一点”）以及相互冲突的优先级。AGENTS.md 是一项已被超过 6 万个项目采用的开放标准 ¹，可在 Codex、Cursor、Copilot、Amp、Devin Desktop 等工具中使用 ²。

背景： AGENTS.md 由 Linux Foundation 下属的 Agentic AI Foundation 管理 ³，白金会员包括 Anthropic、Google、Microsoft 和 OpenAI。本文讲的是实用模式。Codex 专有配置请参阅 Codex 指南；Claude Code 的对应机制（CLAUDE.md）请参阅 Claude Code 指南。

哪些内容会被忽略

以下模式在智能体行为上稳定地产生不了任何可观察的变化。每一条都是我通过”有该说明”与”无该说明”两种条件下执行相同任务、每种模式跑 10 次以上并比较任务完成准确率而识别出来的。GitHub 对 2500 多个包含 AGENTS.md 的仓库所做的分析也得出了同样的结论：”大多数智能体文件失败，是因为写得太含糊” ¹¹。下面这些模式没有以任何可测量的方式提升准确率。

没有命令的散文段落

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

智能体读到这些内容，把它表示为一种模糊的偏好，然后照样写出没有测试的代码。这里没有可执行的指令，没有要运行的命令，没有需要达到的阈值，也没有对”充分测试过”的定义。

含糊的指令

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

“小心”不是约束。”在可能的情况下”不是触发条件。”优雅地”不是行为规范。这些读起来像是人对人的建议，而不是给智能体的指令。对比一下真正有效的写法：”应用迁移前先运行 alembic check。若缺少降级路径则中止。”

相互冲突的优先级

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

这四条智能体无法同时满足。当说明彼此冲突又没有明确的优先级排序时，模型会跳过验证步骤，直奔代码生成。ICLR 2026 的研究（Ambig-SWE）发现，”若不加以显式提示，即便面对严重缺乏规格说明的输入，模型也几乎从不发起交互”——智能体会默默推进，而不是提出澄清问题——而提示模型进行交互，可使规格不足任务的表现最多提升 74% ¹²。解决冲突说明的办法是给优先级编号：”优先级 1：测试通过。优先级 2：控制在 5 分钟以内。优先级 3：尽快发布。”

没有强制手段的风格指南

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

除非您写明强制执行该风格的确切 lint 命令（例如 ruff check --select D 或 pylint --rcfile=.pylintrc），否则智能体没有任何机制来验证自己是否符合要求。这里的道理是普适的：没有验证命令的说明只是建议，而不是规则。

哪些做法确实有效

以下模式能在智能体行为上带来稳定且可测量的变化。

命令优先的说明

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

命令没有歧义。智能体确切知道该运行什么、传哪些参数，并可以通过检查退出码来验证是否成功。AGENTS.md 中的每一条说明都应当回答这个问题：”哪条命令能证明这件事做对了？”

收尾条件的定义

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

明确的收尾定义消除了最常见的失败模式：智能体不做验证就报告”完成”。当”完成”被定义为特定的退出码时，智能体会在报告完成之前逐项执行检查。缺少这个定义，”完成”就变成了”我觉得我做完了”，而这正是智能体引入缺陷的常见来源。

按任务组织的章节

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

按任务组织的文件让智能体能够根据当前正在做的事情挑选相关说明。扁平的列表则迫使它不论上下文如何都解析每一条说明。”当……时”这一前缀，正好对应智能体推断任务上下文的方式。

升级处理规则

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

没有升级处理规则，智能体在遇阻时会退回到越来越”有创意”的变通做法：删除锁文件、绕过检查，或者默默忽略失败。”绝不”清单和升级路径同样重要。明确禁止破坏性的补救模式，能够防住最糟糕的失败情形。

面向 Monorepo 的目录作用域

分层作用域是 AGENTS.md 规范的一项核心能力 ²。离工作目录越近的文件优先级越高：

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

根目录的说明会与更深层的文件拼接在一起。Codex 会从项目根目录一路走到当前工作目录，把沿途找到的每个 AGENTS.md 合并起来 ⁴；而规范本身定义的是最近文件优先，因此其他工具在解析层级时可能有所不同 ²。OpenAI 自家的 codex 仓库就是这么做的：它在根目录文件之下还附带了一个嵌套的 AGENTS.md ⁴。

在 Codex 中，您还可以在任意层级使用 AGENTS.override.md 来替换（而不是扩展）上层说明 ⁴。这一覆盖机制是 Codex 专有的，其他工具并未实现。

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

何时使用覆盖： 发布冻结期、故障处置模式，或任何安全约束需要凌驾于项目级默认设置之上的服务。

跨工具兼容性

AGENTS.md 已被超过 6 万个项目采用 ¹，并获得所有主流 AI 编码工具的识别。同一份文件在各生态中的表现如下（表格内容已于 2026 年 8 月核验）：

如果您的团队同时使用多种工具： 把 AGENTS.md 写成唯一权威来源，再添加导入或镜像相关章节的工具专有文件（CLAUDE.md、.cursorrules）。不要维护会各自漂移的并行说明集。

编写顺序：先写什么

如果您要从零写一份 AGENTS.md，请按下面的优先级依次添加章节。每一层都建立在前一层之上：

1. 构建与测试命令——智能体得先有这些，才能做点有用的事
2. 完成的定义——防止”我觉得我做完了”这类虚假完成
3. 升级处理规则——防止智能体卡住时采取破坏性变通
4. 按任务组织的章节——减少每个任务中对无关说明的解析
5. 目录作用域（仅限 monorepo）——把各服务的说明彼此隔离

在前四项跑通之前，先别管风格偏好。大多数 AGENTS.md 之所以失败，就是因为一上来先写风格指导，结果一直写不到命令。

测试您的 AGENTS.md

验证智能体是否真的读取并遵循了您的说明：

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

关键检验： 让智能体解释您的构建命令。如果它无法逐字复述，说明这些内容要么没被读取，要么过于冗长以致无法在上下文中保留。过长的 AGENTS.md 会被上下文窗口截断——把每个章节控制在 50 行以内，并把最关键的说明放在前面。

常见问题

AGENTS.md 文件应该写多长？

我的经验法则是：每个章节控制在 50 行以内，整个文件控制在 150 行以内。这背后的原则来自 Marmelab 关于智能体体验的建议——由于编码智能体在每次会话开始时都会读取这个文件，它应当保持”简短切题” ¹³；不过具体的行数是我自己的标准，并非出自他们。Codex 默认强制 32 KiB 的上限（project_doc_max_bytes）⁴。长文件会被上下文窗口截断，所以请把最关键的说明——命令和收尾条件——放在风格偏好之前。

AGENTS.md 会取代工具专有的说明文件吗？

不会。AGENTS.md 与 CLAUDE.md、.cursor/rules 等工具专有文件是并存关系。请把 AGENTS.md 写成唯一权威来源，再把相关章节镜像到各工具专有文件中。AGENTS.md 中的这些模式（命令优先、明确收尾条件）适用于任何说明文件，与具体工具无关。

如果智能体忽略了我的 AGENTS.md 怎么办？

让智能体解释您的构建命令来做测试。如果它无法逐字复述，那么这个文件要么太冗长（内容被挤出了上下文），要么太含糊（智能体提取不出可执行的说明），要么根本没被发现（请检查文件位置和工具文档）。GitHub 对 2500 多个仓库的分析发现，大多数智能体文件失败都是因为写得太含糊 ¹¹。

关键要点

对个人开发者：

• 用命令替换散文。每一条说明都应当能通过运行某个东西来验证。
• 明确定义收尾条件。”完成”指的是特定的退出码，而不是一种感觉。
• 让智能体复述您的 AGENTS.md 来测试它。它复述不出来的内容，就不会去遵循。

对团队：

• 把 AGENTS.md 当作唯一可信来源。镜像到工具专有文件，而不是维护并行副本。
• 按任务（编码、审查、发布）组织，而不是按类别（风格、测试、部署）。
• 写上升级处理规则。没有这些规则，卡住的智能体会以您不喜欢的方式即兴发挥。
• 在 monorepo 中按目录划分作用域。某个服务专有的规则不应污染全局说明。

参考资料