本架构示例项目：AI Coding Guidelines

原文链接（掘金）：前端 AI Coding 落地指南（二）Rules篇

转载声明：本文为转载整理内容，仅用于技术学习与交流；相关版权归原作者所有。如有侵权，请联系删除。

本篇是《前端 AI Coding 落地指南》的续作，专门讲 Rules 的实践：演进过程、设计原则、如何划分模块、何时写 Rules 何时写 Skills，以及项目级 Rules 的完整清单与每条 rule 的头部、介绍和通用化示例。首篇中已给出 Rules 的简要历程与清单，这里展开为可落地的细节。

Rules 是什么、解决什么问题

Rules 是写在项目里的持久化指导，用 Markdown 等形式约定项目的规范、约束和惯例。Agent 在「需要确认某类规范时」按需读取对应规则文件，从而在生成或审查代码时遵守「做什么、不做什么」——命名、目录、接口契约、样式变量、错误处理等有据可查。

作用：统一边界（减少模型随意发挥）、按需加载（控制上下文长度）、提高接纳率（生成结果更符合项目既有约定）。能解决的 AI Coding 问题：规范不一致（没有规则时 AI 易按通用习惯写，与项目脱节）；约束缺失（如「接口必须放某目录」不写进规则就容易漏）；上下文漂移（规则按场景拆分，需要时只加载相关文件，避免一次性塞入整本规范导致注意力分散）。

演进过程

一开始：整个项目一个庞大的 Rules
所有规范、步骤、示例都塞在一个或少数几个大文件里。带来的问题是：单次上下文过大（容易顶到上下文上限或挤占对话）、容易丢记忆/注意力分散（长文档里模型容易「看了后面忘前面」）、难以按场景聚焦（比如只想加个路由，却不得不带着 UI 验收、设计稿分析等无关内容）。结果是步骤漏、检查项漏，接纳率反而不稳定。

中期：按模块拆成多个 Rules
把「项目概述、编码、结构、组件、API、路由、状态、通用约束、样式、文档、测试」等拆成 01～11 这样的独立文件，需要哪类规范就读哪几个。按需加载效果好很多，上下文压力下来，也便于维护。但还有一个问题没解决：「如何落地」的步骤和示例仍然写在 Rules 里——例如「怎么加一个路由」的详细步骤、目录示例、检查清单，和「路由必须和菜单一致」这类约束混在一起，单文件仍然偏长，且步骤化、可复用工作流不好跨项目复用。

最近：Skills 盛行，Rules 简化 + 实施指导迁到 Skills
引入 Skills 之后，做了两件事：Rules 只保留「原则与约束」（做什么、不做什么、目录/命名/契约），把「如何一步步做、怎么写示例、产出长什么样」迁到 Skills，并利用 Skills 的渐进式披露（只在执行该任务时加载对应 SKILL 和技能内 rules）。这样 Rules 变薄、按需读；具体落地在 Skills 里按场景加载，既避免上下文爆炸，又避免模型在长文档里「抓不住重点」。Skills 的详细实践、何时封装、技能下 rules 如何拆分见《前端 AI Coding 落地指南（三）Skills 篇》。

设计原则：哪些写 Rules、哪些写 Skills

原则概括：Rules 回答「是什么 / 不能是什么」，Skills 回答「怎么做 / 先做什么再做什么」。

模块划分：按「开发时会被问到的决策类型」来拆，而不是按代码目录拆。例如：项目背景与技术栈（项目概述）、命名与风格（编码规范）、文件放哪（项目结构）、组件怎么拆（组件规范）、接口怎么定义和调用（API 规范）、路由和菜单怎么对（路由规范）、状态放哪怎么用（状态管理）、全局约定（通用约束）、样式和主题（样式规范）、注释与测试（文档/测试规范）。这样 Agent 在「要做一个什么类型的决策」时，能对应到某一个或少数几个规则文件。

什么留在 Rules：原则、约束、契约、目录与命名约定。例如「接口必须放在某目录下」「路由配置必须和菜单配置一致」「错误必须用统一方式处理」「主题色必须走 CSS 变量」——这些是「是/否」判断，不涉及长步骤和大量示例，适合放在 Rules，篇幅可控。

什么放到 Skills：多步骤流程、检查清单、产出模板、示例代码。例如「创建提案的 5 步」「设计稿分析的 4 步」「加一个路由要创建哪几个文件、每步检查什么」「UI 分析清单/问题清单长什么样」——这些一旦写进 Rules 会让单文件很长，且和「原则」混在一起，不利于按场景加载；放到 Skills 里，用 SKILL.md + 技能内 rules 做渐进披露更合适。

判断方式：若一句话能说清且不需要示例，放 Rules；若需要「第一步、第二步、检查点、模板、示例」，放 Skills。

项目级 Rules 清单（目录结构）

1
2
3
4
5
6
7
8
9
10
11
12
13
.agents/rules/
├── 01-项目概述.md
├── 02-编码规范.md
├── 03-项目结构.md
├── 04-组件规范.md
├── 05-API规范.md
├── 06-路由规范.md
├── 07-状态管理.md
├── 08-通用约束.md
├── 09-样式规范.md
├── 10-文档规范.md
├── 11-测试规范.md
└── README.md

由于篇幅问题，以下每条 rule 示例是简化后的，主要作为参考，后续会把完整的代码放到 github 上。

01-项目概述

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
---
alwaysApply: false
description: 项目定位与技术栈概览。当需要了解项目背景、使用的技术栈时读取此规则。
---

# 项目概述

## 项目定位

一段话说明项目是什么、面向谁、核心能力。

## 技术栈

| 领域     | 技术               | 说明                      |
| -------- | ------------------ | ------------------------- |
| UI 框架  | React x.x          | 强制使用                  |
| 类型系统 | TypeScript x.x     | 强制使用，禁止 JavaScript |
| 状态管理 | Zustand / Redux 等 | 统一使用，禁止其他方案    |
| 组件库   | Ant Design / 其他  | 交互 UI 基于此二次封装    |
| 样式方案 | SCSS Modules       | 强制使用，禁止全局样式    |

02-编码规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
---
alwaysApply: false
description: 编码规范，包括 TypeScript 使用、命名约定（变量、常量、接口、组件等）、业务函数命名。编写或审查代码时读取。
---

# 编码规范

## TypeScript 规范

- 所有代码必须使用 TypeScript，禁止使用 JavaScript
- 禁止使用 `any`（除非有明确理由并注释）
- 接口、类型使用 PascalCase；组件 Props 必须定义清晰接口

## 命名规范

| 类型         | 规则       | 示例               |
| ------------ | ---------- | ------------------ |
| 文件夹/路由  | kebab-case | user-profile       |
| 变量/函数    | camelCase  | userList, onSubmit |
| 常量         | UPPER_CASE | API_TIMEOUT        |
| 接口/类      | PascalCase | UserInfo           |
| React 组件   | PascalCase | UserProfile        |
| 自定义 Hooks | use 开头   | useUserStore       |

## 业务函数命名

- 事件处理：onXxx（如 onSubmit）
- 内部处理：handleXxx（如 handleDelete）
- 内部处理：handleXxx（如 handleDelete）

03-项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
---
alwaysApply: false
description: 目录结构规范，各目录用途与约束（禁止新建非标准目录）。确定代码放哪时读取。
---

# 项目结构（NON-NEGOTIABLE）

## 目录结构

src/
├── assets/ # 静态资源
├── components/ # 可复用 UI 组件
├── constants/ # 业务常量、枚举
├── hooks/ # 自定义 Hook
├── http/ # 请求封装
├── interfaces/ # 类型声明（model、api）
├── routes/ # 路由页面
├── stores/ # 全局状态，按业务拆分
├── utils/ # 工具函数
└── 根级入口文件

## 结构约束

- 常量 → constants/；状态 → stores/；接口类型 → interfaces/（每模块含 model.ts、api.ts）
- 组件 → components/ 或 routes/<name>/components/；路由 → routes/，每路由含 Page、Loader、index.module.scss

04-组件规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
alwaysApply: false
description: 组件目录结构、样式方案、通用 vs 页面级。创建或拆分组件时读取。
---

# 组件规范

## 组件结构

- 组件在 src/components 或路由下 components，每组件单独目录
- 文件：index.tsx、index.module.scss；必须 SCSS Modules，禁止全局样式
- Props 接口必须明确；使用 classnames 管理动态 class

## 组件层级

- 页面级：仅单页使用 → routes/<page>/components/
- 通用：跨页面复用 → src/components/
- 单文件建议不超过 400 行（拆分参考）

05-API规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
alwaysApply: false
description: 接口请求封装、函数命名、错误处理。新增或修改接口时读取。
---

# API 规范

## 接口请求规范

- 请求使用 src/http 下封装；类型 Params/Body/Response 放在 src/interfaces/<module>/api.ts
- 所有接口集中在 src/http/<module>.ts

## 接口函数命名（NON-NEGOTIABLE）

| 操作           | 命名规则                          | 示例            |
| -------------- | --------------------------------- | --------------- |
| 获取列表       | getXxxList                        | getBannerList   |
| 获取详情       | getXxxDetail                      | getBannerDetail |
| 创建/更新/删除 | createXxx / updateXxx / deleteXxx | 禁止 fetch 前缀 |

## 错误处理（NON-NEGOTIABLE）

- 接口错误由拦截器统一处理，业务代码只处理成功逻辑；禁止重复 message.error

06-路由规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
alwaysApply: false
description: 路由目录结构、Page/Loader 模式、路由配置集中管理。新增页面或配置路由时读取。
---

# 路由规范（NON-NEGOTIABLE）

## 路由结构

- 路由目录在 src/routes 下，每页单独目录，kebab-case
- 必须包含：Page.tsx、Loader.tsx、index.module.scss
- Loader 只负责懒加载对应 Page，不嵌套 Routes/Route

## 路由与菜单

- 禁止多处维护路由：全局唯一路由配置集中管理
- 同一页面只在一处被 lazy 引入

07-状态管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
alwaysApply: false
description: 全局状态使用 Zustand（或项目约定方案）。新增或重构状态时读取。
---

# 状态管理规范（NON-NEGOTIABLE）

## 基础规范

- 必须使用项目约定的状态库（如 Zustand），所有 store 放在 src/stores
- 禁止在 src 下新建其他目录存放 store

## Store 组织

- 按业务模块划分，每模块单独文件；暴露 useXxxStore Hook
- Store 只存数据与业务行为，不耦合 UI 组件
- 需持久化时使用 persist 等中间件

08-通用约束

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---
alwaysApply: false
description: 语言、可观测性、占位元素等通用约束。确认通用约束时读取。
description: 语言、可观测性、占位元素等通用约束。确认通用约束时读取。
---

# 通用约束

## 语言规范（NON-NEGOTIABLE）

- 文档和代码注释使用中文；变量/函数命名仍用英文

## 可观测性与兜底

- 任务需完整链路：任务 ID、引用、日志；失败时兜底提示与重试

## 占位元素

- 图标/图片未定时：用占位 div + TODO 注释，禁止临时 svg/占位图服务；明确标记替换点

09-样式规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
---
alwaysApply: false
description: SCSS Modules、主题 CSS 变量。编写样式或主题适配时读取。
---

# 样式规范

## 基础原则

- 样式采用 SCSS Modules（index.module.scss）；classnames 管理动态 class
- 自定义样式必须使用主题色 CSS 变量，禁止硬编码颜色

## 主题变量（NON-NEGOTIABLE）

- 主色/文本/背景/边框等使用 var(--ant-color-xxx) 或项目自定义 var(--xxx)
- 确保主题切换（浅色/暗色）一致

10-文档规范

1
2
3
4
5
6
7
8
9
10
11
---
alwaysApply: false
description: JSDoc 与注释规范。编写或审查注释时读取。
---

# 文档规范

## 注释规范

- 使用 JSDoc（/\*\* \*/），解释「为什么」而非「是什么」
- 文件头、函数/方法、复杂逻辑、类型定义均需必要说明

11-测试规范

1
2
3
4
5
6
7
8
9
10
11
---
alwaysApply: false
description: 测试覆盖与质量门禁。确认测试要求时读取。
---

# 测试规范

## 测试要求

- 新增功能需必要类型定义，关键业务逻辑需测试用例
- 所有代码通过 TypeScript 与 ESLint 检查

以上就是项目级 Rules 的完整清单与通用化示例。项目级 Skills 的逐条示例在《前端 AI Coding 落地指南（三）Skills 篇》；架构篇、Rules 篇、Skills 篇一起构成从架构到 Rules/Skills 落地的完整指南。