1. 为什么我急着给AI定规矩先说个真实场景。项目上线前的一个晚上我在review新功能的PR越看越不对劲同一个交互组件这一版用的是fetchUserList上一版叫getUserData接口封装一会儿走service/order.ts一会儿又在页面里直接axios.get更离谱的是有个AI生成的工具函数没做空值处理线上差点崩了。队友一脸无辜地说“AI写的我让它改它每次都按自己的风格来。”这个场景你应该不陌生。现在团队里用AI编程已经成了常态AI能快速产出大量可运行代码但问题是AI对项目已有的约定一无所知它只会“写代码”不会“按项目的规矩写代码”。于是代码库像被好几个人用不同笔迹写满了批注看着能跑维护起来想哭。我当时的判断是问题不在AI在我——我没有给AI一份“工作手册”。所谓给AI制定的代码规范本质上是把团队沉淀下来的工程经验——命名习惯、目录约定、错误处理策略、提交规范——整理成一份AI能读懂、能严格执行的指令集。它不是给人看的规范文档而是给AI Agent的“岗位说明书”。有了它AI生成的代码才能从“能用”变成“好用”从“个人风格”变成“团队风格”。这篇文章就聊聊我是怎么在项目里落地这份规范的它长什么样、怎么写的、怎么让AI听话、以及踩过的坑。适合正在被AI生成代码质量困扰的开发者、技术负责人也适合前端、后端、全栈工程师做参考。2. 给AI立规矩的第一步先想清楚要约束什么2.1 AI代码规范和人用规范的核心差异人和AI读规范的方式完全不同。人有上下文感知能力看完规范脑子里会留个印象写的时候大概率能遵守AI不同它每次生成代码都像失忆了一次只有明确、可操作、放在上下文里的规则才有效果。所以给AI制定的代码规范不能是“请保持代码整洁”这种模糊表述而必须是“所有API请求必须经过src/services/目录下对应文件封装禁止在组件内直接调用axios”这样的硬性约束。我踩过最典型的坑就是规范写得像散文AI看完等于没看输出还是我行我素。另外人用规范是“偶尔查”AI用规范是“每次都要加载”。这意味着规范文档不能太长不能有废话每个条目都要直击要害。我在实践中发现超过80条的规范AI就开始选择性忽略前20条的遵守率最高越往后越低。所以规范的顺序也很讲究最重要的、必须100%执行的内容要放在最前面。2.2 先盘点项目的痛点再决定规范条目我不建议一上来就照搬网上的“AI编程规范模板”而是先问自己三个问题当前AI生成的代码里最影响我的是什么最影响团队协作的是什么最影响项目稳定的是什么我在这个项目里的痛点排序是这样的第一是命名和目录混乱。AI经常为同一个概念生成不同命名比如订单模块一会儿OrderInfo一会儿OrderDetail一会儿orderData导致代码搜索和review都很难受。第二是技术栈漂移。项目用的UI组件库是Ant DesignAI有时候会引入MUI的组件状态管理统一用ZustandAI偶尔会写Redux的写法。第三是安全隐患。AI生成代码时经常忽略输入校验、SQL参数化这类细节甚至会把敏感信息硬编码进去。把痛点理清之后规范条目就自然有了。每个条目都对应一个真实坑落地的时候团队接受度也高——因为大家都遇到过这些问题。2.3 规范文件的形态AGENTS.md和CLAUDE.md双轨制目前主流AI编程工具基本都有“项目级指令文件”的约定。我做了一个双轨方案仓库根目录放一个AGENTS.md面向通用AI编程助手CLAUDE.md专用于Claude Code这类深度集成工具。两者内容基本一致只是在Claude版本里可以写更多工具调用相关的约束。还有一点很重要这个规范文件必须跟着代码仓库走入库评审、版本管理。这样新成员拉下代码时AI第一时间就能读到规范不用额外配置。而且规范更新时走PR流程谁改的、为什么改都留下痕迹。3. 一份可以直接抄作业的AI代码规范长什么样3.1 规范的顶层结构我设计的规范分五个模块每个模块解决一类问题。整体目标是让AI在生成代码前就知道我在什么项目里、用什么技术栈、按什么风格写、有哪些雷区不能踩。# AI代码规范项目工作守则 ## 全局原则 - 本规范优先级高于AI工具默认行为 - 修改已有代码前先阅读并遵循原文件风格 - 不确定时询问不擅自决定 ## 技术栈锁定 列举项目核心技术选型及禁止项 ## 命名与结构 目录、文件、变量、组件命名规则 ## 代码风格与质量 错误处理、边界条件、注释标准 ## 提交规范 commit message格式、PR描述要求3.2 技术栈锁定防止AI自由发挥AI编程工具最让人头疼的一点是它会“跨栈发挥”。明明项目用的是Vue 3 Composition APIAI能给你生成Options API的写法明明图标库用的是ant-design/iconsAI可能顺手引入react-icons。技术栈锁定模块就是干这个的。我列了几个硬性规则UI组件必须使用Ant Design 5.x禁止引入其他组件库状态管理必须使用Zustand禁止Redux/MobX请求库必须使用项目封装的src/utils/request.ts禁止直接调用axios或fetch样式方案必须使用CSS Modules禁止使用Tailwind或styled-components日期处理必须使用dayjs禁止使用moment.js技术栈锁定不能只写“用什么”还要写“不用什么”。AI对禁止项的理解比鼓励项更精确你告诉它“不要用moment.js”它通常就真的不会用。我把这条经验写进了规范后续AI生成代码的技术栈一致性明显提升。3.3 命名与目录规范让AI“说同一种语言”命名是代码可读性的第一道防线。我给AI定了非常明确的命名规则每条都配了正反例子因为AI学习示例的能力远强于理解抽象描述。变量命名和函数命名采用camelCase组件和类型采用PascalCase常量采用UPPER_SNAKE_CASE。这属于基础规则AI一般不会错。容易错的是语义层面布尔变量必须以is、has、can开头获取数据的函数必须以fetch、get、query开头事件处理函数必须以handle开头。目录结构方面我明确要求API请求必须放在src/services/下按业务域分文件如orderService.ts、userService.ts禁止在组件代码里直接写请求逻辑。工具函数放src/utils/通用类型放src/types/。这里有个细节我在规范里写了一条“新功能组件必须放在src/components/[业务域]/下禁止在页面文件里堆砌超过200行的子组件”。这个200行的数字不是我拍脑袋定的是团队code review时发现AI生成的页面经常一个文件上千行可维护性极差。3.4 错误处理与边界条件AI最弱的一环AI生成代码时最常犯的错就是假设输入永远是合法的。用户永远不会传空值、接口永远会返回预期结构、缓存永远能命中。等这些假设被打破线上就会出事故。我在规范里专门写了一节“边界条件必查清单”要求AI在生成任何函数或组件时必须自查以下内容接口调用是否有loading状态和错误状态列表渲染时是否有空数组兜底从对象中取属性时对象本身是否为null输入框是否有长度限制和格式校验文件读取、缓存读取是否有异常捕获写法上我给了具体示例让AI参照执行。比如请求封装模板我会在规范里贴一段示例代码要求AI遵循同样的模式而不是每次自由发挥。注意错误处理最容易出现的问题不是“没有try-catch”而是“catch住了却什么都不做”。我专门加了一条catch到的错误必须打印日志、设置错误状态或进行用户提示禁止空catch。3.5 格式、注释与代码风格约定关于格式我不依赖AI的自觉而是引入工具强制。项目配置了ESLint和Prettier规范里明确要求AI生成代码后必须经工具格式化并且不允许通过disable注释跳过检查。这条规则能让AI收敛很多“野路子”写法。注释方面我要求AI对每个对外暴露的函数写清楚参数含义和返回值说明对超过10行的复杂逻辑写“为什么这么写”的说明而不是“做了什么”的流水账注释。这一点也是AI的通病它会写一堆“// 这里调用了接口”这种废话注释对“为什么不用方案A而用方案B”完全不解释。我给AI提供的注释模板/** * 获取订单列表 * param params 查询参数包含页码page和每页数量pageSize * returns 订单列表数据和总数 * throws 当网络异常或接口返回错误码时抛出 */还有一条容易被忽略的禁止在注释或代码中出现过时信息。AI经常复制旧代码把已经不存在的函数名或业务规则也带过来我在规范里要求AI如果发现注释与代码行为不一致必须更新注释而不是只改代码。4. 怎么让AI真正“听”你的规范4.1 从Prompt层面约束开头就把规范“喂”给AI规范文件写好了只是个开始。关键在于怎么让AI在实际编码中遵守它。我调试出来的方法是分两步走。第一步在每次和AI对话的开头用一段固定的“上下文注入模板”把规范加载进去第二步在对话过程中持续用规则约束AI的输出而不是等它写完再去改。上下文注入模板长这样你是本项目的高级前端工程师。在开始编码前请阅读并严格执行仓库根目录下的AGENTS.md文件中的规则。本项目使用TypeScript React 18 Zustand Ant Design 5所有代码必须符合项目规范禁止引入项目未使用的依赖。这段模板放在每轮对话的第一条消息里AI后续生成的代码合规率会显著提升。原因很简单AI的上下文窗口是有限的你Project里堆了太多文件时它可能忽略掉规范文件。主动注入能确保规范占住上下文的重要位置。4.2 持续纠偏对话中的“规则锚点”规范注入一次不等于万事大吉。在一次长对话中AI会逐渐“跑偏”前几轮还遵守规范越往后越随意。我的办法是在对话中设置“规则锚点”——每过几轮或者在AI要生成关键文件代码前主动重申一遍核心约束。比如在AI即将生成一个新页面时我会插一句“请使用当前项目的目录规范页面文件放在src/pages/下组件代码放在src/components/目录中API请求调用src/services/下的封装函数。组件使用Ant Design的Table、Form等组件不要自造轮子。”这样做的效果非常明显。AI对近期指令的遵循度远高于远期指令每过一段时间就锚定一下核心规范比一次性全量灌输高效得多。4.3 用代码审查让AI“长记性”规范最终要落到代码上。我强烈建议为AI生成代码建立审查流程而且要立即反馈结果。AI不像人它不会“总结经验”每次对话都是独立的。但在同一对话里如果你告诉它“上一步的代码违反了规范某条规则应该改成这样”后续代码的合规率会有显著提升。我会在审查时把问题划分为硬伤和软伤硬伤技术栈漂移、命名不规范、有安全隐患、绕过项目封装软伤代码重复、可读性差、缺注释、结构不够清晰对于硬伤我会直接要求AI重写对于软伤我会在审查意见里描述具体修改建议。这个方法执行一个月后AI生成的代码硬伤从每10次出现6次下降到1次效果立竿见影。4.4 针对性工具加持AI插件与规范联动项目里还引入了一些辅助检查的工具。比如我配置了ESLint规则集让AI的代码在生成后就被强制约束还在CI流水线里加了一步“AI代码风格检查”用自动化脚本扫描AI生成文件中是否存在违反技术栈锁定的import语句。一旦发现构建直接失败AI需要自行修复。这个机制的思路是与其指望AI自觉不如让流程卡住它。人工审查是兜底自动化检查才是常态。我在实践中发现AI对报错信息的响应比对口头点评要敏感得多——只要说“构建失败了原因是引入了禁止使用的依赖”它基本能正确修正。提醒不要指望一条规范文件解决所有问题。规范只是基础真正的质量关口在工程流程里。规范负责“告诉AI正确的方式”流程负责“保证不符合规范的代码进不了主干”。5. 常见翻车现场与排查心得5.1 AI“选择性失忆”规范读了但没用这是最高频的问题。明明规范就在仓库根目录AI还是会产出不符合规范的代码。排查下来主要有几个原因一是AI一次读取的上下文有限规范被其他内容挤掉了二是规范内容太模糊AI不知道具体该怎么执行。我的解决方法前面也提到了对话开始前主动注入规范核心内容把最关键的约束写在Prompt里而不是只放在文件中。另外规范文件里多用具体示例少用抽象原则。AI不理解“保持代码整洁”但能理解“函数超过50行必须拆分成多个函数”。还有一个很实用的技巧把规范文件拆成总规范和分模块规范。总规范放在根目录面向所有AI分模块规范放在对应目录下AI在读取该目录代码时会自然看到。比如src/services/README.md里就写明“所有服务文件禁止直接操作DOM”这类模块级约束AI在这个目录里写代码时遵守率极高。5.2 过度遵守AI把规范用错了地方还有一种反向的翻车——AI太刻板地遵守规范把不该统一的东西也统一了。比如我要求“布尔变量以is开头”AI在命名所有标志位时都套用这个模式结果生成了isIsOpen、isHasPermission这种怪异命名。这种情况的根因是规范写得太死缺少例外说明。后来我在规范里补充了“命名可读性优先于规则一致性”这一条兜底原则AI再没犯过这个毛病。5.3 规范文件自身如何维护规范不是写完就固定不变的。随着项目演进技术栈可能升级、目录结构可能调整、团队约定可能变化规范文件也要跟着更新。我的维护节奏是每两周review一次把过去两周AI生成代码中出现的问题重新过一遍看看哪些高频问题规范里还没覆盖哪些规范条目已经失效。凡是新出现的坑就补充一条新规范凡是AI和人都已经内化的规则就移出规范减少噪音。规范也要走版本管理和变更评审不能一个人拍脑袋改。因为它的受众不只是AI新同学也要靠它理解项目约束随意改动会带来混乱。5.4 速查表典型问题和对应解法我把实际操作中最常遇到的问题整理成了一张速查表供大家参考问题表现可能原因优先处理AI引入项目未使用的依赖技术栈锁定规则缺失或未注入在规范中增加禁用清单Prompt里强约束生成的组件全是千人千面的命名命名规范缺少正反示例补充具体命名对照表配示例代码接口请求没有loading和错误处理边界条件清单未覆盖在规范中增加必查清单并要求AI自查代码风格和项目不一致ESLint/Prettier约束未强制配置自动化检查CI中阻断不合规提交规范读了但总被忽略上下文或优先级不够把关键规则前置到Prompt开头设置规则锚点AI在无提示下“自由发挥”规范缺少兜底原则增加“不确定时先问”的全局原则6. 最后说点实操中的个人体会这套给AI制定代码规范的方法我实际用了大概三个多月最大的体会是别把它当成一次性的文档而要当成一个持续迭代的机制。最有意思的变化是AI生成的代码从“一眼就能看出是AI写的”逐渐变成了“和我们团队的代码融为一体”这说明规范不再只是约束它已经变成了AI理解项目的“语言模型”。还有一个体会给AI定规范其实是在帮团队重新梳理一遍自己的工程体系。因为你要把之前靠“默契”和“常识”传递的经验变成显性、明确、可执行的内容这个整理过程本身就会暴露很多问题——比如你发现团队对“到底用不用dayjs”都没有统一过那AI就更不知道了。所以如果你正准备给AI定规矩我的建议是不用追求一步到位先抓住最痛的三个问题写成规范让AI跑起来然后每周迭代。规范会逐渐变成新的团队资产它沉淀的不仅是一份约束更是开发团队对“什么是好代码”的共同理解。
AI代码规范实战：如何让AI生成的代码符合团队标准
1. 为什么我急着给AI定规矩先说个真实场景。项目上线前的一个晚上我在review新功能的PR越看越不对劲同一个交互组件这一版用的是fetchUserList上一版叫getUserData接口封装一会儿走service/order.ts一会儿又在页面里直接axios.get更离谱的是有个AI生成的工具函数没做空值处理线上差点崩了。队友一脸无辜地说“AI写的我让它改它每次都按自己的风格来。”这个场景你应该不陌生。现在团队里用AI编程已经成了常态AI能快速产出大量可运行代码但问题是AI对项目已有的约定一无所知它只会“写代码”不会“按项目的规矩写代码”。于是代码库像被好几个人用不同笔迹写满了批注看着能跑维护起来想哭。我当时的判断是问题不在AI在我——我没有给AI一份“工作手册”。所谓给AI制定的代码规范本质上是把团队沉淀下来的工程经验——命名习惯、目录约定、错误处理策略、提交规范——整理成一份AI能读懂、能严格执行的指令集。它不是给人看的规范文档而是给AI Agent的“岗位说明书”。有了它AI生成的代码才能从“能用”变成“好用”从“个人风格”变成“团队风格”。这篇文章就聊聊我是怎么在项目里落地这份规范的它长什么样、怎么写的、怎么让AI听话、以及踩过的坑。适合正在被AI生成代码质量困扰的开发者、技术负责人也适合前端、后端、全栈工程师做参考。2. 给AI立规矩的第一步先想清楚要约束什么2.1 AI代码规范和人用规范的核心差异人和AI读规范的方式完全不同。人有上下文感知能力看完规范脑子里会留个印象写的时候大概率能遵守AI不同它每次生成代码都像失忆了一次只有明确、可操作、放在上下文里的规则才有效果。所以给AI制定的代码规范不能是“请保持代码整洁”这种模糊表述而必须是“所有API请求必须经过src/services/目录下对应文件封装禁止在组件内直接调用axios”这样的硬性约束。我踩过最典型的坑就是规范写得像散文AI看完等于没看输出还是我行我素。另外人用规范是“偶尔查”AI用规范是“每次都要加载”。这意味着规范文档不能太长不能有废话每个条目都要直击要害。我在实践中发现超过80条的规范AI就开始选择性忽略前20条的遵守率最高越往后越低。所以规范的顺序也很讲究最重要的、必须100%执行的内容要放在最前面。2.2 先盘点项目的痛点再决定规范条目我不建议一上来就照搬网上的“AI编程规范模板”而是先问自己三个问题当前AI生成的代码里最影响我的是什么最影响团队协作的是什么最影响项目稳定的是什么我在这个项目里的痛点排序是这样的第一是命名和目录混乱。AI经常为同一个概念生成不同命名比如订单模块一会儿OrderInfo一会儿OrderDetail一会儿orderData导致代码搜索和review都很难受。第二是技术栈漂移。项目用的UI组件库是Ant DesignAI有时候会引入MUI的组件状态管理统一用ZustandAI偶尔会写Redux的写法。第三是安全隐患。AI生成代码时经常忽略输入校验、SQL参数化这类细节甚至会把敏感信息硬编码进去。把痛点理清之后规范条目就自然有了。每个条目都对应一个真实坑落地的时候团队接受度也高——因为大家都遇到过这些问题。2.3 规范文件的形态AGENTS.md和CLAUDE.md双轨制目前主流AI编程工具基本都有“项目级指令文件”的约定。我做了一个双轨方案仓库根目录放一个AGENTS.md面向通用AI编程助手CLAUDE.md专用于Claude Code这类深度集成工具。两者内容基本一致只是在Claude版本里可以写更多工具调用相关的约束。还有一点很重要这个规范文件必须跟着代码仓库走入库评审、版本管理。这样新成员拉下代码时AI第一时间就能读到规范不用额外配置。而且规范更新时走PR流程谁改的、为什么改都留下痕迹。3. 一份可以直接抄作业的AI代码规范长什么样3.1 规范的顶层结构我设计的规范分五个模块每个模块解决一类问题。整体目标是让AI在生成代码前就知道我在什么项目里、用什么技术栈、按什么风格写、有哪些雷区不能踩。# AI代码规范项目工作守则 ## 全局原则 - 本规范优先级高于AI工具默认行为 - 修改已有代码前先阅读并遵循原文件风格 - 不确定时询问不擅自决定 ## 技术栈锁定 列举项目核心技术选型及禁止项 ## 命名与结构 目录、文件、变量、组件命名规则 ## 代码风格与质量 错误处理、边界条件、注释标准 ## 提交规范 commit message格式、PR描述要求3.2 技术栈锁定防止AI自由发挥AI编程工具最让人头疼的一点是它会“跨栈发挥”。明明项目用的是Vue 3 Composition APIAI能给你生成Options API的写法明明图标库用的是ant-design/iconsAI可能顺手引入react-icons。技术栈锁定模块就是干这个的。我列了几个硬性规则UI组件必须使用Ant Design 5.x禁止引入其他组件库状态管理必须使用Zustand禁止Redux/MobX请求库必须使用项目封装的src/utils/request.ts禁止直接调用axios或fetch样式方案必须使用CSS Modules禁止使用Tailwind或styled-components日期处理必须使用dayjs禁止使用moment.js技术栈锁定不能只写“用什么”还要写“不用什么”。AI对禁止项的理解比鼓励项更精确你告诉它“不要用moment.js”它通常就真的不会用。我把这条经验写进了规范后续AI生成代码的技术栈一致性明显提升。3.3 命名与目录规范让AI“说同一种语言”命名是代码可读性的第一道防线。我给AI定了非常明确的命名规则每条都配了正反例子因为AI学习示例的能力远强于理解抽象描述。变量命名和函数命名采用camelCase组件和类型采用PascalCase常量采用UPPER_SNAKE_CASE。这属于基础规则AI一般不会错。容易错的是语义层面布尔变量必须以is、has、can开头获取数据的函数必须以fetch、get、query开头事件处理函数必须以handle开头。目录结构方面我明确要求API请求必须放在src/services/下按业务域分文件如orderService.ts、userService.ts禁止在组件代码里直接写请求逻辑。工具函数放src/utils/通用类型放src/types/。这里有个细节我在规范里写了一条“新功能组件必须放在src/components/[业务域]/下禁止在页面文件里堆砌超过200行的子组件”。这个200行的数字不是我拍脑袋定的是团队code review时发现AI生成的页面经常一个文件上千行可维护性极差。3.4 错误处理与边界条件AI最弱的一环AI生成代码时最常犯的错就是假设输入永远是合法的。用户永远不会传空值、接口永远会返回预期结构、缓存永远能命中。等这些假设被打破线上就会出事故。我在规范里专门写了一节“边界条件必查清单”要求AI在生成任何函数或组件时必须自查以下内容接口调用是否有loading状态和错误状态列表渲染时是否有空数组兜底从对象中取属性时对象本身是否为null输入框是否有长度限制和格式校验文件读取、缓存读取是否有异常捕获写法上我给了具体示例让AI参照执行。比如请求封装模板我会在规范里贴一段示例代码要求AI遵循同样的模式而不是每次自由发挥。注意错误处理最容易出现的问题不是“没有try-catch”而是“catch住了却什么都不做”。我专门加了一条catch到的错误必须打印日志、设置错误状态或进行用户提示禁止空catch。3.5 格式、注释与代码风格约定关于格式我不依赖AI的自觉而是引入工具强制。项目配置了ESLint和Prettier规范里明确要求AI生成代码后必须经工具格式化并且不允许通过disable注释跳过检查。这条规则能让AI收敛很多“野路子”写法。注释方面我要求AI对每个对外暴露的函数写清楚参数含义和返回值说明对超过10行的复杂逻辑写“为什么这么写”的说明而不是“做了什么”的流水账注释。这一点也是AI的通病它会写一堆“// 这里调用了接口”这种废话注释对“为什么不用方案A而用方案B”完全不解释。我给AI提供的注释模板/** * 获取订单列表 * param params 查询参数包含页码page和每页数量pageSize * returns 订单列表数据和总数 * throws 当网络异常或接口返回错误码时抛出 */还有一条容易被忽略的禁止在注释或代码中出现过时信息。AI经常复制旧代码把已经不存在的函数名或业务规则也带过来我在规范里要求AI如果发现注释与代码行为不一致必须更新注释而不是只改代码。4. 怎么让AI真正“听”你的规范4.1 从Prompt层面约束开头就把规范“喂”给AI规范文件写好了只是个开始。关键在于怎么让AI在实际编码中遵守它。我调试出来的方法是分两步走。第一步在每次和AI对话的开头用一段固定的“上下文注入模板”把规范加载进去第二步在对话过程中持续用规则约束AI的输出而不是等它写完再去改。上下文注入模板长这样你是本项目的高级前端工程师。在开始编码前请阅读并严格执行仓库根目录下的AGENTS.md文件中的规则。本项目使用TypeScript React 18 Zustand Ant Design 5所有代码必须符合项目规范禁止引入项目未使用的依赖。这段模板放在每轮对话的第一条消息里AI后续生成的代码合规率会显著提升。原因很简单AI的上下文窗口是有限的你Project里堆了太多文件时它可能忽略掉规范文件。主动注入能确保规范占住上下文的重要位置。4.2 持续纠偏对话中的“规则锚点”规范注入一次不等于万事大吉。在一次长对话中AI会逐渐“跑偏”前几轮还遵守规范越往后越随意。我的办法是在对话中设置“规则锚点”——每过几轮或者在AI要生成关键文件代码前主动重申一遍核心约束。比如在AI即将生成一个新页面时我会插一句“请使用当前项目的目录规范页面文件放在src/pages/下组件代码放在src/components/目录中API请求调用src/services/下的封装函数。组件使用Ant Design的Table、Form等组件不要自造轮子。”这样做的效果非常明显。AI对近期指令的遵循度远高于远期指令每过一段时间就锚定一下核心规范比一次性全量灌输高效得多。4.3 用代码审查让AI“长记性”规范最终要落到代码上。我强烈建议为AI生成代码建立审查流程而且要立即反馈结果。AI不像人它不会“总结经验”每次对话都是独立的。但在同一对话里如果你告诉它“上一步的代码违反了规范某条规则应该改成这样”后续代码的合规率会有显著提升。我会在审查时把问题划分为硬伤和软伤硬伤技术栈漂移、命名不规范、有安全隐患、绕过项目封装软伤代码重复、可读性差、缺注释、结构不够清晰对于硬伤我会直接要求AI重写对于软伤我会在审查意见里描述具体修改建议。这个方法执行一个月后AI生成的代码硬伤从每10次出现6次下降到1次效果立竿见影。4.4 针对性工具加持AI插件与规范联动项目里还引入了一些辅助检查的工具。比如我配置了ESLint规则集让AI的代码在生成后就被强制约束还在CI流水线里加了一步“AI代码风格检查”用自动化脚本扫描AI生成文件中是否存在违反技术栈锁定的import语句。一旦发现构建直接失败AI需要自行修复。这个机制的思路是与其指望AI自觉不如让流程卡住它。人工审查是兜底自动化检查才是常态。我在实践中发现AI对报错信息的响应比对口头点评要敏感得多——只要说“构建失败了原因是引入了禁止使用的依赖”它基本能正确修正。提醒不要指望一条规范文件解决所有问题。规范只是基础真正的质量关口在工程流程里。规范负责“告诉AI正确的方式”流程负责“保证不符合规范的代码进不了主干”。5. 常见翻车现场与排查心得5.1 AI“选择性失忆”规范读了但没用这是最高频的问题。明明规范就在仓库根目录AI还是会产出不符合规范的代码。排查下来主要有几个原因一是AI一次读取的上下文有限规范被其他内容挤掉了二是规范内容太模糊AI不知道具体该怎么执行。我的解决方法前面也提到了对话开始前主动注入规范核心内容把最关键的约束写在Prompt里而不是只放在文件中。另外规范文件里多用具体示例少用抽象原则。AI不理解“保持代码整洁”但能理解“函数超过50行必须拆分成多个函数”。还有一个很实用的技巧把规范文件拆成总规范和分模块规范。总规范放在根目录面向所有AI分模块规范放在对应目录下AI在读取该目录代码时会自然看到。比如src/services/README.md里就写明“所有服务文件禁止直接操作DOM”这类模块级约束AI在这个目录里写代码时遵守率极高。5.2 过度遵守AI把规范用错了地方还有一种反向的翻车——AI太刻板地遵守规范把不该统一的东西也统一了。比如我要求“布尔变量以is开头”AI在命名所有标志位时都套用这个模式结果生成了isIsOpen、isHasPermission这种怪异命名。这种情况的根因是规范写得太死缺少例外说明。后来我在规范里补充了“命名可读性优先于规则一致性”这一条兜底原则AI再没犯过这个毛病。5.3 规范文件自身如何维护规范不是写完就固定不变的。随着项目演进技术栈可能升级、目录结构可能调整、团队约定可能变化规范文件也要跟着更新。我的维护节奏是每两周review一次把过去两周AI生成代码中出现的问题重新过一遍看看哪些高频问题规范里还没覆盖哪些规范条目已经失效。凡是新出现的坑就补充一条新规范凡是AI和人都已经内化的规则就移出规范减少噪音。规范也要走版本管理和变更评审不能一个人拍脑袋改。因为它的受众不只是AI新同学也要靠它理解项目约束随意改动会带来混乱。5.4 速查表典型问题和对应解法我把实际操作中最常遇到的问题整理成了一张速查表供大家参考问题表现可能原因优先处理AI引入项目未使用的依赖技术栈锁定规则缺失或未注入在规范中增加禁用清单Prompt里强约束生成的组件全是千人千面的命名命名规范缺少正反示例补充具体命名对照表配示例代码接口请求没有loading和错误处理边界条件清单未覆盖在规范中增加必查清单并要求AI自查代码风格和项目不一致ESLint/Prettier约束未强制配置自动化检查CI中阻断不合规提交规范读了但总被忽略上下文或优先级不够把关键规则前置到Prompt开头设置规则锚点AI在无提示下“自由发挥”规范缺少兜底原则增加“不确定时先问”的全局原则6. 最后说点实操中的个人体会这套给AI制定代码规范的方法我实际用了大概三个多月最大的体会是别把它当成一次性的文档而要当成一个持续迭代的机制。最有意思的变化是AI生成的代码从“一眼就能看出是AI写的”逐渐变成了“和我们团队的代码融为一体”这说明规范不再只是约束它已经变成了AI理解项目的“语言模型”。还有一个体会给AI定规范其实是在帮团队重新梳理一遍自己的工程体系。因为你要把之前靠“默契”和“常识”传递的经验变成显性、明确、可执行的内容这个整理过程本身就会暴露很多问题——比如你发现团队对“到底用不用dayjs”都没有统一过那AI就更不知道了。所以如果你正准备给AI定规矩我的建议是不用追求一步到位先抓住最痛的三个问题写成规范让AI跑起来然后每周迭代。规范会逐渐变成新的团队资产它沉淀的不仅是一份约束更是开发团队对“什么是好代码”的共同理解。
