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.mdAI 就会在你还没开口之前遵守。所以说告别 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.md3.1 写之前先盘点你的项目最需要 AI 遵守什么很多人一上来就照着模板写 AGENTS.md写完全都拿给 AI 用结果发现 AI “看了个寂寞”。问题出在AGENTS.md 不是写得越多越好而是要精准命中你项目里 AI 最容易出错的地方。所以我建议动笔之前先做一次小盘点问自己几个问题这个项目里AI 最常写错的是什么是类型定义、目录结构、错误处理还是测试哪些规则是人必须遵守、但 AI 没有意识到的哪些命令、脚本、配置是 AI 在修改代码前必须知道的有哪些历史教训是“入职不到一个月的新人最容易踩的坑”把这些问题的答案写出来再去组织 AGENTS.md 的结构效果远好过照搬网上现成模板。我见过最典型的案例是一个 Python 项目用了 poetry 管理依赖但 AGENTS.md 里只写了pip installAI 每次都按错误命令操作导致依赖版本全乱。这种问题完全不涉及编程能力纯粹是上下文缺失——但一份“命令清单”就能彻底解决。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 -DtestOrderServiceTest - 代码检查mvn checkstyle:check ## 架构约束 - 代码分层controller - service - mapper禁止跨层调用 - service 层必须面向接口编程禁止直接注入其他 service 的实现类 - 外部 HTTP 调用统一走 Feign Client禁止使用 RestTemplate - 数据库操作统一走 MyBatis-Plus 的 BaseMapper禁止手写 SQL - 所有敏感配置放在 Nacos 配置中心禁止在代码里写死 ## 编码规范 - 业务错误通过 BizException 抛出由全局异常处理器统一转换 - 返回结果统一使用 ResultT 包装禁止直接返回裸实体类 - 新增接口必须包含参数校验注解和对应单元测试 - 日期时间类型使用 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.mdAI 反而可能因为现有代码和规则冲突而频繁“卡壳”。我的建议是“三步走”第一步先写一份最基础的 AGENTS.md只包含项目概述、常用命令、任务执行流程先让 AI 能正常完成“读代码、改代码、跑测试”的基本闭环。第二步运行一两周后把 AI 在评审中最常犯的错误收集起来逐条转成规则加进去同时保持现有代码的兼容性。第三步等规则稳定下来后再把架构约束、编码规范、禁止事项逐渐补全并同步给团队做一次说明。这样渐进式的做法不会让 AI 在适应期就频繁触发规则冲突也能避免团队因为“AI 老不遵守规范”而一开始就对 AGENTS.md 失去信心。最后再分享一个我个人的体会AGENTS.md 写得好不好本质上取决于你有多了解自己项目的“隐性规范”。那些永远不会出现在文档里、但所有人写代码时都会自觉遵守的东西才是 AI 最容易忽视、也最需要通过 AGENTS.md 显式化的内容。每次和 AI 协作时发现它“不太懂事”别急着骂模型先回头看看是不是自己的 AGENTS.md 还差一句该说的话。把这份文件当成一个可以不断打磨的“AI 新人入职手册”你会在一次次迭代里亲眼看到代码输出质量一点点变稳。 
长河君 · 2026/10/18 1:12:36 · 阅读 1.2k AGENTS.md：给AI编程助手的项目规范手册，告别乱写代码
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.mdAI 就会在你还没开口之前遵守。所以说告别 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.md3.1 写之前先盘点你的项目最需要 AI 遵守什么很多人一上来就照着模板写 AGENTS.md写完全都拿给 AI 用结果发现 AI “看了个寂寞”。问题出在AGENTS.md 不是写得越多越好而是要精准命中你项目里 AI 最容易出错的地方。所以我建议动笔之前先做一次小盘点问自己几个问题这个项目里AI 最常写错的是什么是类型定义、目录结构、错误处理还是测试哪些规则是人必须遵守、但 AI 没有意识到的哪些命令、脚本、配置是 AI 在修改代码前必须知道的有哪些历史教训是“入职不到一个月的新人最容易踩的坑”把这些问题的答案写出来再去组织 AGENTS.md 的结构效果远好过照搬网上现成模板。我见过最典型的案例是一个 Python 项目用了 poetry 管理依赖但 AGENTS.md 里只写了pip installAI 每次都按错误命令操作导致依赖版本全乱。这种问题完全不涉及编程能力纯粹是上下文缺失——但一份“命令清单”就能彻底解决。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 -DtestOrderServiceTest - 代码检查mvn checkstyle:check ## 架构约束 - 代码分层controller - service - mapper禁止跨层调用 - service 层必须面向接口编程禁止直接注入其他 service 的实现类 - 外部 HTTP 调用统一走 Feign Client禁止使用 RestTemplate - 数据库操作统一走 MyBatis-Plus 的 BaseMapper禁止手写 SQL - 所有敏感配置放在 Nacos 配置中心禁止在代码里写死 ## 编码规范 - 业务错误通过 BizException 抛出由全局异常处理器统一转换 - 返回结果统一使用 ResultT 包装禁止直接返回裸实体类 - 新增接口必须包含参数校验注解和对应单元测试 - 日期时间类型使用 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.mdAI 反而可能因为现有代码和规则冲突而频繁“卡壳”。我的建议是“三步走”第一步先写一份最基础的 AGENTS.md只包含项目概述、常用命令、任务执行流程先让 AI 能正常完成“读代码、改代码、跑测试”的基本闭环。第二步运行一两周后把 AI 在评审中最常犯的错误收集起来逐条转成规则加进去同时保持现有代码的兼容性。第三步等规则稳定下来后再把架构约束、编码规范、禁止事项逐渐补全并同步给团队做一次说明。这样渐进式的做法不会让 AI 在适应期就频繁触发规则冲突也能避免团队因为“AI 老不遵守规范”而一开始就对 AGENTS.md 失去信心。最后再分享一个我个人的体会AGENTS.md 写得好不好本质上取决于你有多了解自己项目的“隐性规范”。那些永远不会出现在文档里、但所有人写代码时都会自觉遵守的东西才是 AI 最容易忽视、也最需要通过 AGENTS.md 显式化的内容。每次和 AI 协作时发现它“不太懂事”别急着骂模型先回头看看是不是自己的 AGENTS.md 还差一句该说的话。把这份文件当成一个可以不断打磨的“AI 新人入职手册”你会在一次次迭代里亲眼看到代码输出质量一点点变稳。