如何写一个真正能帮到你 AI 编码 agent 的 AGENTS.md

如果你在真实项目上用过 AI 编码 agent，你大概遇到过这样的时刻：它跑错了测试命令、无视了你的格式化工具，或者重新发明了一个你早就有的辅助函数。解决之道通常不是更聪明的模型——而是给 agent 提供它推断不出来的、项目特有的上下文。这正是 AGENTS.md 文件的用途。

AGENTS.md 是什么

AGENTS.md 是一种简单、开放的 Markdown 格式，给编码 agent 一个可预期的地方去找到项目上下文和说明。它最初是 OpenAI Codex、Amp、Google Jules、Cursor 和 Factory 之间的一次协作，如今由 Linux 基金会下的 Agentic AI Foundation 进行维护管理。已有 25 多个工具读取它——包括 Codex、Cursor、VS Code、GitHub Copilot、Aider、Windsurf、JetBrains Junie、Zed 和 goose——并且它出现在超过 6 万个开源仓库中。

把它想成一份写给 agent 而非人类的 README：README 向新贡献者解释你的项目；AGENTS.md 则告诉 agent 那些它否则会猜错的东西。（Claude Code 用户会认出 CLAUDE.md 是它的等价物；许多团队两个都留着，或者把一个软链接到另一个。）

它放在哪里

把 AGENTS.md 放在仓库根目录。在 monorepo 里，在每个包里再加嵌套的文件——agent 读取目录树中最近的那个文件，所以当 agent 在某个文件夹里工作时，packages/api/AGENTS.md 优先于根目录那个。这让一个 Python 服务和一个 TypeScript 前端各自获得量身定制的说明。

该往里写什么

格式就是普通 Markdown——用你喜欢的任何标题。常见有用的章节包括：

• 构建和测试命令——准确的命令，而不是近似
• 代码风格——格式化工具、linter，以及任何 linter 抓不到的约定
• 测试说明——如何运行单个测试、一个改动完成前必须通过什么
• 安全注意事项——绝不能碰的文件或操作
• 提交 / PR 约定——消息格式、分支命名
• 部署步骤——仅当 agent 被预期要碰它们时

下面是一个最小化、高信号的示例：

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

注意里面没有什么：没有架构长篇大论、没有重述文件夹结构、没有"这是一个用最佳实践构建的现代 web 应用"。这是刻意为之的。

通常越短越好

有一种诱惑是让 agent 替你生成一个巨大的 AGENTS.md。抵制它。2026 年苏黎世联邦理工学院的一项研究（由 InfoQ 报道）测量了这些文件的真实影响，发现其效果既微弱又参差。LLM 生成的上下文文件实际上把任务成功率平均降低了约 3%，同时让推理成本上升了 20% 以上。人类编写的文件帮助不大——成功率大约提升 4%——但仍推动 agent 多走了一些步骤，把成本提高了多达约 19%。

其机理很有启发性：agent 会乖乖照着文件里写的去做，所以一份庞杂的文档会让它们去跑多余的测试、读更多文件、执行手头任务并不需要的质量检查。研究者的建议是：彻底跳过自动生成的上下文文件，并把人类编写的说明限定在无法推断的细节上——也就是 agent 真正靠自己发现不了的特定工具和自定义命令。

换句话说，每一行都应当靠阻止一个你确实见过 agent 犯下的具体错误，来挣得它的位置。

一套行之有效的工作流

1. 从空白开始。 在你亲眼看到 agent 做错某件事之前，别写 AGENTS.md。
2. 写进去的是纠正，不是理论。 当它跑错了测试命令，就把正确的加进去。当它按它的方式重格式化了一个文件而 linter 报错时，就把规则加进去。
3. 保持精炼。 如果一行只是重述 agent 能从 package.json 或文件夹名读到的东西，删掉它。
4. 在 monorepo 里用嵌套，好让每个包的文件保持小巧。
5. 每月重读一遍。 过时的说明比没有更糟——一个照着过时构建命令行事的 agent 会自信地失败。

最好的 AGENTS.md 文件读起来像给那位"从不遗忘、但也从不推断"的队友准备的一张简洁入职小抄。把他们猜不到的东西写下来，其余一概不写。