AGENTS.md实战指南：一份文件管住所有AI编程工具，从规范到落地

AGENTS.md已被6万个开源仓库和20多种AI编程工具原生支持，2025年底捐入Linux基金会成为中立标准。一项2026年初针对124个真实PR的实测研究显示：有它的项目，AI完成任务的中位耗时降低28.6%，输出token减少16.6%。但写法决定成败——自动生成的AGENTS.md反而让任务成功率下降3%、推理成本上升20%。这篇文章讲清楚它的发现链、写法规范、各工具接入方式和反模式，附可直接抄的模板和15分钟落地清单。

关键词：AGENTS.md、AI编程、Codex、Cursor、Claude Code、上下文工程、AI Agent

一、你的AI听从指令吗？

用AI写代码的都见过这种场面：
让AI加一个按钮，它顺手把你的API封装层”重构”了；
让它跑测试，它敲了npm install，而你的项目用的是pnpm；
让它写个组件，MUI版本用错、状态管理用了useState而团队标准是Mobx；
让它提个PR，commit message是fix bug；
周一刚讲完的规矩，周三它原样再犯一遍……

这五个问题根因相同：AI不知道你的项目有什么约定、工具链和结构。每个新会话它都从白纸开始，你口头纠正一百次，也不会留存。

AGENTS.md就是堵住这个口子的文件——放在仓库根目录的纯Markdown，写明这个项目怎么构建、怎么测试、有什么规矩。AI编程工具开工前会自动读它，相当于每次交接班先看一眼墙上的交接清单。

这个格式2025年中由OpenAI发起，Cursor、Amp、Google Jules、Factory联合推动，2025年12月捐给Linux基金会旗下的Agentic AI Foundation（专管Agent开放标准），成了厂商中立标准。到2026年9月，GitHub上使用它的开源仓库超过6万个，OpenAI自己的主仓库里放了88份AGENTS.md。社区里流传的一句话概括了它的价值：”一份好的AGENTS.md相当于一次模型升级；一份差的，比没有文档更糟。”

二、规范：格式极简，规则讲究

2.1格式：没有必填字段

AGENTS.md就是标准Markdown，没有任何schema、frontmatter或必填章节。官方给的极简版长这样：

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

工具不解析结构，只是把全文拼进系统上下文。所以写法的自由度极高——这正是问题所在：怎么写全靠你自己把关。

2.2发现链：工具怎么找到这个文件

以Codex CLI为例，它构建指令链分两步：

1. 全局层：读~/.codex/下的AGENTS.override.md，没有则读AGENTS.md，二选一
2. 项目层：从Git根目录一路往下走到当前工作目录，沿途每个目录收一份AGENTS.md（或AGENTS.override.md），每目录最多一份
3. 合并：从根到叶依次拼接，离当前目录越近的文件排得越靠后、优先级越高

两个关键细节：

• 是拼接不是覆盖。全局和项目级文件同时生效，冲突条目才以更近的为准
• 默认32KiB上限（project_doc_max_bytes），算的是合并后总和。一份文件写太肥，可能把后面更重要的子目录文件顶出窗口

冲突时的最终裁决顺序：用户对话里的明确指令 > 离被改文件最近的AGENTS.md > 更上层文件。

2.3内容六要素

对比openai/codex（约290行）和astral-sh/uv（约20行）两份标杆文件，高质量AGENTS.md基本覆盖六块：

判断一条信息该不该放进去，有个实用标准：AI不知道这条就会写出错误的代码，放AGENTS.md；只是写得不够好，放详细文档，这里放链接。

三、不同工具下怎么用

3.1支持矩阵

3.2三个”异类”的接法

Claude Code——社区主流方案是symlink，一份文件两个名字：

ln -s AGENTS.md CLAUDE.md

不想用symlink，在CLAUDE.md第一行写@AGENTS.md，Claude Code会把文件内容导入。注意@引用只有Claude Code认识，其他工具会当纯文本，所以引用只能作为桥接手段，不能放核心内容。

Gemini CLI——改配置指定文件名：

// .gemini/settings.json
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Aider——同样一行配置：

# .aider.conf.yml
read: AGENTS.md

3.3 monorepo：嵌套文件

这是AGENTS.md设计里最值钱的一招。每个子包放自己的AGENTS.md，Agent处理packages/web/src/Button.tsx时自动用packages/web/AGENTS.md：

my-project/
├── AGENTS.md              # 全局：commit规范、通用边界
├── packages/
│   ├── web/
│   │   └── AGENTS.md      # 前端：React版本、组件规范、单文件测试命令
│   └── api/
│       └── AGENTS.md      # 后端：DB迁移规则、curl验证流程

规则只有一条：就近优先。根文件放所有包通用的内容，子文件放栈相关的特化指令，不要在子文件里重复根文件已有的规矩。

四、实战用例

4.1用例一：20行的最小有效版

参考uv仓库的思路，小项目根本不需要长文件：

# AGENTS.md

## 命令
- 安装依赖: `uv sync`
- 跑全部检查: `make lint`（含ruff和类型检查）
- 单文件检查: `ruff check path/to/file.py`
- 测试: `uv run pytest`，单测某个: `uv run pytest tests/test_foo.py::test_bar`

## 结构
- 路由和入口: src/main.py
- API定义: src/api/，按资源一个文件
- 不要动legacy/目录，只读

## 边界
- 允许直接做: 读文件、单文件lint、跑测试
- 必须先问: 安装新依赖、git push、删文件
- 禁止: 修改已应用的迁移脚本——要改就新增一个迁移

## 提交
- commit格式: `<type>: <description>`，type取feat/fix/docs/refactor
- 提交前必须跑通`make lint`

20行，每条可执行。这就是合格线。

4.2用例二：堵住”差一点”的代码

Builder.io创始人Steve分享过一个真实对比：把Figma设计稿丢给AI生成Tab组件，出来的代码看着不错，但MUI版本用错、emotion格式不符团队习惯、状态管理用了useState而非团队的Mobx、样式token没从统一文件取。修这些”差一点”的问题花的时间比重写还多。

加了AGENTS.md后同样的任务：

## 前端规范
- 用MUI v3，确保API兼容该版本
- 样式用emotion的`css={{}}`写法
- 状态管理用Mobx的`useLocalStore`，不用useState管理跨组件状态
- 所有颜色、间距从`app/lib/theme/tokens.ts`取设计token，禁止硬编码
- 图表用ApexCharts，不手写HTML/SVG
- 新依赖必须先征得同意

重跑任务，版本、格式、token全部正确。这类规则的价值在于：每一条都对应一次实际翻车。

4.3用例三：把AGENTS.md当反馈回路用

一个Python项目维护者的做法值得抄：每次AI犯错，不只在对话里纠正（下个会话就忘），而是让它把这条修正写进AGENTS.md。调了两周，文件从空白长到二十来行，全是它自己踩过、被逮住、然后记下来的坑，之后新会话基本不犯重复错误。

触发加内容的具体信号：

• 同一个错误第二次出现
• 你又敲了一遍上周敲过的那句更正
• code review发现它本该知道的库约定

五、反模式：怎么写会适得其反

这部分比正面清单更重要。ETH Zurich的AGENTbench评测给过数据支撑：

反模式一：用/init自动生成就提交。 LLM生成的AGENTS.md让任务成功率降约3%，推理成本升20%—23%。生成的内容大多是Agent自己能推断出的代码库描述，不需要写；而错误的那几行，Agent会忠实执行。正确做法：拿生成结果当草稿，人工删到只剩不可推断的项目特有信息。

反模式二：正确的废话。 “写干净代码””遵循最佳实践””用好的命名”——零可执行信号，纯token成本。每一条都换成可检查的动作：不说”注意质量”，说”提交前跑pnpm lint和pnpm test，红了修到绿”。

反模式三：30条裸don’ts。 Augment的评测里，堆砌禁令让Agent慢了约2倍；只有”never”没有”do”，Agent会卡住。每条禁令配一条出路：”禁止修改已应用的迁移——需要变更就新增一个迁移文件”。

反模式四：孤儿文档。 有评测统计过文档发现率：AGENTS.md本体约100%，被显式链接的文档超过90%，目录README约40%，没人链接的docs文件不到10%。你写的架构文档Agent基本看不见。修法：在AGENTS.md里显式链接关键文档，链接数控制在10—15个以内。

反模式五：复制README。 双倍维护、必然漂移，Agent读到过期副本。README给人类，AGENTS.md给Agent，重叠内容用链接。

反模式六：写代码里还没有的架构。 文件里写”我们全面使用CQRS”，代码里一处都没有——Agent会照文件忠实实现，提前制造不一致。只写今天真实存在的约定，模式落地了再更新文件。

反模式七：过时信息。 包管理器从npm换到pnpm，AGENTS.md没更新，之后每个会话它都在用错的命令污染lockfile。过时的规则比没有规则伤害大得多，因为Agent默认文件是可信的。

六、15分钟落地清单

1. 建文件：仓库根目录建AGENTS.md，名字必须精确（大写AGENTS+小写.md）
2. 填六要素：命令、结构、代码风格、测试、边界、提交规范，对照4.1的模板，每条写成可执行动作
3. 接异类工具：团队用Claude Code就加symlink，用Gemini CLI就改settings.json，用Aider就改conf
4. 配边界：明确”允许直接做/必须先问/禁止”三级，危险操作（push、装包、删文件）全部拦到”先问”
5. 提交进仓库：让队友直接继承，不要放.gitignore
6. 设反馈回路：约定”AI第二次犯的错，当场写进AGENTS.md”
7. 定期修剪：每月扫一遍，删掉过时命令和已解决的条目——文件是越修越短的过程，不是越写越长

monorepo再加一步：根文件只留通用项，给每个技术栈差异大的子包建嵌套文件。

七、结语

AGENTS.md的本质不是提示词，是把”你希望AI怎么在这个仓库里干活”从口头传递变成版本化的工程资产。它解决的问题很朴素——AI每轮从白纸开始——所以它的最佳形态也很朴素：短、准、每条可执行，随着项目演化持续修剪。

一个值得琢磨的问题：当这份文件成为团队里”AI协作规范”的唯一事实源，code review的对象就多了一种——不只是代码，还有这份管着所有代码的规则文件。谁有权改它、怎么评审改动，会慢慢变成团队工程流程的一部分。

50字内中文概述，概括文章核心内容和结论。

AGENTS.md已成为6万仓库、20多种AI工具通用的项目指令标准，本文拆解其发现链与写法规范、各工具接入配置、三个实战用例与七条反模式，附15分钟落地清单。