最近我把一份《AI代码规范》加进了项目仓库半个月下来AI生成的代码通过评审的比例肉眼可见地往上走。以前总听人说“AI写代码不靠谱”后来发现多半不是AI不行而是你没告诉它“这个项目该怎么写”。这份规范不是给人类同事看的而是专门写给AI看的。它能解决一个很现实的问题Copilot、Cursor、各种编程Agent确实能快速产出代码但产出的风格、依赖、边界处理往往和团队标准对不上。代码能跑但评审全是问题。给AI制定代码规范本质上是把团队的工程约束翻译成AI能理解、能执行的指令让大模型在生成代码的那一刻就遵守规则而不是靠事后人肉修。这篇文章把我做这件事的完整思路、规范文件长什么样、怎么放进项目、怎么让AI真正遵守以及踩过的坑全部写出来。不管你是后端、前端还是做AI应用开发的只要团队里有人在用AI写代码这份经验都能直接用。1. 为什么团队需要一份“专门给AI看”的代码规范1.1 让AI写代码的最大风险不是不智能而是太稳定人写代码有个特点状态好的时候写得漂亮状态差的时候糊弄。AI不一样它只要命中了你的提示词就会沿着一条“最像正确答案”的路径连续输出。问题在于这个“最像正确答案”是从海量开源代码里统计出来的它更像整个互联网的平均水平而不是你们团队的工程水准。我见过最典型的场景让AI补一个接口它开开心心地把三层架构拆成了五层每个类都有抽象接口还顺手加了一堆未来可能用到的泛型设计。代码风格无可挑剔但和项目现有结构格格不入。还有另一种极端AI为了省事把一堆逻辑全塞进ControllerService层形同虚设。这两种问题正好相反但根子上是同一件事AI不知道你们项目“长什么样”它对“好代码”的定义和你不一样。所以你会发现AI写的代码有一种让人头疼的稳定它稳定地忽略日志规范稳定地不去处理事务边界稳定地生成魔法数字稳定地复制粘贴相似逻辑。这种稳定比人类的三分钟热度可怕多了因为代码量一大问题就被成规模地复制。1.2 团队规范与人机协作的落差人读规范与AI读规范的区别大多数团队其实已经有代码规范比如《Java开发手册》、公司的《前端工程规范》这些文档写得没问题但直接拿给AI用效果很差。我试过把十几页的规范PDF扔给AI它“理解”了但生成代码时该犯的错一个没少。原因在于人类规范和AI规范是两种完全不同的东西。人类规范面向的是有判断力的工程师很多条目只需要写“原则上不允许”人就知道什么时候可以变通。AI没有这个判断力它看到“原则上”只会觉得这是个可以商量的事然后按自己的概率分布决定要不要遵守。AI需要的是确定性指令什么场景下必须怎么做什么写法必须禁止最好连示例都给它。另一个落差是检索成本。人类查规范靠目录和搜索AI读长文档时注意力会分散规范写到五十条之后前面的约束基本就失效了。所以给AI的规范必须短、必须分层、必须按项目场景排列。这跟我们给新人写Checklist是一个道理你不会让他一口气读五十页文档再上手而是给他一页纸的关键约束先干起来再说。1.3 给AI制定代码规范的适用范围与目标读者也不是所有项目都急着做这件事。我的建议是只要满足下面任一条件就值得投入团队已经在用Cursor、Copilot、通义灵码等AI编程工具代码库里AI生成代码比例超过30%项目有明确的工程标准比如严格的代码评审、自动化测试、部署流水线AI代码经常在评审阶段被打回团队里有多个开发者使用不同的AI工具希望输出风格趋于统一正在做AI Agent相关开发Agent本身会大量调用代码生成能力需要保证生成质量反过来如果只是一个个人项目或者Demo那完全没必要搞这么重直接让AI自由发挥你人工微调就够了。规范是团队协作的产物当参与的人多了、AI参与得多了约束的价值才会显现。2. 设计一套AI代码规范的核心思路与结构2.1 先从“输出审计”反向设计规范AI容易在哪里犯错我做这件事的第一步不是写规范而是做了一次“输出审计”。把团队最近一个月AI生成的代码全部拉出来过一遍统计出现频率最高的问题。结果很有参考价值这里直接分享一份通用版的“AI高频错误清单”命名随意变量名、方法名要么是通用的data、info、result要么是意义不明的缩写层次混乱不按项目已有分层结构走经常跨层调用或者在Controller里写复杂业务逻辑异常处理粗暴大段try-catch吞异常或者直接把异常往上抛到最外层日志缺失或过载要么一个关键操作毫无日志要么在循环里打日志魔法数字和硬编码常量不抽出配置直接写死在代码里重复代码不知道复用项目里已有的工具类把类似逻辑重新写一遍不必要的过度设计给简单功能套上繁琐的设计模式依赖随意喜欢引入新的第三方库哪怕只是用其中一个很简单的功能安全与边界缺失不做参数校验不处理空值不关注并发安全测试缺失或无效生成的单测只是为了提升覆盖率断言形同虚设这份清单就是规范的“需求文档”。规范不是在脑子里凭空想出来的而是针对这些真实问题逐个下药。每个高频错误对应一到两条约束写清楚“应该怎么做”和“什么情况绝对禁止”。2.2 规范文件的“四层结构”项目层、语言层、工程层、行为层刚开始我试着把规范写成一个三十条的Markdown文档结果AI根本记不住后面的内容。后来我参考了几家大厂开源出来的AI工程实践把规范拆成了四层每一层解决不同问题优先级也不同。层级解决的问题典型内容项目层这个项目特有的约定架构分层、命名前缀、目录结构、技术栈版本语言层某门语言通用最佳实践Java空值处理、Python类型标注、TS严格模式工程层流程和质量门槛测试要求、日志标准、CI检查、提交信息格式行为层AI交互时的纪律遇到不确定怎么问、不做范围外修改、主动说明风险为什么要分层因为AI工具的上下文窗口是有限的。项目层优先级最高必须在每次对话开始就让AI读到语言层和工程层只要有代表性示例即可不需要穷举行为层则是为了让AI在自由生成的同时保持“团队协作感”。实际落地时我不建议把四层压在一份文件里。项目层放仓库根目录的AGENTS.md语言层和工程层放docs/ai-coding-standards.md行为层放进工具的规则配置里。这样AI在不同阶段读到的内容刚好够用不会信息过载。2.3 编写规范的三条硬性原则可执行、给示例、给反例写了几个月规范文件后我总结出三条铁律只要违反任何一条这份规范的有效性都会大打折扣。第一条每一条规范必须可执行。什么叫可执行“代码要清晰”不可执行“禁止在Controller中编写超过20行的业务逻辑”就非常可执行。你在写规范时脑补一下如果AI违反了这条你能否在评审时明确指出来如果能这条就是合格的如果连你自己都说不清楚“算不算违反”AI更无法理解。第二条必须配正面示例。AI理解指令的方式是概率匹配一个具体的正面示例比十句抽象描述有用得多。比如规范写“方法命名要有意义”AI还是可能生成processData。但如果你给一个例子说明在这个项目里类似场景应该叫calculateOrderAmountAI就会按照这个模式走。第三条必须有反例。反面教材的力量远超正面描述。规范里可以明确写“不要这样写在for循环里打印日志”AI看到这个反例后会直接避开。正反例结合等于把问题的边界给AI画清楚了。3. 落地方案在项目中新增AI代码规范的具体实操3.1 推荐规范载体AGENTS.md、CLAUDE.md与项目级docs先说结论仓库根目录建一个AGENTS.md是目前和AI协作的最佳实践。这个命名已经成了事实标准Cursor、GitHub Copilot、开源的编程Agent基本都会自动读取它。如果你的团队主要用Claude Code那文件名叫CLAUDE.md更合适。不同工具各有偏好为了兼容可以放一份通用的AGENTS.md再在关键位置放“指针型”的文档指向详细规范。我见过有人在项目的README里写规范但效果不好。README是给人看的内容太杂AI分不清哪些是项目介绍、哪些是必须遵守的约束。专门建一个AI规范文件好处是收敛AI读到的第一个文件就是它不会被无关信息干扰。另外一个关键点是规范文件本身要纳入版本管理像代码一样走评审、走变更记录。AI规范不是一次写完就完了它是跟着项目演进持续更新的。我在团队里定了个规矩每两周的代码评审会上只要发现AI反复犯同类问题就有人负责把对应约束补进规范文件。3.2 一个可直接参考的AI代码规范模板下面这份模板是我在一个Spring Boot项目里实际用过的精简版你可以直接抄走改改。它不是一个面面俱到的Java开发手册而是针对AI的“高频犯错点对应约束”。我给它起名叫“面向AI的编码规则”放在AGENTS.md里# 项目 AI 编码规则 你是这个项目的资深开发工程师。请严格遵守以下规则规则冲突时按编号顺序优先。 ## 项目架构 1. 本项目为 Spring Boot 3 MyBatis-Plus分层Controller - Service - Mapper 2. Controller 只做参数接收和响应封装禁止写业务逻辑 3. Service 只处理业务逻辑禁止直接操作 HttpServletRequest/Response 4. Mapper 只做数据访问禁止在注解里写复杂动态SQL复杂SQL一律用 XML 文件 5. 新增代码必须放在合理的包结构中禁止在根包下新建类 ## 命名与风格 1. 类名用名词接口名用 I 开头方法名用动词开头 2. 变量名禁止使用 data、info、result、list 这类无意义命名必须体现业务含义 3. 表示订单金额、数量、费率等数值必须使用 BigDecimal禁止使用 double 4. 所有命名的缩写必须只在项目已存在缩写的范围内禁止自创缩写 ## 异常与日志 1. 禁止捕获异常后不做任何处理捕获后必须记录日志或抛出业务异常 2. 业务异常统一抛出 BizException由全局异常处理器统一处理 3. 禁止在循环体内打印日志日志必须包含关键业务标识订单号、用户ID等 ## 安全与边界 1. 对外接口的参数必须做校验禁止信任前端传值 2. 所有涉及金额、数量的运算必须先判空 3. 禁止在代码中硬编码任何配置项一律使用 application.yml 配置 ## 提交与协作 1. 只实现我明确要求的功能禁止顺手重构无关代码 2. 如果不确定某个改动的影响范围先说明你的疑问不要自行假设 3. 代码完成后用一句话说明你改了什么、影响哪些模块、是否有数据库变更你别看这份模板不长它每条都来自真实的评审失败案例。比如第2条“变量名禁止data、info”就是因为我发现AI在生成Mapper查询结果时特别喜欢用ListMapString, Object加通用命名。把这条写进去之后同类问题减少至少一半。前端项目也类似不过侧重点不一样。前端规范里我会额外强调组件文件用大驼峰、样式禁止全局污染、状态管理不许塞所有数据、副作用必须放在生命周期或Hooks里统一管理、接口请求统一走封装的Request函数而不是裸用axios。语言框架不同但“针对性给反例”的思路是通用的。3.3 让现有AI工具自动读取规范Cursor、Copilot、编程Agent的配置要点规范写好了还得让AI在生成代码时真的看到。不同工具读取方式略有差异我逐个说下实测经验。Cursor最新版本会自动读取仓库根目录的AGENTS.md作为上下文。使用时要确认项目索引已经把仓库根目录包含进去。如果发现AI没遵循规范先在设置里看Rules是否生效然后直接在对话里补充“请阅读AGENTS.md并按其中规则实现”。还能在Cursor Rules里把规范的核心条目直接加进去这样规则会和代码上下文一起注入效果更稳定。GitHub Copilot它更倾向于在编辑器里即时补全对长文档的读取能力弱一些。我有两个办法一个是在仓库根目录放一个.github/copilot-instructions.mdCopilot会读取这个文件再一个是把规范里最关键的十条浓缩到/.github/workflows旁边的说明里或者在每个子目录放一份短指令比如src/main/java/README.md写“这个目录下的代码禁止xxx”。编程Agent比如开源的代码Agent走的是更通用的方式。大多数Agent支持指定“指令文件”在启动时通过参数或配置文件传入。你用哪个Agent去翻它的rules或instructions配置项就行。还有一种做法是把规范文件路径写进系统提示词里让Agent先读文件再开始干活。另外一个很容易忽略的点规范文件本身不要用中文以外的复杂格式。AI读Markdown没问题但千万不要给PDF、不要给超过50行的单段内容。我踩过坑把规范写成了一个大表格结果AI经常漏读后面的行改成短段落加“必须”“禁止”这种强指令词后效果好了很多。4. AI代码规范的演进与维护规范是活的4.1 建立“规范驱动的开发循环”我给团队搭了一个很简单的循环叫“评审-沉淀-复用”。每次代码评审只要发现AI生成的问题不管是命名、边界还是安全风险都把这个问题转化成一条规范写进对应层级的文件里。这样规范不是一次性大工程而是一直在长。迭代几次之后你会发现规范文件越来越长这时候要做减法。通告里规定超过三十条的规范必须做合并或删减只保留那些“违反成本高”和“高频出现”的条目。那些无所谓对错的风格偏好比如“缩进是2还是4空格”根本不需要写进去交给格式化工具处理就好。为了让这个循环跑起来我建议在代码评审的模板里加一栏“是否为AI生成代码如果是本次问题是否应沉淀为AI规范”不需要强制填写但只要有一个人记得写规范就能持续进化。4.2 常见问题与排查技巧实录执行过程中遇到的问题我整理成了一份速查表基本都是实战里踩过的症状可能原因排查与解决AI完全不遵守规范规范文件路径不对或者工具版本不支持自动读取确认文件在仓库根目录名字与工具要求一致在提示词中显式引用规范文件只遵守前半部分忽略后半部分规范太长超出模型注意力范围精简条目把不重要的内容移出主文件把规范分层核心约束保持在20条以内有示例的条款遵守得好没示例的经常犯模型对抽象指令理解不足给关键条目补正面示例和反例AI和人类规范冲突两套规范各自维护内容不一致明确AI规范是“面向机器执行版”人类规范为准定期同步规范更新了但AI还在用旧规范提示词缓存或对话上下文仍是旧文档更新规范后新建对话测试对历史会话显式要求重新加载规范团队成员各自用不同AI工具表现不一不同工具的上下文注入方式不同统一使用AGENTS.md并在每个工具里配置指向该文件的Rules这几个问题里最值得警惕的是第一条。很多AI工具并不会自动读文件。你写了一个规范觉得自己已经做了全部防护结果AI连看都没看。我的习惯是写完规范后先用一个完全相同的新对话测试让它总结规范内容看它有没有读到。这个测试只要十秒钟但能避免后面一大堆返工。4.3 用CI和静态检查兜底AI规范不能只靠自觉不管规范写得多清楚都要承认一个事实大模型的执行有概率性。写进提示词里的规范即使是最强的模型遵守率也很难到100%。所以真正的工程防线还是要在代码合并之前卡一道自动检查。我在项目里做了这么几件事后端用Checkstyle或Spotless检查命名、格式、代码违规模式前端用ESLint和Stylelint规则和给AI的规范同步维护通过Git Hooks在提交前检查规范文件是否被AI直接绕过在CI里加一个“AI规范合规检查”核心就一条扫描Agent生成的代码看有没有命中反例模式用静态检查兜底还有一个额外的好处当AI生成代码后在本地跑一遍检查报错信息会直接喂回给AIAI可以根据报错自动修正。这比靠提示词更可靠因为报错是确定性的不是概率性的。我在实际操作中经常用这个流程让AI写代码 - 本地lint - 报错丢回给AI - AI自行修复。一轮下来代码质量比单纯对话生成好一个量级。5. 配套技巧让AI“长在”规范里5.1 把上下文塞进提示词常用Prompt模板有些场景AI工具可能没读到规范文件或者你希望临时强调某些规范。这时候需要在提示词里手动注入规范。我习惯用一套固定模板请阅读仓库根目录的 AGENTS.md并严格遵循其中的项目架构、命名与异常规则实现以下任务。 任务 这里写具体需求 要求 1. 只修改与需求相关的文件不进行任何无关重构 2. 所有业务异常统一抛 BizException禁止吞异常 3. 生成完成后用列表说明修改了哪些文件、影响哪些接口这套模板在工作里被我用了很长时间。它的核心思想不是让AI重新“学习”规范而是明确告诉它“哪里能拿到规范、必须怎么用”。AI对文件路径的指令响应非常直接它哪怕没读过AGENTS.md也会先去读一遍再干活。5.2 给AI一个“代码自检清单”我发现直接要求AI“写高质量代码”没用但要求它按Checklist自检非常有效。原因很简单模型在生成结束后再做一次自检相当于多了一步推理更容易发现之前写错的地方。我在规范文件里会附带一个自检清单并要求AI在输出代码后逐项确认我是否只使用了项目里已有的技术栈没有引入新依赖我的变量命名是否体现了完整业务含义而不是data、info这类通用词是否所有异常分支都做了处理没有吞异常或裸抛是否处理了所有可能为空的输入我的Controller里有没有混入业务逻辑代码里是否存在魔法数字或硬编码配置有没有复制粘贴重复代码能否复用已有工具类每次生成后让AI过一遍这个清单相当于白赚了一次代码自查。实际运行中这个技巧能把单测覆盖率提升不少因为很多模型在生成完功能代码后不会主动考虑测试而清单里明确要求了它就会补上。5.3 从“规范”到“技能”在Agent中固化规范如果你团队用的AI工具支持自定义指令或者技能包强烈建议把规范固化进去。比如有些Agent平台支持把规范做成一整套技能下次直接唤起连提示词都不用写。这一点对AI应用开发方向特别有用。我们团队做过一个内部代码生成Agent它就是读一套基于规范的“技能文件”来工作的。每个任务进来Agent先加载技能文件里的规范再开始写代码最后按自检清单复核输出。效果很稳定甚至可以说比很多开发者的平均水平还要稳定。固化规范的另外一个好处是新人友好。团队新同事不需要花一周时间背编码规范他只要用AI工具规范就会跟着代码一起生成出来。代码评审时指出问题AI也会自动根据规范条目标注是哪条没遵守学习和纠错成本都大幅降低。写在最后我自己最大的体会是给AI制定代码规范本质上是把团队过去踩过的坑用一种机器能理解的方式沉淀下来。它不是一劳永逸的需要跟着项目反复迭代但它带来的收益是复利式的——规范每改进一次后面所有AI生成的代码质量都会同步提升一次。根据我的经验一开始不用追求完美先抓最痛的三五个问题写进规范跑通流程。等团队适应了再逐步扩大覆盖范围。这套东西越早开始做项目的代码债就越少。
