fusion-rule-author

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rule Author

规则编写工具

Canonical workflow, templates, and references for authoring AI coding assistant rules. Supports GitHub Copilot, Cursor, and Claude Code.

Internal skill. Users interact via the
fusion-rules
gateway, which routes to editor-specific agents that follow the workflow defined here.

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

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

Scope

适用范围

This skill provides:

Workflow (Steps 1–7 below) — the guided authoring process
Templates (
```
assets/
```
) — starter files for each editor format
References (
```
references/
```
) — tech-stack examples

It does not provide agents. Agents live in

fusion-rules/agents/

and reference this skill's assets and workflow.

本Skill提供：

工作流（下文步骤1-7）——引导式规则编写流程
模板（
```
assets/
```
目录）——各编辑器格式的起始文件
参考资料（
```
references/
```
目录）——技术栈示例

本Skill不提供Agent。Agent存放在

fusion-rules/agents/

目录中，并引用本Skill的资源和工作流。

Required inputs

所需输入

Mandatory

必填项

Repository context (working directory or repo URL)

Gathered during interview

访谈过程中收集

Instructions

操作步骤

Step 1 — Assess current state

步骤1 — 评估当前状态

Check the repository for existing rule files:

.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

Report what exists, what is missing, and whether updates or new files are needed.

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

.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

报告已存在的文件、缺失的文件，以及是否需要更新或创建新文件。

Step 2 — Scan repository

步骤2 — 扫描仓库

Before interviewing, scan the repository for existing documentation and configuration that encodes conventions. Extract actionable directives from:

Documentation files:

```
README.md
```
— project overview, setup instructions, tech stack
```
CONTRIBUTING.md
```
— code style, PR workflow, commit conventions
```
AGENTS.md
```
,
```
CLAUDE.md
```
— existing AI instructions
```
docs/adr/**
```
,
```
adr/**
```
,
```
docs/decisions/**
```
— Architecture Decision Records
```
docs/**/*.md
```
— any developer guides, onboarding docs, style guides
```
SECURITY.md
```
— security policies and constraints
```
CODE_OF_CONDUCT.md
```
— collaboration guidelines (rarely rule-relevant)

Configuration files:

```
package.json
```
/
```
pyproject.toml
```
/
```
*.csproj
```
— tech stack, scripts, dependencies
```
tsconfig.json
```
/
```
jsconfig.json
```
— language settings, strictness

biome.json

.eslintrc*

.prettierrc*

ruff.toml

.editorconfig

— formatting and linting rules

```
.github/workflows/*.yml
```
— CI checks, required validations, test commands
```
Dockerfile
```
/
```
docker-compose.yml
```
— runtime environment
```
Makefile
```
/
```
Justfile
```
/
```
Taskfile.yml
```
— build and task commands

Code patterns (sample, do not exhaustively read):

Entry points (
```
src/index.*
```
,
```
src/main.*
```
,
```
app.*
```
) — architecture patterns
Test files — testing framework, naming conventions, file placement
Directory structure — architectural boundaries, feature organization

For each source, extract:

Concrete conventions that can become imperative directives
Build/test/lint commands the AI should know
Architecture boundaries or patterns to follow
Explicit "do this / don't do that" rules

Skip:

Implementation details that change frequently
Content that restates language/framework defaults
Aspirational rules not enforced by CI or team practice

Present a summary of discovered conventions to the developer, organized by area, before proceeding to the interview.

在访谈前，扫描仓库中已有的文档和配置文件，提取其中的规范要求。从以下来源提取可执行的指令：

文档文件：

```
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

— 格式化与 linting 规则

```
.github/workflows/*.yml
```
— CI检查、必填验证、测试命令
```
Dockerfile
```
/
```
docker-compose.yml
```
— 运行时环境
```
Makefile
```
/
```
Justfile
```
/
```
Taskfile.yml
```
— 构建与任务命令

代码模式（抽样查看，无需通读）：

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

针对每个来源，提取：

可转化为强制指令的具体规范
AI需要知晓的构建/测试/lint命令
需要遵循的架构边界或模式
明确的“要做/不要做”规则

跳过以下内容：

频繁变更的实现细节
重复语言/框架默认规则的内容
CI或团队实践未强制执行的理想规则

在进入访谈前，将发现的规范按领域整理后呈现给开发者。

Step 3 — Interview (fill gaps)

步骤3 — 访谈（填补空白）

Use the scan results to skip areas already well-documented. Ask focused questions only for gaps. Cover these areas one at a time:

Tech stack — languages, frameworks, runtime, package manager
Code style — naming conventions, formatting rules, import ordering
Architecture — project structure, key patterns (MVC, hexagonal, etc.)
Testing — framework, conventions, coverage expectations
Documentation — inline comments style, doc generation, README standards
Git workflow — branch naming, commit message format, PR expectations
Security — sensitive data handling, auth patterns, compliance rules
Path-specific concerns — any directories or file types that need specialized guidance

For each area, present what the scan found and ask: "Is this accurate? Anything to add or correct?" Do not re-ask for information already captured.

For each convention that needs deeper context, use the follow-up questions in

assets/creation-follow-up.md

— purpose, exceptions, boundaries, voice.

利用扫描结果跳过已充分文档化的领域，仅针对空白部分提出针对性问题。依次覆盖以下领域：

技术栈——编程语言、框架、运行时、包管理器
代码风格——命名规范、格式化规则、导入顺序
架构——项目结构、核心模式（MVC、六边形架构等）
测试——框架、规范、覆盖率要求
文档——内联注释风格、文档生成、README标准
Git工作流——分支命名、提交消息格式、PR要求
安全——敏感数据处理、认证模式、合规规则
路径专属需求——任何需要特殊指导的目录或文件类型

针对每个领域，先展示扫描结果，然后询问：“此内容是否准确？是否有需要补充或修正的地方？” 不要重复询问已收集到的信息。

对于需要更深入上下文的规范，使用

assets/creation-follow-up.md

中的跟进问题——目的、例外情况、边界、语气。

Step 4 — Classify guidance

步骤4 — 分类指导内容

Separate the gathered conventions into buckets:

GitHub Copilot:

Bucket	Target file	When it activates
Always-on conventions	`.github/copilot-instructions.md`	Every Copilot interaction
Scoped conventions	`.github/instructions/<name>.instructions.md`	Only when matching files are open/referenced

Cursor:

Bucket	Target file	When it activates
Always-on conventions	`.cursor/rules/<name>.mdc` with `alwaysApply: true`	Every Cursor Agent session
Auto-attached conventions	`.cursor/rules/<name>.mdc` with `globs`	When matching files are in context
Agent-selected conventions	`.cursor/rules/<name>.mdc` with `description` only	When the Agent decides it is relevant
Manual conventions	`.cursor/rules/<name>.mdc` (no `alwaysApply` , no `globs` )	Only when @-mentioned in chat

Claude Code:

Bucket	Target file	When it activates
Always-on conventions	`CLAUDE.md` or `.claude/CLAUDE.md`	Every Claude Code session
Scoped conventions	`.claude/rules/<name>.md` with `paths` frontmatter	When Claude reads matching files
Unconditional rule	`.claude/rules/<name>.md` (no `paths` )	Every session (like always-on)

Decision rule: If a convention applies to all files in the repo, it belongs in root / always-on instructions. If it applies only to specific paths or file types, create a scoped rule.

When targeting multiple editors, generate parallel files with equivalent content — do not duplicate guidance within a single editor's files.

将收集到的规范划分为不同类别：

GitHub Copilot：

分类	目标文件	触发时机
全局生效规范	`.github/copilot-instructions.md`	每次Copilot交互时
范围化规范	`.github/instructions/<name>.instructions.md`	仅当打开/引用匹配文件时

Cursor：

分类	目标文件	触发时机
全局生效规范	带有 `alwaysApply: true` 的 `.cursor/rules/<name>.mdc`	每次Cursor Agent会话时
自动关联规范	带有 `globs` 的 `.cursor/rules/<name>.mdc`	上下文包含匹配文件时
Agent选择规范	仅带有 `description` 的 `.cursor/rules/<name>.mdc`	Agent判定相关时
手动触发规范	无 `alwaysApply` 和 `globs` 的 `.cursor/rules/<name>.mdc`	仅在聊天中@提及触发

Claude Code：

分类	目标文件	触发时机
全局生效规范	`CLAUDE.md` 或 `.claude/CLAUDE.md`	每次Claude Code会话时
范围化规范	带有 `paths` 前置元数据的 `.claude/rules/<name>.md`	Claude读取匹配文件时
无条件规则	无 `paths` 的 `.claude/rules/<name>.md`	每次会话时（同全局生效）

判定规则： 如果规范适用于仓库所有文件，则放入根目录/全局生效指令文件。如果仅适用于特定路径或文件类型，则创建范围化规则。

当针对多个编辑器时，生成内容等效的并行文件——不要在单个编辑器的文件中重复指导内容。

Step 5 — Draft rule files

步骤5 — 起草规则文件

Generate files using the templates in

assets/

GitHub Copilot:

For root instructions: use
```
assets/copilot-instructions-template.md
```
as the starting structure
For scoped instructions: use
```
assets/scoped-rule-template.md
```
and fill in the correct
```
applyTo
```
glob pattern

Cursor:

For always-on or scoped rules: use
```
assets/cursor-rule-template.mdc
```
and set frontmatter accordingly

Claude Code:

For project instructions: use
```
assets/claude-rule-template.md
```
as the starting structure
For scoped rules: place in
```
.claude/rules/
```
with
```
paths
```
frontmatter

Quality rules (enforced during drafting):

Keep instructions concise — aim for actionable directives, not explanations
Use imperative voice ("Use camelCase for variables", not "Variables should use camelCase")
Avoid duplicating guidance between root and scoped files
Validate
```
applyTo
```
/
```
globs
```
/
```
paths
```
glob patterns match the intended files
Warn if total root instructions exceed ~80 lines (risk of context dilution)
Warn if a scoped instruction file exceeds ~50 lines (GitHub Copilot), ~500 lines (Cursor), or ~200 lines (Claude Code CLAUDE.md)
See
```
references/examples.md
```
for concrete good and bad examples
See
```
assets/quality-checklist.md
```
for the full checklist

使用

assets/

目录中的模板生成文件：

GitHub Copilot：

根目录指令：以
```
assets/copilot-instructions-template.md
```
为基础结构
范围化指令：使用
```
assets/scoped-rule-template.md
```
并填写正确的
```
applyTo
```
glob模式

Cursor：

全局生效或范围化规则：使用
```
assets/cursor-rule-template.mdc
```
并相应设置前置元数据

Claude Code：

项目指令：以
```
assets/claude-rule-template.md
```
为基础结构
范围化规则：放置在
```
.claude/rules/
```
目录中并添加
```
paths
```
前置元数据

起草时的质量规则：

指令保持简洁——聚焦可执行指令，而非解释
使用祈使语气（如“变量使用小驼峰命名”，而非“变量应该使用小驼峰命名”）
避免在根目录和范围化文件中重复指导内容
验证
```
applyTo
```
/
```
globs
```
/
```
paths
```
glob模式与目标文件匹配
如果根目录指令总长度超过约80行，发出警告（存在上下文稀释风险）
如果范围化指令文件超过以下长度，发出警告：GitHub Copilot约50行，Cursor约500行，Claude Code的CLAUDE.md约200行
参考
```
references/examples.md
```
中的正反示例
参考
```
assets/quality-checklist.md
```
中的完整检查清单

Step 6 — Review and refine

步骤6 — 审核与优化

Present the drafted files to the developer for review. For each file:

Show the full content
Highlight any quality warnings (length, broad globs, duplication)
Ask for approval or edits

将起草好的文件提交给开发者审核。针对每个文件：

展示完整内容
高亮任何质量警告（长度、过宽glob、重复内容）
询问是否批准或需要编辑

Step 7 — Write files

步骤7 — 写入文件

After approval, write the rule files to the repository. Create the

.github/instructions/

.cursor/rules/

, and/or

.claude/rules/

directories as needed.

Confirm the final file list and paths before writing.

获得批准后，将规则文件写入仓库。根据需要创建

.github/instructions/

、

.cursor/rules/

和/或

.claude/rules/

目录。

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

Expected output

预期输出

```
.github/copilot-instructions.md
```
— root instructions file (created or updated)
```
.github/instructions/*.instructions.md
```
— zero or more scoped instruction files
```
.cursor/rules/*.mdc
```
— zero or more Cursor rule files (when Cursor is targeted)
```
CLAUDE.md
```
or
```
.claude/CLAUDE.md
```
— project instructions (when Claude Code is targeted)
```
.claude/rules/*.md
```
— zero or more Claude Code scoped rule files
Summary of what was created/updated and why

```
.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范围化规则文件
已创建/更新内容的摘要及原因

Instructions vs skills vs rules — when to use which

指令、Skill与规则的适用场景

Need	GitHub Copilot	Cursor	Claude Code
Always-on coding conventions	`copilot-instructions.md`	`.cursor/rules/*.mdc` with `alwaysApply: true`	`CLAUDE.md`
File/path-specific guidance	`.github/instructions/*.instructions.md`	`.cursor/rules/*.mdc` with `globs`	`.claude/rules/*.md` with `paths`
Task-specific multi-step workflows	A skill ( `SKILL.md` )	`.cursor/rules/*.mdc` (manual or agent-selected)	Skills / subagents
Agent routing and orchestration	Agent definitions ( `.agent.md` )	`.cursor/rules/*.mdc` with `description`	Subagent configs
Simple project-wide instructions	`copilot-instructions.md`	`AGENTS.md`	`CLAUDE.md`

Instructions and rules shape how the AI writes code. Skills define what it can do as structured tasks.

需求	GitHub Copilot	Cursor	Claude Code
全局生效的编码规范	`copilot-instructions.md`	带有 `alwaysApply: true` 的 `.cursor/rules/*.mdc`	`CLAUDE.md`
文件/路径专属指导	`.github/instructions/*.instructions.md`	带有 `globs` 的 `.cursor/rules/*.mdc`	带有 `paths` 的 `.claude/rules/*.md`
任务专属多步骤工作流	Skill（ `SKILL.md` ）	`.cursor/rules/*.mdc` （手动或Agent选择触发）	Skills/子Agent
Agent路由与编排	Agent定义（ `.agent.md` ）	带有 `description` 的 `.cursor/rules/*.mdc`	子Agent配置
简单项目全局指令	`copilot-instructions.md`	`AGENTS.md`	`CLAUDE.md`

指令和规则定义AI如何编写代码。Skill定义AI作为结构化任务能做什么。

Safety and constraints

安全与约束

Never:

Embed secrets, tokens, or credentials in rule files
Generate rules that contradict repository security policies
Overwrite existing files without showing the diff and getting approval
Invent conventions — only document what the developer confirms

Always:

Show drafts before writing any files
Validate glob patterns against actual repository paths
Warn on overly broad globs (e.g.,
```
**/*
```
captures everything)
Keep instructions concise and actionable
Preserve existing content when updating (append or merge, never replace silently)

绝对禁止：

在规则文件中嵌入密钥、令牌或凭证
生成与仓库安全策略冲突的规则
未展示差异并获得批准就覆盖现有文件
自创规范——仅记录开发者确认的内容

必须遵守：

在写入任何文件前展示草稿
验证glob模式与仓库实际路径匹配
对过于宽泛的glob模式发出警告（如
```
**/*
```
会匹配所有内容）
保持指令简洁且可执行
更新时保留现有内容（追加或合并，绝不静默替换）

References

参考资料

```
references/examples.md
```
— concrete examples for different tech stacks
```
assets/creation-follow-up.md
```
— per-rule follow-up questions (purpose, exceptions, boundaries, voice)
```
assets/frontmatter-scenarios.md
```
— scenario-based frontmatter guide for GitHub Copilot, Cursor, and Claude Code
```
assets/copilot-instructions-template.md
```
— starter template for root instructions
```
assets/scoped-rule-template.md
```
— starter template for scoped rules
```
assets/cursor-rule-template.mdc
```
— starter template for Cursor rules
```
assets/claude-rule-template.md
```
— starter template for Claude Code rules
```
assets/quality-checklist.md
```
— quality review checklist

```
references/examples.md
```
——不同技术栈的具体示例
```
assets/creation-follow-up.md
```
——针对规则的跟进问题（目的、例外、边界、语气）
```
assets/frontmatter-scenarios.md
```
——GitHub Copilot、Cursor和Claude Code的前置元数据场景指南
```
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
```
——质量审核清单