我在给项目接入AI编程后前两周的最大感受不是效率提升而是代码风格突然不受控了。AI生成代码的速度确实快但同一个功能换个需求描述方式它可能给你写三种不同风格的实现目录层级随心情命名忽长忽短注释时有时无。更麻烦的是它会默认采用训练数据里最常见的写法而那种写法未必符合我们项目的技术栈约定和工程质量底线。于是我在项目里新增了一份“给AI制定的代码规范”不是给同事看的那种而是专门喂给AI工具作为行为约束。这篇文章就来聊聊这份规范是怎么设计的怎么让它真正被AI读进去、执行出来以及遇到AI不守规矩时我踩过的一些坑和处理办法。如果你正准备在团队里引入AI辅助编码或者已经被AI生成的“野代码”搞得有些头疼这份经验应该能帮你少走不少弯路。1. 为什么项目里要给AI单独定一份代码规范给AI定代码规范这件事很多人第一反应是不理解。代码规范不是给程序员看的吗AI又不是人它靠模型生成代码怎么遵守规范但实际操作之后你会发现AI比人更需要一份显式的、可读的、放在项目里的行为规则文档。1.1 AI没有“团队默契”只有上下文和概率人的代码规范执行力来自两个层面一个是明文规范另一个是团队默契。老同事看到你的命名风格能猜到你大概是哪个模块的人知道该不该用单例知道事务应该放在哪一层这些没人写在文档里但大家心照不宣。AI没有这套默契。它只有上下文窗口里的信息以及它被训练出来的概率分布。如果你不告诉它项目用的是什么框架、什么语言版本、什么约定它就会在所有候选写法里挑一个它觉得最“通用”的。而这个最通用的写法往往和你们项目实际采用的方案是两码事。我遇到过一个很典型的情况项目里统一使用函数组件加HooksAI却在某个新页面里自动生成了Class Component还带了一份完整的生命周期方法。不是它不会写函数组件而是它在生成时判断“这个场景可能需要更完整的组件能力”于是选了更高频出现的写法。你在Review时当然能发现问题但你发现一个问题它就可能在下一个文件里再犯一个类似的。没有显式约束AI犯错的概率不会自然收敛。所以给AI定代码规范本质上是在补全它的上下文。它不是要“背规则”而是需要一份项目级的行为说明书让它在每次生成时都能读到“在这个项目里你应该怎么干活”。1.2 规范的收益不只是约束更是减少返工和降低审查成本给AI制定代码规范最直接的好处是减少返工。AI生成一段不符合规范的代码表面上看只是多了一次修复实际上整个链路都被拖慢了先生成再人工发现再来回描述问题再让AI重新改改完了还要重新验证。这个循环如果每天来回几次效率提升就被抵消了大半。我在项目里加了给AI的规范之后一个很直观的变化是PRPull Request里的修改评论数量明显下降了。以前AI提的PR经常会收到一堆关于命名、格式、目录归属的评论这些评论和业务逻辑无关但你又不能不管。有了规范之后AI生成的代码在风格层面基本能对齐项目基线我Review时可以把注意力集中在逻辑正确性、边界条件、异常处理这些真正值得看的地方。另外代码规范对AI还有一个额外作用它可以让AI在生成代码时主动规避一些高风险的“自由发挥”。比如你写清楚“禁止为代码自动添加未使用的依赖”AI就不会在实现一个小工具函数时顺手帮你import一个巨大的工具库。这种线画得越清晰AI的产出就越可控。2. 给AI制定代码规范的核心维度与内容取舍给AI定的规范和给人定的规范有重叠但不等同。人的规范可以写得含蓄、指向性模糊因为人会追问、会类比、会结合上下文理解“尽量”“通常”这类词。AI不会。你写“尽量使用现有工具类”它不知道“现有”是哪些它只会生成一个大概率能用但可能和项目脱节的工具调用。所以给AI的规范必须更具体、更可执行、更偏向“机器可读”。2.1 规范分层把硬性约束和软性建议分开我在项目里把给AI的规范分成了两层一层是“必须遵守”一层是“可以参考”。这个分层不是拍脑袋想的而是实践后发现如果不分AI会把你所有的话都当成同等强度的约束。尤其当规范里出现“建议”“可以”“尽量”这类词时模型可能一会儿遵守一会儿忽略全看上下文里其他提示词的比重。我把“必须遵守”这一类写成了最简短、最直接的祈使句每条不超过一行。比如所有新代码必须使用TypeScript禁止使用any绕过类型检查。文件命名使用kebab-case组件统一以大写开头。所有外部数据访问必须经过service层禁止在组件内直接请求。禁止在代码中写入访问密钥、Token等敏感信息。而“可以参考”这一类我会写得稍微宽松一点比如“可以优先使用项目已有的utils目录中的工具函数”“设计新模块时建议参考现有admin模块的分层方式”。这类内容AI即使不严格遵守影响也可控。分层的核心意义在于让AI在生成时能快速判断哪些是不可触碰的底线哪些只是偏好。如果所有约束都混在一起规则多了之后AI反而会为了满足某条规则而牺牲更重要的人体工程学特性比如为了严格遵守“单文件行数不超过200行”而强行拆文件拆得毫无内聚性。2.2 约束维度表一份可直接参考的规范框架下面这张表是我在项目里沉淀出来的约束维度覆盖了从生成到提交的各个环节。你在设计自己项目的AI规范时可以直接拿这个框架去改去掉不适用的维度就行。约束维度典型约束示例对AI的核心意义技术栈锁定语言版本、框架版本、包管理工具防止AI生成与项目环境不兼容的代码目录与命名模块放置位置、文件命名规则、组件命名规则保证生成代码落到正确位置无需搬文件格式与风格缩进、引号、尾逗号、格式化工具减少Review时大量细节评论依赖管理禁止新增依赖确有需要走确认流程防止AI“顺手”引入大库或错误版本安全红线密钥、鉴权逻辑、用户敏感信息处理防止出现高危安全隐患Git提交规范提交信息格式、分支命名让AI辅助提交的信息能直接融入团队流程行为边界禁止重构无关代码、禁止修改锁文件、禁止清理与本次需求无关的注释控制AI的改动范围降低合并风险这张表不必一开始就填满可以先从当前团队最痛的两三个点开始比如目录归属和命名然后随用随加。给AI的规范最怕一开始就写得像论文模型读不进去人看着也累。2.3 内容取舍规范太细反而会带偏AI给AI写规范的时候还有一个很微妙的平衡不是越细越好。规范太细AI生成时会变得很“紧张”它会花大量概率空间去满足那些格式层面的细枝末节反而忽略了代码逻辑本身的正确性。我有一次在规范里写了很多关于缩进和空行的硬性要求结果AI生成方法的函数体里挤满了空行魔法一行代码一个换行看起来确实“很规范”但阅读体验非常差。后来我把这类格式层的规则全部交给了格式化工具去处理而不是交给AI。AI只需要知道“提交之前执行过格式化不要手工搞排版就行”。格式问题交给工具AI把精力放在架构、命名、逻辑边界这些真正需要脑子的地方。这一条经验我觉得特别值得分享给AI的代码规范要写工具管不了的事而不是重复工具已经在做的事。3. 实操落地让AI真正“读到”并执行规范规范写好了接下来最关键的一步是怎么喂给AI模型。很多人把规范写在Confluence或Wiki里然后指望AI每次自动知道这是不可能的。AI不会自己去翻文档库它只读到当前对话上下文和工具能加载的项目文件。所以规范必须放在AI可以访问的地方并且最好放在项目仓库里随代码走。3.1 规范文件放哪里AGENTS.md、CLAUDE.md与项目内规则现在主流AI编程工具都有“读取项目规则文件”的能力我把这类文件俗称为“AI的项目手册”。常见的文件名包括AGENTS.md比如GitHub Copilot或部分Agent工具会自动读取根目录下的AGENTS.mdCLAUDE.mdClaude Code以及一些兼容工具会读取.cursor/rules目录Cursor支持通过规则文件给不同目录配置指令自定义指令比如一些AI工具的“项目级Prompt”设置。我建议至少维护一个AGENTS.md放在项目根目录同时把更详细的分模块规范放到对应子目录里比如frontend/.rules.md、backend/.rules.md。这样AI在处理不同模块时能读到对应的规范而不是一开始就被全文规范淹没了。这个做法的逻辑很简单AI也有上下文窗口限制。如果整个项目的规范加起来有几千字一股脑塞给它它会“消化不良”尤其当它在处理一个很小的功能修改时大部分规范其实和当前任务无关。放在就近目录里等于给AI做了一个“按需加载”的约束机制效果比根目录放一篇超级长文好很多。3.2 规范文件怎么写短句、给例子、带反例规范的写作风格会显著影响AI的执行效果。同样一句话“命名要有意义”就效果很差因为AI有自己的“意义”标准但如果你写“服务类文件统一以Service结尾禁止将DTO直接命名为Entity同名字段”AI执行的准确度就会明显提高。我现在写规范时基本遵循三个原则短句、正反例、可验证。短句好理解每一条规则能一句话说完就绝不用两句。这不是为了排版美观而是因为模型对冗长解释中的核心诉求容易注意力稀释短句能提高约束指令在生成时的权重。正反例是给AI提供锚点。比如我写“命名规范”时会附上正例: userService, UserProfile, fetchUserList 反例: user_service, UserProfileInfo, getListData这组正反例比任何语言描述都直接。模型看到正例会理解风格倾向看到反例能排除具体错误模式两者一起给效果远超单独描述。可验证的意思是每条规范最好能对应一个检查动作。比如“提交前运行pnpm lint”“单元测试需要包含边界条件用例”。这样AI在完成实现之后能执行检查形成闭环而不只是“自动遵守”一个模糊期望。3.3 再进一步把规范做成可复用的指令包或Skill如果团队里已经有折腾过AI工作流的同学可能听说过“Skill”或者“指令包”这类概念。本质上就是把一组提示词、规范说明、示例代码、检查清单打包成一个独立模块然后在需要时把这份模块注入到AI的上下文中。我给AI制定的这份代码规范也做了一份精简版打包成了团队内部的“代码规范Skill”。这个包不复杂就是一份结构化的Markdown加一个加载说明里面包含规范摘要、常见项目结构、必须遵守的红线、提交前自检清单。做成Skill的好处是团队里的AI工具在启动新任务时可以按需加载不需要每次手动复制粘贴。比如我用的AI编程流程里新建一个功能分支时会自动加载对应的规范包然后要求AI在动手前先回答这个问题“根据代码规范本次新增功能涉及的文件应该放在哪些目录会出现哪些命名冲突”这个“输出计划再写代码”的步骤非常有用它会迫使AI先理解规范重点再进入生成环节而不是一上来就直接写一堆代码。下面是Skill包里的核心摘要片段你可以参考它的写法# 项目代码规范速查AI版 ## 必守红线 - 禁止引入未在package.json中声明的依赖。 - 禁止直接修改public目录下的静态资源路径。 - 禁止在所有Service方法中写入业务事务之外的自定义锁逻辑。 ## 常用目录 - 页面组件 - src/pages/{feature}/ - 公共组件 - src/components/ - API封装 - src/services/ - 工具函数 - src/utils/ ## 命名规则 - 组件文件PascalCase.tsx - hookuseXxx.ts - 工具函数camelCase.ts ## 提交前自检 1. 运行 pnpm lint 是否通过。 2. 新增文件是否在正确目录。 3. 是否只修改与本次需求相关的文件。 4. 是否包含单元测试覆盖边界场景。这段内容的体量不大但你在实际操作中会发现AI照着它干活时很多以前反复强调的问题都少了一大半。它最直接的变化是AI终于不再问你“这个文件放在哪里”也不会在你的代码里随手加一个不在package.json里的依赖了。4. AI不守规矩怎么办问题定位与排查实录就算你规范写得很完整、放的位置也对AI还是会出现不遵守的情况这是概率模型的天性不要幻想“一劳永逸”。真正重要的是当你发现AI生成的代码又跑偏时能快速定位是哪个环节出了问题。本节记录我实际遇到的几类典型问题以及对应的处理流程。4.1 问题一规范写了AI好像没读到排查第一步永远是确认AI是否真的读到了规范文件。AI工具加载规则文件通常有一定条件比如某些工具只在项目根目录有AGENTS.md时自动加载某些工具的规则文件必须放在.rules目录下还有些Agent工具需要在系统提示词里明确“请先读取项目根目录的AGENTS.md”才会去读。我踩了一个坑有一次把规范写好了放在docs/ai-standards.md里结果AI完全无视。后来才意识到我的工具默认只感知根目录的AGENTS.md和当前工作目录下的.rules文件对这个docs路径一无所知。所以以后规范文件要么放到工具能自动读到的位置要么在每次会话的初始Prompt里明确给出路径并让AI先读取再回答。你可以在会话开始时就发一句请先读取AGENTS.md中的开发约定然后再开始处理任务。这一步虽然简单但能强制把规范放进上下文。4.2 问题二规范太多AI上下文被撑爆还有一种情况是规范文件本身太大。某次项目管理规范加得多了根目录AGENTS.md写了三千多字结果AI在处理一个简单的小需求时总是“忘记”给它明确指令的部分生成的代码风格飘忽不定。后来我把根目录的AGENTS.md精简到大约八百字只保留全项目通用红线把详细规范下沉到对应子目录AI的执行稳定性马上提高了。这里有个经验AI工具的上下文窗口是有限的而且会随着对话变长发生早期截断或加权衰减很长的规范放到后面基本等于没放。不要指望AI“通读”一份很长的文档。规范应该按需加载、按模块分发保证在关键决策时刻规范就在最近的上下文里。4.3 问题三新旧规范冲突AI不知所措项目是在过程里持续演进新增给AI的规范可能会和旧代码的写法冲突。如果旧模块都是类组件而新规范要求函数组件AI生成新代码时会出问题。它不是不知道该用哪个而是两个信息都有它会随机摇摆。遇到这种情况我会在规范里专门加一节“迁移策略”明确哪些地方允许旧风格哪些地方必须新风格。比如我会写“新页面统一使用函数组件历史类组件文件不在本次需求范围内时不要重构只有当修改该类组件超过50%逻辑时才允许顺手迁移”。这条规则给AI画出了可操作的范围边界它就不会在改一个小功能时顺手把整个文件重写一遍也不会在新文件里继续沿用旧写法效果非常明显。4.4 常见问题速查表把上面这些整理一下形成一张排查表遇到类似情况直接查表现可能原因解决办法AI完全不遵守规范规范文件没有被工具加载把规范放到AGENTS.md或工具约定目录并在初始Prompt中提示读取规则时灵时不灵规范条目太多或太冗长精简规则分模块、按目录就近放置在旧代码旁边风格突变新旧规范冲突权重争夺在规范中补充迁移策略明确适用边界擅自修改无关代码缺少行为边界约束在规范中加入“只修改本次需求相关文件”等禁止项代码风格正确但逻辑偷懒只关注表层规范增加“提交前运行测试”“覆盖边界条件”这类过程校验重复产生同样的坏味道单一反馈不够将踩过的坏味道写进规范反例形成负反馈这张表的核心逻辑是规范不生效先找加载链路规则反复失效先看规则是不是太模糊AI行为跑偏先查是不是需求边界没写清楚。多数时候问题不在AI“态度”而在你给出的指令结构。5. 让AI代码规范成为项目里的“活文档”给AI制定的代码规范不是一次性动作它是跟着项目一起演化的。AI会变工具会变项目的工程基线和团队审美也会变。这些规范如果只更新一次就不再管几个月后就会和项目实际节奏脱节甚至会从“帮助约束”变成“生成阻力”。5.1 把规范纳入代码评审和复盘流程我建议把给AI的这部分规范直接纳入日常代码评审不是去评审规范本身而是把“AI改动是否符合规范”作为Review的检查项之一。Review时如果发现AI生成代码违反了某条规范除了让AI去修还要顺手思考一下这条规范是否表述清晰是否有反例可加。你把一次Review变成一次规则反馈规范就会越来越贴近真实需求。我在团队里最常用的做法是给AI提的每个修改要求都会加上一句“说明这违反了规范中的哪一条”。一开始只是为了让AI修正得更快后来发现这句话其实是在持续校验规范本身的质量。如果AI经常无法定位到违反的条款那说明条款写得不够可执行需要重写。5.2 用数据看趋势而不是凭感觉给AI定规范有没有用不能靠感觉要看几个基础指标AI辅助的PR平均修改评论数、单次PR变更文件数、规范中禁止项被触发的频率。这些数据不需要专门做系统用Git记录加简单的脚本就能统计。我项目里会定期导出近一个月的PR数据粗筛出“AI参与度高”的PR看其中有多少是因为命名、目录、依赖这类规则性问题被要求改动。如果这个比例下降说明规范在起作用如果上升说明规范出现了疲劳要么是AI读到概率降低了要么是规则已经过时了需要刷新。这个工作很轻量但对规范迭代的方向感很有帮助。不然你很难判断AI代码质量的改善究竟来自规范还是来自大家Review更认真了。5.3 沉淀踩坑经验做成团队的AI协作知识库最后还是要说一句给AI制定代码规范的过程本身就是在积累团队与AI协作的工程经验。最初可能只是几条命名规则后面会慢慢长成一份涉及技术栈、目录、安全红线、依赖管理、提交规范的完整文档。每一次AI踩坑都是往这份知识库里补充经验的好时机。我现在的做法是每次遇到AI在项目里生成“接地气但有毛病”的代码时都会先问自己这个毛病能不能通过一条规则避免掉如果能就把它写进AGENTS.md不能可能就要改工具链或调整工作流程。把这个习惯坚持下来规范会越来越像一份团队级的“AI新人入职手册”而团队成员也会更清楚哪些事可以放心交给AI哪些事必须靠人的判断把住关口。我个人在实际操作中最深的一点体会是给AI定代码规范不是要把它管死恰恰是为了让它放开手脚干活。规则越明确AI能自己处理的事情就越多我Review时也就越轻松。如果你也打算在项目里做同样的事建议不要一开始就追求大而全先挑当前最头疼的两三个问题写清楚、放到位、跑一段看看再逐步迭代。这个过程本身就是在慢慢摸索一套适合你自己团队的AI协作方式的边界。