前阵子我在代码评审里看到一份AI生成的PR功能实现完全正确测试也过了但代码风格跟项目里沉淀了快十年的惯例差了十万八千里变量命名用的是缩写错误处理直接吞掉异常模块划分把几个内聚的类硬拆成了网状依赖。你提醒它它说好的我改下一次换个任务它又犯。后来我把项目的AGENTS.md补完整这类问题才真正开始减少。这一章的话题就是AGENTS.md与规则文件设计。它不是某个工具的插件也不是花架子而是AI编程协作时代一份面向AI agent的项目说明书和约束契约。如果你正在用Claude Code、Codex、Cursor这类AI编程工具或者你的团队正在摸索怎么让AI稳定地产出符合项目规范的代码这一章的内容应该能直接帮到你。1. 为什么AI协作时代需要一份专门的规则文件1.1 AI agent不是没有能力而是缺少项目上下文大模型本身的知识储备非常强你问它怎么写一个Python装饰器、怎么调React Hooks它能给你讲得头头是道。但真正进入一个具体项目后它面对的最大问题是它对你的项目一无所知。它不知道你的项目是单体应用还是微服务不知道src/utils/里那些工具函数的命名约定不知道你们规定所有数据库操作必须走仓储层也不知道测试文件应该放在tests/目录而不是和源码混在一起。这些信息如果你不主动告诉它它就只能靠猜。而猜的结果就是大方向对细节全是项目语境缺失导致的偏差。传统做法是在每次对话里反复交代这些上下文但人的记忆和耐心都是有限的你少说一次它就发散一次。AGENTS.md的作用就是把这些项目里散落的规则和隐性知识沉淀成一个稳定的文件让AI agent在开始工作前就自动读取相当于给每个进项目的人发了一份员工手册。1.2 传统README在AI agent面前的三个短板有人可能会问很多项目已经有README了为什么还要单独搞一个AGENTS.md我自己的体会是README和AGENTS.md在本质上是两种不同的文档它们在AI agent面前的表现差距非常明显。第一个短板是语气问题。README是写给人类看的大门招牌它的基调是介绍和展示这个项目是干什么的、有哪些功能、怎么安装、怎么启动。它默认读者有判断力不需要命令式地告诉读者禁止做什么。但AI agent不一样它需要的是明确指令。它不会像人一样从字里行间体会这里最好不要那样写它只会执行字面意思。第二个短板是粒度问题。README为了保持可读性通常会省略掉大量细节命名规范、目录结构的约定原因、哪些代码是历史包袱不能碰、哪些操作有先后顺序。这些细节恰恰是AI生成代码时最容易出错的地方。没有这些细节AI产出的代码就像一个人只知道公司业务方向但完全不了解内部规章的新员工。第三个短板是可执行性问题。README里的内容大多是描述性的没有给AI一个明确的行动边界比如不要做什么什么时候必须做什么怎么验证做对了。而AGENTS.md里最有价值的部分恰恰就是那些可以转化成具体动作的规则。不用代码尽量保持整洁这种话要用单个函数不超过80行超过80行必须拆分并给出拆分理由这种可以验证的指令。1.3 生态现状AGENTS.md正在成为事实标准很多工具其实早就意识到这个问题了。Claude Code用的是CLAUDE.mdOpenAI Codex支持AGENTS.mdCursor有自己的.cursor/rules目录GitHub也在推动AGENTS.md作为仓库级的AI协作配置文件。虽然文件名和读取优先级略有差异但核心思路是一致的在仓库里放一个纯文本Markdown文件AI agent在启动时自动加载它把文件内容当作处理任务的先验知识。这个生态正在快速收敛到AGENTS.md这个命名上。我的建议是不管你现在主力用哪个工具尽量把规则文件命名为AGENTS.md放在仓库根目录因为它是目前跨工具兼容性最好的选择。即使你的主力工具读的是自己的专属文件也可以做一个很薄的小工具或脚本在提交前把AGENTS.md同步到对应的CLAUDE.md或.cursor/rules里保证规则只有一个源头。2. 规则文件设计的第一性原理信噪比与可执行性2.1 规则的分层全局约束、项目知识、任务指令我第一次写AGENTS.md的时候恨不得把项目里所有信息都塞进去结果文件膨胀到几百行效果反而很差。后来我把规则重新梳理了一遍发现规则其实天然分成三个层次揉在一起是灾难分开写才清晰。第一层是全局约束。这一层写的是不管接什么任务都必须遵守的东西比如不得直接修改生产环境的数据库所有对外接口必须做参数校验提交代码前必须运行现有的单元测试。全局约束的特点是稳定、通用不随具体功能变化。因为它们要一直生效所以通常会放在AGENTS.md的靠前位置。第二层是项目知识。这一层写的是项目的地图和规矩技术栈是什么、核心目录的职责划分、数据库迁移的流程、依赖管理用的是npm还是pnpm、日志规范是什么。这些内容是AI在完成任务时需要随时查阅的背景信息它决定了AI生成方案时往哪个方向靠。第三层是任务指令。这一层最容易被忽略但也往往是规则文件里最有价值的部分。它写的是当AI被要求做某类任务时应该采用的具体流程。比如处理bug时先复现再修复修复后要写一条对应的回归测试新增API时必须同步修改OpenAPI文档前端改动涉及视觉样式时必须截图对比设计稿。任务指令把AI的行为从自由发挥变成了按规定动作执行。这三层不是并列关系而是从通用到具体、从稳定到变化的递进。维护的时候也要区分对待全局约束和项目知识尽量少改动任务指令则可以根据复盘结果不断调整。2.2 高信噪比表达什么该写、什么不该写AGENTS.md不是技术博客不是README扩充版更不是给AI的表白信。它的价值密度决定它在AI上下文窗口里的优先级。AI编程工具通常会把项目里的规则文件连同用户指令一起放进上下文如果你的文件里一半是废话AI在有限的上下文窗口里就会用更多的注意力处理无效信息真正关键的规则反而可能被忽略。那什么是不该写的空泛的好话不写比如提供高质量的代码追求卓越的用户体验这些话没有操作意义。项目发展史的煽情段落不写比如这个项目始于2018年的一次头脑风暴这类内容对AI完成任务没有任何帮助。AI能推理出来的常识不写比如不要删除数据库中的用户数据这类属于基础安全常识写了反而稀释了文件里真正针对项目定制的规则。该写的是什么呢精确的路径和文件命名约定、具体的命令和脚本、可以直接copy的代码模板、明确禁止的操作清单以及每条禁止事项背后的简短理由。比如禁止在组件内部直接调用API请求函数请统一使用src/api/下的封装层原因是方便统一处理token刷新和错误上报。给理由不是为了展示文采而是让AI在遇到规则没覆盖到的边缘情况时能根据理由做出符合意图的推导。2.3 让规则可执行而不是可读判断一条规则写得好不好有一个很简单的标准把规则读给一个刚入职的工程师听他能不能不追问就按照规则去执行如果不能说明规则还是可读的而不是可执行的。举个例子注意代码性能是一条典型的不可执行规则。改成所有涉及列表渲染的组件必须使用React.memo或者useMemo性能关键路径需要添加注释说明为什么这个优化是必要的这就是可执行的。又比如遵循项目现有风格也不可执行改成导入语句按标准库、第三方库、内部模块分组排序每组之间加空行具体参照src/utils/format.ts顶部就可执行了。一个让规则变可执行的小技巧是给每条规则配一个验证动作。如果规则说新增依赖必须由项目负责人确认那就同时写上在PR描述中注明新增依赖的名称、用途和版本号并在docs/dependencies.md中登记。这样AI可以明确知道做完之后应该检查什么也方便你在评审时核对。规则一旦能被验证被遵守的概率就会大幅提升。3. 从零搭建一份AGENTS.md完整骨架与逐段拆解3.1 文件头项目定位、职责边界和语言约定文件头不需要很长两到四句话把项目是什么说清楚就够了。但有一个很关键的细节明确告诉AI这个文件自身的性质。我会在开头写一句本文件是AI agent在参与本项目时的最高规则所有任务执行前必须先阅读并遵循本文件。这句话看起来多余实际上能显著提升规则的约束力因为很多AI工具会把用户指令的优先级排在项目规则之前如果没有明确的最高规则声明用户一句别管那么多直接写就可能让规则全面失效。还需要约定的是沟通语言。如果你的团队成员和AI交互时主要用中文就在文件头写明所有与用户交互时使用中文代码注释、命名和提交信息使用英文。这个约定能避免AI一会儿中文一会儿英文的混乱状态。我见过不少团队因为漏了这条生成出来的代码注释中英混杂提交信息更是看心情换语言后期维护非常痛苦。3.2 技术栈与关键架构指引接下来的章节要写项目地图。首先是技术栈清单包括语言的版本、框架、核心依赖和构建工具。不需要列出全部依赖但要列出对编码方式影响最大的那几项比如TypeScript 5.xReact 18Vitepnpm。版本信息尽量写主版本避免AI按过时的API写代码。然后是目录结构的职责说明。不要贴整个目录树而是只标注那些有特殊规则的目录。比如src/api/所有后端接口调用的唯一入口禁止在组件内直接使用fetch。src/store/全局状态管理禁止在非行动层直接修改store状态。migrations/数据库迁移脚本目录只允许通过CLI工具生成。最后是核心流程的说明。比如数据的流向UI事件触发actionaction调用api层api层返回后通过reducer更新store组件订阅store渲染。这段描述可以用一个简洁的流程图表达但在我使用的工具生态里纯文本的分步描述往往比流程图更稳定因为AI解析文本指令比解析图表更可靠。所以建议至少保留一份纯文本版本。3.3 编码规范与红线事项这一节是避坑的重头戏也是你和AI之间最需要约法三章的地方。不要照抄网上的通用编码规范要写那些你在这个项目里真实遇到过、真实踩过坑的规则。比如禁止在src/utils/中引入任何框架相关代码该目录保持纯函数。所有新增的表单校验必须使用zod禁止手写if-else校验。错误消息不允许直接展示给用户英文原文必须走src/i18n/的翻译函数。红线事项建议单列一个小节用禁止开头每一条都加上后果说明。为什么加后果说明因为只写禁止xxx就像交通标志只有禁令没有罚款AI无法判断遵守与否的优先级。加上后果说明后比如禁止在生产代码中使用console.log会导致日志系统被刷屏如需日志请使用src/utils/logger.tsAI在生成代码时就会自己权衡而不是机械地在你移除console.log之后又偷偷加回来。3.4 工作流与验收标准最后一块内容是活的流程也就是AI在接到任务后应该走的完整步骤。举个例子如果你要求AI完成一个功能开发流程应该写成先阅读docs/下相关的设计文档再浏览src/中关联模块的现有代码然后基于现有代码风格实现功能补充测试用例最后运行pnpm test和pnpm lint并修复全部问题。验收标准这一节同样重要它决定了AI怎样才算做完。要明确写出来代码必须通过类型检查、Lint和全部单测。新功能对应的测试覆盖率不得低于80%。如果改动影响了视觉布局需要在PR附上改动前后的截图。PR描述必须关联对应的issue编号。这些条目看起来像是在约束一个人类开发者的行为但实际上把它们写清楚之后AI的产出质量会得到一个可预期的下限。AI是很吃清单的你给它一个明确的检查清单它就会逐项去满足你什么都不写它就会认为能跑就行。4. 实战中容易踩的坑写了但AI不听的五个原因4.1 语义模糊导致的暴力遵守规则写得模糊AI就会按自己的理解去严格执行。最典型的是那句保持代码简洁。什么叫简洁不同模型、不同语境下的理解天差地别。有的会把嵌套循环简洁成一行filter有的会为了简洁把条件判断简化得完全不可读。当规则语义模糊而AI又必须遵守时它就会选择一个自己认为最符合标准的解读结果往往是灾难。解决办法很直接把形容词改成可量化的指标。保持代码简洁改成单个函数体不超过40行嵌套深度不超过3层超过的必须拆分或者用早返回简化。虽然这种量化指标多少有点武断但它给了AI一个可判定的边界减少了解读空间。如果你觉得某些指标定得过死可以加上一句如为保持可读性需要突破上述限制请在代码注释中说明原因既保留灵活性又不至于让规则变成空文。4.2 上下文超载导致的选择性失明AGENTS.md写得越长AI对其中每条规则的注意力就越分散。根据我的统计超过300行的规则文件被AI完整引用的概率断崖式下降。原因很简单现代AI工具的上下文窗口虽然越来越大但模型对上下文的注意力并不是均匀分布的中间部分的内容更容易被遗忘。当规则文件长到一定规模AI通常会重点照顾开头和靠近当前任务的部分中间的规则就变成了可有可无的背景噪音。解决这个问题有三个办法。第一个是精简把规则文件压缩到100到200行之内太细碎的规则放到二级文档里比如docs/agents/coding-style.md在AGENTS.md中只写编码规范请参阅docs/agents/coding-style.md并严格遵守其中的命名、目录和代码结构要求。第二个是重排把最重要的规则放在文件最前面次要的依次往后排。第三个是拆分如果项目确实复杂就按子目录拆分规则比如在src/api/AGENTS.md中写这个模块的特殊约定根目录的AGENTS.md只写全局规则。4.3 规则冲突与优先级缺失当一个项目里同时存在多个规则文件时冲突几乎是必然的。比如根目录的AGENTS.md说所有API接口必须返回统一的ApiResponse结构但某个子模块的AGENTS.md又说本模块负责对外回调接口按第三方协议格式返回两条规则在AI眼里就产生了矛盾。这时候AI的选择通常很随机可能这次听子模块的下次又听根目录的。要避免这种冲突首要是给规则分级。在AGENTS.md里明确写清楚根目录的AGENTS.md优先于所有子目录规则子目录规则只对当前目录及以下生效当子目录规则与根目录规则冲突时以根目录规则为准除非子目录规则中明确标注了此条为对根目录规则的专项豁免。有了这个优先级声明AI在遇到矛盾时就有了判断的依据而不是靠猜。4.4 更新滞后规则成了历史文档AGENTS.md有一个很容易被忽视的问题它会贬值。项目的技术栈、目录结构、编码习惯在持续演进但AGENTS.md只要没人主动更新就会停在某个历史时间点。AI按一份过时的规则文件工作产出不仅不能匹配现状还会比没有规则更糟因为规则让它对已经废弃的写法产生了一种错误的信心。我的习惯是每次对规则文件进行大改时顺手把改动记录提交到Git里并在PR描述里说明AGENTS.md更新原因。每隔一两个月做一次整体巡检对照现在的代码结构、目录、命名习惯把已经不符合现实的部分改掉。不要小看这个动作一份长期有效的规则文件一定是一份被持续维护的文件它和技术文档一样需要有人对它负责。4.5 把README直接改名为AGENTS.md这个坑看起来低级但我真的见过不止一次。有人图省事觉得README反正写了不少项目信息改个名就能当规则文件用。结果AI确实读取了但产出的代码该乱的还是乱因为README里根本没有约束性的内容全是背景介绍和使用指南。AI读完之后只知道这是个电商平台的后端服务但完全不知道新增接口时必须把参数校验放在service层这种关键约束。AGENTS.md不能从README改个名得来它是独立设计、按需求倒推出来的产物。一份好的AGENTS.md应该是你站在AI的角度问自己如果我现在加入这个项目我需要知道哪些规则才能在不动别人代码的前提下做出符合项目惯例的修改想清楚这个问题你就会明白README和AGENTS.md之间的鸿沟有多大。4.6 一次规则没生效的完整排查过程如果你的AGENTS.md明明写了规则AI却完全无视先别急着骂工具按下面这个顺序排查。第一步确认文件位置和命名。不同工具对规则文件的读取路径不一样有的读根目录的AGENTS.md有的读CLAUDE.md有的只读.cursor/rules下特定命名的文件。先确认你的文件确实被工具加载了最简单的办法是直接在对话里问AI你当前加载的项目规则文件有哪些内容是什么如果它答不上来说明文件压根没被读取。第二步确认文件内容格式。有些工具要求规则文件遵循特定的格式比如用YAML frontmatter标记适用条件或者某些目录下的文件只按文件名匹配。格式不对工具可能跳过这个文件。第三步检查优先级。规则文件本身的优先级是一回事用户的对话指令是另一回事。如果你在对话里给出的指令和规则冲突AI通常会优先执行用户的最新指令。所以出现规则没生效时先回看你的prompt是不是无意中覆盖了规则。第四步观察上下文截断。如果规则文件很大或者对话里贴了太多内容规则可能根本没有被完整放进上下文窗口。这种情况可以通过让AI复述规则来验证。按这个顺序排查大部分规则没生效的问题都能定位到具体环节而不是两眼一抹黑地反复改规则内容。5. 团队落地与效果度量从个人玩法到团队资产5.1 落地顺序先试点、后推广规则文件这种东西很容易变成写了一堆团队没人用。如果你们团队已经在用AI编程工具我的建议是先不要全员铺开而是选一两个对AI工具接受度高的成员、挑一两个相对独立的中小型任务做试点。试点期间你要盯的是两个指标一是AI生成代码的返工率有没有下降二是团队成员手动修改AI产出代码耗费的时间有没有下降。试点过程中一定会有各种问题比如AI生成的代码风格对了一半但另一半还是不对这时就回去改AGENTS.md把缺失的规则补进去。我一般会建议团队在试点期的每周做一次复盘把当周AI犯的错误归类凡是重复出现三类以上的问题就说明AGENTS.md里对应缺少规则或者规则写得不够准确。等试点团队稳定运行两三周以后再把规则文件推广到更大的范围。推广之前做一次统一培训可能不太现实但至少要发一份简单的如何更新AGENTS.md说明让团队成员知道规则文件不是一成不变的谁发现了问题都可以提改动建议。这样AGENTS.md才能真正从个人维护变成团队共同维护的资产。5.2 效果度量怎么判断规则真的生效了规则文件好用不好用不能靠感觉得靠几个可量化的信号。我常用的有三个。第一个信号是违反规则的次数在下降。设定几个硬规则作为监测点比如新增API是否自动补充了OpenAPI文档commit信息是否使用了约定的格式然后每隔一段时间抽一批AI生成的PR统计这些硬规则的违反率。如果写了AGENTS.md之后违反率从40%降到5%左右说明规则生效了。第二个信号是风格一致性。给同一个任务目标分别让AI在读了AGENTS.md和没读AGENTS.md两种情况下生成代码对比命名方式、目录组织、错误处理、注释风格这四个维度的一致性。只要规则文件写得好读了和没读的差异会非常明显。第三个信号是上下文复用率。如果团队同学在对话里开始减少重复交代同样的背景信息比如不用再反复说我们这项目用pnpm启动命令是pnpm dev说明规则文件正在被AI有效利用把原来需要人肉灌输的项目信息内化成了AI的基础认知。5.3 模板化、版本管理与社区生态当规则文件在你们团队运作成熟后应该把它沉淀成模板。下次启动新项目时直接复制模板再按新项目的特点删改而不是从空白文件开始。模板的层级和章节结构保留具体的路径、技术栈、红线事项全部替换成新项目的真实情况。模板化还有一个额外的好处不同项目的AGENTS.md风格统一AI交叉调试多个项目时就不会因为规则格式差异产生混乱。版本管理这块一定要纳入Git不要在任何聊天工具里传文件。AGENTS.md的历史版本有重要的参考价值比如某条规则为什么加了、某条规则为什么删了这些信息在Git提交记录里都能查到。如果没有版本记录光凭人脑回忆规则文件很快就会腐烂成没人看得懂的化石。社区生态现在也起来了GitHub上能找到不少项目公开的AGENTS.md有些是专门收集高质量规则文件模板的仓库还有一些工具可以帮你校验AGENTS.md的格式规范。多看看别人怎么写的能找到很多自己想不到的细节。但切记参考可以直接抄不行。每一条规则都应该对应你真实项目的实际约束而不是照搬别人的最佳实践。5.4 一个隐藏价值规则文件倒逼团队规范显性化说到最后我想分享一个我当初没想到的收获。做AGENTS.md的过程本质上是在把团队里口口相传的隐性知识变成文字。以前很多规矩是老员工知道新员工靠问问多了别人烦不问你走弯路。而为了写规则文件你必须把这些规矩一条条从脑子里挖出来用精确的语言写清楚。这个过程比AGENTS.md本身更有价值。它强迫团队把为什么这个目录要这么分为什么错误处理要这么写为什么这里的命名要加前缀这些问题清晰地表达出来。有些问题你会发现说不清楚那就说明团队的规范本身就存在漏洞。AGENTS.md就像一面镜子照出来的不是AI的问题而是你自己项目的真实状态。我个人的体会是规则文件设计这件事越早做越好。哪怕你的AGENTS.md一开始只有十几行也比没有强因为它给了AI一个明确的起点。与其等AI一次次犯错、一次次在对话里纠正不如花一个下午把项目里那些你已经习以为常的规矩写下来然后看着AI实实在在少犯错。这个投入产出比我自己算下来是相当划算的。