# 新增规则规范

## 规则文件基本要求

### 规则类型选择

在创建规则之前，**必须**明确规则的适用范围：

**全局规则 vs 项目规则：**

- **全局规则**：
  - 适用范围：所有项目通用的规则，适用于整个 Jarvis 系统
  - 存放位置：`{{ jarvis_data_dir }}/rules/` 目录下
  - 典型场景：通用编码规范、安全标准、性能优化策略等

- **项目规则**：
  - 适用范围：仅适用于当前项目的特定规则
  - 存放位置：`{{ git_root_dir }}/.jarvis/rules/` 目录下
  - 典型场景：项目特定的架构规范、开发流程、工具配置等

**选择原则：**

1. **通用性优先**：如果规则在多个项目中都能使用，应创建为全局规则
2. **项目特性优先**：如果规则仅针对当前项目的特殊需求，应创建为项目规则
3. **维护便利**：全局规则需要跨项目维护，修改时需考虑对所有项目的影响
4. **权限考虑**：全局规则通常需要更高的权限级别

**操作流程：**

1. 确定规则类型（全局规则或项目规则）
2. 根据类型选择对应的文件位置（见下方章节）
3. 创建规则文件
4. **询问用户是否需要注册到索引**（见"规则注册"章节）
5. 如果用户确认注册，按照对应的注册流程进行注册

### 1. 文件位置（必须遵守）

#### 1.1 项目规则文件位置

**位置规范：**

- **必须**：项目规则文件应放置在项目的 `.jarvis/rules/` 目录下的对应分类子目录中

**文件路径：**

```text
{{ git_root_dir }}/.jarvis/rules/<category>/<rule_name>.md
```

**分类说明：**

- `<category>`：规则分类，建议使用描述性目录名称
- **可选参考分类**（非强制限制）：
  - `architecture_design`（架构设计）
  - `code_quality`（代码质量）
  - `deployment`（部署规范）
  - `development_tools`（开发工具）
  - `development_workflow`（开发流程）
  - `performance`（性能优化）
  - `security`（安全规范）
  - `tool_config`（工具配置）
  - `ui_design`（UI 设计）
- **可以创建新的分类目录**，根据项目实际需求组织规则
- 详细的分类选择指南请参考本文档末尾的「规则分类指南」章节

#### 1.2 全局规则文件位置

**位置规范：**

- **必须**：全局规则文件应放置在 Jarvis 数据目录的 `rules/` 目录下

**文件路径：**

```text
{{ jarvis_data_dir }}/rules/<rule_name>.md
```

或按分类组织：

```text
{{ jarvis_data_dir }}/rules/<category>/<rule_name>.md
```

**路径说明：**

- `{{ jarvis_data_dir }}`：Jarvis 数据目录，通常为 `~/.jarvis` 或用户配置的数据目录
- 全局规则文件可以放置在 `rules/` 根目录下，也可以按分类创建子目录
- 建议全局规则也按照与项目规则相同的分类体系组织，便于统一管理

### 规则注册（必须遵守）

#### 重要提示：注册前询问用户

- **必须**：在将规则注册到索引之前，**必须先询问用户是否需要注册**
- **原因**：有些规则可能不需要注册到索引中（如临时规则、特定场景规则、内部工具规则等）
- **询问方式**：明确告知用户规则已创建，询问是否要将其注册到规则索引中
- **用户选择**：
  - 如果用户选择注册：按照下方要求进行注册
  - 如果用户选择不注册：规则文件仍然存在，可以通过 `load_rule` 工具直接加载使用

**位置规范：**

- **项目规则列表位置：** `{{ git_root_dir }}/.jarvis/rule`
- **全局规则列表位置：** `{{ jarvis_data_dir }}/rule`

**注册要求：**

**项目规则注册：**

- **必须**：按照 `{{ git_root_dir }}/.jarvis/rule` 的格式添加规则条目
- **必须**：提供规则的简短描述和文件路径
- **必须**：将规则添加到合适的分类下（如架构设计、开发流程、代码质量等）

**全局规则注册：**

- **必须**：在全局规则列表中添加规则条目
- **必须**：提供规则的简短描述和文件路径
- **必须**：明确标注为全局规则

**注册示例：**

**项目规则注册示例：**

```markdown
### 规则名称

规则简短描述。（{{ git_root_dir }}/.jarvis/rules/<rule_name>.md）
```

**全局规则注册示例：**

```markdown
### 规则名称 [全局]

规则简短描述。（{{ jarvis_data_dir }}/rules/<rule_name>.md）
```

### 2. 文件命名规范（必须遵守）

**命名规则：**

- **必须**：使用小写字母
- **必须**：使用下划线 `_` 分隔单词
- **必须**：使用 `.md` 后缀
- **禁止**：使用空格、连字符 `-` 或大写字母

**命名示例：**

- ✅ 正确：`code_review.md`, `tdd.md`, `security.md`
- ❌ 错误：`CodeReview.md`, `code-review.md`, `CODE_REVIEW.md`

**命名建议：**

- 使用简短、描述性的名称
- 反映规则的核心用途
- 避免过于通用的名称（如 `rule.md`）

### 3. 规则分类（必须遵守）

**分类体系：**

规则文件应放置在合适的分类子目录中。建议根据规则的主题和应用场景创建描述性的分类目录。以下是常见的分类参考（**非强制限制，可根据需要创建新分类**）：

- **architecture_design**（架构设计）：
  - 设计模式、架构原则、代码组织结构等
  - 例如：SOLID 原则、整洁架构、架构图生成器

- **code_quality**（代码质量）：
  - 代码规范、审查标准、文档要求等
  - 例如：代码审查、文档编写、重构检查

- **deployment**（部署规范）：
  - 部署流程、发布规范、环境配置等
  - 例如：开源部署、版本发布

- **development_tools**（开发工具）：
  - 开发工具使用、脚本生成、工具配置等
  - 例如：脚本生成专家

- **development_workflow**（开发流程）：
  - 开发方法论、工作流程、协作流程等
  - 例如：TDD、SDD、重构流程

- **performance**（性能优化）：
  - 性能分析、优化策略、资源管理等
  - 例如：性能优化、Rust 性能优化

- **security**（安全规范）：
  - 安全编码、漏洞分析、安全测试等
  - 例如：安全编码、安全漏洞分析

- **tool_config**（工具配置）：
  - 工具配置、规则管理等
  - 例如：新增规则规范、忽略告警

- **ui_design**（UI 设计）：
  - 界面设计规范、主题配置等
  - 例如：iOS 暗色/亮色主题

**分类选择原则：**

1. **单一职责**：每个规则只属于一个分类
2. **核心主题**：选择规则最核心的主题对应的分类
3. **避免歧义**：如果规则涉及多个领域，选择最主要的应用场景
4. **参考现有**：优先参考 `builtin_rules.md` 中同类规则所在的分类

**示例：**

- ✅ `code_review.md` → `code_quality/`（核心是代码质量审查）
- ✅ `sdd.md` → `development_workflow/`（核心是开发流程）
- ✅ `security.md` → `security/`（核心是安全规范）

### 4. 文件格式要求（必须遵守）

**Markdown 格式：**

- **必须**：使用 Markdown 格式
- **必须**：使用 UTF-8 编码
- **必须**：使用 LF 换行符（Unix 风格）

**结构要求：**

```markdown
# 规则标题

## 简介/背景

（可选）简要说明规则的用途和背景

## 你必须遵守的原则

（必需）规则的核心原则

### 具体要求1

**要求说明：**

- **必须**：具体要求
- **禁止**：禁止事项

## 你必须执行的操作

（必需）具体的执行步骤或规范

## 检查清单

（可选）完成后的验证项

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

### 4. 内容编写要求（必须遵守）

**语言风格：**

- **必须**：使用清晰、简洁的语言
- **必须**：使用肯定式表述（"必须"、"禁止"）
- **必须**：避免模糊的表达

**结构化要求：**

- 使用分级标题组织内容（`#`、`##`、`###`）
- 使用列表罗列要求（`-` 或 `1.`）
- 使用代码块提供示例
- 使用加粗强调关键词（`**必须**`、`**禁止**`）

**完整性要求：**

- 说明规则的适用场景
- 提供具体的示例代码
- 列出必须遵守的要求
- 列出禁止的事项
- 提供验证或检查清单

## Jinja2 变量使用指南

### 可用的内置变量

规则文件中可以使用以下 Jinja2 模板变量：

| 变量名                                       | 说明                 | 示例值                   |
| -------------------------------------------- | -------------------- | ------------------------ |
| `{% raw %}{{ rule_file_dir }}{% endraw %}`   | 当前规则文件所在目录 | `/path/to/builtin/rules` |
| `{% raw %}{{ git_root_dir }}{% endraw %}`    | Git 仓库根目录       | `/home/user/project`     |
| `{% raw %}{{ current_dir }}{% endraw %}`     | 当前工作目录         | `/home/user/project/src` |
| `{% raw %}{{ jarvis_src_dir }}{% endraw %}`  | Jarvis 源码目录      | `/home/user/jarvis`      |
| `{% raw %}{{ jarvis_data_dir }}{% endraw %}` | Jarvis 数据目录      | `/home/user/.jarvis`     |

### 使用原则

- **必须**：尽量使用 jinja2 变量替代绝对路径
- **必须**：优先使用合适的内置变量（如 `{% raw %}{{ git_root_dir }}{% endraw %}`、`{% raw %}{{ jarvis_data_dir }}{% endraw %}` 等）
- **禁止**：在规则文件中硬编码绝对路径（如 `/home/user/project`）
- **禁止**：使用相对路径（如 `../rules/`）而不用变量

**最佳实践：**

- 项目路径使用 `{% raw %}{{ git_root_dir }}{% endraw %}`
- 数据目录使用 `{% raw %}{{ jarvis_data_dir }}{% endraw %}`
- 当前规则目录使用 `{% raw %}{{ rule_file_dir }}{% endraw %}`

### 变量使用示例

#### 示例 1：引用其他规则文件

```markdown
### 相关规则

- 参考代码审查规则：`{% raw %}{{ rule_file_dir }}{% endraw %}/../code_quality/code_review.md`
- 参考安全规则：`{% raw %}{{ rule_file_dir }}{% endraw %}/../security/security.md`
```

#### 示例 2：指定项目路径

```markdown
### 文件放置位置

**测试文件必须放置在：**

- `{% raw %}{{ git_root_dir }}{% endraw %}/tests/`
- `{% raw %}{{ git_root_dir }}{% endraw %}/src/{% raw %}{{ module_name }}{% endraw %}/tests/`
```

#### 示例 3：使用条件逻辑

```markdown
{% if git_root_dir == current_dir %}
**注意**：当前在项目根目录
{% else %}
**注意**：当前在子目录中
{% endif %}
```

## 规则模板

以下是一个完整的规则文件模板，可直接复制使用：

````markdown
# [规则名称]

## 规则简介

简要描述规则的用途、适用场景和预期效果。

## 你必须遵守的原则

### 1. 原则名称

**要求说明：**

- **必须**：具体要求1
- **必须**：具体要求2
- **禁止**：禁止事项

**示例：**

    ```python
    # 示例代码
    def example():
        pass
    ```

## 你必须执行的操作

### 操作1：操作名称

**执行步骤：**

1. 步骤1
2. 步骤2
3. 步骤3

**注意事项：**

- 注意事项1
- 注意事项2

## 检查清单

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

- [ ] 规则文件已创建在 `{% raw %}{{ git_root_dir }}{% endraw %}/.jarvis/rules/` 目录
- [ ] 已询问用户是否需要将规则注册到索引
- [ ] 如果用户选择注册，规则已注册到 `{% raw %}{{ git_root_dir }}{% endraw %}/.jarvis/rule` 文件
- [ ] 如果已注册，规则注册格式符合规范

## 相关资源

- 参考文档：`related_rule.md`
````

## 最佳实践

### 1. 规则设计原则

- **单一职责**：每个规则只关注一个主题
- **可操作性**：规则必须具体、可执行
- **可验证**：规则结果必须可检查
- **简洁明了**：避免冗长和重复

### 2. 常见错误

- ❌ **规则过于抽象**："代码要写得好看"
- ✅ **规则具体明确**："函数长度不超过 50 行"

- ❌ **规则相互冲突**：规则 A 要求 X，规则 B 要求非 X
- ✅ **规则协调一致**：相关规则应相互补充

- ❌ **缺少示例**：只有文字描述，没有示例代码
- ✅ **提供示例**：包含正面和反面的示例

### 3. 规则维护

- 定期审查规则的适用性
- 根据项目发展更新规则
- 删除过时或不再使用的规则
- 记录规则变更历史

## 附录：规则分类指南

### 分类决策树

以下决策树可以帮助您快速确定规则应该属于哪个分类：

```text
开始
  │
  ├─ 是否关于系统架构、设计模式或代码组织？
  │   └─ 是 → architecture_design
  │
  ├─ 是否关于代码质量、代码规范或审查？
  │   └─ 是 → code_quality
  │
  ├─ 是否关于安全编码、漏洞分析或安全测试？
  │   └─ 是 → security
  │
  ├─ 是否关于性能分析、优化或资源管理？
  │   └─ 是 → performance
  │
  ├─ 是否关于部署、发布或环境配置？
  │   └─ 是 → deployment
  │
  ├─ 是否关于开发方法论、工作流程或协作流程？
  │   └─ 是 → development_workflow
  │
  ├─ 是否关于开发工具使用、脚本生成或工具配置？
  │   └─ 是 → development_tools
  │
  ├─ 是否关于工具配置、规则管理等？
  │   └─ 是 → tool_config
  │
  └─ 是否关于 UI 设计、界面规范或主题配置？
      └─ 是 → ui_design
```

### 分类详细说明

#### 1. architecture_design（架构设计）

**适用场景：**

- 系统架构设计原则和方法
- 设计模式的应用
- 代码组织和模块化设计
- 架构图生成和维护
- 整洁架构、整洁代码等设计理念

**典型规则示例：**

- SOLID 设计原则
- 整洁架构规范
- 代码反向设计规范
- 架构图生成器配置

#### 2. code_quality（代码质量）

**适用场景：**

- 代码编写规范和风格指南
- 代码审查标准和流程
- 文档编写要求
- 代码可读性、可维护性要求
- 重构检查和代码质量评估

**典型规则示例：**

- 代码审查规范
- 文档编写要求
- 重构检查标准
- 代码质量评分标准

#### 3. deployment（部署规范）

**适用场景：**

- 软件部署流程和规范
- 版本发布流程
- 环境配置管理
- 部署自动化要求
- 开源项目部署最佳实践

**典型规则示例：**

- 开源项目部署规范
- 版本发布流程
- 环境配置标准
- CI/CD 部署要求

#### 4. development_tools（开发工具）

**适用场景：**

- 开发工具的使用和配置
- 代码生成工具的规范
- 开发辅助脚本的使用
- IDE 配置和插件管理
- 工具集成规范

**典型规则示例：**

- 脚本生成专家规则
- IDE 配置规范
- 代码生成器使用规范
- 开发工具集成指南

#### 5. development_workflow（开发流程）

**适用场景：**

- 开发方法论（如 TDD、BDD、SDD）
- 开发工作流程和协作规范
- 代码提交和审查流程
- 重构流程和方法
- 开发任务管理规范

**典型规则示例：**

- 测试驱动开发（TDD）
- Spec 驱动开发（SDD）
- 重构流程规范
- C2Rust 转译流程

#### 6. performance（性能优化）

**适用场景：**

- 性能分析和 profiling 方法
- 代码优化策略
- 资源管理和内存优化
- 性能测试和基准测试
- 特定语言（如 Rust）的性能优化

**典型规则示例：**

- 性能优化策略
- Rust 性能优化规范
- 内存管理最佳实践
- 性能测试标准

#### 7. security（安全规范）

**适用场景：**

- 安全编码规范和最佳实践
- 漏洞分析和修复方法
- 安全测试要求
- 加密和数据保护规范
- 安全漏洞分析方法

**典型规则示例：**

- 安全编码规范
- 安全漏洞分析方法
- 安全测试要求
- 数据加密规范

#### 8. tool_config（工具配置）

**适用场景：**

- 工具配置文件规范
- 规则管理系统使用
- 工具行为配置
- 告警和错误处理配置
- 工具级别设置

**典型规则示例：**

- 新增规则规范（本文档）
- 忽略告警配置
- 工具行为调整
- 规则管理流程

#### 9. ui_design（UI 设计）

**适用场景：**

- UI 设计规范和风格指南
- 界面布局和交互规范
- 主题配置（颜色、字体等）
- 组件设计规范
- 响应式设计要求

**典型规则示例：**

- iOS 暗色主题配置
- iOS 亮色主题配置
- UI 组件设计规范
- 界面布局标准
