AGENTS.md 是 AI 辅助开发时代一个非常实用的仓库级说明文件它解决的核心问题很直接当你把 AI 编程助手放进一个代码仓库时它并不知道你的构建命令、测试方式、代码风格、目录边界以及哪些文件不能随便改。把这些信息用简洁的 Markdown 记录成 AGENTS.mdAI 代理第一次进入仓库时就能少踩很多坑。这篇文章想重点聊一个我越来越确定的观点AGENTS.md 不要一开始就写大而全先保留一份最小可用版本随着仓库结构稳定再逐步丰富。这个思路听起来简单真正落地时却有不少细节值得展开。下面按我实际维护的顺序拆开讲。1. 先搞清楚 AGENTS.md 到底是给谁看的别和 README 混在一起1.1 给 AI 代理和协作者的“仓库操作说明”很多第一次接触的人会把它当成 README 的变体这是最常见的误解。README 的目标读者是人和搜索引擎负责讲“这个项目是做什么的、怎么安装、怎么使用”。AGENTS.md 的目标读者是 AI 代理、代码自动补全工具、代码审查助手以及愿意按同样约定参与开发的协作者。它讲的是“在这个仓库里工作时你应该遵守哪些操作规则”。换句话说README 回答 what 和 whyAGENTS.md 回答 how to work here。举个例子README 会说“运行 npm install 安装依赖”AGENTS.md 要写清楚“不要直接修改 package-lock.json新增依赖时使用 npm install xxx而不是手动编辑文件”。AI 编程助手现在越来越强但它在面对一个不熟悉的仓库时本质上还是靠猜测补全上下文。一份写得到位的 AGENTS.md 能把这部分猜测变成确定性规则。我在实测时发现没有 AGENTS.md 的仓库AI 代理经常会用错构建命令、改错文件或者把一次性脚本写进核心目录有了明确约定之后这类问题会明显减少。1.2 和 README、CONTRIBUTING、docs 的分工边界仓库里往往已经有不少文档AGENTS.md 的位置要划清楚否则很容易和 README、CONTRIBUTING、docs 内容重叠。README 面向用户讲安装、使用、截图、徽章。CONTRIBUTING 面向人类贡献者讲提 PR、跑测试、提交规范。docs/ 通常是功能文档讲架构、API、部署、教程。AGENTS.md 面向 AI 代理和需要自动化执行的协作者讲命令、约束、目录边界、任务流转规则。它和 CONTRIBUTING 有部分重叠但关注点不同。CONTRIBUTING 把规则当作“给人类的建议”AGENTS.md 则要写成“代理必须遵循的硬性约束”。比如“提交信息要遵循 Conventional Commits”这句话在 CONTRIBUTING 里只是规范在 AGENTS.md 里最好写成“每次提交前先检查变更文件按类型生成提交信息禁止把多个无关改动塞进同一次提交”。实际项目里我推荐把 AGENTS.md 放在仓库根目录文件名保持固定。大部分 AI 编程工具会默认读取这个文件名。如果仓库结构变化大可以在子目录放更局部的 AGENTS.md给代理提供局部上下文。2. 为什么一定要从 minimal 版本开始而不是一次写全2.1 写大而全的 AGENTS.md 反而让代理无所适从刚接触这个思路的人最容易犯的错就是一次性把几十条规则写进去。结果往往是代理读完一大份文件后抓不住重点该遵守的没遵守不该动的反而被限制住。把 AGENTS.md 写成一本厚重的操作手册并不能提升代理表现反而会让每次任务变慢。原因在于 AI 代理处理上下文时会尽量对齐所有约束。当约束过多、相互之间没有优先级时代理只能随机选一种解释。所以规则越多违反其中某一条的概率越高。维护者也会很痛苦因为每条规则都需要持续维护仓库一重构文档大概率过期。真正该做的是从最小可用版本开始。所谓最小不是只写项目名而是只写那些代理容易做错、且做错成本很高的事。比如“不要在 data/ 里提交临时文件”“测试命令是 python -m pytest tests/ -x”“修改模型权重路径前先搜一下旧路径在哪里被引用”。等到某个约束反复被触犯或者发现代理总是在同一类问题上犯错再把对应的规则补进去。2.2 极简版应该包含什么一份可以落地的初始模板一个太小的 AGENTS.md 也不推荐。它至少要覆盖三类信息项目是干什么的、最常用的命令、代理特别容易弄错的红线。我个人会从这样一份模板开始# AGENTS.md ## 项目概览 这是一个 Python 数据清洗工具偶尔也会被部署成命令行服务。 主要目录 - src/pipeline/ 为核心清洗逻辑 - tests/ 为 pytest 用例 - scripts/ 为一次性迁移脚本 ## 常用命令 - 安装依赖pip install -e .[dev] - 运行测试pytest tests/ -x - 代码格式ruff check src tests ## 红线 - 不要修改 src/pipeline/ 下的公共接口签名除非任务明确要求。 - 不要把脚本产生的临时 CSV 文件提交进仓库输出请放在 output/。 - 新增依赖时必须同步更新 pyproject.toml 和文档。这份文件长度很短但关键信息已经交代清楚了。第一段让代理知道项目结构第二段给出运行命令避免它靠猜第三段列出最容易出问题的地方。这三个部分比写满三十条细规则更能减少实际错误。2.3 初始版本验证如何判断 AGENTS.md 有没有被正确使用写完极简版后不要急着扩充。先做一轮验证判断代理到底有没有读到并遵守它。我的验证方式是把一个新人最容易踩坑的小任务交给代理比如“在项目里新增一个数据预处理函数并跑通对应测试”。如果代理按照 AGENTS.md 里的命令执行正确避开了红线说明文件生效了。如果代理完全无视这些约定优先排查工具是否支持读取根目录 AGENTS.md配置里是否关了相关开关或者文件是否被 .gitignore 忽略。这里有一个细节有些工具会在 README 里自动生成摘要而不是直接读 AGENTS.md。这种情况下AGENTS.md 写得好不好还要看 README 是否经过整理。所以验证时要同时观察代理的实际行为和你的工具链文档来源。3. 仓库开始膨胀之后AGENTS.md 应该怎么跟着长3.1 什么时候该更新信号和触发点我见过两种极端一种是从不更新文件写完就变成摆设另一种是每改一行代码就更新结果大部分规则根本没被触发过。比较合理的做法是“有信号才更新”。常见的更新信号包括代理在同一个问题上一周内犯错超过两次。你新增了一个目录结构从此稳定。测试命令、构建方式、依赖管理方式发生了变更。你明确拒绝过某类改动拒绝理由值得沉淀成规则。仓库入口文件、主分支、发布流程出现了结构变化。在这些信号里最关键的是“代理连续犯同一个错误”。它不是靠感觉而是靠 review 代理产生的 PR。如果你发现自己一遍又一遍地在评论里写“这个文件不能提交”“请改用项目里的 xx 模块”那就该把这句话写进 AGENTS.md 了。3.2 从模块化开始为不同目录分别写约定当仓库扩大后根级 AGENTS.md 不要无限膨胀。更合理的做法是保持根级文件精简在各子目录创建局部 AGENTS.md。AI 代理在读取文件时通常会合并仓库根目录的全局规则和当前定位目录的局部规则。比如一个仓库里有两个模块src/backend/是服务端使用 Go 和 Docker。frontend/是 React 应用使用 pnpm 和 Vite。根级 AGENTS.md 只写“仓库是前后端一体化项目提交后端改动时不要同时带上前端依赖”而src/backend/AGENTS.md写清楚“所有迁移必须用 goose 命令不要手改 generated SQL”。frontend/AGENTS.md写清楚“组件样式优先使用现有 design tokens禁止提交 console.log”。这样每个代理在进入对应目录时看到的是更贴合当前任务的上下文规则冲突的概率更低。子目录文件不要过长通常能覆盖某目录的常用命令和红线就够了。3.3 多包仓库和 repo 工具场景下怎么处理这里需要特别提醒一句repo 这个词在不同场景下指的是完全不同的东西。在 git 仓库语境里repo 就是代码仓库在 Android 开发等场景里repo 又是谷歌提供的一个多仓库管理工具核心是 manifest 和多个 git 仓库的同步在部分包管理体系里repo 还可以指软件源或包仓库。写 AGENTS.md 时先把这几个概念分清否则很容易把多仓库工具的配置写进错误的文档里。如果项目本身使用 repo 工具管理多个独立仓库根目录的 AGENTS.md 更多是给整个工作区看的操作约定而每个独立仓库内部还要有自己的 AGENTS.md。我见过一个比较混乱的做法在仓库的 AGENTS.md 里写“repo sync 之后记得跑某个脚本”结果代理不知道 repo sync 是外部工具的动作一度以为要在当前仓库里先执行造成工作目录错乱。遇到这种情况建议在根级 AGENTS.md 里明确写出工具链类型本工作区使用 repo 工具管理多个独立仓库。repo sync 只允许在 work 目录的根执行。 以下规则只适用于当前仓库 - 不要修改其他仓库的文件。 - 跨仓库依赖调整必须先写设计说明再谈代码改动。如果你把“repo”当成“git 仓库”的同义词那么写 AGENTS.md 时也建议统一叫“仓库”或“当前仓库”避免代理理解偏差。实际排错时如果看到error: repo is not installed. use repo init to install it here.这类报错先判断它来自外部 repo 工具还是当前 git 仓库的环境问题不要急着改 AGENTS.md 里的规则因为这两层问题通常毫不相干。4. 记录那些 README 里不会写但代理必须知道的事情4.1 构建、测试、代码生成各自用什么命令很多仓库里最缺的不是功能说明而是命令。AI 代理拿到一个任务后最常做的事是猜测如何跑测试、如何构建、如何生成代码。如果 AGENTS.md 里没有这些命令它可能从 README 里找也可能直接试错甚至会用默认的 npm test 或 pytest 猜一个结果自然不一致。所以命令部分要有三个维度如何安装依赖如何锁定版本。如何运行单测、指定测试文件、跑全部测试。如何构建、生成产物、校验代码格式。写得越具体越好。不要写“跑测试用 pytest”要写“跑全部测试用pytest tests/ -x -q只看某个文件用pytest tests/test_validate.py -x -q”。如果仓库里有 Makefile、Justfile、Taskfile也要写清楚任务名比如“构建所有镜像执行just build-all”。4.2 目录边界和“千万别动”区域比起告诉代理能做什么告诉它哪些区域不能动往往更重要。因为 AI 代理在生成代码时通常会优先参考现有结构但现有结构并不总是适合被随意复用。需要标红的目录一般包括vendor/、third_party/类第三方依赖目录改动后很难 review。generated/、dist/、build/类输出目录提交前要忽略。migrations/类已经上线的迁移文件一般不建议回滚修改需要新增迁移文件。包含测试夹具、配置模板、密钥占位文件的目录不应被代理随意添加或删除内容。写法上不要只说“不要修改”要给出替代路径。例如“不要修改migrations/下的历史文件需要变更 schema 时创建新的迁移文件”。没有替代路径的规则代理往往会更困惑。4.3 提交规范、依赖管理和输出文件处理这块内容是 AGENTS.md 与工程规范最容易衔接的部分也是定期维护时会被反复调整的部分。依赖管理上要写清楚“通过什么命令添加依赖、是否允许自动更新、哪些依赖必须共享”。比如一个 monorepo 项目里你最不想看到的就是代理在某个子包中单独引入一个全局工具的新版本造成环境分裂。把“新增根级依赖需要连同 workspace 配置一起改”写进去可以避免不少麻烦。提交规范最好落到具体命令和格式上。如果仓库使用 Conventional Commits可以写提交信息前缀feat、fix、refactor、docs、test。本次提交涉及的逻辑改动必须集中在同一主题。不要把格式化改动和功能改动混在同一次提交。输出文件处理也很重要。代理往往会因为图省事把中间结果、日志、临时脚本直接放到仓库根目录或src/里。AGENTS.md 里可以预留一个output/或.tmp/目录并写明哪些内容要进.gitignore哪些内容必须删除后才能提交。5. 版本敏感为不同场景创建不同粒度的 AGENTS.md5.1 根级、子目录级、任务级三个层级随着仓库成长AGENTS.md 会自然分成几个层级。三层结构是我目前用下来最顺手的。根级 AGENTS.md放全局约定内容精简只写仓库整体信息、根级命令、所有模块通用的红线。子目录级 AGENTS.md放局部约定覆盖某模块或某目录比如前端、后端、训练脚本、部署配置各自写一份。任务级说明不一定要放在 AGENTS.md 文件里可以在某个具体功能目录下放TASK.md或CONTEXT.md解释这个任务来自哪里、有哪些限制、验收标准是什么。重点在于根级和子目录级文件是长期维护的任务级说明是临时的。任务级说明不要写进 AGENTS.md否则仓库每个 issue 都在改 AGENTS.md文件会迅速膨胀到没人能维护。5.2 训练代码和部署脚本混在一个仓库时怎么拆这个场景在数据类项目里很常见。仓库里既有模型训练代码又有生产部署脚本还可能有一些 Jupyter Notebook。如果只写一份根级 AGENTS.md描述会非常笼统代理在训练目录和部署目录里看到的规则完全一样等于没有局部上下文。我的做法是分开写。根级只写“本仓库包含实验代码与生产部署代码改动前先确认你正在修改哪个区域”。training/AGENTS.md写“所有训练实验记录提交到runs/目录禁止把模型权重直接放进 git单条训练命令用python train.py --config configs/debug.yaml”。deploy/AGENTS.md写“生产部署脚本默认使用容器镜像修改镜像版本前先确认目标运行环境是否匹配”。这样每个代理在进入相应目录后看到的是匹配当前任务的规则而不是一份容易导致误判的全仓库规则。这个做法对减少“训练代码环境变量写错”“部署脚本用了实验参数”这类问题帮助很大。5.3 用 examples 和反例来校准代理行为除了规则文字AGENTS.md 里可以放少量“好例子”和“反例”。AI 代理对自然语言的解释能力有限但尤其擅长从少量示例中推断模式。如果仓库里有一条规则是“所有新增脚本都必须放在scripts/下并且包含--input和--output参数”那么给出一个期望的命令行示例会比一百次文字提醒更有效。同样如果提交 PR 有特定流程可以放一个“期望 diff”的小片段。注意 examples 不要写得太多每节一到两个足够。写的越多代理反而越难判断哪个示例是“当前任务应该参考的”。反例的作用也不是羞辱而是告诉代理“你看到这个模式时应该停下来先确认任务意图再继续”。6. 常见误判和排查当 AGENTS.md 没有生效时6.1 别把 AGENTS.md 和 repo 工具报错混在一起排错的第一步是分清报错来自哪一层。我在排查“代理没按 AGENTS.md 执行”时经常看到的是代理在执行过程中报了一堆 repo 相关错误比如error: repo is not installed. use repo init to install it here.于是维护者开始怀疑 AGENTS.md 写错了但其实这两个问题经常没有任何关系。repo 这个词在当前语境里有多种含义。一种是 git 仓库对应 AGENTS.md 描述的目标仓库另一种是谷歌的多仓库管理工具 repo它负责repo init、repo sync等命令还有一种是包管理里的软件源。如果你在 AGENTS.md 里把“仓库”和“repo 工具”混用代理就很容易在读取上下文时把它们当成同一件事。排查顺序是先确认报错命令属于哪个工具。如果命令是repo sync出错去查 manifest、repo 工具安装位置如果是pytest找不到模块再看 AGENTS.md 里的目录约定和 Python 环境如果代理压根没有遵守 AGENTS.md那就回到工具支持层面排查而不是继续堆规则。6.2 排查顺序工具是否支持、路径是否对、格式是否规范如果 AGENTS.md 写得很完整但代理就是不听按下面这个顺序排查。确认工具支持。不是所有 AI 编程工具默认读取 AGENTS.md有些工具叫 CLAUDE.md有些只读 README有些需要在配置里开启“仓库级规则”。先查工具的文档说明看它支持哪些文件名和字段。确认文件位置。大多数工具默认读取仓库根目录的 AGENTS.md。放在docs/AGENTS.md或嵌套目录不一定会被读取。子目录文件有没有被合并读取也要看工具实现。确认格式。Markdown 嵌套层级太深、表格结构异常、头部 YAML front matter 写错都可能影响解析。尤其要注意某些工具只读取根目录文件的前几百行如果关键规则写在文件最后可能永远读不到。确认权限和忽略规则。如果 AGENTS.md 被.gitignore或工作区忽略规则排除工具可能不会把它当作有效配置。最后看规则冲突。子目录 AGENTS.md 覆盖根级 AGENTS.md 时两条规则如果互相矛盾代理可能会选择更靠近当前目录但非预期的解释。这种冲突只能靠人工 review 发现。6.3 权限、引用、格式化导致的静默失败有些失败不会直接报错而是默默发生。最典型的有三种。第一种是符号链接或子模块。仓库里的AGENTS.md如果是通过符号链接指向外部文件某些工具出于安全考虑不会跟随链接。第二种是编码和换行符问题。文件如果带着 BOM或者用非 UTF-8 编码工具解析时可能失败。第三种是文件名大小写。在 macOS 上误写成agents.md在 Linux 或 Docker 环境里可能找不到目标文件。这些情况很难从代理行为里直接判断。一个有效的做法是在 AGENTS.md 里放一句带明确符号的标记比如“本仓库的构建命令统一使用 make build禁止使用 python setup.py build”然后给代理布置一个需要正确区分这两者的任务。如果代理还是用错你至少能确认文件没有被有效读取再继续排查。还有一种情况工具的上下文窗口有限读取规则时被 README 和大量源码挤掉了。这种情况不算 AGENTS.md 本身的问题解决方式是把 AGENTS.md 里最核心的命令和红线放到最前面避免排在长段落之后被截断。7. 我建议的落地流程从零到一个能用的 AGENTS.md7.1 先跑通一轮“代理从零完成任务”的实验不要急着写文件先做一个实验让 AI 代理在一个还没有 AGENTS.md 的仓库里完成一个小任务比如“修改某个配置项并跑通对应测试”。观察它会犯哪些错、会猜哪些命令、会试图提交哪些不该提交的文件。这个实验通常在 10 到 30 分钟内完成但得到的信息比看十篇教程都有价值。记录下三个清单它用错的命令。它误改的地方。你为了纠正在对话里手动补充的信息。这三样就是初始 AGENTS.md 的原材料。后续你在对话里再次解释同样的事情时不用怀疑“要不要写进去”因为已经验证过这些信息确实是漏掉的必要信息。7.2 把每次对话中需要重复解释的内容沉淀进来之后每轮任务都做同样的事如果你发现自己又一次在对话里解释“跑这条命令要加上环境变量”“这个目录不要放 CSV 文件”“先跑 lint 再提交”就在 AGENTS.md 里加一条。这个“重复即沉淀”的节奏比一次性追求完整更可持续。沉淀时注意规则的通用性。一次性的、只针对某个具体问题的说明不一定要写进 AGENTS.md如果是代理以后每次都会遇到的操作或者仓库结构调整后仍然成立的约束才值得记录。我通常的检查方法是这条规则换一个任务是否仍然适用如果不适用就不写如果适用写进去。7.3 定期 review哪些内容已经过时哪些需要删除AGENTS.md 需要 review不然也会像所有文档一样烂掉。建议每两到四周或每次项目结构大调整后把 AGENTS.md 从头读一遍做三件事删除已经失效的命令和路径。合并互相重叠的规则。把频繁被触发、但代理还是容易忘记的约束往前调。删除这个动作非常关键。很多维护者只加不减等到文件里全是过时约束时代理反而成了最忠诚的执行者——把已经废弃的构建命令当成圣旨。AGENTS.md 不是越厚越好维护它的目标是让代理少犯错不是让文件显得完整。7.4 一份可以照抄的验收清单最后给一份我每次写完或改完 AGENTS.md 都会过的清单。检查项说明怎么判断文件位置是否在仓库根目录路径是否确定工具能否发现首屏信息命令和红线是否靠前前 30 行是否已经覆盖最核心约定命令可执行命令是否能直接复制运行不含绝对路径、不依赖当前 shell 环境目录边界是否有明确“别动”区域每个重要模块是否标注了允许/禁止操作规则可验证每条规则都能通过任务检测给代理安排探测任务看能否避开红线无明显冲突根级和子目录规则是否一致同一类操作是否有两个互相矛盾的解释更新记录谁在什么时候改过哪些规则有简单的变更记录或 PR review 历史这张清单不需要每条都列出证据重点是强迫自己确认“这个文件不是写给人类看的而是写给代理执行的”。读完清单后如果每条都能给出一个明确的“是”这份 AGENTS.md 基本就能投入日常使用了。最后说一句个人体会。AGENTS.md 看起来只是一个 Markdown 文件真正难的是把它当作一套会生长的工程约定来经营。不要追求一稿到位也别把它写成 README 的复读机。从极简版本开始让代理和协作者的行为反馈来驱动更新仓库稳定到什么程度文档就生长到什么程度。踩过几次“规则太多导致代理不知道怎么选”“命令写错导致代理反复试错”的坑之后你就会明白small 的开局虽然朴素但往往是最能坚持到最后的方案。