148 lines
4.6 KiB
Markdown
148 lines
4.6 KiB
Markdown
# rules-skills
|
||
|
||
本项目是一个 AI 编程辅助知识库，用于集中存放和管理常用的 **Rules（规则）** 与 **Skills（技能）**。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [概念定义](#概念定义)
|
||
- [核心区别](#核心区别)
|
||
- [目录结构](#目录结构)
|
||
- [使用方法](#使用方法)
|
||
- [书写规范](#书写规范)
|
||
- [文件命名规范](#文件命名规范)
|
||
|
||
---
|
||
|
||
## 概念定义
|
||
|
||
### Rule（规则）
|
||
|
||
**Rule** 是全局性的约束条件，用于划定 AI 的行为边界和输出规范。它告诉 AI "应该怎么做" 以及 "不应该做什么"。
|
||
|
||
- **作用范围**：全局生效，影响 AI 的所有响应
|
||
- **核心目的**：确保 AI 输出符合团队规范、编码标准或项目约束
|
||
- **典型场景**：
|
||
- 代码风格规范（如必须使用某种命名约定）
|
||
- 安全约束（如禁止输出敏感信息）
|
||
- 输出格式要求（如必须包含特定字段）
|
||
- 行为边界（如遇到不确定时必须询问而非猜测）
|
||
|
||
### Skill（技能）
|
||
|
||
**Skill** 是可复用的原子化能力单元，用于执行特定任务或完成特定目标。它告诉 AI "具体做什么" 以及 "如何一步步完成"。
|
||
|
||
- **作用范围**：按需调用，仅在触发时生效
|
||
- **核心目的**：封装可复用的任务执行流程，提高效率和一致性
|
||
- **典型场景**：
|
||
- 代码审查流程
|
||
- 特定框架的项目初始化
|
||
- 标准化的文档生成
|
||
- 重复的代码重构模式
|
||
|
||
---
|
||
|
||
## 核心区别
|
||
|
||
| 维度 | Rule（规则） | Skill（技能） |
|
||
|------|-------------|--------------|
|
||
| **本质定位** | 约束与边界 | 能力与动作 |
|
||
| **作用时机** | 全局持续生效 | 按需触发执行 |
|
||
| **内容形式** | 原则性、声明式描述 | 步骤化、流程化指导 |
|
||
| **使用方式** | 自动应用，无需显式调用 | 需要显式触发或调用 |
|
||
| **生命周期** | 长期稳定，少变更 | 随需求迭代，可增减 |
|
||
| **典型内容** | "必须使用驼峰命名"、"禁止硬编码密钥" | "1. 分析代码 2. 找出问题 3. 给出建议" |
|
||
|
||
### 类比理解
|
||
|
||
- **Rule** 像是交通规则：红灯停、绿灯行，所有车辆（AI 输出）都必须遵守。
|
||
- **Skill** 像是驾驶技能：倒车入库、侧方停车，需要时按步骤执行。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
rules-skills/
|
||
├── rules/ # 存放所有 Rule 文件
|
||
│ ├── example-rule.md
|
||
│ └── ...
|
||
├── skills/ # 存放所有 Skill 文件
|
||
│ ├── example-skill.md
|
||
│ └── ...
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
---
|
||
|
||
## 使用方法
|
||
|
||
### 使用 Rule
|
||
|
||
Rule 通常配置在 AI 工具的全局设置或项目配置中，自动生效：
|
||
|
||
1. 将需要的 Rule 文件内容复制到 AI 工具的规则配置区
|
||
2. 或在项目配置中引用 Rule 文件路径
|
||
3. AI 在处理所有请求时自动遵循这些规则
|
||
|
||
### 使用 Skill
|
||
|
||
Skill 需要显式触发，常见方式：
|
||
|
||
1. **命令触发**：在对话中直接引用 Skill 名称，如 `/skill-name` 或 `@skill-name`
|
||
2. **文件引用**：将 Skill 内容粘贴到对话中，让 AI 按步骤执行
|
||
3. **工具集成**：在支持 Skill 的 AI 平台中配置为可调用工具
|
||
|
||
---
|
||
|
||
## 书写规范
|
||
|
||
### Rule 书写规范
|
||
|
||
1. **明确性**：每条规则应清晰、无歧义，避免模糊表述
|
||
2. **可验证性**：规则应能被明确判断是否符合（是/否）
|
||
3. **必要性**：只写真正需要的规则，避免过度约束
|
||
4. **优先级**：如有多条规则冲突，应标明优先级
|
||
5. **格式统一**：建议使用 "必须..."、"禁止..."、"应该..." 等明确措辞
|
||
|
||
### Skill 书写规范
|
||
|
||
1. **步骤清晰**：将任务拆分为明确的步骤，每步一个动作
|
||
2. **输入输出定义**：明确 Skill 需要什么输入，产生什么输出
|
||
3. **可复用性**：设计时考虑通用性，避免过度绑定具体场景
|
||
4. **错误处理**：包含常见异常情况的应对方式
|
||
5. **示例说明**：提供 1-2 个使用示例，帮助理解
|
||
|
||
---
|
||
|
||
## 文件命名规范
|
||
|
||
### Rule 文件
|
||
|
||
- 使用 **kebab-case**（短横线连接）
|
||
- 格式：`{领域}-{具体规则}.md`
|
||
- 示例：
|
||
- `code-style-java.md`
|
||
- `security-sensitive-data.md`
|
||
- `response-format-json.md`
|
||
|
||
### Skill 文件
|
||
|
||
- 使用 **kebab-case**（短横线连接）
|
||
- 格式：`{动作}-{目标}.md` 或 `{领域}-{动作}.md`
|
||
- 示例：
|
||
- `review-code-java.md`
|
||
- `generate-api-doc.md`
|
||
- `refactor-extract-method.md`
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
1. 新增 Rule 或 Skill 前，先检查是否已有类似内容
|
||
2. 遵循上述书写规范和命名规范
|
||
3. 将文件放入对应的 `rules/` 或 `skills/` 目录
|
||
4. 保持内容简洁，聚焦单一职责
|
||
5. 定期回顾和维护，移除过时内容
|