dyoshikawa/rulesync · 上手攻略

• 仓库：dyoshikawa/rulesync
• 链接：https://github.com/dyoshikawa/rulesync
• 分类：开发工具 · AI 配置管理
• 作者：Tom
• 更新：2026-08-26

是什么

rulesync 是一个 Node.js CLI 工具，用来统一管理各种 AI 编程工具的配置文件（rules、instructions、MCP、commands、subagents、skills、hooks 等）。它的思路是：维护一份 .rulesync/ 目录下的"规则真相源"，再从这个单一来源生成目标工具（Claude Code、Cursor、GitHub Copilot、Vibe Code 等）的配置文件。它还支持把已有工具的配置文件导入到 .rulesync/ 中，以及在工具之间互相转换配置。

解决什么问题

AI 编程工具的配置格式五花八门：

• Claude Code 用 CLAUDE.md
• Cursor 用 .cursorrules
• GitHub Copilot 用 .github/copilot-instructions.md
• Roo Code 用 roo Rules.md
• Goose 用 agent.yaml
• ……

当你想在多个工具之间统一规则，或者想换工具时，配置迁移是个头疼的问题。rulesync 解决了这个：一个源 → 多个目标，还支持导入已有配置和跨格式转换。

快速安装

npm（全局）

npm install -g rulesync

Homebrew（macOS / Linux）

# 注意：需要完整的两参数形式
brew tap dyoshikawa/rulesync https://github.com/dyoshikawa/rulesync
brew install rulesync
# ⚠️ 简写形式 brew install dyoshikawa/rulesync/rulesync 无效（未 tap 先 install 失败）

安装脚本（Linux / macOS）

curl -fsSL https://github.com/dyoshikawa/rulesync/releases/latest/download/install.sh | bash

验证安装

rulesync --version

核心用法

初始化新项目

rulesync init
# 生成 .rulesync/ 目录结构
# + 样例规则文件和 rulesync.jsonc 配置文件

获取官方 Skill 集

# 推荐：获取 rulesync 官方 skill 源
rulesync fetch dyoshikawa/rulesync

# 然后生成本项目所有目标工具的配置
rulesync generate --targets "*" --features "*"

导入已有配置文件

如果已用某个工具，导入现有配置到 .rulesync/ 作为真相源：

# 从 Claude Code 的 CLAUDE.md 导入
rulesync import --targets claudecode

# 从 Cursor 的 .cursorrules 导入
rulesync import --targets cursor

# 从 GitHub Copilot 导入
rulesync import --targets copilot

# 导入时指定具体 feature（可选）
rulesync import --targets claudecode --features rules,mcp,commands,subagents

⚠️ 导入动作把已有配置写入 .rulesync/ 目录，不会修改原始文件。

跨工具直接转换（无需 .rulesync/ 工作流）

想把 Cursor 的 .cursorrules 转成 Claude Code 和 Copilot 格式，但不采用 rulesync 的管理工作流：

# 直接转换，不写 .rulesync/ 文件
rulesync convert --from cursor --to copilot,claudecode

常用 CLI 命令参考

# 生成配置
rulesync generate --targets "claudecode,cursor" --features "rules,mcp,commands"

# 查看支持的目标工具列表
rulesync generate --help

# 导入配置
rulesync import --targets <tool>

# 拉取远程 skill 源
rulesync fetch <owner/repo>

# 从 rulesync.jsonc 安装 skill
rulesync install

# 初始化（已有项目）
rulesync init

支持的工具与功能矩阵

rulesync 支持 30+ 种 AI 开发工具，每种工具支持的功能子集不同（rules / ignore / mcp / commands / subagents / skills / hooks / permissions / checks）。

完整列表见 官方支持工具参考，常见工具覆盖：

工具	rules	mcp	commands	subagents	skills
Claude Code	✅	✅	✅	✅	✅
Cursor	✅	✅	✅	✅	✅
GitHub Copilot	✅	✅	✅	✅	✅
Codex CLI	✅	✅	✅	✅	✅
Vibe Code	✅	✅	✅	—	✅
Cline	✅	✅	✅	✅	✅
Roo Code ⚠️	✅	✅	✅	✅	✅
Goose	✅	—	✅	✅	✅

⚠️ Roo Code 状态：已于 2026-05-15 停止维护（v3.54.0），官方推荐迁移到 Zoo Code。

⚠️ ignore 功能：已废弃，由更表达的 permissions 功能替代。现有 .rulesyncignore 仍被 14.x 支持，不会突然移除。

⚠️ Kiro 工具：IDE 和 CLI 使用不同配置格式（IDE 用 Markdown subagents，CLI 用 JSON subagents），需分别生成：--targets kiro-ide 和 --targets kiro-cli。

典型适用场景

场景	rulesync 价值
多工具团队（有人用 Cursor，有人用 Claude Code）	统一规则一次维护，多端生效
切换 AI 编程工具	导入旧工具配置 → 转换到新工具，无需重写
管理 MCP 服务配置	在 .rulesync/ 统一配置，多工具共享
标准化团队 AI 开发规范	.rulesync/ 纳入版本控制，团队成员各自生成本地配置
探索不同工具	用 rulesync convert 快速对比不同工具的配置格式

坑与注意

1. Homebrew 安装注意两参数形式：必须先 brew tap dyoshikawa/rulesync <URL> 再 brew install rulesync。⚠️ 直接 brew install dyoshikawa/rulesync/rulesync（不先 tap）会失败。

2. Roo Code 已停止维护：当前转 Roo Code 配置仍有意义，因为 Zoo Code（社区接续）仍使用相同格式，但新项目不应再用 Roo Code 目标。

3. --targets "*" 生成全部工具：如果安装了很多工具支持，会生成大量文件。根据需要指定具体目标工具列表更安全。

4. 导入会覆盖已有 .rulesync/ 内容：如果 .rulesync/ 已有配置，重新 import 同工具会覆盖已有内容。⚠️ 建议在 import 前先备份，或纳入版本控制。

5. 插件打包目标（claudecode-plugin / antigravity-plugin）：这些目标不会出现在 --targets "*" 中，避免把 package 级别的 skills/rules 目录写入普通项目。如需插件打包，参考 Plugin Packaging 指南。

6. 权限 vs ignore 功能：ignore 已废弃但 14.x 仍可用；新项目建议用 permissions（功能更丰富），两者不要混用。

7. GitHub Copilot CLI：目标名是 copilot（不是 copilot-cli），且只支持 rules、mcp、commands、subagents、skills、hooks，不支持 ignore。

与同类对比

工具	多工具统一配置	导入已有配置	跨格式转换	开源
rulesync（本工具）	✅	✅	✅	✅
Smithery（AI 工具配置市场）	部分	❌	❌	部分
Claude Code 原生 rules	❌	❌	❌	✅
Cursor rules	❌	❌	❌	✅

核心差异：rulesync 是目前唯一开源、支持 30+ 工具、能从已有配置导入并互相转换的统一配置管理 CLI。Smithery 是配置市场但不支持导入/转换；各工具原生配置互不兼容。

一句话推荐结论

多工具团队或经常切换 AI 编程环境？用 rulesync 管理 .rulesync/ 这一个真相源，一次写入、按需生成各工具配置，还能导入已有配置迁移——比各工具分别维护 CLAUDE.md、.cursorrules 散落四处省心得多。