Ruler:多 AI 编程助手统一配置管理方案
- 2026-01-31 19:13:18
TL;DR
当你需要频繁在 Kilocode、OpenCode、Claude、Codex、GitHub Copilot 等多个 AI 编程助手之间切换时，Ruler[1] 是你的最佳选择：
单一数据源：集中管理所有 AI 编程助手的 instructions 自动分发：一键将配置分发到各个编程助手的专属文件 MCP 配置管理：统一管理 Model Context Protocol 服务器配置 Skills 支持：集中管理并分发 Agent Skills 到各个工具 嵌套规则加载：支持复杂项目结构的分层配置管理 自动维护 .gitignore：保持项目目录整洁
背景：从混乱到标准化的演进
曾经的痛点
在我写《AGENTS.md：统一编码助手指令文件的新标准[2] 这个项目。当时实际上我并没有频繁使用这个工具，因为我主要使用的是单一的编程助手。
但现在情况不同了。
随着 AI 编程助手的爆发式增长，我需要频繁在多个工具之间切换：
Kilocode - 日常编码和快速原型 Claude - 深度思考和算法优化 Codex - API 开发和文档生成 OpenCode - 开源项目贡献
每个工具都有自己的：
Instructions 文件位置和格式 MCP 服务器配置方式 Agent Skills 目录结构 特定的功能和配置项
AGENTS.md 解决了什么？没解决什么？
AGENTS.md[3] 标准的出现（Google、OpenAI、Factory、Sourcegraph 和 Cursor 联合推出），统一了 instructions 文件的名称和位置。这是一个重大进步，项目根目录不再混乱。
AGENTS.md 解决的问题：
统一了 instructions 文件名（都叫 AGENTS.md） 统一了文件位置（项目根目录） 提供了标准的内容格式建议
AGENTS.md 没有解决的问题：
MCP 服务器配置仍然各自为政 Cursor 使用 .cursor/mcp.jsonClaude 使用 .mcp.jsonWindsurf 使用 .windsurf/mcp_config.jsonCodex 使用 .codex/config.tomlAgent Skills 目录结构不统一 Claude/Copilot/Kilocode 使用 .claude/skills/Codex 使用 .codex/skills/OpenCode 使用 .opencode/skill/Goose/Amp 使用 .agents/skills/特定工具的额外配置文件 Aider 的 .aider.conf.ymlCline 的 .clinerulesCrush 的 CRUSH.md没有便捷的管理和同步机制
这就是 Ruler 依然不可或缺的原因。
Ruler 是什么？
Ruler 是一个命令行工具，提供 单一数据源（Single Source of Truth） 来管理所有 AI 编程助手的配置。
核心理念
统一由 Ruler 管理内容：
.ruler/ # 单一数据源├── AGENTS.md # 主指令文件├── coding_style.md # 代码风格指南├── api_guidelines.md # API 设计规范├── ruler.toml # Ruler 配置└── skills/ # 集中管理的 Skills ├── my-skill/ │ └── SKILL.md └── another-skill/ └── SKILL.md执行 ruler apply 命令生成并分发到各工具的专属文件：
AGENTS.md # 分发给所有支持的工具.cursor/mcp.json # Cursor 的 MCP 配置.mcp.json # Claude 的 MCP 配置.codex/config.toml # Codex 的 MCP 配置.claude/skills/ # Claude/Copilot/Kilocode 的 Skills.codex/skills/ # Codex 的 Skills.opencode/skill/ # OpenCode 的 Skills.gitignore # 自动更新，忽略生成的文件关键特性
集中式规则管理
所有 instructions 都放在 .ruler/目录支持多个 Markdown 文件，自动合并 文件发现和加载顺序可预测 嵌套规则加载（Nested Rule Loading）
支持复杂项目的分层配置 适用于 Monorepo 和多组件项目 不同目录可以有特定的上下文规则 自动分发配置
一键生成各个工具的配置文件 支持 30+ 种 AI 编程助手 可按需选择要配置的工具 MCP 服务器管理
在 ruler.toml中统一定义 MCP 服务器自动分发到各工具的配置文件 支持 merge 和 overwrite 两种策略 Agent Skills 分发
集中管理 Skills 在 .ruler/skills/自动复制到各工具的 skills 目录 支持嵌套的 Skills 结构 自动 .gitignore 管理
自动添加生成文件到 .gitignore 使用标记块管理，不影响其他内容 保持项目仓库整洁
核心概念详解
1. .ruler/ 目录结构
.ruler/├── AGENTS.md # 主指令文件（新标准）├── instructions.md # 旧版支持（向后兼容）├── ruler.toml # Ruler 配置文件├── coding_style.md # 额外的规则文件├── api_conventions.md # API 设计规范└── skills/ # Skills 目录 ├── skill-1/ │ └── SKILL.md # 必需 └── skill-2/ └── SKILL.md文件加载顺序和优先级：
项目根目录的 AGENTS.md（如果存在，最高优先级）.ruler/AGENTS.md（新标准，推荐）.ruler/instructions.md（旧版，向后兼容）.ruler/下的其他.md文件（按字母顺序）
所有文件内容会被合并，每个文件前会自动添加来源标记。
2. 嵌套规则加载（Nested Rules）
这是 Ruler 的杀手级特性，特别适合复杂项目。
使用场景：
my-monorepo/├── .ruler/ # 全局规则│ ├── AGENTS.md│ └── global_standards.md├── frontend/│ └── .ruler/ # 前端特定规则│ └── react_guidelines.md├── backend/│ └── .ruler/ # 后端特定规则│ └── api_standards.md└── docs/ └── .ruler/ # 文档写作规则 └── writing_style.md启用方式：
# .ruler/ruler.tomlnested = true或使用 CLI 参数：
ruler apply --nested适用场景：
Monorepo 项目（多个服务/包） 前后端分离项目 多团队协作（不同区域有不同标准） 大型复杂代码库
3. MCP 服务器配置
为什么重要？
Model Context Protocol (MCP) 为 AI 模型提供额外的上下文和能力：文件系统访问、Git 操作、远程 API 调用、数据库查询等。但每个工具的 MCP 配置格式都不同，Ruler 统一管理。
配置示例：
# .ruler/ruler.toml[mcp]enabled = truemerge_strategy = "merge" # 或 "overwrite"# 本地 stdio 服务器[mcp_servers.filesystem]command = "npx"args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]# Git 服务器[mcp_servers.git]command = "npx"args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]# 远程服务器[mcp_servers.api]url = "https://mcp.example.com"[mcp_servers.api.headers]Authorization = "Bearer your-token"Ruler 会自动将 MCP 配置转换为各工具的格式并分发。
4. Agent Skills 管理
什么是 Agent Skills？
Agent Skills 是 AI 代理的可复用能力包，类似于软件的插件系统。详见我的另一篇文章《Agent Skills 深度解析：为 AI 代理构建可复用的技能生态系统》。
Ruler 的 Skills 管理：
.ruler/skills/├── obsidian-workflow/│ ├── SKILL.md # 必需：技能说明│ ├── templates/ # 可选：模板文件│ └── scripts/ # 可选：辅助脚本└── api-design/ ├── SKILL.md └── examples/Ruler 会将 Skills 自动复制到各工具的 skills 目录（.claude/skills/、.codex/skills/、.opencode/skill/ 等）。
支持的 AI 编程助手
Ruler 支持 30+ 种 AI 编程助手，包括：
常用工具：
GitHub Copilot Claude Code Cursor Kilo Code OpenCode Codex
完整列表详见：Ruler GitHub[4]
安装和快速入门
安装
# 全局安装（推荐）npm install -g @intellectronica/ruler# 或使用 npx（一次性）npx @intellectronica/ruler apply要求：Node.js ^20.19.0 || ^22.12.0 || >=23
项目初始化
# 进入项目目录cd your-project# 初始化 Rulerruler init这会创建 .ruler/ 目录、AGENTS.md 和 ruler.toml 配置文件。
实战指南
场景 1：基础使用
创建配置：
ruler init编辑规则：
# .ruler/AGENTS.md## 项目概述这是一个 TypeScript + React 项目，使用 Vite 构建。## 代码规范- 使用 TypeScript strict 模式- 组件使用函数式写法，优先使用 hooks- 使用 ESLint 和 Prettier- 所有导出函数必须有 JSDoc 注释## 测试要求- 每个功能必须有单元测试- 使用 Vitest 作为测试框架- 测试覆盖率不低于 80%应用到所有工具：
ruler apply场景 2：只配置特定工具
# 只配置 Cursor 和 Clauderuler apply --agents cursor,claude# 查看详细输出ruler apply --agents cursor,claude --verbose场景 3：配置 MCP 服务器
编辑 .ruler/ruler.toml：
[mcp]enabled = true[mcp_servers.filesystem]command = "npx"args = ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"][mcp_servers.git]command = "npx"args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]然后应用配置：
ruler apply --mcp场景 4：管理 Agent Skills
创建 Skills：
mkdir -p .ruler/skills/api-designcat > .ruler/skills/api-design/SKILL.md << 'EOF'# API Design Guidelines## REST API 设计原则1. **资源命名** - 使用名词复数形式：`/users`, `/products` - 避免动词2. **HTTP 方法** - GET：获取资源 - POST：创建资源 - PUT：完整更新资源 - PATCH：部分更新资源 - DELETE：删除资源EOF应用 Skills：
ruler apply --skills场景 5：Monorepo 嵌套规则
在 .ruler/ruler.toml 中启用：
nested = true然后从项目根目录运行：
ruler apply --nestedRuler 会自动发现所有嵌套的 .ruler/ 目录并合并规则。
与其他方案对比
Ruler vs. AGENTS.md 标准
| Instructions 统一 | ||
| MCP 配置 | ||
| Skills 管理 | ||
| 嵌套规则 | ||
| 自动化 | ||
| 学习成本 |
推荐使用场景：
使用 AGENTS.md 即可：
只使用 1-2 个 AI 编程助手 不需要 MCP 服务器配置 不使用 Agent Skills 项目结构简单
Ruler 更适合：
频繁切换多个 AI 工具 需要统一管理 MCP 配置 使用 Agent Skills Monorepo 或复杂项目结构 团队协作，需要标准化配置
最佳实践：结合使用
使用 AGENTS.md 标准（统一文件名和位置） 使用 Ruler 管理配置（MCP、Skills、嵌套规则） 将 .ruler/目录提交到版本控制团队成员只需运行 ruler apply
团队协作建议
1. 提交 .ruler/ 到版本控制
# .gitignore# 生成的文件由 Ruler 自动管理，不提交AGENTS.md.cursor/mcp.json.mcp.json.claude/skills/# .ruler/ 目录提交到版本控制!.ruler/2. NPM Scripts 集成
{"scripts": {"ruler:apply": "ruler apply","ruler:check": "ruler apply --dry-run","postinstall": "npm run ruler:apply" }}3. 团队标准化
创建团队配置模板：
team-configs/├── ruler-templates/│ ├── frontend.toml│ ├── backend.toml│ └── fullstack.toml└── skills/ ├── company-api-design/ └── security-guidelines/项目初始化时复制团队配置：
cp team-configs/ruler-templates/frontend.toml .ruler/ruler.tomlcp -r team-configs/skills/* .ruler/skills/ruler apply总结
AGENTS.md 标准统一了 instructions 文件的名称和位置，但 MCP 配置、Agent Skills 管理和嵌套规则等问题依然需要手动处理。Ruler 以 " 单一数据源 " 的理念填补了这个空白，支持 30+ 种 AI 编程助手的自动化配置管理，特别适合频繁切换多个工具、使用复杂项目结构或需要团队标准化的场景。通过一键 ruler apply 命令，你可以将集中管理的配置自动分发到各个工具，大幅降低维护成本，让配置管理回归简单。
Ruler: https://github.com/intellectronica/ruler
[2]AGENTS.md：统一编码助手指令文件的新标准: https://mp.weixin.qq.com/s/6ZEGcGzt-Nsb1h354ySscg
[3]AGENTS.md: https://agents.md/
[4]Ruler GitHub: https://github.com/intellectronica/ruler
