Rules 规则体系
用户规则、项目规则、三种加载类型、约束AI行为
引言：让 AI 遵循你的规范
你是否有过这样的经历：AI 生成的代码风格与团队不一致？用了不推荐的库？命名不符合规范？每次都要在对话中重复说明编码规范？
CodeBuddy 的 Rules 规则体系就是为了解决这个问题——通过预定义规则，让 AI 在每次交互时都遵循你的编码规范、技术选型和团队约定。
核心思想：Rules = 你对 AI 的编程规范培训。一次配置，永久生效。
1. 两种规则类型
1.1 用户规则（User Rules）
适用范围：所有项目的个人偏好
存储位置：~/.codebuddy/rules/
典型内容：
# 个人编码偏好
## 代码风格
- 使用 2 空格缩进
- 字符串使用单引号
- 语句末尾不加分号
- 优先使用 const，其次 let，禁止 var
## 命名规范
- 组件使用 PascalCase：UserProfile
- 函数使用 camelCase：getUserById
- 常量使用 UPPER_SNAKE_CASE：MAX_RETRY_COUNT
- 文件名使用 kebab-case：user-profile.ts
## 偏好
- 优先使用 TypeScript 而非 JavaScript
- 优先使用 async/await 而非 Promise.then
- 错误处理使用 try-catch，不使用 .catch()
1.2 项目规则（Project Rules）
适用范围：仅当前项目
存储位置：.codebuddy/rules/
典型内容：
# 项目技术规范
## 技术栈
- 框架：Next.js 14 (App Router)
- 数据库：PostgreSQL + Prisma ORM
- 认证：NextAuth.js v5
- 样式：Tailwind CSS + shadcn/ui
- 测试：Vitest + Testing Library
## 架构规范
- 使用 Repository 模式隔离数据访问
- API 路由使用 Zod 进行参数验证
- 错误处理使用自定义 AppError 类
- 日志使用 Pino，不使用 console.log
## 禁止事项
- 不使用 any 类型
- 不使用 useEffect 直接修改 state
- 不在组件中写业务逻辑
- 不使用 alert()，使用 toast 通知
2. 三种加载类型
| 类型 | 标识 | 加载时机 | 适用场景 |
|---|---|---|---|
| Always | always | 始终加载到上下文 | 核心规范、编码风格 |
| Agent | agent | 仅智能体模式加载 | 项目架构、部署流程 |
| Manual | manual | 手动触发加载 | 特定任务的详细指南 |
2.1 Always 类型示例
---
type: always
---
# 编码风格规范
- 2 空格缩进
- 单引号
- 无分号
2.2 Agent 类型示例
---
type: agent
---
# 部署流程
1. 运行 npm run test
2. 运行 npm run build
3. 执行 docker build
4. 推送到 ECR
5. 更新 ECS 服务
2.3 Manual 类型示例
---
type: manual
---
# 数据库迁移指南
1. 创建迁移文件：npx prisma migrate dev --name xxx
2. 检查生成的 SQL
3. 在 staging 环境验证
4. 在 production 环境执行
3. Rules 文件格式
3.1 文件格式说明
规则文件使用 .mdc 格式（Markdown with frontmatter），每条规则对应一个包含 RULE.mdc 文件的文件夹。
目录结构：
- .codebuddy/rules/
- coding-style/
- RULE.mdc
- api-design/
- RULE.mdc
- coding-style/
YAML Frontmatter 字段：
- description: 规则描述，决定 AI 何时使用
- alwaysApply: 是否总是加载
- enabled: 是否启用
3.2 三种规则类型
| 类型 | 描述 | 加载方式 |
|---|---|---|
| always | 总是加载 | 每次会话自动加载 |
| agent_requested | AI判断需要时加载 | 只加载描述，需要时读取全文 |
| manual | 手动触发 | 通过 @rule-name 触发 |
3. Rules 文件格式
3.1 文件格式说明
规则文件使用 格式（Markdown with frontmatter），每条规则对应一个包含 文件的文件夹。
目录结构：
文件格式示例：
3.2 YAML Frontmatter 字段
| 字段 | 说明 | 必需 |
|---|---|---|
| description | 规则描述，决定 AI 何时使用 | 是 |
| alwaysApply | 是否总是加载 | 否 |
| enabled | 是否启用 | 否 |
| updatedAt | 更新时间 | 否 |
3.3 三种规则类型
| 类型 | 描述 | 加载方式 |
|---|---|---|
| always | 总是加载 | 每次会话自动加载 |
| agent_requested | AI判断需要时加载 | 只加载描述，需要时读取全文 |
| manual | 手动触发 | 通过 @rule-name 触发 |
4. Rules 编写最佳实践
3.1 简洁明确
不推荐：
请在写代码的时候注意一下代码风格，尽量写得好看一点，
变量名要有意义，不要用太短的名字...
推荐：
- 变量名使用描述性名称，最少 3 个字符
- 函数名以动词开头：getData, setUser, handleSubmit
- 布尔变量以 is/has/can 开头：isLoading, hasError, canEdit
3.2 优先级排序
# 优先级：安全 > 性能 > 可读性 > 简洁
## 安全规则（必须遵守）
- 所有用户输入必须验证和清洗
- SQL 查询必须使用参数化
- 敏感数据必须加密存储
## 性能规则（尽量遵守）
- 列表渲染使用虚拟滚动
- 大型数据使用分页
- 图片使用懒加载
## 代码风格（建议遵守）
- 函数不超过 50 行
- 文件不超过 300 行
3.3 示例驱动
# API 响应格式
## 正确示例
```json
{
"code": 0,
"message": "success",
"data": { "id": 1, "name": "John" }
}
错误示例
{
"status": "ok",
"result": { "id": 1 }
}
---
## 4. 完整的项目规则示例
以下是一个完整的企业级项目规则配置：
```markdown
---
type: always
---
# 项目编码规范
## 目录结构
- src/app/ - Next.js App Router 页面
- src/components/ - 可复用组件
- src/lib/ - 工具函数和配置
- src/types/ - TypeScript 类型定义
- src/hooks/ - 自定义 React Hooks
- src/services/ - API 服务层
- prisma/ - 数据库 Schema 和迁移
## 组件规范
- 每个组件一个文件
- 组件文件使用 PascalCase
- Props 使用 interface 定义
- 导出使用 named export（不用 default export）
## API 规范
- 使用 Route Handlers (app/api/)
- 请求体使用 Zod 验证
- 响应使用统一格式
- 错误使用 HTTP 状态码
## 测试规范
- 单元测试：*.test.ts
- 集成测试：*.integration.test.ts
- 测试覆盖率 > 80%
5. 常见陷阱
陷阱 1：Rules 不是万能的
现象：定义了 Rules，AI 仍然偶尔违反
原因：Rules 是指导而非硬约束，复杂场景 AI 可能遗漏
解决：关键规则通过 Hooks 强制执行（如 PreCommit 检查）
陷阱 2：过多的 Rules 会消耗 Token
现象：定义了 50+ 条规则，每次对话 Token 消耗很大
解决：只定义真正重要的规则，使用 manual 类型加载不常用的规则
陷阱 3：Rules 需要定期更新
现象：项目演进后，Rules 与实际代码不一致
解决：每次重大技术变更后，同步更新 Rules 文件
总结
| 概念 | 说明 |
|---|---|
| 用户规则 | 个人偏好，跨项目生效 |
| 项目规则 | 团队规范，当前项目生效 |
| Always 加载 | 始终生效的核心规范 |
| Agent 加载 | 仅智能体模式生效 |
| Manual 加载 | 手动触发的详细指南 |
下一章预告：我们将学习 Skills 技能系统，了解如何为 AI 配备专业领域的知识和能力。