我们团队最近做了一件看起来有点“反直觉”的事在项目仓库里新增了一份专门写给AI看的代码规范。你没听错不是给新人看的开发文档是给Copilot、Cursor、通义灵码这些AI编程助手看的“行为准则”。这事我踩了不少坑今天把完整的思路和落地方案整理出来希望对同样在重度使用AI编程的团队有帮助。先交代一下背景。我们项目组从去年开始大规模引入AI编程工具日常开发里大概有40%的代码是AI生成的。一开始大家挺爽但不到两个月问题就出来了AI生成的代码风格飘忽不定、命名习惯一天一个样、有时候还会搞出一些看着没问题但根本不符合项目架构的实现。代码评审变成了“AI代码纠错大会”reviewer怨声载道。我意识到问题不在AI本身而在于我们没有告诉AI“入乡随俗”的规则。于是我花了两周时间在项目里新增了一份专门给AI制定的代码规范文件效果出奇地好。1.1 为什么AI写的代码会“水土不服”要解决问题得先理解问题是怎么来的。AI编程工具的本质是“根据上下文预测下一段最可能的代码”。它参考的是GitHub上数以亿计的开源项目这些项目用了五花八门的风格有的用分号有的不用有的喜欢长命名有的偏好短命名有的强制函数不超过10行有的一个函数写300行。最关键的是AI在生成代码时默认会往“统计上最可能”的方向走而不是“你项目里最合适”的方向。这就像一个新来的同事见多识广但不懂你的项目规矩。你如果只丢给他一个需求文档他写出来的东西大概率是“通用风格”而不是“项目风格”。这时候一份清晰的、机器可读的代码规范就是给AI的“入职手册”。有意思的是大模型对自然语言指令的理解能力远超我们想象。只要规范写得足够具体、无歧义AI是真的会“照着做”的。我把这个发现跟几个同行聊过他们也反馈同样一个AI编程工具在配置了项目级规范之后生成代码的一次通过率能提升30%到50%。1.2 传统代码规范为什么对AI“不友好”我们项目里其实早就有代码规范文档用的是ESLint配置加一份Word文档。但实践下来发现这份规范对AI基本没什么约束力。我琢磨了一下问题出在几个地方。第一传统的规范工具链ESLint、Prettier等是在代码写完之后做检查的属于“事后校验”。AI生成代码的时候它并不知道有这些规则生成完了再让ESLint去格式化虽然风格能统一但架构层面的问题比如该用策略模式却写了一大堆if-else是Lint工具管不了的。第二人看的规范文档总是充满了“原则上”“尽量”“建议”这类模糊词汇。比如“优先使用组合而非继承”这句话人懂但AI会把它理解成概率问题有时候组合有时候继承。AI需要的是确定性规则什么场景用什么方案没有例外。第三规范和实际代码之间没有建立关联。AI一次只能看有限的上下文一般在几万token内它不会主动去翻你的规范文档除非你把它塞到它能看到的地方。所以我们需要一份“AI原生”的代码规范它不是给Lint工具用的配置文件也不是纯文字说明文档而是一份经过结构化设计、能够被AI理解和遵循的行为准则。2.1 把规范翻译成“AI指令”我做的第一件事是重新梳理了一份规范起名叫AGENTS.md。这个命名借鉴了GitHub Copilot识别的约定放在仓库根目录很多主流AI编程工具会自动读取它。内容上用中文撰写因为我们的AI工具配置的就是中文交互用中文写规则AI理解的准确率更高。核心的写法是给定场景给定约束给定输出。不再是“应该怎样”的建议句式而是“遇到X情况必须Y”的命令句式。比如传统规范可能写“请合理处理异常情况”我改成当编写函数时所有可能抛错的I/O操作必须用try-catch包裹。catch块中不得为空必须记录日志并返回统一的错误响应结构。我还加入了大量“禁忌清单”。AI很擅长遵循“不要做哪些事”的指令。比如禁止在Component内部直接定义函数并传递给子组件除非使用useCallback包裹。禁止修改已提交的公共接口方法签名。这类“负面清单”比“正面要求”更能有效限制AI的行为边界因为AI的训练数据里包含大量“错误示范”你必须明确告诉它哪些是项目中的禁忌。2.2 区分“全局规范”和“模块规范”代码规范不是一份文件打天下。不同模块、不同技术栈的代码风格差异很大AI如果只看到一份全局规范在处理具体任务时还是容易跑偏。我把规范分成了三个层级全局规范AGENTS.md适用于整个项目的通用规则包括命名风格、Git提交规范、代码结构组织原则、注释语言等。模块规范如frontend/AGENTS.md、backend/AGENTS.md每个技术栈一个文件比如前端强制使用TypeScript严格模式、禁止使用any、组件文件必须默认导出后端则规定分层结构、事务边界等。任务指令Prompt Templates当你在IDE里让AI做事时你给的提示词本身就包含规范。我们把这些指令模板沉淀下来做成团队共享的能力。关于第三点多说一句。我见过不少团队在“调教”AI时觉得难其实问题往往就在于指令太泛。我们沉淀了一套任务指令模板比如“帮我重构这个函数要求保持外部行为不变拆分后每个函数不超过15行并补充单元测试”。这类模板写多了AI的表现会稳定很多。2.3 规范的内容结构设计具体来说我给AI制定的这份规范分成七个部分每一部分都有明确的用意项目技术栈清单用列表列出项目使用的语言、框架、核心库和版本。AI知道“底牌”后不会擅自引入你项目里没有的新依赖也不会用错误版本的API。目录结构与职责边界用树状图展示项目目录并注释每个目录的职责。AI看到src/modules/user/就知道业务逻辑放这里不会往src/utils/里塞业务代码。命名与风格强约束给AI指定变量、函数、类、组件的命名风格。我明确写死了前缀规则例如use开头的Hook、is/has开头的布尔变量等。编码模式规定这是最核心的部分。列出项目中必须使用的设计模式、禁止使用的反模式。比如后端必须用依赖注入禁止在Controller里写业务逻辑等。错误处理与日志规范明确统一的日志格式、错误码命名规则、异常处理策略。测试要求规定核心逻辑必须附带单元测试测试文件命名规则、断言风格等。Git提交约定AI有时候会自动生成提交信息需要规范提交信息的格式比如必须遵循Conventional Commits类型限定为feat/fix/refactor/docs/test等。3.1 让AI真正“读到”规范规范写好了接下来的问题是怎么确保AI在生成代码的时候确实“看到”了这些规则我试过几种方式踩过一些坑最后形成了三层保障机制。第一层是工具级别。像GitHub Copilot这样深度集成在IDE里的工具会默认读取仓库根目录下的AGENTS.md把它作为项目上下文的一部分。Cursor的规则配置里还支持添加全局规则和项目规则你可以把规范文件明确绑定到项目。这一层可以把90%的“AI自然生成”行为纳入规范。第二层是Prompt级别。当使用Chat模式的AI工具时第一句指令就把规范关键点加进去。我写了一个统一的兜底提示词你是本项目的资深开发者。在回答所有问题前请先阅读仓库根目录的AGENTS.md和各模块内的AGENTS.md文件严格遵守其中的代码规范。如果规范与你的惯常做法冲突以规范为准。这个提示词成本极低但效果显著能让AI在处理复杂重构或跨文件修改时保持方向感。第三层是反馈闭环。在代码评审中凡是AI生成的代码违反了规范我会把具体的违规情况、原因、正确写法全部回写进规范文件。比如我发现AI经常把常量定义在组件函数内部导致重复创建我就在规范里加上一条禁止在React组件内部使用const定义不变的对象或数组字面量。此类定义必须提升到模块顶层或使用useMemo。持续迭代规范本身让AI越用越“懂”你的项目。这里我强烈建议把规范文件纳入版本管理像维护代码一样维护规范这样每个规范的修改都带有历史上下文团队review起来也方便。3.2 规范文件的具体写法示例我把我们的全局规范文件AGENTS.md的核心段落摘出来给大家做个参考。注意我使用的是规则清单方式减少自由发挥空间。# 项目开发规范AI Agent 必读 ## 技术栈 - 语言TypeScript严格模式 - 框架React 18 Node.js 20 - 状态管理Zustand - 样式方案CSS Modules - HTTP请求Axios统一封装在src/api/目录下 ## 目录结构约束 - 禁止在src/utils/index.ts中放业务逻辑 - 页面组件统一存放于src/pages/{pageName}/index.tsx - 所有API请求必须经过src/api/modules/{domain}.ts封装禁止在组件内直接调用axios ## 命名规范 - 组件文件名PascalCase.tsx - 自定义Hookuse开头useCamelCase - 常量UPPER_SNAKE_CASE - 布尔变量is/has/should/open等前缀 ## 编码规则 - 禁止使用any未知类型使用unknown并完成类型收窄 - 函数长度不超过30行超过必须说明理由 - 禁止在useEffect中直接使用async函数须使用IIFE包裹 - 禁止在React组件内定义重复的普通函数优先提升到模块作用域 ## 错误处理 - 所有外部请求必须try-catchcatch块内使用统一错误提示组件 - 错误日志必须包含时间戳、错误码、请求URL、失败原因 ## 测试要求 - 重要工具函数必须附带单元测试 - 测试文件与被测文件同目录命名为*.test.ts你可能会说这也不算特别很多规范文档都这么写。但关键在于我在文件中用了很多“禁止”句式而且规定得很具体、可判否。大模型看到“禁止使用any”会比“建议使用unknown”执行得更彻底。你可以把AI想象成一个记忆力极好但缺乏常识的新人你定得越细他做得越好。3.3 配套的评审与自动化检查机制规范文件本身是“软约束”它能让AI大概率生成合规代码但总有“不听话”的时候。为了保证底线我加了自动化检查兜底在CI管道里做了三道关eslint --fix和prettier --write处理代码格式层的规范。自定义脚本检查目录结构和命名比如遍历文件命名检查组件是否放对了目录API是否走了封装层用了正则和文件系统扫描。AI代码占比标记这不是强制否决但在PR描述里会标注“此PR包含AI生成代码”提醒reviewer重点看AI产出部分。这三道关卡并不能替代代码评审但它们把AI生成代码的风险从“可能完全跑偏”降到了“只有业务逻辑需要人工把关”。实际运行了半年我们的平均评审时长降低了大概40%。我在这里必须多说一句自动化检查只能兜住“硬规范”也就是那些可以被程序判定的规则。架构设计、业务逻辑、边界条件的处理这类“软规范”还是得靠AI理解力和你的Prompt设计来保证。4.1 AI“无视”规范怎么办这是大家最常问的问题我明明把规范写进AGENTS.md了AI还是违反。别急着骂AI先检查几个方面。第一AI工具是否真的读取了这个文件。部分IDE的AI插件需要额外配置才能读取根目录的AGENTS.md。像Cursor比较友好自动加载但一些JetBrains系插件可能不会读你需要把规范内容手动粘贴进上下文或使用插件配置。第二上下文窗口问题。AI在处理超长对话时早期输入的内容有可能被截断或“遗忘”。这就是为什么我把规范文件的优先级设计成“任务指令 模块规范 全局规范”最关键的限制条件需要在即时Prompt里重复一遍。第三规范与AI的默认行为冲突太大。比如AI的训练数据里90%的代码都用let而非const你规范要求“尽量用const”但它还是会本能地生成let。怎么办两条路一是把规范改成“禁止使用let除非变量会被重新赋值”让AI的判断逻辑更明确二是把类似规则写进代码评审的检查清单在人工环节兜底。我实践中发现绝大多数问题出在“规范写得不够死”上。比如你写“尽量使用函数式组件”AI就会偶尔生成类组件。改成“统一使用函数式组件禁止在新增代码中使用类组件”AI就再也没犯过。4.2 规范文件的“副作用”管理给AI定规范就像给团队定流程一定会有副作用这里提醒三个容易踩的坑。第一个坑是规范膨胀。第一版写了20条规则用了两周后膨胀到80条。副作用是AI在有限的上下文里抓不住重点反而可能忽略最核心的规则。我的经验是定期做“减法”把不痛不痒的规则删掉只保留那些违反后会造成实质性问题的规范。一般来说全局规范文件控制在50行以内效果最好。第二个坑是过度限制导致AI能力退化。AI编程工具最大的价值在于它的创造力和跳跃性思维。如果你把每条路都堵死AI就变成了一个“翻译机”遇到问题只会按模板输出反而失去了使用AI的意义。我对此的策略是规范只管“底线问题”开放区域留给AI自由发挥。第三个坑是团队争论浪费精力。不是每个人都认同某条规则特别是关于代码风格和架构决策的部分。我的建议是先小范围实验一个月用数据说话再决定是否作为团队规范。我们最初的node版本规范就折腾了两轮才最终定下来。4.3 针对不同AI工具的经验差异市面上常见的AI编程工具对规范文件的读取机制还是有差异的我大致总结一下实测经验。GitHub Copilot在IDE里对AGENTS.md的读取相对保守它对当前打开文件的上下文更敏感。建议你在实际工作时把相关规范片段直接写在Prompt中或者加在文件头部注释里。我们团队的公共代码文件顶部就有一段注释块标注了本文件适用的特殊规范。Cursor对项目规则的支持最好可以直接配置项目级RulesAI在生成时基本都能读到。它的Agent模式可以自动多文件修改下规范执行也比较听话适合做跨文件重构。通义灵码对中文指令的理解比较自然我们测试下来对规范的理解能力不错但注意要把规范放在对话的开头部分不要藏在很深的子目录里。Codex CLI / Claude Code这类终端型Agent强在可以读取任意文件所以只要规范文件在仓库里它就会自动检索。只要文件路径写清楚问题不大。需要提醒的是AI工具更新频率很高以上经验可能在半年后就变了。我的习惯是每隔一段时间就做一次小测试故意让AI写一段违反核心规范的代码看它是否遵守以此验证当前工具的行为特性。我还有一个比较实用的技巧把常见规范分歧写成一个Test Case文件放在代码库里用写测试的思维来验证AI是否理解规范。比如我写了一个avoid-any.ts里面故意写了几个使用any的反例然后在注释里问AI“这段代码违反了哪条规范应该怎么改”实测下来用这种“考考AI”的方式去训练它比单纯写规范文档更有效。5.1 规范与现有Lint工具的配合有人可能会问为什么有了ESLint和Prettier还要给AI写规范这里我花点篇幅聊聊两者的配合关系。传统的Lint工具是“确定性”的规则清晰明确代码必须符合但它的执行时机是在代码写完以后所以叫“事后约束”。AI的代码规范是“语义化”的它约束的是AI生成代码过程中对项目架构、模式选择的判断是“事中指导”。两者不是替代关系而是前后衔接的关系。举个实际例子。ESLint能检查出“变量定义了但未使用”但它检查不出“这个函数放在utils里违反了业务分层”。后者需要AI在写第一行代码的时候就有概念。反过来AI再聪明也不可能记住900条ESLint规则它只关注规范文件中摘录的高优先级约束。所以ESLint规则要全、要细AI规范要精、要准。在配合上我有两个小建议一是ESLint规则的错误提示要保持和AI规范文件用词一致。这样当开发者去修Lint错误时AI也能从修复记录中学到这个项目的偏好。二是每当AI规范新增一条核心规则时尽量在ESLint配置里对应增加一条自动化检查规则。这样AI软约束加上Lint硬检查双重保障能最大程度降低“漏网之鱼”。5.2 规范迭代把AI当成团队新人来带这次实践给我最大的感受是给AI制定代码规范的本质是建立一种“持续沟通”的机制。AI不是一次性学会规范的它会根据你的反馈不断调整行为前提是你得持续“喂”给它正确信息。我现在的迭代节奏是每两周评审一次规范文件每次只改3到5个“点”改完立刻让AI试跑新规则观察效果。这个节奏下规范的演进不会太快导致混乱也不会太慢导致问题反复发生。另外我建议规范文件建设初期一定要让全团队参与Review。因为AI写的代码是团队共有的资产规范如果只反映某一个人的偏好其他人使用AI时会觉得别扭。我们团队的规范文件里React组件写法的规则就是前后端同学一起敲定的避免AI生成“前端看觉得合理、后端看不懂”的代码。最后还有一个小心得是关于“AI规范”和“AI能力”的关系。规范不是限制AI的天花板反而是提升AI产出效率的助推器。有了明确的规范约束AI生成的代码更少被驳回开发者花在“纠错”和“返工”上的时间大幅减少整体的开发幸福感其实是在上升的。我个人在这里面的体会是AI编程工具就像一把锋利的刀规范就是刀鞘。没有刀鞘的刀容易伤人但有了刀鞘的刀才能安全地发挥它最大的作用。如果你也在团队里推AI编程但总觉得效果不稳定不妨先停下来想想你有没有给AI一本足够清晰的“项目入乡随俗指南”如果你还没有这份规范值得你花两周时间认真写一版。