2.4 项目规则配置

---

1. 为什么要学这个?

你可能会发现:每次开始新对话,都要重复告诉AI"用TypeScript"、"用Tailwind"、"遵循我的命名规范"。

想象你管理一个工厂。

• 没有规章制度:每个工人都按自己的方式干活,产品质量参差不齐,你得盯着每个人重复同样的要求。
• 有规章制度:制定好《生产规范手册》,所有工人按统一标准操作,产品质量稳定,你只需要偶尔检查。

关键问题:

• 怎么让AI记住项目的技术栈?
• 怎么让AI自动遵循编码规范?
• 怎么让团队所有人用AI时保持一致?
• 怎么避免每次都重复相同的指令?

项目规则配置就是给AI制定的《生产规范手册》。

---

2. 核心概念

2.1 项目规则的三个层次

技术定义:项目规则是告诉AI"在这个项目中应该怎么做"的指令集合,分为全局规则、项目规则、对话规则三个层次。

就像公司的规章制度体系。

• 全局规则:适用于所有项目的通用规范(如"用中文回答")
• 项目规则:只适用于当前项目的特定规范(如"用Next.js 14")
• 对话规则:临时的、一次性的指令(如"这次用简洁的风格")

graph TD
    A[AI接收任务] --> B[读取全局规则]
    B --> C[读取项目规则]
    C --> D[读取对话指令]
    
    D --> E{规则冲突?}
    E -->|有冲突| F[对话指令 > 项目规则 > 全局规则]
    E -->|无冲突| G[合并所有规则]
    
    F --> H[执行任务]
    G --> H
    
    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style H fill:#e8f5e9

2.2 规则的优先级

优先级从高到低:

1. 对话指令:你当前说的话,临时覆盖其他规则
2. 项目规则:项目特定的规范
3. 全局规则:你的个人偏好
4. AI默认行为:AI的通用知识

举例说明:

# 全局规则:用中文回答
# 项目规则:用TypeScript
# 对话指令:"这次用JavaScript写"

# AI会:用JavaScript写代码(对话指令优先),但用中文回答(全局规则)

---

3. 项目规则的配置方式

3.1 方式1:.cursorrules文件

最常用的方式,适合大多数项目。

# 在项目根目录创建.cursorrules文件
project/
├── .cursorrules      # 项目规则文件
├── package.json
├── src/
└── README.md

.cursorrules示例:

# 技术栈
- Next.js 14 App Router
- TypeScript (严格模式)
- Tailwind CSS + shadcn/ui
- pnpm包管理器

# 编码规范
- 组件:PascalCase (UserCard.tsx)
- 函数:camelCase (getUserData)
- 常量:UPPER_SNAKE_CASE (API_URL)
- 文件:kebab-case (user-card.tsx)

# 代码风格
- 使用函数组件
- 优先使用服务端组件
- 客户端组件加"use client"

# 禁止项
- ❌ any类型
- ❌ var关键字
- ❌ class组件
- ❌ 内联样式

3.2 方式2:README.md中的规范

适合开源项目或需要公开规范的项目。

# 项目名称

## 开发规范

### 技术栈
- React 18 + TypeScript
- Vite构建工具
- Vitest测试框架

### 代码规范
详见 CONTRIBUTING.md

### 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新

AI会自动读取README.md中的规范信息。

3.3 方式3:专门的规范文档

适合大型项目或企业项目。

project/
├── docs/
│   ├── coding-standards.md    # 编码规范
│   ├── api-design.md          # API设计规范
│   ├── database-schema.md     # 数据库规范
│   └── git-workflow.md        # Git工作流
├── .cursorrules               # 引用这些文档
└── src/

.cursorrules引用文档:

# 项目规范

## 编码规范
详见: docs/coding-standards.md

## API设计
详见: docs/api-design.md

## 数据库规范
详见: docs/database-schema.md

## Git工作流
详见: docs/git-workflow.md

---

4. 实际应用场景

🏢 场景1:企业级Web应用

# 企业ERP系统开发规范

## 技术栈
- 前端:Next.js 14 + TypeScript + Ant Design
- 后端:NestJS + PostgreSQL + Prisma
- 部署:Docker + Kubernetes

## 安全规范
- 所有API必须验证JWT token
- 敏感数据必须加密存储
- 禁止在代码中硬编码密码

## 性能要求
- 页面首屏加载 < 2秒
- API响应时间 < 500ms
- 数据库查询必须有索引

## 测试要求
- 核心功能必须有单元测试
- API必须有集成测试
- 测试覆盖率 > 80%

## Code Review检查清单
- [ ] 通过TypeScript类型检查
- [ ] 通过ESLint检查
- [ ] 有必要的单元测试
- [ ] 有清晰的注释
- [ ] 处理了错误情况
- [ ] 没有安全漏洞

📱 场景2:移动应用开发

# React Native移动端规范

## 技术栈
- React Native + Expo
- TypeScript
- React Navigation
- Redux Toolkit

## 移动端特殊要求
- 所有尺寸使用相对单位
- 图片提供@2x和@3x版本
- 长列表用FlatList
- 异步操作显示loading

## 性能优化
- 列表用React.memo优化
- 避免在render中创建函数
- 图片压缩,单张<200KB
- 使用Hermes引擎

## 平台兼容
- 用Platform.select处理差异
- iOS和Android都要测试
- 注意安全区域

🎨 场景3:设计系统开发

# 设计系统组件库规范

## 技术栈
- React + TypeScript
- Vite构建
- CSS Modules
- Storybook文档

## 组件开发要求
每个组件必须有:
1. TypeScript类型定义
2. Storybook故事
3. 单元测试
4. 使用文档

## 设计规范
- 颜色:使用CSS变量
- 间距:8px网格系统
- 字体:使用设计Token
- 动画:transition < 300ms

## 可访问性
- 交互元素有aria-label
- 支持键盘导航
- 颜色对比度WCAG AA

---

5. 规则配置的最佳实践

✅ 实践1:分层管理

不同类型的规则放在不同地方:

# 全局规则(个人偏好)
~/.cursor/rules.md
- 用中文回答
- 代码简洁
- 详细注释

# 项目规则(团队共识)
project/.cursorrules
- 技术栈
- 编码规范
- Git规范

# 临时规则(对话指令)
"这次用简洁的风格,不要太多注释"

✅ 实践2:保持简洁

规则文件不要超过100行,只写核心内容:

# ❌ 不好的做法:写得太详细
## 命名规范
- 组件名必须用PascalCase
- 组件名的第一个字母必须大写
- 组件名不能包含数字开头
- 组件名要有意义,不能用a,b,c
- ...（写了50条）

# ✅ 好的做法:简洁明了
## 命名规范
- 组件:PascalCase (UserCard)
- 函数:camelCase (getUserData)
- 常量:UPPER_SNAKE_CASE (API_URL)
- 文件:kebab-case (user-card.tsx)

✅ 实践3:使用检查清单

把规则变成可执行的检查清单:

## Code Review检查清单
提交前确保:
- [ ] 通过TypeScript检查
- [ ] 通过ESLint检查
- [ ] 通过单元测试
- [ ] 添加必要注释
- [ ] 更新相关文档

✅ 实践4:定期更新

每月review一次规则文件:

# 规则更新记录
## 2026-01
- 新增:使用shadcn/ui组件库
- 删除:过时的CSS Modules规范
- 更新:TypeScript升级到5.0

## 2025-12
- 新增:API设计规范
- 更新:测试覆盖率要求提高到80%

---

6. 避坑指南

❌ 不要这样做	✅ 应该这样做	为什么
规则写得太长太详细	只写核心规则,不超过100行	规则太长消耗大量Token,AI也记不住
规则互相矛盾	定期review,确保一致性	矛盾的规则让AI困惑,不知道听谁的
把个人偏好写进项目规则	个人偏好放全局,项目规则只写团队共识	避免影响团队其他成员
规则过于严格	留有灵活空间	过度规定限制AI的创造力
从不更新规则	每月review一次	过时的规则会误导AI
规则散落各处	集中管理,清晰引用	方便维护和查找

---

7. 真实案例

---

8. 本章小结

1. 📋 三个层次:全局规则(个人偏好) > 项目规则(团队共识) > 对话指令(临时需求)
2. 📁 三种方式:.cursorrules文件、README.md、专门的规范文档
3. 🎯 优先级:对话指令 > 项目规则 > 全局规则 > AI默认行为
4. ✍️ 写什么:技术栈、编码规范、命名约定、Git规范、检查清单
5. 🔧 保持简洁:不超过100行,只写核心规则
6. 🔄 定期更新:每月review,随项目演进更新
7. 👥 团队一致:统一规则让所有人用AI时保持相同标准