最近我在不同仓库里做了个小实验同一个 AI 编程代理读不读 AGENTS.md产出的代码质量和维护成本完全是两个世界。AGENTS.md 说白了就是一份专门写给 AI 编程代理看的项目上下文说明书但真正让它从“一份文档”变成“一套可执行规则”的关键我认为就两点分层规则设计以及冲突检测。这两个词看起来像工程术语实际做起来并不复杂但踩过坑的人会知道能做到这两点的团队太少了。大多数项目里AI 代理的表现就是“薛定鄂的靠谱”——在 README 完善、目录清爽的仓库里像高级实习生在约定混乱的老仓库里就像醉汉。而 AGENTS.md 这套机制的妙处是它把“团队约定”显式地编码成 AI 能读取的行为边界。这篇文章我会从原理讲到落地把我自己维护 AGENTS.md 的真实过程、踩过的坑、以及一套冲突检测的土办法一次性写清楚。无论你是个人开发者还是团队维护者只要在用 Cursor、Claude Code、Codex 这类工具都值得往下看。1. 为什么 AI 代理需要一份可执行的 AGENTS.md1.1 AI 代理的上下文困境它不像人类会先“找人问”先说个真实场景。一个项目里团队早就从 npm 迁到了 pnpm根目录也放着 pnpm-lock.yaml。但我让 AI 代理加个依赖时它依然在终端里敲npm install生成一个 package-lock.json把仓库搞得一团糟。你给我一个 Top 级模型它照样不知道这个项目实际用什么包管理器——因为它只会从你打开的文件里猜。人类开发者接手新仓库时会翻 README、看 CONTRIBUTING、问身边同事。AI 代理没这个能力它本质上是一个“拿着有限上下文、在 token 窗口里左顾右盼”的执行器。窗口里没有的信息它就只能用训练数据里的通用模式去猜猜出来的结果自然容易“偏科”用旧时代的工具链操作新时代的仓库或者把只适用于 A 模块的约定套到 B 模块上。这正是 AGENTS.md 要解决的问题。它不是写给人看的项目介绍而是专门写给 AI 代理看的一份“最小可执行上下文包”项目是什么、怎么跑、有哪些硬性约定、哪些绝对不能做。把它放在仓库根目录代理工作时第一时间就能读到而不是靠猜。1.2 从“给人类看的 README”到“给 Agent 的行为边界”很多人觉得 README 写详细点不就行了真不行。README 的默认读者是“人”它讲目标、讲用法、讲截图和徽章它不会约束行为。而 AGENTS.md 的读者是“程序”它需要的是指令式的、可验证的、贴着具体动作的规则。我给你打个比方README 是公司官网上的“关于我们”AGENTS.md 是给新入职员工发的“员工手册”——里面不光写你是做什么的还得写几点上下班、代码提交前要跑什么测试、哪些操作属于红线。“可执行”这个词我理解成三个层次指令能核验规则里写“用 pnpm 安装依赖”而不是“注意包管理器”AI 可以从 lockfile 推测也可以直接执行pnpm install验证。命令能直接跑AGENTS.md 里每条构建、测试、检查命令都是仓库真实支持的命令不是“理想中应该有的命令”。边界能直接判定哪些行为不被允许边界要足够清晰比如“不要修改 migrations 目录下的文件”AI 能对照路径直接判断。这套文件适合谁说实话任何把 AI 编程代理当日常生产力工具的人都需要。个人项目可能只需要根目录一份几十行的规则小团队可能需要在几个核心模块目录各放一份大型 monorepo 更是需要一套严格的分层体系。你把上下文交代得越清楚AI 代理的自由发挥空间就越小产出反而越稳定。2. 分层规则设计别把 AGENTS.md 写成“一本废纸”2.1 为什么不能只有一个 AGENTS.md最开始的直觉是在根目录放一个长长的 AGENTS.md把项目所有规则都写进去不就行了实际跑一阵你就会发现两个问题。第一规则文件越长AI 代理真正能吸收的信息密度反而越低它不会像人一样跳读所有内容都会占用上下文窗口真正关键的约定被淹没在细节里。第二不同目录、不同模块的技术栈和约束并不一样你在根规则里规定了一堆针对旧模块的细节新模块的代理可能完全用不上纯属噪声。分层的思路说穿了就是“关注点分离”。根目录文件只放全局原则子目录文件只放该目录范围内的特殊约定任务相关的临时规则单独用 context 文件携带。这就像法律体系里的上位法和下位法宪法管全局地方法规管当地办事细则管具体场景。每一层只管自己该管的事遇到问题时按优先级向上追溯。其实这个逻辑和写代码很像。你不会把整个系统的配置全都塞进一个 config 文件而是拆成不同层、不同作用域各有各的职责。AGENTS.md 是同一个道理它是“给 AI 代理看的配置”也应该分层、模块化、可组合。2.2 根目录 AGENTS.md项目宪法写什么根目录的 AGENTS.md 相当于宪法覆盖整个仓库。根据我自己的实践它应该包含这几块内容项目一句话目标让代理快速判断这个仓库是干什么的避免用无关领域的通用知识来回答。技术栈与版本事实语言、框架、依赖管理工具等必须是“事实”不是“偏好”。常用命令安装依赖、启动、测试、构建、Lint每个都要明确写命令必须是实际可运行的。目录结构地图只用三四行描述主干目录解释每一块是干什么的尤其要标注“低层代码”“生成代码”“不可修改区域”。工作流约定提交规范、分支命名、PR 检查项能写多具体就写多具体。红线与禁止事项比如不要动生成的代码、不要改数据库迁移文件、不要把密钥写进配置。我举个最简单的根目录模板# AGENTS.md ## 项目是什么 一个面向中小团队的项目管理系统后端服务提供任务、看板、报表 API。 ## 技术栈 - Python 3.11 FastAPI - PostgreSQL 15 - Redis 7 - 包管理器poetry ## 常用命令 - 安装依赖poetry install - 启动开发服务poetry run uvicorn app.main:app --reload - 运行测试poetry run pytest - 代码检查poetry run ruff check . ## 目录结构 - app/ 核心业务代码 - tests/ 测试 - infra/ Docker 与部署环境配置 - scripts/ 运维与数据脚本 ## 硬性约定 - 所有数据库 schema 变更必须新增迁移文件禁止修改历史迁移 - 模块之间只能通过 service 层调用禁止跨模块直接 import model - 所有外部 API 的响应必须包在统一结构里 ## 禁止事项 - 禁止把访问密钥、密码写入代码库哪怕注释里也不行 - 禁止直接修改 generated/ 目录下的文件这个文件写完后代理一进仓库就可以直接照着做事。你会发现它不需要反复去翻代码才敢动手而是先建立了一张“地图”再在限定范围内发挥。2.3 子目录 AGENTS.md把规则贴到代码说话的地方根目录规则解决的是“全局怎么做事”但很多模块有自己独特的玩法这时候就该用子目录级别的 AGENTS.md。比如一个前后端分离的仓库root 规则只讲整体工作流而backend/AGENTS.md可以规定 ORM 的使用方式、接口文档的生成方式frontend/AGENTS.md可以规定状态管理用哪套方案、样式用 Tailwind 还是 CSS Modules。子目录文件不需要重复根目录已有的内容它只需要写“与本目录相关的增量规则”。例如# frontend/AGENTS.md ## 本目录限定 - 前端构建使用 vite不要引入 webpack 相关配置 - 状态管理统一使用 zustand禁止使用 redux 新写代码 - 组件文件放在 src/components/ 下按功能分子目录 - 样式使用 Tailwind不需要写独立 css 文件除非是全局主题注意几个写子目录规则的原则第一不要写无关紧要的话子目录规则是用来补差异的第二如果某个规则在全仓库都成立就不要放到子目录文件里否则两个文件同时读进来代理还得判断哪个更权威第三子目录文件里的“禁止事项”如果要覆盖全局默认必须写明理由方便冲突仲裁。2.4 引用与 CONTEXT.md让上下文可以组合而不重复分层之后还有个问题有些背景知识很长又不想每次都写进 AGENTS.md。我的习惯是让 AGENTS.md 通过引用路径去关联其他文档。很多工具支持在 AGENTS.md 里用path/to/file的方式引用额外上下文代理读到时会主动加载。这样根目录文件保持在 50 行以内真正需要时再展开细节。常见的搭档是 CONTEXT.md我把它理解为“稳定的领域常识”。AGENTS.md 规定“怎么执行”CONTEXT.md 提供“背景依据”。比如项目里有一段历史逻辑为什么要这么设计、哪些模块是遗留代码、哪些依赖有特殊兼容需求写在这里面。AI 代理在改代码时如果只有规则没有背景经常会在看不懂的地方强行“重构”反而破坏了原有逻辑有了背景说明它才懂得敬畏那些看起来奇怪但背后有原因的代码。顺便说一句目前市面上主流 AI 编程工具对 AGENTS.md 的兼容性已经越来越统一Cursor、Claude Code 等都能自动读取。有些工具默认读 CLAUDE.md有些读 AGENTS.md稳妥的做法是让根目录 AGENTS.md 作为“主入口”需要时通过引用指向其他文件避免各个工具加载不到同一份上下文。3. 冲突检测多层规则交汇处如何裁决3.1 多层规则一定会冲突这不是异常而是常态只要规则一分层冲突就是迟早的事。原因很现实根规则可能是三个月前由架构负责人写定的子目录规则可能是上周由 feature 团队为了某个特殊需求加的两个人对“项目事实”的理解可能不一样甚至仓库本身已经变了规则还停留在旧版本。我见过最典型的冲突是根规则写“依赖统一用 poetry 管理”后来团队为兼容老环境改用 pip requirements.txt根规则没更新但某模块的 AGENTS.md 还写着“新增依赖时使用 poetry add”。AI 代理读到两个互相矛盾的指令通常不会停下来提问而是随机挑一个或者干脆根据上下文就近原则选一个——结果就乱了。所以我们真正要做的不是说“尽量避免冲突”而是建立一套“冲突发生时规则怎么办”的机制。这一步不做分层反而是帮倒忙。3.2 冲突类型速查表根据我实际遇到过的场景我把规则冲突分成四大类冲突类型含义例子影响优先级冲突不同层级对同一动作给出不同指令根规则允许 pytest子目录规则要求用 unittest代理行为不可预期事实冲突规则描述的“项目事实”与仓库实际不一致规则说用 pnpm仓库锁文件是 npm命令直接失败语义冲突同一规则在不同上下文里解读不同“快速修复”在不同模块含义不同代理执行方向跑偏结构冲突规则引用失效或层级关系混乱子规则引用了一个不存在的文件上下文加载失败优先级冲突相对容易解决靠的就是下文要说的裁决体系。事实冲突最隐蔽因为规则本身写得没错是仓库变了而规则没同步。这是我最推荐做“自动化检测”的地方。3.3 建立裁决体系先定优先级再规定冲突时的动作我自己的 AGENTS.md 里会显式写一段“冲突处理协议”就像一个断路开关。协议内容大致是## 冲突处理协议 - 规则优先级从高到低安全红线 根目录规则 子目录规则 临时任务上下文 - 当规则冲突时默认遵循更高优先级的规则 - 如果冲突涉及安全红线立即停止操作并向用户报告 - 如果两个同级规则冲突停止操作并列出冲突内容请求用户裁决这段协议本身也是规则代理遇到矛盾时就有了行动依据不是自己拍脑袋挑一条而是停下来报告。安全红线是一个特殊的存在比如“禁止删除数据库”“禁止把密钥写入代码”这种约束哪怕子目录规则里写了相反的内容也不能被覆盖。有人可能会问怎么让代理真的照做答案是把它放在 AGENTS.md 靠前的位置并且写得像“铁律”而不是“建议”。用户自己也可以在交互里强调“遇冲突先问我”双保险效果更好。3.4 事实冲突检测实操脚本检查包管理器、命令与引用事实冲突是最好自动化的。我写过一个简单的巡检脚本放在 CI 或 pre-commit 里每次规则文件变更时跑一下能挡掉大半问题。核心检查三点包管理器、常用命令、path 引用是否有效。#!/usr/bin/env bash # 1. 检查 AGENTS.md 中提到的包管理器与仓库实际是否存在冲突 ROOT_AGENTSAGENTS.md if grep -qiE npm (install|ci) $ROOT_AGENTS 2/dev/null; then if [ -f pnpm-lock.yaml ]; then echo [冲突] AGENTS.md 提到 npm但仓库使用 pnpm exit 1 fi fi # 2. 检查 AGENTS.md 中的 path 引用是否存在 refs$(grep -oE [A-Za-z0-9_./-] $ROOT_AGENTS 2/dev/null | tr -d ) for ref in $refs; do if [ ! -f $ref ] [ ! -d $ref ]; then echo [冲突] AGENTS.md 引用了不存在的路径: $ref exit 1 fi done # 3. 检查子目录 AGENTS.md 是否包含根规则的关键字段重复 find . -name AGENTS.md -not -path */node_modules/* | while read -r f; do if [ $f ! $ROOT_AGENTS ]; then if grep -qE 包管理器|pnpm install|poetry install $f; then echo [提醒] 子目录规则重复根规则: $f fi fi done这个脚本很土但胜在简单有效。更精细的做法是直接用 Node.js 脚本解析所有 AGENTS.md检查命令是否能在仓库的 lockfile 中找到对应证据或者用 LLM 做一次“规则一致性 review”。我自己在团队里是脚本初筛 人工 review 双轨走完全指望脚本也不现实——毕竟语义冲突、优先级冲突机器短时间还判断不了。4. 实操环节从零搭建一套带分层与冲突检测的 AGENTS.md4.1 第一步先盘点项目真相别凭记忆写规则动手写 AGENTS.md 之前我会先花十几分钟做一次“事实盘点”。找一张纸或一个临时文件把下面的问题列出来然后逐个去仓库里核实当前包管理器到底是谁看 lockfile 后缀pnpm-lock.yaml就是 pnpmyarn.lock是 yarnpackage-lock.json是 npm。测试命令是什么去看 package.json 的 scripts、Makefile、pytest.ini 等配置文件。构建命令是什么有没有独立的构建工具还是直接跑脚本目录结构是怎么分的不能只看顶层还要看两三层。哪些地方是“雷区”比如 migrations、generated、vendored 目录这些通常不应该被自动修改。团队有没有既有的编码规范比如 .editorconfig、ESLint 配置、.prettierrc这些都能提炼成规则。这个过程的核心原则是“以仓库事实为准不以预期为准”。如果文档说项目用 pnpm但 lockfile 明明是 npm以 lockfile 为准然后把规则写成正确的事实。4.2 第二步编写根目录 AGENTS.md把条目落实到动作完成盘点后我建议直接套用一节中的结构但要注意一个写作技巧每条规则都要能被一个理性执行者直接转化为操作。与其写“保证代码质量”不如写“新增函数都必须要写类型注解”与其写“注意性能”不如写“数据库查询必须通过 repository 层禁止循环内执行查询”。下面是一个可以改改就用的完整例子# AGENTS.md ## 项目是什么 在线文档协作平台的核心服务。提供文档 CRUD、实时协同编辑与权限管理。仓库同时包含后端 API 与前端 Web 应用。 ## 技术栈 - 后端Python 3.12 Django 5.0 - 前端Vue 3 TypeScript Vite - 数据库PostgreSQL 16ORM 使用 Django ORM - 包管理器后端 pipenv前端 pnpm ## 常用命令 - 启动后端pipenv run python manage.py runserver - 启动前端cd frontend pnpm dev - 后端测试pipenv run pytest - 前端测试cd frontend pnpm test - 全量检查pipenv run pre-commit run --all-files ## 目录结构 - backend/ Django 项目业务逻辑均在此 - frontend/ Vue 单页应用 - docs/ 架构文档与决策记录 - scripts/ 运维脚本不参与业务 ## 工作流 - 每项改动优先补测试测试不通过不要声称完成 - 提交信息遵循 conventional commits 规范 - 数据库 schema 变更必须生成 migration 文件 - 前端组件必须通过类型检查后才能合并 ## 安全红线 - 禁止提交任何形式的 API 密钥、token 到仓库 - 禁止修改历史 migration 文件 - 禁止在未确认数据量的情况下在生产环境执行批量 UPDATE 或 DELETE写完后自己照着规则走一遍流程从头 clone 仓库、按规则安装、启动、测试。任何一步不对说明规则写错了立刻改。4.3 第三步添加模块级 AGENTS.md补差异但不制造冲突根目录规则已经覆盖了全局接下来看哪些目录需要自己的 AGENTS.md。判断标准很简单这个目录下的工作方式是否明显区别于仓库其他地方比如前端目录用了完全不同的构建工具或者某个后端模块有独立的第三方集成。承接上面的例子我给frontend/AGENTS.md写的内容大概是# frontend/AGENTS.md ## 模块约定 - 组件统一使用 Vue 3 composition API禁止使用 options API 写新组件 - 状态管理使用 pinia禁止直接修改 props 传入的对象 - API 请求统一走 src/api/index.ts禁止在组件内直接 fetch - 样式使用 Tailwind不新增全局 css 文件除非有主题级变更 - 新增依赖前确认是否已有等价封装优先复用内部 utils写子目录规则时我会格外注意和根规则的关系。根规则使唤“后端用 pipenv、前端用 pnpm”子目录就不要刻意重复也不需要反着写。如果真出现子目录规则与根规则冲突的情况比如前端模块确实必须用 webpack 而不是 vite那就必须在子目录文件里显式写出“此规则覆盖根目录 vite 约定原因是公司统一构建平台要求 webpack”方便后续仲裁。4.4 第四步把冲突检测脚本纳入工作流规则文件不是写完就完事的它们和代码一样会腐化。我的做法是把第 3.4 节的检测脚本放进 pre-commit 或 CI 中只要 AGENTS.md 有变更就自动跑一遍。再加上一条人工 review 流程凡是修改 AGENTS.md 的 PR必须经过另一个人的 review重点就是看“新写的规则是否与既有规则冲突”“描述的仓库事实是否真实”。脚本只能查事实冲突和引用问题语义冲突和优先级冲突还得靠人来把关。但在实践中这套组合拳已经能挡住绝大多数问题。我见过太多仓库AGENTS.md 写了一堆结果实际命令根本跑不起来——代理照着执行直接报错然后它就“自由发挥”了这比没有规则还糟糕。脚本至少能保证“规则里写的都是真的”。4.5 第五步验收测试确认代理真的读到了上下文写完之后别急着庆祝先做个验收。我的做法是给代理派一个简单任务比如“在 frontend 新增一个按钮组件找出应该放到哪个目录”然后观察它的回答。如果它正确提到了 pinia、Tailwind、src/components 等规则里写明的约定说明它确实读到了。如果它还在用 options API 写组件、或者问我要组件放哪里那说明 AGENTS.md 根本没被加载或者写得不够前置。我还会做一次更狠的测试故意给它一个和规则冲突的指令比如“直接修改数据库迁移文件”。观察它是按规则拒绝还是照做。这是检验安全红线有没有真正起效的最直接方式。如果你的代理在老版本工具里连 AGENTS.md 都不读那就换个工具或者换一种能显式注入上下文的方式总之别硬扛。5. 常见问题与排查技巧实录5.1 AI 代理不读 AGENTS.md怎么办很多人会抱怨“我写了 AGENTS.md但代理不理我”。先排查三个原因文件名是不是放对位置了有的工具只认仓库根目录的 AGENTS.md子目录的不一定自动加载规则是不是写得太长太啰嗦几百行的规则真正执行时上下文窗口会被大量占用模型注意力容易涣散规则写得像文档而不是指令如果通篇是“项目是一个…”“我们重视…”代理不知道如何转化为动作。解决方式也很直接把规则压缩到核心把“关键指令”尽量放在文件前部用最明确的情态动词如“必须”“禁止”“只有在…才允许”在对话开头明确要求代理“先阅读 AGENTS.md 并列出规则”。最后这个做法在调试时特别有用能瞬间确认文件有没有被读取。5.2 规则文件越写越肥如何瘦身规则膨胀是自然发生的。每次踩坑就加一条几个月后文件充满各种边角料。我的经验是定期做一次“规则清理”删掉已经失效的命令、合并重复的约定、把低频的细节移到引用文档里。根目录 AGENTS.md 的目标是每次加载时能被代理完整读完区块尽量不要超过 60 行最好控制在 40 行内。做不到就要考虑分层把内容下沉到子目录或 CONTEXT.md。瘦身的原则是宁缺毋滥。一条能执行的规则胜过十条正确的废话。我在清理时还会问自己一个问题“这条规则如果被一个普通中级工程师看到他能直接执行吗”如果不能说明写得太抽象要么改为具体动作要么删掉。5.3 冲突已经发生谁来仲裁怎么止损规则冲突发现后千万不要修在 agent 的输出里而是要回到 AGENTS.md 源文件去修。我团队里的做法是设一个“规则 Owner”通常是技术负责人对规则改动有最终解释权。出现冲突时Owner 先看两个规则各自出现的背景再决定保留哪条、合并哪条、哪条该下沉到更低层级。每次裁决完在 AGENTS.md 里记一句“此规则覆盖 xxx原因是 yyy”相当于给后来的维护者留了一份仲裁记录。如果冲突发生在代理执行过程中代理已经停下来报告那就按“从高优先级规则”执行。如果代理没有报告而是擅自选了某条规则执行了错误操作那就需要回到源头加强冲突处理协议并确保代理在每次改动前都会读取规则。很多工具支持在对话上下文中加入“全局指令”把“冲突即停下”这条规则通过全局指令再注入一次双通道保障。5.4 多工具时代AGENTS.md 兼容性如何处理Cursor、Claude Code、Codex 等工具对 AGENTS.md 的支持细节并不完全一致。有的工具会自动加载根目录文件有的需要用户手动指定有的读AGENTS.md有的读CLAUDE.md。我的兼容策略是以AGENTS.md为主文件如果某个工具只读CLAUDE.md就在根目录放一个软链接或者内容一致的CLAUDE.md维护时同步改两份。本质上它们都是纯文本 Markdown维护成本不高。另外要注意不同工具对“引用上下文”的支持程度不同path这种语法不是所有工具都认。如果某个工具读不到引用文件就把关键内容直接写在根文件里避免代理因为缺上下文而瞎猜。多工具兼容没有银弹我的原则就一条让任何工具读同一份文件都能得到一样的核心结论。最后分享一个实在的小技巧我个人在维护 AGENTS.md 这套体系时最大的体会不是“AI 编程代理变聪明了”而是团队真的把项目的约定重新想清楚了一遍。很多约定过去只活在口头或 PR review 的肌肉记忆里散落在不同人的脑子里现在被显式写下来、排好优先级、配上巡检脚本整个仓库的“可被理解程度”都上了一个台阶。如果你准备实践我建议从最小的一步开始先只写根目录一份 30 行的 AGENTS.md确认代理能按它执行再慢慢加模块级规则最后再上冲突检测脚本。别一开始就铺开否则你自己都会被一堆规则之间的相互矛盾绕晕。每隔两周左右跑一次检测脚本把跟仓库事实脱节的规则标红修正这个习惯坚持下来你会明显感觉到 AI 编程代理的“靠谱概率”提高了不少。