1. 当AI进入你的代码仓库先别急着谈生产力先抛一个我自己的真实经历。团队引入AI辅助编程之后头两周效率确实肉眼可见地提升简单CRUD接口、单元测试、DTO转换这类“体力活”基本不用人工上手。但到了第三周问题开始密集出现了——有人把AI生成的数据库连接串直接提交到了公开仓库有人用AI重构了一段加解密逻辑但是把初始化向量写死成了全零更有意思的是同一个模块的三个不同文件分别出现了三种截然不同的日志格式。那一刻我意识到AI就像一个精力充沛但毫无经验的实习生你让它放手去干之前必须先给它一本完整的行为手册。这个“行为手册”就是标题里说的“给AI制定的代码规范”。它不是一份普通的编码风格指南而是一套面向AI工具、AI辅助编程助手、自动化编码Agent的完整约束体系。核心目标只有一个在享受AI效率红利的同时把它的不确定性关进规则的笼子里。有人可能会想AI不是可以自动遵循项目的.editorconfig、ESLint配置吗还需要专门给它定规范这个想法大方向上没错但现实远比这复杂。大家用得比较多的AI编程工具往往能识别仓库里的配置文件但这只能解决“代码长什么样”的问题解决不了“什么能写、什么不能写、写到什么程度可以提交”的问题。举个最简单的例子ESLint只能检查出变量定义了没用但不能告诉你“这笔金额计算涉及资金安全必须走财务模块封装好的接口不得自行实现浮点运算”。而这一类语义层面的规则恰恰是AI最容易踩坑的地方。所以这份代码规范本质上是给AI划定一个“能力边界”和“行为准则”。它配合工具链里的lint、测试、CI检查一起使用各管一段。我的经验是规范文本主要管住“AI不能做什么”和“AI应该怎么做”工具链负责“AI做得不对时如何打回”。两者结合才能真正让AI稳定输出高质量代码。这篇文章我不会给你讲纸上谈兵的大道理而是把我自己在项目中制定的这份AI代码规范从设计思路、核心条目、落地方式到踩坑实录完完整整拆开讲。无论你现在已经在用AI编程还是正准备引入这份规范都能直接拿来改改就用。2. 为什么通用代码规范管不住AI先搞懂AI犯错的底层逻辑2.1 AI不是“会写代码的程序员”而是“会补全上下文的概率模型”要制定有效的AI代码规范第一件事是纠正一个认知偏差不要用管人类程序员的方式去管AI。人类程序员读代码规范理解的是“为什么”——为什么这里要用LRU缓存而不是简单的HashMap为什么日志里不能打用户密码。即使规范没写全一个有经验的开发者也能靠领域知识推断出该怎么做。AI不一样。它的工作方式是基于上下文做概率预测给它看什么它就更倾向生成什么。如果团队里没有明确写出“金额计算统一使用BigDecimal”AI极大概率会在新代码里用double因为训练数据里75%的同类代码就是这么写的。所以我制定规范时的第一原则是把潜规则变成显式约束。团队默认“所有人都知道”的东西恰恰是AI不知道的。规范的核心部分不是怎么缩进、怎么命名而是把所有沉淀在资深开发者脑子里的“工程判断”一条条写清楚。2.2 AI在代码审查环节的“幸存者偏差”另一个有意思的现象是AI生成的代码会存在一种“看起来都对”的错觉。它们的代码风格可能完全符合项目里的ESLint规则函数命名也符合驼峰命名法注释写得比人写的还规整。但如果你仔细审查边界条件会发现大量“默认输入合法”的假设。我印象很深的一次让AI生成一个文件上传功能它用了几分钟就写出了完整代码文件类型校验、大小限制、错误处理全都有。但审查的时候我注意到它是直接用原始文件名拼接到存储路径里的完全没考虑路径穿越攻击的问题。这类安全敏感点通用规范里很少会具体写到但AI的错误率相当高。这背后的原因在于AI的训练数据里大量“简单示例代码”都是省略了安全处理的。它补全出来的内容统计上更接近“大多数普通人的写法”而不是“符合你们团队安全标准的写法”。所以规范里就必须额外开辟一块安全边界的内容把AI默认不会做、但项目里必须做的事情讲清楚。2.3 规范不只是给AI看的更是给人机协作流程定的最后还要想清楚一个立场问题这份规范是不是只约束AI我实践下来不是。它实际上规范的是整个“人机协作流程”。因为AI生成的任何代码最终责任人是提交它的工程师。规范必须明确哪些环节必须人审、哪些步骤允许AI独立完成、什么情况下可以信任AI输出、什么情况下必须打断。这不是对AI的不信任而是对工程质量的基本尊重。把流程定义清楚之后好处是双向的——人知道自己在什么节点该切入AI也能在最大自主空间内干活。我在规范的第一页就写着本规范约束的对象是所有AI辅助编码工具如自动补全、代码生成对话、智能Agent在参与本项目开发时的行为以及开发者在使用这些工具时的操作流程。3. AI代码规范的核心设计五个维度一个都不能少3.1 边界维度明确AI“能做什么”和“绝不能做什么”这是整个规范里最重要的部分。我在设计时把所有开发任务分成三个区间允许AI独立完成、AI辅助人类完成、完全禁止AI参与。允许AI独立完成的任务一般是低风险、高模式化的工作。比如为已有函数补充单元测试、生成VO/DTO之间的转换代码、编写简单的CRUD接口、根据注释生成工具函数等。这些任务即使AI写得有瑕疵后果也可控代码审查能轻松兜住。AI辅助人类完成的任务是需要人主导、AI当助手的场景。典型代表是模块重构。这个时候AI负责分析调用关系、生成重构建议方案但最终的拆分逻辑、接口设计必须由人拍板。还有一个常见场景是代码解释和排查问题AI可以帮忙梳理调用链、做个初步的根因分析但修复动作必须人来做。完全禁止AI参与的任务我用红色标注了涉及密钥和凭证的代码、加解密实现、支付和金额计算逻辑、数据迁移脚本、用户隐私数据处理、权限控制核心。这些领域一旦出错损失不可逆而且AI生成的代码往往“看起来没问题但经不起推敲”风险系数太高。比如密钥管理AI很容易生成硬编码的密钥这在开发测试阶段问题不大但一旦误提交几乎就是安全事故。3.2 上下文维度让AI“说人话”的提示词工程来兜底有了边界接下来要解决“怎么让AI每次生成代码前都记住规矩”。我的方案是在项目根目录维护一份特殊的规范文件用AI最擅长理解的Markdown结构化格式书写。文件命名为AI_CODING_RULES.md固定在项目根目录确保AI在读取上下文时可以自动加载到。这份文件不能太长我压到50行以内。太长AI会“选择性地遗忘”关键信息反而抓不住。结构上采用极简的“正/反”清单形式# 项目AI编码规则 ## 必须遵守 - 金额相关计算一律使用BigDecimal禁止使用double/float - 所有日期操作使用Java 8 Time API禁止使用SimpleDateFormat - 日志使用SLF4J门面禁止直接使用log4j/Log4j2的API - 对外接口入参一律使用DTO对象禁止直接暴露实体类 - 数据库操作必须走MyBatis-Plus内置方法或自定义Mapper禁止JdbcTemplate混用 ## 禁止事项 - 禁止在代码中硬编码任何密钥、Token、数据库连接串 - 禁止引入项目依赖中不存在的第三方库 - 禁止使用Thread.sleep进行异步等待使用async工具或消息队列 - 禁止在循环中调用远程接口或执行SQL这份文件同时还会作为AI辅助工具的system prompt注入双保险。在各家AI编程工具里都可以设置项目级自定义规则指向这个文件即可。另有一个关键点规范文件里的每一项都必须“可检查”不能写模糊感受。比如“代码质量要高”这种话等于没说AI不知道具体怎么做是“高”。而“金额计算用BigDecimal”就是可检查的团队成员也知道怎么在代码审查时对照。3.3 技术栈维度锁死依赖防止AI“自由发挥”引入AI之后一个非常头疼的问题就是它会自由发挥引入新依赖。有一次我在审查AI生成的Excel导入功能时发现它自动引入了一个POI的封装库功能确实好用文档也齐全但这个库的出现意味着项目多了一个需要维护的第三方依赖而且和团队自研的基础组件功能重叠。这不是一个简单的“这个库能不能用”的问题而是项目治理的问题。所以规范里专门有一条AI生成的代码中凡涉及新增第三方依赖必须由人工确认并走依赖引入评审流程AI不能自行在构建文件中添加依赖坐标。不过这条规范在实践中遇到了新的挑战——很多AI工具为了追求效果会自动帮你改构建文件并添加依赖。因此我们不得不在更底层做限制在CI配置里增加依赖白名单检查发现新依赖直接构建失败。当AI发现添加依赖这条路被“物理性堵死”之后它会主动改用项目已有的工具类实现这比任何提示词都管用。技术栈锁死的另一个维度是框架版本。上下文不同AI补全的API可能属于完全不同的版本。比如在Spring Boot 2.7的项目里它经常补出3.x才有的新方法。规范里我会写明通用配置文件位置和版本约束要求AI在生成代码前先查看项目构建文件的版本信息。3.4 架构维度强制分层让代码待在它该待的地方代码架构是AI最容易搞砸的地方。人类程序员写代码时脑子里有分层意识——Controller层只做参数接收和响应封装Service层只做业务逻辑DAO层只做数据访问。AI没有这个意识它纯粹在“最小上下文窗口”里做题经常把业务逻辑直接写在Controller里或者在Service里直接new一个Mapper。短期看功能是通的长期必然变成一座活火山。我在规范里固定了几条架构硬约束禁止在Controller中出现业务逻辑只能调用Service并做响应转换禁止在Service层出现SQL语句或查询条件封装应下沉到DAO层禁止跨层调用Controller不允许直接注入Mapper涉及外部接口调用的逻辑必须统一走独立的Client类禁止散落各处这类约束在实际落地时经常遇到AI工具不听话的情况。毕竟架构约束不像“用BigDecimal”那样是单一代码层面的规则它需要AI理解一个类在项目里的“角色”。我的办法是在规则文件里加一条硬要求“生成代码前先查看目标目录的包结构确认类所属层次”。同时在审查时把“分层是否清晰”列为第一检查项一旦发现越层直接打回。3.5 测试维度不能让AI只“写功能”不“写验证”最后是测试。AI最让人省心也最让人担心的地方是它几乎不排斥写测试。让它写单测它能给你洋洋洒洒生成几十个用例。但问题在于它写的测试通常都是“证明代码能跑”的测试而不是“证明业务逻辑是对的”的测试——大部分断言都在验证正常路径的返回值而极少覆盖异常分支和边界条件。规范里的测试要求有三条AI生成的功能代码必须同时生成对应的单元测试测试代码和功能代码一起提交测试用例必须覆盖正常路径、异常路径、边界条件三个维度缺失任一维度需要补充Mock外部依赖时必须验证关键交互参数而不只是mock后返回固定值我在实际执行时发现让AI写边界测试是最划算的——它对“极端但合法”的输入往往能产生意想不到的思路而人最容易忽视的恰好就是这类场景。比如为空字符串、最大长度、时区影响、闰年2月29日等。这些用例如果靠人写容易陷入思维定式AI反而能补盲。4. 不只是“规则文本”把AI规范固化到工具链里的实操方案4.1 规则文件如何组织才能被AI稳定读取规则文件是整份规范的载体组织方式非常有讲究。比例失衡会让AI抓不住重点过于冗长它会按照“统计概率”选择性遗忘。我的做法是“金字塔式”三层结构第一层项目级AI编码规则AI_CODING_RULES.md50行以内包含“必须遵守”和“禁止事项”清单这份文件是最高优先级任何AI生成代码前都必须读取。第二层技术栈与架构说明TECH_STACK.md200行以内包含项目技术栈版本、分层架构约定、模块职责说明。这份文件供AI理解项目全貌适合在让AI参与较大模块开发时引用。第三层具体模块的领域知识文档放在对应目录下如ORDER_SERVICE.md描述该模块特有的业务规则、常见坑位、不可变约束。这部分只有在AI处理该模块时才会被引用。三层文件的逻辑关系是第一层是“法律”强制执行第二层是“宪法”指导方向第三层是“案例库”辅助理解。实际使用中AI工具到底能不能自动加载这三份文件取决于你用的工具类型。有些工具会自动读取项目根目录的Markdown文件有些不支持。我用的组合是一部分依赖工具自身的文档加载功能一部分在对话时手动指定文件。这块没有统一标准常见做法是把规则文件内容嵌入到AI工具的“自定义指令/系统提示”配置项里保证每次对话都生效。4.2 CI流水线让规范校验从“自觉”变“强制”规则写好了AI也可能不执行。人的记忆会衰减AI的概率模型更难保证稳定。所以CI阶段必须有一道强制的“物理防线”。我在流水线里接了三道检查第一道是风格与静态检查。ESLint、Checkstyle、golangci-lint这类工具在原有配置基础上增加了一组专门针对AI生成代码常见问题的规则。比如禁止硬编码密钥的正则检查、禁止过时API调用检查等。第二道是依赖白名单检查。前文说过的AI自己加依赖会导致构建失败。这块用脚本实现解析构建产物中的依赖列表与项目锁定的白名单比对不在白名单里直接fail。第三道是AI生成代码标识检查。要求开发者在提交信息里注明哪些文件是AI生成的例如带上[ai-gen]标记CI根据这个标记对相关文件做更严格的检查项。这个看起来像形式主义实际价值很大——它让“AI参与度”可度量、可追溯后面会细说。注意第三道检查最好做善意提醒而不是强制拦截否则开发人员会有逆反心理刻意去掉标记反而让数据失真。我的经验是标注出自AI代码的提交审查优先级提高标注的开发者每周可以得到AI协作效率的数据反馈。正向激励比负向惩罚效果好得多。4.3 给AI配几个固定搭档从“一次性生成”到“可复用流程”代码规范文档只是“静止的规矩”。真正让我体会到质变的是把AI的工作流从“一次生成完事”改造成“固定角色分工”的模式。我在项目里配置了四个固定的AI Agent角色代码审查员Agent拿到提交代码后先检查是否符合AI_CODING_RULES.md输出违规清单文档生成员Agent负责为接口生成API文档为复杂函数生成注释和示例测试补全员Agent分析已有代码找出缺失的测试分支生成补充用例重构建议Agent在代码审查通过后分析重复代码和坏味道给出重构建议这一套角色分工的好处是每个Agent的职责单一、上下文聚焦规范落地更容易。代码审查员Agent的规则文件就是那份50行的AI_CODING_RULES.md它不需要了解整个业务看到违反规则的点直接输出警报即可。这样即使主编码Agent偶尔“犯浑”审查Agent也能把住最后一道关。这一套角色分工的好处是每个Agent的职责单一、上下文聚焦规范落地更容易。代码审查员Agent的规则文件就是那份50行的AI_CODING_RULES.md它不需要了解整个业务看到违反规则的点直接输出警报即可。这样即使主编码Agent偶尔“犯浑”审查Agent也能把住最后一道关。4.4 从一个人遵守到一群人遵守规范和知识库联动规范的落地还有一个隐藏保障——和团队知识库联动。AI是概率模型它回答“项目里金额用什么类型”这种问题时可能从训练数据里“见过”类似的项目结构但并不能肯定你们项目的具体约定。所以我在搭建规则体系时刻意把规范条目和知识库里的详细文档做了映射。比如规则说“金额计算用BigDecimal”知识库里就有“为什么不用double”的详细分析文章包括浮点数表示原理、线上事故案例、替代方案对比。当AI在对话中触发了某条规则而开发者想进一步了解背景时AI工具可以基于知识库内容生成更完整的解释。这种做法既保证了规则的执行力度又方便团队新人在阅读代码时理解“为什么这么写”最终让规范从一份“死文档”变成团队共识的载体。我第一次把知识库链接加到规范里的时候团队里有位老同事说“这终于解决了‘我按规范写了但又不知道为什么’的痛点。”5. 规范推不下去问题很可能出在流程和授权5.1 没有“否决权”的规范等于白写规范写得再完备如果没有配套的裁决机制AI根本不会怕。这里说的裁决不是“审查人发现违规打回修改”而是当AI的行为超出规范边界时团队有一套响应流程。举例来说AI在写某个功能时发现自己需要调用一个项目里不存在但训练数据里很常见的库。规范要求它“停下来问人”但AI无法主动停下来。它要么硬着头皮用已有工具实现要么生成代码后Crash。理想的情况是AI生成代码不通过CI检查提交失败开发者收到报错然后开发者手动决定是改代码还是调整依赖白名单。这套“AI尝试-检查拦截-人工决策”的闭环本质上就是给规范装上了“牙齿”。另一个“牙齿”是代码审查的人工抽查。我们规定了一个硬性比例AI生成的代码前25个PR必须100%人工审查之后可以根据AI的表现动态调整但抽查比例不低于50%。低于这个比例你就是在拿生产稳定性赌AI的表现。5.2 权限精细化哪些模块允许AI动不仅是“什么代码AI可以写”还有“哪些文件AI可以改”。我把项目的目录权限分成了三档第一档是AI可自由编辑区比如测试目录、DTO/VO目录、工具方法目录这些地方变更影响面小允许AI独立提交代码。第二档是AI可辅助修改区比如Service实现类、Controller层允许AI生成代码但必须有人共同修改、确认逻辑。第三档是AI禁止修改区包括数据库迁移脚本、核心交易流程代码、权限校验代码、配置中心相关代码。这些目录在AI工具的配置里直接设为忽略即使AI生成了相关文件也不得保存到仓库。这个权限分级的价值在于它把“AI能做什么”从一个模糊的伦理议题变成了工程上的访问控制问题。不需要每个人自觉“不让AI碰敏感代码”AI工具本身就会自动避开。顺着这个思路团队内部复盘时能少扯很多皮。5.3 规范也要版本化记好每一次修改的原因最后一条比较容易被忽略AI代码规范本身也是需要版本管理的。我把这份规范放在独立的Git仓库里维护每次都走PR流程每次修改都要注明原因。例如v1.2版本增加“禁止在循环中调用远程接口”原因是订单批量处理时AI生成了一段逐个调用库存服务的代码导致接口响应时间从200ms飙升到15秒。v1.4版本新增“所有日期时间必须存储UTC时间戳”的规则源于一次跨境订单时间错乱事故——AI在生成逻辑时直接用了服务器本地时间导致美国和欧洲用户看到的订单时间不一样。版本化的好处是每个团队成员能清楚看到规范的演进脉络理解每条规则背后的代价。对新加入的人来说读规范的过程也是一次浓缩的“踩坑教育”。6. 踩坑实录那些规范没堵住的问题6.1 AI的“过度自信”不存在的依赖和错误的方法签名最常见的翻车现场不是AI写不出代码而是它写出的代码“看起来完全正确”但实际上编译不过。AI工具的特点是会“模拟”出它认为最可能的API签名而这个签名在真实环境里可能根本不存在。有一段时间我花了很多工夫在编译错误处理上因为AI生成的一个加密工具类引用了某个库并不存在的AES-GCM辅助类而它给出的解决办法是“请添加某某依赖”。这个问题靠规范文本解决不了只能靠“编译检查AI自我修正循环”。现在我们在开发流程里约定了一个硬步骤AI生成代码后必须先在本地或CI环境执行编译失败信息反馈回去要求修正。不经过编译验证的AI代码不允许进入人工审查环节。6.2 上下文遗忘长对话里的“记忆衰减”AI工具处理长对话时存在明显的“上下文遗忘”现象。对话前20轮还能严格遵循规范到了第80轮生成代码的风格和质量就开始漂移了之前约定的命名规则、异常处理模式都不再稳定。应对办法是拆分任务不建议让AI在一次对话里连续生成多个模块的代码。我现在的习惯是每个功能模块单独开启一次新的对话每次对话开始时重新粘贴一遍核心规范片段。这个习惯看着麻烦但在质量上的收益非常明显。6.3 规范冲突时的“危险沉默”当AI收到的指令与现有代码出现冲突时它倾向于“沉默地选一个它认为合理的方案”而不太会主动提醒。这在工程上是致命的。比如说项目里的订单号生成逻辑原本是“日期随机数”但AI在学习已有代码时发现某个工具类里有UUID的用法于是自作主张在新代码里用了UUID格式的订单号。单体看新代码完全没问题但对老系统来说订单号的格式关联到了数据统计、报表导出、客服查询等多个模块改格式等于捅马蜂窝。规范里我加了一条“当已有代码中的写法与本规范不一致时以已有代码为准并提醒开发者确认。”谁来决定永远是人。AI只有建议权没有决策权。7. 度量AI协作质量用数据判断规范要不要收紧规范落地两个月后我建立了一套简单的度量指标用数据回答“这份规范到底起没起作用”。分享几个核心指标AI生成代码的通过率AI生成的PR中一次通过审查的比例。如果这个比例低于50%说明规范过严或者AI工具和项目匹配度不够。审查返工率平均每个AI生成PR被要求修改的次数。和人类写的代码对比看差值是否在缩小。规范违规类型分布按违规类型统计比如“依赖新增违规”“硬编码密钥”“分层越界”。这个指标能告诉团队规范里的哪条规则最需要加强或调整。缺陷逃逸率合入主分支后AI生成代码中被发现线上缺陷的概率。这是最终的“成绩单”也是评估整个AI协作模式是否可持续的关键。用数据说话的好处是可以避免围绕“AI到底行不行”展开无休止的争论。数据说不行就去看规范哪里没堵住数据说行就适当放宽边界给AI更大的发挥空间。规范的松紧应该像调PID参数一样根据系统反馈动态调整而不是一劳永逸。8. 当“给AI的规范”变成“团队习惯”文化建设比文档更重要到最后有一个问题想特别说说。我见过不少团队把AI代码规范写完之后往仓库里一放就再也不看了。原因很简单大家觉得“自己又不是AI为什么要读给AI的规范”。这种想法我能理解但实际上是浪费了规范的最大价值。一份高质量的AI代码规范是团队所有隐性工程知识的显性化沉淀。“金额用BigDecimal”背后是浮点数误差的教训“禁止在循环里调接口”背后是性能问题的血泪“禁止在Controller里写业务逻辑”背后是架构腐化的痛苦。这些知识一直存在只是从未被系统梳理成文。给AI写规范的过程等于逼着团队把脑子里“默认你会懂”的东西写出来这对人也是极大的提升。很多资深开发者在完成规范文档后的反馈是“从来没想过我们项目里的规矩这么多”。所以我最后的建议是不要把AI代码规范单纯看作给工具用的配置文件把它当成团队工程文化的一次集体反思。执行层面可以靠CI、权限、检查这些工具但认同层面一定靠人对“代码质量和可维护性”的共同追求。AI是队友还是对手归根结底取决于你给它划的跑道和共同目标。如果你正在经历“AI代码满天飞团队心里都发慌”的时期试试按这套框架梳理一份你自己的AI代码规范。从50行的规则清单开始到CI检查落地再逐步补充上下文和权限控制你会发现AI带来的不只是效率还有一次重新审视工程标准的机会。 
长河君 · 2026/9/15 13:45:56 · 阅读 1.2k AI代码规范实战：从边界划定到CI强制校验的完整落地指南
1. 当AI进入你的代码仓库先别急着谈生产力先抛一个我自己的真实经历。团队引入AI辅助编程之后头两周效率确实肉眼可见地提升简单CRUD接口、单元测试、DTO转换这类“体力活”基本不用人工上手。但到了第三周问题开始密集出现了——有人把AI生成的数据库连接串直接提交到了公开仓库有人用AI重构了一段加解密逻辑但是把初始化向量写死成了全零更有意思的是同一个模块的三个不同文件分别出现了三种截然不同的日志格式。那一刻我意识到AI就像一个精力充沛但毫无经验的实习生你让它放手去干之前必须先给它一本完整的行为手册。这个“行为手册”就是标题里说的“给AI制定的代码规范”。它不是一份普通的编码风格指南而是一套面向AI工具、AI辅助编程助手、自动化编码Agent的完整约束体系。核心目标只有一个在享受AI效率红利的同时把它的不确定性关进规则的笼子里。有人可能会想AI不是可以自动遵循项目的.editorconfig、ESLint配置吗还需要专门给它定规范这个想法大方向上没错但现实远比这复杂。大家用得比较多的AI编程工具往往能识别仓库里的配置文件但这只能解决“代码长什么样”的问题解决不了“什么能写、什么不能写、写到什么程度可以提交”的问题。举个最简单的例子ESLint只能检查出变量定义了没用但不能告诉你“这笔金额计算涉及资金安全必须走财务模块封装好的接口不得自行实现浮点运算”。而这一类语义层面的规则恰恰是AI最容易踩坑的地方。所以这份代码规范本质上是给AI划定一个“能力边界”和“行为准则”。它配合工具链里的lint、测试、CI检查一起使用各管一段。我的经验是规范文本主要管住“AI不能做什么”和“AI应该怎么做”工具链负责“AI做得不对时如何打回”。两者结合才能真正让AI稳定输出高质量代码。这篇文章我不会给你讲纸上谈兵的大道理而是把我自己在项目中制定的这份AI代码规范从设计思路、核心条目、落地方式到踩坑实录完完整整拆开讲。无论你现在已经在用AI编程还是正准备引入这份规范都能直接拿来改改就用。2. 为什么通用代码规范管不住AI先搞懂AI犯错的底层逻辑2.1 AI不是“会写代码的程序员”而是“会补全上下文的概率模型”要制定有效的AI代码规范第一件事是纠正一个认知偏差不要用管人类程序员的方式去管AI。人类程序员读代码规范理解的是“为什么”——为什么这里要用LRU缓存而不是简单的HashMap为什么日志里不能打用户密码。即使规范没写全一个有经验的开发者也能靠领域知识推断出该怎么做。AI不一样。它的工作方式是基于上下文做概率预测给它看什么它就更倾向生成什么。如果团队里没有明确写出“金额计算统一使用BigDecimal”AI极大概率会在新代码里用double因为训练数据里75%的同类代码就是这么写的。所以我制定规范时的第一原则是把潜规则变成显式约束。团队默认“所有人都知道”的东西恰恰是AI不知道的。规范的核心部分不是怎么缩进、怎么命名而是把所有沉淀在资深开发者脑子里的“工程判断”一条条写清楚。2.2 AI在代码审查环节的“幸存者偏差”另一个有意思的现象是AI生成的代码会存在一种“看起来都对”的错觉。它们的代码风格可能完全符合项目里的ESLint规则函数命名也符合驼峰命名法注释写得比人写的还规整。但如果你仔细审查边界条件会发现大量“默认输入合法”的假设。我印象很深的一次让AI生成一个文件上传功能它用了几分钟就写出了完整代码文件类型校验、大小限制、错误处理全都有。但审查的时候我注意到它是直接用原始文件名拼接到存储路径里的完全没考虑路径穿越攻击的问题。这类安全敏感点通用规范里很少会具体写到但AI的错误率相当高。这背后的原因在于AI的训练数据里大量“简单示例代码”都是省略了安全处理的。它补全出来的内容统计上更接近“大多数普通人的写法”而不是“符合你们团队安全标准的写法”。所以规范里就必须额外开辟一块安全边界的内容把AI默认不会做、但项目里必须做的事情讲清楚。2.3 规范不只是给AI看的更是给人机协作流程定的最后还要想清楚一个立场问题这份规范是不是只约束AI我实践下来不是。它实际上规范的是整个“人机协作流程”。因为AI生成的任何代码最终责任人是提交它的工程师。规范必须明确哪些环节必须人审、哪些步骤允许AI独立完成、什么情况下可以信任AI输出、什么情况下必须打断。这不是对AI的不信任而是对工程质量的基本尊重。把流程定义清楚之后好处是双向的——人知道自己在什么节点该切入AI也能在最大自主空间内干活。我在规范的第一页就写着本规范约束的对象是所有AI辅助编码工具如自动补全、代码生成对话、智能Agent在参与本项目开发时的行为以及开发者在使用这些工具时的操作流程。3. AI代码规范的核心设计五个维度一个都不能少3.1 边界维度明确AI“能做什么”和“绝不能做什么”这是整个规范里最重要的部分。我在设计时把所有开发任务分成三个区间允许AI独立完成、AI辅助人类完成、完全禁止AI参与。允许AI独立完成的任务一般是低风险、高模式化的工作。比如为已有函数补充单元测试、生成VO/DTO之间的转换代码、编写简单的CRUD接口、根据注释生成工具函数等。这些任务即使AI写得有瑕疵后果也可控代码审查能轻松兜住。AI辅助人类完成的任务是需要人主导、AI当助手的场景。典型代表是模块重构。这个时候AI负责分析调用关系、生成重构建议方案但最终的拆分逻辑、接口设计必须由人拍板。还有一个常见场景是代码解释和排查问题AI可以帮忙梳理调用链、做个初步的根因分析但修复动作必须人来做。完全禁止AI参与的任务我用红色标注了涉及密钥和凭证的代码、加解密实现、支付和金额计算逻辑、数据迁移脚本、用户隐私数据处理、权限控制核心。这些领域一旦出错损失不可逆而且AI生成的代码往往“看起来没问题但经不起推敲”风险系数太高。比如密钥管理AI很容易生成硬编码的密钥这在开发测试阶段问题不大但一旦误提交几乎就是安全事故。3.2 上下文维度让AI“说人话”的提示词工程来兜底有了边界接下来要解决“怎么让AI每次生成代码前都记住规矩”。我的方案是在项目根目录维护一份特殊的规范文件用AI最擅长理解的Markdown结构化格式书写。文件命名为AI_CODING_RULES.md固定在项目根目录确保AI在读取上下文时可以自动加载到。这份文件不能太长我压到50行以内。太长AI会“选择性地遗忘”关键信息反而抓不住。结构上采用极简的“正/反”清单形式# 项目AI编码规则 ## 必须遵守 - 金额相关计算一律使用BigDecimal禁止使用double/float - 所有日期操作使用Java 8 Time API禁止使用SimpleDateFormat - 日志使用SLF4J门面禁止直接使用log4j/Log4j2的API - 对外接口入参一律使用DTO对象禁止直接暴露实体类 - 数据库操作必须走MyBatis-Plus内置方法或自定义Mapper禁止JdbcTemplate混用 ## 禁止事项 - 禁止在代码中硬编码任何密钥、Token、数据库连接串 - 禁止引入项目依赖中不存在的第三方库 - 禁止使用Thread.sleep进行异步等待使用async工具或消息队列 - 禁止在循环中调用远程接口或执行SQL这份文件同时还会作为AI辅助工具的system prompt注入双保险。在各家AI编程工具里都可以设置项目级自定义规则指向这个文件即可。另有一个关键点规范文件里的每一项都必须“可检查”不能写模糊感受。比如“代码质量要高”这种话等于没说AI不知道具体怎么做是“高”。而“金额计算用BigDecimal”就是可检查的团队成员也知道怎么在代码审查时对照。3.3 技术栈维度锁死依赖防止AI“自由发挥”引入AI之后一个非常头疼的问题就是它会自由发挥引入新依赖。有一次我在审查AI生成的Excel导入功能时发现它自动引入了一个POI的封装库功能确实好用文档也齐全但这个库的出现意味着项目多了一个需要维护的第三方依赖而且和团队自研的基础组件功能重叠。这不是一个简单的“这个库能不能用”的问题而是项目治理的问题。所以规范里专门有一条AI生成的代码中凡涉及新增第三方依赖必须由人工确认并走依赖引入评审流程AI不能自行在构建文件中添加依赖坐标。不过这条规范在实践中遇到了新的挑战——很多AI工具为了追求效果会自动帮你改构建文件并添加依赖。因此我们不得不在更底层做限制在CI配置里增加依赖白名单检查发现新依赖直接构建失败。当AI发现添加依赖这条路被“物理性堵死”之后它会主动改用项目已有的工具类实现这比任何提示词都管用。技术栈锁死的另一个维度是框架版本。上下文不同AI补全的API可能属于完全不同的版本。比如在Spring Boot 2.7的项目里它经常补出3.x才有的新方法。规范里我会写明通用配置文件位置和版本约束要求AI在生成代码前先查看项目构建文件的版本信息。3.4 架构维度强制分层让代码待在它该待的地方代码架构是AI最容易搞砸的地方。人类程序员写代码时脑子里有分层意识——Controller层只做参数接收和响应封装Service层只做业务逻辑DAO层只做数据访问。AI没有这个意识它纯粹在“最小上下文窗口”里做题经常把业务逻辑直接写在Controller里或者在Service里直接new一个Mapper。短期看功能是通的长期必然变成一座活火山。我在规范里固定了几条架构硬约束禁止在Controller中出现业务逻辑只能调用Service并做响应转换禁止在Service层出现SQL语句或查询条件封装应下沉到DAO层禁止跨层调用Controller不允许直接注入Mapper涉及外部接口调用的逻辑必须统一走独立的Client类禁止散落各处这类约束在实际落地时经常遇到AI工具不听话的情况。毕竟架构约束不像“用BigDecimal”那样是单一代码层面的规则它需要AI理解一个类在项目里的“角色”。我的办法是在规则文件里加一条硬要求“生成代码前先查看目标目录的包结构确认类所属层次”。同时在审查时把“分层是否清晰”列为第一检查项一旦发现越层直接打回。3.5 测试维度不能让AI只“写功能”不“写验证”最后是测试。AI最让人省心也最让人担心的地方是它几乎不排斥写测试。让它写单测它能给你洋洋洒洒生成几十个用例。但问题在于它写的测试通常都是“证明代码能跑”的测试而不是“证明业务逻辑是对的”的测试——大部分断言都在验证正常路径的返回值而极少覆盖异常分支和边界条件。规范里的测试要求有三条AI生成的功能代码必须同时生成对应的单元测试测试代码和功能代码一起提交测试用例必须覆盖正常路径、异常路径、边界条件三个维度缺失任一维度需要补充Mock外部依赖时必须验证关键交互参数而不只是mock后返回固定值我在实际执行时发现让AI写边界测试是最划算的——它对“极端但合法”的输入往往能产生意想不到的思路而人最容易忽视的恰好就是这类场景。比如为空字符串、最大长度、时区影响、闰年2月29日等。这些用例如果靠人写容易陷入思维定式AI反而能补盲。4. 不只是“规则文本”把AI规范固化到工具链里的实操方案4.1 规则文件如何组织才能被AI稳定读取规则文件是整份规范的载体组织方式非常有讲究。比例失衡会让AI抓不住重点过于冗长它会按照“统计概率”选择性遗忘。我的做法是“金字塔式”三层结构第一层项目级AI编码规则AI_CODING_RULES.md50行以内包含“必须遵守”和“禁止事项”清单这份文件是最高优先级任何AI生成代码前都必须读取。第二层技术栈与架构说明TECH_STACK.md200行以内包含项目技术栈版本、分层架构约定、模块职责说明。这份文件供AI理解项目全貌适合在让AI参与较大模块开发时引用。第三层具体模块的领域知识文档放在对应目录下如ORDER_SERVICE.md描述该模块特有的业务规则、常见坑位、不可变约束。这部分只有在AI处理该模块时才会被引用。三层文件的逻辑关系是第一层是“法律”强制执行第二层是“宪法”指导方向第三层是“案例库”辅助理解。实际使用中AI工具到底能不能自动加载这三份文件取决于你用的工具类型。有些工具会自动读取项目根目录的Markdown文件有些不支持。我用的组合是一部分依赖工具自身的文档加载功能一部分在对话时手动指定文件。这块没有统一标准常见做法是把规则文件内容嵌入到AI工具的“自定义指令/系统提示”配置项里保证每次对话都生效。4.2 CI流水线让规范校验从“自觉”变“强制”规则写好了AI也可能不执行。人的记忆会衰减AI的概率模型更难保证稳定。所以CI阶段必须有一道强制的“物理防线”。我在流水线里接了三道检查第一道是风格与静态检查。ESLint、Checkstyle、golangci-lint这类工具在原有配置基础上增加了一组专门针对AI生成代码常见问题的规则。比如禁止硬编码密钥的正则检查、禁止过时API调用检查等。第二道是依赖白名单检查。前文说过的AI自己加依赖会导致构建失败。这块用脚本实现解析构建产物中的依赖列表与项目锁定的白名单比对不在白名单里直接fail。第三道是AI生成代码标识检查。要求开发者在提交信息里注明哪些文件是AI生成的例如带上[ai-gen]标记CI根据这个标记对相关文件做更严格的检查项。这个看起来像形式主义实际价值很大——它让“AI参与度”可度量、可追溯后面会细说。注意第三道检查最好做善意提醒而不是强制拦截否则开发人员会有逆反心理刻意去掉标记反而让数据失真。我的经验是标注出自AI代码的提交审查优先级提高标注的开发者每周可以得到AI协作效率的数据反馈。正向激励比负向惩罚效果好得多。4.3 给AI配几个固定搭档从“一次性生成”到“可复用流程”代码规范文档只是“静止的规矩”。真正让我体会到质变的是把AI的工作流从“一次生成完事”改造成“固定角色分工”的模式。我在项目里配置了四个固定的AI Agent角色代码审查员Agent拿到提交代码后先检查是否符合AI_CODING_RULES.md输出违规清单文档生成员Agent负责为接口生成API文档为复杂函数生成注释和示例测试补全员Agent分析已有代码找出缺失的测试分支生成补充用例重构建议Agent在代码审查通过后分析重复代码和坏味道给出重构建议这一套角色分工的好处是每个Agent的职责单一、上下文聚焦规范落地更容易。代码审查员Agent的规则文件就是那份50行的AI_CODING_RULES.md它不需要了解整个业务看到违反规则的点直接输出警报即可。这样即使主编码Agent偶尔“犯浑”审查Agent也能把住最后一道关。这一套角色分工的好处是每个Agent的职责单一、上下文聚焦规范落地更容易。代码审查员Agent的规则文件就是那份50行的AI_CODING_RULES.md它不需要了解整个业务看到违反规则的点直接输出警报即可。这样即使主编码Agent偶尔“犯浑”审查Agent也能把住最后一道关。4.4 从一个人遵守到一群人遵守规范和知识库联动规范的落地还有一个隐藏保障——和团队知识库联动。AI是概率模型它回答“项目里金额用什么类型”这种问题时可能从训练数据里“见过”类似的项目结构但并不能肯定你们项目的具体约定。所以我在搭建规则体系时刻意把规范条目和知识库里的详细文档做了映射。比如规则说“金额计算用BigDecimal”知识库里就有“为什么不用double”的详细分析文章包括浮点数表示原理、线上事故案例、替代方案对比。当AI在对话中触发了某条规则而开发者想进一步了解背景时AI工具可以基于知识库内容生成更完整的解释。这种做法既保证了规则的执行力度又方便团队新人在阅读代码时理解“为什么这么写”最终让规范从一份“死文档”变成团队共识的载体。我第一次把知识库链接加到规范里的时候团队里有位老同事说“这终于解决了‘我按规范写了但又不知道为什么’的痛点。”5. 规范推不下去问题很可能出在流程和授权5.1 没有“否决权”的规范等于白写规范写得再完备如果没有配套的裁决机制AI根本不会怕。这里说的裁决不是“审查人发现违规打回修改”而是当AI的行为超出规范边界时团队有一套响应流程。举例来说AI在写某个功能时发现自己需要调用一个项目里不存在但训练数据里很常见的库。规范要求它“停下来问人”但AI无法主动停下来。它要么硬着头皮用已有工具实现要么生成代码后Crash。理想的情况是AI生成代码不通过CI检查提交失败开发者收到报错然后开发者手动决定是改代码还是调整依赖白名单。这套“AI尝试-检查拦截-人工决策”的闭环本质上就是给规范装上了“牙齿”。另一个“牙齿”是代码审查的人工抽查。我们规定了一个硬性比例AI生成的代码前25个PR必须100%人工审查之后可以根据AI的表现动态调整但抽查比例不低于50%。低于这个比例你就是在拿生产稳定性赌AI的表现。5.2 权限精细化哪些模块允许AI动不仅是“什么代码AI可以写”还有“哪些文件AI可以改”。我把项目的目录权限分成了三档第一档是AI可自由编辑区比如测试目录、DTO/VO目录、工具方法目录这些地方变更影响面小允许AI独立提交代码。第二档是AI可辅助修改区比如Service实现类、Controller层允许AI生成代码但必须有人共同修改、确认逻辑。第三档是AI禁止修改区包括数据库迁移脚本、核心交易流程代码、权限校验代码、配置中心相关代码。这些目录在AI工具的配置里直接设为忽略即使AI生成了相关文件也不得保存到仓库。这个权限分级的价值在于它把“AI能做什么”从一个模糊的伦理议题变成了工程上的访问控制问题。不需要每个人自觉“不让AI碰敏感代码”AI工具本身就会自动避开。顺着这个思路团队内部复盘时能少扯很多皮。5.3 规范也要版本化记好每一次修改的原因最后一条比较容易被忽略AI代码规范本身也是需要版本管理的。我把这份规范放在独立的Git仓库里维护每次都走PR流程每次修改都要注明原因。例如v1.2版本增加“禁止在循环中调用远程接口”原因是订单批量处理时AI生成了一段逐个调用库存服务的代码导致接口响应时间从200ms飙升到15秒。v1.4版本新增“所有日期时间必须存储UTC时间戳”的规则源于一次跨境订单时间错乱事故——AI在生成逻辑时直接用了服务器本地时间导致美国和欧洲用户看到的订单时间不一样。版本化的好处是每个团队成员能清楚看到规范的演进脉络理解每条规则背后的代价。对新加入的人来说读规范的过程也是一次浓缩的“踩坑教育”。6. 踩坑实录那些规范没堵住的问题6.1 AI的“过度自信”不存在的依赖和错误的方法签名最常见的翻车现场不是AI写不出代码而是它写出的代码“看起来完全正确”但实际上编译不过。AI工具的特点是会“模拟”出它认为最可能的API签名而这个签名在真实环境里可能根本不存在。有一段时间我花了很多工夫在编译错误处理上因为AI生成的一个加密工具类引用了某个库并不存在的AES-GCM辅助类而它给出的解决办法是“请添加某某依赖”。这个问题靠规范文本解决不了只能靠“编译检查AI自我修正循环”。现在我们在开发流程里约定了一个硬步骤AI生成代码后必须先在本地或CI环境执行编译失败信息反馈回去要求修正。不经过编译验证的AI代码不允许进入人工审查环节。6.2 上下文遗忘长对话里的“记忆衰减”AI工具处理长对话时存在明显的“上下文遗忘”现象。对话前20轮还能严格遵循规范到了第80轮生成代码的风格和质量就开始漂移了之前约定的命名规则、异常处理模式都不再稳定。应对办法是拆分任务不建议让AI在一次对话里连续生成多个模块的代码。我现在的习惯是每个功能模块单独开启一次新的对话每次对话开始时重新粘贴一遍核心规范片段。这个习惯看着麻烦但在质量上的收益非常明显。6.3 规范冲突时的“危险沉默”当AI收到的指令与现有代码出现冲突时它倾向于“沉默地选一个它认为合理的方案”而不太会主动提醒。这在工程上是致命的。比如说项目里的订单号生成逻辑原本是“日期随机数”但AI在学习已有代码时发现某个工具类里有UUID的用法于是自作主张在新代码里用了UUID格式的订单号。单体看新代码完全没问题但对老系统来说订单号的格式关联到了数据统计、报表导出、客服查询等多个模块改格式等于捅马蜂窝。规范里我加了一条“当已有代码中的写法与本规范不一致时以已有代码为准并提醒开发者确认。”谁来决定永远是人。AI只有建议权没有决策权。7. 度量AI协作质量用数据判断规范要不要收紧规范落地两个月后我建立了一套简单的度量指标用数据回答“这份规范到底起没起作用”。分享几个核心指标AI生成代码的通过率AI生成的PR中一次通过审查的比例。如果这个比例低于50%说明规范过严或者AI工具和项目匹配度不够。审查返工率平均每个AI生成PR被要求修改的次数。和人类写的代码对比看差值是否在缩小。规范违规类型分布按违规类型统计比如“依赖新增违规”“硬编码密钥”“分层越界”。这个指标能告诉团队规范里的哪条规则最需要加强或调整。缺陷逃逸率合入主分支后AI生成代码中被发现线上缺陷的概率。这是最终的“成绩单”也是评估整个AI协作模式是否可持续的关键。用数据说话的好处是可以避免围绕“AI到底行不行”展开无休止的争论。数据说不行就去看规范哪里没堵住数据说行就适当放宽边界给AI更大的发挥空间。规范的松紧应该像调PID参数一样根据系统反馈动态调整而不是一劳永逸。8. 当“给AI的规范”变成“团队习惯”文化建设比文档更重要到最后有一个问题想特别说说。我见过不少团队把AI代码规范写完之后往仓库里一放就再也不看了。原因很简单大家觉得“自己又不是AI为什么要读给AI的规范”。这种想法我能理解但实际上是浪费了规范的最大价值。一份高质量的AI代码规范是团队所有隐性工程知识的显性化沉淀。“金额用BigDecimal”背后是浮点数误差的教训“禁止在循环里调接口”背后是性能问题的血泪“禁止在Controller里写业务逻辑”背后是架构腐化的痛苦。这些知识一直存在只是从未被系统梳理成文。给AI写规范的过程等于逼着团队把脑子里“默认你会懂”的东西写出来这对人也是极大的提升。很多资深开发者在完成规范文档后的反馈是“从来没想过我们项目里的规矩这么多”。所以我最后的建议是不要把AI代码规范单纯看作给工具用的配置文件把它当成团队工程文化的一次集体反思。执行层面可以靠CI、权限、检查这些工具但认同层面一定靠人对“代码质量和可维护性”的共同追求。AI是队友还是对手归根结底取决于你给它划的跑道和共同目标。如果你正在经历“AI代码满天飞团队心里都发慌”的时期试试按这套框架梳理一份你自己的AI代码规范。从50行的规则清单开始到CI检查落地再逐步补充上下文和权限控制你会发现AI带来的不只是效率还有一次重新审视工程标准的机会。