前阵子我在代码评审里看到一份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.md，OpenAI Codex支持AGENTS.md，Cursor有自己的.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.x，React 18，Vite，pnpm"。版本信息尽量写主版本，避免AI按过时的API写代码。
然后是目录结构的职责说明。不要贴整个目录树，而是只标注那些有特殊规则的目录。比如：
src/api/：所有后端接口调用的唯一入口，禁止在组件内直接使用fetch。src/store/：全局状态管理，禁止在非行动层直接修改store状态。migrations/：数据库迁移脚本目录，只允许通过CLI工具生成。
最后是核心流程的说明。比如数据的流向：UI事件触发action，action调用api层，api层返回后通过reducer更新store，组件订阅store渲染。这段描述可以用一个简洁的流程图表达，但在我使用的工具生态里，纯文本的分步描述往往比流程图更稳定，因为AI解析文本指令比解析图表更可靠。所以建议至少保留一份纯文本版本。
3.3 编码规范与红线事项
这一节是避坑的重头戏，也是你和AI之间最需要"约法三章"的地方。不要照抄网上的通用编码规范，要写那些你在这个项目里真实遇到过、真实踩过坑的规则。比如：
- 禁止在
src/utils/中引入任何框架相关代码，该目录保持纯函数。 - 所有新增的表单校验必须使用
zod，禁止手写if-else校验。 - 错误消息不允许直接展示给用户英文原文，必须走
src/i18n/的翻译函数。
红线事项建议单列一个小节，用"禁止"开头，每一条都加上后果说明。为什么加后果说明？因为只写"禁止xxx"就像交通标志只有禁令没有罚款，AI无法判断遵守与否的优先级。加上后果说明后，比如"禁止在生产代码中使用console.log，会导致日志系统被刷屏，如需日志请使用src/utils/logger.ts"，AI在生成代码时就会自己权衡，而不是机械地在你移除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实实在在少犯错。这个投入产出比，我自己算下来是相当划算的。
