# 规则使用最佳实践

## 1. 概述

本文档总结了 Jarvis 规则系统的最佳使用实践，帮助开发者高效、正确地使用规则系统，提高代码质量和开发效率。

---

## 2. 规则选择策略

### 2.1 根据任务类型选择规则

不同的任务类型应该使用不同的规则组合：

| 任务类型 | 推荐规则 | 说明 |
|---------|---------|------|
| **代码生成** | `clean_code`, `security` | 确保代码质量和安全性 |
| **代码重构** | `refactoring`, `clean_code` | 遵循重构原则和代码规范 |
| **API 开发** | `clean_code`, `security`, `documentation` | API 需要文档和安全考虑 |
| **性能优化** | `performance`, `rust_performance`（如适用） | 专注于性能优化 |
| **测试编写** | `tdd`, `python_test`（或对应语言） | 测试驱动开发和测试规范 |
| **架构设计** | `clean_architecture`, `solid` | 架构设计原则 |
| **安全审计** | `security`, `vulnerability-analysis` | 安全相关任务 |

### 2.2 规则组合原则

1. **核心规则优先**：先选择核心规则（如 `clean_code`），再添加特定规则
2. **避免冲突**：注意规则之间的冲突，后加载的规则会覆盖先加载的规则
3. **适度使用**：不要一次性加载过多规则，3-5 个规则通常足够
4. **项目规则优先**：项目特定规则应该优先于通用规则

### 2.3 规则优先级理解

理解规则加载优先级，合理组织规则：

```
优先级从高到低：
1. 中心规则仓库
2. 项目规则目录（.jarvis/rules/）
3. 配置的规则目录
4. 全局规则目录（~/.jarvis/rules/）
5. 内置规则（builtin/rules/）
```

---

## 3. 规则使用方式

### 3.1 命令行参数方式

**适用场景**：脚本、CI/CD、一次性任务

```bash
# 单个规则
jca --rule-names clean_code "创建用户模块"

# 多个规则
jca --rule-names clean_code,security,performance "创建 API"

# 项目规则 + 内置规则
jca --rule-names my_project_rule,clean_code "创建功能"
```

**优点**：

- 明确指定规则
- 适合自动化场景
- 可重复执行

**缺点**：

- 需要记住规则名称
- 命令行可能很长

### 3.2 项目规则文件方式

**适用场景**：项目固定的编码规范

**推荐方式**：使用 `add_rule` 规则自动创建，而不是手写。

**手动创建**（不推荐）：
创建 `.jarvis/rule` 文件：

```markdown
# 项目规则

你必须遵守以下原则：

- 代码必须符合 PEP 8 规范
- 所有公共函数必须有类型注解
- 必须编写单元测试
```

**优点**：

- 自动加载，无需每次指定
- 团队共享，统一规范
- 版本控制，可追踪变更

**缺点**：

- 仅适用于当前项目
- 可能影响所有任务

### 3.3 全局规则文件方式

**适用场景**：个人通用编码规范

**推荐方式**：使用 `add_rule` 规则自动创建，而不是手写。

**手动创建**（不推荐）：
创建 `~/.jarvis/rule` 文件：

```markdown
# 全局规则

使用 Python 编写代码时：

- 必须使用 f-strings 进行字符串格式化
- 禁止使用 print() 语句（使用 logging 模块）
```

**优点**：

- 所有项目生效
- 个人偏好统一

**缺点**：

- 可能不适合所有项目
- 需要谨慎使用

### 3.4 @ 交互式方式

**适用场景**：交互式开发、临时需求

在交互式会话中输入 `@` 触发规则补全：

```
> @clean_code @security 创建用户认证模块
```

**优点**：

- 快速选择
- 支持搜索
- 灵活组合

**缺点**：

- 仅交互模式可用
- 需要手动输入

---

## 4. 规则组织最佳实践

### 4.1 项目规则组织

**推荐结构**：

```
项目根目录/
├── .jarvis/
│   ├── rule                    # 项目规则文件（自动加载）
│   └── rules/                  # 项目规则目录
│       ├── api/
│       │   └── rest_api_standard.md
│       ├── database/
│       │   └── db_migration_guide.md
│       └── testing/
│           └── test_standards.md
```

**组织原则**：

1. 按功能模块分类
2. 使用描述性目录名
3. 保持结构清晰
4. 及时更新文档

### 4.2 全局规则组织

**推荐结构**：

```
~/.jarvis/
├── rule                        # 全局规则文件（自动加载）
└── rules/                      # 全局规则目录
    ├── python/
    │   └── python_style_guide.md
    ├── javascript/
    │   └── js_best_practices.md
    └── general/
        └── code_review_checklist.md
```

### 4.3 规则命名规范

**文件命名**：

- ✅ 使用小写字母：`python_api_standard.md`
- ✅ 使用下划线分隔：`rest_api_guide.md`
- ❌ 避免空格：`python api standard.md`
- ❌ 避免连字符：`python-api-standard.md`
- ❌ 避免大写：`PythonApiStandard.md`

**规则名称**（用于 `--rule-names`）：

- 文件名去掉 `.md` 后缀
- 例如：`python_api_standard.md` → `python_api_standard`

---

## 5. 规则编写最佳实践

**推荐方式**：使用 `add_rule` 规则自动生成或引入规则，而不是手写。`add_rule` 本身也是一个规则，它会指导 Agent 按照最佳实践创建规则文件，确保规则格式正确、结构清晰。

**使用方式**：

```bash
# 使用 add_rule 规则创建新规则
jca --rule-names add_rule "创建 Python API 开发规范规则"

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

### 5.1 明确性原则

**要求**：使用清晰、无歧义的语言

**❌ 不好的写法**：

```markdown
函数应该尽可能短一些
```

**✅ 好的写法**：

```markdown
**必须**：函数长度不超过 20 行
```

### 5.2 可操作性原则

**要求**：每条规则都应该是可验证的

**❌ 不好的写法**：

```markdown
代码应该高效
```

**✅ 好的写法**：

```markdown
**性能要求：**
- 数据库查询必须使用索引
- 避免 N+1 查询问题
- 批量操作必须使用批量 API
```

### 5.3 结构化原则

**要求**：按照逻辑层次组织内容

**推荐结构**：

1. 引言/背景
2. 核心原则（最高优先级）
3. 具体规范
4. 代码示例
5. 检查清单

### 5.4 示例驱动

**要求**：每条关键规范都应配有示例

```markdown
## 代码示例

### ❌ 不好的实践

```python
def process_data(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result
```

### ✅ 好的实践

```python
def process_data(data: List[int]) -> List[int]:
    """处理数据，将每个元素乘以 2"""
    return [item * 2 for item in data]
```

```

---

## 6. 规则使用场景示例

### 场景 1：新项目初始化

**目标**：为新项目建立编码规范

**推荐方式**：使用 `add_rule` 规则自动创建项目规则。`add_rule` 本身也是一个规则，通过 `jca --rule-names add_rule` 来使用。

**步骤**：

1. 使用 `add_rule` 创建项目规则文件
2. 根据需要创建规则目录并添加更多规则文件
3. 提交到版本控制

**示例**：

```bash
# 使用 add_rule 创建项目规则文件
jca --rule-names add_rule "创建项目编码规范，包括：
- 代码必须符合 PEP 8 规范
- 所有公共函数必须有类型注解
- 必须编写单元测试
- API 必须返回统一格式"

# 使用 add_rule 创建规则目录中的规则文件
jca --rule-names add_rule "在 .jarvis/rules/api/ 目录下创建 REST API 规范规则"
jca --rule-names add_rule "在 .jarvis/rules/database/ 目录下创建数据库迁移指南规则"

# 提交到版本控制
git add .jarvis/
git commit -m "添加项目编码规范"
```

**手动创建方式**（不推荐）：

```bash
# 手动创建项目规则（不推荐）
cat > .jarvis/rule << 'EOF'
# 项目编码规范

- 代码必须符合 PEP 8 规范
- 所有公共函数必须有类型注解
- 必须编写单元测试
- API 必须返回统一格式
EOF

# 创建规则目录
mkdir -p .jarvis/rules/{api,database,testing}

# 提交到版本控制
git add .jarvis/
git commit -m "添加项目编码规范"
```

### 场景 2：代码审查

**目标**：使用规则指导代码审查

**步骤**：

1. 使用代码审查规则
2. 结合项目特定规则
3. 生成审查报告

**示例**：

```bash
jca --rule-names code_review,my_project_rule "
审查以下代码文件：
- src/api/users.py
- src/models/user.py
- src/services/user_service.py

重点关注：
1. 代码风格一致性
2. 安全漏洞
3. 性能问题
4. 测试覆盖率
"
```

### 场景 3：重构任务

**目标**：使用规则指导重构

**步骤**：

1. 使用重构规则
2. 结合代码质量规则
3. 逐步重构

**示例**：

```bash
jca --rule-names refactoring,clean_code "
重构用户认证模块：
1. 提取认证逻辑到独立服务类
2. 实现依赖注入
3. 添加单元测试
4. 更新文档
"
```

### 场景 4：性能优化

**目标**：使用规则指导性能优化

**步骤**：

1. 使用性能优化规则
2. 分析性能瓶颈
3. 应用优化策略

**示例**：

```bash
jca --rule-names performance,rust_performance "
优化订单查询性能：
1. 分析当前查询性能
2. 添加必要的数据库索引
3. 优化查询逻辑
4. 添加性能测试
"
```

---

## 7. 规则维护最佳实践

### 7.1 定期审查

**建议**：每季度审查一次规则

**审查内容**：

1. 规则是否仍然适用
2. 是否有新的最佳实践需要添加
3. 是否有过时的规则需要删除
4. 规则之间是否有冲突

### 7.2 版本控制

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

**项目规则**：

```bash
# 提交项目规则
git add .jarvis/rules/
git commit -m "更新项目规则：添加 API 规范"
```

**全局规则**：

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

### 7.3 团队协作

**建议**：建立规则管理流程

1. **规则提案**：团队成员可以提案新规则
2. **规则审查**：团队审查规则提案
3. **规则发布**：审查通过后发布规则
4. **规则更新**：定期更新规则

### 7.4 文档同步

**建议**：保持规则文档同步

1. 规则变更时更新文档
2. 提供规则使用示例
3. 记录规则变更历史

---

## 8. 性能优化建议

### 8.1 规则文件大小

**建议**：

- 单个规则文件不超过 10KB
- 避免在规则中包含大量代码示例
- 使用链接引用外部资源

### 8.2 规则加载优化

**建议**：

1. 只加载必要的规则
2. 避免加载过多规则（建议 3-5 个）
3. 使用项目规则文件而非每次指定

### 8.3 规则缓存

**说明**：Jarvis 会自动缓存规则内容，但规则文件变更后需要重启 Jarvis。

---

## 9. 总结

### 9.1 核心原则

1. **明确目标**：根据任务类型选择合适的规则
2. **适度使用**：不要一次性加载过多规则
3. **组织清晰**：按功能模块组织规则文件
4. **定期维护**：定期审查和更新规则
5. **团队共享**：将规则纳入版本控制，团队共享

### 9.2 推荐实践

1. **项目规则**：为项目创建专属规则文件
2. **规则组合**：根据任务类型组合使用多个规则
3. **规则优先级**：理解规则加载优先级，避免冲突
4. **规则维护**：定期审查和更新规则，保持最佳实践
