---
name: add_rule
description: 当需要添加新规则、管理现有规则或配置规则系统时使用此规范——指导如何创建和管理规则文件，包括文件位置、命名规范、分类体系、格式要求和YAML头部规范。包括：创建新的规则文件；确定规则的合适位置和目录结构；遵循规范的命名约定；选择合适的规则分类；编写符合格式的YAML头部；定义规则的description字段；组织规则的内容结构；管理规则的索引和加载；配置规则的依赖关系。每当用户提及"添加规则"、"创建规则"、"新建规则"、"规则管理"、"规则配置"、"编写规则"、"定义规则"或需要添加新规则、管理规则、配置规则系统时触发，无论规则的类型和用途是什么。如果需要创建、管理或配置规则文件，请使用此规范。
---

# 新增规则规范

## 规则文件基本要求

### 规则类型选择

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

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

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

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

**选择原则：**

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

**操作流程：**

1. 确定规则类型（全局规则或项目规则）
2. 根据类型选择对应的文件位置（见下方章节）
3. 创建规则文件
4. 规则会自动被索引系统扫描并添加到索引中

### 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/` 根目录下，也可以按分类创建子目录
- 建议全局规则也按照与项目规则相同的分类体系组织，便于统一管理

### 规则索引

**自动索引机制：**

- Jarvis 已实现自动规则索引功能，**无需手动注册**
- 系统会自动扫描 `builtin/rules/` 和 `.jarvis/rules/` 目录下的所有 `.md` 文件
- 从 YAML 头部提取 `description` 字段生成索引
- 索引可通过 `load_rule` 工具的内置索引功能访问

**YAML 头部规范：**

- **必须**：顶层规则文件（作为入口的主规则）必须包含 YAML front matter header
- **可选**：子规则文件（被顶层规则引用的详细规则）可以不包含 header
- **禁止**：header 内容为空或格式错误

**对于顶层规则文件，所有规则文件**必须\*\*在文件顶部包含 YAML 头部，格式如下：

```yaml
---
name: 规则名称 # 必需，规则的简短标识
description: 规则功能描述 # 必需，规则的详细触发场景说明
license: MIT # 可选，开源协议标识
---
```

**字段说明：**

- **name**（必需）：规则的名称标识
  - 用于唯一标识规则
  - **必须**使用规则文件的简短名称（不含.md后缀）
  - **必须**使用英文或拼音，不建议使用中文
  - 示例：`code_review`, `tdd`, `security`

- **description**（必需）：规则的详细触发场景说明
  - 用于规则索引展示和自动匹配
  - 应清晰描述规则的适用范围、操作类型、触发条件
  - **必须**按照以下详细格式编写，参考 `builtin/rules/pptx/SKILL.md`

- **license**（可选）：开源协议标识
  - 用于标识规则的授权协议
  - 常见协议：`MIT`, `Apache-2.0`, `GPL-3.0`, `BSD-3-Clause`
  - 如果不需要特别授权，可以不填写此字段

**description 详细格式要求：**

```yaml
name: clean_code
description: 当需要[明确触发条件]时使用此规则——[规则名称]，[简要说明]。包括：[操作类型1]；[操作类型2]；[操作类型3]。每当用户提及"[触发关键词1]"、"[触发关键词2]"或[适用场景]时触发，无论[适用范围]。如果需要[使用条件]，请使用此规则。
```

**格式要素说明：**

1. **触发条件**：明确说明什么情况下使用该规则
   - 格式：`当需要[具体场景]时使用此规则`
   - 示例：`当需要编写整洁代码时使用此规则`

2. **规则名称**：规则的正式名称
   - 格式：`——[规则名称]，[简要说明]`
   - 示例：`——整洁代码规则，代码编写规范和最佳实践`

3. **操作类型**：列出具体的操作类别，用分号分隔
   - 格式：`包括：[操作1]；[操作2]；[操作3]`
   - 示例：`包括：编写可读性强的代码；确保单一职责；消除重复代码`

4. **触发关键词**：具体的触发关键词，用引号括起
   - 格式：`每当用户提及"[关键词1]"、"[关键词2]"`
   - 示例：`每当用户提及"整洁代码"、"代码规范"、"最佳实践"`

5. **适用范围**：说明触发的适用边界
   - 格式：`或[适用场景]时触发，无论[适用范围]`
   - 示例：`或需要编写/审查高质量代码时触发，无论他们之后打算如何处理代码`

6. **使用条件**：明确的使用指导
   - 格式：`如果需要[使用条件]，请使用此规则。`
   - 示例：`如果需要编写、审查或改进代码的可读性和质量，请使用此规则。`

**完整示例：**

```yaml
---
name: clean_code
description: 当需要编写或审查整洁代码时使用此规则——整洁代码规则，代码编写规范和最佳实践。包括：编写可读性强的代码，使用有意义的变量名和函数名；确保每个函数和类只做一件事；消除重复代码，提取公共逻辑；遵循命名规范；控制函数长度。每当用户提及"整洁代码"、"代码规范"、"最佳实践"、"代码审查"、"可读性"或需要编写/审查高质量代码时触发，无论他们之后打算如何处理代码。如果需要编写、审查或改进代码的可读性和质量，请使用此规则。
license: MIT
---
```

**编写原则：**

- **必须**：包含全部6个格式要素
- **必须**：操作类型列表至少3-5项，使用分号分隔
- **必须**：触发关键词至少3-5个，用引号括起
- **必须**：明确触发条件和边界
- **建议**：总长度在150-300字之间
- **禁止**：过于简短或模糊的描述

**兼容性说明：**

- 系统兼容没有 YAML 头部的规则文件（主要是子规则文件）
- 如果规则文件缺少 YAML 头部，索引将使用文件名作为描述
- **建议**：顶层规则文件务必包含完整规范的 YAML 头部，以获得最佳索引和匹配效果

### 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 %}`

**⚠️ 重要提示：`rule_file_dir` 的正确使用**

`{% raw %}{{ rule_file_dir }}{% endraw %}` 变量表示**当前规则文件所在目录**的绝对路径。使用时请注意：

- **引用同目录下的文件**：直接使用 `{% raw %}{{ rule_file_dir }}{% endraw %}/文件名.md`，**不要**重复添加目录层级
- **错误示例**：如果规则文件在 `builtin/rules/development_workflow/` 目录下，引用同目录的子规则时，**错误**写法是 `{{ rule_file_dir }}/development_workflow/sub_rule.md`
- **正确示例**：直接写 `{{ rule_file_dir }}/sub_rule.md` 即可
- **常见错误**：因为 `rule_file_dir` 已经包含了完整的目录路径（如 `/path/to/builtin/rules/development_workflow/`），所以不应该再添加目录前缀

### 变量使用示例

#### 示例 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/` 目录
- [ ] 文件命名符合规范（小写、下划线分隔、.md 后缀）
- [ ] 文件包含 YAML 头部，包含 `description` 字段
- [ ] 文件放置在合适的分类子目录中
- [ ] 文件格式符合 Markdown 规范

## 相关资源

- 参考文档：`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 组件设计规范
- 界面布局标准
