1. 为什么你的 AI 写代码总是不守规矩

很多团队在使用 AI 编程助手时都会遇到同一个问题：AI 生成的代码风格五花八门，命名随意、注释缺失、错误处理不到位，代码规范率长期徘徊在 60% 左右。问题往往不在 AI 本身，而在于你没有给它一份足够清晰的「行为说明书」。

AGENTS.md 正是这样一份文件。它告诉 AI 你的项目规范、代码风格、目录结构和工作流程，让 AI 在动手写代码之前就「知道规矩」。本文将从零开始，带你写出一份能让 AI 代码规范率从 60% 飙升到 95% 的 AGENTS.md。

2. AGENTS.md 是什么

AGENTS.md 是放在项目根目录下的一份 Markdown 文件，专门用于指导 AI 编程助手理解项目上下文和编码规范。它不同于 README（面向人类读者），也不同于 CONTRIBUTING（面向贡献者），它是一份面向 AI 的「项目操作手册」。

一份好的 AGENTS.md 通常包含以下核心模块：

• 项目概览：用几句话说明项目是做什么的、技术栈是什么。
• 代码风格规范：命名规则、缩进、注释风格、错误处理方式。
• 目录结构说明：各目录的职责，AI 新增文件时知道该放哪里。
• 工作流程：从需求到提交的完整流程，包括测试、构建、提交信息规范。
• 禁止事项：明确列出 AI 绝对不能做的事。

3. 从 60% 到 95% 的关键：写清楚「怎么做」

很多团队写的 AGENTS.md 只有「要遵守代码规范」这种空话，AI 看了等于没看。真正有效的 AGENTS.md 必须写清楚「具体怎么做」。

以命名规范为例，不要只写「命名要有意义」，而要写：

## 命名规范
- 变量名使用 camelCase，如 `userName`、`orderCount`
- 常量名使用 UPPER_SNAKE_CASE，如 `MAX_RETRY_COUNT`
- 函数名使用动词开头，如 `fetchUserData`、`validateInput`
- 布尔变量使用 is/has/can 前缀，如 `isLoading`、`hasPermission`
- 禁止使用单字母变量名（循环变量 i、j 除外）

再以错误处理为例，不要只写「要做好错误处理」，而要写：

## 错误处理
- 所有可能失败的 IO 操作必须使用 try-catch 包裹
- 捕获异常后必须记录日志，禁止静默吞掉异常
- 对外抛出的异常必须包含上下文信息，禁止裸抛
- 网络请求必须设置超时时间，默认 10 秒

当规范具体到这种程度，AI 才能准确执行。这也是代码规范率能大幅提升的核心原因。

4. 一份可直接套用的 AGENTS.md 模板

下面是一份经过实践验证的 AGENTS.md 模板，你可以根据自己的项目直接修改使用。

# AGENTS.md
项目概览
这是一个基于 Spring Boot 3 + Vue 3 的电商后台管理系统，提供商品管理、订单管理、用户管理三大核心模块。
技术栈
后端：Java 17、Spring Boot 3.2、MyBatis-Plus、MySQL 8
前端：Vue 3、TypeScript、Vite、Element Plus
构建：Maven、npm
代码风格
后端
类名使用 UpperCamelCase，如 OrderService
方法名使用 lowerCamelCase，如 createOrder
常量使用 UPPER_SNAKE_CASE，如 MAX_PAGE_SIZE
Controller 只做参数校验和结果封装，业务逻辑放在 Service 层
所有查询必须使用分页，禁止一次性加载全表数据
前端
组件文件名使用 PascalCase，如 OrderList.vue
变量和方法使用 lowerCamelCase
组件内 props 使用 camelCase，模板中使用 kebab-case
禁止在组件内直接修改 props
目录结构
backend/src/main/java/com/example/controller/：接口层
backend/src/main/java/com/example/service/：业务逻辑层
backend/src/main/java/com/example/mapper/：数据访问层
frontend/src/views/：页面组件
frontend/src/components/：通用组件
frontend/src/api/：接口请求封装
工作流程
先阅读相关模块的现有代码，理解已有风格
编写代码前先确认接口设计，避免返工
代码完成后必须补充单元测试，覆盖率不低于 80%
提交前运行 mvn test 和 npm run lint，确保全部通过
提交信息格式：type(scope): description，如 feat(order): 新增订单导出功能
禁止事项
禁止在代码中硬编码数据库连接信息
禁止使用 System.out.println 输出日志，必须使用 SLF4J
禁止提交包含敏感信息的文件
禁止修改公共工具类而不补充测试
禁止在未确认需求的情况下擅自重构已有代码

5. 让 AGENTS.md 真正生效的 5 个技巧

写好 AGENTS.md 只是第一步，让它真正生效还需要注意以下 5 个技巧。

技巧一：放在正确的位置。AGENTS.md 必须放在项目根目录，AI 工具才能自动读取。如果你的项目是 monorepo，可以在每个子项目目录下各放一份，内容更聚焦。

技巧二：保持简洁。AGENTS.md 不是越长越好。超过 200 行的规范文件，AI 反而会抓不住重点。建议控制在 100 到 150 行，只写最关键、最容易出错的规范。

技巧三：用「禁止」代替「建议」。AI 对「禁止」类指令的执行率远高于「建议」类。把最容易出问题的行为写成明确的禁止项，效果立竿见影。

技巧四：定期迭代。每次发现 AI 写出不合规的代码，就把对应的规范补充进 AGENTS.md。坚持迭代两周，规范覆盖率会明显提升。

技巧五：配合代码评审。AGENTS.md 不能替代人工评审。在 AI 生成代码后，仍然需要人工把关，但评审重点可以从「找问题」变成「验证规范执行」，效率会高很多。

6. 效果验证：从 60% 到 95% 的实践数据

我们团队在一个中型电商项目中实践了这套方法，效果非常明显。在引入 AGENTS.md 之前，AI 生成的代码规范率约为 60%，主要问题集中在命名不规范、缺少错误处理、注释缺失三个方面。

引入第一版 AGENTS.md 后，规范率提升到约 80%。随后经过两轮迭代，补充了更具体的错误处理规范和提交信息格式要求，规范率稳定在 95% 左右。

需要说明的是，95% 并不是终点。剩余 5% 的问题主要集中在边界情况处理上，比如极端输入、并发场景等，这些仍然需要人工把关。但相比之前，人工评审的负担已经大幅降低。

7. 总结

AGENTS.md 的核心价值，是把团队积累的编码经验沉淀成一份 AI 能读懂、能执行的规范文件。它不需要很复杂，但必须具体、可操作、持续迭代。

从 60% 到 95% 的跨越，靠的不是更强大的 AI 模型，而是一份写清楚「怎么做」的 AGENTS.md。如果你也在为 AI 代码质量发愁，不妨从今天开始，为你的项目写一份 AGENTS.md。