可能很多人刚接触 AI 编程助手时都有过类似的体验装好 Clich建好项目激动地输入第一句需求然后看着它一本正经地写出一个完全不符合你项目规范的代码。不是它不聪明而是它对“这个项目怎么组织、有哪些硬性约定、哪些代码不能碰”一无所知。AGENTS.md 就是用来解决这个问题的。简单说AGENTS.md 是放在项目根目录下的一个规则文件专门给 AI 编程代理Agent看的项目说明书。它和 README 最大的区别是受众不同README 是给人看的项目介绍AGENTS.md 是给 AI 看的“做事规矩”。我在几个不同类型的项目里折腾了一段时间从被 AI 的无知气到摔键盘到慢慢摸清怎么用一份规则文件让它变成“懂规矩的老员工”中间的坑和心得都在这篇里了。1. 从“看不懂”到“按规则办事”AGENTS.md 要解决的真实痛点1.1 AI 编程助手最让人抓狂的几个瞬间先说说我一开始的悲惨经历。当时让 AI 在一个 Python 项目里加一个 API 接口它非常守信用地把文件写对了但那边的项目结构是src/包 tests/目录分离测试有自己的一套 fixture 写法代码风格用的是 Black 格式化加 isort 排序类型标注强制开启。AI 一概不管直接在scripts/下面新建了一个模块测试文件也按它自己习惯的 pytest 裸写法来连__init__.py都不加。代码能跑但跟整个项目格格不入Review 的时候同事直接问这是谁写的。后来我在 Cursor 里试过一个前端项目让它改一个组件它把组件拆成了三个文件引入了项目里根本没有的依赖还顺手改了一个公共工具函数。最要命的是它改公共函数的时候完全没意识到这个函数被十几个地方引用。AI 不是坏是真的“两眼一抹黑”。这些场景归结起来就一句话AI 编程助手缺少项目的上下文约定。它懂的是通用编程知识不是你项目的具体规矩。AGENTS.md 要填的正是这个 gap。1.2 AGENTS.md 和 README 的分工一个给人一个给 AI很多团队在 README 里写了一大堆开发规范、目录说明、命令清单然后发现 AI 助手根本不看。不是工具没有读取能力而是 README 的信息组织方式不适合 AI 决策。README 往往用叙述性语言夹杂背景故事、架构演进、致谢信息AI 在长篇里提取“当前这个任务要遵守什么”的效率很低。AGENTS.md 从一开始就是给 AI 写的规定所以我个人的经验是它应该更像一份操作手册而不是散文。开头一句话说明项目是什么然后直接进入规则列表、命令清单、目录边界、禁止事项。项目里同时存在 README 和 AGENTS.md 是很正常的一个负责介绍项目背景一个负责约束 AI 行为甚至 AGENTS.md 里可以引用 README 说“详细架构见 README”但必须告诉自己该遵守什么。1.3 一条规则文件的边界它能管住什么管不住什么我踩过的最大的一个坑是以为 AGENTS.md 是万能的。写完一份自认为详尽无比的规则文件然后指望 AI 从今往后不犯任何错误。结果发现完全不是这么回事。AGENTS.md 能管住的是项目里用哪些语言和框架、代码放在哪个目录、命名规范是什么、哪些命令是验证手段、哪些文件绝对不能动、任务的常规完成路径是什么、测试和 Lint 必须过。这些都是“执行过程”层面的约束。它管不住的是复杂的架构权衡、需要多人语境才能理解的隐性知识、产品层面的判断。AI 看到规则也不代表它就能做架构决策。我对它的定位是“执行约束器”而不是“架构师”。所以写规则的时候要反复问自己一个问题这条规则是为了让 AI 在做事时不跑偏还是为了让智者来拍板如果是后者别往 AGENTS.md 里写。2. 动手之前先理解 AI 读取规则文件的底层机制2.1 三种上下文加载方式全量读取、自动检索、手动引用用 AGENTS.md 之前搞懂 AI 工具怎么读这个文件直接决定你怎么写。以我之前用过的几类工具举例全量注入型一些 Agent 工具在启动时把项目根目录的 AGENTS.md 读入上下文。特点是简单粗暴规则文件会一直存在于对话里但会占用上下文窗口。自动检索型只把 AGENTS.md 作为索引AI 根据任务内容判断要不要搜索具体规则文件。优点是省上下文缺点是非核心规则可能被忽略。显式引用型AI 不主动读文件但会在检测到命令或匹配前缀时引用指定文件相当于规则文件的后备。这三种机制的差异直接决定了篇幅控制策略。如果是全量注入一份 3000 行的 AGENTS.md 会挤掉大量有效代码上下文AI 的“注意力”会被稀释如果是检索型规则文件就需要写得结构清晰、标题明确方便命中检索。2.2 为什么 AI 读了规则但经常“视而不见”很多人都有过“我明明写在 AGENTS.md 里了它为什么不做”的困惑。我的观察是AI 的指令遵循存在一个优先级链系统提示词 当前用户消息 外部文件。AGENTS.md 属于外部文件优先级天然排在用户直接指令之后。这很好理解如果我的对话里说了“临时改成 Python 脚本实现”那 AGENTS.md 里“本项目使用 TypeScript”就得让位。更关键的是AI 的注意力机制决定了它容易记住规则文件的头尾部分中段容易被忽略。我在实践中发现最重要的规则放在文件头部前 15 行内能得到最高的遵循率放在中间区域且长句冗长得像段落的话基本等于没写。还有一个坑是“默认思维”AI 的通用训练数据里有海量“自己的一套做事方式”。如果不明确说“本项目不用这种方式”它有很大概率按默认习惯走下去。所以一致的教训是规定“应该这样做”很好写出“不要那样做”“不要做什么”同样重要。2.3 我见过最合理的篇幅命令和边界用列表解释留给文档关于篇幅网上众说纷纭。我的经验法则有点像做菜的佐料太少了没味道太多了盖住主料。我见过一份控制得非常好的 AGENTS.md全篇只有 80 行分六个区域全是列表和命令。它成功的原因在于几乎没有一句废话每条规则都可以被 AI 机械执行。它里面写的是“运行npm run test验证”“禁止修改migrations/目录下已提交的文件”“在src/api/下新建文件”而不是“保持代码质量的持续提升确保架构的演进性”。因为 AI 比人类员工更需要“可判定性”。什么叫可判定能通过字符串匹配验证对错。比如“文件必须放在src/components/base/下”就比“放一个合适的位置”可判定得多。所以我建议优先完成“可判定规则”把需要解释的东西放 README 或注释里。3. 结构化写规则我验证过的分层格式3.1 顶部区域身份声明 一句话定位 关键命令AI 读规则文件很像一个人进新公司第一天他首先要明白三件事我在哪这里干嘛的怎么验证我干得对不对所以 AGENTS.md 的开头我建议就三块内容项目是什么一句话别超过 25 字核心技术栈语言、框架、包管理器三个最重要的命令安装、启动、测试这一部分的意义在于让 AI 建立一个基线认识。之后所有行为都基于这个基线展开。命令尤其重要因为后面所有“验证动作”都要用命令来闭环。如果你不写npm run lintAI 就不知道自己写出来的代码是否满足格式要求。3.2 工程约定层目录结构、命名规范、依赖规则这部分是整份文件的硬核每一条都要能直接约束 AI 的行为。我按优先级列举一下目录结构明确哪些目录是源码区、哪些是测试区、哪些是构建产物。如果项目里有几个目录必须被当作“黑盒”务必写清楚。命名规范文件命名、变量命名、组件命名甚至 CSS 类名的约定全部写出来。依赖规则允许使用哪些依赖、禁止引入什么、依赖加在哪类清单里dependenciesvsdevDependencies。提交约定是否要求 Conventional Commits 格式分支命名规则。我在一个 Monorepo 项目里还加了一条硬性规则新增代码必须落在packages/下对应包内禁止往apps/的根目录直接塞文件。这样一来 AI 再也没试过把两个包的代码混在一起。3.3 行为约束层禁止列表比允许列表更关键人的注意力是有限的AI 也是。与其列出 30 条“尽量做什么”不如列出 10 条“绝对不要做什么”。禁止类语句对 AI 的约束力更强因为它们制造了冲突场景——如果一个行为在“禁止”里AI 在规划时会额外考虑这个 Conflict。我维护了一个“禁止列表”模板你可以直接参考改造禁止修改generated/目录下的任何文件如需改动必须通过代码生成器重新生成。禁止引入新的全局状态管理库现有方案已经够用。禁止在业务代码中使用any类型特殊情况必须经团队约定注释确认。禁止格式化整个项目只格式化本次修改涉及的文件。禁止在提交信息中使用不规范的动词如 fixed、change 之类的非约定词。别小看这些限制每条都是从真实翻车事件里提炼出来的。之前有一次 AI 为了统一代码风格把项目里几万个文件的格式全跑了一遍 Prettier导致 PR 变更量巨大。加了“禁止格式化整个项目”这条之后就再没发生过。3.4 任务类型工作流按需触发免得所有任务都走同一条路项目里的任务大体可以分成几类修 bug、加功能、性能优化、升级依赖。不同任务的最优路径完全不同。把这种区分写进 AGENTS.mdAI 的表现明显上一个档次。我习惯用“If Then”句式描述工作流如果是修复 bug先写一个失败的测试再修复代码最后验证测试通过如果是添加 API 接口先看docs/api.md确认接口规范再写实现然后补充测试如果是性能优化先用 profiler 跑出基线数据再修改最后对比结果如果是依赖升级先读 changelog再改 lock 文件跑全量测试。这套设计的本质是把团队在日常协作中积累的显式流程搬给 AI让它不需要重新发明路径。每一条工作流本质上都是你给 AI 预设的“最优路径”。3.5 用表格、列表和标记语法提升 AI 解析效率我试过几种写法之后发现结构化的表格和列表比大段自然语言更利于 AI 提取关键信息。比如技术栈表格场景方案备注前端框架React 18 Next.js 14保持 App Router 结构样式方案Tailwind CSS CSS Modules全局样式少用状态管理Zustand禁止 Redux测试框架Vitest Testing Library不用 Jest这类表格的好处是信息密度高AI 可以用较短时间完成“匹配当前场景”的操作。如果你还需要在规则文件中挂接更多外部文档可以用docs/path/to/file.md格式显式声明让它去检索。4. 从真实错误中反推规则维护 AGENTS.md 的正确姿势4.1 建立错误日志每一次 AI 犯错都喂给规则AGENTS.md 是一份活的文件不是写完就完的。我的工作是建立一个流程AI 犯错 → 记录 → 分析根因 → 提炼规则 → 追加到 AGENTS.md。这个循环看着简单但很多人没坚持下来因为平时需求紧张AI 犯个错改过来就算了。我的建议是每周花十分钟专门看当前项目的规则文件问两个问题这周的一周里 AI 犯过同样的错误超过一次吗这个错误是因为规则缺失还是规则写了它没看到如果是规则缺失立刻补如果是写了没看到就考虑挪到更显眼的区块或者检查是否因为篇幅太长导致注意力分散。我就是靠这个节奏把规则的“命中率”一点点从 60% 拉到了接近 90%。4.2 把抽象约定翻译成可判定的操作指令有一次我在规则里写了“保持组件设计的可扩展性”。回头看这句话基本等于没说AI 完全不知道怎样算可扩展于是它基于自己训练数据里的理解去发挥了。后来我把这条改成了新增组件时必须拆分出presentation和logic两个层次组件接收的 props 如果超过 5 个必须拆分。这下它立刻能执行了。抽象约定只能靠人靠团队达成共识对 AI 必须拆成具体操作。我总结了一个句式“当遇到 X 情况时必须执行 Y当发现 Z 条件时禁止 W。”这种句式很高效。比如“当修改公共 API 时必须同步更新类型定义和所有调用方当发现新增依赖时禁止直接安装必须征询用户”。4.3 版本化维护规则文件本身也要走提交审查在项目里AGENTS.md 和其他代码一样需要版本控制而且改动建议应该和普通代码一起 Review。不要让它变成一个“霸王条款”文件谁想加什么就加什么。我知道有些团队最开始 AGENTS.md 是某个成员自己写的后来变成每个人往里丢一句最终文件膨胀到了几百行一半的规则互相矛盾。我的实践经验是每次改动最好附上一条理由比如“新增禁止修改 generated 目录规则因为 AI 曾重写该目录导致构建失败”。这样后续维护时如果某条规则看起来奇怪可以通过 git blame 找到背景。作为规则的控制者我只保留能证据的规则不是“感觉有用的规则”。5. 容易翻车的细节我在实践中踩过的坑5.1 规则与系统提示词打架用户消息优先级更高AGENTS.md 写多了AI 是不会主动违背当时用户明确指定的指令的。但有时候我在对话里说“你先帮我看看整体方案”它可能基于 AGENTS.md 里的“固定顺序”跳过某些步骤因为那个任务是模糊的。这不算规则失效但会给人一种“不听话”的感觉。解决办法是在 AGENTS.md 里写一条“当用户提出探索性任务或方案咨询时优先遵循用户的探索意图暂缓转入执行标准流程”。这可能挺反直觉但确实可以减少很多摩擦。5.2 过度约束导致 AI 变得低效我曾经试图把每一个步骤都写进规则比如“必须用 X 命令初始化然后执行 Y再执行 Z”。结果 AI 每一步都在机械照做遇到应该自己判断的情况也变得不会变通了。这就像给员工写了 200 页操作手册严重依赖流程反而无法灵活应对小变化。我的边界感关键路径、验证方式、安全底线要硬约束实现细节、代码风格、顺序安排保持软约束。如果规则已经导致它绕远路完成任务就说明约束太细了。5.3 绝对路径和模糊隐喻AI 最容易误解的两种表达写路径时我用的是绝对路径风格相对于项目根目录比如src/components/Button.tsx而不是components 下的 Button 文件因为后者它可能去猜。类似地“不要动下层目录”这种表述就太模糊了必须指名道姓列出目录名。用隐喻更要小心。我在早期规则里写过“不要让面条式代码蔓延”这句话我自己明白但 AI 完全懵。后来改成“单个函数超过 80 行必须拆分函数内分支嵌套超过 3 层必须预警”它才找到执行依据。5.4 多项目协同时的规则冲突在 Monorepo 里不同子项目可能有完全不同的约定。如果根目录一份 AGENTS.md 想管所有包必然鱼龙混杂。我采用的办法是根目录只写公共规则比如构建命令、CI 信息、提交规范每个子包的目录下单独放自己那份 AGENTS.md用packages/web/AGENTS.md这种形式让 AI 优先读取对应包的规则。统一不了的部分不要硬统一各包各写各的反而清晰。6. 大型项目的进阶规则文件的组织架构6.1 分散式 vs 集中式按项目规模选型对于小型项目一份根目录 AGENTS.md 够用。但对于多人维护的 Monorepo 或者大型项目我更推荐分散式根目录写公共部分子目录/子包内放局部规则。分散式的典型结构是这样的AGENTS.md apps/web/AGENTS.md apps/api/AGENTS.md packages/ui/AGENTS.md docs/AGENTS.md根目录说明“先看对应的子目录规则”子规则聚焦本目录的技术选型、命名规范和禁止事项。6.2 用索引文件代替全量粘贴随着规则越来越多上下文窗口的压力也会突显。我现在习惯用一个更省上下文的做法根目录 AGENTS.md 只写核心十几条的高优先级规则以及一个目录索引比如- 前端应用规则apps/web/AGENTS.md - API 服务规则apps/api/AGENTS.md - 共享组件规则packages/ui/AGENTS.md用引用替代全量内容。AI 真正落入相应区域时再去读取对应子规则既不影响篇幅也保留了各目录的自洽性。6.3 让规则文件“活起来”与模板、Hook 联动如果你像我一样用多个 AI 工具比如 Clich 命令行工具、Cursor 编辑器里的 Copilot就要注意不同工具的上下文机制不同。我的做法是做一个项目脚手架模板把 AGENTS.md 作为初始化模板的一部分新项目启动就自动带上基础规则从源头保证一致性。再进阶一点可以在 Git Hook 里加一层检查比如提交前自动跑 lint 和格式校验这样相当于给 AI 加的规则加了一道硬性网关。AI 写过不了 lint 的代码也没关系Hook 拦截下来它再去改反复几次就记住了。7. 根据我这段时间的实际使用AGENTS.md 最重要的一条心得如果只让我留一条建议就是把它当成一个跨任务的项目记忆而不是一份写完就结束的文档。规则可以随时追加但每一条都要有真实项目场景支撑。我现在新项目的第一天就会花十五分钟把 AGENTS.md 填起来项目定位、技术栈、目录骨架、命令、禁止事项。第二天开始在真实任务里推进每遇到一次 AI 的“无礼冒犯”就回看规则补一条。两周之后这个文件就成了这个项目的专属行为准则比任何通用提示词都有效。规则文件对 AI 编程助手的价值不是让它变强而是让它的“常识”与“项目实际情况”对齐。对我而言这就是一份值得长期投入的资产。同一份代码库有规则和没规则的 AI 助手写出来的东西差着半个工程师的段位。如果你现在还在跟 AI 助手废话“你别乱改公共函数”不如花点时间把这句话写进 AGENTS.md 的禁止列表。剩下的它会替你记得而且记得比人靠谱。