刚到新项目组的时候我干过一件挺后悔的事把 AI 生成的代码直接合入主干结果 Code Review 第一次就没过同事留言说这风格“不像咱们组的东西”。那时候我才意识到AI 写代码这件事靠的不是自觉而是约束。从那以后我开始在项目里单独给 AI 定一套代码规范不是给同事看的那种而是专门给 AI 助手和 AI Agent 看的“行为说明书”。这篇文章就把这套规范的思路、写法和落地过程完整拆开讲。1. 为什么要单独给AI定一套代码规范1.1 被AI带崩节奏的那段经历我先说一个真实场景。前阵子在做一个中后台管理系统功能点密集接口多我为了赶进度让 AI 批量生成了几个工具类和一个列表页。当时我给它的大致要求是“仿照项目现有风格写”AI 也回了“好的”。结果代码合进去之后问题接二连三地冒出来。首先是命名风格不统一同一个时间戳格式化函数在一个文件里叫formatTime在另一个文件里叫formatDate还有一个地方叫dealTime。其次是冗余代码AI 特别喜欢把几段相同逻辑复制到不同文件而不是抽成公共函数。最离谱的是它在某个组件里偷偷 import 了一个项目里根本没用过的第三方库理由是“这样处理更稳妥”。当然这些问题靠 Code Review 也能拦下来但这背后暴露了一个更核心的问题传统代码规范针对的是会自觉维护一致性的人类工程师而 AI 不会自觉。它每次都在重新“猜”你想要什么。如果你不把规范写得足够明确它就会用概率分布的方式从网上学过的海量代码里挑一个“看起来合理”的写法。今天挑这个明天挑那个结果就是项目风格被快速稀释。1.2 AI代码规范与传统团队规范的区别传统团队规范比如 Java 的谷歌风格指南、前端的 Airbnb Style Guide本质上是给人读的。工程师读了之后内化成习惯配合 linter 和 code review 落地。AI 不一样它不会“记住”规则每次对话都是新的开始它的行为完全取决于当前上下文里能看到什么。这意味着三件事规范必须随每次对话注入到 AI 的上下文里不能指望它记在心里。规范语句要短、要绝对不要用“建议”、“尽量”这类模糊词。AI 会按字面理解模糊指令等于没指令。规范要有可验证性。人能靠审美判断一段代码整洁不整洁AI 不行所以规范要落到具体的模式上比如“禁止console.log提交”“所有文件名必须小驼峰”。另外还有一点容易被忽略不同 AI 模型的行为差异很大。同一个命名规则模型 A 执行得很好模型 B 可能完全无视。所以项目里如果同时有人用 Copilot、有人用 Cursor、有人用 Claude那这套规范要设计成跨模型通用用最简单的祈使句不要依赖某个模型特有的“理解能力”。1.3 什么样的项目适合先引入AI代码规范不是所有项目都适合立刻上这套东西。我自己的判断标准有两条一是团队里实际使用 AI 写代码的人比较多二是项目本身有一定历史代码沉淀需要维护风格一致性。如果你的项目刚起步只有三千行代码那这时候定 AI 规范反而可能拖慢节奏。因为规范本身需要投入精力维护而早期项目最大的任务是快速验证方向。如果测试覆盖率接近零那优先补测试比给 AI 立规矩更有价值因为 AI 代码再乱只要测试能兜住重构和规范都可以晚一步。反过来如果项目代码量过了五万行团队又同时接了三个业务线那 AI 带来的风格漂移问题会成倍放大。这时候一套面向 AI 的规范就是刚需而且越早定历史包袱越轻。2. 内容设计的几个关键层次2.1 先划边界比先立规矩更重要我在写规范的第一版时犯了个典型错误一上来就写“变量命名要用小驼峰”“函数要有 JSDoc”这种细枝末节结果 AI 很听话地把项目里所有变量都改名了造成大量无意义 diff差点把同事逼疯。后来我把边界条款挪到了最前面这才是整个规范的核心。边界的意思是告诉 AI 哪些代码是它可以碰的哪些是绝对不许碰的。比如禁止修改配置文件application.yml、package.json、tsconfig.json除非用户明确要求。禁止修改数据库迁移文件和锁文件。禁止对原有函数的内部逻辑做“顺手优化”除非用户描述了 bug 或改动需求。禁止移除代码中看起来“没用”的注释有些注释是业务背景AI 无法理解。禁止为了通过 lint 而添加// eslint-disable这类豁免注释。这些边界写清楚之后AI 的“擅自行动率”会肉眼可见地下降。因为大部分 AI 失控都不是因为它技术不行而是因为它对“任务边界”的理解跟人不一样。它会觉得“重构一下”和“改个 bug”是同一件事随时可能顺手把别的模块给改了。边界就是用来堵这种意外。2.2 对“输出格式”做硬性约束接下来是输出格式。这一层主要解决的是代码结构问题也就是 AI 生成的代码在视觉上、组织上必须符合项目惯性。我挑了几个最容易出问题的点模块导入顺序固定。前端项目统一React/Vue→第三方库→业务组件→类型定义→样式/常量。AI 经常把导入顺序打乱或者把样式插在中间看着就很别扭。禁止在同一函数里混用多种异步风格。要么全部用async/await要么全部用.then()。AI 很容易在一种风格里突然混入另一种。函数长度控制在合理范围。如果 AI 生成了一个超过 100 行的函数我会要求它主动拆分。但不是强制拆分因为有些场景里长函数反而是对的。变量命名必须和上下文语义一致。例如表示用户列表的数组叫userList或users不要叫data、res、listData这种空洞名字。返回类型必须明确。TypeScript 项目里禁止让函数隐式推断出一个联合类型必须手动标注。这些规则看起来很像常见的工程规范但注意它们的表达方式必须是不留解释空间的。比如“函数长度合理”这种话AI 听不懂。要写成“如果函数体超过 60 行必须拆分为多个函数并在拆分处说明每个函数的职责”这才有效。我还在规范里加了一条很有意思的规则禁止 AI 生成“只有当前文件用到”的通用工具函数然后复制到多个文件里。如果它觉得逻辑可以复用应该主动在回答里提示“这里可以考虑抽公共函数”而不是直接动手复制。这样一来是否抽象的决策权回到人手上不会产生那种到处都是 30 行重复代码的尴尬情况。2.3 对“依赖和引入”做硬性约束依赖失控是 AI 编码里最隐蔽也最危险的问题。AI 不仅会为了省事引入项目里本来没有的第三方库还可能引入无意义的间接依赖。我在规范里明确写了三条默认只允许使用项目package.json/requirements.txt/go.mod中已声明的依赖。新增依赖前必须先向用户说明“需要引入 XX 库版本 XX用于 XX”经过确认后才可以安装。禁止复制第三方库实现片段到项目里除非该库许可证明确允许且用户知情。这里还要提醒一点很多人以为 AI 不会主动安装依赖但实际上如果它运行在具备终端执行权限的 Agent 模式下它真的可能直接npm install一个新包。我遇到过它为了处理日期格式装了一个dayjs但项目里本来就有moment这就很离谱。所以这条约束对于 AI Agent 团队尤其重要。2.4 命名、注释和错误处理的细则这一节做的是“兜底”工作。前面讲了边界和输出格式但还剩下一些 AI 容易在细节上翻车的点需要单独列出来规范。注释这块我要求 AI 遵循“只写为什么不写是什么”的原则。例如“// 这里不能提前返回因为必须先释放锁”是好的注释“// 遍历数组”这种纯粹描述代码行为的注释则属于噪音。AI 特别喜欢生成后一种有时甚至会给每一行都加上中文注释读起来像小学生作文。这跟项目风格不匹配会拖慢真正的代码审阅速度。错误处理也需要强制模式。比如网络请求的异常必须捕获timeout和http error两类不能只 catch 一个error然后 console.log。又比如文件操作必须保证finally中释放句柄。这些规则如果写在人类规范里大家会觉得是常识但在 AI 输出里默认很多模型“照顾不到”这些边界情况所以你必须在规范里写清楚。还有一点针对函数的命名我会要求 AI 在生成公共函数时必须用“动词 业务领域名词”的格式比如sendOrderNotification、calcInvoiceTotal。它生成的内部临时函数可以随意但凡是会被其他模块引用的命名必须体现出意图。否则时间一长代码库里全是handleSomething、processData这种抽象到等于没命名的函数。2.5 如何用一份检查清单落地规范写了一大堆最后一个必要的输出物就是一份可以逐条打勾的检查清单。没有检查清单AI 面对大段规则文本时很容易进行所谓的“选择性遗忘”也就是它会高概率遵守前面的几条后面则越来越马虎。我把检查清单放在规范文档的最末尾用平铺直叙的极短句子列出。例如是否引入了未确认的新依赖是否修改了锁文件函数长度是否超过 60 行是否使用console.log作为临时调试是否有复制粘贴的重复逻辑是否添加了无意义注释这段清单很妙因为它在每次 AI 对话时都会被截取进上下文AI 可以在输出代码前进行“自检”相当于在思维链里多了一道闸门。实测下来加了自检清单之后规范遵守率会有明显提升。3. 规范文件的落地实操3.1 规范文件放哪、取什么名字这一节说落地。文件放的位置和命名直接影响 AI 能不能读到它。不同工具读文件的方式不一样我见过几种主流做法根目录放AGENTS.md许多 AI Agent 工具会自动加载根目录下的这个文件。使用.cursor/rules/目录里面放.mdc规则文件Cursor 会在代码生成时自动匹配。用CLAUDE.md作为 Claude Code 的项目记忆文件。有些团队把规范放在docs/coding/ai-coding-rules.md并在提示词里显式引用。我的做法是双份。根目录放一份精简版的AGENTS.md只包含最重要的边界和检查清单因为 AI Agent 会自动加载同时在docs/目录放一份面向人类团队成员的完整版规范里面包含背景解释、设计原理和常见案例。一份给机器快速看一份给人慢慢理解避免“既要又要”导致的文档臃肿。3.2 面向AI的规范文件怎么写才有效这里有几个写作技巧属于经验之谈。第一用绝对化的祈使句。该写“禁止”“必须”“绝对不要”不要写“建议”“尽量”“通常”。AI 面对概率性词句时会取平均概率然后挑一个它认为“差不多”的行为。只有绝对化的指令才能限制它的自由发挥空间。第二每条规则之间不要嵌太多解释性文字。比如“禁止直接修改接口返回的数据结构”后面如果你再接一句“因为这样会导致 type 定义不同步进而引发运行时错误同时在审查时也容易遗漏……”AI 会抓不住重点。解释性文字是给人看的机器只看命令。如果要加解释放在文档末尾的“原因说明”区域。第三规则数量控制在 30 条以内。如果超过 30 条上下文会被大量占用而且 AI 的指令遵循率会急剧下降。我最初写了 80 多条规则结果是灾难模型只执行前十几条后面的形同虚设。后来压缩到 27 条配合率上去了。第四把最重要的规则重复出现在两个地方一个是开头的“最高优先级”段落另一个是结尾的“交付前自检”清单。AI 对重复信息的权重重现能力很强这条亲测有效。3.3 工具配置与CI门禁规范文档写完之后还需要把它和工具链结合起来。否则它只是“纸面规范”AI 在 IDE 里自动补全时根本不会主动去读你的文档。我目前给项目配套做了这几件事把规范文件加载到 AI 编码工具的“项目规则”配置里。这样每次 AI 生成代码前规则都会自动注入。在.pre-commit-config.yaml或husky钩子里加上 lint 检查和格式化检查。AI 生成代码后本地提交时会被自动拦截如果格式不通过提交失败。在 CI 流水线里增加了一个轻量检查脚本专门扫描是否新增未声明的依赖或者是否存在重复代码块。这一步很重要它是兜底因为 AI 在本地可能绕过了 pre-commit但 CI 是最后一道防线。当然CI 检查会消耗一些构建时间所以我把规则设置得很克制只拦截明确违反规范的情况不做太主观的判断避免误伤。3.4 代码评审时如何快速识别AI不合规产出代码评审是最后一道人工关卡。要让评审效率高你得学会快速识别哪些 diff 是“AI 痕迹明显的产物”。AI 生成的代码通常有几个共同特征变量名过于通用比如data、temp、result、obj。有大量“过度防御性”的判空逻辑每个函数入口都加上if (!data)之类的判断。注释风格很“教学式”像是在给学生讲课。会生成多余的临时变量明明可以直接返回却中间绕了几层赋值。对原有代码做无害但无意义的重命名产生噪音 diff。我习惯在做 Code Review 时先看文件模式的变更。如果一个 PR 里出现了超过 10 个文件的改动但描述却是“修复一个 bug”那大概率是 AI 顺手做了“重构式修复”这种 PR 我会直接打回让开发者把改动范围缩小。实践中这招非常管用能挡住大量无效代码变更。4. 常见问题与排查经验4.1 规则太多太长AI直接“选择性遗忘”这是最常遇到的问题。你把写了 50 条规则的文档丢给 AI让它写一个分页组件结果它只遵守了文件命名规则其他全忘了。不是它不想遵守是上下文里信息太多了模型对指令的注意力资源有限。我的解决办法是分层。每次任务对话时不把整本规范全塞进去而是只注入与本次任务相关的部分。比如生成前端组件时只把“边界条款 输出格式 前端规则”注入写后端接口时注入“边界条款 错误处理 依赖规则”。这样每次对话的规则量控制在 10 条左右遵循率会好很多。4.2 过度遵守代码变得僵硬冗长还有一个有趣的反向问题AI 太遵守规范了结果代码写得很僵硬。比如我规定“所有函数必须写 JSDoc”它就真的给每个内部函数都写了三行注释我规定“错误处理必须区分 timeout 和 http error”它就真的在每个 function 里重复写 10 行 try-catch。这种“用力过猛”的情况本质原因是 AI 不理解规则的“适用场景”。人类工程师知道“函数必须写注释”指的是有外部调用的公共函数内部闭包里的临时函数可以略过但 AI 分不清它会不加选择地执行。面对这种情况我倾向于给规则加权重标签。比如在规范里注明“本规则适用于公共 API / 组件对外接口不适用于内部实现函数”而不是单纯说“必须写注释”。这需要一点调试过程但长期收益很大。4.3 依赖失控AI爱“造轮子”且爱“乱引入”依赖管控是最头疼的。AI 识别出项目里需要一个 URL 拼接函数但它不会先去看看utils/url.ts里有没有现成的它可能直接就在新文件里复制了一遍类似逻辑。导致项目里出现三四个实现相似但细节不同的buildUrl维护成本直线上升。这个问题的解法第一是靠规范里“禁止复制重复逻辑必须复用已有函数”这一条第二是靠脚本去检测重复代码。我现在的做法是每周手动跑一次“重复代码检测”把不同实现集中起来统一收敛。另外AI 在 Agent 模式下的依赖安装行为需要权限手段来限制而不是只靠书面规范。比如在容器环境下阻断它访问外网 npm registry或者给执行终端配置白名单只允许安装某个固定镜像源里的包。这些都是工程层面的配合措施。4.4 规范文件本身腐烂了怎么办项目迭代半年后你会发现当初定的规范有些已经不再适用。比如项目早期要求所有代码必需支持 IE 兼容后来放弃了 IE这条规则就成了阻碍又比如某个规则设定的函数长度阈值放在新模块里根本不合理。规范腐烂是必然的。我现在的做法是给规范文件加一个“修订记录”区域每三个月至少过一遍看看哪些规则还能拦到问题哪些规则只是摆设。如果一条规则在三个月里没有在 Code Review 中发挥任何作用那说明它不是废话就是已经被 AI 内化了这时候就应该删除或精简。这步很多人会跳过但长期看特别重要。因为规范的威信一旦丧失——大家发现里面有一半内容没人遵守——那么连有价值的规则也会一起被无视。5. 一段时间的运行感受这套 AI 代码规范在项目里跑了半年多我最真实的体会是它并不是万能的也不可能完全阻止 AI 写出烂代码但它把“预期管理”这件事做到了。以前让 AI 改完代码我得拆开 diff 慢慢看风格、看依赖、看边界现在它改完之后我只需要重点看逻辑是否对其余大部分规范问题提前被拦截了。如果你现在正在为“AI 生成的代码破坏了团队规范”而头疼我的建议很简单别急着教育同事也别急着骂 AI先把边界划清楚再写一份给 AI 看的规则文件然后把它配置到工具链里让 AI 在输出之前就知道哪些事不能做。这个过程不需要多少成本但对代码质量的改善是立竿见影的。最后再分享一个习惯我会在每个 PR 模板里加一个字段“本 PR 中 AI 的参与比例”这个动作倒不是想限制 AI 使用而是让规范可以持续量化演进知道哪些场景 AI 表现最好哪些场景需要我们介入更多。
