yy-create-rule

这个技能用于创建或更新规则文档，并更新 AGENTS.md 中的引用关系，确保 AI 助手能够理解项目的具体规范和最佳实践。

规则目录规则

• 如果用户指定了目录，则在用户指定的目录下生成规则文件
• 如果用户未指定目录，则在 .agents/rules 目录下生成（没有该目录则创建）

使用方式

用户可以通过以下方式调用这个技能：

• /yy-create-rule <规则内容> - 创建或更新指定的规则内容

工作流程

步骤 1：获取规则内容

记录用户提供的规则内容，并询问以下信息：

• 内容类型：最佳实践 / 规范约定 / bug修复 / 架构决策 / 其他
• 适用范围：全局 / 特定功能模块 / 特定技术栈
• 核心要点：用一句话总结这条知识

步骤 2：检查并初始化必要目录和文件

检查规则目录：

• 根据目录规则确定目标目录（用户指定目录或默认的 .agents/rules）
• 如果目录不存在，创建该目录并提示用户

检查 AGENTS.md 文件：

• 如果文件不存在，提示用户先使用 /yy-init 命令创建 AGENTS.md，或者询问是否现在创建
• 如果文件存在，读取其内容

步骤 3：决定放置位置

列出规则目录下所有文件。对每个现有规则文档，判断新内容是否属于其主题范围。

情况A：找到合适的现有规则文档

• 读取目标文档内容
• 找到合适的章节插入内容
• 如果没有合适的章节，创建新章节
• 更新规则文档
• 不需要修改 AGENTS.md

情况B：没有合适的现有规则文档文档

• 询问用户为新规则文档命名（建议使用主题命名，如 vue组件规范.md、api调用最佳实践.md）
• 在规则目录下新建该文件
• 将内容写入新文件
• 在 AGENTS.md 中新增对该文件的引用（引用路径应包含完整目录路径）

情况C：用户选择在现有文档中追加

• 用户指定一个现有文档
• 在该文档中追加新内容

步骤 4：格式化并插入内容

根据文档的现有格式，组织要插入的内容：

内容结构：

### [章节标题]

**[子标题或要点]**

[详细描述]

**[示例/代码]**（如果适用）

\`\`\`[语言]
[代码示例]
\`\`\`

**[注意事项]**（如果适用）

- 注意事项1
- 注意事项2

语言规范：

• 文档主体使用中文
• 专有名词（Vue、TypeScript、React）、代码片段、已广泛使用的技术缩写（API、SDK、OSS）保留英文
• 正文叙述不夹杂不必要的英文，如"这个 component 需要 emit 一个 event"应改为"该组件需要通过事件通知父级"

插入位置优先级：

1. 如果存在明确相关的章节，插入到该章节内
2. 如果是新的主题，创建新的章节
3. 保持文档的层级结构一致性

步骤 5：更新 AGENTS.md 引用（仅当创建新规则文档时）

在 AGENTS.md 中添加对新建规则文档的引用：

1. 检查 AGENTS.md 中是否存在 ## Rules 章节
2. 如果不存在，在文件末尾添加 ## Rules 章节
3. 在 Rules 章节中添加引用：- [规则目录路径]/[文件名].md: [简要说明]

示例：

## Rules

- .agents/rules/vue组件规范.md: Vue 组件开发规范
- .agents/rules/api调用最佳实践.md: API 调用的最佳实践和错误处理

步骤 6：更新文档并确认

1. 使用 Edit 或 Write 工具更新目标文档
2. 如果需要，更新 AGENTS.md
3. 显示更新摘要：

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

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

示例场景

场景1：创建新的规则文档 用户说："/yy-create-rule Vue组件中不要直接修改 props，要通过 emit 事件" → 检查规则目录是否存在 → 查找现有规则文档，没有找到合适的 → 创建新文档 规则目录/vue组件规范.md → 在 AGENTS.md 中添加引用

场景2：追加到现有规则文档 用户说："/yy-create-rule 所有 API 错误都要用统一的错误处理器，不能自己 catch 后静默忽略" → 检查规则目录 → 找到 规则目录/api调用最佳实践.md → 在该文档中追加新内容 → 不需要修改 AGENTS.md

场景3：记录 bug 修复经验 用户说："/yy-create-rule iOS WebView 中 position:fixed 在软键盘弹起时会失效" → 检查规则目录 → 没有找到合适的现有文档 → 创建新文档 规则目录/移动端兼容性问题.md → 在 AGENTS.md 中添加引用

最佳实践

1. 规则文档的编写原则

   • 使用标准的 Markdown 层级结构
   • 章节标题要具有描述性
   • 使用列表和代码块增强可读性
   • 将相似的规范/实践归类到同一章节
   • 提供具体的代码示例
   • 说明"为什么"而不仅仅是"怎么做"
   • 包含反例说明（如果适用）
   • 面向 AI 读者：写的是给下一次对话中的 AI 看的，要清晰、无歧义、可操作
   • 具体而非抽象：给出代码示例、文件路径、具体场景，而非泛泛而谈

2. 保持一致性

   • 遵循现有文档的格式风格
   • 使用一致的术语和命名
   • 保持章节编号/层级的一致性

3. 避免重复

   • 更新前先检查是否已存在类似内容
   • 如果已存在，考虑补充或改进现有内容，而不是添加重复内容

4. AGENTS.md 引用格式

   • 引用格式：- [规则目录路径]/[文件名].md: [简要说明]
   • 简要说明要清晰，让 AI 能够快速了解该规则文档的作用

注意事项

• 使用正斜杠作为路径分隔符，路径包含空格时使用引号包裹，以确保跨平台兼容性和正确解析
• 在更新文档前，务必先读取文档内容，了解现有结构
• 不要删除或修改现有内容，除非用户明确要求
• 如果不确定应该放在哪个章节，询问用户的意见
• 保持专业和简洁的技术写作风格
• 使用中文编写内容（除非项目文档是与其他）
• 不要将同一条内容写进多个文件（避免文档碎片化）
• 规则目录下的文件内容深度 > AGENTS.md 的引用说明深度
• 如果用户提供的内容已经在文档中存在，告知用户并说明在哪里，不重复写入
• 对于非常临时或版本相关的信息（如"某个依赖的临时 bug"），写入时标注"临时"或版本号
• 确保 AGENTS.md 文件存在，如果不存在提示用户使用 /init 命令创建