给AI编程工具立规矩：一份面向AI的代码规范实践-北京尧图网络

如果你最近一直在用AI编程工具写代码可能已经遇到过一个很熟悉的烦恼AI给出的代码能跑、功能也对但放进项目仓库里总有一种“不对劲”的感觉。它可能把一个已经封装好的请求方法扔在一边自己又包了一层HTTP可能因为一个小需求悄悄引入了一个几MB的第三方依赖更常见的是它把团队约定俗成的写法完全无视生成一版“语法正确但风格违和”的代码。这种感受很像团队里来了一个能力很强、但完全不了解项目规则的新人你需要盯着它一点点把规矩补上。我最近就在项目里做了一件事新增了一份专门给AI制定的代码规范把团队的隐形约定、红线禁区、基础架构约束全部显式地写进规则文件并接入到日常使用的AI编程工具里。这篇文章就聊聊我为什么这么做、规范里到底写了什么、以及落地过程中踩过的坑。1. 为什么非要单独给AI定一套代码规范1.1 人类的规范和AI能执行的规范是两回事传统的代码规范通常长这样“命名要有意义”“函数要符合单一职责”“接口要做好参数校验”。这些话人看得懂因为人会结合具体业务场景、项目背景去理解知道什么时候该变通。但AI没有这种“项目记忆”每次对话都是从一个全新的上下文开始它能看到的只是当前打开的文件、最近的对话、以及被明确喂给它的信息。如果你不对它做约束它就会按照训练数据里的“通用最佳实践”去写代码而不是按照你们项目的“自定义最佳实践”去写。所以给AI制定规范本质上不是把人类规范换一个文档格式而是要完成一次“知识显性化”把团队里那些写在代码评审记录里、存在老同事脑子里的隐性约定变成AI能够逐条读取并执行的显性规则。我真正动手之后才发现这件事比想象中复杂但也比想象中有价值。1.2 没立规矩之前我见过三次翻车第一次翻车发生在给一个列表页加筛选功能的时候。项目里明明有封装好的 request 方法和列表接口通用的 usePagination 组合式函数AI 完全没有参考旧代码自己写了个 axios 调用、自己管理分页状态、自己做了 loading 展示。功能是好的但代码风格和项目里其他十几个列表页完全不同维护成本一下子就上去了。第二次翻车更典型。业务需要一个数组按某个字段排序AI 顺手在 package.json 里加了一个 lodash 依赖。我们项目之前为了控制体积特意把所有需要 lodash 的用法收拢到了 utils 里这个约定对人是隐性的但对AI来说根本不存在。它按“推荐实践”选择了最省事的方案结果直接踩了项目的红线。第三次翻车让我决定彻底落地规范AI 在修复一个按钮样式问题时连续改了三个不相关的文件包括公共主题配置和全局 CSS 变量导致线上样式整体变化。这个问题的根子不在AI笨而是它根本分不清“这个任务允许改动的范围”到底在哪。这三件事结合起来结论非常清晰AI是一个没有项目常识的超级执行者你必须在它动手之前把所有“常识”喂给它的上下文。1.3 给AI的规范本质是一种约束性的上下文工程把规范写进规则文件和写一段优秀的提示词底层逻辑是一样的降低模型输出空间里的不确定性。人写代码遇到不熟悉的地方会问同事AI不会主动问它只会尽可能生成“看起来合理”的内容。规范的存在就是把“看起来合理”强行拉回“项目里真实存在”的轨道上来。想明白这一点之后我的思路就从“写一份代码规范文档”变成了“做一套AI编码约束系统”。它至少要覆盖几个维度技术栈边界、现有模式的参考入口、文件修改范围、质量与安全底线、输出前的自检流程。下面我会一个个拆开讲。2. 给AI的代码规范应该包含哪些模块2.1 技术栈与依赖红线先锁死AI的“工具箱”AI在生成代码时有一个惯性倾向于使用训练数据里出现频率最高的库而不是你们项目实际在用的库。所以规范里的第一优先级就是锁定技术栈和依赖。我在规范里放了明确的白名单和黑名单例如约束类别规则示例原因框架版本项目基于 Vue 3 TypeScript 5禁止输出 Vue 2 语法防止新旧语法混用日期处理统一使用 dayjs禁止新增 momentmoment 已停止维护且体积大依赖白名单除项目已有依赖外禁止自行引入 npm 包控制包体积与安全风险样式方案必须使用项目的 SCSS 变量与 mixin保证主题一致这里的表达不能太含糊。比如“尽量减少新依赖”就不行AI无法判断“减少”到什么程度要用“禁止新增”“必须使用”这样无歧义的词。刚开始大家的规范普遍太软AI执行起来就会松弛后来我把所有规则全部改成祈使句效果立刻提升了。2.2 模式优先让AI先找到“同类代码”再动手AI犯懒的时候生成代码的逻辑是“听起来合理就行”而不是“项目里同类代码怎么写的”。要纠正这种倾向最好的办法是把“参考现有实现”写进规范并且给出具体的路径。我在规范里专门加了一条规定动手之前先搜索项目中与当前需求最相似的现有实现如果已有工具函数、组合式函数、公共组件必须优先复用禁止重复实现。新增页面或组件时先阅读同目录或相邻目录下已有的两到三个文件保持结构、命名、注释风格一致。光这样还不够我还在规范附录里列了一个“常用工具函数清单”把 formatDate、request、usePagination、fileDownload 这些高频工具的路径和用法写清楚。AI每次读规则文件时都会看到这张清单重复造轮子的概率大幅下降。实测下来这条规则对“AI写出来的代码像不像团队自己人写的”影响最大。2.3 边界约束明确“AI不能碰哪些文件”这一条是吸取第三次翻车教训之后补上的。AI天然没有“改动范围”的概念给它一个任务它有时会顺手把看起来相关的公共文件改掉。所以规范里必须画一条清晰的安全边界。我在项目根目录维护了一个“禁止AI修改”的名单包括全局配置文件package.json新增依赖须由人工完成、vite.config.、tsconfig.json公共样式入口styles/global.scss、theme 相关变量文件基础设施代码request封装、路由守卫、权限校验模块类型定义全局 .d.ts 文件同时规定如果任务确实涉及这些文件AI必须在回复里明确说明“需要修改公共文件XXX原因是什么”由人来最终决定。这条规则听起来简单实际作用非常大相当于给AI加了一道“先请示再动工”的流程。2.4 错误处理、日志与安全基线兜住质量底线AI写代码还容易在两个地方出问题一是错误处理太粗暴二是日志信息约等于没有。规范里我加了几条最低要求禁止写空的 catch 块捕获异常后必须给出至少一条可读的日志或向上抛出。日志必须包含业务上下文例如操作对象ID、失败原因禁止只输出“error occurred”。涉及用户敏感信息、Token、手机号等字段时禁止直接输出到日志或接口报错信息。涉及鉴权、支付、用户数据导出的功能必须使用团队已有统一实现禁止自己另写一套。这里特别要提一个现象AI对“安全基线”的理解通常停留在“不能有SQL注入”这种通用层面而项目里的自定义安全约定比如“管理端接口必须走某个鉴权中间件”它完全意识不到。不把这类约定写进规范AI就一定会漏。2.5 输出自检让AI交代码前先过一遍“自问清单”最后规范里还设计了一段“提交前必查”清单要求AI在生成完整代码后逐条自检是否引入了新的第三方依赖如果有是否已经过人工确认是否复用了现有的工具函数或组件而不是重复实现是否修改了边界文件中不允许修改的内容错误处理是否完整有没有未捕获的异常路径新增代码是否与现有代码风格一致命名、缩进、注释语言一开始我以为AI不会认真执行这种自检实测下来发现把“自检清单”放在规范文件的末尾与代码生成指令放在同一个上下文中AI确实会像过流程一样逐条检查很多低级错误能在生成阶段就被拦下来。3. 实操过程把规范真正落进工具链3.1 规范文档怎么设计AI才“看得进”写规范这件事最大的误区是把它写成“给人看的文档”。给AI看的规范要满足三个特点短、具体、可执行。先说“短”。AI的上下文窗口是有限的规则文件如果超过几千字越靠后的内容越容易被忽略。我给自己的要求是强制规则控制在二三十条以内每条一句话说清附录里的工具清单可以长一点但核心规则必须精简。再说“具体”。不能写“注意复用”要写“项目已有 common/request.ts所有HTTP请求必须通过它发出”不能写“注意日志规范”要写“禁止输出只有error字符串的日志”。最后是“可执行”。每条规则都应该能让AI判断出“我到底有没有违反”。如果一条规范写出来AI看完了还是一脸懵那它基本等于没写。我当时落地的规则文件开头是这么写的# AI 编码强制规则MUST 你是本项目的一名开发工程师。在生成、修改代码前必须先阅读以下规则并严格遵守。如果规则与你的通用知识冲突以本文件为准。 1. 技术栈项目是 Vue 3 TypeScript 5。禁止生成 Vue 2 Options API 风格代码。 2. 复用优先动手前先搜索 utils/、hooks/、components/ 下是否有现成实现有则必须复用禁止重复实现。 3. 依赖红线禁止自行在 package.json 中新增第三方依赖。确需新增时在回复中明确说明原因由人类确认后手动添加。 4. 文件边界禁止修改 package.json、vite.config.*、styles/global.scss、types/ 下的全局类型文件。如任务确实需要先输出修改方案不直接修改。 5. 错误处理禁止空 catch。所有失败路径必须有可读日志或向上抛错。 6. 敏感信息禁止将 token、手机号、身份证号等敏感字段写入日志或错误信息。 7. 风格一致新增组件/页面时先阅读同目录下 2-3 个现有文件保持命名和结构一致。 8. 完成前自检输出前逐条对照以上规则自动修正不符合项。这一段规则写好后我再根据具体项目情况补充附录。附录里放了工具函数清单、目录结构说明、常用组件清单帮助AI在具体任务里找到参照物。3.2 三种方式把规范注入AI工具规范文档写得再好不放进AI实际读取的上下文里也等于零。目前我在项目里尝试了三种方式读者可以根据自己用的工具选一种或叠加使用。第一种是Cursor的规则文件。在项目根目录建一个.cursor/rules/目录把规范写进ai-coding-rules.mdcCursor在读取代码库时会把规则文件的内容作为上下文加载。规则文件顶部可以用 frontmatter 声明适用范围比如只对 TS/TSX/Vue 文件生效。这种方式体验最好规则是项目级的团队成员clone下来就能用。第二种是GitHub Copilot。需要在仓库根目录放一个.github/copilot-instructions.mdCopilot会把这个文件作为代码补全和对话时的项目级指令。语法上直接用Markdown就可以核心规则和上面类似。配置简单适合团队统一维护缺点是它主要影响补全和简单对话对复杂任务的控制力不如Cursor那么强。第三种是自定义Agent或AI编程插件比如 Cline、Continue、或者团队自研的Agent。这类工具通常在设置里有一个系统提示词或规则文件路径我可以把同样的规范内容粘贴进去做全局指令也可以指定读取项目中的AGENTS.md之类的文件。如果你在用开源工具把规范直接放进仓库根目录的AGENTS.md很多主流Agent框架会自动读取算是一个跨工具的通用做法。3.3 验证AI有没有遵守评审、脚本、抽查三件套规则写进工具不代表AI就会百分百执行。我见过太多人以为配好文件就完事了结果PR里依然充满违规代码。所以验证环节一定要跟上。我的做法是三层第一层是代码评审。每次AI生成的PR我都会重点看 diff 里是否有“新引入依赖”“重写现有工具函数”“修改边界文件”这三类苗头。只要出现一次就把对应的真实案例补充到规范里让规则更有针对性。第二层是自动化检查。类似“禁止新增依赖”这种硬性规则光靠人工看不过来我写了一个非常简单的 CI 脚本比对 package.json 的 diff如果发现依赖列表有变化就自动标记要求人类确认后才能合并。另外用 ESLint 和 TypeScript 严格模式把基础质量问题兜住AI再怎么写也绕不过编译和静态检查。# 检查 package.json 是否在 PR 中被修改用于人工确认依赖变更 if git diff HEAD~1 --name-only | grep -q package.json; then echo package.json 被修改需要人工确认是否新增依赖 exit 1 fi第三层是抽查统计。我每周随机抽两到三个AI完成的PR对照规范清单逐项打分把违规率记下来。说实话刚开始那几周违规率非常高有三分之一的PR至少有1条违规。等规范迭代到第二三周明显下降到十分之一以内。这个过程没法一下子到位但方向是对的。4. 实战中遇到的典型问题与排查技巧4.1 规则太长AI容易“读完就忘”项目里的规则越加越多之后我很快遇到了新问题AI偶尔会把前面的规则忽略掉尤其是在处理复杂任务时上下文被大量代码块占满规则文件里的内容会退到一个比较“弱”的位置。排查后我做了两件事。第一把规则拆成“核心强制规则”和“附录参考信息”两部分核心规则保持在20条以内附录里的内容不强制每次加载。第二在用户任务里补充一句“请先阅读项目根目录 AGENTS.md 中的AI编码规则再开始分析”相当于给AI一个明确的检索指令让它在当前会话里主动读取规则文件。这个办法对长会话的帮助很大尤其是当任务比较复杂、AI需要多轮对话时主动提醒它回读规则能显著减少中途跑偏的情况。4.2 AI经常“表面遵守规则细节照旧放飞”有一段时间AI确实不再新增依赖了但它在 dayjs 的用法上还是写得很奇怪代码风格跟项目原有代码一眼就能看出差别。问题出在规范的颗粒度上我只写了“用dayjs”但没有告诉它项目里真正流行的用法是什么。后来我在规范附录里补充了大量“正例对照”。// 反例不推荐 const day dayjs(date).format(YYYY-MM-DD); // 正例项目统一写法 const day formatDate(date, YYYY-MM-DD);这种“反例加正例”的写法比单纯写“使用统一日期工具”有效得多。AI在生成时会把正例作为模板来模仿而不是把抽象规则“翻译”成自己的理解。现在我把“反例加正例”作为规范写作的固定格式效果非常明显尤其是对风格一致性要求高的项目这招基本是必备的。4.3 规则之间存在冲突AI会“卡住”或“选错方向”规范写多了以后会出现互相打架的情况。最典型的是“禁止引入新依赖”和“优先使用成熟的第三方库”这两条规则同时存在某天需求是处理一个PDF导出项目里没有现成库AI就不知道该怎么办了最后随便选了个方向。后来我在规范里加了优先级说明当规则冲突时以“不新增依赖”为最高优先级如果确有必要必须走“先请示人工”流程。这个改动很小但解决了AI决策路径不稳定的问题。现在规范里每条规则旁都标了优先级强制规则大于参考规则AI在执行时有了明确的取舍依据。建议大家在写规范的时候一定要预判规则之间可能的冲突场景提前把优先级写清楚否则AI很容易在边界情况里做出让人意外的决定。4.4 规范多久更新一次比较好我给团队定的节奏是每周代码评审结束后花半小时更新一次规范。更新的时候只做两类操作把AI常犯的新错误写成反例补进去把已经不再符合现状的旧规则删掉。尽量避免大范围重写因为规范变动太大会降低AI执行的稳定性它需要一定的时间去适应新版本。还没写完的另一个心得是规范本身也要纳入版本管理最好由负责AI工具落地的人统一维护并记录变更原因。团队里其他人如果对规则有意见直接在合并请求里讨论不要在群里口头说一句就完事说完了规则没有进文件下一次AI照样踩坑。规范从“第一次写完”到“真正稳定可用”中间至少要经过两三周的迭代这个迭代过程本身就是团队对项目“隐性知识”的一次大梳理。最后再分享一点个人经验。给AI制定代码规范这件事真正难的不是写文档、也不是配置工具而是把团队多年的隐性经验“翻译”成AI听得懂、能执行的话。我前前后后迭代了差不多一个季度规则文件越来越长但AI产出的代码却越来越像团队自己人写的那种不断纠正、不断收敛的过程是很有成就感的。如果你们团队刚开始做这件事我的建议是别想着一步到位。先挑最痛的三五条规则写进文件跑起来再根据PR和评审里的真实案例慢慢补。规范不是束缚AI的枷锁它是让AI真正融入项目的一本“团队手册”。

给AI编程工具立规矩：一份面向AI的代码规范实践

相关推荐

【javaweb】day3

缓存预热（Cache Warm-up）的解决方案与对比

【Matlab】城市应急疏散仿真与评估实现

更多资讯

DeFi技术解析：智能合约与金融乐高的工程实践

基于GAN的复杂背景文字修复：从掩码到对抗训练实战

【三个月 AI Agent 实战学习】Day 6：结构化输出（JSON）—— 让模型与代码无缝协作

YOLOv5+ArcFace：从人脸检测到身份识别的完整改进实践

Flutter与HarmonyOS 6.0构建旅行记录应用类型选择器

毕业设计之微信小程序酒店预约管理系统

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？