我们似乎正站在一个奇妙的分岔路口。一方面代码生成的速度快得让人眼花缭乱；另一方面审查AI生成的代码时那种“似是而非”的痛苦又让人抓狂。你有没有遇到过这样的情况：你让AI帮你写一个组件，结果它用了一套你项目里根本不存在的命名规范，或者把API接口扔进了一个随意的目录里？这时候你不得不叹口气，然后自己动手重写。

这其实不是AI不够聪明，而是我们忘了给它立规矩。就像带一个聪明但没经验的新人，Ru果不告诉他“这里的插座不Neng碰”，他大概率会去试一试。今天我想和大家深入聊聊一个kan似枯燥却至关重要的话题：如何制定前端AI编码规范？ 这不仅仅是为了让代码好kan，geng是为了让AI真正成为你团队中那个“懂规矩”的高效伙伴。

为什么我们需要给AI立规矩？

在深入具体操作之前，我们得先明白，这套规范到底是为了解决什么痛点。hen多时候，我们把AI当成万Neng的神，期待它无师自通。但现实是AI模型是基于概率预测的，Ru果没有明确的约束，它就会倾向于使用它训练数据中出现频率Zui高的“通用习惯”。这就像是去了一家餐厅，厨师默认给你Zuo了Zui辣的菜，因为他觉得大家dou爱吃辣，但你其实一点辣dou沾不得。

制定规范的核心作用，其实Ke以概括为三点：

第一，统一边界，减少模型随意发挥。 这就好比给AI画了一个圈，告诉它：“在这个圈子里你Ke以尽情施展；出了这个圈，就是禁区。” 比如你的项目强制规定所有的接口请求必须经过统一的拦截器处理，Ru果没有这条规则，AI可Neng就会直接写一个裸的 `fetch` 或者 `axios` 调用，这显然是你不想kan到的。

第二，按需加载，控制上下文长度。 大家dou知道，AI的上下文窗口是有限的资源。Ru果你把整个公司的几百条规范一股脑塞给它，不仅浪费Token，还容易导致“注意力分散”。这就好比你给一个人同时kan了十份不同的图纸，他大概率会搞混。我们需要的是一种机制，在AI需要写路由的时候，只给它kan路由的规范；在写样式的时候，只给它kan样式的规范。

第三，提高接纳率，让生成结果geng符合项目既有约定。 这一点Zui直接。当AI生成的代码完美契合你的项目风格时你只需要稍微检查一下就Neng直接合并，这种“丝滑”的感觉才是我们使用AI编程的初衷。否则，AI写得越快，你改得越累，那还有什么意义呢？

核心哲学：Rules 与 Skills 的博弈

在构建这套规范体系时我们Zui容易犯的错误就是把所有东西dou混在一起。这就像把冰箱里的生肉、蔬菜和饮料全部扔在一个抽屉里虽然dou在冰箱里但找起来极其痛苦。经过大量的实践和摸索，我发现一个极其有效的原则：Rules 回答「是什么 / 不Neng是什么」，Skills 回答「怎么Zuo / 先Zuo什么再Zuo什么」。

这听起来有点抽象，让我们来拆解一下。

Rules 是静态的、约束性的。它们是项目中的“法律”。比如“组件文件必须使用 PascalCase 命名”，“接口定义必须放在 `api` 目录下”，“所有的颜色变量必须定义在 CSS 变量中”。这些是是非题，只有“是”或“否”的判断，没有中间地带。

Skills 则是动态的、流程性的。它们是项目中的“操作手册”或“SOP”。比如“如何从零开始创建一个新的业务模块”，“如何进行设计稿的还原分析”，“添加一个新路由需要经过哪几个步骤”。这些是流程题，涉及第一步Zuo什么、第二步Zuo什么、检查点在哪里、Zui终的产出物长什么样。

为什么要分得这么清楚？因为Ru果把“怎么Zuo”的步骤也塞进 Rules 里会导致单个文件极其臃肿。想象一下Ru果在“路由规范”里不仅规定了路由的命名规则，还详细写了“如何创建路由文件、如何配置菜单权限、如何编写路由守卫”的十步流程，那么当AI只需要查询“路由文件该叫什么名字”时它不得不读完这长长的十步流程，这不仅浪费了算力，还可Neng干扰它的判断。

判断标准：一句话原则

在实际操作中，我给自己定了一个简单的判断标准：Ru果一句话Neng说清且不需要示例，就放 Rules；Ru果需要“第一步、第二步、检查点、模板、示例”，那就放 Skills。

这个简单的原则，Neng帮你解决90%的分类困惑。

演进之路：从“大杂烩”到“精细化”

这套体系的形成并非一蹴而就。回顾过去，我们大概经历了三个阶段，每一个阶段dou是对前一个阶段痛点的反思和修正。

第一阶段：庞大的“单文件”时代

Zui开始，我们尝试把所有的规范、步骤、示例dou塞在一个或者少数几个巨大的 Markdown 文件里。那时候的想法hen天真：“只要我把所有东西dou写进去，AI肯定就懂了。”

结果呢？灾难现场。

单次上下文过大，经常顶到模型的 Token 上限。geng糟糕的是由于文档太长，模型经常出现“kan了后面忘前面”的情况。比如它可Neng在文档开头kan到了“使用 TypeScript”，写到一半又忘了后面开始写 JavaScript。或者，当你只想让它加个路由时它却带着一堆关于“UI 验收”和“设计稿分析”的无关信息，导致注意力分散，Zui终生成的代码步骤遗漏，检查项缺失，接纳率极其不稳定。这就像你想让厨师只炒个青菜，他却把整本菜谱dou读了一遍，Zui后把糖当成盐放了。

第二阶段：按模块拆分的“多文件”时代

痛定思痛，我们开始拆分。我们把“项目概述、编码、结构、组件、API、路由、状态、通用约束、样式、文档、测试”等拆分成十几个独立的文件。需要哪类规范，就读哪几个。

效果立竿见影。按需加载的效果好了hen多，上下文的压力下来了维护也方便了不少。但是问题依然存在。

虽然文件拆了但内容结构没变。我们依然把“如何落地”的详细步骤和示例写在 Rules 里。比如在“路由规范”里依然混杂着“怎么加一个路由”的详细步骤、目录示例和检查清单。这就导致单文件虽然比以前小了但依然偏长。而且，那些步骤化、可复用的工作流，hen难跨项目复用。每换一个项目，就要重新整理一遍这些流程，非常繁琐。

第三阶段：Rules 简化 + Skills 盛行的“混合”时代

这就是我们目前推崇的终极形态。引入 Skills 的概念后我们Zuo了一次彻底的“断舍离”。

Rules 只保留「原则与约束」——Zuo什么、不Zuo什么、目录结构、命名规范、接口契约。这些是骨架，是底线。

把「如何一步步Zuo、怎么写示例、产出长什么样」全部迁到 Skills。并利用 Skills 的渐进式披露特性——只在执行该特定任务时才加载对应的 SKILL 文件和技Neng内部的 rules。

这样一来Rules 变得非常薄，非常轻量，按需读取的速度极快。而具体的落地细节，则被封装在 Skills 里按场景加载。这不仅避免了上下文爆炸，还防止了模型在长文档里“抓不住重点”。这种架构，既保证了规则的严肃性，又赋予了流程的灵活性。

实战指南：如何搭建你的规范体系

说了这么多理论，到底该怎么动手呢？别急，我们来kankan具体的架构设计。

目录结构设计

我们需要一个清晰的目录结构来存放这些规则。不要按照代码的目录结构来拆分，而是要按照「开发时会被问到的决策类型」来拆。这一点非常关键，因为AI在思考时是基于“我要解决什么问题”而不是“这个文件属于哪个文件夹”。

.agents/rules/
├── -项目概述.md
├── -编码规范.md
├── -项目结构.md
├── -组件规范.md
├── -API规范.md
├── -路由规范.md
├── -状态管理.md
├── -通用约束.md
├── -样式规范.md
├── -文档规范.md
├── -测试规范.md
└── README.md

由于篇幅限制，这里无法列出每个文件的完整内容，但我会详细解释每个模块应该包含什么以及为什么这样划分。

1. 项目概述

这是AI认识你的项目的第一扇窗。这里不应该写具体的代码规则，而应该写背景信息。比如：这是一个电商后台还是社交App？主要的技术栈是 React + TypeScript 还是 Vue3？有没有什么特殊的历史遗留问题？

这就像是给新员工Zuo的入职培训，先让他知道我们在干什么用什么工具，再去谈怎么干。

2. 编码规范

这里放的是Zui基础的语法和风格约定。比如：缩进是用2个空格还是4个空格？单引号还是双引号？语句末尾要不要加分号？变量命名是用 camelCase 还是 snake_case？

这些是“是什么”的问题，非常适合放在 Rules 里。比如：“必须使用 2 空格缩进，禁止使用 Tab。” 简单、直接、无歧义。

3. 项目结构

这是AIZui容易迷路的地方。你需要明确告诉它，文件应该放在哪里。比如：页面组件放在 `pages` 目录，公共组件放在 `components` 目录，工具函数放在 `utils` 目录。

规则示例：“所有的业务接口请求文件，必须存放在 `src/api/` 目录下且按业务模块划分子目录。” 这就是一个典型的约束，不需要步骤，只需要结果。

4. 组件规范

前端开发的核心就是组件。这里要规定组件的拆分原则、Props 的定义方式、事件的命名规范等。

比如：“组件文件名必须使用 PascalCase命名，且与组件内部 export 的名称保持一致。” 或者 “组件必须通过 Props 定义接收的数据，禁止直接在组件内部修改父组件传递的 props。”

5. API 规范

这里主要规定接口的定义和调用方式。比如：接口类型定义必须使用 TypeScript 的 `interface` 还是 `type`？请求方法如何封装？错误如何统一处理？

规则示例：“所有 API 函数必须显式声明返回值的 TypeScript 类型。” 这Neng有效避免类型推导错误。

6. 路由规范

路由是前端应用的骨架。这里要规定路由的配置方式、懒加载的写法、路由守卫的使用等。

规则示例：“路由配置必须与菜单配置保持一致的层级结构，确保权限控制的准确性。” 这条规则Neng解决hen多权限管理的隐患。

7. 状态管理

Ru果你的项目使用了 Redux、Pinia 或 Zustand，这里就要规定状态如何划分、如何修改、如何派发。

规则示例：“全局状态必须存放在 store 模块中，禁止在组件内部通过 Context 滥用全局状态。”

8. 通用约束

这是一个兜底的文件，用来放那些无法归类到具体模块，但又必须遵守的“铁律”。比如：禁止使用某些不安全的库、禁止在生产环境打印 console.log 等。

9. 样式规范

CSS 是Zui容易写出“屎山”的地方。这里要规定是使用 CSS Modules、Tailwind CSS 还是 Styled Components。主题色如何定义？响应式断点如何设置？

规则示例：“所有主题色变量必须定义在 `src/styles/variables.css` 中，通过 CSS 变量引用，禁止硬编码颜色值。”

10. 文档与测试规范

Zui后别忘了文档和测试。规定注释的写法、测试文件的命名规范、测试覆盖率的要求等。

Skills：让流程自动化

好了Rules 建好了AI 知道了“不NengZuo什么”。那“怎么Zuo”呢？这就是 Skills 大显身手的时候了。

正如前面提到的，Skills 适合放那些多步骤的流程、检查清单、产出模板和示例代码。

举个例子，假设我们要定义一个“新增路由技Neng”。在 Skills 文件里我们会这样写：

步骤一在 `src/router/modules` 下创建对应的模块文件。

步骤二定义路由配置对象，包含 path、name、component 等字段。

步骤三在 `src/views` 下创建对应的页面组件文件。

步骤四确认路由配置中的 `component` 路径与实际文件路径一致。

步骤五在菜单配置文件中添加对应的菜单项，确保 `path` 匹配。

甚至，你Ke以附上一个标准的代码模板，让 AI 直接填充。

这种写法，Ru果放在 Rules 里会显得非常啰嗦且格格不入。但放在 Skills 里它就是一个完美的“操作指南”。当 AI 接到“帮我加一个用户管理页面的路由”的指令时它会自动加载这个 Skill，然后按部就班地执行，不会漏掉任何一个检查点。

规范是AI的“导航仪”

制定前端 AI 编码规范，本质上是在为 AI 编写一本“生存指南”。我们通过 Rules 划定了安全的边界，通过 Skills 提供了行动的地图。这不仅解决了规范不一致、约束缺失、上下文漂移等常见问题，geng重要的是它让我们从繁琐的代码审查和重复劳动中解放出来。

不要指望 AI 天生就懂你的项目，就像不要指望一个新来的实习生天生就懂公司的文化一样。花点时间，把你的经验、你的约定、你的Zui佳实践，沉淀成这一份份 Rules 和 Skills。你会发现，AI 变得越来越“聪明”，越来越像你肚子里的蛔虫，生成的代码也越来越让你省心。

这才是我们拥抱 AI 编程的正确姿势。希望这篇指南Neng为你打开一扇新的大门，让你的前端开发效率实现质的飞跃。Ru果你在实践过程中遇到什么问题，或者有什么geng好的点子，欢迎随时交流，毕竟在这条探索之路上，我们dou是同行者。

---