1. 为什么突然要给 AI 立一套代码规范这事儿得从一次让我印象深刻的 code review 说起。团队引入 AI 辅助编程小半年大家从最初的新鲜、质疑到后来的“真香”效率确实上来了。但问题也在悄悄积累——我那天 review 一位同事的 MR改动文件有十几个打开一看风格五花八门有的函数写得像个迷你论文注释比代码还长有的地方又极简到让人摸不着头脑变量名就一个字母异常处理有的吞掉错误有的恨不得把堆栈打到用户脸上。更麻烦的是AI 生成的代码里有的按我们现有的分层规范来写有的则自创了一套“私货”结构看起来逻辑没毛病但跟项目里的既有风格完全是两路人马。这其实是所有深度使用 AI 编码的团队迟早要撞上的墙。我们得承认一个现实当下的大模型编程助手本质上是“概率性的代码生成器”它给出的代码是基于海量公开代码库训练出来的“平均表现”而不是基于你项目里的具体约束。你如果不给它画清楚边界它就会拿平均水准来“糊弄”你。平均水准是什么是网上各路教程、各类开源项目的混合体风格割裂、防御层次不一、甚至有时连依赖的用法都是过时版本。于是我们决定在项目里专门给 AI 增补一份“代码规范”——不是替代原来的团队规范而是叠加在人类规范之上专门用来约束 AI 生成代码的行为。这份规范从本质上看是一套写给大模型的“纪律条款”它要解决三个核心问题第一让 AI 输出稳定且可预测第二让 AI 生成代码的“第一版”就接近团队评审标准而不是把评审变成大型挑错现场第三让人类工程师从“给 AI 擦屁股”中解放出来把精力留给真正的业务逻辑。如果你所在的项目组也在用 AI 写代码或者正准备引入 AI 编程工具那么这篇文章里记录的思路、条款、落地方法以及我们踩过的坑应该能给你一个不错的参照。我会按我们实际推进的顺序来拆解先从规范的内容设计说起再讲怎么把它灌进 AI 的工作流程里最后是执行中遇到的典型问题与排查手段。整个方案不需要你推翻现有的研发流程也不需要你引入复杂的平台系统一支 prompt 文件加上几条 CI 检查规则就能起步。2. 给 AI 制定规范的设计思路与拆解2.1 规范和给人类看的规范本质上是两码事给 AI 立规范跟给团队新人写开发规范表面上都是“约束行为”但底层的逻辑完全不同。人类的规范文档很多时候只写“要做什么、不要做什么”剩下的靠人的常识、经验和上下文理解去补齐。比如我们原来的团队规范里有一条“禁止在循环体内执行数据库查询”人看到了会点头到了具体场景基本能判断什么算循环内、什么场景可以豁免。但 AI 不一样。它对规范的执行是字面级的、缺乏常识补全能力的。你说“代码要整洁”它能给你写出自认为整洁但其实很啰嗦的代码你说“不要写重复代码”它可能为了消除重复硬抽出过度抽象的函数。所以给 AI 的规范必须做到“机器可读、字面可执行、边界清晰”不能依赖模型去理解你的“言外之意”。我们内部把这条原则称为“对 AI 的规范要像对测试用例一样较真”。每一条规范都要能转换成一句不带歧义的指令最好还能附带正反例。比如“禁止在循环内查库”这条对 AI 要写成“当你在 for、while、forEach、map 等循环体内部调用数据库查询方法时必须先把查询结果提取到循环外的变量中循环内只允许访问已获取的数据集合。”这样描述模型在执行时才有明确抓手。2.2 规范的层级结构从全局红线到局部偏好在设计规范文件时我没有把它做成一个大而全的文档而是拆成了三层分文件存放。原因很简单不同场景下AI 需要关注的规范粒度不同。如果你把所有规则塞进一个庞大的上下文里不仅 token 消耗大模型还容易“注意力稀释”该遵守的反而忽略了。第一层叫“全局红线”放在项目根目录的 AGENTS.md 或者 CLAUDE.md 里是所有 AI 工具不管是用 Copilot、Cursor 还是其他 Agent都要加载的底线规则。这一层只写不可妥协的内容比如禁止提交密钥、禁止删除他人代码、禁止使用已废弃的 API、必须通过哪些基础检查才能提交等。全局红线控制在 20 条以内每条一句话便于模型全部记住。第二层叫“模块约定”放在各子模块或软件包目录下。这一层约束的是某个业务域内的特殊规则。比如我们的支付模块里要求金额字段一律使用整数分作为单位禁止浮点数运算比如订单模块里状态变更必须走统一的状态机方法不允许直接修改状态字段。这些约定跟着代码目录走AI 在处理对应模块的代码时能通过项目文件结构自动读取到相关约束。第三层叫“风格偏好”它不是强约束而是为了让代码更接近团队手写风格的软性建议。这一层我会写一些类似“变量命名优先使用业务术语而不是泛化的 data、info”“函数注释说明意图而不是复述代码”这类内容。风格偏好不需要 AI 强制遵守但作为上下文注入后明显能提升代码的可读性和团队的接受度。为什么这样分因为 LLM 的指令遵循存在“近因效应”和“特定性优先”现象。离当前任务越近的指令、描述越具体的指令被遵循的概率越高。把全局红线放在根目录把模块约定放在具体目录就能最大化利用这个特性。2.3 规范不是一锤子买卖需要版本化与迭代给 AI 的代码规范在项目里应该拥有跟源代码同等的待遇——纳入版本管理、有变更记录、有评审过程。我们最开始犯的错就是让规范停留在口头或者某个 wiki 页面里结果规范更新了AI 工具加载的还是旧版本导致生成代码的行为漂移。后来我们把规范文件放进了 git 仓库任何改动都必须走 MR 评审。每次规范变更我们会在文件头部的“变更日志”里写明改动点、原因和生效范围。这样做还有一个额外好处当 AI 生成行为出现异常时我们可以快速回溯“规范最近改了什么”排查是不是某条新规范把模型带偏了。迭代方面我们保持一个比较务实的心态规范不是越严越好而是越“恰好”越好。如果某条规范频繁被 AI 违反我们要分析是描述不够精确还是这条规范本身就反直觉。如果一条规范长期零触发也可以考虑删掉减少上下文噪声。3. 规范的核心内容与实操要点3.1 通用红线清单先把底线焊死先展示我们目前在全局规范里实际使用的核心清单并拆解每条背后的意图。你可以基于项目语言和技术栈增删禁止提交敏感信息包括 API 密钥、数据库连接串、token、.env 文件内容。AI 经常在示例代码里顺手硬编码密钥这条必须放在第一句。我们同时要求 AI 在发现代码中出现形如sk-、AKIA、password 之类特征串时主动替换为环境变量引用。禁止引入未经确认的新依赖AI 特别喜欢为了一个小工具函数去引入 lodash、day.js 之类的第三方库。我们的规范要求如果现有代码或团队内部 util 已有等价实现必须复用之确实需要新增依赖的AI 应生成带 TODO 标记的代码并明确说明引入理由等待人工评审。不要删除或修改与当前任务无关的代码AI 在重构时容易出现“顺手清理”行为删掉一些它认为是冗余但实际被其他逻辑依赖的代码。规范明确要求只能改动与本次需求直接相关的行。新代码必须匹配现有代码风格包括缩进、命名风格、是否分号、字符串引号等。我们约定 AI 在生成代码前必须先读取同目录下至少一个现有文件来推断风格而不是直接套用“最流行”的风格。错误处理不允许空 catchAI 默认生成不规范代码时经常产出catch (e) {}这种吞异常写法。规范要求 catch 块内至少要记录日志或抛出带有上下文的异常。禁止硬编码魔法值对于数字、字符串字面量如果在一个函数里出现超过两次就必须提取为命名常量。每条红线我们都配套了一个正例和反例块放在规范文件的最下方。你别小看这一招给 AI 看正反例比单纯描述规则的效果好一个量级。大模型本质上是模式匹配机器你给它的“不该长什么样”范例越多它跑偏的概率就越低。3.2 模块级规范怎么写才有约束力模块级规范的撰写和全局规范有微妙的差异。这里的核心是要绑定到具体的代码符号上而不是描述抽象原则。比如你说“支付模块必须使用 BigDecimal 处理金额”AI 能听懂但不知道边界在哪你得写成“在 com.xxx.payment 包下所有涉及金额加减乘除的代码必须使用 Amount 工具类禁止直接对 float、double 类型执行算术运算。金额参数类型统一为 Long单位分”。这样模型在执行支付相关任务时就能准确命中约束。另外一个要点是模块规范要跟着业务文档走。我们在每个模块的 README 或 package 的约定文件里用固定区块标注“AI 接入注意”内容不超过 10 条。模型在读取模块代码时通常会顺带读一下 README这个区块就会自然进入它的上下文。如果模块改了关键设计记得同步更新这个区块否则旧约定会持续“污染”AI 的生成。我还建议在每个模块规范里写一个“不做什么”的列表。LLM 在遵循指令时对否定指令的敏感性通常低于肯定指令所以否定性的规则要写得特别明确。例如“不要创建新的 service 类除非现有 service 无法承载当前职责且需在 MR 描述中说明重构理由”。这个“除非”写得越具体AI 就越不会轻易越界。3.3 风格偏好与硬规范的区别处理风格类规范比如“函数命名倾向动词开头”“注释用中文写”我们单独放一个文件不强制校验但会让 AI 在生成完代码后自己 review 一遍。为什么要这样对待因为风格类规则如果硬性约束会大幅增加模型的思维负担反而影响主逻辑的生成质量。AI 一旦把注意力放在“变量名是不是够优雅”上就容易在核心功能实现上犯低级错误。我见过有些团队为了追求“AI 生成代码零改动”把命名规范、注释格式都写进强约束里结果代码生成速度明显变慢而且经常为了形式牺牲逻辑清晰度。所以我倾向于让 AI 先保证正确性与可维护性再在后续的人工评审过程中逐步调整风格问题。毕竟代码风格问题是可以靠格式化工具和静态检查自动兜底的而逻辑缺陷和架构偏差才是真正需要人的判断力去兜底的点。你可以把风格偏好理解为给 AI 的“气口”适当留白让它发挥反而能让生成的代码更像团队里一个老手写的。我们曾经在风格文件里加了一条“函数的圈复杂度超过 10 时主动拆分”这条反而带来不少积极作用因为 AI 会在逻辑变复杂时自己停下来拆函数而不是硬拗一个巨无霸。3.4 规范落地从 prompt 文件到工程检查规范文件的载体我们用的是 Markdown文件名是 AGENTS.md放在仓库根目录。主流的 AI 编程工具像 GitHub Copilot 的自定义指令、Cursor 的 Rules都支持加载项目内的规则文件。除了给工具加载外我们还做了一层硬校验在 CI 流水线里加入了针对 AI 生成“典型违规”的自动检查。比如用 gitleaks 检查密钥泄露用 eslint 的 no-empty 规则检查空 catch。硬校验的意义在于不能让规范只停留在“建议”层面出现违规时要有客观的失败信号。在 prompt 层面我们会在需要 AI 生成代码的任务描述末尾自动追加一句固定后缀注意请严格遵循项目根目录 AGENTS.md 中的规则。如与当前模块 README 中的A I 接入注意冲突以后者为准。生成完代码后请对照 AGENTS.md 自查一遍并在 代码注释中标注你认为可能有争议的设计决策。这句后缀看起来简单其实起了很好的作用。前一句告诉模型去读取规范第二句解决规范冲突时的优先级第三句则让模型在生成时多一层自我审视第四句为后续人工 review 提供了有价值的上下文。4. 实操过程与核心环节实现4.1 从零搭建规范文件三步走如果你现在要动手给项目制定 AI 代码规范我建议按三个步骤推进别想着一次到位。第一步是“沉淀纠偏记录”。把过去一两个月里 AI 生成代码被 review 打回的问题按照频率排序。最常见的问题优先写进规范。你不用猜 AI 会犯什么错你手头的 MR 评论、bug 记录就是最好的素材。我们当时的高频条目是“不必要的依赖引入”“硬编码密钥”“重复实现已有工具函数”这三项后来都成了规范里的头几条。第二步是“起草与试行”。整理出一个 v0.1 版规范挑一个中等复杂度的模块试行两周。注意不要全组铺开找一个小模块的好处是试错成本低反馈周期短你可以快速判断哪些条目有效、哪些描述有歧义。试行期间要记录 AI 生成代码的返工率——如果返工率没下降说明规范没写到位或者加载方式有问题需要回头调整。第三步是“全量推广与定期修订”。v0.1 稳定后把规范同步到其他模块并在每周的工程例会上留出 5 分钟专门讨论“规范条款的有效性”。我们的修订周期是双周一次每次改动一行也要走 MR保持变更可追溯。如果你觉得从零起草太耗精力可以直接找一些公开的“AI 编码规范示例”作为底稿再按项目情况裁剪。但不要原文照搬别人的规范是基于他们项目的痛点和语言特性沉淀的直接套用会在你的场景里水土不服。4.2 关键参数与模板直接抄作业的版本下面我给出一个可直接参考的 AGENTS.md 简化模板你可以在此基础上按需增删# AGENTS.md项目 AI 编码规则 ## 全局红线必须遵守 1. 禁止提交任何敏感信息API 密钥、token、连接串、密码等。 若在任务中出现替换为环境变量引用并注释说明所需环境变量名。 2. 禁止删除、注释掉与当前任务无关的既有代码。 如需调整必须在 MR 描述中逐条说明理由。 3. 禁止为当前任务引入新的第三方依赖。 如确有必要生成代码中使用 TODO(dep) 标记并在注释里说明引入目的 等待人工评审通过后方可合并。 4. 禁止在 catch 块中留空或直接吞掉异常。 必须至少记录日志使用现有 logger或抛出带业务上下文的异常。 5. 新代码的风格匹配同目录现有代码缩进、引号、分号、命名风格均保持一致。 6. 禁止硬编码魔法值。同一函数内超过两次出现的字面量提取为命名常量。 7. 禁止使用已废弃 API、已标记删除的方法、明显过时版本写法。 如不确定 API 是否仍受支持在代码注释中标注 TODO(verify) 并说明你的顾虑。 ## 自查清单代码生成完成后 - [ ] 是否读取了根目录 AGENTS.md - [ ] 是否有硬编码的密钥或敏感信息 - [ ] 是否修改了与当前任务无关的代码 - [ ] 每个 catch 块是否都有处理逻辑 - [ ] 新代码风格与同目录文件是否一致 ## 冲突处理 当本文件规则与模块目录下 README 或模块规范冲突时以模块规范为准 如模块规范缺失按本文件执行。这个模板的核心思路是“能用一句明确指令说清的绝不用一段抽象描述”。你可以看到每条规则里除了说明“不能做什么”还给出了“应该怎么做”以及“无法避免时的兜底动作”。比如第 3 条里写“生成代码中使用 TODO(dep) 标记”这就让 AI 在确实需要新依赖时仍然有一个合规的出入口而不是被迫违反规范或者干脆拒绝生成。4.3 把规范接入 AI 工具Cursor 与 Copilot 的实测在实际接入环节不同 AI 编程工具对规范文件的加载机制略有差异我分别说一下我的实测体会。如果你用的是 Cursor在项目根目录放 .cursor/rules 文件或者直接放 AGENTS.mdCursor 都会自动识别并在对话上下文中加载。我个人的建议是用 .cursor/rules 里的一个专门文件来放“面向 AI 编码约束”把 AGENTS.md 放在仓库根目录也保留一份这样即使团队里有成员用别的工具规范依然是可发现的。Cursor 的 Rules 支持按文件路径做 glob 匹配你可以把模块级规范放在对应目录下实现“进入哪个代码目录就自动切换到哪套规则”效果很不错。如果你用的是 GitHub Copilot自定义指令分为两种一种是 GitHub 仓库设置的 .github/copilot-instructions.md对所有开发者生效另一种是个人在本地设置的自定义指令。仓库级的 instructions 适合放全局红线因为它是跟随项目的其他协作者 clone 下来就能用。Copilot 对规范文件的遵循程度不如 Cursor 的 Rules 那么“显式”但实际测试下来只要把规则写得足够清晰它在生成时确实会更守规矩。还需要提一下的是规范文件本身建议使用英文和中文双语的关键词。因为当前主流模型对英文指令的遵循稳定性通常优于中文但完全用英文写团队阅读成本高。我们的做法是规则标题用英文详细解释用中文关键约束词用英文。这样既提高了模型遵循率也保证了团队成员的可读性。4.4 通过 CI 让规范“带电”硬性校验配置如果只有 prompt 层面的软约束AI 还是会时不时越界。我们要让规范在工程层面有“牙齿”。我在 CI 流程里加了三个轻量级检查第一个是密钥扫描用的是 gitleaks。配置很简单在流水线里加一步gitleaks detect --source .就够。这一步能把硬编码密钥的问题拦在合并前。过去一个季度我们抓到过 3 次 AI 生成的代码里带测试用密钥全靠这一步兜住。第二个是静态检查规则增强。在 ESLint 或对应语言的 Linter 配置里开启 no-empty、no-duplicate-imports、no-unused-vars 等和规范直接相关的规则。注意把规则级别设为 error 而不是 warn否则 AI 会倾向于忽略 warning。第三个是依赖白名单检查。我们写了一个简短的脚本读取 package.json 的 dependencies 字段和一份白名单列表比对新增依赖如果没有对应的 MR 关联编号CI 直接失败。这个检查有点严格但确实有效地刹住了 AI 随意引入依赖的毛病。你可能会问这些检查和给“人类”的规范有什么区别其实检查规则和规范文件是同一套逻辑的一体两面规范文件是用来“告诉AI应该怎么做”的输入CI 检查是用来“验证AI实际做了什么”的输出。两者缺一不可。没有规范文件的 CI 检查只是被动防御没有 CI 检查的规范文件只是纸上谈兵。5. 规范执行中遇到的坑与排查心得5.1 模型不读规范文件怎么排查这是最常见的坑。你把 AGENTS.md 写得天花乱坠但 AI 生成代码时仿佛根本没看过。排查思路先从加载链路开始检查工具是否正确识别了规范文件路径比如 Cursor 的 Rules 是否匹配了目标目录。很多时候问题出在 glob 规则写错了规则只对 src 目录生效你在 tests 目录下让 AI 写代码它当然读不到。其次是上下文的截断问题。项目代码一多AI 的上下文窗口被代码填满规范文件可能被挤出注意力区。我们的做法是把规范里的最核心三条红线在每次问答的任务描述里再重复一遍。比如注意不引入新依赖不硬编码密钥不修改无关代码。这三句话成本极低但能把 AI 的行为锚定住。你也可以尝试在让 AI 生成代码之前先发一条指令“请阅读项目根目录 AGENTS.md并复述其中前三条规则”确认它真的读进去了。这一步虽多花几秒但对稳定长任务的执行质量很有帮助。5.2 规范之间互相打架怎么办规范一多就会出现自相矛盾的情况。比如全局规范说“禁止新增依赖”但某个模块规范说“本模块必须使用某第三方库进行日期格式化”。当 AI 同时读到两条规则时轻则随机选一条执行重则产生混乱。解决办法有两个。第一在每份规范文件的开头写清楚优先级。我们的约定是模块规范 全局规范 工具默认行为。然后在全局规范里加一条兜底“当本文件与模块规范冲突时以模块规范为准。”这样模型在判断规则冲突时就有明确依据。第二尽量避免规则条目之间的“逻辑交集”。在新增一条规范前先检索已有规则如果新规则和旧规则描述的范围有重叠要么合并要么明确新旧规则的适用边界。我们每两周修订规范时有一项固定任务就是“冲突扫描”把可能互斥的条目列出来逐条梳理。5.3 规范太细导致 AI“过度优化”还有一个比较隐蔽的问题规范写得太细AI 在处理小任务时反而会过度设计。比如你要求“所有函数必须注明复杂度、必须有完整的 JSDoc、必须处理所有边界条件”AI 在写一个简单的工具函数时也会生成一大坨防御代码和注释看起来无懈可击实际上把简单的逻辑搞复杂了可读性和维护性反而下降。我们的应对方式是在规范里加一条“匹配任务规模”的原则小改动保持小改动不要为了满足规范而扩大代码体积。这条原则听起来像废话但对模型来说很重要因为模型倾向于“最大化满足所有约束”一旦约束多它就会通过堆代码来“求稳”。在规范文件里加入这条原则相当于许可它在合理范围做减法整体生成质量会更贴近人类工程师的判断。5.4 如何评估规范有没有效果最后聊聊怎么判断这套规范值不值得持续投入。我们用的核心指标有三个第一个是 MR 的一次通过率也就是不含重大修改意见直接合入的比例。引入规范前AI 参与较多的 MR 一次通过率大概在三成左右规范稳定运行一个月后这个数字提升到了接近六成。虽然不敢说全是规范的功劳但趋势很明显。第二个是 AI 相关 MR 的平均 review 耗时。之前每份 AI 相关 MR 的评审时间普遍要 20 分钟以上因为要挑一堆风格和约束问题。现在大部分时间花在业务逻辑评审上耗时降到了 10 分钟左右。第三个是“规范违规”的密度我们靠 CI 检查和人工标记统计。从初期每个 MR 平均 2~3 处违规下降到现在的约 0.5 处。我个人在实际推进这件事时还有一个体会规范存在的意义不是把 AI 变成一个“不会犯错”的工具而是让它的错误变得可预期、可控制。就像给一个非常能干但有点毛躁的新同事配了一本操作手册你不指望他从此毫不犯错但至少他犯错的方向、频率、半径都清晰可控团队协作的摩擦系数自然就降下来了。如果你也在为项目里的 AI 协作头疼不妨从这个方向试试先别贪多挑三五个痛点写成规则跑两周看效果再逐步迭代。