写一份 AI 编码规范，CR 时间减一半

同事分别用 Cursor、qoder、codebuddy和claude写代码，功能都跑通了。

CR 变成了"代码风格纠错大会"。你让团队成员各自用 AI 写代码，这个问题就一定会出现。上个月和一个做 PHP 的朋友聊天，他们团队也一样——有的 AI 生成的 Laravel 代码用 Eloquent 关联，有的直接 DB::raw 一把梭。

AI 没有记忆。它每次对话都是新的。上一轮你让它遵循的规则，下一轮它就忘了。

你肯定也经历过这个循环：提醒→它照做→下次忘记→再提醒→又照做→又忘记。

靠人肉提醒太累了。你需要一个"一次写好、次次生效"的东西。这个东西就是 AI_RULES.md——一份写给 AI 看的编码约束文件。

这不是代码风格指南

先说一个最容易搞混的点：AI 编码规范跟《阿里巴巴 Java 开发手册》不是一回事。

阿里巴巴的规范是给人看的。人可以灵活理解——"函数不超过 80 行"是建议，你真写 81 行，同事也不会说什么。但 AI 不行。AI 需要绝对的"是/否"判断。你写"尽量使用 XML"，AI 就当没看见。你必须写"多表关联必须使用 XML，禁止使用 MyBatis-Plus Wrapper"。

两者的核心区别一句话就能说清楚：

• 给人的规范：原则性指导，允许灵活变通。人读了会自己判断。
• 给 AI 的规范：硬性约束，每条都能回答"是/否"。AI 只会做你明确要求它做的事。

我给你一个具体的对比。给人的规范可能会写：

给 AI 的规范必须写成：

区别在哪？第一条是建议，AI 会忽略。第二条是命令，AI 能执行。AI 只能理解"必须做X"和"禁止做Y"，它不理解"最好做X"和"尽量不要做Y"。

所以你写 AI 规范时，通篇只用"禁止"和"必须"两个动词。把"建议""尽量""最好"全部删掉。

怎么设计你自己的 AI 编码规范

下面我用一份 Java SpringBoot 团队的规范做案例，拆解设计方法。不要复制这份规范——你要理解每一步的设计思路，然后套到你自己的技术栈上。

整套方法论分五步。

第一步：选技术栈基线

你不能只说"代码写规范点"，AI 不知道什么叫规范。你必须告诉它"以哪套标准为基准"。

对于 Java 生态，最自然的基线是《阿里巴巴 Java 开发手册》。在规范开头直接声明："本规范以《阿里巴巴 Java 开发手册（黄山版）》为基准，所有通用规则继承阿里规范。"这样你只需要补充技术栈特化的规则——包名怎么分、Lombok 怎么用、MyBatis XML 怎么写——不用重复定义命名、注释、异常处理这些通用要求。

我见过一个反面案例：一个团队写了一份 AI 规范，用了 30% 的篇幅重复阿里规范已经说清楚的东西，比如"类名大驼峰""方法名小驼峰"。这不光是浪费，还会稀释真正重要的特化规则。AI 读长文本时，信息密度越低，关键规则的遵守率就越差。

对于其他技术栈，选基线同理：Python 声明"以 PEP 8 为基准"，Vue 声明"以 Vue 官方风格指南（Priority A 强制执行）为基准"，PHP 声明"以 PSR-12 为基准"。

一句话总结：选一个社区公认的基线规范作为"默认层"，你的规范只写"差异层"。不要从零开始写，也不要复读基线。

第二步：定义硬性红线

硬性红线是 AI 绝不能违反的规则。每条都必须能做"是/否"判断。

以 Java 规范为例，最核心的红线只有一句，我把它作为规范的"最高优先级声明"放在文件最前面：

为什么这条排第一？因为 AI 极其喜欢用 LambdaQueryWrapper 拼复杂 SQL，越拼越长。你让它查"用户及其订单列表"，它会写：

 复制代码//  AI 最爱这样写，但不要让 AI 碰链式 Wrapper 做多表查询
List<UserOrderVO> list = userMapper.selectList(
    new LambdaQueryWrapper<User>()
        .eq(User::getDeleted, 0)
        // ... 然后三十行链式调用拼了三表联查
);

XML 里的 SQL，你一眼能看懂它查了什么表、关联条件是什么。链式 Wrapper 拼出来的 SQL，只有 AI 自己能看懂。半年后你要优化慢查询，发现完全不知道这段代码对应哪些数据库操作。出问题时连调试都无从下手。

你的硬性红线应该控制在 3 到 5 条。多了等于没有——AI 对十条以上的红线会选择性忽略，这和人类面对长清单时的行为一模一样。每条用"禁止"或"必须"开头：

• 禁止多表关联使用 MP Wrapper（必须写 XML）
• 禁止 Controller 写业务逻辑
• 禁止直接返回 Entity 给前端
• 禁止日志打印手机号、身份证、密码明文
• 必须使用统一返回封装 R<T>

反面教材：不要把"方法名应该语义清晰"写成红线。这不是硬性判断——什么叫"语义清晰"，AI 判断不了。

第三步：分层约束——告诉 AI 每层该做什么

AI 最擅长把代码"写在错误的地方"。它会在 Controller 里查数据库、在 Entity 里写业务方法、在 Mapper 里打日志。你必须明确每一层的"能做什么"和"不能做什么"。

还是用 Java 三层架构做例子。

Controller 层：只做四件事——接收参数、鉴权、调用 Service、返回结果。别的什么都不做。

 复制代码//  规范约束下的 AI 输出
@GetMapping("/list")
@SaCheckPermission("user:list")
public R<Page<UserVO>> list(@RequestParam Long pageNum, @RequestParam Long pageSize) {
    return R.ok(userService.pageUser(pageNum, pageSize));
}

 复制代码//  没有规范约束的 AI 输出——业务逻辑侵入了 Controller
@GetMapping("/list")
public R<List<User>> list(@RequestParam Long pageNum) {
    List<User> users = userMapper.selectList(new LambdaQueryWrapper<>());
    users.forEach(u -> u.setPassword(null));  // 手动脱敏
    return R.ok(users);  // 直接返回 Entity
}

Service 层：业务逻辑的唯一归宿。数据校验、缓存读写、事务管理、数据组装、对象转换——全在这里。复杂业务拆成私有方法，单个方法不超过 80 行。

Mapper/XML 层：单表 CRUD 用 MyBatis-Plus 内置方法（list、getById、page、save、updateById）；多表关联和复杂 SQL 必须 XML，这是第二步的红线。

对于你自己的项目，把架构层次拆开——不管你是三层、四层还是 DDD 的六边形架构——每一层写清楚"允许做什么"和"禁止做什么"，各 3 到 5 条。不需要长篇大论，简洁明确就够了。

第四步：AI 自检清单

规范正文写完之后，在文件末尾加一章"AI 强制自检清单"。AI 生成代码后，必须逐条自查，违规自动修正。

清单不需要原创——把前面所有章节的硬性规则汇总成"是否"问题列表：

• 是否遵循了阿里 Java 规范？
• 多表/复杂 SQL 是否写入 XML，未滥用 MP Wrapper？
• Controller 是否加了完整的 Knife4j 文档注解？
• Sa-Token 鉴权注解是否按需添加？
• 返回结果是否统一 R<T>，未直接返回 Entity？
• Redis Key 命名是否遵循"项目:模块:业务:标识"格式？
• 异常是否捕获并打印了完整堆栈？
• 事务注解是否添加在正确的方法上？
• 是否出现了 select *？
• DTO/VO 是否做了数据脱敏？
• ……

我这份 Java 规范的自检清单有 15 条，你可以参考这个密度。

为什么自检清单要放在文件最后？因为 AI 在处理长文本时，开头和结尾的信息权重最高——这是大语言模型注意力机制的基本特性。规范正文放前面，自检清单放最后，AI 在生成代码前最后读到的是"检查自己有没有违规"，效果最好。

第五步：补充禁止项——集中检索入口

前四步定义的规则散落在各个章节中。到最后，单独开一章"补充禁止项"，把所有红线聚合成一个编号列表。

这一章的作用不是补充新内容，而是给 AI 一个集中检索入口。10 条以内，每行一句话，简短有力：

 复制代码1. 禁止多表关联使用 LambdaQueryWrapper
2. 禁止 Controller 写业务逻辑
3. 禁止日志打印手机号、身份证、密码明文
4. 禁止直接返回 Entity 给前端
5. 禁止使用 select *
6. 禁止硬编码接口地址、缓存时间、SQL 字符串
7. 禁止 Boolean 字段加 is 前缀
8. 禁止 XML 中使用 ${} 拼接用户输入
9. 禁止无事务注解执行多表增删改
10. 禁止生产环境开启 Knife4j 接口文档

你翻到前面看——这些确实都在前四步里出现过。但聚合在一起，效果完全不同。AI 检索"我有什么不能做的"时，直接定位到这一章，10 条全命中。

其他技术栈怎么适配

上面的方法论不限于 Java。核心框架——基线 + 红线 + 分层约束 + 自检清单 + 禁止项——对任何技术栈都适用。你只要把每个步骤填进自己的内容。

PHP（Laravel）：

• 基线：PSR-12 + Laravel 官方最佳实践
• 硬性红线：Eloquent 关联查询必须使用 with() 预加载，严禁 N+1 问题；禁止在 Blade 模板中写数据库查询；所有请求验证必须在 FormRequest 中完成，禁止在 Controller 里手动校验
• 分层：Controller → FormRequest → Service → Model。Controller 只做路由分发，Model 只定义关联和访问器，业务逻辑全在 Service

Python（FastAPI）：

• 基线：PEP 8 + PEP 484 类型注解
• 硬性红线：所有函数必须有类型注解（AI 生成的 Python 代码经常缺类型注解）；Pydantic Schema 与 ORM Model 严格分离，禁止直接返回 ORM 对象；禁止在路由函数中写数据库查询逻辑
• 分层：Router → Service → Repository。Repository 只做数据库 CRUD，不包含业务判断

Vue 3 前端：

• 基线：Vue 官方风格指南（Priority A 规则强制执行）
• 硬性红线：所有 API 调用统一放在 /api 目录下管理，禁止在组件中直接 fetch；禁止在组件中直接操作 localStorage（封装 composable）；组件超过 300 行必须拆分；禁止使用 any 类型
• 分层：View（页面）→ Component（组件）→ Composables（逻辑）→ API（请求）。Composables 不操作 DOM，组件不做数据请求

给一个通用模板，你照着填就行：

 复制代码[项目名] AI 编码规范## 前置说明
本规范以 [社区基线规范] 为基准，适配技术栈：[列出你的框架和中间件]。## 硬性红线（≤5 条）
1. ...
2. ...## 分层约束
- [层名]：能做什么 / 禁止做什么
- ...## AI 自检清单（汇总全文规则）
1. 是否...
2. 是否...## 补充禁止项（聚合所有红线）
1. 禁止...
2. 禁止...

这个文件放哪里

项目根目录，文件名 AI_RULES.md。

主流 AI 编码工具都能读取项目级规则文件。Cursor 读 .cursorrules 和 AI_RULES.md；GitHub Copilot 通过 .github/copilot-instructions.md 生效；通义灵码、Windsurf、CodeBuddy 也都支持项目根目录下的规则文件。

如果你团队用了多种工具，建议在 AI_RULES.md 维护唯一规则源，然后在各工具的配置文件中引用它。这样修改规则时只改一处，所有人、所有工具同步生效。

最后

有了这份规范，AI 写的代码确实不会跑偏太多。但别期望"有了规范就等于有了好代码"。

规范能解决的，是底线问题。代码不会出现 Controller 查数据库——因为红线禁止了。不会出现三表联查的链式 Wrapper——因为红线禁止了。不会出现明文密码打在日志里——因为红线禁止了。

但业务逻辑是否合理、异常处理是否完整、缓存策略是否正确、接口设计是否优雅——这些仍然需要人来判断。

规范不是替代 Code Review。规范让 CR 不再花 70% 的时间纠结"你这格式不对""返回类型不统一""怎么又在 Controller 里查库"，让 CR 把精力放在真正重要的事情上——架构、性能、安全、业务正确性。

好了，去写你的第一份 AI_RULES.md。从选基线开始，一条一条往下写。写完记得让 AI 自己读一遍——它会告诉你哪里不够清楚。然后改，再让它读一遍，直到它不再问"这里是什么意思"为止。

规范不是写给团队看的，是写给 AI 看的。AI 能准确理解、严格执行，这份规范才算及格。