前阵子我们项目群里又热闹了一回。起因是同事用AI生成了一段批量数据迁移脚本逻辑没问题但函数名全是a、b、temp这种注释写着“这里处理数据”异常处理直接pass代码评审的时候被后端负责人连环追问。同事还觉得委屈“AI写出来能用不就行了”——这句话我听过很多次也是很多团队在引入AI编程之后最先撞上的那堵墙。问题在于AI生成的代码能用但未必“能留”。能跑的代码和符合工程规范的代码之间差的恰恰是项目长期维护最需要的那部分。如果团队里每个人都拿AI当免费的临时工又不告诉它这个项目的规矩那代码库里很快就会变成“AI风格大杂烩”。今天这篇就聊聊我们项目里是怎么给AI“立规矩”的——我们新增了一套专门给AI看的代码规范以及这套规范从设计、落地到迭代的完整过程。1. 从代码评审的“口水战”说起AI写代码不等于写好代码先说清楚一个前提给AI制定代码规范并不是要限制AI的发挥而是把团队沉淀多年的工程经验“翻译”成AI能听懂的语言让它在一个明确的边界里辅助开发。我们在实际操作中总结出的核心差异有几点这决定了整套规范文件的设计思路。1.1 AI生成代码的几类典型“欠规范”表现我观察了团队里三个多月用AI辅助开发的产出问题高度集中在几类命名随意。短变量名、拼音缩写、语义模糊的英语单词混用AI会根据训练数据里的各种习惯随机发挥不会自动对齐你项目里的命名约定。注释两极分化。要么一个注释都没有要么全是“把x加1”这种复述代码语义的垃圾注释真正需要解释的“为什么这样做”反而没有。异常处理薄弱。最常见的写法是try...except...里面放个print或者直接吞掉异常对业务流程没有兜底出了问题连日志都找不到线索。代码结构扁平化。一个函数从头写到尾不拆分、不复用也很少考虑可扩展性——因为AI的目标是“完成当前指令”不是“为下一位维护者铺路”。风格与项目不一致。引号单双混用、缩进不统一、import顺序随意这些细小问题聚合起来非常致命会让代码评审变成一场消耗战。1.2 传统代码规范和“AI代码规范”的本质差异传统代码规范是给人看的写在Wiki或文档里靠Code Review和自觉来执行。但给AI看的代码规范更像是“使用说明书”——你告诉它这个项目的上下文、技术栈、约束条件、不允许做什么、鼓励做什么它才能在生成代码时少踩雷。还有一个很多人忽略的差异传统规范大多停留在“禁止清单”级别比如“禁止使用魔法数字”“函数不得超过50行”但AI无法像人一样理解这些抽象的工程原则背后的微妙情境。你写“禁止魔法数字”AI在生成时根本判断不出来某个数值算不算魔法数字它需要的是带例子的、边界的、几乎可以当作规则引擎来解析的文档。这套规范在工程里本质上是一份“给AI的角色说明书操作手册”下面我展开讲讲内容怎么设计。2. AI代码规范文件的内容设计我们最终沉淀成了什么样我们最终没有把传统代码规范直接改吧改吧丢给AI而是单独写了一份AI_CODE_GUIDE.md放在项目仓库根目录同时把精简版注入到AI工具的系统提示词里。整个文件大概2000多行我讲讲里面最核心的几块设计。2.1 顶层约定先让AI知道它面对的是谁规范文件开头我们要求必须写明项目的定位、技术栈、核心业务领域以及AI参与代码生成的边界。我见过很多团队写规范上来就列命名规则但AI对项目毫无背景认知生成的代码经常带着无关依赖或者错误的架构假设。所以我们的开头是这样组织的项目简介一句话说清这个系统是干什么的面向什么用户。技术栈清单语言、框架、数据库、消息队列、缓存等明确AI不要擅自引入新的技术组件。代码边界哪些目录和文件AI不能动比如自动生成的文件、数据库迁移脚本、基础设施配置哪些模块是可以自由修改的。集成方式说明当前项目是否采用AI Agent自动提PR还是仅作为开发者的辅助插件。这两种模式下规范执行的严格程度完全不同。这一部分最重要的作用是信息对齐。AI并不知道“我们这个项目”和“网上那个开源项目”有什么区别你给它越多的上下文约束它就表现得越像“团队里的自己人”。2.2 命名与格式约定给AI一套“自动补全”的决策依据命名规范我们写得非常具体不是简单一句“要有意义”而是给出了决策树布尔变量用is、has、can等开头例如is_ready而不是ready_flag。组件/函数名用动词名词结构例如getUserById而不是query_user_info_1。常量使用全大写下划线且必须在所属模块顶部集中定义不允许散落在业务代码里。避免缩写除非是业界通用缩写如html、url、id。集合类型变量用复数名词映射类型用xxx_map或xxx_by_xxx格式。格式上我们直接指定了Prettier或Black这类自动格式化工具的配置为唯一标准并且在规范中附上配置文件内容要求AI生成的代码必须符合该格式输出而不是依赖后期人为调整。2.3 注释与文档要求什么样的注释才是有效注释这是AI最容易出错的部分。我们的约定是公开接口、函数签名必须写docstring说明参数含义、返回值、可能抛出的异常。业务逻辑里的“非显然决策”必须加行级注释例如“这里为什么先更新缓存再更新数据库”。禁止写复述型注释比如“// 遍历列表”这种纯属废话。复杂算法或临时修复需在注释中注明思路和参考依据最好带上链接或issue编号。为了让AI理解什么叫“非显然决策”我们专门在规范文档里放了几个金样例和一个反样例。比如下面这段# 反例复述代码 # 遍历用户列表 for user in users: ... # 正例解释原因 # 这里必须逆序遍历才能优先处理刚插入的用户 for user in reversed(users): ...这种带正反例的模板AI吸收得比抽象描述快得多。后来我们在所有规范章节里都采用了“规则正例反例”三段式结构。2.4 错误处理与健壮性约定让AI学会“体面地失败”AI默认倾向生成非常乐观的代码路径——最顺利的执行流、最少的分支判断、最简化的异常处理。为了掰正这个习惯我们写了一套专门的宠物规则所有外部IO操作网络请求、数据库访问、文件读写必须处理异常不允许裸奔。异常对象必须携带上下文信息至少包括操作名称、影响对象ID、原始异常信息。禁止捕获异常后直接pass或者只打日志不处理如果是“预期内异常”需要显式注释说明预期场景。业务逻辑的错误分支需要返回统一格式的错误响应而不是各种随意抛异常。日志输出必须区分级别调试信息用debug状态变更用info异常用error错误恢复用warn。这些规则看起来很简单但写进规范并用例子说明“上下文信息怎么携带”之后AI生成的代码质量提升非常明显。2.5 安全与隐私红线不可谈判的约束条件我们明确在规范中设定了“一票否决项”——只要触犯这些红线AI生成的代码不允许合并禁止在代码中硬编码密钥、Token、数据库密码。生成配置时只允许占位符模式。禁止拼接SQL字符串必须使用参数化查询或ORM。禁止直接输出未经转义的用户输入到页面防XSS。涉及用户敏感数据的日志必须脱敏。不使用任何来源不明的第三方依赖所有依赖引入必须由人工评估。这部分的落实不能只靠AI自觉后面我会讲到工程实践中如何通过工具链强制约束。2.6 测试要求AI生成代码的“出厂质检线”在我们的规范里AI生成的新功能代码默认必须包含对应的单元测试或集成测试测试代码本身也要符合几条规则不要求100%覆盖率但核心业务模块必须覆盖正常路径、异常路径、边界条件三条路径。测试命名采用test_功能点_场景_预期结果格式。禁止写只断言“不报错”的无效测试必须有明确的断言。涉及外部服务的测试默认使用Mock不允许真实调用。一开始大家觉得这个要求太严但后来发现只要在Prompt里带上规范片段AI生成测试代码的速度非常快。给AI提要求不会降低效率反而让产出可验证了。3. 不只是写文档怎么让AI真正遵守这套规范规范文件写得再漂亮如果AI不看、不看进上下文里就等于零。我们在实际推行中试了好几种注入方式按效果排个序。3.1 三种注入方式与效果对比注入方式做法效果适用场景Prompt模板把规范精简版粘到每次对话的系统提示词里即时生效但受上下文窗口限制只能放核心约束个人使用ChatGPT/Claude等通用对话工具项目级指令文件在仓库根目录放AGENTS.md或CLAUDE.mdAI工具自动读取无需每次手动粘贴内容可以更长覆盖更全面团队统一使用Cursor/Codex等支持项目记忆的IDEAgent技能包把规范封装成AI Agent的Skill按需触发最智能AI能在特定场景主动调用规范已经有Agent自动化流程的团队我们最终采用的是“项目级指令文件为主 Prompt模板兜底”的组合。在每个核心仓库根目录都放了一份AGENTS.md开头就写着“你是本项目的外包开发工程师必须遵守以下规范”中间是精简版规范结尾附上操作流程。这里有个经验规范文件不是越长越好模型对超长上下文的关注度会衰减。我们的精简版控制在了200行以内只保留最核心的红线和最常见的易错点完整版放仓库里供人工查阅。3.2 给AI配置“代码生成三步走”为了让AI输出的代码更稳定我们在规范里给它固定了一套工作流要求它在处理任务时按步骤执行理解阶段重述你对任务的理解包括涉及的模块、改动范围、潜在风险。这一步能过滤掉大量AI“自信地跑偏”的情况。方案阶段先给出实现方案而不是直接写代码。方案里说明用什么模式、动哪些文件、是否影响现有接口。执行阶段按方案生成代码并附上自检清单逐一确认符合规范里的红线要求。这个过程看起来多花了时间实际上省了大量来回返工的精力。AI自己先梳理一遍很多低级错误在源头就避免了。3.3 效果验证同一个Prompt有规范和没规范的区别我们做了一个对照实验用同一个需求描述分别在“无规范注入”和“有规范注入”两种情况下让AI生成一个用户注册接口。结果很直观维度无规范有规范命名风格temp_user、savecreate_user、is_phone_valid参数校验手动拼接校验逻辑零散统一使用validation schema错误码结构化异常处理except Exception: pass按异常类型分支处理携带上下文日志数据库操作裸SQL拼接ORM参数化查询测试代码无正常异常边界三条用例齐全同样一段Prompt输出质量完全是两个量级。这也印证了一件事AI的能力边界不只在模型本身也在你给它的约束质量上。4. 推行过程中踩过的坑规范写了AI不听话怎么办规范落地的过程并不顺利我们踩了至少五个坑每个都挺有代表性。4.1 坑一规范文件太长AI选择性“失忆”第一版规范我们写得特别全包含了团队多年的编码经验整整几十页精华。结果AI根本不买账——上下文窗口有限它记住了开头和结尾的规则中间部分全部忽略行为跟没看规范几乎没区别。后来我们把规范拆成了“多级结构”第一优先级红线列表永远放最前面AI必须遵守违反就拒绝生成。第二优先级命名、格式、错误处理等高频场景规则控制在20条以内。第三优先级具体到某个模块的补充说明按需提取。文件越短AI遵守率越高。这跟人看文档的规律是一样的太长就没人会读完。4.2 坑二规范写得太抽象AI“礼貌性遵守”有些规范条目写的是“保证代码的可维护性”“遵循高内聚低耦合”结果AI生成出来的代码自我感觉极度良好但离我们想要的工程标准差得远。后来我们意识到AI不是不听话它是理解不了抽象的工程价值。于是我们把所有抽象条目都改成“可验证”的具体约束“保证可维护性”改成“不允许单函数超过60行超过必须拆分”“遵循分层架构”改成“禁止在Controller层直接写SQL必须经由Service和DAO层”“代码风格统一”改成“只允许使用项目配置的格式化工具输出结果”。只有AI自己能检查自己是否违规的规则才有约束力。4.3 坑三规范与工程工具链脱节一开始我们只靠“AI自觉”执行规范后来发现这是不现实的。因为让AI“不使用魔法数字”远远不如在CI流水线里加一个ESLint规则来的直接。我们的解决方案是“人机互补”AI相关的规范强调它生成代码时的行为准则而工程强制约束格式化、Lint、安全检查、依赖扫描全部下沉到工具链。AI生成代码后自动过一遍Prettier/Husky/CI检查发现不合规的直接打回AI再根据报错信息修改。这形成了一个闭环——AI负责“写得合理”工具链负责“写得合规”各管一段效率最高。4.4 坑四团队成员用不同AI工具行为不一致团队里有人用Cursor有人用普通ChatGPT还有人自己写了脚本调API。不同工具对规范文件的读取支持完全不一样。我们后来做了一轮统一所有AI辅助代码生成的工具至少要求支持通过Prompt注入规范并统一使用项目根目录的AGENTS.md作为标准入口。这样不管谁用什么工具至少都基于同一套规范工作。4.5 坑五规范更新了但AI的“记忆”还停在上一版代码规范不是一成不变的但AI工具的对话上下文往往还是以前的历史——如果之前AI记住了旧版本的命名约定你改了规范它也不会自动纠正。我们的做法是每次调整规范后都在团队的AI使用指南里加一条强制操作——“新建对话or重置上下文”确保AI以最新版本规范为准。这听起来像个笨办法但确实是最有效的办法。5. 从规范到闭环AI代码规范不是静态文档到现在这套AI代码规范已经在我们项目里迭代了四五轮从一个“给AI看的文档”逐步变成了一套代码质量保障机制。这块我最后展开讲讲闭环怎么运转。5.1 用AI来自动检查AI形成规范执行的闭环既然AI能写代码自然也能当代码评审助手。我们的做法是把规范文档“反向”用于评审在让AI做Code Review的时候给它的指令是“严格对照AI_CODE_GUIDE.md逐条检查这份代码列出违规项”。这一步效果很好。因为规范是我们和AI共同维护的“共同语言”AI评审的准确率比人工抽查高很多。评审结果里的高频违规项反过来又成为下一轮规范更新的输入。规范的版本库和代码仓库放一起每次修改都走PR流程有评审记录可追溯。这样整个体系就从“单方面给AI立规矩”变成了“AI写→AI查→人来审→规范再更新”的正向循环。5.2 让规范具备“项目自适应”能力我们还做了一步实验把历史代码里符合团队风格的优质代码块提取成“风格参考范例”附在规范后面。这个做法无意中开启了“少样本学习”模式——AI看到真实项目里高质量的代码风格比空洞的描述更能模仿到精髓。方法其实很简单从项目里挑选5-10个典型的优秀代码文件覆盖不同场景接口、服务、数据处理、工具函数。把它们的共同风格特征总结成若干条具体规则加进规范。同时保留1-2个完整参考文件路径告诉AI如果要写相似代码可以参照这些文件的组织方式。5.3 不同岗位的定制化规范分支随着项目复杂化我们也意识到通用规范还不够。前端团队和后端团队对AI的要求差异很大岗位方向核心关注点规范侧重点前端组件拆分、状态管理、样式隔离、构建体积函数组件hooks规范、样式命名约束、禁止内联对象后端接口幂等性、数据库事务、缓存一致、服务降级API设计模式、事务边界、超时与重试策略数据/算法数据流清晰、结果可复现、性能可评估Pipeline分段规范、随机种子管理、离线/在线一致性我们的做法是在主规范基础上按技术栈维护了几个附录文件AI根据不同场景自动加载对应分支。这让规范更精准也不会让AI在写前端代码的时候被后端规则干扰。5.4 最后说点实际操作中的体会如果你所在的团队还没给AI立过规矩我的建议是不用憋大招先从一个仓库开始。挑一个最核心、团队成员最常让AI写代码的模块起草一份精简规范重点解决当前最让你头疼的一两个问题比如命名、异常处理用两周时间在真实需求里试用再根据效果迭代。你会发现一旦AI的产出踩在了团队的节奏上大家对AI编程的接受度会有一个质的飞跃——因为不再有人需要在代码评审会上替AI“擦屁股”了。代码评审能回归到设计讨论和业务逻辑的层面而不是每天都在抠细节。这套规范文件放在仓库里不只是约束AI它其实也反向逼着我们把自己的工程要求想得更清楚。就冲这一点这活投入产出比就不亏。