企业官网建设流程全解析

1. 为什么我急着给AI定规矩

先说个真实场景。项目上线前的一个晚上，我在review新功能的PR，越看越不对劲：同一个交互组件，这一版用的是fetchUserList，上一版叫getUserData；接口封装一会儿走service/order.ts，一会儿又在页面里直接axios.get；更离谱的是，有个AI生成的工具函数没做空值处理，线上差点崩了。队友一脸无辜地说：“AI写的，我让它改，它每次都按自己的风格来。”

这个场景你应该不陌生。现在团队里用AI编程已经成了常态，AI能快速产出大量可运行代码，但问题是，AI对项目已有的约定一无所知，它只会“写代码”，不会“按项目的规矩写代码”。于是代码库像被好几个人用不同笔迹写满了批注，看着能跑，维护起来想哭。

我当时的判断是：问题不在AI，在我——我没有给AI一份“工作手册”。

所谓给AI制定的代码规范，本质上是把团队沉淀下来的工程经验——命名习惯、目录约定、错误处理策略、提交规范——整理成一份AI能读懂、能严格执行的指令集。它不是给人看的规范文档，而是给AI Agent的“岗位说明书”。有了它，AI生成的代码才能从“能用”变成“好用”，从“个人风格”变成“团队风格”。

这篇文章就聊聊我是怎么在项目里落地这份规范的：它长什么样、怎么写的、怎么让AI听话、以及踩过的坑。适合正在被AI生成代码质量困扰的开发者、技术负责人，也适合前端、后端、全栈工程师做参考。

2. 给AI立规矩的第一步：先想清楚要约束什么

2.1 AI代码规范和人用规范的核心差异

人和AI读规范的方式完全不同。人有上下文感知能力，看完规范脑子里会留个印象，写的时候大概率能遵守；AI不同，它每次生成代码都像失忆了一次，只有明确、可操作、放在上下文里的规则才有效果。

所以给AI制定的代码规范，不能是“请保持代码整洁”这种模糊表述，而必须是“所有API请求必须经过src/services/目录下对应文件封装，禁止在组件内直接调用axios”这样的硬性约束。我踩过最典型的坑就是规范写得像散文，AI看完等于没看，输出还是我行我素。

另外，人用规范是“偶尔查”，AI用规范是“每次都要加载”。这意味着规范文档不能太长，不能有废话，每个条目都要直击要害。我在实践中发现，超过80条的规范AI就开始选择性忽略，前20条的遵守率最高，越往后越低。所以规范的顺序也很讲究，最重要的、必须100%执行的内容要放在最前面。

2.2 先盘点项目的痛点，再决定规范条目

我不建议一上来就照搬网上的“AI编程规范模板”，而是先问自己三个问题：当前AI生成的代码里，最影响我的是什么？最影响团队协作的是什么？最影响项目稳定的是什么？

我在这个项目里的痛点排序是这样的：

第一是命名和目录混乱。AI经常为同一个概念生成不同命名，比如订单模块，一会儿OrderInfo，一会儿OrderDetail，一会儿orderData，导致代码搜索和review都很难受。

第二是技术栈漂移。项目用的UI组件库是Ant Design，AI有时候会引入MUI的组件；状态管理统一用Zustand，AI偶尔会写Redux的写法。

第三是安全隐患。AI生成代码时经常忽略输入校验、SQL参数化这类细节，甚至会把敏感信息硬编码进去。

把痛点理清之后，规范条目就自然有了。每个条目都对应一个真实坑，落地的时候团队接受度也高——因为大家都遇到过这些问题。

2.3 规范文件的形态：AGENTS.md和CLAUDE.md双轨制

目前主流AI编程工具基本都有“项目级指令文件”的约定。我做了一个双轨方案：仓库根目录放一个AGENTS.md，面向通用AI编程助手；CLAUDE.md专用于Claude Code这类深度集成工具。两者内容基本一致，只是在Claude版本里可以写更多工具调用相关的约束。

还有一点很重要：这个规范文件必须跟着代码仓库走，入库评审、版本管理。这样新成员拉下代码时，AI第一时间就能读到规范，不用额外配置。而且规范更新时走PR流程，谁改的、为什么改，都留下痕迹。

3. 一份可以直接抄作业的AI代码规范长什么样

3.1 规范的顶层结构

我设计的规范分五个模块，每个模块解决一类问题。整体目标是让AI在生成代码前就知道：我在什么项目里、用什么技术栈、按什么风格写、有哪些雷区不能踩。

# AI代码规范（项目工作守则） ## 全局原则 - 本规范优先级高于AI工具默认行为 - 修改已有代码前，先阅读并遵循原文件风格 - 不确定时询问，不擅自决定 ## 技术栈锁定 （列举项目核心技术选型及禁止项） ## 命名与结构 （目录、文件、变量、组件命名规则） ## 代码风格与质量 （错误处理、边界条件、注释标准） ## 提交规范 （commit message格式、PR描述要求）

3.2 技术栈锁定：防止AI自由发挥

AI编程工具最让人头疼的一点是它会“跨栈发挥”。明明项目用的是Vue 3 Composition API，AI能给你生成Options API的写法；明明图标库用的是@ant-design/icons，AI可能顺手引入react-icons。技术栈锁定模块就是干这个的。

我列了几个硬性规则：

• UI组件：必须使用Ant Design 5.x，禁止引入其他组件库
• 状态管理：必须使用Zustand，禁止Redux/MobX
• 请求库：必须使用项目封装的src/utils/request.ts，禁止直接调用axios或fetch
• 样式方案：必须使用CSS Modules，禁止使用Tailwind或styled-components
• 日期处理：必须使用dayjs，禁止使用moment.js

技术栈锁定不能只写“用什么”，还要写“不用什么”。AI对禁止项的理解比鼓励项更精确，你告诉它“不要用moment.js”，它通常就真的不会用。我把这条经验写进了规范，后续AI生成代码的技术栈一致性明显提升。

3.3 命名与目录规范：让AI“说同一种语言”

命名是代码可读性的第一道防线。我给AI定了非常明确的命名规则，每条都配了正反例子，因为AI学习示例的能力远强于理解抽象描述。

变量命名和函数命名采用camelCase，组件和类型采用PascalCase，常量采用UPPER_SNAKE_CASE。这属于基础规则，AI一般不会错。容易错的是语义层面：布尔变量必须以is、has、can开头，获取数据的函数必须以fetch、get、query开头，事件处理函数必须以handle开头。

目录结构方面，我明确要求：API请求必须放在src/services/下，按业务域分文件（如orderService.ts、userService.ts），禁止在组件代码里直接写请求逻辑。工具函数放src/utils/，通用类型放src/types/。

这里有个细节：我在规范里写了一条“新功能组件必须放在src/components/[业务域]/下，禁止在页面文件里堆砌超过200行的子组件”。这个200行的数字不是我拍脑袋定的，是团队code review时发现AI生成的页面经常一个文件上千行，可维护性极差。

3.4 错误处理与边界条件：AI最弱的一环

AI生成代码时最常犯的错，就是假设输入永远是合法的。用户永远不会传空值、接口永远会返回预期结构、缓存永远能命中。等这些假设被打破，线上就会出事故。

我在规范里专门写了一节“边界条件必查清单”，要求AI在生成任何函数或组件时，必须自查以下内容：

• 接口调用是否有loading状态和错误状态？
• 列表渲染时是否有空数组兜底？
• 从对象中取属性时，对象本身是否为null？
• 输入框是否有长度限制和格式校验？
• 文件读取、缓存读取是否有异常捕获？

写法上我给了具体示例，让AI参照执行。比如请求封装模板，我会在规范里贴一段示例代码，要求AI遵循同样的模式，而不是每次自由发挥。

注意：错误处理最容易出现的问题不是“没有try-catch”，而是“catch住了却什么都不做”。我专门加了一条：catch到的错误必须打印日志、设置错误状态或进行用户提示，禁止空catch。

3.5 格式、注释与代码风格约定

关于格式，我不依赖AI的自觉，而是引入工具强制。项目配置了ESLint和Prettier，规范里明确要求AI生成代码后必须经工具格式化，并且不允许通过disable注释跳过检查。这条规则能让AI收敛很多“野路子”写法。

注释方面，我要求AI对每个对外暴露的函数写清楚参数含义和返回值说明，对超过10行的复杂逻辑写“为什么这么写”的说明，而不是“做了什么”的流水账注释。这一点也是AI的通病：它会写一堆“// 这里调用了接口”这种废话注释，对“为什么不用方案A而用方案B”完全不解释。

我给AI提供的注释模板：

/** * 获取订单列表 * @param params 查询参数，包含页码page和每页数量pageSize * @returns 订单列表数据和总数 * @throws 当网络异常或接口返回错误码时抛出 */

还有一条容易被忽略的：禁止在注释或代码中出现过时信息。AI经常复制旧代码，把已经不存在的函数名或业务规则也带过来，我在规范里要求AI如果发现注释与代码行为不一致，必须更新注释而不是只改代码。

4. 怎么让AI真正“听”你的规范

4.1 从Prompt层面约束：开头就把规范“喂”给AI

规范文件写好了，只是个开始。关键在于怎么让AI在实际编码中遵守它。

我调试出来的方法是分两步走。第一步，在每次和AI对话的开头，用一段固定的“上下文注入模板”把规范加载进去；第二步，在对话过程中持续用规则约束AI的输出，而不是等它写完再去改。

上下文注入模板长这样：

你是本项目的高级前端工程师。在开始编码前，请阅读并严格执行仓库根目录下的AGENTS.md文件中的规则。本项目使用TypeScript + React 18 + Zustand + Ant Design 5，所有代码必须符合项目规范，禁止引入项目未使用的依赖。

这段模板放在每轮对话的第一条消息里，AI后续生成的代码合规率会显著提升。原因很简单：AI的上下文窗口是有限的，你Project里堆了太多文件时，它可能忽略掉规范文件。主动注入能确保规范占住上下文的重要位置。

4.2 持续纠偏：对话中的“规则锚点”

规范注入一次不等于万事大吉。在一次长对话中，AI会逐渐“跑偏”，前几轮还遵守规范，越往后越随意。我的办法是在对话中设置“规则锚点”——每过几轮，或者在AI要生成关键文件代码前，主动重申一遍核心约束。

比如在AI即将生成一个新页面时，我会插一句：“请使用当前项目的目录规范，页面文件放在src/pages/下，组件代码放在src/components/目录中，API请求调用src/services/下的封装函数。组件使用Ant Design的Table、Form等组件，不要自造轮子。”

这样做的效果非常明显。AI对近期指令的遵循度远高于远期指令，每过一段时间就锚定一下核心规范，比一次性全量灌输高效得多。

4.3 用代码审查让AI“长记性”

规范最终要落到代码上。我强烈建议为AI生成代码建立审查流程，而且要立即反馈结果。AI不像人，它不会“总结经验”，每次对话都是独立的。但在同一对话里，如果你告诉它“上一步的代码违反了规范某条规则，应该改成这样”，后续代码的合规率会有显著提升。

我会在审查时把问题划分为硬伤和软伤：

• 硬伤：技术栈漂移、命名不规范、有安全隐患、绕过项目封装
• 软伤：代码重复、可读性差、缺注释、结构不够清晰

对于硬伤，我会直接要求AI重写；对于软伤，我会在审查意见里描述具体修改建议。这个方法执行一个月后，AI生成的代码硬伤从每10次出现6次下降到1次，效果立竿见影。

4.4 针对性工具加持：AI插件与规范联动

项目里还引入了一些辅助检查的工具。比如我配置了ESLint规则集，让AI的代码在生成后就被强制约束；还在CI流水线里加了一步“AI代码风格检查”，用自动化脚本扫描AI生成文件中是否存在违反技术栈锁定的import语句。一旦发现，构建直接失败，AI需要自行修复。

这个机制的思路是：与其指望AI自觉，不如让流程卡住它。人工审查是兜底，自动化检查才是常态。我在实践中发现，AI对报错信息的响应比对口头点评要敏感得多——只要说“构建失败了，原因是引入了禁止使用的依赖”，它基本能正确修正。

提醒：不要指望一条规范文件解决所有问题。规范只是基础，真正的质量关口在工程流程里。规范负责“告诉AI正确的方式”，流程负责“保证不符合规范的代码进不了主干”。

5. 常见翻车现场与排查心得

5.1 AI“选择性失忆”：规范读了但没用

这是最高频的问题。明明规范就在仓库根目录，AI还是会产出不符合规范的代码。排查下来主要有几个原因：一是AI一次读取的上下文有限，规范被其他内容挤掉了；二是规范内容太模糊，AI不知道具体该怎么执行。

我的解决方法前面也提到了：对话开始前主动注入规范核心内容，把最关键的约束写在Prompt里而不是只放在文件中。另外，规范文件里多用具体示例，少用抽象原则。AI不理解“保持代码整洁”，但能理解“函数超过50行必须拆分成多个函数”。

还有一个很实用的技巧：把规范文件拆成总规范和分模块规范。总规范放在根目录，面向所有AI；分模块规范放在对应目录下，AI在读取该目录代码时会自然看到。比如src/services/README.md里就写明“所有服务文件禁止直接操作DOM”这类模块级约束，AI在这个目录里写代码时遵守率极高。

5.2 过度遵守：AI把规范用错了地方

还有一种反向的翻车——AI太刻板地遵守规范，把不该统一的东西也统一了。比如我要求“布尔变量以is开头”，AI在命名所有标志位时都套用这个模式，结果生成了isIsOpen、isHasPermission这种怪异命名。

这种情况的根因是规范写得太死，缺少例外说明。后来我在规范里补充了“命名可读性优先于规则一致性”这一条兜底原则，AI再没犯过这个毛病。

5.3 规范文件自身如何维护

规范不是写完就固定不变的。随着项目演进，技术栈可能升级、目录结构可能调整、团队约定可能变化，规范文件也要跟着更新。

我的维护节奏是每两周review一次：把过去两周AI生成代码中出现的问题重新过一遍，看看哪些高频问题规范里还没覆盖，哪些规范条目已经失效。凡是新出现的坑，就补充一条新规范；凡是AI和人都已经内化的规则，就移出规范减少噪音。

规范也要走版本管理和变更评审，不能一个人拍脑袋改。因为它的受众不只是AI，新同学也要靠它理解项目约束，随意改动会带来混乱。

5.4 速查表：典型问题和对应解法

我把实际操作中最常遇到的问题整理成了一张速查表，供大家参考：

6. 最后说点实操中的个人体会

这套给AI制定代码规范的方法，我实际用了大概三个多月，最大的体会是：别把它当成一次性的文档，而要当成一个持续迭代的机制。最有意思的变化是，AI生成的代码从“一眼就能看出是AI写的”，逐渐变成了“和我们团队的代码融为一体”，这说明规范不再只是约束，它已经变成了AI理解项目的“语言模型”。

还有一个体会：给AI定规范，其实是在帮团队重新梳理一遍自己的工程体系。因为你要把之前靠“默契”和“常识”传递的经验，变成显性、明确、可执行的内容，这个整理过程本身就会暴露很多问题——比如你发现团队对“到底用不用dayjs”都没有统一过，那AI就更不知道了。

所以如果你正准备给AI定规矩，我的建议是：不用追求一步到位，先抓住最痛的三个问题，写成规范，让AI跑起来，然后每周迭代。规范会逐渐变成新的团队资产，它沉淀的不仅是一份约束，更是开发团队对“什么是好代码”的共同理解。