给AI制定代码规范：从规则文件到CI兜底的完整落地指南

今年团队正式把AI编程工具纳入日常开发之后我遇到的最头疼的问题不是AI写不出代码而是AI写出来的代码“能用但不像我们团队写的”。命名风格五花八门错误处理爱写不写有时候还会自作主张引入一个没人用过的依赖review起来像考古现场。后来我意识到问题不在AI在于我们没有给AI制定代码规范。所谓给AI制定代码规范准确说就是把团队多年沉淀的工程约定从人的脑子里搬到AI能读取、能理解、能被自动校验的地方。它不是一份普通文档而是一套工程约束体系。这篇文章就完整分享我在项目中给AI制定代码规范的全过程包括为什么做、规范里写什么、怎么落地、踩了哪些坑。如果你正被AI生成代码的质量问题折磨或者团队刚引入AI编程但发现代码风格越来越乱这篇文章应该能帮到你。1. 为什么必须管住AI给AI制定代码规范的核心思路1.1 AI不会主动遵守你的工程约定我在项目里最先踩的坑是默认AI“应该”懂我们团队的规范。结果自然很惨。AI写出来的代码语法没错逻辑也能跑但放到工程里就是别扭有的函数写了100行有的错误处理直接 return null有的明明项目里统一用DTO做参数传递AI却给你塞个 Map 进去。这个问题的根源在于人和AI理解“规范”的方式完全不同。人是靠长期浸染、Code Review、互相提醒来遵守约定的而AI只依赖两样东西上下文和提示约束。如果你不在上下文里把规则写清楚AI就会用训练数据里那些“常见写法”来交付代码。它不是一个会主动问“你们项目怎么约定”的同事它更像一个能力很强、但只会按给定条件答题的实习生。你给的条件越模糊它越容易自由发挥。所以给AI制定代码规范的第一性原理是不要指望AI猜要把规则变成它不得不看、看了就懂的输入。凡是人靠自觉维护的规则AI几乎都不会自觉遵守凡是写进文件、写进检查脚本、写进约束条件的规则AI才会真正执行。1.2 给AI的规范和给人看的规范根本不是一回事很多团队第一次写AI代码规范时直接拿团队原有的《开发规范》扔给AI结果毫无效果。原因很简单给人看的规范和给AI看的规范适用的载体、语气、粒度完全不一样。给人看的规范通常写“为什么”比如“service层不要直接操作DAO便于后期扩展”人能理解这个动机并灵活执行。但AI没有这种“灵性”它需要的是“什么必须做、什么禁止做、每种情况长什么样”这种高度可判定的描述。我整理过两组对比体验很直观对比维度给人看的规范给AI看的规范目的统一认知指导判断限制生成空间约束输出格式载体文档、Wiki、口头文化规则文件、提示词、CI检查脚本语气建议性、解释性命令式、清单式粒度抽象原则具体到类型、后缀、目录、禁止项校验方式Code Review时人肉判断自动化检查 Review双重验证给AI看的规范要满足三个特点一是足够机械能被ESLint、Ruff、静态检查这类工具自动判定二是必须有正反示例AI对示例的学习能力远超对抽象规则的理解能力三是必须有优先级核心红线放在最前面普通建议放在后面避免AI在上下文里捡了芝麻丢了西瓜。1.3 规范的本质是上下文工程不是限制AI我一度担心“给AI定太多规范是不是反而捆住手脚”后来发现这个担心是多余的。AI编程工具的能力上限很大程度上取决于你给它的上下文质量。一份好规范不是给AI戴镣铐而是在给AI“补课”补的是你项目的技术栈、约束、常见反模式、命名习惯这些训练数据之外的信息。打个比方一个外聘顾问能力很强但第一次进团队也不知道你们的接口路径要带版本号、也不知道实体字段禁止用缩写。你把规则讲清楚之后他干活的速度和准确率才会上来。AI也一样。规范写得越清楚AI一次写对的概率越高反而减少了对话往返和反复修改的成本。所以我在项目里把“AI代码规范”定位成一套闭环而不是一份文档。闭环包含三部分规则文件告诉AI什么能做什么不能做、自动化检查让不合规代码进不了主干、Review反馈把新发现的问题回填到规则里。这三者缺一个规范的效果都会大打折扣。2. 一份能落地的AI代码规范必须写清这五类内容第二大部分是纯干货。我把项目里沉淀的AI代码规范按内容拆成五类全局底线、架构分层约束、命名与风格、安全合规红线、测试与可维护性。每一类都有对应的规范示例文本你可以直接抄到自己的规则文件里。2.1 全局底线语言版本、禁止项、通用原则全局底线是所有AI生成代码都必须遵守的硬性约束建议放在规则文件最开头。AI有两个典型毛病喜欢用最新语法不过脑子以及随手写一些“看起来简洁但实际是反模式”的代码。比如项目还在用Python 3.8AI直接生成str | None这种3.10才有的类型语法再比如为了减少行数把复杂逻辑压成一个eval()。我项目里的全局底线长这样# 全局底线最高优先级任何情况下不得违反 - 目标语言版本Java 17 / TypeScript 5.x禁止生成项目语言版本不支持的语法。 - 禁止硬编码任何密钥、Token、数据库连接串包括但不限于代码字面量、常量类、YAML配置。 - 禁止使用 eval、exec、Function 等动态执行函数除非有安全评审通过。 - 禁止魔法数字散落业务代码所有业务常量必须定义到常量类或枚举中。 - 禁止空catch块捕获异常后必须记录日志或者做向上抛出的处理。 - 禁止直接打印堆栈后继续吞掉异常。全局底线这一段不用太长但每一条都得是“如果违反代码review一定打回”级别的硬指标。写太多反而稀释优先级我建议控制在10条以内。2.2 架构与分层约束别让AI打破依赖倒置AI对“分层”的理解通常很模糊。它知道Controller、Service、DAO这些词但它不知道你们项目里到底怎么分。最典型的问题AI在Controller里直接写JDBC查询在Service里操作前端入参的JSON结构或者在前端组件里直接改全局Store的数据而不通过Action。所以架构约束这块必须写清楚依赖方向和调用边界。我项目里的写法是# 架构与分层生成代码时必须遵守 - 后端分层Controller - Service - Mapper/Repository禁止跨层调用。 - Controller只做参数接收、参数校验、结果包装不允许出现业务逻辑和SQL。 - 所有跨Service的调用必须经过接口禁止直接依赖另一个Service的实现类。 - 前端组件通信父组件用props传参子组件用事件回调禁止组件直接修改props对象。 - 全局状态必须通过状态管理工具本项目使用Pinia/Redux的Action修改禁止页面组件直接改State字段。 - 新增对外接口必须使用项目统一响应体 RT 包装禁止直接返回裸对象或Map。这一节不需要面面俱到重点是把你项目里最不希望AI踩的分层雷区列出来。如果有跨模块的依赖规范比如“订单模块不能依赖库存模块的内部Service”也一定要写上。AI特别容易在你没规定的地方放飞自我。2.3 命名体系与代码风格给AI“签字画押”的命名规则命名是AI代码规范里性价比最高的一项。命名规则写清楚之后review代码时的“眼睛不适感”会大幅下降。但注意命名规则必须具体到类型级别不能写“命名要有意义”这种虚话。我总结了一个表格直接放进规则文件里作为附件代码要素规则示例类名名词形式UpperCamelCaseOrderService、UserController接口名以I开头UpperCamelCaseIOrderRepositoryDTO/VO必须带DTO/VO后缀CreateOrderDTO、OrderDetailVO布尔属性禁止is前缀valid而不是isValid常量全大写下划线分隔MAX_RETRY_COUNT测试类被测类名TestOrderServiceTest代码风格这块我的建议是彻底交给格式化工具。不要让规范文件去规定“缩进4个空格”这种AI容易记混的事直接在规范里写“所有生成代码必须通过ESLint Prettier校验”就够了。让AI把精力集中在结构和逻辑上格式化的事交给工具省下大量口水。2.4 安全与合规红线AI最容易闯祸的地方安全红线是AI代码规范里绝对不能省的一节。倒不是说AI会故意写漏洞而是它在追求“功能正确”时经常忽略边界和安全。我在review里看到过最典型的几种用字符串拼接SQL、把用户输入直接塞进HTML、在后端日志里打印用户手机号、用明文存密码。这些问题的共同点是逻辑能跑、测试能过但一上线就是事故。所以安全红线要放在规范里靠前的位置并且必须配反面示例# 安全红线违反直接Rework - 禁止拼接SQL字符串必须使用参数化查询或ORM的查询构造器。 错误示范String sql SELECT * FROM user WHERE id userId; 正确示范mapper.selectById(userId) 或使用 #{} 占位。 - 禁止将用户输入直接渲染到HTML/JS上下文必须经过项目统一的XSS过滤机制。 - 禁止在后端日志中输出完整手机号、身份证号、银行卡号、Token等敏感信息必须脱敏。 - 禁止以明文方式存储密码必须使用 BCrypt 等加盐哈希算法。 - 新增依赖必须先确认来源和许可证禁止让AI随意推荐未经验证的第三方库。安全红线的每个“禁止”后面最好紧跟一个“正确示范”。AI对示例的遵循率远高于抽象规则这是我实测下来的结论。2.5 测试与可维护性让AI的代码经得起Review最后一块是测试与可维护性。这个容易被忽略但其实很重要。AI写代码时如果不管测试团队就得花双倍时间补review成本居高不下。我们团队的规范是凡是AI生成的核心业务方法必须同时生成单测骨架。# 测试与可维护性 - 核心业务方法必须附带单元测试断言至少覆盖正常路径、异常路径、边界值。 - 测试命名统一为方法名_场景_预期结果例如 testCreateOrder_库存不足_抛异常。 - 单个函数不超过50行超过则必须拆分并说明职责。 - 禁止AI“过度设计”不要自动引入设计模式、抽象基类、工厂类除非已在任务中明确要求。 - 禁止生成未被调用的私有方法或无用代码片段。 - 所有新增方法必须有对应注释说明入参、出参、可能抛出的异常。过度设计这条是我特别加的。AI很喜欢在代码里“炫技”动不动给你抽象一个模板方法模式实际上项目只需要一个if else。规范里明确规定“不要在任务没要求的情况下引入新架构元素”能省掉大量无意义的重构。3. 三步落地把AI代码规范真正接入项目和日常开发规范写得好是一回事AI实际遵守是另一回事。这一节我分享亲测有效的落地三步法分别是写规则文件、配置AI工具、用CI兜底。三步做完才算是真正把规范接进了工程链路。3.1 用项目级规则文件替代口头约定第一步是在仓库根目录放一个项目级规则文件。现在的AI编程工具基本都支持读取项目规则文件有的叫 AGENTS.md有的识别项目内自定义指令文件主流的IDE AI插件也都在逐步支持类似机制。无论工具叫什么思路一致让AI在生成代码前自动读取这个文件。我项目里的做法是放一个.ai-rules.md文件并在文件开头加一句“严格遵守本文件中的所有约束”。完整模板可以直接参考下面这个结构# 项目AI代码规范 本文件是AI生成代码时必须遵守的最高优先级约束。 每次生成代码之前先阅读本文件全部内容再开始编写。 ## 0. 项目技术栈必读 后端Java 17 Spring Boot 3.x MyBatis-Plus 前端Vue 3 TypeScript Pinia Vite 数据库MySQL 8.x禁止使用存储过程 ## 1. 全局底线最高优先级 - 禁止硬编码密钥/Token/数据库连接串必须放在环境变量或配置中心。 - 禁止使用 eval、exec、Function 动态执行。 - 禁止空catch吞异常。 - 禁用魔法数字常量必须定义到常量类或枚举。 ## 2. 架构分层 - Controller - Service - Mapper禁止跨层调用。 - Controller只做参数绑定和校验不写业务逻辑。 - 所有对外接口返回统一响应体 RT。 - 前端禁止组件直接修改props禁止页面组件绕过Store修改State。 ## 3. 命名约定 - 接口以 I 开头IOrderRepository - DTO/VO 必须带后缀CreateOrderDTO、OrderDetailVO - 常量全大写MAX_RETRY_COUNT - 测试类以 Test 结尾OrderServiceTest ## 4. 安全红线违反直接Rework - SQL禁止拼接必须参数化或使用ORM构造器。 - 禁止输出完整手机号/身份证号/Tokent到日志。 - 密码必须BCrypt加盐哈希。 - 禁止引入未经验证的第三方依赖。 ## 5. 测试要求 - 核心方法必须生成单元测试覆盖正常、异常、边界。 - 函数不超过50行超过必须拆分。 - 禁止未经要求引入设计模式、抽象类、工厂。 ## 6. 反例速查新增问题持续补充 - 反例Controller内直接用 JdbcTemplate 查询。 - 反例Service返回 Map 代替DTO。 - 反例前端组件里直接改 Store 的 state 字段。文件不一定要很长但关键约束必须全。它既给AI划定边界也充当团队开发的统一入口新成员来了看这个文件也能快速理解项目约定。3.2 在IDE和AI工具里配置规范引用规则文件放好之后下一步是让它真正进入AI的上下文。不同工具的配置入口不一样但通用思路是在新会话或项目设置里指定“项目级规则文件”路径或者在自定义指令里明确要求“根据项目根目录的 .ai-rules.md 规范生成代码”。如果你用的工具不支持自动读取项目文件退一步的做法是在每次发起AI任务时先用一条指令把规范文件内容喂进去。可以简单粗暴地写“先阅读项目根目录的 .ai-rules.md 文件并遵守其中所有规则然后开始编写代码”。虽然多了半句话但实测AI对规范的理解和遵守程度会显著提升。还有一个小技巧把规范文件放在显眼位置不要放在深层目录。AI读取项目规则文件时通常有文件大小和路径优先级的限制放在根目录最容易被命中。3.3 用自动化检查兜底AI不听话CI会拦规则文件能约束AI但不是万能的。总会有AI在特定场景下忽略某条规范的时候。这种时候如果只靠人工review迟早会漏。所以第三步特别关键凡是规范里能自动检查的项目全部做成自动化检查接入CI。前端项目里就是ESLint Prettier后端项目里就是静态检查工具加单测。举个例子前端在CI里加这一步npm run lint npm run type-check npm run test:unit后端对应的是mvn checkstyle:check mvn test # 或者如果使用Python ruff check src/ pytest --covsrc这一步的本质是把“AI有没有按规范写”从主观判断变成客观门禁。之前我们reviewAI代码时每一条都要人肉盯现在很多低级问题在CI阶段就被拦住了Review只需要聚焦业务逻辑和架构合理性。如果CI有未通过的项直接把报错信息丢给AI让它基于报错修改比人肉一遍遍解释规范高效得多。3.4 用Review反馈形成闭环让AI越用越“懂规矩”最后一步是闭环。建议每两周或每月把Review中发现的AI高频问题回填到规则文件里特别是在“反例速查”一节追加真实案例。为什么是反例因为AI对失败样本的学习速度比抽象描述快得多你给它看“这个写法是错的以后禁止”它下次再遇到类似情况时踩雷的概率会明显下降。我们项目经过三轮迭代后规则文件从最初的十几行长到了快一百行但AI生成代码的“一次通过率”反而从不到50%提升到了80%以上。原因很简单规则文件补上了AI对项目特有约定的知识盲区同时反例清单帮它绕开了大量已知的坑。规范不是一成不变的它需要在项目和AI的反复磨合中持续生长。4. 给AI定规范后我踩过的五个坑和排查经验前几节说的是“应该怎么做”这一节讲的是“实际做的时候会翻车的地方”。每一个坑都是我自己在项目里真金白银踩出来的希望能帮你绕开。4.1 写了规范AI却不看怎么办第一次把规范文件放到项目根目录后我信心满满地让AI写一个订单模块结果它完全无视规范照样输出Map和字符串拼接SQL。排查之后发现我用的AI工具根本不会自动读取项目根目录的任意md文件它只会读取特定文件名或者需要我在对话中显式指定。解决方式新会话第一句指令固定写成“先阅读 .ai-rules.md然后严格按规范完成以下任务”。不要默认AI会看要在每次会话开始的时候主动强调。另一个做法是把最重要的10条规范直接写在AI工具的自定义指令里这样即使它不读文件也能收到关键约束。4.2 规范文件太长AI记不住后面的内容有一次我把团队完整的《Java开发规范》直接丢给AI结果它在开头聊得非常专业写到后面就开始放飞。原因是AI的上下文窗口虽然大但对于长文件的注意力会衰减后面的内容经常被忽略。解决方式核心规范控制在100行以内最关键的10条红线放在文件最前面。详细的团队历史约定、背景说明、参考资料全部挪到独立文档不要塞进AI规则文件。规则文件里只留“能执行的命令”不要留“解释了半天的论文”。4.3 负面指令太多AI反而更混乱有段时间我们的规则文件里全是“不要xxx”“禁止xxx”结果AI生成的代码变得畏手畏脚甚至为了避开某个模式写出了更别扭的代码。后来我意识到AI对“禁止”的处理能力没有我们想的那么强它需要一个“正面替代方案”。解决方式每写一条禁止项后面必须跟一句正确做法和示例。比如“禁止在Controller里写SQL”后面务必接“所有数据库操作必须放到Mapper层参考 OrderMapper”。规则文件不是法律条文光靠禁止是教不会AI的给出可模仿的正例才有用。4.4 AI生成的代码“符合规范”却不符合业务约定这是最隐蔽的一个坑。AI严格遵循了命名规则、分层约束、安全红线但生成的代码还是不对接口路径没带版本号、表名用了复数、枚举值命名和前端约定不一致。因为这些业务约定没有被写进规则文件里AI根本不可能知道。解决方式把项目特有的约定单独成节不要和通用规范混在一起。比如“新增对外接口必须以 /api/v1 开头”、“数据库表名统一单数”、“状态字段用整数枚举不用字符串”每一条都写清楚。项目特有约定其实比通用规范更值钱它才是AI真正无法从公开代码中学到的东西。4.5 用AI批量修规范问题改出一堆新问题有一次为了让存量代码通过规范检查我让AI批量修改多个文件。结果它确实修掉了原有问题但顺手改坏了三处业务逻辑一个事务注解被删了一个幂等判断被“优化”掉了还有一个缓存key的拼写变了。那次事故之后我定了一个原则AI批量修改只允许限于单文件、小范围、可回滚的场景。解决方式要用AI修代码规范可以一次只丢一个文件给它并且强制生成diff后再review。严禁让AI“一把梭”把整个模块的规范问题全修了。修完之后必须跑全套测试确认行为没有变化。规范修复属于重构不改变行为是第一原则。4.6 常见问题速查表现象可能原因解决方式AI完全不遵守规范文件工具没有自动读取规则文件在指令中显式要求先读 .ai-rules.md规则文件太长导致AI忽略后半段内容过长注意力衰减核心规范控制在100行内详细文档外置负面指令多但AI还是犯错缺少正面示例每条禁止项后面配一个正确写法代码规范却没改业务约定项目特有约定没写入规则文件把接口版本号、表名、枚举约定单独成节AI批量修复引入新bug修改范围过大缺少行为校验单文件小范围修改强制diff review和全量测试这份速查表我会一直放在团队Wiki里每次出问题就回来对照。AI代码规范不是写完就完事的静态文档它更像一份持续生长的操作手册踩坑一次就往里补一条越用越顺手。我个人在带团队用AI编程后最大的体会是与其每次生成完代码都花半小时骂AI写得不对不如花一个下午把规范沉淀成文件并且把校验交给工具。AI不是不听话只是它不知道你说的“规矩”才是规矩。等规则文件长到一定程度你会发现AI生成的代码越来越像“自己人写的”review从考古变成走流程那种感觉确实值得。