1. 先搞清楚 AI 为什么会“乱写代码”
1.1 AI 编程工具的痛：能力越强，越容易“自作主张”
这两年 AI 编程工具进化得很快，从最初只会补全几行代码，到后来能直接照着 issue 梳理思路、改文件、跑测试，确实把很多重复劳动接了过去。但接得越多，问题也越明显——AI 生成的代码经常“看起来没什么毛病，一跑就出事”。
这个现象背后的原因其实不复杂：AI 编程助手默认情况下对项目是一无所知的。它只知道你当前打开的这个文件，或者通过对话临时塞给它的一点上下文，至于你这个项目的目录结构为什么这么分、错误处理为什么要统一走某个工具函数、数据库迁移要遵守什么命名规范，它完全不知道。
所以它会在一个用 Java 的老项目里给你生成 Python 风格的长函数名；会在一个明确用“仓库模式”分层的数据访问层里，顺手把 SQL 写在 Controller 里；会在一个对向后兼容要求极高的 SDK 项目里，直接改掉公共 API 的签名。这些错误不是模型理解能力不够，而是项目上下文确实没被有效传递给它。说得更直接一点——AI 破格输出的根源，往往不是你提示词写得不够好，而是它没有一份“项目使用说明书”可以查。
我曾经接手过一个中度规模的微服务项目，团队决定让 AI 助手帮忙补单元测试。结果它一口气生成了两百多个测试文件，覆盖范围挑不出毛病，但全部用了它自己“发明”的工厂类来构造测试数据，而这套工厂类既不符合项目现有的测试基建，也没法在 CI 里跑出稳定结果。那一整个下午我们都在删文件。后来我才意识到：AI 需要的不只是“请遵守项目规范”这种抽象要求，而是一份可以读取、可以检索、可以原文引用的项目级指令文件。
1.2 你说的“规范”它看不到，问题就在上下文
跟 AI 协作的一大特点，是它只能依据当前对话的上下文来做判断。虽然像 Claude Code、Codex、Cursor 这类工具已经有能力自动扫描整个仓库，但扫描到的原始代码量太庞大，模型必须靠自身的注意力机制从中挑出最关键的信息。在这种“盲人摸象”式的上下文里，AI 经常抓到的是局部代码风格，而不是项目整体的架构约束。
这就好比一个新入职的工程师，你给他开通了代码仓库的查看权限，但他不知道你们团队的 Code Review 清单、不知道哪些目录是自动生成的、不知道核心模块的改动需要哪些人审批，最后当然只能靠着“猜”来写代码。AI 编程助手也是同一个道理——它不是没有能力，而是缺一份“入职培训手册”。
所以“乱写代码”这个问题的本质，是上下文供给不足。你越希望 AI 写出贴近团队风格的代码，就越需要主动把团队在长期实践中沉淀下来的约束、流程、偏好喂给它。而 AGENTS.md 正是目前用来做这件事的最直接、最标准化的工具。
1.3 不是模型不聪明，是它缺少“项目纪律”
把 AI 生成的代码风格想象成一个没有纪律约束的实习生：它能干活，但思维方式取决于它读过什么、见过什么。如果你只告诉它“帮忙实现一个导出功能”，它大概率会按自己在训练数据里最常见的模式来写——通用性强，但和你的项目不一定合拍。
AGENTS.md 的作用，相当于给 AI 立一套“项目纪律”。它不是一个每次都要从头写一遍的提示词，而是放在仓库根目录下的一组规则文件，AI 编程工具在开始干活之前会自动读取它，并把它当作最高优先级的参考依据之一。在这份文件里，你可以告诉 AI：项目用什么语言和框架、目录结构有哪些约定、构建和测试命令是什么、哪些代码风格是必须遵守的、哪些操作绝对不能做。
一旦这套纪律建立起来，AI 的输出质量会有一个非常明显的提升。最直接的体感是——你不再需要反复在对话里纠偏：“别用 ts-ignore”“错误处理统一走 AppException”“新加的字段去哪边注册”。这些规则只要写进 AGENTS.md，AI 就会在你还没开口之前遵守。
所以说，告别 AI 乱写代码这件事，真正要做的不只是换更强的模型，而是把项目的“行为准则”以 AI 能理解的方式交付给工具本身。AGENTS.md，就是这座桥。
2. AGENTS.md 到底是个什么东西
2.1 它和 README、docs 的根本区别
第一次听到 AGENTS.md 的人，很容易把它和 README 搞混。两者都在仓库根目录，都是 Markdown 格式，都描述项目信息，但阅读对象和使用场景完全不同。
README 的读者是人类。它的目的是让新同学快速了解“这个项目是干嘛的、怎么启动、怎么部署”。所以你会看到 README 里有大段的功能介绍、界面截图、一长串环境变量说明。这些内容对 AI 编程助手来说不是没用，但太杂、太啰嗦，而且很多信息是写给产品经理和运维看的，AI 在写代码时根本用不上。
AGENTS.md 的读者是 AI Agent。它的内容应该是一份高度浓缩、直接指向“AI 在代码层面做决策时需要遵守的规则”的指令集。它不需要介绍业务价值和产品愿景，但必须明确说清楚：修改这个模块时要注意什么、新增依赖要不要先问、测试命令是哪个、代码格式由谁来管。
这里有个容易被忽略的差异：README 是给人看的，所以可以用叙述性语言；AGENTS.md 是给 AI 执行的，所以更接近一份“规则清单”。你希望 AI 遵守“新封装的方法必须附带单元测试”，就别写“我们建议最好补充一下测试”，而要写“新封装的方法必须附带单元测试，并在提交前运行 npm test 验证”。命令式、明确、无歧义，是 AGENTS.md 最重要的三个写作原则。
2.2 主流 AI 编程工具是如何读取它的
AGENTS.md 之所以能在 2025 年迅速普及，很大程度上是因为头部 AI 编程工具都开始原生支持它。Claude Code、Codex、Cursor、Gemini CLI 这些工具，在初始化会话时会把仓库里的 AGENTS.md 作为系统级的上下文注入给模型，优先级比普通对话内容更高。
以我实测过的工作流来说：在仓库根目录放一份 AGENTS.md 之后，再让 AI 助手执行“帮我修一下登录接口的并发问题”这类任务，它会在动代码之前先按文件里的要求，弄清楚登录模块所在的位置、依赖的中间件、现有的幂等方案，然后基于这些信息去修改代码。它甚至会主动提一句“按照项目规范，我需要同时更新相关单测”，因为规范写进了它启动时的默认上下文。
需要留意的是，不同工具读取 AGENTS.md 的机制不完全一样。有的工具只读根目录和当前目录的文件，有的支持多级目录叠加读取，有的还兼容AGENTS-extra.md、.cursorrules这类变体。但当前的主流趋势是统一拥抱 AGENTS.md 这个标准文件名，工具之间的生态兼容性也越来越好。所以对你来说，不需要为每个工具单独维护一套规则文件，一份根目录的 AGENTS.md 就能覆盖绝大多数场景。
2.3 一个最小的 AGENTS.md 长什么样
为了让你对 AGENTS.md 有个直观印象，我先给一个最小可用的示例。这个示例虽然简单，但已经能显著减少 AI“乱来”的概率：
# AGENTS.md ## 项目概述 这是一个 Node.js + TypeScript 构建的 REST API 服务，核心业务是用户认证与订单管理。 ## 常用命令 - 安装依赖：pnpm install - 本地开发：pnpm dev - 运行测试：pnpm test - 代码检查：pnpm lint ## 代码规范 - 所有业务错误必须通过 AppError 类抛出，禁止直接 throw new Error() - 控制器层只做参数校验与响应包装，不写业务逻辑 - 数据库访问统一走 Prisma Client，禁止直接拼 SQL - 新增文件必须使用 TypeScript 严格模式 - 所有对外接口的返回结构必须是 { code, data, message } ## 禁止事项 - 禁止提交 .env 文件内容 - 禁止修改公共 API 路径或请求方法，除非先在对话中向用户确认 - 禁止在未运行测试的情况下声称“修改已完成”把这个文件放在仓库根目录后，AI 编程助手每次会话开始时都会读到它。对于一个小型 API 服务来说，这份文件已经能把代码风格、错误处理方式、测试要求这些最容易引发返工的冲突点全部“打上预防针”。
3. 动手写一份真正管用的 AGENTS.md
3.1 写之前先盘点：你的项目最需要 AI 遵守什么
很多人一上来就照着模板写 AGENTS.md，写完全都拿给 AI 用，结果发现 AI “看了个寂寞”。问题出在：AGENTS.md 不是写得越多越好，而是要精准命中你项目里 AI 最容易出错的地方。
所以我建议动笔之前，先做一次小盘点，问自己几个问题：
- 这个项目里，AI 最常写错的是什么？是类型定义、目录结构、错误处理还是测试？
- 哪些规则是人必须遵守、但 AI 没有意识到的？
- 哪些命令、脚本、配置是 AI 在修改代码前必须知道的？
- 有哪些历史教训，是“入职不到一个月的新人最容易踩的坑”？
把这些问题的答案写出来，再去组织 AGENTS.md 的结构，效果远好过照搬网上现成模板。我见过最典型的案例是：一个 Python 项目用了 poetry 管理依赖，但 AGENTS.md 里只写了pip install，AI 每次都按错误命令操作，导致依赖版本全乱。这种问题完全不涉及编程能力，纯粹是上下文缺失——但一份“命令清单”就能彻底解决。
3.2 核心区块一：项目背景与定位
项目背景这一节，是给 AI 建立“项目感”的。你不必写得像产品发布会，但至少要让它知道：这个项目是什么类型的应用、服务的核心场景是什么、整体架构是什么样的。
举个实际例子：
## 项目概述 order-service 是电商平台的后端微服务之一，负责订单创建、支付回调、库存扣减等核心链路。 技术栈为 Java 17 + Spring Boot 3 + MyBatis-Plus + MySQL + Redis。 服务通过 HTTP 接口对内对外提供能力，遵循 RESTful 风格。AI 看到这段背景后，在生成代码时的“方向感”会完全不同：它不会在订单服务里突然建议你引入一套消息队列来做本可以同步完成的库存校验，因为它知道这个服务边界在哪里。你也不用在每次对话里反复强调“我们是微服务，注意服务边界”。
背景信息不宜过长，控制在 5 到 10 行即可。关键是让 AI 知道“它在一个什么样的世界里干活”，这样后续的规则才有依附的土壤。
3.3 核心区块二：把常用命令变成“肌肉记忆”
在 AGENTS.md 里写命令，不是给 AI 当字典，而是为了减少它“自己猜”的次数。AI 在没有明确命令信息时，会用自己的方式启动项目、跑测试，结果往往和环境不匹配。
我建议把项目里最常用的四类命令全部写进去：安装依赖、启动开发环境、运行测试、代码检查/构建。如果项目有特殊的数据库迁移命令、代码生成命令，也一并写上。
## 常用命令 - 安装依赖：npm ci（禁止使用 npm install，保证锁文件一致） - 启动前端开发服务：npm run dev - 启动后端 API 服务：npm run server - 运行全部测试：npm test - 运行单个测试文件：npx jest src/xxx.test.ts - 类型检查：npx tsc --noEmit - 代码格式化：npm run format写清楚命令还有一个隐藏好处——AI 在修改代码之后，会主动运行这些命令来验证自己的改动。如果没有这些命令信息，很多 AI 在改完代码后只是“声称完成”而不做验证，等到人接手才发现编译都过不了。
3.4 核心区块三：架构约束与代码组织规则
这是 AGENTS.md 里含金量最高、也最需要根据项目定制的内容。它回答的问题是：AI 在改代码时，应该把代码放在哪里？新增模块应该怎么组织？哪些层之间不能直接调用？
不同的项目类型需要不同的约束。这里举几个方向的例子，你可以按项目实际补充：
## 架构与目录约束 - 所有业务代码位于 src/ 目录下，scripts/ 目录只能放运维脚本 - 前端页面文件按页面维度组织，公共组件存放在 src/components/common/ - 后端新增接口时，按 controller -> service -> mapper 三层结构实现 - service 层禁止直接依赖其他 service 的实现类，必须走接口 - 外部 HTTP 调用统一通过 feign 客户端封装，禁止在业务代码里直接用 RestTemplate - 数据模型变更必须同时提交对应的数据库迁移脚本这些规则看起来零散，但它们解决的是 AI 最常见的“乱放代码”问题。没有这些约束，AI 完全有可能在一个分层清晰的项目里，把所有逻辑都塞进 Controller，或者在微服务里直接跨服务查别人数据库——对的，我遇到过一次，AI 为了让联调方便，直接在订单服务里连了用户服务的数据库表。
AI 这种“为了完成任务不择手段”的特性，必须在 AGENTS.md 里提前设卡。
3.5 核心区块四：编码规范、禁止事项与“优先级说明”
编码规范和禁止事项，是 AGENTS.md 里“力度”最大的部分。在这里写下的规则，AI 会把它当成高优先级指令来执行。
写这部分的时候，我有几个经验可以分享：
一是规范要具体，能落到代码层面。与其写“注意代码质量”这种正确但没用的废话，不如写“所有函数的返回类型必须显式声明，禁止依赖 IDE 自动推断”。AI 能执行的是具体规则，而不是抽象价值。
二是禁止事项要比提倡事项更有力。比如这条就非常有效：“禁止在代码中新增 console.log 调试输出，如需日志请使用 Logger 模块。”AI 对“不能做什么”的记忆和执行通常比“应该怎么做”更准确。
三是必要时加“优先级说明”。比如：
## 规则优先级 如上述规则与用户临时指令冲突，用户指令优先；如项目现有代码风格与本文件规则冲突，以本文件规则为准。实际执行的时候，我不建议把这条优先级说明写得太复杂，否则会影响 AI 的判断。但写一句“用户临时指令优先于本文件”是值得的——这能避免 AI 为了“守规矩”而死板地拒绝你的临时需求。
3.6 核心区块五：任务执行流程模板
前四类内容是“静态规则”，而任务执行流程是“动态步骤”。它告诉 AI：接到一个任务后，应该按照什么顺序来干活。
这个模块对提升 AI 代码输出质量特别有帮助。因为很多 AI 生成代码质量不稳定的另一个原因，是它经常“一步到位”——直接给出完整的大段代码，而不是遵循小步验证的工程方式。
我在 AGENTS.md 里通常会这样写：
## 任务执行流程 1. 阅读任务描述，梳理需求，如果有歧义先向用户确认 2. 定位相关代码文件，阅读并理解现有实现 3. 制定改动方案，说明涉及的文件和影响范围 4. 执行代码修改，保持现有代码风格 5. 新增或更新单元测试 6. 运行相关测试与 lint，确保全部通过 7. 汇总改动清单，提交给用户 review这七步流程看着简单，但真正写进 AGENTS.md 之后，AI 干活的方式会发生不小变化。它会从一个“直接给出代码”的生成器，变成一个“先分析再动手、改完再验证”的协作伙伴。对团队来说，这种变化意味着 review 时不用再提心吊胆。
3.7 一份完整示例：融合前面五个区块
把上面几个部分串起来，一个更完整的 AGENTS.md 大概是这样的结构：
# AGENTS.md ## 项目概述 order-service 是电商平台订单域的后端微服务，技术栈为 Java 17 + Spring Boot 3 + MyBatis-Plus + MySQL + Redis。 服务遵循 RESTful API 设计，内部通过 Feign 调用用户、商品等下游服务。 ## 常用命令 - 安装依赖：mvn clean install - 启动本地服务：mvn spring-boot:run - 运行全部测试：mvn test - 运行单个测试：mvn test -Dtest=OrderServiceTest - 代码检查：mvn checkstyle:check ## 架构约束 - 代码分层：controller -> service -> mapper，禁止跨层调用 - service 层必须面向接口编程，禁止直接注入其他 service 的实现类 - 外部 HTTP 调用统一走 Feign Client，禁止使用 RestTemplate - 数据库操作统一走 MyBatis-Plus 的 BaseMapper，禁止手写 SQL - 所有敏感配置放在 Nacos 配置中心，禁止在代码里写死 ## 编码规范 - 业务错误通过 BizException 抛出，由全局异常处理器统一转换 - 返回结果统一使用 Result<T> 包装，禁止直接返回裸实体类 - 新增接口必须包含参数校验注解和对应单元测试 - 日期时间类型使用 LocalDateTime，禁止使用 Date ## 禁止事项 - 禁止用 System.out.println 代替日志框架 - 禁止修改已发布接口的路径、请求方法或返回结构 - 禁止把数据库连接、密码等敏感信息硬编码到代码 - 禁止在未运行 mvn test 的情况下声称改动完成 ## 任务执行流程 1. 理解需求，如有歧义先向用户确认 2. 阅读相关代码，明确改动范围 3. 按架构约束修改代码 4. 补充或更新单元测试 5. 运行 mvn test 和相关检查 6. 汇总改动清单，提交 review这份文件看下来，一个对项目一无所知的 AI，至少能对项目的骨架有一个清晰认知。配合上对话里的具体需求，它能给出的代码质量和使用默认上下文时完全是两个水准。
4. 写完不是结束：验证、迭代与调优
4.1 别急着全量铺开，先选两个任务做验收
AGENTS.md 写完之后，我强烈建议先别立刻拿它驱动各种大型重构任务，而是先找两三个有代表性的任务做“验收测试”。
选任务时注意覆盖面：一个选新增功能类任务，比如“新增一个查询订单列表的接口”；另一个选修改类任务，比如“修复某个接口的空指针异常”。如果在验收过程中发现 AI 仍然没有遵守 AGENTS.md 里的规则，优先检查是不是规则本身写得不够明确。
我自己的一个典型翻车经历是：在 AGENTS.md 里写了“禁止使用 System.out.println”，结果 AI 在测试代码里照样输出了一堆。后来检查发现，我写的是“禁止使用 System.out.println 调试”，AI 理解成了“建议不这么干”，于是转手用在了测试断言的场景里。把规则改成“禁止在 src/ 目录下任何代码中使用 System.out.println，统一使用 Logger”之后，它才真正遵守。这件事给我的教训是：AGENTS.md 不是写给人看的建议，而是写给机器执行的指令，措辞必须足够明确。
4.2 让 AI 先“复述”规则，确认它真的读懂了
AGENTS.md 里的规则再多，如果 AI 没有真正“理解”，也是一纸空文。我习惯在正式干活之前，先让 AI 用一句话总结它从 AGENTS.md 里读到的关键约束。这个操作看起来多余，但能省下后面大量返工时间。
实操方式很简单，直接在对话里发：
请先阅读项目根目录的 AGENTS.md，然后用三句话概括你将要遵守的最重要规则，并在后续开发中严格遵守。如果 AI 能准确总结出架构约束、命令入口、禁止事项这些核心点，说明它确实把文件读进去了。如果它总结的内容连你自己都看不懂，或者明显偏离了 AGENTS.md 的重点，那就要考虑是不是文件太长、结构太乱，导致 AI 没有抓取到关键信息。
4.3 版本管理：AGENTS.md 也要像代码一样演进
AGENTS.md 不是写一次就一劳永逸的文件，它需要跟随项目的演进持续迭代。我见过不少团队，第一版 AGENTS.md 写得很好，但用着用着就成了“僵尸文件”——项目加了新模块、换了数据库、改了接口规范，文件里的内容早就过时了，AI 继续按老规矩办事，反而制造出新的问题。
建议把 AGENTS.md 的维护纳入代码评审流程：每当项目引入新的架构决策、新的约束规范，或者发现 AI 在某类任务上持续犯错时，同步更新 AGENTS.md，并让这些更新走一次 review。我个人的习惯是，每次 AI 在代码评审中被驳回的修改，都会反问一句：这是不是 AGENTS.md 里缺少规则导致的？如果是，就补一条规则进去。这样 AGENTS.md 才能保持“新鲜”，真正反映项目当下的真实约束。
5. 把 AGENTS.md 用明白：进阶玩法与团队实践
5.1 从单文件到多文件：按目录层级组织规则
对于单体项目或者小型仓库，根目录一份 AGENTS.md 通常够用。但项目一复杂，一份文件就会变得臃肿——根目录要写的通用规则之外，每个子模块还有自己的独有约束，全塞在一份文件里，AI 读取时反而会“信息过载”。
这时候可以把 AGENTS.md 拆开，用多级文件组织。通用规则放在根目录的 AGENTS.md，模块级约束放在对应子目录。AI 编程工具在读取时，会同时把根目录和当前工作目录的规则都带进上下文，形成一种叠加效果。
举个例子，一个仓库里既有前端又有后端，根目录的 AGENTS.md 写通用命令和提交规范，frontend/AGENTS.md里写前端的状态管理约定、组件命名规则、样式方案，backend/AGENTS.md里写后端的接口分层、异常处理、数据库访问规则。这样 AI 改前端时不需要背后端那堆 SQL 约束，改后端时也不会被前端组件规则干扰。
5.2 团队协作：把 AGENTS.md 变成“团队的公共接口”
AGENTS.md 不应该属于某个人的个人配置，而应该是团队共同的资产。它的内容应该来自团队共识：架构师定架构边界，一线开发补充容易踩坑的实现细节，测试同学提出可测试性要求。
我们团队现在的做法，是把 AGENTS.md 的维护当成和 README 同等重要的事情，写进开发规范文档里。每个新项目初始化时就要创建 AGENTS.md，并通过 Code Review 保证它的质量。后续 AI 生成的代码如果在评审里被反复打回，根因分析时必查一条：AGENTS.md 有没有需要补充的规则。
这样做还有一个隐性好处：AGENTS.md 本身成了新成员了解项目的快捷入口。很多人刚开始接触一个团队时看 README，但进入实际开发后真正该看的是这份“给 AI 的规则”里沉淀的架构共识与避坑指南。
5.3 和其他 AI 工程实践合流：不只是“写文件”
AGENTS.md 能解决很大一部分问题，但它不是银弹。如果你想持续稳定地提升 AI 代码输出质量，还需要把它和其他实践组合起来。
比如，为 AI 准备一份“代码评审清单”文件，让 AI 在提交代码前自查；再比如，把项目里最典型的几个代码示例收录到一个 examples 目录，并在 AGENTS.md 里引向这些示例，让 AI “参考现有最优实现”而不是凭空发挥；又比如，接入 CI 流程里的 AI 代码评审 bot，让 AI 在每次提交时对照 AGENTS.md 的规范做自动检查。
这套组合拳下来，AGENTS.md 就不再是一个孤立的文本文件，而会成为团队整体 AI 工程实践的一部分。代码输出质量会从“靠 AI 自觉”，逐步变成“靠规则约束 + 自动校验 + 人工兜底”的确定性流程。
6. 常见问题与避坑清单
6.1 AI 总是不遵守 AGENTS.md 里的规则，怎么办
这是被问得最多的问题。如果 AGENTS.md 写好了，AI 还是“我行我素”，优先检查三件事：
第一，文件位置对不对。AGENTS.md 必须放在 AI 工具的工作区根目录，比如你在 VS Code 里打开的是my-project文件夹，那文件就在my-project/AGENTS.md，而不是放在更深层级的子目录里。
第二，规则本身的描述是否足够明确。AI 对“禁止使用魔法数字”这种规范其实理解有限；但“所有状态码必须定义为枚举并放在 constants 目录”它就清楚得多。规则越接近代码层面，执行效果越好。
第三，是不是文件太长导致关键信息被稀释。如果一个 AGENTS.md 超过 300 行，AI 在读取时可能会漏掉一些中后段的规则。解决办法是精简文件，把最重要的规则放前面，或者拆成多级文件。
如果以上都没问题，还可以尝试在对话中显式引用 AGENTS.md，比如“请严格按照项目根目录 AGENTS.md 的规范修改代码”，这是临时强化手段，但对很多工具都有效。
6.2 AGENTS.md 越写越长，AI 反而忽略核心规则，怎么取舍
这确实是进阶使用中很常见的问题。AGENTS.md 越长，单条规则被读取和执行的权重就越低。我给的取舍原则很简单：只写“必要的规则”，不写“正确的废话”。
比如“代码要清晰易读”就不是 AGENTS.md 该有的内容，因为 AI 无法将该抽象要求落成具体动作；“每个函数不超过 80 行”虽然也有争议，但它至少是一条可执行的指令。
此外，把规则按重要性排序，把“红线规则”放在文件前部。AI 在读取大文件时，对开头的关注度通常高于后面。如果你的项目里有“禁止在未确认的情况下删除公共接口”这类红线，一定要靠前放，并且措辞要非常强硬。
6.3 老项目接入 AGENTS.md，有没有平缓过渡的方案
老项目通常代码体量大、历史包袱多，直接上一套严格的 AGENTS.md，AI 反而可能因为现有代码和规则冲突而频繁“卡壳”。我的建议是“三步走”：
第一步，先写一份最基础的 AGENTS.md，只包含项目概述、常用命令、任务执行流程，先让 AI 能正常完成“读代码、改代码、跑测试”的基本闭环。
第二步，运行一两周后，把 AI 在评审中最常犯的错误收集起来，逐条转成规则加进去，同时保持现有代码的兼容性。
第三步，等规则稳定下来后，再把架构约束、编码规范、禁止事项逐渐补全，并同步给团队做一次说明。
这样渐进式的做法，不会让 AI 在适应期就频繁触发规则冲突，也能避免团队因为“AI 老不遵守规范”而一开始就对 AGENTS.md 失去信心。
最后再分享一个我个人的体会：AGENTS.md 写得好不好，本质上取决于你有多了解自己项目的“隐性规范”。那些永远不会出现在文档里、但所有人写代码时都会自觉遵守的东西，才是 AI 最容易忽视、也最需要通过 AGENTS.md 显式化的内容。每次和 AI 协作时发现它“不太懂事”，别急着骂模型，先回头看看是不是自己的 AGENTS.md 还差一句该说的话。把这份文件当成一个可以不断打磨的“AI 新人入职手册”，你会在一次次迭代里，亲眼看到代码输出质量一点点变稳。
