diff --git a/README.md b/README.md index e773d8c..8dac9ea 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,147 @@ # rules-skills -常用的一些rules和skills \ No newline at end of file +本项目是一个 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. 定期回顾和维护,移除过时内容 diff --git a/rules/common/language-zh-cn.md b/rules/common/language-zh-cn.md new file mode 100644 index 0000000..b6c9b56 --- /dev/null +++ b/rules/common/language-zh-cn.md @@ -0,0 +1,27 @@ +# 语言规范 - 中文优先 + +## 规则 + +1. **必须使用中文**:与用户交流时,默认使用简体中文(zh-CN)进行所有回复。 +2. **禁止混用**:除非用户明确要求或涉及专有名词(如代码、API 名称、品牌名),否则禁止在中文回复中夹杂英文单词或短语。 +3. **技术术语处理**: + - 专有技术名词(如 `React`、`Docker`、`Kubernetes`)可保留英文原词。 + - 通用技术术语(如 "database" 应译为 "数据库","function" 应译为 "函数")应使用中文表述。 +4. **代码与注释**:代码中的注释、文档字符串(docstring)应使用中文编写。 +5. **异常场景**: + - 若用户主动使用其他语言提问,可先用该语言简短确认,随后切换回中文继续交流。 + - 若系统提示词或上下文强制要求使用英文(如特定工具的内部指令),可在该范围内使用英文,但对用户的输出仍须为中文。 + +## 示例 + +| 场景 | 正确示例 | 错误示例 | +|------|---------|---------| +| 日常回复 | "这是一个函数,用于处理用户输入。" | "This is a function used to handle user input." | +| 技术解释 | "使用 Docker 容器来部署应用。" | "Use Docker container to deploy the app." | +| 代码注释 | `// 计算两个数的和` | `// Calculate the sum of two numbers` | + +## 适用范围 + +- 所有面向用户的文本输出 +- 代码注释与文档 +- 错误提示与日志说明(面向用户时) diff --git a/rules/common/output-format.md b/rules/common/output-format.md new file mode 100644 index 0000000..7752d78 --- /dev/null +++ b/rules/common/output-format.md @@ -0,0 +1,59 @@ +# 输出规范 + +## 规则 + +1. **结构清晰**:输出内容必须层次分明,合理使用标题、列表、表格等格式,避免大段文字堆砌。 +2. **简洁优先**:在保证信息完整的前提下,力求简洁。删除冗余词汇,避免重复表达。 +3. **格式统一**: + - 同类内容使用一致的格式呈现。 + - 代码块必须标注语言类型(如 ```java)。 + - 列表项保持对齐,层级关系明确。 +4. **重点突出**: + - 关键信息使用加粗(**文本**)或代码块(`代码`)突出。 + - 重要结论前置,细节补充在后。 +5. **完整性**: + - 回答必须完整,不遗漏用户问题的任何部分。 + - 涉及多步骤时,按顺序列出,确保逻辑连贯。 +6. **可读性**: + - 适当使用空行分隔不同段落或模块。 + - 长文本超过 5 行时,考虑拆分为列表或表格。 + - 避免一行文字过长,建议控制在 80-120 个字符内。 +7. **错误与警告**: + - 输出警告或错误信息时,使用明确的标识(如 `⚠️ 警告:`、`❌ 错误:`)。 + - 提供错误的具体位置和修复建议。 +8. **代码输出**: + - 只输出必要的代码片段,避免完整文件复制。 + - 修改代码时,标注修改点(如使用注释 `// 修改:...`)。 + - 提供代码上下文说明,帮助理解。 + +## 示例 + +### 正确示例 + +```markdown +## 问题分析 + +**根本原因**:数据库连接池耗尽。 + +**影响范围**: +- 用户登录接口响应超时 +- 订单查询服务不可用 + +**修复步骤**: +1. 增加连接池最大连接数(当前:20 → 建议:50) +2. 检查并关闭未释放的数据库连接 +3. 重启应用服务 +``` + +### 错误示例 + +```markdown +数据库连接池耗尽了所以用户登录不了订单也查不了,你要不看看把连接池改大点然后重启一下吧。 +``` + +## 适用范围 + +- 所有面向用户的文本输出 +- 技术文档与说明 +- 代码审查意见 +- 问题排查报告 diff --git a/rules/common/token-efficiency.md b/rules/common/token-efficiency.md new file mode 100644 index 0000000..0f8845b --- /dev/null +++ b/rules/common/token-efficiency.md @@ -0,0 +1,105 @@ + Token 效率规范 + +## 规则 + +1. **精简输出**: + - 默认输出控制在必要最小范围内,优先提供关键信息而非完整内容。 + - 避免冗余解释,用户已知的背景信息不再重复。 + - 单次回复总长度建议控制在 2000 字以内,复杂任务可分步输出。 + +2. **代码输出优化**: + - 只输出修改相关的代码片段,禁止输出完整文件内容。 + - 使用 `// ...` 或注释省略未修改部分,保留必要的上下文(通常前后 3-5 行)。 + - 多文件修改时,逐个文件展示,每个文件只展示变更部分。 + +3. **避免重复**: + - 不重复用户已提供的信息或上下文。 + - 不重复解释同一概念,首次提及即可。 + - 列表或表格中避免重复字段,使用引用或缩写。 + +4. **结构化压缩**: + - 优先使用列表、表格替代段落描述,减少连接词和过渡句。 + - 使用符号(如 `→`、`⇒`)替代文字表达因果关系。 + - 技术术语使用标准缩写(如 API、DB、UI),避免全称重复。 + +5. **智能省略**: + - 通用代码模板(如 import 语句、标准配置)可省略,必要时提供链接或提示。 + - 错误堆栈只保留关键帧,过滤框架内部调用。 + - 日志输出只保留与问题相关的行,使用 `...` 省略无关内容。 + +6. **分步响应**: + - 复杂任务先给出概要方案和关键步骤,确认后再展开细节。 + - 多步骤任务每步只输出当前步骤内容,不预输出后续步骤。 + +## 与现有规则的关联 + +| 关联规则 | 说明 | +|---------|------| +| `output-format.md` 第 2 条"简洁优先" | 本规则是对"简洁优先"的具体化和量化补充,侧重 Token 层面的优化 | +| `output-format.md` 第 8 条"代码输出" | 本规则第 2 条是对该条的扩展,增加了具体的代码省略策略 | + +## 示例 + +### 代码输出(优化前) + +```java +package com.example.service; + +import org.springframework.stereotype.Service; +import org.springframework.beans.factory.annotation.Autowired; + +@Service +public class UserService { + + @Autowired + private UserRepository userRepository; + + @Autowired + private OrderRepository orderRepository; + + // ... 其他代码 ... + + public User getUserById(Long id) { + return userRepository.findById(id).orElse(null); + } + + // ... 其他代码 ... +} +``` + +### 代码输出(优化后) + +```java +// UserService.java +public User getUserById(Long id) { + return userRepository.findById(id).orElse(null); +} +``` + +### 日志输出(优化前) + +``` +2024-01-01 10:00:01 INFO [main] Starting application... +2024-01-01 10:00:02 INFO [main] Loading configuration... +2024-01-01 10:00:03 ERROR [main] Failed to connect to database +java.sql.SQLException: Connection refused + at com.mysql.jdbc.Connection.createNewIO(Connection.java:1234) + at com.mysql.jdbc.Connection.(Connection.java:567) + at com.mysql.jdbc.Driver.connect(Driver.java:89) + at java.sql.DriverManager.getConnection(DriverManager.java:123) + at com.example.config.DatabaseConfig.init(DatabaseConfig.java:45) + ... 省略 20 行框架内部调用 +``` + +### 日志输出(优化后) + +``` +ERROR: Failed to connect to database (Connection refused) + at DatabaseConfig.init(DatabaseConfig.java:45) +``` + +## 适用范围 + +- 所有代码和技术内容输出 +- 日志和错误信息展示 +- 多步骤任务的分步回复 diff --git a/rules/language/java-naming.md b/rules/language/java-naming.md new file mode 100644 index 0000000..726159e --- /dev/null +++ b/rules/language/java-naming.md @@ -0,0 +1,108 @@ +# Java 命名规范 + +## 规则 + +1. **包名(Package)**: + - 全部小写,使用反斜杠分隔层级。 + - 格式:`com.公司名.项目名.模块名` + - 示例:`com.example.order.service` + +2. **类名(Class)**: + - 使用大驼峰命名法(UpperCamelCase)。 + - 名词或名词短语。 + - 示例:`UserService`、`OrderController`、`DatabaseConfig` + +3. **接口名(Interface)**: + - 使用大驼峰命名法(UpperCamelCase)。 + - 通常以 `Interface` 结尾(可选,根据团队规范)。 + - 示例:`PaymentServiceInterface` 或 `PaymentService` + +4. **抽象类名(Abstract Class)**: + - 使用大驼峰命名法(UpperCamelCase)。 + - 以 `Abstract` 开头。 + - 示例:`AbstractBaseController`、`AbstractEventHandler` + +5. **枚举名(Enum)**: + - 使用大驼峰命名法(UpperCamelCase)。 + - 示例:`OrderStatus`、`UserRole` + +6. **变量名(Variable)**: + - 使用小驼峰命名法(camelCase)。 + - 见名知意,避免缩写(如 `userList` 而非 `ul`)。 + - 示例:`userName`、`orderList`、`isActive` + +7. **常量名(Constant)**: + - 全部大写,单词间用下划线分隔。 + - 使用 `static final` 修饰。 + - 示例:`MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE` + +8. **方法名(Method)**: + - 使用小驼峰命名法(camelCase)。 + - 动词或动词短语开头。 + - 示例:`getUserById`、`createOrder`、`isValid` + +9. **布尔变量与方法**: + - 布尔变量以 `is`、`has`、`can`、`should` 开头。 + - 示例:`isEnabled`、`hasPermission`、`canDelete` + - Getter 方法:布尔类型使用 `is` 前缀(如 `isEnabled()`),其他类型使用 `get` 前缀。 + +10. **异常类名(Exception)**: + - 以 `Exception` 结尾。 + - 示例:`UserNotFoundException`、`OrderProcessingException` + +11. **测试类名(Test Class)**: + - 以 `Test` 结尾或开头。 + - 示例:`UserServiceTest`、`TestOrderService` + +12. **集合变量名**: + - 使用复数形式或添加 `List`、`Map`、`Set` 后缀。 + - 示例:`users`、`userList`、`orderMap` + +## 示例 + +### 正确示例 + +```java +package com.example.order.service; + +public class OrderService implements OrderServiceInterface { + + private static final int MAX_RETRY_COUNT = 3; + private static final int DEFAULT_PAGE_SIZE = 10; + + private final OrderRepository orderRepository; + + public List getAllOrders() { + return orderRepository.findAll(); + } + + public Optional getOrderById(Long id) { + return orderRepository.findById(id); + } + + public boolean isValidOrder(Order order) { + return order != null && order.getAmount() > 0; + } +} +``` + +### 错误示例 + +```java +package com.example.order; // 包名缺少层级 + +public class orderservice { // 类名未使用大驼峰 + + private int maxretrycount = 3; // 常量未大写 + + public List getorder() { // 方法名未使用小驼峰 + return orderRepository.findAll(); + } +} +``` + +## 适用范围 + +- 所有 Java 项目代码 +- Spring Boot 后端服务 +- Java 单元测试 diff --git a/rules/language/vue-naming.md b/rules/language/vue-naming.md new file mode 100644 index 0000000..381e80f --- /dev/null +++ b/rules/language/vue-naming.md @@ -0,0 +1,193 @@ +# Vue 命名规范 + +> 本规范适用于 Vue2 和 Vue3。两者在命名规范上基本一致,主要区别在于 API 风格(Options API vs Composition API)。 + +## 规则 + +1. **文件名**: + - 组件文件使用大驼峰命名法(PascalCase)。 + - 示例:`UserProfile.vue`、`OrderList.vue` + - 视图页面文件使用 `View` 后缀:`UserListView.vue`、`OrderDetailView.vue` + +2. **组件名(Component Name)**: + - 在 `components` 目录中的组件使用多单词命名,避免与 HTML 标签冲突。 + - 示例:`BaseButton.vue`、`ThemePicker.vue`、`UserAvatar.vue` + - 视图组件使用 `View` 后缀。 + +3. **模板中组件引用**: + - 在模板中使用大驼峰(PascalCase)或短横线(kebab-case)均可,建议统一使用大驼峰。 + - 示例:`` 或 `` + +4. **Props 命名**: + - 声明时使用小驼峰(camelCase)。 + - 在模板中传递时使用短横线(kebab-case)。 + - 示例: + ```javascript + // 声明 + props: { + userName: String, + orderList: Array + } + ``` + ```html + + + ``` + +5. **Emits 命名**: + - 使用短横线(kebab-case)。 + - 示例:`update:user-name`、`delete-order` + +6. **数据属性(Data Properties)**: + - 使用小驼峰(camelCase)。 + - 避免与 props 同名。 + - 示例:`searchQuery`、`isLoading` + +7. **方法名(Methods)**: + - 使用小驼峰(camelCase)。 + - 动词开头,清晰表达动作。 + - 示例:`handleSubmit`、`fetchOrders`、`toggleMenu` + +8. **计算属性(Computed)**: + - 使用小驼峰(camelCase)。 + - 名词或名词短语表示派生数据。 + - 示例:`formattedName`、`filteredOrders`、`isLoading` + +9. ** watchers**: + - 方法名与被监听的属性同名。 + - 示例:`watch: { searchQuery(newValue) { ... } }` + +10. **CSS 类名**: + - 使用短横线连接(kebab-case)。 + - 若使用 scoped CSS,建议添加组件名前缀。 + - 示例:`.user-profile-header`、`.order-list-item` + +11. **组合式函数(Composition API - Vue3 特有)**: + - 文件名以 `use` 开头,使用小驼峰。 + - 示例:`useFetch.js`、`useMouse.js` + - 函数名以 `use` 开头,使用小驼峰。 + - 示例:`function useFetch(url) { ... }` + +12. **响应式变量(Composition API)**: + - 使用小驼峰(camelCase)。 + - ref 变量:`count`、`userName` + - reactive 对象:`state`、`form` + +13. **Provide / Inject**: + - 使用 Symbol 或字符串常量。 + - 命名清晰表达提供的功能。 + - 示例:`provide('currentUser', user)`、`inject('currentUser')` + +## Vue2 与 Vue3 的差异说明 + +| 项目 | Vue2 (Options API) | Vue3 (Composition API) | +|------|-------------------|----------------------| +| **数据定义** | `data()` 返回对象 | `ref()` 或 `reactive()` | +| **方法定义** | `methods` 选项 | 直接在 `setup()` 中定义 | +| **计算属性** | `computed` 选项 | `computed()` 函数 | +| **侦听器** | `watch` 选项 | `watch()` 或 `watchEffect()` 函数 | +| **命名规范** | ✅ 相同 | ✅ 相同 | + +> **结论**:Vue2 和 Vue3 在命名规范上没有本质差异,仅 API 使用方式不同。 + +## 示例 + +### 正确示例 + +```vue + + + + + + +``` + +### Composition API 示例(Vue3) + +```vue + + + + + + +``` + +### 错误示例 + +```vue + + + + +``` + +## 适用范围 + +- Vue2 项目(Options API) +- Vue3 项目(Options API 和 Composition API) +- Vue 组合式函数(Composables) diff --git a/rules/workflow/git-workflow.md b/rules/workflow/git-workflow.md new file mode 100644 index 0000000..a7c25dc --- /dev/null +++ b/rules/workflow/git-workflow.md @@ -0,0 +1,74 @@ +# Git 工作流规范 + +## 规则 + +1. **提交粒度**: + - 每次提交只做一件事,保持提交的原子性。 + - 避免将不相关的修改混入同一提交。 + - 提交前使用 `git diff --cached` 检查变更内容。 + +2. **提交信息规范**: + - 使用 `git commit -m ": "` 格式。 + - `` 必须是以下之一: + - `feature`:新功能 + - `bug`:修复 bug + - `docs`:文档更新 + - `style`:代码格式(不影响功能) + - `refactor`:重构 + - `test`:测试相关 + - `chore`:构建过程或辅助工具的变动 + - `` 使用祈使句,首字母小写,不超过 50 个字符。 + - 需要详细说明时,使用 `-m` 多行提交,空行分隔标题和正文。 + +3. **分支管理**: + - 主分支: `master`,始终保持可部署状态。 + - 开发分支:`dev`,集成所有功能开发。 + - 功能分支:`feature/<编号>`,没有编号时使用`feature/<描述>`,从 `master`切出,完成后合并回 `master`。 + - 修复分支:`bug/<编号>`,没有编号时使用`bug/<描述>`,从 `master` 切出,完成后合并回 `master`。 + - 紧急修复:`hotfix/<描述>`,从 `master` 切出,完成后合并回 `master` 。 + +4. **代码审查**: + - 合并到 `master` 前必须通过 Pull Request。 + - PR 标题遵循提交信息规范。 + - PR 描述简要描述修改内容,不要过长的提交信息。 + +5. **冲突处理**: + - 优先使用 `git rebase` 保持提交历史线性。 + - 冲突解决后,确保代码可正常编译和运行。 + - 禁止在公共分支上使用 `git push --force`。 + +6. **标签与版本**: + - 使用语义化版本号:`v..`。 + - 版本发布时创建对应的 tag。 + - 在 `CHANGELOG.md` 中记录版本变更。 + +## 示例 + +### 提交信息 + +```bash +# 正确 +git commit -m "feature: add user authentication" +git commit -m "bug: resolve null pointer in order service" + +# 错误 +git commit -m "update" +git commit -m "Fix bug" +``` + +### 分支操作 + +```bash +# 创建功能分支 +git checkout -b feature/user-login master + +# 完成后合并 +git checkout master +git merge --no-ff feature/user-login +``` + +## 适用范围 + +- 所有使用 Git 进行版本管理的项目 +- 团队协作开发流程 +- 开源项目贡献