Ruler：多 AI 编程助手统一配置管理方案

TL;DR

当你需要频繁在 Kilocode、OpenCode、Claude、Codex、GitHub Copilot 等多个 AI 编程助手之间切换时，Ruler 是你的最佳选择：

• 单一数据源：集中管理所有 AI 编程助手的 instructions
• 自动分发：一键将配置分发到各个编程助手的专属文件
• MCP 配置管理：统一管理 Model Context Protocol 服务器配置
• Skills 支持：集中管理并分发 Agent Skills 到各个工具
• 嵌套规则加载：支持复杂项目结构的分层配置管理
• 自动维护 .gitignore：保持项目目录整洁

背景：从混乱到标准化的演进

曾经的痛点

在我写《AGENTS.md：统一编码助手指令文件的新标准》那篇文章时，提到过 intellectronica/ruler 这个项目。当时实际上我并没有频繁使用这个工具，因为我主要使用的是单一的编程助手。

但现在情况不同了。

随着 AI 编程助手的爆发式增长，我需要频繁在多个工具之间切换：

• Kilocode - 日常编码和快速原型
• Claude - 深度思考和算法优化
• Codex - API 开发和文档生成
• OpenCode - 开源项目贡献

每个工具都有自己的：

• Instructions 文件位置和格式
• MCP 服务器配置方式
• Agent Skills 目录结构
• 特定的功能和配置项

AGENTS.md 解决了什么？没解决什么？

AGENTS.md 标准的出现（Google、OpenAI、Factory、Sourcegraph 和 Cursor 联合推出），统一了 instructions 文件的名称和位置。这是一个重大进步，项目根目录不再混乱。

AGENTS.md 解决的问题：

• 统一了 instructions 文件名（都叫 AGENTS.md）
• 统一了文件位置（项目根目录）
• 提供了标准的内容格式建议

AGENTS.md 没有解决的问题：

• MCP 服务器配置仍然各自为政
  • Cursor 使用 .cursor/mcp.json
  • Claude 使用 .mcp.json
  • Windsurf 使用 .windsurf/mcp_config.json
  • Codex 使用 .codex/config.toml
• Agent Skills 目录结构不统一
  • Claude/Copilot/Kilocode 使用 .claude/skills/
  • Codex 使用 .codex/skills/
  • OpenCode 使用 .opencode/skill/
  • Goose/Amp 使用 .agents/skills/
• 特定工具的额外配置文件
  • Aider 的 .aider.conf.yml
  • Cline 的 .clinerules
  • Crush 的 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               # 自动更新，忽略生成的文件

关键特性

1. 集中式规则管理

   • 所有 instructions 都放在 .ruler/ 目录
   • 支持多个 Markdown 文件，自动合并
   • 文件发现和加载顺序可预测

2. 嵌套规则加载（Nested Rule Loading）

   • 支持复杂项目的分层配置
   • 适用于 Monorepo 和多组件项目
   • 不同目录可以有特定的上下文规则

3. 自动分发配置

   • 一键生成各个工具的配置文件
   • 支持 30+ 种 AI 编程助手
   • 可按需选择要配置的工具

4. MCP 服务器管理

   • 在 ruler.toml 中统一定义 MCP 服务器
   • 自动分发到各工具的配置文件
   • 支持 merge 和 overwrite 两种策略

5. Agent Skills 分发

   • 集中管理 Skills 在 .ruler/skills/
   • 自动复制到各工具的 skills 目录
   • 支持嵌套的 Skills 结构

6. 自动 .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

文件加载顺序和优先级：

1. 项目根目录的 AGENTS.md（如果存在，最高优先级）
2. .ruler/AGENTS.md（新标准，推荐）
3. .ruler/instructions.md（旧版，向后兼容）
4. .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.toml
nested = true

或使用 CLI 参数：

ruler apply --nested

适用场景：

• Monorepo 项目（多个服务/包）
• 前后端分离项目
• 多团队协作（不同区域有不同标准）
• 大型复杂代码库

3. MCP 服务器配置

为什么重要？

Model Context Protocol (MCP) 为 AI 模型提供额外的上下文和能力：文件系统访问、Git 操作、远程 API 调用、数据库查询等。但每个工具的 MCP 配置格式都不同，Ruler 统一管理。

配置示例：

# .ruler/ruler.toml

[mcp]
enabled = true
merge_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

安装和快速入门

安装

# 全局安装（推荐）
npm install -g @intellectronica/ruler

# 或使用 npx（一次性）
npx @intellectronica/ruler apply

要求：Node.js ^20.19.0 || ^22.12.0 || >=23

项目初始化

# 进入项目目录
cd your-project

# 初始化 Ruler
ruler init

这会创建 .ruler/ 目录、AGENTS.md 和 ruler.toml 配置文件。

实战指南

场景 1：基础使用

1. 创建配置：

ruler init

2. 编辑规则：

# .ruler/AGENTS.md

## 项目概述
这是一个 TypeScript + React 项目，使用 Vite 构建。

## 代码规范
- 使用 TypeScript strict 模式
- 组件使用函数式写法，优先使用 hooks
- 使用 ESLint 和 Prettier
- 所有导出函数必须有 JSDoc 注释

## 测试要求
- 每个功能必须有单元测试
- 使用 Vitest 作为测试框架
- 测试覆盖率不低于 80%

3. 应用到所有工具：

ruler apply

场景 2：只配置特定工具

# 只配置 Cursor 和 Claude
ruler 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-design
cat > .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 --nested

Ruler 会自动发现所有嵌套的 .ruler/ 目录并合并规则。

与其他方案对比

Ruler vs. AGENTS.md 标准

推荐使用场景：

使用 AGENTS.md 即可：

• 只使用 1-2 个 AI 编程助手
• 不需要 MCP 服务器配置
• 不使用 Agent Skills
• 项目结构简单

Ruler 更适合：

• 频繁切换多个 AI 工具
• 需要统一管理 MCP 配置
• 使用 Agent Skills
• Monorepo 或复杂项目结构
• 团队协作，需要标准化配置

最佳实践：结合使用

1. 使用 AGENTS.md 标准（统一文件名和位置）
2. 使用 Ruler 管理配置（MCP、Skills、嵌套规则）
3. 将 .ruler/ 目录提交到版本控制
4. 团队成员只需运行 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.toml
cp -r team-configs/skills/* .ruler/skills/
ruler apply

总结

AGENTS.md 标准统一了 instructions 文件的名称和位置，但 MCP 配置、Agent Skills 管理和嵌套规则等问题依然需要手动处理。Ruler 以 " 单一数据源 " 的理念填补了这个空白，支持 30+ 种 AI 编程助手的自动化配置管理，特别适合频繁切换多个工具、使用复杂项目结构或需要团队标准化的场景。通过一键 ruler apply 命令，你可以将集中管理的配置自动分发到各个工具，大幅降低维护成本，让配置管理回归简单。