yy-create-rule

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、调试技巧

选择建议：

1. 默认使用 always_on
2. 规则只涉及特定文件类型时用 glob（避免污染无关任务的上下文）
3. 规则属于"按需查阅"的专业知识时用 model_decision（必须精心编写 description）
4. 规则属于临时方案或低频场景时用 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 中添加对新建规则文档的引用：

1. 检查 AGENTS.md 中是否存在 ## 需要遵守的规则 章节
2. 如果存在，在该章节中添加引用
3. 如果不存在，检查是否存在 ## Rules 章节；存在则添加到该章节
4. 如果两个章节都不存在，在文件末尾添加 ## 需要遵守的规则 章节
5. 在目标章节中添加引用：- [规则名称 @rules/[目录名]/RULE.md](./rules/[目录名]/RULE.md)

步骤 7. 更新文档并输出结果

1. 更新目标文档
2. 如果需要，更新 AGENTS.md
3. 输出更新摘要：

✓ 已更新文档：[文件路径]
✓ 更新章节：[章节名称]
✓ 新增内容：[简要描述]

内容已添加到 [章节路径]，供后续 AI 开发参考。

验收清单

创建规则文档后检查项

1. frontmatter 完整且字段顺序正确：name → description → trigger → alwaysApply → globs
2. name 使用 kebab-case，与所在目录名一致
3. trigger 取值为 always_on / glob / model_decision / manual 之一
4. alwaysApply 值与 trigger 匹配（仅 always_on 为 true）
5. trigger: glob 时 globs 字段已填写且语法正确
6. trigger: model_decision 时 description 写清了适用场景（非模糊名称）
7. 规则文档有明确的章节标题，具有描述性
8. 内容结构清晰，使用标准的 Markdown 层级结构
9. 提供具体的代码示例（如有适用场景）
10. 代码示例包含语言标签
11. 说明"为什么"而不仅仅是"怎么做"
12. 包含反例说明（如有适用场景）
13. 文件命名符合规范（kebab-case）
14. 使用中文编写内容
15. AGENTS.md 中已添加对新规则文档的引用
16. 通用性检查：内容必须是可复用的指导原则，不包含特定项目的具体数据（如具体行数、具体版本号、具体项目名等）；示例应使用占位符或通用场景，而非真实项目数据

更新规则文档后检查项

1. 新内容与现有章节主题相关
2. 保持文档格式风格一致性
3. 未删除或修改现有内容（除非用户明确要求）
4. 代码示例包含语言标签
5. 使用中文编写内容

相关资源

本技能包含以下辅助资源：

• resources/content-template.md：规则内容结构模板
• resources/rule-best-practices.md：规则文档编写最佳实践