1. 为什么项目必须给AI单独制定代码规范1.1 通用规范拿AI没辙团队里大部分人都遇到过这个场景项目已经沉淀了几年的代码规范文档里面写了命名规则、目录结构、错误处理方式、提交信息格式评审的时候也一直拿这些标准卡人。但等到AI编程工具大规模接入开发流程后大家发现一个尴尬的事实——规范文档写了AI根本不看。不是AI工具没有能力而是它压根不知道这些规范的存在。AI编程助手在你写代码的时候眼里看到的只是当前文件、相关文件和历史上下文它不会主动去仓库根目录翻一遍你的CONVENTIONS.md或者开发规范文档。即便你把规范文档地址告诉它不同工具对文档的解析方式、读取深度、优先级也完全不同。结果就是AI生成的代码经常出现“能力很强但风格很野”的情况——方法命名、参数风格、错误处理、组件拆分逻辑每一处都跟团队约定不一致。我见过最典型的一次是团队让AI帮忙重构一个老接口AI确实把业务逻辑理清楚了但错误处理写了三种风格有的地方用throw有的地方返回null有的地方统一返回Result对象。联调的时候后端同事直接崩溃因为调用方根本不确定这个方法到底会怎么失败。问题不在AI的代码水平在于工程上下文完全没有被AI感知到。1.2 AI代码最容易出现的三类失控结合自己和周边团队的实际观察AI生成的代码失控基本集中在三个维度。第一类是风格不一致。AI模型在训练时见过的代码面太广了JSDoc、TSDoc、JavaDoc、Python docstring全都有它生成代码时会随机“抽取”某个来源的风格。你今天看着它生成的代码像Google风格明天又像Airbnb风格同一份PR里两种风格还能并存活脱脱一个“拼盘”。这种现象在进行跨文件重构时尤其严重——每个文件都是AI独立生成的风格完全没有延续性。第二类是架构意识缺失。AI的上下文窗口有限它看到的往往是文件级甚至函数级信息。你让它“给新模块加个导出入口”它不会去对照现有的模块划分方式而是直接在它认为合理的地方新建文件。一套遵循分层架构的工程里AI可能把数据访问逻辑直接写进组件或者在新代码里复用了已经被废弃的底层方法。这种问题在代码评审阶段很容易被漏掉因为单看文件本身没有大毛病只有对照整体架构图才能发现它在“错误的位置做了正确的事”。第三类是工具链兼容性问题。很多AI工具倾向于使用“最新最干净的写法”但这些写法可能跟项目里固定的依赖版本、构建配置、Lint规则不兼容。最典型的例子是项目还在用Vue 2AI却按Vue 3的语法写了组件项目禁止使用anyAI却用它来绕过类型报错项目统一用单引号和无分号AI却每次生成双引号和分号。这些问题的根源只有一个——AI不知道你们项目里的约束条件。1.3 给AI用的规范到底解决什么问题给AI制定代码规范本质上不是在约束AI而是在给AI补齐“团队知识”和“工程约束”这两块关键信息。它的核心目标有三个第一把规则写进AI的输入层。让AI在生成代码之前就看到这些规则而不是生成了再靠人肉检查、批评、返工。第二降低评审负担。大部分低级问题在生成阶段就被规避掉了代码评审的人力可以集中在业务逻辑、性能、安全性这些真正需要人判断的地方。第三让AI产出可预测。一个团队如果每天都在用AI写代码那么模型的随机性会被最大程度压平——同一批指令、同一条规范不管是今天生成还是明天生成不管是在Cursor里生成还是在Copilot里生成产出的风格都应保持基本一致。所以规范的受众不是人类程序员而是AI编程工具本身。一个“给AI的规范”应该像AGENTS.md一样能被工具自动读取、自动执行而不是像传统规范文档那样躺在Wiki里吃灰。2. 落地前的准备工作与规范内容设计2.1 规范文件放哪AI才能稳定读到如果你还想着“把规范写在一个文档里每次在提示词里让AI去读”那这条规范大概率几天后就失效了。因为人总会忘记粘贴提示词的总长度也有限制而且不同的AI工具对上下文的利用方式不一样你辛辛苦苦粘进去的几千字很可能被模型当作次要背景信息处理。正确的做法是把规范文件放到AI工具约定的读取路径上。目前主流AI编程工具都支持通过特定文件来自动加载工程规范Claude Code读取CLAUDE.mdCodex和大量开源Agent工具读取AGENTS.mdCursor从.cursor/rules目录读取规则GitHub Copilot读取.github/copilot-instructions.md。这些文件名不是摆设工具会优先读取它们并合并进模型上下文。我个人的建议是在主流的几种工具里选一个作为团队的标准然后把规范内容尽量精简后放进它“约定俗成”的位置。如果你的团队同时用多款AI工具可以在仓库根目录同时放置AGENTS.md和CLAUDE.md内容保持一致通过软链接或者统一生成脚本维护避免改了一处忘了另一处。这里的关键经验是规范文件必须放在仓库里并随代码一起走版本管理而不是放在Wiki或飞书文档里——因为AI工具只会读取它能够访问的本地文件。2.2 AI规范与人类规范的侧重点差异给AI看的代码规范和给团队同学看的开发规范看着名字一样内容组织方式却有很大差别。人类规范往往讲“为什么”会花大篇幅解释背景、权衡和例外场景——比如“为什么禁止在循环里发HTTP请求”因为要说明白N1问题的来龙去脉。但AI规范只需要讲“做什么”和“不要做什么”原因、背景、权衡这些内容对模型来说信息密度太低不仅浪费上下文窗口还可能让模型在“理解原因”和“执行规则”之间犹豫。一个高效的AI代码规范建议只包含三类内容硬性禁令明确不允许出现的写法、禁止使用的API、禁止绕过的检查项。强制格式命名风格、文件组织、导入顺序、注释约定、错误处理模式。默认方案当AI不确定怎么做时应该默认采用哪种模式。原因和解释部分如果有必要放在每条规则后面的括号里用一句一带而过。比如“禁止在api目录以外直接调用fetch为了统一错误处理和接口鉴权”。长篇大论的解释留给人来看就够了。另外要特别注意给AI的规范语气要绝对命令式。不要写成“建议使用”“可以考虑”“尽量保持”而要用“必须”“禁止”“默认使用”。模型对模糊措辞的执行力度远低于强硬措辞这是实测下来的经验。2.3 规则粒度与分层的取舍还有一个常见的误区是“规则越多越好”。有些团队把AI规范写了两千多字恨不得把之前十年积累的所有最佳实践都塞进去。结果发现AI工具的上下文窗口被挤占得厉害而且规则之间的优先级不明确模型表现反而更差——每一条都看到一点每条都执行得不彻底。我的建议是按“层级”拆分而不是按“篇幅”堆砌。仓库级别的根目录文件放的是所有模块都必须遵守的基础规则比如语言版本、格式化风格、禁止事项各子模块或服务目录下可以放局部规则文件规定这个模块特有的架构要求和技术选型。这样AI在处理一个具体模块的代码时读到的规则量更小、相关性更高执行率也会明显提升。规则本身也要控制粒度。单条规则尽量做到“一句话能说清”不要一条规则里塞好几个约束条件。比如“禁止在utils目录中引用业务模块的代码工具函数必须是无副作用的纯函数并且在入口处必须写JSDoc”——这条规则包含了三个互相独立的要求模型在生成时很容易只记住其中一两个。应该拆成三条独立规则各自单独执行。3. 核心环节在项目中落地AI代码规范3.1 初始版本规范文件怎么搭落到实操层面我给团队做初始版本的时候一般是从以下这个模板起步的。文件放在仓库根目录命名为AGENTS.md内容只覆盖最关键的约束不贪多。# 项目代码规范AI专用 ## 技术栈 - 语言TypeScriptstrict模式 - 框架React 18 Next.js 14App Router - 样式Tailwind CSS禁止编写自定义全局CSS类 ## 通用规则 - 禁止使用 any 类型遇到无法推断的类型优先定义 interface - 函数必须显式声明返回值类型 - 组件文件名使用 PascalCase工具函数文件使用 camelCase - 禁止在组件内联定义样式对象一律使用 Tailwind 原子类 - 禁止直接使用 localStorage/sessionStorage必须通过 utils/storage.ts 封装 - 错误处理统一使用 Result 模式禁止在业务层直接 throw Error - API 请求必须通过 src/api 目录下的函数转发禁止在组件中直接调用 fetch ## 代码生成默认模式 - 新组件默认生成函数组件 hooks - 列表渲染必须携带稳定 key禁止使用 index 作为 key - 事件处理函数使用 handle 前缀命名 - 新增依赖时先检查 package.json 中是否已有同类依赖这个模板的核心思路是“少而硬”每条规则都是AI能理解和立刻执行的所有规则都是可以从语法上或结构上被检查出来的技术栈信息放在最前面帮AI在生成代码前先建立基础判断。注意我没有在这个文件里写注释说明为什么这样设计。给AI的工具性文件注释越少越好——AI会把这些注释也当作规则的一部分处理反而稀释了规则的密度。3.2 规范文件要按语言和场景做变体根目录的AGENTS.md是给整个仓库用的基础规范但AI在不同场景下的行为模式其实不一样。有的AI Agent会被用来写后端接口有的会被用来写前端页面还有的会被用来跑自动化测试脚本。如果所有场景都共用一份规范你会发现规则之间的冲突逐渐暴露。以我一个全栈项目为例。根目录的规范文件管的是通用风格——命名、文件结构、错误处理但我在后端模块的目录下额外放了一个AGENTS.md里面明确写了“数据库操作必须走Repository层”“事务边界必须由Service层管理”“禁止在Controller层写业务逻辑”前端模块的目录下又放了另一个写着“组件必须通过props传参禁止使用全局状态管理库访问页面级状态”“新页面默认使用 Server Component除非需要客户端交互”。这种做法的好处是当AI Agent在这个目录下生成代码时它能读到最近上下文里的模块级规范回答会更“贴地气”。也就是说规则不是越多越好而是在什么场景给什么样的规则。3.3 让AI“记得”规范的两种方式在项目实践中让AI规范真正“进入”模型推理过程需要考虑的不是规范本身而是AI工具如何加载它。第一种方式是直接依赖AI工具的内置规则机制。比如Claude Code会在启动时自动读取项目根目录的CLAUDE.md把它注入到每次对话的上下文里Cursor在开启Rules功能后也会把.cursor/rules目录下的规则作为系统提示词的一部分。这种方式最省力不需要用户在每次对话中手动告诉AI“请阅读规范文件”。第二种方式是在主动对话中引用规范。当你让AI处理一个大任务时可以在提示词里写明“请先阅读根目录下的AGENTS.md然后严格按照其中的约定来重构这些文件”。这种方式适合那些不支持自动加载规则的工具也适合那些上下文比较窄、但你又希望AI严格遵守规范的重要任务——你可以在关键任务开始时把规范作为“第一优先级指令”手动强调一遍。在实际项目中我会同时启用这两种方式平时靠工具的自动加载兜底重要任务再加一句显式引用。实测下来双通道结合比只靠任何一种方式都稳定。3.4 从规范落地到代码评审的完整闭环如果到此为止你会发现在“用AI生成代码”这个环节规范该起作用的地方已经起作用了。但现实是AI不是一次性能做到100%遵守规则的它会时不时漏掉某个细节。这时候要补上的是一个“规范校验”的闭环。我在实际操作中的顺序是AI生成代码后先用eslint带完整规则集跑一遍再跑prettier --check确认格式与规范一致如果代码涉及类型定义跑一次tsc确认严格模式通过最后把这三类报错信息当作上下文回传给AI让它按错误信息逐条修复。这个步骤看起来简单但它恰恰是“AI规范落地”中很多人忽略的部分。AI生成的代码是概率模型输出的结果它不是你写完就能保证正确的文本文件而是一个需要持续迭代的草稿。如果你没有校验闭环你就永远不知道规范到底有没有被执行。跑完校验之后还有个值得做的动作把校验错误里反复出现的那几类问题追加回规范文件的“禁止”区。比如我发现AI连续三次都忘了给Promise的catch分支做错误处理那就在规范里加一条“所有异步操作必须显式处理rejection”。这个习惯坚持两个月后你和AI之间的“规范磨合期”就基本结束了。4. 常见问题与排查技巧实录4.1 规则写了不生效的五个原因在实际推行中团队最常问的一句话就是“规范文件里写清楚了AI怎么还是不按规则来”这个问题我排查过很多次总结下来基本就是以下五类原因。一是规则不在AI的读取范围内。工具没有把AGENTS.md或CLAUDE.md当作自动加载的文件或者你用的是某个不支持自定义规则的AI工具。排查方法是直接在对话里问AI“你有没有读取到项目根目录下的规范文件”它如果答不上来说明文件压根没进上下文。这种情况要把规则改成通过提示词手动引用的方式。二是规则太多太长。规范文件超过两千字后AI对规则区的关注权重会被分散尤其当规则区和代码实现区混在同一个上下文时模型可能会“选择性地遗忘”部分规则。排查方法是把规范精简到最核心的50条以内或者把不常用的分支规则拆到子目录。三是规则优先级冲突。比如规范里写了“使用Tailwind原子类”但某条业务需求要求动态拼接样式AI就会陷入规则冲突中最终选了一个它“看起来更合理”的方案。排查方法是在规范开头加一条“当规则与用户指令冲突时以用户指令为准”或者“以项目规范为准”明确优先级。四是语气太软。我之前写过一版规范大量使用了“建议”“推荐”“可以”结果AI的执行率只有50%左右。改成“必须”“禁止”“默认”之后执行率明显提升。AI对命令式和模糊式指令的处理效果差异非常大这在模型设计上就有实验依据。五是上下文覆盖。某些AI工具在长对话中会越来越偏向“从对话历史里找线索”而不是从规范文件里找线索。如果你发现前几次对话正常越往后AI越跑偏可以在关键节点重新发起一次新对话并让AI重新读一遍规范。4.2 规范太严格导致AI“罢工”怎么办规则太严格也是一个真实存在的问题而且很多人一开始意识不到。有一种情况是规范文件里写了一条“禁止在任何场景下使用flex布局一律使用grid”然后AI在实现某个确实更适合flex的组件时会不断尝试用grid绕过flex的语法最终生成一堆又长又绕的代码甚至直接给个“此需求无法完成”的回应。这种“罢工”的本质是规范剥夺了模型在生成路径上的灵活性导致它在找不到合法解时选择了放弃或硬凑。解决思路并不是盲目删规则而是给规则加上“例外通道”。在规范文件里加一条兜底条款例如“如果为实现某个需求必须违反上述规定请先向用户说明原因并获得确认”。这样做的好处有三个AI不会再硬凑代码规则的完整性得到保留当它确实需要突破规范时会触发一次明确的人工评审而不是由模型自行决策。这种“默认执行异常上报”的机制本质上和人类团队里的“规范豁免流程”是一样的逻辑只不过对象从人换成了AI。4.3 新成员适应与规范演进的节奏引入AI规范之后团队内部还会出现一个之前没有预料到的问题老开发者和新成员对规范的感知差异变得更大了。人类看规范需要逐字读、理解、再记忆但AI读规范是即时生效的所以老开发者对规范的认同感有时候还不如对AI工具生成的代码的信任感高。于是我在实际项目中采用了一套很轻量的推送机制规定每个月花半天时间把上个月AI代码中出现的“典型不合规案例”收集起来挑两到三个最有代表性的写进规范文件的开头作为“反面示例”。这些示例不解释原理只写“禁止以下风格”和“正确写法”。这套机制的核心价值在于它不是靠某个人自觉去推动的而是被构建成了一个持续进化的系统。规范文件随着项目的进展、AI工具的升级和团队的实践不断微调AI生成代码的质量也因此能保持在一个相对稳定的高位上。5. 这套规范在项目里的实际效果在推行AI代码规范的第一个月里最直观的变化是代码评审通过率上来了。评审时不再出现“为什么是双引号”“这个变量名怎么跟上下文毫无关系”“为什么又直接调fetch”这类琐碎的低级问题。这些东西不是说AI永远不会再犯而是“批量触发”的概率大幅降低了。第二个明显变化是Lint修复效率提升了。以前收到ESLint报错我习惯性手动改或者一条条给AI指出现在直接把报错内容原样丢给AI工具让它按规范文件自行修复第一轮修复通过率大概在80%左右剩下20%多数是规则之间的冲突或上下文理解不到位人工稍微点拨一下就能过。第三个变化很多人没预料到团队成员对新技术的上手速度变快了。因为AI规范文件把项目的技术栈、依赖偏好、推荐默认方案都写清楚了一个刚加入团队、对业务还不太熟悉的新同学用AI写出来的代码已经能基本踩在团队风格上了。这等于把老成员脑子里的“项目潜规则”显式化成了机器可读的版本。我个人在实际操作中最大的体会是给AI制定代码规范这件事本质上是在和AI搭建一套“协作协议”而不是单方面给它下命令。你把约束写清楚AI才能在没有你盯着的时候也替你守住底线。反过来如果规范写得太粗AI自然会用自己见过最多的那种风格来填充你留下的空白然后你就要花大量时间去“收拾现场”。这两者之间的成本差距谁实践过谁知道。最后再分享一个小技巧规范文件里可以画一条“禁止事项”我特意把团队踩过的所有坑都写在里面。每隔两三个月回看一次你会发现自己团队和AI协作时的“事故率”真的在慢慢下降这是我最满意的部分。
