先说个背景。最近两个月我所在的团队把AI编码助手和几个内部Agent正式接进了日常研发流程功能交付速度肉眼可见地变快了。但伴随而来的问题也特别让人头疼代码仓库开始“快速变脏”不同模块的风格割裂、相似逻辑反复重写、边界条件漏处理、全局变量满天飞。代码Review的工作量不但没降反而涨了一截。一开始我以为只是工具用得不熟后来才发现真正的问题在于——我们从头到尾只给AI提了需求却从来没给它立过规矩。项目里一直在强调“代码规范”但那份规范是给人看的AI写完提交之前根本不会主动去对照。于是我做了一件以前从来没认真做过的事在项目里新增一份专门的“给AI制定的代码规范”。这篇文章就把这份规范的设计思路、完整模板、落地方式和踩坑记录全部整理出来给同样在AI辅助开发里挣扎的团队一个能直接抄作业的底稿。它目前已经在多个项目里跑了一个多月新接入的AI助手和Agent遵循度明显提升代码Review的负反馈也少了很多。1. 给AI立这次规矩之前我想清楚的三件事1.1 传统代码规范管不到AI生成过程绝大多数团队都已经有了一套传统的代码规范比如Google Style Guide、阿里Java开发手册、Airbnb JavaScript规范或者是团队内部自己整理的一份Markdown文档。这些规范针对的是“人”所以里面充满的是“参数命名使用驼峰”“禁止使用魔法数字”“Service层不能直接操作数据库”这类约定。人写代码的时候会自然地去遵守这些约定因为经过长时间的训练和Review。但AI不一样。无论API、Copilot还是项目里的Agent它在生成代码时参考的首先是Prompt、上下文和模型参数然后才是检索或注入进来的项目规范。传统规范如果只是放在docs目录里没有主动注入到AI的上下文窗口那AI基本就是“看不见”的。我把之前的规范文档丢给一个Agent让它生成一段用户列表查询逻辑结果它完全按照自己训练时的“通用最佳实践”来写连项目里已有的分页工具类都不用反而自己写了一段分页逻辑。那一刻我就明白了给AI定的规范不能再是“项目文化文件”必须是“机器能读取并执行的行为指令”。1.2 规范约束的不只是代码更是生成流程我这次制定AI代码规范时反复和团队强调一个概念这份规范约束的对象不是AI写出来的“文件内容”而是AI的“生成流程”。人写代码会经历需求理解、方案设计、编码、自测、提交这几个阶段。AI直接生成往往把中间环节跳过了。比如你在Prompt里说“帮我实现一个订单导出功能”一个不守规矩的AI可能直接输出几百行代码没有异常处理没有状态机没有日志甚至没有告诉你它假设了什么边界条件。如果项目里遵循“先设计后编码”的规范那么AI也应该先输出设计要点、假设条件、影响面再给出具体代码。所以这份规范里我专门加了一类“过程约束”规则包括必须首先复述任务理解、必须列出不确定点并主动提问、必须拆分任务再逐一产出、必须先给测试方案再写实现、每次交付必须附一段变更说明。这些约束都有明确目的就是强迫AI把思考过程显性化。我们团队花了大概一周测试发现这类过程约束对代码质量的提升作用远大于单纯约束命名和格式化。1.3 不是所有团队都需要马上做这件事如果你的团队只是偶尔用AI查个函数用法、写个临时脚本那完全不需要一份给AI的代码规范。投入产出的分界线在“AI产出的代码是否要长期沉淀到主仓库”以及“是否有多个成员共用同一套AI工具”。我们内部触发这次复盘的原因就是项目里同时有三拨人在用AI后端用Cursor写Java接口、前端用Copilot写TypeScript组件、还有两个Agent流水线在自动修Bug和生成单元测试。明明都是我们自己的代码最后Review起来感觉像三个外包团队不同时期写的。这种情况下如果不给AI立一套统一规范项目维护成本会指数级上升。团队规模小、主仓库长期未更新的场景可以先做“轻量版”只约定工具链、禁止事项、代码风格三块后期再逐步扩展。但只要是多人协同且AI高频参与生产的项目我建议越早立规矩越好因为每一段未经规范约束的AI代码都会成为后续所有人的技术债。2. 给AI的代码规范到底该写什么、不写什么2.1 先给规范定性它是一份行为协议不是技术手册我写初稿的时候犯过一个典型错误把以前给人类看的规范又扩写了一遍增加了更多细则比如“常量命名使用UPPER_SNAKE_CASE”“方法长度不能超过80行”。结果AI工具加载这份规则后表现很糟糕生成缓慢且频繁地“过度格式化”把本来能跑的代码改得东一块西一块。问题在于人类规范中大量内容是“判断性约束”需要经验才能判断什么场景适用。AI没有完整的项目经验它只能根据字面规则做全局应用于是“方法不能超过80行”变成了它暴力拆分方法的理由拆出来的方法反而破坏了原有的业务内聚性。所以我最后把这份文档重新定性为“行为协议”内容重心放在项目使用的关键依赖、技术栈版本、目录结构约定、标准流程步骤、禁止项、必须遵守的输出格式。这些规则都是机器可执行的AI读一遍就能准确理解不需要主观判断。2.2 必须写清楚项目的“关键上下文快照”我们项目里有一个很常见的问题AI总把项目当成一个通用Spring Boot工程来处理生成各类基础配置和样板代码而我们项目其实已经模块化得很彻底有自己的脚手架和基础库。这类问题靠AI模型本身的常识解决不了必须靠规范里写清楚。我在规范的“项目全景”章节记录了项目类型、核心框架、包名规范、三个常用模块、现有公共工具类的调用方式、以及禁止使用的依赖列表。内容不需要特别长但一定要准确避免模糊表述。比如有一条规定是“所有数据库操作必须走DAO层封装禁止在Service层直接注入JdbcTemplate”当AI生成新代码时就会主动调用项目既有的DAO接口而不是自己写SQL再拼一个Template。另一条规定“如发现现有公共类缺少你需要的功能不得私自新增同名工具类应列出缺失能力并停止生成”这条极大地减少了AI生成重复工具类的比例。2.3 哪些内容不需要写进给AI看的规范这里要给各位提个醒不是所有规范内容都适合塞给AI。首先带有团队风纪色彩的内容比如“代码提交必须使用单号前缀”这类流程规则可以保留在传统规范里因为那是人主导的流程AI参与度不高。其次带有审美偏好的内容比如“保持代码整洁美观”“适当加注释”这类模糊要求AI无法量化执行写了也是白写反而增加上下文权重。我给AI看的规范只保留三类信息硬性技术栈信息、必须遵守的安全和性能红线、生成过程的格式要求。其余内容在传统规范里解决。这份给AI的规范文件也不宜过长我控制在2000字到3000字左右太长了AI的注意力会被稀释反而不容易执行。3. 实操落地我如何把AI代码规范注入项目3.1 在仓库根目录创建规范文件与规则目录落地开始前我确定的承载方式是在仓库根目录创建一份名为AI_CODING_STANDARD.md的文件同时搭建一个ai-rules/目录存放分场景规则。之所以不直接沿用已有的CONTRIBUTING.md是怕给AI看的指令和给人看的说明混合在一起导致两边都不便。我在AI_CODING_STANDARD.md开头写了三行加载说明提示工具优先读取这个文件并严格遵守。再配合不同工具的实际加载机制把规范文件路径放到工具的配置里。比如在JetBrains插件中将该文件标记为项目上下文在Cursor的Rules目录中通过引用路径指定在自定义Agent的System Prompt中直接注入全文。这样做的好处是可以按场景细分规则。核心规范文件放通用约束ai-rules/下面再根据前端、后端、单元测试、重构等主题拆分子文件让AI按特定任务加载对应部分降低上下文负担。3.2 用Prompt入口与配置文件双重约束光有规范文件还不够。我一直在和团队强调AI是一种“上下文敏感”的系统它遵循规则的优先级不是“仓库里的规范文件”优先而是“当前对话中的指令”优先。所以落地时我做了两件事。第一件事是统一成员使用AI工具时的Prompt入口模板在模板开头就声明“本项目的AI代码规范位于项目根目录的AI_CODING_STANDARD.md开始生成代码前请先完整阅读并严格按照其中的风格与结构约定执行。”这一步大幅提升了规则加载概率。第二件事是把规范按工具场景分别写入配置。Cursor的Project Rules、Copilot的OTHER说明文件、自建Agent的System Prompt各放一份精简版。这些配置会随着仓库分支一起走新成员一进来继承的全是同一套规则不需要互相传文档。另外我们在CI流水线加了一个规范检查脚本不校验代码风格只校验AI生成内容关键特征比如是否包含TODO、是否包含硬编码密钥占位符、是否绕过了DAO层直接操作数据源。这一步不是为了阻止AI生成而是为了让“违反规范”可以被快速发现。3.3 规范文件也执行版本管理与审查给AI制定的代码规范也是项目资产需要像其他代码一样走Review和变更记录。我们后来把这份文件纳入常规评审流程任何新增约束都必须写清“引入原因”和“期望解决的具体问题”。有一个例子早期规范里有一条“禁止生成静态工具类”写的时候感觉没问题过了两周项目需要新增一个和现有工具类完全无关的通用能力AI因为这条规则直接拒绝了任务。后来我们把这条规则改成“如项目已有同名或相似工具类禁止另起炉灶如确为全新领域允许新建并列出理由”这个“带条件的允许”远比“绝对禁止”更符合实际开发场景。建议团队定期回顾这份给的AI规范文件比如每两周或在引入新AI工具时检查一次删除已经失效的约束补充新发现的AI高频错误点。我在项目里就养成了这个习惯每逢AI代码Review出现某种规律性问题就去规范里对应位置补一条约束并附带典型反例说明让AI能更清楚地理解触发边界。4. 可直接抄走的AI开发规范核心模板4.1 全局任务理解与拆解规则这一节放在规范模板的最前面约束AI在接到任务后的“思考路径”。我给AI定的规则是每次收到任务先用自己的话复述需求确认范围。接着拆解子任务标注每个子任务的相互依赖关系并提示可能存在的风险点。比如“订单导出”任务拆解出来应当包括查询条件校验、权限校验、数据汇总、文件生成、历史记录留存五个子任务每个都要在回复中单独列出。必须强调的是这个拆解不是走形式。我明确要求AI在输出最终方案前不得直接生成代码否则打断并要求它重新补全设计过程。如果任务非常小比如“调整方法参数类型”AI可以省略拆解但在修改前仍要描述影响面和相关调用方。这条规则一旦坚持两周团队就会发现AI产出的代码与现有架构的契合度明显提升因为它不再跳过“任务分析”这一步直接进到“机械填码”。4.2 编码产出的硬性约束编码约束是AI代码规范的“正文”我按约束力强弱分成“红线”“强约束”和“建议项”三档。红线是绝对不能碰的包括禁止引入未经确认的新依赖禁止绕过项目的统一异常处理禁止把密钥、地址、账号等敏感配置硬编码禁止在提交代码时保留大段注释掉的代码块。AI一旦要触碰这些场景必须中止任务并说明原因。强约束是“必须遵守的产出格式”包括类名、方法名、变量命名遵循项目既有的命名映射所有对外暴露的接口必须包含入参校验新增方法必须附带单元测试或至少说明测试计划数据库操作只能使用项目统一DAO层。建议项则包括“方法尽量控制在合理长度”“优先复用现有工具函数”“日志级别选择要与场景匹配”等这类规则我不强制AI执行但会在Review时由人来判断减少大量无意义的格式争执。为了让这些约束更可操作我还在规范里附带一个“产出自检表”。AI生成完代码后必须自己按表核查一遍是否涉及敏感配置、是否使用了项目已有依赖、是否遵循DAO层访问规则、是否包含必要异常处理。自查机制实施后常见的低级错误明显减少。4.3 测试、验证与变更说明要求以前AI生成代码我们最担心的就是它“自己觉得没问题”但实际上没跑过测试甚至连最基本的编译都不保证。所以我在规范里要求凡是交给AI实现的完整功能模块产出物必须同时包含测试方案和验证步骤。现阶段我使用的是“先生成测试再生成实现”的逆序模式。AI拿到需求后先在回复中写出关键用例的测试伪代码明确输入、期望输出和边界条件然后才开始写实际代码。这样做的好处是让AI必须提前思考清楚行为边界而不是先写一堆实现最后再为“已经写完的代码”编几个测试补丁。另外任何一次生成完成后AI的回复末尾都要附一段“本变更说明”包括改动涉及的文件列表、是否影响已有接口、需要人工重点检查的部分。这条规定在多人协作场景中特别有用因为Review人能直接从AI的输出结构里找到该看的重点内容不费时猜。4.4 沟通交互风格与收敛原则除代码产出外我也在规范里写了几条交互风格约束目的是减少AI在对话中的“废话输出”。我要求AI在等代码时必须直接给出代码和必要的解释不要输出大段分析过程当一个任务有多种可行方案时AI可以给出方案对比表但必须标注推荐项和理由不得只丢出几个平级选项让用户做作业AI对不确定的信息要明确说“不确定”不能推测补充一个看似合理的默认值。交互风格里还有一条“问题收敛原则”同一问题最多追问两次若无法在对话中解决就整理成待确认清单输出避免对话发散无穷无尽。这条让AI从“聊天机器人”变成了“靠谱协作伙伴”团队的效率提升很明显。5. 常见问题速查与真实排查记录5.1 规范不生效的几个典型原因我在推进这件事的第一个星期就被打击了明明写好了规范文件AI还是我行我素。排查后发现问题出在“加载顺序”上有些AI工具的上下文是有限长度项目文档一多规范文件并没有被真正放入核心上下文窗口。我后来把规范文件路径放进工具的固定配置区域同时把Prompt入口改为“先生成规范摘要再开始任务”才解决了这个问题。还有一次是规范文件里“禁止事项”写得太抽象AI无法正确判断触发边界。比如“不要写出冗余代码”AI根本不知道什么叫“冗余”它觉得自己生成的每行都有必要。改成“不要新增项目已存在的工具方法”“不要复制超过三行重复逻辑”之后误判率立刻下降。总结成速查表后我在团队内部分享大部分成员遇到的“规范不生效”基本都能对号入座现象常见原因处理办法AI完全无视规范直接输出规范文件未加载进上下文把文件路径放到工具固定配置Prompt中显式声明AI部分遵守但漏掉细节规范太长注意力被稀释精简核心规范分场景拆分子文件AI频繁误判禁止事项规则表述含糊缺少具体反例每条规则追加典型反例说明AI输出大段分析不写代码未约定回复格式规范中明确提出“直接给代码简短解释”AI生成代码与项目风格不一致缺少项目上下文快照在规范中补充技术栈和目录结构的快照5.2 规范文件过长反而拖慢生成速度初期我把所有规则塞进一个文件结果有一次测试Agent生成一个CRUD接口光读规范就花了不少时间而且后续代码生成特别“小心翼翼”动不动就停下来问“请问你希望我如何处理异常”。交互体验很差效率反而比没规范时更低。这个问题的解法是分层核心规范控制在3000字以内用最直接的语言写“必须”和“禁止”扩展规则按任务类型拆分比如前端生成规则、后端生成规则、SQL规则、测试规则存成多个小文件。Agent在接到任务后根据任务类型选择加载对应扩展规则,而不是每次都把全部规范读完。这个改动上线后生成速度和代码质量都很理想。我建议一个项目最多保留一个核心规范文件加四五个场景子文件文件树要清晰规则之间不要互相矛盾。每次修改子文件都要同步检查核心规范文件是否冲突防止AI读到“一个地方说不能新建工具类另一个地方又说可以新建”这种自相矛盾的情况。5.3 一次实际Agent重构中的规范调试记录举一个我们团队遇到的具体实例。有一个Agent任务是从旧模块迁移用户数据到新表结构在没有规范的时期Agent生成一段包含大量冗余字段和临时判断逻辑的代码代码能跑但完全没法维护。追加给AI的规范后Agent在任务开始时先输出了拆解步骤列出了“数据源表字段映射”“历史数据清洗规则”“新表唯一键冲突处理”三个子任务然后逐个生成并且在“不确定事项”清单里明确问我们“旧表中存在字段A和字段B的取值逻辑冲突是否以新表字段B为准”。这个交互质量比之前高了一个量级。整个重构过程只用了两次人工干预一次是确认数据清洗规则另一次是确认迁移失败后的重试策略。最终代码结构比初期的版本更清晰得多。这次调试让我深刻意识到给AI的规范不是一次性写死的僵化条文它更像是“行为基线”随着项目的演进需要持续增补和调整。每次发现AI暴露新的问题我都把它补进规范里每次发现某条规范反而束缚效率就立刻把它改良或删除。这种持续打磨的节奏比“写一份完美规范文件”更重要。6. 后续可以继续扩展的方向规范在项目里跑顺之后我又开始尝试把同样思路扩展到更多场景。现在内部已经在做三件事目前都有初步成效。第一是把安全约束集成到规范中。比如AI生成代码时如果涉及文件上传、权限校验、外部接口调用必须走固定的安全检查清单。传统代码规范里这部分很少强调但AI生成代码时最容易漏掉的恰恰是这些非功能性需求。第二是让规范参与到Code Review里。我们已经尝试将规范中的关键规则写进静态检查规则让机器先扫一遍AI生成的Diff把涉嫌违规的点标注出来再交给人类Reviewer二次确认。这比纯靠人眼检查要高效很多。第三是在新成员培训过程中使用这套规范。新人加入项目后先读给AI看的代码规范再读传统代码规范心中的技术栈和项目脉络会比以前建立得更快。这也是一个额外的收获本来是用来约束AI的文档最后变成了团队知识沉淀的最小集。对我个人而言给AI制定代码规范这件事带来最大的认知变化是我们需要用一种“不是把AI当成工具而是把AI当成一名远程协作者”的心态来对待它。既然是一个协作者就该有统一的交接流程、行为边界和产出格式。团队里那些“AI写的代码一言难尽”的吐槽大多都源于缺少这套协作框架。如果你也在项目里大量使用AI生成代码真心建议抽半天时间把这份规范搭起来早搭早受益。
