AGENTS.md 编写指南：给 AI 编程助手的项目边界说明书

1. 先搞清楚：AGENTS.md 到底是谁在看

1.1 从一次改错文件开始的反思

前阵子我接手了一套跨平台数据同步系统的日常维护，代码规模不算大，但结构很绕，平台相关逻辑和公共逻辑混在一起，生成文件也不少。为了提升效率，我给仓库接入了AI编程助手，结果第一个星期就翻车了：我让它调整某个同步模块的日志输出，它顺手把另一个平台专属目录里的核心逻辑也改了，代码评审时差点没发现。更让我头疼的是，每次新开会话，它都会把"这个项目是做什么的""测试命令是什么""为什么有两个配置文件"这类问题重新问一遍。

后来我慢慢意识到，问题不在AI本身，而在于我从来没有认真告诉过它这个仓库的基本规则。仓库里只有一份面向新人的 README，写了项目简介、架构概述和环境搭建步骤，但完全没有提到"哪些目录不能碰""改完 schema 必须重新生成""测试命令到底是哪个"。也就是说，AI 每次进入仓库时，手里只有一张模糊的地图，却要完成高精度的施工，出错几乎是必然的。

AGENTS.md 这个文件，才是真正给 AI 看的项目说明书。它和我平时写的 README 完全不同：README 是给人看的，叙事是完整的；AGENTS.md 是给智能体（agent）看的，内容应该是一组可以执行的指令、约束和边界。我花了两周时间，把它从一份二十多行的"备忘录"迭代成了一套分层上下文体系，整个项目的协作效率有了很明显的变化。这篇文章就是把这次治理过程拆开，聊聊 AGENTS.md 应该怎么组织、怎么落地、怎么避坑。

1.2 它和 README 有什么本质区别

很多人以为 AGENTS.md 就是 README 的 AI 版，其实两者的读者完全不同，写法自然天差地别。

我见过不少项目把 README 写得很完善，但 AI 该犯的错一个没少。原因很简单：把背景知识丢给 agent，它并不能自动推导出"我的行为边界在哪里"。比如 README 里写"本系统的平台适配层位于 src/platform 下"，它读了之后只知道有个目录叫 platform，并不知道改这里需要同时改配置、做回归测试、禁止硬编码。这些隐含约定恰恰是 AGENTS.md 要显式写出来的。

另一点容易被忽略的是：普通文档可以容忍冗余，但 agent 的上下文窗口是有限的。README 里一大段技术选型背景放进 agent 的上下文，挤掉的可能是它本可以用来理解当前任务的空间。所以我现在的原则是：给人看的文档负责解释，给 agent 看的文档负责约束。两者可以互相引用，但不要混写在同一份文件里。

1.3 交互习惯决定写法：agent 不是程序员

要写好 AGENTS.md，最好先理解主流的 AI 编程助手是如何使用它的。通常在会话启动时，工具会把仓库根目录下名为 AGENTS.md 的文件读取进上下文，部分工具还会叠加读取各子目录中的同名文件。它并不会像人一样通读全文并领会精神，而是把文件内容当成一组初始化提示词。

这对写法有两个直接影响。第一，顺序就是优先级。agent 对靠前内容的遵循度通常高于靠后内容，所以最核心的红线要放在文件前面，而不是藏在附录里。第二，措辞要像指令，不像描述。"建议不要修改构建产物"这类话效果很弱，agent 会把"建议"当成可选项；换成"dist/ 目录下任何文件均为构建产物，禁止手工修改，修改内容不会被保留"，行为立刻不一样。

我用一个类比来理解这件事：AGENTS.md 相当于 agent 入职第一天收到的岗位红线清单，而不是一本三百页的员工手册。红线清单要短、要具体、要有后果；员工手册虽然信息全，但新员工不一定记得住、抓不住重点。真实项目里，文件越短、约束越可验证，agent 的执行效果越好。

2. 真实项目里的上下文混乱，到底乱在哪

2.1 项目背景：一套跨平台数据同步系统

以我这次治理的项目为例。这是一个虚构的跨平台数据同步系统，下面就叫它"同步系统"，代码大概六万行，分为三个大块：后台服务、桌面端界面、一批同步脚本。仓库里还有不少自动生成的内容，包括接口封装、类型定义和资源文件。开发时还区分两个平台，很多逻辑长得像，入口和约定却不同。

这种项目有典型的上下文复杂特征：目录多、生成文件多、平台差异多、命令分散。对于人类开发者，靠长期记忆和代码评审能兜住；对于 AI 助手，它每次会话都是"失忆"的，如果没有人告诉它规则，它就只能靠猜。猜的结果，就是出现结构上很接近、语义上却很离谱的错误。

我当时大致盘了一下仓库的目录分布：

有了这张表，后面写 AGENTS.md 时，边界就非常清楚了。

2.2 三种典型失败模式

在治理前，我记录了几类高频问题，基本可以归类为三种：

1. 文件定位错误：两个平台目录结构几乎一样，agent 经常把 A 平台的改动落到 B 平台，甚至在一个平台目录里创建出另一个平台风格的目录结构。
2. 命令幻觉：它会在没有确认的情况下调用不存在的脚本或参数。比如项目里测试命令实际是make test-frontend，它能编出npm run test:all。
3. 破坏生成文件：generated/ 下的类型定义本应由 schema 重新生成，agent 为了修好类型报错直接手改生成物，下一轮生成时又把改动冲掉，反复制造不一致。

这些问题单看都不严重，但叠加起来很要命。每一次误改都需要人肉评审发现，每次发现都要回滚、重跑生成、重新验证，效率比不用 AI 还低。问题的根源不是 agent 不够聪明，而是项目里缺少一份它能读懂的、覆盖这些边界的上下文文件。

2.3 治理目标：把发散上下文变成可执行约束

遇到这种混乱局面，我没有急着去给 AI 写长篇大论的项目说明书，而是先定了几个治理目标：

• 减少重复问答：项目定位、常用命令这些信息，让 agent 一进仓库就知道。
• 降低误改率：把受保护目录、生成文件、平台差异写成立即生效的约束。
• 保证可验证：AGENTS.md 里的每条命令我都先跑一遍，确保不是摆设。
• 保持可演进：代码结构一变，文档及时跟上，不出现文档说的是旧结构的情况。

我当时做了个很粗糙的记录：同样让我完成一个同步模块的重构，治理前 AI 要反问四到五次，中途还会改错一两个文件；治理后基本几句话就能开工，出错回滚的情况明显减少。体感上，这份文件带来的回报比我想象中高很多。这也是我后来坚持把 AGENTS.md 当作生产配置而不是普通文档来看待的原因。

3. 分层上下文：我在项目里采用的治理结构

3.1 根级 AGENTS.md：全局约定只留一屏

为了不让 AGENTS.md 变成一个臃肿的大杂烩，我采用了三层结构。最上层是根目录的 AGENTS.md，只负责全局规则。它的目标是一屏以内能看完，我一般控制在八九十行，内容涵盖：

• 项目一句话定位（让 agent 知道这是什么系统）
• 三个最常用的命令（测试、类型检查、启动）
• 全局红线（哪些目录不能动、哪些文件是生成的）
• 通用工作流（开始改动前先看哪份文档、改完要跑什么检查）

示例内容大概是这样的：

# AGENTS.md ## 项目定位 同步系统：跨平台数据同步工具，核心逻辑位于 src/sync， 两个平台分别位于 src/platform-a 和 src/platform-b。 ## 常用命令 - 运行全部测试：`make test` - 类型检查：`make typecheck` - 本地启动后台：`make dev` ## 硬性约束 - generated/ 目录由工具生成，禁止手改，改 schema 后运行 `make gen` - 平台特有逻辑必须放在对应平台目录，禁止在 src/shared 中引入平台依赖 - 新增依赖前先与维护者确认 ## 工作流 1. 动手前先读 docs/ARCHITECTURE.md 2. 修改后运行 `make test` 和 `make typecheck` 3. 提交前检查 git status，确认没有意外改动的文件

这份文件不需要解释为什么，只需要告诉 agent 做什么、不做什么。如果你想知道某条规则的背景，可以在 docs 里补充说明，但 AGENTS.md 正文保持指令式。

3.2 子目录级 AGENTS.md：让上下文按需加载

很多项目的复杂度不在根目录，而在各个子模块里。把所有模块的细节都塞进根级文件，文件会迅速膨胀，agent 抓不住重点。我的做法是：把模块特有的规则放到子目录里的 AGENTS.md。

比如 src/platform-b/AGENTS.md 只写与平台 B 相关的约定：

# AGENTS.md ## 本模块说明 platform-b 是平台 B 的专属实现区域，所有改动都基于 src/platform-b/adapters。 ## 注意 - 不要引用 src/platform-a 的任何实现 - 新增适配器必须实现接口 SyncAdapter，并注册到 adapters/index.ts - 本地验证命令：`cd src/platform-b && make test-b`

为什么要这样分层？因为 agent 在修改某个子模块时，通常更容易读到该目录下的上下文，而不是每次都要从根目录的长文件中搜索。这种就近放规则的方式，类似代码里的最小权限原则：每个 agent 实例只加载它当前工作区域相关的上下文，而不是全仓的上下文。对于大仓库，这是避免上下文被稀释的关键手段。

当然，子目录级文件不宜滥用。如果每个十行的小目录都放一份 AGENTS.md，反而制造噪音。我一般在三类地方放：有平台差异的目录、有自动生成物的目录、有特殊集成逻辑的目录。

3.3 任务级上下文：会话开始时的一句话

三层结构的最后一层不在文件系统里，而在每次会话开始时的提示词中。用户可以在任务描述里补充本次任务的目标、范围和注意事项。

比如"给同步模块增加重试机制，只改 src/sync/retry.go，不要动 src/queue"。这句话在文件系统里没有对应文件，但对 agent 的约束效果往往比 AGENTS.md 还要直接，因为这是它当前正在执行任务的最即时指令。

所以我的建议是：AGENTS.md 负责稳定的长期约束，任务描述负责临时的短期约束。两者要配合好，而不是指望某一份文件解决所有问题。这也是我常跟朋友说的：AGENTS.md 写得再好，也不能替代一个清晰的任务描述；反过来，任务描述再清晰，缺少稳定的边界文件，agent 照样会在细节上翻车。

4. 怎么写才不被 agent 忽略：六条实战细节

4.1 命令必须可执行，且标注工作目录

AGENTS.md 里凡是出现命令，我都会先手动在仓库里跑一遍。原因很简单：如果文档给你的命令是错的，agent 就会在错误的路上一路狂奔。比如有次我写"运行测试：npm test"，实际上这个仓库根本没有 npm 项目，测试命令是 Makefile 里的make test。agent 照字面执行，自然失败。

标注工作目录也很重要。有些命令只能在子目录里跑，比如前端测试要cd frontend && pnpm test:unit；有些必须在根目录跑。AGENTS.md 里我会写成：

- 前端单测：`cd frontend && pnpm test:unit` - 后台服务测试：`make test-server`

这样 agent 就不会混淆。另外，命令命名要一致，避免同一个动作在文档里出现三种写法。比如一会儿叫make test，一会儿叫npm test，一会儿又写成"运行测试脚本"，agent 很容易理解错。

4.2 约束要"后果化"，像测试用例一样可验证

写约束时，我尽量让每条规则能被验证，最好能关联到一个检查命令。比如：

• 不要写"注意保持代码风格"，而要写"运行make lint，通过后再提交"。
• 不要写"不要改生成文件"，而要写"如果 git diff 里有 generated/ 下的文件，请先运行make gen重新生成，再对比差异"。

为什么要这样？因为 agent 在执行任务时，如果约束只是一个抽象原则，它需要自行判断当前行为是否触碰红线，很容易判断失误；如果约束对应一个可执行检查，它就能把"是否违规"变成"运行命令看结果"，判断成本低很多。这有点像测试驱动开发：你把规则写成测试，行为自然会被约束住。

我还在 AGENTS.md 里加过一段"提交前自检"清单，用 Markdown 的任务列表形式：

## 提交前自检 - [ ] `make lint` 通过 - [ ] `make test` 通过 - [ ] `git status --short` 无多余改动 - [ ] `generated/` 目录没有被手改

agent 在完成一个任务后，如果能按这个清单逐项核验，出错的概率会下降非常多。

4.3 只读边界越具体越好

人的直觉里，"dist 和 build 不能改"是不言自明的，但对 agent 来说并不存在"不言自明"。它不知道哪个文件是手工维护的，哪个是自动生成的。所以在 AGENTS.md 里，我会把只读边界写到文件或目录级别：

## 只读区域 - dist/、build/：构建产物，任何改动都会被 CI 覆盖 - generated/types.ts：由 schema 定义文件生成，手改无效 - scripts/vendor/：第三方脚本，禁止本地改动

写完这些后，我还会在真实任务里验证：故意让 AI 去调整 dist 目录里的一个文件，看它是否拒绝或先询问。如果它直接动手改，说明约束位置不对或者措辞不够强，需要调整。

4.4 排序即优先级：前 10 行决定行为

我前面说过，agent 对 AGENTS.md 靠前内容的遵循度明显更高。这和个人使用经验一致：文件开头如果先写了一大段项目背景，agent 读完后会把背景当成重点，后面的约束反而容易忽略。所以我现在的写作顺序固定是：

1. 红线（禁止事项）
2. 常用命令
3. 工作流
4. 可选背景说明

这样即使 agent 只认真读了文件的前半部分，它也会先看到最关键的约束。背景说明不是不重要，只是可以放在 docs 里，AGENTS.md 中一句话带过就行。

4.5 用清单驱动自查

除了给 agent 提供规则，还可以让它主动执行自查清单。我通常会在 AGENTS.md 末尾放一个固定段落：

## 完成标准 - [ ] 理解项目定位，不重复询问已说明信息 - [ ] 修改前搜索公共工具函数，优先复用 - [ ] 涉及 schema 变更时，运行 `make gen` 并检查生成结果 - [ ] 不触碰只读区域

这段清单不是写给人看的装饰品，而是给 agent 的"完成定义"。实测下来，带清单的 AGENTS.md 比纯叙述文档的合规性好很多。因为 agent 在完成任务时，会把清单当成验收标准，而不是靠记忆总结。清单里每一项都是可以被git diff、make test这类命令验证的，agent 也能更清楚地知道什么时候算真正做完。

4.6 给 agent 一个"不确定时怎么办"的兜底出口

最后一条很容易被忽略：AGENTS.md 不仅要定义能做什么、不能做什么，还要给 agent 一个不确定时的兜底动作。比如：

## 不确定时 - 如果无法确定某个文件属于哪个平台，先搜索 src/platform-a 下是否有同名实现 - 如果命令不确定，先运行 `make help` 查看可用的任务 - 如果仍然不确定，停止修改并向用户确认

这条规则的价值在于，它把 agent 的"猜"变成了"检查"。一个知道自己在什么情况下应该停下来的 agent，远比一个盲目往前冲的 agent 安全。尤其当项目里存在明显的镜像目录时，这条兜底规则能避免很多跨目录的误改。

5. 落地过程：从盘点、实测到迭代

5.1 三步盘点仓库现状

写 AGENTS.md 之前，我先做了三件事。第一步，扫描目录结构，搞清楚这个仓库到底有多少模块、哪些目录是核心、哪些是产物、哪些是第三方代码。第二步，收集常用命令，把 Makefile、package.json、scripts 目录里的真实命令全部列出来，标注出测试、类型检查、启动分别对应什么。第三步，回顾近期评审和回滚记录，找出最容易踩的坑，比如生成文件被手改、平台目录串位。

这三步做完，AGENTS.md 的框架基本就出来了。没有盘点的 AGENTS.md 是在脑补一个不存在的项目，写出来的规则要么过时，要么与现实脱节。我自己第一版就是凭印象写的，后来发现仓库里早就不存在那个结构了，花了不少时间修正。

5.2 用一组触发式提问做行为实测

初稿完成后，我采取了一个很有效的验证方式：像面试官一样，对 AI 助手问一组触发式问题，观察它的行为。我常问的包括：

• "这个项目的测试命令是什么？"——检验命令是否准确。
• "给同步模块加一个重试机制。"——检验是否能正确定位文件。
• "这个仓库里两个平台的区别是什么？"——检验是否有边界意识。
• "运行一下构建流程。"——观察是否触碰构建产物。

每次实测我都记录三类问题：文件定位错误、命令幻觉、踩保护目录。每个问题都对应 AGENTS.md 里的一条修改。这个方法很像测试驱动：先用测试用例暴露缺陷，再用修文档修复缺陷，直到所有用例通过。记录下来后，我也会把典型问题写成一个简单的对照表，方便以后回归验证。

5.3 把每次行为偏差都变成一次文档修订

AGENTS.md 不是一次写完就结束的。我在项目里建立了一个简单的维护机制：每一次 AI 行为不符合预期，第一反应不是骂 AI，而是回头改 AGENTS.md。比如 AI 把某个模块的改动放错了目录，我会在对应子目录的 AGENTS.md 里加一条更明确的说明；AI 编造了一个不存在的参数，我会在命令段落里补充正确用法。

我还习惯在 AGENTS.md 末尾维护一个简短的变更记录，格式不用复杂，一行即可：

## 变更记录 - 2025-xx-xx: 增加 platform-b 只读边界说明 - 2025-xx-xx: 修正测试命令为 make test

这个记录在多人协作时尤其有用，能快速看出文件最近发生了哪些变化，也方便评审时确认改动意图。它跟代码提交记录互为补充：提交记录说的是这次提交做了什么，变更记录说的是这个文件为什么变成了现在的样子。

5.4 多工具协同时的上下文文件分级

现在一个仓库里可能同时有多个 AI 相关工具在工作：代码补全、独立编程助手、自动化评审机器人，甚至还有不同的模型版本。如果把所有工具的专属约定都写进同一个 AGENTS.md，它们会互相干扰。比如某种工具适用的指令，在另一种工具里可能是噪音或冲突。

我的做法是：根目录的 AGENTS.md 只放所有工具都遵循的公共规则，比如命令、只读目录、编码规范；把特定工具的专项规则单独拆成文件，让对应工具按需读取。比如AGENTS.tool.md这种命名方式。公共文件保持稳定，专项文件按工具演进。这样即使未来更换 AI 工具，公共规则依然有效，迁移成本也低。

6. 常见问题与排查技巧实录

6.1 agent 无视规则？先查这五个位置

如果你发现 agent 没有遵守 AGENTS.md，不要急着下"它太笨"的结论，按以下顺序排查：

1. 文件位置：确认 AGENTS.md 在仓库根目录，且文件名大小写完全正确。部分工具有严格的大小写识别。
2. 指令优先级：检查是否有其他说明文件或任务描述与 AGENTS.md 冲突，如果有，把冲突消除。
3. 命令可执行性：把 AGENTS.md 里的每条命令复制到终端跑一遍，命令错了 agent 就会放弃遵守。
4. 措辞强度：把"建议""可以"改成"必须""禁止"，观察行为变化。
5. 会话状态：修改文档后新开一个会话再试，因为有些工具只在会话初始化时读取上下文文件。

我遇到过最隐蔽的问题是文件里同时存在两条互相矛盾的规则：一条说"generated 目录不要动"，另一条说"确保所有类型都可用，必要时在 generated 中补充类型"。agent 大概率会选择更具体的那条执行，结果还是破坏了生成目录。所以排查时别忘了全仓搜索所有 AGENTS.md 文件，不仅仅是根目录那个。

6.2 上下文太长被"冲掉"怎么办

仓库一大，AGENTS.md 很容易越写越长。我自己的经验阈值是：核心 AGENTS.md 超过 300 行后，后半部分内容基本是无效的，agent 对靠后规则的遵循率会明显下降。想解决这个问题，可以参考以下几点：

• 把核心红线压缩到前 30 行，保证即使只能读取部分内容，也能命中关键规则。
• 把展开细节放到子目录级 AGENTS.md 或 docs 文档里，通过"详见"的方式引用。
• 在一段时间内只强调一个重点工作项，把它临时放到文件最前面，完成后再移除。
• 如果上下文实在太多，考虑拆分仓库或模块，从架构上降低单次上下文的密度。

这条经验也解释了为什么要做分层：你不可能让一份文件承载所有信息，合理的做法是把最需要被遵守的规则放在最容易被读取的位置。

6.3 多人维护 AGENTS.md 时的冲突

团队一起用 AI 编程助手时，AGENTS.md 会变成所有人共同修改的文档，不可避免地出现几种问题：有人加了冲突规则，有人提交时把规则改得面目全非，还有人只改代码不更新文档。

我建议做三件事。第一，指定一名上下文负责人，负责审核所有 AGENTS.md 改动，避免口径不一致。第二，把 AGENTS.md 的改动纳入代码评审范围，任何涉及 AI 行为约束的变更都有记录可查。第三，如果团队对某条规则有争议，优先选择可验证的规则而不是靠语气的规则。比如"不要动 dist"这种争议少，但"代码风格要优雅"就没什么可执行性，不如直接落到make lint。

6.4 排查速查表

这张表是我在项目里实际用到的排查工具。遇到问题对着查一遍，大部分情况都能定位到根因，而不是停留在"AI 不听话"的表面判断上。

7. 写在最后：一次低成本、高回报的治理

整套流程走下来，我最直观的感受是：AGENTS.md 的维护成本远低于预期，但收益非常直接。它不像重构代码那样需要大动干戈，也不需要额外引入复杂的工具链，只需要在每次 AI 行为出现偏差时，把教训沉淀成一条可执行的规则。三个月后回头再看，这个文件已经成为我仓库里最重要的配置之一。

我也慢慢养成了一个习惯：每次改完核心模块，都会顺手检查 AGENTS.md 里对应的段落是否需要更新。这个动作比写注释还快，收益却大得多——下次 AI 进入仓库时，用的是最新规则，而不是一张已经过时的旧地图。如果你也发现 AI 编程助手频繁出一些低级错误，不妨先别急着换工具、加提示词，认真写一份 AGENTS.md，把边界、命令和工作流说清楚。它可能是你投入产出比最高的一个文件。