fusion-rule-author

规则编写者

用于编写 AI 编码助手规则的标准工作流、模板和参考资料。支持 GitHub Copilot、Cursor 和 Claude Code。

内部技能。 用户通过 fusion-rules 网关进行交互，该网关会将请求路由到遵循此处定义的工作流的编辑器专属 Agent。

范围

此技能提供：

• 工作流（下方的步骤 1–7）——引导式编写流程
• 模板（assets/）——适用于各编辑器格式的起始文件
• 参考资料（references/）——技术栈示例

此技能不提供 Agent。Agent 位于 fusion-rules/agents/ 中，并引用此技能的资源和工作流。

必需输入

必填

• 仓库上下文（工作目录或仓库 URL）

访谈过程中收集

• 技术栈（语言、框架、构建工具）
• 代码规范（命名、格式、模式）
• 测试要求（框架、覆盖率、风格）
• 文档偏好（注释、TSDoc/JSDoc、README 标准）
• 提交和 PR 规范
• 错误处理模式
• 安全或合规约束
• 需要设置作用域规则的特定文件或路径规范

说明

步骤 1 — 评估当前状态

检查仓库中是否存在现有规则文件：

.github/copilot-instructions.md
.github/instructions/*.instructions.md
.cursor/rules/*.md
.cursor/rules/*.mdc
.cursor/rules/**/*.md
.cursor/rules/**/*.mdc
CLAUDE.md
.claude/CLAUDE.md
.claude/rules/*.md
.claude/rules/**/*.md

报告已有内容、缺失内容，以及是否需要更新或新增文件。

步骤 2 — 扫描仓库

访谈前，先扫描现有文档和配置中体现的规范。从以下内容中提取可执行的指令：

文档文件：

• README.md — 项目概览、设置、技术栈
• CONTRIBUTING.md — 代码风格、PR 工作流、提交规范
• AGENTS.md、CLAUDE.md — 现有 AI 指令
• docs/adr/**、adr/**、docs/decisions/** — 架构决策记录
• docs/**/*.md — 开发者指南、入门文档、风格指南
• SECURITY.md — 安全策略
• CODE_OF_CONDUCT.md — 协作指南（很少与规则相关）

配置文件：

• package.json / pyproject.toml / *.csproj — 技术栈、脚本、依赖项
• tsconfig.json / jsconfig.json — 语言设置、严格程度
• biome.json / .eslintrc* / .prettierrc* / ruff.toml / .editorconfig — 格式化和代码检查
• .github/workflows/*.yml — CI 检查、必需的验证、测试命令
• Dockerfile / docker-compose.yml — 运行时环境
• Makefile / Justfile / Taskfile.yml — 构建和任务命令

代码模式（抽样检查，无需穷举）：

• 入口文件（src/index.*、src/main.*、app.*）— 架构模式
• 测试文件 — 测试框架、命名规范、文件位置
• 目录结构 — 架构边界、功能组织方式

针对每个来源，提取：

1. 可转化为命令式指令的具体规范
2. AI 应了解的构建、测试和代码检查命令
3. 需要遵循的架构边界或模式
4. 明确的“应该做”和“不应该做”的规则

跳过：

• 经常变化的实现细节
• 重述语言或框架默认行为的内容
• CI 或团队实践未落实的愿景性规则

继续访谈前，先按领域整理并向开发者展示发现的规范摘要。

第 3 步 — 访谈（补足缺口）

利用扫描结果，跳过已有充分文档说明的部分。只针对缺失信息提出聚焦的问题。一次只覆盖以下一个领域：

1. 技术栈 — 语言、框架、运行时、包管理器
2. 代码风格 — 命名约定、格式规则、导入顺序
3. 架构 — 项目结构、关键模式（MVC、六边形等）
4. 测试 — 框架、约定、覆盖率预期
5. 文档 — 行内注释风格、文档生成、README 标准
6. Git 工作流 — 分支命名、提交消息格式、PR 预期
7. 安全 — 敏感数据处理、身份验证模式、合规规则
8. 特定路径相关注意事项 — 需要专门指导的目录或文件类型

对于每个领域，展示扫描结果并询问：“这些信息准确吗？还有什么需要补充或更正的吗？”不要重复询问已记录的信息。

对于需要深入了解的每项约定，请使用 assets/creation-follow-up.md 中的后续问题，询问其目的、例外情况、适用范围和语气。

第 4 步 — 对指导内容分类

将收集到的约定划分到以下类别中：

GitHub Copilot：

类别	目标文件	生效时机
始终生效约定	.github/copilot-instructions.md	每次 Copilot 交互
限定范围约定	.github/instructions/<name>.instructions.md	仅当匹配的文件处于打开或引用状态时

Cursor：

类别	目标文件	生效时机
始终生效约定	.cursor/rules/<name>.mdc，带有 alwaysApply: true	每次 Cursor Agent 会话
自动附加约定	.cursor/rules/<name>.mdc，带有 globs	匹配的文件处于上下文中时
Agent 选择约定	.cursor/rules/<name>.mdc，仅带有 description	Agent 判定相关时
手动约定	.cursor/rules/<name>.mdc（无 alwaysApply、无 globs）	仅在聊天中通过 @ 提及时

Claude Code：

类别	目标文件	生效时机
始终生效约定	CLAUDE.md 或 .claude/CLAUDE.md	每次 Claude Code 会话
限定范围约定	.claude/rules/<name>.md，带有 paths frontmatter	Claude 读取匹配的文件时
无条件规则	.claude/rules/<name>.md（无 paths）	每次会话（与始终生效的规则相同）

决策规则： 如果某项约定适用于仓库中的所有文件，则应放入根目录的始终生效说明中。如果仅适用于特定路径或文件类型，则应创建限定范围的规则。

面向多个编辑器时，生成内容等效的对应文件 — 不要在同一编辑器的文件中重复指导内容。

第 5 步 — 起草规则文件

使用 assets/ 中的模板生成文件：

GitHub Copilot：

• 根目录说明：使用 assets/copilot-instructions-template.md
• 限定范围的说明：使用 assets/scoped-rule-template.md，并设置正确的 applyTo glob

Cursor：

• 使用 assets/cursor-rule-template.mdc 并相应设置 frontmatter

Claude Code：

• 项目说明：使用 assets/claude-rule-template.md
• 限定范围的规则：放入 .claude/rules/，并设置 paths frontmatter

质量规则（起草时强制执行）：

• 保持说明简洁 — 使用可执行的指令，而非解释
• 使用祈使语气（“变量使用 camelCase”，而不是“变量应使用 camelCase”）
• 避免在根目录文件与限定范围文件之间重复指导内容
• 验证 applyTo / globs / paths glob 模式能匹配预期文件
• 如果根目录说明总计超过约 80 行，发出警告（存在上下文稀释风险）
• 如果限定范围的说明文件超过约 50 行（GitHub Copilot）、约 500 行（Cursor）或约 200 行（Claude Code CLAUDE.md），发出警告
• 具体的正反示例请参见 references/examples.md
• 完整检查清单请参见 assets/quality-checklist.md

步骤 6 — 审核和完善

向开发者展示起草的文件。对于每个文件：

1. 显示完整内容
2. 标出质量警告（长度、宽泛的 glob、重复内容）
3. 询问是否批准或需要修改

步骤 7 — 写入文件

获得批准后，将规则文件写入代码仓库。按需创建 .github/instructions/、.cursor/rules/ 和／或 .claude/rules/ 目录。

写入前确认最终文件列表和路径。

预期输出

• .github/copilot-instructions.md — 根指令文件（新建或更新）
• .github/instructions/*.instructions.md — 零个或多个范围限定的指令文件
• .cursor/rules/*.mdc — 零个或多个 Cursor 规则文件（目标平台包含 Cursor 时）
• CLAUDE.md 或 .claude/CLAUDE.md — 项目指令（目标平台包含 Claude Code 时）
• .claude/rules/*.md — 零个或多个 Claude Code 范围限定的规则文件
• 所创建／更新内容及原因的摘要

指令、技能与规则——何时使用哪种

需求	GitHub Copilot	Cursor	Claude Code
始终生效的编码约定	copilot-instructions.md	.cursor/rules/*.mdc，并设为 alwaysApply: true	CLAUDE.md
特定文件／路径的指导	.github/instructions/*.instructions.md	.cursor/rules/*.mdc，并设置 globs	.claude/rules/*.md，并设置 paths
特定任务的多步骤工作流	技能（SKILL.md）	.cursor/rules/*.mdc（手动选择或由 Agent 选择）	技能／子 Agent
Agent 路由和编排	Agent 定义（.agent.md）	.cursor/rules/*.mdc，并设置 description	子 Agent 配置
简单的项目级指令	copilot-instructions.md	AGENTS.md	CLAUDE.md

指令和规则规定 AI 如何编写代码。技能则将其能力定义为结构化任务。

安全与约束

切勿：

• 在规则文件中嵌入秘密、令牌或凭据
• 生成与代码仓库安全策略相矛盾的规则
• 未展示差异并获得批准就覆盖现有文件
• 臆造约定——只记录开发者确认的内容

务必：

• 写入任何文件前先展示草稿
• 根据实际代码仓库路径验证 glob 模式
• 对过于宽泛的 glob 发出警告（例如，**/* 会匹配所有内容）
• 保持指令简洁且可执行
• 更新时保留现有内容（追加或合并，切勿悄然替换）

参考资料

• references/examples.md — 不同技术栈的具体示例
• assets/creation-follow-up.md — 针对每条规则的后续问题（用途、例外、边界、语气）
• assets/frontmatter-scenarios.md — GitHub Copilot、Cursor 和 Claude Code 的场景化 frontmatter 指南
• assets/copilot-instructions-template.md — 根指令起始模板
• assets/scoped-rule-template.md — 范围限定规则起始模板
• assets/cursor-rule-template.mdc — Cursor 规则起始模板
• assets/claude-rule-template.md — Claude Code 规则起始模板
• assets/quality-checklist.md — 质量审核清单