# 利用规则增加新的规则

## 1. 概述

### 1.1 为什么需要创建新规则

虽然 Jarvis 内置了丰富的规则集，但在实际开发中，你可能需要：

- **项目特定规范**：为项目创建专属的编码规范
- **团队最佳实践**：将团队积累的最佳实践文档化
- **技术栈规范**：为特定技术栈创建使用规范
- **业务逻辑约束**：定义业务相关的代码约束

### 1.2 使用规则创建规则的优势

Jarvis 提供了 `add_rule.md` 规则，可以指导 Agent 自动创建规则文件，具有以下优势：

- **标准化流程**：遵循统一的规则创建流程
- **格式规范**：自动生成符合规范的规则文件格式
- **减少错误**：避免手动创建时的格式错误
- **快速创建**：通过自然语言描述快速创建规则

---

## 2. 快速创建规则

### 2.1 使用规则创建规则

最简单的方式是直接使用规则，让 Agent 帮你创建规则：

```bash
# 方式 1：在命令行中使用规则
jca --rule-names add_rule "创建 Python API 开发规范规则"

# 方式 2：在交互式会话中使用规则
jca
> '<rule:add_rule>' 创建 Python API 开发规范规则
```

### 2.2 规则创建流程

Agent 会根据规则自动执行以下步骤：

1. **需求分析**
   - 理解规则的目标和用途
   - 确定规则的分类和位置
   - 规划规则的结构和内容

2. **规则文件创建**
   - 选择合适的规则文件位置
   - 创建符合规范的规则文件
   - 生成规则的基本结构

3. **规则内容编写**
   - 编写规则的核心原则
   - 添加详细的规范说明
   - 提供代码示例和检查清单

4. **规则注册**
   - 在相应的规则索引文件中注册新规则
   - 更新规则列表文档

---

## 3. 创建不同类型的规则

### 3.1 创建项目规则

项目规则存储在项目目录的 `.jarvis/rules/` 下，仅适用于当前项目：

```bash
jca --rule-names add_rule "
创建项目规则：Python API 开发规范

规则要求：
1. 所有 API 必须返回统一格式：{'code': 0, 'data': {...}, 'msg': ''}
2. 必须使用 Pydantic 进行数据验证
3. 必须添加 API 文档注释
4. 错误处理必须使用统一的异常类
"
```

Agent 会自动创建：

```
项目根目录/.jarvis/rules/python_api_standard.md
```

### 3.2 创建全局规则

全局规则存储在 `~/.jarvis/rules/` 下，适用于所有项目：

```bash
jca --rule-names add_rule "
创建全局规则：个人 Python 编码规范

规则要求：
1. 必须使用类型注解
2. 必须使用 f-strings 进行字符串格式化
3. 禁止使用 print()，必须使用 logging
4. 函数长度不超过 50 行
"
```

Agent 会自动创建：

```
~/.jarvis/rules/personal_python_style.md
```

### 3.3 创建内置规则

如果需要创建内置规则（添加到 `builtin/rules/` 目录），需要使用 `add_builtin_rule.md` 规则：

```bash
jca --rule-names add_builtin_rule "
创建内置规则：TypeScript 最佳实践

规则分类：code_quality
规则要求：
1. 必须使用 TypeScript 严格模式
2. 必须使用接口而非类型别名（除非需要联合类型）
3. 必须使用 async/await 而非 Promise.then
4. 必须使用 const 而非 let（除非需要重新赋值）
"
```

---

## 4. 规则创建示例

### 示例 1：创建项目特定的 API 规范

```bash
jca --rule-names add_rule "
创建项目规则：REST API 开发规范

规则文件：.jarvis/rules/rest_api_standard.md

规则内容：

## 核心原则

### 1. 统一响应格式
- 所有 API 必须返回统一格式：
  {
    'code': 0,      # 0 表示成功，非 0 表示错误
    'data': {...},  # 响应数据
    'msg': ''       # 错误消息（成功时为空）
  }

### 2. HTTP 状态码
- 200：请求成功
- 400：请求参数错误
- 401：未授权
- 403：禁止访问
- 404：资源不存在
- 500：服务器内部错误

### 3. 错误处理
- 必须使用统一的异常类：APIException
- 异常必须包含错误码和错误消息
- 必须记录错误日志

### 4. 数据验证
- 必须使用 Pydantic 进行请求数据验证
- 必须验证所有必填字段
- 必须验证数据类型和格式

## 代码示例

### ✅ 好的实践

```python
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel

router = APIRouter()

class UserCreateRequest(BaseModel):
    username: str
    email: str
    password: str

@router.post('/users')
async def create_user(request: UserCreateRequest):
    try:
        user = create_user_service(request)
        return {'code': 0, 'data': user, 'msg': ''}
    except ValidationError as e:
        raise HTTPException(status_code=400, detail=str(e))
```

### ❌ 不好的实践

```python
@router.post('/users')
def create_user(data: dict):
    user = create_user(data)  # 没有验证
    return user  # 格式不统一
```

## 检查清单

在创建 API 前，必须确认：

- [ ] 响应格式符合统一规范
- [ ] HTTP 状态码使用正确
- [ ] 错误处理使用统一异常类
- [ ] 请求数据使用 Pydantic 验证
- [ ] 添加了 API 文档注释
"

```

### 示例 2：创建技术栈特定规范

```bash
jca --rule-names add_rule "
创建全局规则：React Hooks 使用规范

规则文件：~/.jarvis/rules/react_hooks_guide.md

规则内容：

## React Hooks 使用规范

### 1. useState 使用
- 必须为每个状态使用独立的 useState
- 复杂状态使用 useReducer
- 避免在循环中使用 useState

### 2. useEffect 使用
- 必须指定依赖数组
- 清理函数必须返回清理函数
- 避免在 useEffect 中执行副作用

### 3. 自定义 Hooks
- 必须以 'use' 开头命名
- 必须返回对象或数组
- 必须处理边界情况

## 检查清单

- [ ] 所有 Hooks 以 'use' 开头
- [ ] useEffect 有正确的依赖数组
- [ ] 自定义 Hooks 有清晰的文档
"
```

### 示例 3：创建业务逻辑约束规则

```bash
jca --rule-names add_rule "
创建项目规则：订单业务逻辑约束

规则文件：.jarvis/rules/order_business_rules.md

规则内容：

## 订单业务逻辑约束

### 1. 订单状态流转
- 订单状态必须按照：待支付 -> 已支付 -> 已发货 -> 已完成
- 禁止跳过中间状态
- 已取消的订单不能再次激活

### 2. 库存检查
- 创建订单前必须检查库存
- 库存不足时必须返回明确错误
- 扣减库存必须在事务中执行

### 3. 价格计算
- 必须使用订单创建时的价格
- 价格变更不影响已创建的订单
- 必须记录价格变更历史

## 检查清单

- [ ] 订单状态流转符合规范
- [ ] 库存检查逻辑正确
- [ ] 价格计算逻辑正确
- [ ] 事务处理正确
"
```

---

## 5. 规则文件结构规范

### 5.1 基本结构

Agent 会根据 `add_rule.md` 规则自动生成符合规范的规则文件结构：

```markdown
# 规则标题

## 引言/背景

简要说明规则的用途和适用场景。

## 核心原则

### 原则名称

**执行要求：**

- **必须**：强制要求
- **禁止**：禁止行为

## 详细规范

### 子章节

**检查项：**

- [ ] 检查点 1
- [ ] 检查点 2

## 代码示例

### ❌ 不好的实践

```language
# 错误示例代码
```

### ✅ 好的实践

```language
# 正确示例代码
```

## 检查清单

在完成任务前，你必须确认：

- [ ] 检查项 1
- [ ] 检查项 2

```

### 5.2 格式要求

Agent 会自动确保规则文件符合以下格式要求：

1. **标题层级**：使用 `##` 作为顶级章节，`###` 作为子章节
2. **强调标记**：
   - **必须**：强制要求，使用粗体
   - **禁止**：禁止行为，使用粗体
   - 建议：推荐做法，使用粗体
3. **检查清单**：使用 `- [ ]` 格式
4. **代码示例**：使用明确的标题区分好/坏实践

---

## 6. 规则注册

### 6.1 项目规则注册

项目规则创建后，Agent 会自动在项目规则索引中注册（如果有的话）。

### 6.2 全局规则注册

全局规则创建后，Agent 会自动在全局规则索引中注册。

---

## 7. 规则使用

### 7.1 使用项目规则

```bash
# 使用项目规则
jca --rule-names python_api_standard "创建用户 API"
```

### 7.2 使用全局规则

```bash
# 全局规则会自动加载，也可以通过名称引用
jca --rule-names personal_python_style "创建新的 Python 模块"
```

---

## 8. 规则维护

### 8.1 更新规则

如果需要更新已有规则，可以直接编辑规则文件，或使用 Agent：

```bash
jca --rule-names add_rule "
更新规则：python_api_standard.md

更新内容：
- 添加新的要求：所有 API 必须支持版本控制
- 修改错误处理要求：使用新的异常类
"
```

### 8.2 删除规则

```bash
jca "删除规则文件：.jarvis/rules/old_rule.md，并从规则索引中移除"
```

### 8.3 规则版本管理

建议将规则文件纳入版本控制：

```bash
# 项目规则应该提交到项目仓库
git add .jarvis/rules/
git commit -m "添加项目规则：python_api_standard"

# 全局规则可以单独管理
cd ~/.jarvis
git add rules/
git commit -m "更新全局规则"
```

---

## 9. 最佳实践

### 9.1 规则创建最佳实践

1. **明确目标**：在创建规则前明确规则的目标和用途
2. **详细描述**：提供详细的需求描述，帮助 Agent 理解意图
3. **结构清晰**：使用清晰的结构组织规则内容
4. **示例丰富**：提供丰富的代码示例说明规则
5. **可验证性**：确保规则是可验证的，Agent 能够检查

### 9.2 规则命名最佳实践

1. **描述性**：使用描述性的文件名
2. **一致性**：同类规则使用相同的前缀
3. **小写字母**：使用小写字母和下划线
4. **避免冲突**：避免与内置规则名称冲突

### 9.3 规则组织最佳实践

1. **分类存储**：按功能分类存储规则文件
2. **文档同步**：及时更新规则文档
3. **团队共享**：将项目规则提交到版本控制
4. **定期审查**：定期审查和更新规则
