自从团队里正式引入AI编程助手之后我最大的感受是代码量上去了但代码风格也随之“放飞自我”了。同样的功能上午让AI生成的是findUserById下午换了个会话就变成getUserInfo上一段还在用slf4j打日志下一段直接System.out.println就上来了。最头疼的是它特别爱“自作主张”——明明项目里统一用 FastJSON它偏要给你生成 Jackson 的注解。这些问题的根源只有一个AI 没有读过我们团队的代码规范。后来我花了几天时间专门给 AI 制定了一份“看得懂、能执行、可检查”的代码规范把原来写给人的几十页规范文档压缩成 AI 能直接读懂的规则文件再接进 Cursor、Copilot 这些工具里。效果立竿见影AI 生成的代码从“能跑就行”变成了“风格统一、符合团队约定”的可用代码Review 的工作量至少减了一半。这篇文章就是我在这个过程中的完整记录包括规则文件的目录设计、内容怎么写、如何接入工具、如何用脚本兜底以及上线之后踩过的各种坑。如果你也在用 AI 写代码并且被代码风格不一致、AI 不听指挥这些问题困扰过这篇内容应该能帮你少走不少弯路。1. 为什么写给人的代码规范管不住 AI1.1 AI 写代码的四个典型失控现场先说几个我在项目里真实遇到过的场景。第一个是命名风格漂移。同一个团队同一个模块AI 生成的类名一会是OrderDetailVO一会是OrderDetailDto一会又是OrderDetailInfo。对于人来说这些差异肉眼可见Review 的时候顺手就改了。但 AI 不会觉得自己有问题下个会话它还是按自己的“习惯”来因为每个会话都是独立的它根本记不住上次被改成什么样。第二个是依赖引入过于随意。AI 有个很典型的倾向能用第三方库解决的事绝不自己写。你让它写个 Excel 导出它可能就顺手给你引入一个新的 POI 版本你让它解析一个 JSON 字段它甚至可能引入一个项目里从没用过的工具类。这在个人项目里问题不大但放到团队项目里就意味着 pom 文件越来越臃肿依赖冲突的风险越来越高。第三个是结构设计过度。给它一个很简单的列表查询需求它能给你生成一个包含 Controller、Service、DAO、DTO、VO、Converter、Repository 的完整“全家桶”甚至还要给你上个设计模式。代码是规范了但 90% 的类都是多余的。第四个是不读项目约定。团队明明约定数据库字段用下划线命名、Java 属性用驼峰命名AI 直接按自己的方式生成明明项目里统一用Result包装返回AI 生成的是裸对象。这些问题的共性是AI 不是不会写代码而是它写代码时没有任何“团队上下文”。1.2 传统代码规范为什么失效我们团队原来有一套非常完整的代码规范文档写了足足四十多页从命名规范到日志格式从异常处理到数据库设计事无巨细。这套文档对于人来说很友好——因为人可以通过目录查找、通过经验判断哪些是重点。但放到 AI 面前它有几个致命问题。第一个问题是文件太长。主流 AI 编程工具的上下文窗口虽然越来越大但实际使用时工具会自动截断或压缩不重要的内容。一份四十多页的规范文档AI 根本不可能全部“读完”更不可能在生成每一行代码时都去对照。第二个问题是表达方式不对。人类规范喜欢用“建议”“尽量”“可根据实际情况”这类措辞比如“建议使用卫语句减少嵌套”“尽量保证方法长度不超过80行”。这些词对人来说很好理解但 AI 对这种模糊指令的把握非常不稳定它倾向于把“建议”当成“可选”把“尽量”当成“看心情”。第三个问题是规范之间没有优先级。当规则 A 说“优先使用组合”规则 B 说“保持类结构简单”AI 在具体场景下并不知道该听谁的。人可以通过经验判断AI 只能猜。所以给 AI 定代码规范本质上不是把人看的文档“喂”给它而是要把规范重新编写成 AI 能理解、能执行、能校验的格式。2. 给 AI 的代码规范怎么设计——先搭框架再填内容2.1 规则文件放哪里从项目根目录铺开我踩过的第一个坑是把规则文件放到了docs/目录下结果 AI 工具根本不会主动去读docs/里的文件。主流 AI 编程工具读取项目规则是有约定路径的。以现在常用的工具为例工具约定文件路径读取时机Cursor.cursorrules或项目根目录的Rules配置每次对话时自动加载GitHub Copilot.github/copilot-instructions.md自动加载官方推荐Claude CodeCLAUDE.md启动时自动读取通义灵码等项目根目录.aicode.md或配置面板部分工具需要手动挂载我最终采用的是以AGENTS.md为主文件、以.cursorrules和CLAUDE.md作为兼容入口的方案。因为AGENTS.md是目前 AI Agent 类工具事实上的标准文件名很多新工具即使不认识.cursorrules也会主动找AGENTS.md。为了保险我在根目录同时放了这两个文件内容保持同步。注意规则文件必须放在项目根目录不能放在子目录里。AI 工具在读取时绝大多数是从当前工作目录也就是项目根目录向上查找子目录里的规则文件很容易被忽略。2.2 主文件写什么AGENTS.md 的内容骨架我写的AGENTS.md并不长压到了 80 行左右但覆盖了 AI 生成代码最需要知道的几个方面项目概况这个项目是做什么的、面向什么用户、核心业务口径是什么。AI 有了业务背景就不会把“订单金额”理解成“商品价格”。技术栈清单明确列出语言版本、框架版本、构建工具、ORM 方案、JSON 库、HTTP 客户端。比如写清楚“JSON 统一使用 FastJSON 2.0.4”AI 就不会生成 Jackson 的JsonProperty。目录结构说明告诉 AI 哪层放 Controller、哪层放 Service、哪层放 Mapper。这个对分层规范特别重要AI 看到目录结构后生成代码时能大概率把类放到正确的位置。构建与测试命令写上mvn clean install、npm run test这些命令AI 在需要检查编译或运行测试时会调用它们。核心编码约定这是重点我单独拆了一节来讲。禁止事项清单AI 最容易违规的几条明确用“禁止”句式写出来比如禁止引入未在技术栈清单中列出的依赖、禁止在 Java 代码中直接使用System.out.println、禁止创建超过 200 行的类。一个比较重要的经验是不要把完整的规范写进AGENTS.md。它更像是规范的“索引 核心摘要”。我规定AGENTS.md本身行数不超过 120 行超过之后就要考虑把详细规则拆到子文件里用“指针”的方式让 AI 按需读取。2.3 编码约定的表达方式用“必须”“禁止”代替“建议”写给 AI 看的编码约定和写给人看的最大区别在于语气。人看到“建议使用卫语句”会理解为“有嵌套的 else 时优先用卫语句”AI 看到同样的句子可能就真的当成了“可选项”。我总结了一套比较有效的写法格式每条规则尽量按“触发场景 强制指令 正反示例”的结构组织触发场景当你在编写if-else嵌套超过 3 层的方法时强制指令必须使用卫语句提前返回禁止超过 3 层嵌套正反示例给出一个“推荐”写法和一个“不要这样写”的对比举个例子我在规则文件里写了这样一条当需要从数据库查询单条记录且可能不存在时必须使用 Optional 接收禁止直接返回 null。推荐写法return userMapper.selectById(id); 由调用方处理 Optional不推荐写法return userMapper.selectById(id) null ? null : userMapper.selectById(id).getName()。这种写法信息密度很高AI 能直接照着做。而且正反示例最好放在一起因为大模型对“对比”语句的理解能力明显强于对“抽象描述”的理解能力。另外要注意规则文件里不要用“酌情”“一般”“根据情况”这类词。一旦出现这种词AI 就会在模糊地带自由发挥而它自由发挥的结果往往就是风格失控。每条规则要么是“必须”、要么是“禁止”没有中间态。2.4 按语言和场景拆分让规则“按需命中”项目规模一大所有规则都堆在一个文件里会出问题。一方面文件太长会超过 AI 的有效关注范围另一方面不同模块的规范差异很大——前端 TypeScript 的规则放在后端 Java 项目里毫无意义反而会干扰 AI 的判断。我是这样拆的。在docs/ai-code-rules/目录下建了一组子文件typescript.md前端组件规范、类型定义规范、API 调用规范java.md后端分层规范、命名规范、异常处理规范sql.mdSQL 编写规范、索引使用规范style.md代码格式化规范缩进、引号、分号每个子文件控制在 100 行以内聚焦单一领域。然后在AGENTS.md里用这样的方式引用前端代码src/ 目录下的 .ts/.tsx 文件必须严格遵循 docs/ai-code-rules/typescript.md 中的规则。 后端代码src/main/java 目录下的 .java 文件必须严格遵循 docs/ai-code-rules/java.md 中的规则。这样 AI 生成前端代码时只需要重点读typescript.md生成后端代码时重点读java.md。既减少了上下文负担又提高了规则命中率。2.5 规则冲突时的优先级必须提前约定规则文件一多必然会遇到冲突。比如typescript.md里规定“组件文件使用 PascalCase 命名”但官网示例里某个组件用了 kebab-caseAI 就会犹豫。我给 AI 的指令是从文件顶部开始逐条寻址后出现的规则覆盖先出现的规则。也就是说在同一个文件里后面的规则优先级更高跨文件时AGENTS.md的优先级最高子文件次之。这样设计的好处是核心约定放在AGENTS.md里基本不会被子文件的规则覆盖。同时我在规则文件顶部固定加上一句话遇到规则冲突时优先遵循 AGENTS.md 中与项目相关的部分其次遵循本文件中的规则。若仍无法确定请向用户提问确认。这句话看着简单实际作用很大。它给 AI 留了一个“露出来问”的出口而不是让它在规则冲突时自己硬猜。3. 三条落地路径——把规则真正“装进”AI 的脑子里3.1 路径一通过工具级规则文件接入这是最省事、最推荐的第一步。说白了就是把规则文件放到 AI 工具约定的位置让它每次自动加载。以 Cursor 为例。我是在项目根目录建了一个.cursorrules文件内容就是AGENTS.md的精简版。Cursor 会自动加载这个文件并把它作为对话的上下文背景。如果你用 GitHub Copilot路径是.github/copilot-instructions.md官方推荐的内容结构和我们上面说的AGENTS.md几乎一致。接入之后可以做一个简单的验证在对话中让 AI 读取规则文件然后让它用自己的话复述三条最核心的工程量。如果它说得出来说明规则读进去了如果说得似是而非就要检查文件是不是太长或者路径是不是放错了。这里有个配置细节。部分工具支持设置“规则文件优先级”比如项目级规则 用户级规则 默认行为。如果团队里有人写了一份用户级规则和你项目的规则冲突AI 会优先按项目级规则走这个要提前确认。3.2 路径二通过会话提示词强制加载工具级规则文件虽然方便但有个局限AI 不一定每条都遵守。因为它只是在上下文里“挂”了一份文件模型在生成代码时对每个 token 的注意力权重不同规则文件里的内容可能被“稀释”。我实测下来更稳定的是在每次对话开始时加一句指向性提示词。比如请先阅读项目根目录下的 AGENTS.md 文件严格遵循其中的编码规范。如果规范与我给的指令冲突请按规范执行并提示我。这一步相当于把规则从“背景信息”提升到了“显式指令”。因为提示词在对话中是最近的内容模型对它的注意力权重更高规则遵守率会明显上升。还有一个技巧是让 AI 在生成代码后做一次自检。我常用的说法是代码生成完成后请对照 AGENTS.md 检查以下内容 1. 命名是否遵循驼峰/帕斯卡约定 2. 是否引入了技术栈清单之外的依赖 3. 方法长度是否超过 50 行 4. 是否有 System.out.println 或临时调试代码 如有违规请直接修正后再输出。两次提示一次在开头强制加载规则一次在结尾强制自检AI 生成代码的合规率能提高很大一截。我单独测试过——同样的需求只有工具级规则文件时合规率大概 60%加上开头和结尾提示词之后能到 85% 以上。3.3 路径三用自动审查脚本守最后一道门就算提示词写得再到位AI 的生成结果也不可能 100% 合规。所以我在项目里加了一道“最后防线”用脚本检查 AI 生成的代码是否符合规范。这个脚本做三件事。第一是静态检查通过eslint、prettier、ktlint、gofmt这类工具检查代码格式和基础规范。第二是规则文件检查扫描新增和修改的代码判断是否命中了规则文件里的“禁止事项”。第三是结构检查比如检查类文件是否超过 200 行、方法是否超过 50 行。核心检查脚本并不复杂我贴一个简化版#!/usr/bin/env python3 # ai_code_audit.py —— AI生成代码合规性检查脚本 import os import re import sys # 禁止出现的调试代码模式 BANNED_PATTERNS [ rSystem\.out\.println, rprint\(.*\), # Python调试输出 rdebugger;, # JavaScript断点 rTODO\s*:\s*(fix|bug|临时), rconsole\.log\(, ] # 禁止引入的依赖关键词 BANNED_DEPENDENCIES [ joda-time, commons-lang, # 旧版项目统一使用 commons-lang3 fastjson2, # 项目明确不用 fastjson2 ] def check_file(filepath): errors [] try: with open(filepath, r, encodingutf-8) as f: content f.read() except Exception as e: return [f读取文件失败: {e}] for pattern in BANNED_PATTERNS: matches re.findall(pattern, content) if matches: errors.append(f未通过代码包含禁止模式 {pattern}请在 ./{filepath} 中清除调试代码) for dep in BANNED_DEPENDENCIES: if dep in content: errors.append(f未通过检测到禁止依赖关键词 {dep}请在 ./{filepath} 中删除或替换) # 检查方法长度Java建议以方法体为准这里简单用大括号统计 if filepath.endswith(.java): # 类文件总行数检查 line_count len(content.splitlines()) if line_count 200: errors.append(f未通过./{filepath} 行数达 {line_count}超过 200 行上限请拆分) return errors def main(): changed_files sys.argv[1:] if not changed_files: print(用法python ai_code_audit.py 文件1 文件2 ...) sys.exit(0) all_errors [] for filepath in changed_files: if not os.path.isfile(filepath): print(f跳过不存在的文件: {filepath}) continue all_errors.extend(check_file(filepath)) if all_errors: for err in all_errors: print(err) sys.exit(1) else: print(检查通过未发现规则违规。) if __name__ __main__: main()这个脚本我放在仓库scripts/ai_code_audit.py里然后接进了 CI 流程。具体做法是在 merge request 的 pipeline 里加一步先获取本次变更的文件列表然后跑这个脚本。不通过就 block 在合并之前AI 生成的代码虽然是自动的但入库必须有门槛。git diff --name-only origin/main...HEAD | grep -E \.(java|ts|tsx|py|go)$ changed_files.txt python scripts/ai_code_audit.py $(cat changed_files.txt)这一步很值得。哪怕规则文件没完全生效脚本仍然能把最明显的违规拦在门外。两条防线叠加AI 生成的代码基本就不需要大规模返工了。4. 规范上线后踩过的坑——常见问题与排查技巧4.1 AI 不遵守规则怎么办先自查三个地方规范刚上线那阵子团队反馈最多的一个问题就是“AI 还是不听劝”。我排查了几次之后发现 90% 的情况都出在三个地方。第一个是规则文件太长被工具截断了。很多 AI 工具在处理超长上下文时会做“自动摘要”但摘要的本质是“保留主要内容”而规则文件里的细节恰恰不会被保留。解决方法是把AGENTS.md压到 80 行内核心规则放在文件开头 30 行内。因为模型对上下文开头的注意力通常更高最重要的规则一定要放在前面。我甚至在文件注释里直接写了“越靠前的规则优先级越高”。第二个是提示词里没有显式引用规则。装上规则文件不等于 AI 会主动执行AI 只是“知道有这份文件”但它不知道你希望它做什么。所以在每次重要任务前一定要在提示词里加“请先阅读并严格遵循规则文件”这句话不能省。第三个是规则描述不够“可验证”。比如你写“不要使用过时 API”AI 并不知道哪个 API 过时。你必须写成“禁止使用 java.util.Date统一使用 java.time.LocalDateTime”。规则越具体AI 的执行率越高。4.2 规则库膨胀之后怎么维护分而治之定期清理规则文件用久了会像 wiki 一样越来越厚。我见过一个团队半年之后AGENTS.md写到了 600 多行结果 AI 读取效果直线下降。我的维护思路是“两级管理 定期回顾”。AGENTS.md只保留相对通用的高频规则比如命名、依赖、分层、日志那些特定场景的细节规则放到子文件里比如docs/ai-code-rules/kafka.md、docs/ai-code-rules/redis.md。子文件遵循“用到才读”的原则AI 在处理相关需求时才会加载平时不占用上下文。定期回顾也很重要。我给自己定了个规矩每个月末过一遍规则文件把连续一个月没被触发的规则删掉或归档。因为很多规则是在项目某阶段为了解决特定问题加的问题解决之后规则往往就变成了噪音。还有一个经验是规则文件的变更要走代码 Review 流程。它是团队规范的一部分不应该由某个人单独改。我这边是改成 PR然后让组内同事都过一眼同意后再合入。4.3 团队协作中的“软阻力”怎么让大家愿意用给 AI 定规范这件事技术上的难度其实一般真正难的是让团队每个人接受并坚持用。一开始我们组里就有同事说“AI 生成的代码我还要再改一遍那不如我自己写。”这话听起来没毛病但实际不是这样。AI 的价值在于它能快速完成那些重复性高、逻辑简单的任务比如 CRUD 接口、DTO 转换、模板代码。有了规范之后AI 生成的这部分代码几乎不需要改直接就能用确实是解放生产力。我的做法是找一个试点需求跑一版“没有规则 有规则”的对比数据。同一个需求让 AI 在无规则条件下生成再让 AI 在有规则条件下生成把两个版本的代码并排放在一起让大家直接看。没有规则的那版风格杂乱、命名各异、依赖乱飞有规则的那版基本上就是一个熟练工程师平时写出的代码。数据一摆说服力比任何会议都强。另外我把规则文件也放进了一个“自助下载”的公共目录别的项目要用直接拷贝根目录的AGENTS.md和docs/ai-code-rules/就能用把使用门槛降到最低。我在实际推进中还有一个很管用的小技巧在AGENTS.md的开头加了一段“规则使用说明”不是给 AI 看的而是给人看的——写了这个文件的目的、改动流程、责任人。这样后来接手的人不会一头雾水也减少了很多反复解释的成本。5. 一点个人体会这套给 AI 定代码规范的方法我前后迭代了差不多三周才达到自己满意的状态。最大的体会是给 AI 定规范本质上不是对 AI 提要求而是对团队代码资产做一次重新梳理。很多原来靠口头传承、靠代码 Review 慢慢改的习惯被写成显式规则之后不仅 AI 能遵守新人也更容易上手。如果让我总结最重要的三点我会说规则文件要短、要具体、要放在根目录越短的规则AI 执行率越高。提示词里显式引用规则 生成后自检比单纯放一个配置文件有效得多。永远要把审查脚本作为最后一道防线AI 不是人你没法靠“自觉”。最后再分享一个小经验当你发现 AI 反复违反某条规则时比起反复修改提示词不如先检查这条规则本身——它是不是太模糊了它有没有清晰的“禁止”指令它的正反示例够不够具体很多时候规则失败不是 AI 的问题而是规则还不够“面向 AI”。把规则改到 AI 能看懂、能执行的程度你会发现这个“不听话”的工具其实比你想象的可靠得多。