| name | yy-create-rule |
| description | 创建或更新规则文档，并更新 AGENTS.md 中的引用关系。 用于：用户想要创建规则、记录最佳实践、记录 bug 修复经验、记录架构决策。 不用于创建技能、AGENTS.md 主文件或普通项目文档，也不用于直接修改代码以实施规则。
|
yy-create-rule
创建或更新规则文档，并更新 AGENTS.md 中的引用关系，确保 AI 助手能够理解项目的具体规范和最佳实践。
描述
帮助用户创建或更新规则文档，记录项目特定的规范、最佳实践和经验教训，供后续 AI 开发参考。规则文档是"给 AI 的项目知识库"，用于沉淀项目知识、避免重复踩坑。
使用场景
- 用户想要创建规则文档
- 用户想要记录最佳实践
- 用户想要记录 bug 修复经验
- 用户想要记录架构决策
不应触发：
- 用户只是询问规则是什么
- 用户要求创建普通文件
- 用户要求创建技能文件
指令
步骤 1. 捕获意图
理解用户的需求，确定规则内容。默认采用以下策略：
- 内容类型：根据用户描述自动判断（最佳实践 / 规范约定 / bug 修复 / 架构决策 / 其他）
- 适用范围：默认为全局，若用户指定特定模块则按指定范围
- 核心要点：从用户描述中提取
- 触发模式：初步判断规则应如何被加载（详见步骤 5.1）。默认
always_on；仅特定文件/技术栈相关时考虑 glob；属于按需查阅的专业知识时考虑 model_decision；临时或低频场景考虑 manual
若用户描述不清晰，只询问核心问题：这条规则要解决什么问题？
步骤 2. 检查并初始化必要目录和文件
检查规则目录：
- 根据目录规则确定目标目录（用户指定目录或默认的
.agents/rules）
- 如果目录不存在，记录需要创建的目录路径，待确认方案与计划后再创建
检查 AGENTS.md 文件：
- 如果文件不存在，记录需要创建 AGENTS.md 或需用户先执行
/yy-create-agents 命令，待确认方案与计划后再处理
- 如果文件存在，读取其内容
步骤 3. 决定放置位置
列出规则目录下所有文件。对每个现有规则文档，判断新内容是否属于其主题范围。
情况 A：找到合适的现有规则文档
- 读取目标文档内容
- 找到合适的章节插入内容
- 如果没有合适的章节，创建新章节
- 记录目标规则文档、目标章节和拟插入内容
- 不需要修改 AGENTS.md
情况 B：没有合适的现有规则文档
- 根据内容主题自动生成目录名（kebab-case，如
vue-component-norms、api-best-practices）
- 记录待创建路径：
rules/[目录名]/RULE.md
- 记录需要在 AGENTS.md 中新增的引用（引用路径应包含完整目录路径）
目录结构约定：每个规则独立一个目录，目录内只有一个 RULE.md 文件（及可选的 references/ 子目录存放拆分模块）。
情况 C：用户指定在现有文档中追加
步骤 4. 确认方案与计划
完成放置位置判断后，必须先确认方案与计划，收到用户确认后才可继续格式化内容、写入文件或更新 AGENTS.md。
- 若当前环境可用
yy-mode-plan：优先直接使用该技能创建方案方向和计划，并等待用户确认
- 若当前环境不可用
yy-mode-plan：使用以下本地最小确认流程
- 方向不明确时：先展示方案方向，等用户确认方向正确后，再展示计划
- 方向明确时：直接展示计划
- 展示计划后，必须等用户确认才可继续后续步骤
- 展示方案方向时，至少包含以下内容：
- 目标：一句话说明将要完成的内容
- 方法：高层策略（1-3 句）
- 涉及范围：将要修改或创建的规则文档、章节或关联引用
- 待确认点：仍需用户决策的关键选择（如有）
- 方案方向结尾必须明确提示用户确认方向是否正确，或提出调整意见
- 计划中至少说明规则放置位置、目标文件路径、是否更新 AGENTS.md、内容组织方式和影响范围
步骤 5. 格式化并插入内容
根据文档的现有格式，组织要插入的内容。内容结构模板详见 resources/content-template.md。
语言规范详见 resources/rule-best-practices.md。
5.1 选择触发模式
参考 Cursor Rules 设计，根据规则的适用范围选择触发模式：
| 模式 | 适用场景 | 何时加载 | 典型示例 |
|---|
always_on | 项目级通用规范，所有任务都应遵守 | 每次对话自动加载 | 代码风格、命名约定、错误处理 |
glob | 仅特定文件/技术栈相关 | 匹配文件进入上下文时加载 | Vue 组件规范、API 路由规范 |
model_decision | 特定领域专业知识 | AI 根据 description 判断相关性后加载 | 性能优化策略、复杂 bug 解决方案 |
manual | 临时性、调试性或低频使用 | 仅显式 @ 引用时加载 | 临时 workaround、调试技巧 |
选择建议：
- 默认使用
always_on
- 规则只涉及特定文件类型时用
glob（避免污染无关任务的上下文）
- 规则属于"按需查阅"的专业知识时用
model_decision（必须精心编写 description）
- 规则属于临时方案或低频场景时用
manual
5.2 编写 frontmatter
按字段固定顺序填写：name → description → trigger → alwaysApply → globs。
模式 always_on（默认推荐）
---
name: [kebab-case，与目录名一致]
description: [规则简要描述]
trigger: always_on
alwaysApply: true
---
模式 glob
---
name: [kebab-case，与目录名一致]
description: [规则简要描述]
trigger: glob
alwaysApply: false
globs: [文件匹配模式，如 src/**/*.vue 或 **/*.{ts,tsx}]
---
模式 model_decision
---
name: [kebab-case，与目录名一致]
description: [详细说明规则的适用场景和主题，供 AI 决策]
trigger: model_decision
alwaysApply: false
---
模式 manual
---
name: [kebab-case，与目录名一致]
description: [规则简要描述]
trigger: manual
alwaysApply: false
---
5.3 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | 规则唯一标识，kebab-case（如 vue-component-norms），与所在目录名保持一致 |
description | string | 是 | 规则描述；model_decision 模式下是 AI 判断是否触发的关键依据，需明确写清适用场景 |
trigger | enum | 是 | 触发模式，四选一：always_on / glob / model_decision / manual |
alwaysApply | boolean | 是 | 是否始终应用；仅 always_on 为 true，其余模式为 false |
globs | string | string[] | 否 | 文件匹配模式；仅 trigger: glob 时必填，支持标准 glob 语法，多模式用逗号分隔或 YAML 数组 |
5.4 description 写作指南
description 在所有模式下用于展示，在 model_decision 模式下还承担"触发依据"职责。参考 Cursor Rules 最佳实践：
- 明确具体：清晰说明规则涵盖的主题和适用场景，像写检索关键词
- 长度适中：1-2 句话
- 避免笼统：不要写成模糊的名称
写作对比：
| ❌ 避免 | ✅ 推荐 |
|---|
Vue 规则 | Vue 组件规范：props 单向数据流、生命周期钩子顺序、组件拆分原则 |
错误处理 | API 错误处理：统一错误码、错误响应体结构、异常处理器模式 |
样式规范 | CSS 命名规范：BEM 命名约定、模块化样式、避免全局选择器 |
更新现有规则文档时，不修改已有的 frontmatter。
步骤 6. 更新 AGENTS.md 引用（仅当创建新规则文档时）
在 AGENTS.md 中添加对新建规则文档的引用：
- 检查 AGENTS.md 中是否存在
## 需要遵守的规则 章节
- 如果存在，在该章节中添加引用
- 如果不存在，检查是否存在
## Rules 章节；存在则添加到该章节
- 如果两个章节都不存在，在文件末尾添加
## 需要遵守的规则 章节
- 在目标章节中添加引用：
- [规则名称 @rules/[目录名]/RULE.md](./rules/[目录名]/RULE.md)
步骤 7. 更新文档并输出结果
- 更新目标文档
- 如果需要，更新 AGENTS.md
- 输出更新摘要：
✓ 已更新文档：[文件路径]
✓ 更新章节：[章节名称]
✓ 新增内容：[简要描述]
内容已添加到 [章节路径]，供后续 AI 开发参考。
验收清单
创建规则文档后检查项
- frontmatter 完整且字段顺序正确：
name → description → trigger → alwaysApply → globs
name 使用 kebab-case，与所在目录名一致trigger 取值为 always_on / glob / model_decision / manual 之一alwaysApply 值与 trigger 匹配（仅 always_on 为 true）trigger: glob 时 globs 字段已填写且语法正确trigger: model_decision 时 description 写清了适用场景（非模糊名称）- 规则文档有明确的章节标题，具有描述性
- 内容结构清晰，使用标准的 Markdown 层级结构
- 提供具体的代码示例（如有适用场景）
- 代码示例包含语言标签
- 说明"为什么"而不仅仅是"怎么做"
- 包含反例说明（如有适用场景）
- 文件命名符合规范（kebab-case）
- 使用中文编写内容
- AGENTS.md 中已添加对新规则文档的引用
- 通用性检查：内容必须是可复用的指导原则，不包含特定项目的具体数据（如具体行数、具体版本号、具体项目名等）；示例应使用占位符或通用场景，而非真实项目数据
更新规则文档后检查项
- 新内容与现有章节主题相关
- 保持文档格式风格一致性
- 未删除或修改现有内容（除非用户明确要求）
- 代码示例包含语言标签
- 使用中文编写内容
相关资源
本技能包含以下辅助资源：
resources/content-template.md：规则内容结构模板resources/rule-best-practices.md：规则文档编写最佳实践
