# 规则编写指南

本指南定义了如何编写和格式化项目规则文件。

## 规则文件格式原则

### Markdown 格式

Custom rules can be written in plain text, but **Markdown format is recommended** for better structure and comprehension by the AI models.

### 结构要求

1. **使用 Markdown 标题** (`#`, `##`, etc.) 定义规则分类
2. **使用列表** (`-`, `*`) 枚举具体项目或约束
3. **使用代码块** (```) 包含代码示例

### 示例格式

```markdown
# 规则标题

规则描述...

## 具体规则

- 规则项目 1
- 规则项目 2

## 代码示例

```python
# 正确示例
def example():
    pass

# 错误示例
def wrong():
    pass
```
```

## 规则文件命名规范

- 使用小写下划线：`rule_name.md`
- 避免使用大写字母和空格
- 文件名应清晰表达规则内容

## 规则文件组织

### 核心规则文件

| 文件名 | 描述 |
|--------|------|
| `formatting.md` | 代码格式化规则 |
| `naming_conventions.md` | 命名约定规则 |
| `restricted_files.md` | 限制文件规则（修改限制） |
| `restricted_reads.md` | 读取限制规则 |
| `rule_formatting_guide.md` | 规则编写指南 |

### 规则索引

`rules_index.md` 提供所有规则的快速参考和链接。

## 规则内容结构

### 必要元素

1. **标题**：清晰描述规则主题
2. **描述**：说明规则的目的和作用
3. **具体规则**：使用列表形式枚举
4. **示例**：代码示例说明正确和错误的做法

### 可选元素

- **模式匹配**：使用表格说明匹配规则
- **注意事项**：补充说明和警告
- **相关规则**：指向其他相关规则文件的链接

## 禁止读取规则格式

对于定义禁止读取文件的规则，使用以下格式：

```markdown
# 禁止读取的文件

以下文件包含敏感信息，**绝对禁止**以任何方式读取。

## 配置文件

- `**/*config*` - 包含 config 的文件名
- `config.py`
- `app_config.py`

## JSON 文件

- `**/*.json`
- `settings.json`
- `data.json`

## 强制执行规则

- ❌ 禁止任何理由读取
- ❌ 即使任务无法完成也禁止
- 唯一例外：用户主动上传至上下文
```

## 更新规则时的注意事项

1. **保持格式一致**：遵循 Markdown 格式原则
2. **更新索引**：如果添加新规则，更新 `rules_index.md`
3. **添加示例**：为新规则提供清晰的代码示例
4. **版本控制**：重大变更应记录变更日志

## 验证清单

添加新规则前，检查以下项目：

- [ ] 使用 Markdown 格式
- [ ] 包含清晰的标题和描述
- [ ] 使用列表枚举具体规则
- [ ] 提供代码示例
- [ ] 更新规则索引（如需要）