# Yy Create Rule

> 创建或更新规则文档，并更新 AGENTS.md 中的引用关系。 用于：用户想要创建规则、记录最佳实践、记录 bug 修复经验、记录架构决策。 不用于创建技能、AGENTS.md 主文件或普通项目文档，也不用于直接修改代码以实施规则。

- Skill: `bulls-cows/yy-create-rule` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-create-rule`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-create-rule/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-create-rule

---


# 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`（默认推荐）**

```yaml
---
name: [kebab-case，与目录名一致]
description: [规则简要描述]
trigger: always_on
alwaysApply: true
---
```

**模式 `glob`**

```yaml
---
name: [kebab-case，与目录名一致]
description: [规则简要描述]
trigger: glob
alwaysApply: false
globs: [文件匹配模式，如 src/**/*.vue 或 **/*.{ts,tsx}]
---
```

**模式 `model_decision`**

```yaml
---
name: [kebab-case，与目录名一致]
description: [详细说明规则的适用场景和主题，供 AI 决策]
trigger: model_decision
alwaysApply: false
---
```

**模式 `manual`**

```yaml
---
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. 输出更新摘要：

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

内容已添加到 [章节路径]，供后续 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`：规则文档编写最佳实践