AGENTS.md 模式：哪些做法真正改变了智能体行为

我的第一个 AGENTS.md 是一份200行的团队风格指南粘贴内容。其中包含命名规范、代码审查清单、部署流程和架构原则。智能体忽略了其中大部分内容。原因不在于指令有误——而在于它们是文档，不是操作指令。

这一区别比本文中任何具体模式都更重要。AGENTS.md 是面向 AI 智能体的操作策略，不是面向人类的 README。智能体不需要理解为什么您使用约定式提交。它需要知道要运行的确切命令以及”完成”意味着什么。

TL;DR

大多数 AGENTS.md 的问题源于编写了面向人类的文档而非智能体操作指令。有效的文件应以命令为先（精确的调用方式，而非描述），按任务组织（编码、审查、发布等部分），并明确定义完成标准（显式的”完成”条件）。可靠地被忽略的反模式包括：散文段落、模糊指令（”小心一点”）以及相互矛盾的优先级。AGENTS.md 是一个被60,000多个项目采用的开放标准 ¹，可在 Codex、Cursor、Copilot、Amp、Windsurf 等工具中使用 ²。

背景： AGENTS.md 由 Linux Foundation 下属的 Agentic AI Foundation 管理 ³，白金成员包括 Anthropic、Google、Microsoft 和 OpenAI。本文介绍实用模式。有关 Codex 的具体配置，请参阅 Codex 指南。有关 Claude Code 的等效文件（CLAUDE.md），请参阅 Claude Code 指南。

哪些内容会被忽略

以下模式可靠地不会对智能体行为产生可观察的变化。我通过在有无指令的情况下运行相同任务来识别每一条，然后在每个模式10次以上的运行中比较任务完成准确率。GitHub 对2,500多个包含 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）发现智能体”在没有明确鼓励的情况下默认采用非交互行为”——静默地继续执行而不提出澄清问题，这导致解决率从48.8%降至28% ¹²。通过编号优先级来修复矛盾指令：”优先级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…”前缀直接映射到智能体推理任务上下文的方式。

升级规则

## 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

没有升级规则时，智能体在遇到阻碍时会默认采取越来越有”创造性”的变通方案——删除锁文件、绕过检查或静默忽略失败。”Never”列表与升级路径同样重要。明确禁止破坏性恢复模式可以防止最糟糕的失败情况。

单体仓库的目录作用域

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

根级指令与更深层的文件串联。工具从项目根目录遍历到当前工作目录，合并沿路径找到的每个 AGENTS.md ⁴。OpenAI 自己的 Codex 仓库在其单体仓库中使用了88个独立的 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 已被60,000多个项目采用 ¹，并被所有主流 AI 编码工具识别。以下是同一文件在不同生态系统中的表现：

如果您的团队使用多种工具： 将 AGENTS.md 作为权威来源。添加工具特定文件（CLAUDE.md、.cursorrules），导入或镜像相关章节。不要维护会逐渐产生差异的平行指令集。

编写顺序：先添加什么

如果您从头开始编写 AGENTS.md，请按以下优先级顺序添加章节。每一层建立在前一层的基础上：

1. 构建和测试命令 ——智能体在执行任何有用操作之前需要这些
2. 完成定义 ——防止”我觉得我完成了”的虚假完成
3. 升级规则 ——防止智能体卡住时采取破坏性变通方案
4. 按任务组织的章节 ——减少每个任务中不相关的指令解析
5. 目录作用域（仅限单体仓库）——保持服务指令的隔离

在前四项正常工作之前，跳过风格偏好。大多数 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行以内 ¹³。Codex 强制执行默认的32 KiB 限制（project_doc_max_bytes）⁴。过长的文件会被上下文窗口截断，因此将最关键的指令放在最前面——命令和完成定义优先于风格偏好。

AGENTS.md 能否替代工具特定的指令文件？

不能。AGENTS.md 与 CLAUDE.md、.cursor/rules 以及其他工具特定文件并行工作。将 AGENTS.md 作为权威来源，然后将相关章节镜像到工具特定文件中。AGENTS.md 中的模式（命令优先、明确完成定义）适用于任何指令文件，无论使用什么工具。

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

通过让智能体解释您的构建命令来测试。如果它不能逐字复述，可能是文件过于冗长（内容被推出上下文）、过于模糊（智能体无法提取可执行指令），或者未被发现（检查文件位置和工具文档）。GitHub 对2,500个仓库的分析发现，模糊性——而非技术限制——是大多数失败的原因 ¹¹。

核心要点

对于个人开发者：

• 用命令替代散文。每条指令都应该可以通过运行某些东西来验证。
• 明确定义完成标准。”完成”意味着特定的退出码，而非感觉。
• 通过让智能体背诵来测试您的 AGENTS.md。它背不出来的，它就不会遵循。

对于团队：

• 将 AGENTS.md 作为唯一的事实来源。镜像到工具特定文件，不要维护平行副本。
• 按任务（编码、审查、发布）组织，而非按类别（风格、测试、部署）。
• 包含升级规则。没有它们，被阻塞的智能体会以您不喜欢的方式即兴发挥。
• 在单体仓库中按目录设定作用域。服务特定的规则不应污染全局指令。

参考资料