Ruler：集中管理您的 AI 编码助手指令

GitHub: intellectronica/ruler NPM: @intellectronica/ruler 动画由Elite AI-Assisted Coding 的 Isaac Flath 制作 ➡︎

---

测试版研究预览

• 请在您的环境中仔细测试此版本
• 如发现问题，请前往 https://github.com/intellectronica/ruler/issues 报告

为什么选择 Ruler？

随着团队规模的扩大，跨多个 AI 编码工具管理指令会变得复杂。不同的 AI 助手（如 GitHub Copilot、Claude、Cursor、Aider 等）需要各自的配置文件，这会导致：

• AI 工具之间的指导不一致
• 维护多个配置文件的重复工作
• 项目需求变化时的上下文偏差
• 新 AI 工具的上手难度增加
• 复杂的项目结构需要针对不同组件的特定上下文指令

Ruler 通过提供所有 AI 助手指令的单一可信源来解决这些问题，并自动将这些指令分发到相应的配置文件中。借助嵌套规则加载功能，Ruler 能够处理复杂的项目结构，为不同组件提供特定于上下文的指令。

核心功能

• 集中式规则管理：使用 Markdown 文件将所有 AI 指令存储在一个专用的 .ruler/ 目录中
• 嵌套规则加载：支持复杂的项目结构，允许为不同上下文设置多个 .ruler/ 目录
• 自动分发：Ruler 会将这些规则应用到受支持的 AI 助手的配置文件中
• 目标明确的助手配置：通过 ruler.toml 文件精确控制受影响的助手及其特定的输出路径
• MCP 服务器传播：管理和分发模型上下文协议（MCP）服务器设置
• .gitignore 自动化：自动生成的助手配置文件会自动排除在版本控制之外
• 简洁的命令行界面：提供易于使用的命令来初始化和应用配置

支持的 AI 代理

代理	规则文件(s)	MCP 配置 / 备注	技能支持 / 位置
AGENTS.md	AGENTS.md	（伪代理，确保根目录存在 AGENTS.md）	-
GitHub Copilot	AGENTS.md	.vscode/mcp.json	.claude/skills/
Claude Code	CLAUDE.md	.mcp.json	.claude/skills/
OpenAI Codex CLI	AGENTS.md	.codex/config.toml	.codex/skills/
Pi 编码代理	AGENTS.md	-	.pi/skills/
Jules	AGENTS.md	-	-
Cursor	AGENTS.md	.cursor/mcp.json	.cursor/skills/
Windsurf	AGENTS.md	.windsurf/mcp_config.json	.windsurf/skills/
Cline	.clinerules	-	-
Crush	CRUSH.md	.crush.json	-
Amp	AGENTS.md	-	.agents/skills/
Antigravity	.agent/rules/ruler.md	-	.agent/skills/
Amazon Q CLI	.amazonq/rules/ruler_q_rules.md	.amazonq/mcp.json	-
Aider	AGENTS.md, .aider.conf.yml	.mcp.json	-
Firebase Studio	.idx/airules.md	.idx/mcp.json	-
Open Hands	.openhands/microagents/repo.md	config.toml	-
Gemini CLI	AGENTS.md	.gemini/settings.json	.gemini/skills/
Junie	.junie/guidelines.md	.junie/mcp/mcp.json	.junie/skills/
AugmentCode	.augment/rules/ruler_augment_instructions.md	-	-
Kilo Code	AGENTS.md	.kilocode/mcp.json	.claude/skills/
OpenCode	AGENTS.md	opencode.json	.opencode/skills/
Goose	.goosehints	-	.agents/skills/
Qwen Code	AGENTS.md	.qwen/settings.json	-
RooCode	AGENTS.md	.roo/mcp.json	.roo/skills/
Zed	AGENTS.md	.zed/settings.json（项目根目录，不在 $HOME）	-
Trae AI	.trae/rules/project_rules.md	-	-
Warp	WARP.md	-	-
Kiro	.kiro/steering/ruler_kiro_instructions.md	.kiro/settings/mcp.json	-
Firebender	firebender.json	firebender.json（规则和 MCP 在同一文件中）	-
Factory Droid	AGENTS.md	.factory/mcp.json	.factory/skills/
Mistral Vibe	AGENTS.md	.vibe/config.toml	.vibe/skills/
JetBrains AI Assistant	.aiassistant/rules/AGENTS.md	-	-

开始使用

安装

需要 Node.js ^20.19.0 || ^22.12.0 || >=23。

全局安装（推荐用于 CLI 使用）：

npm install -g @intellectronica/ruler

使用 npx（用于一次性命令）：

npx @intellectronica/ruler apply

项目初始化

1. 导航到您的项目根目录
2. 运行 ruler init
3. 这将创建：

• .ruler/ 目录
• .ruler/AGENTS.md：您规则的主要入门 Markdown 文件
• .ruler/ruler.toml：Ruler 的主配置文件（现在包含示例 MCP 服务器部分；旧版 .ruler/mcp.json 不再自动生成）
• （可选的旧版回退）如果您之前使用过 .ruler/instructions.md，在缺少 AGENTS.md 时仍会生效。（之前的运行时警告已被移除。）

此外，您还可以创建一个全局配置，在未找到本地 .ruler/ 目录时使用：

ruler init --global

全局配置将被创建到 $XDG_CONFIG_HOME/ruler（默认：~/.config/ruler）。

核心概念

.ruler/ 目录

这是您所有 AI 代理指令的中央枢纽：

• 主要文件顺序与优先级：
  1. 如果存在，仓库根目录下的 AGENTS.md（位于 .ruler/ 外部）（优先级最高，会前置插入）
  2. .ruler/AGENTS.md（新的默认起始文件）
  3. 旧版的 .ruler/instructions.md（仅当 .ruler/AGENTS.md 不存在时使用；不再发出弃用警告）
  4. 在 .ruler/ 及其子目录中按排序顺序发现的其余 .md 文件
• 规则文件（*.md）：从 .ruler/ 或 $XDG_CONFIG_HOME/ruler 中递归发现，并按照上述顺序拼接。
• 拼接标记：每个文件的内容前都会添加 <!-- Source: <relative_path_to_md_file> -->，以便追踪来源。
• ruler.toml：Ruler 行为、代理选择、输出路径以及 MCP 服务器设置的主配置文件。
• mcp.json：（旧版，已弃用）共享的 MCP 服务器设置——不再自动生成，但仍为向后兼容而保留。

这种顺序设计允许您在根目录下保留一份简短但极具影响力的 AGENTS.md 文件（例如项目高层概要），同时将详细指导内容存放在 .ruler/ 中。

嵌套规则加载

Ruler 现在支持通过 --nested 标志进行嵌套规则加载，从而为项目的不同部分提供特定于上下文的指令：

project/
├── .ruler/           # 全局项目规则
│   ├── AGENTS.md
│   └── coding_style.md
├── src/
│   └── .ruler/       # 组件特定规则
│       └── api_guidelines.md
├── tests/
│   └── .ruler/       # 测试特定规则
│       └── testing_conventions.md
└── docs/
    └── .ruler/       # 文档规则
        └── writing_style.md

工作原理：

• 发现项目层级中的所有 .ruler/ 目录。
• 按照顺序加载并拼接每个目录中的规则。
• 是否启用嵌套模式由以下优先级决定：
  1. ruler apply --nested（或 --no-nested）具有最高优先级。
  2. ruler.toml 中的 nested = true 设置。
  3. 如果两者均未指定，则默认禁用。
• 当运行处于嵌套模式时，下游配置会被强制保持 nested = true。如果子配置尝试将其禁用，Ruler 仍会维持嵌套处理，并在日志中发出警告。
• 嵌套处理会传递每个目录自身的 MCP 包和配置设置，从而使生成的文件始终限定在其源目录范围内，同时被规范化回项目根目录。

[!CAUTION] 嵌套模式目前处于实验阶段，未来版本可能会发生变化。CLI 会在首次检测到嵌套运行时记录此警告，以提醒您该行为可能随时间演进。

适用场景：

• 包含多个服务的单体代码库。
• 具有明确组件划分的项目（如前端/后端）。
• 需要针对不同领域制定不同指令的团队。
• 规范要求各异的复杂代码库。

规则文件的最佳实践

粒度化：将复杂的指令拆分为专注的 .md 文件：

• coding_style.md
• api_conventions.md
• project_architecture.md
• security_guidelines.md

规则文件示例（.ruler/python_guidelines.md）：

# Python 项目指南

## 通用风格

- 所有 Python 代码应遵循 PEP 8 规范。
- 所有函数签名及复杂变量应使用类型注解。
- 函数应尽量简短，专注于单一任务。

## 错误处理

- 应使用具体的异常类型，而非通用的 `Exception`。
- 记录错误时需包含上下文信息。

## 安全性

- 始终对用户输入进行验证和清理。
- 注意潜在的注入漏洞。

使用方法：apply 命令

主命令

ruler apply [options]

apply 命令会在当前目录树中查找 .ruler/，并读取第一个匹配项。若未找到此类目录，则会搜索 $XDG_CONFIG_HOME/ruler 中的全局配置。

选项

选项	描述
--project-root <path>	项目根目录路径（默认：当前目录）。
--agents <agent1,agent2,...>	以逗号分隔的目标代理名称列表（参见下方支持列表）。
--config <path>	自定义 ruler.toml 路径。
--mcp / --with-mcp	启用应用 MCP 服务器配置（默认：开启）。
--no-mcp	禁用应用 MCP 服务器配置。
--mcp-overwrite	覆盖原生 MCP 配置，而非合并。
--gitignore	启用自动更新 .gitignore 文件（默认：开启）。
--no-gitignore	禁用自动更新 .gitignore 文件。
--gitignore-local	将管理的忽略条目写入 .git/info/exclude 文件中，而非 .gitignore。
--nested	启用嵌套规则加载（默认：继承配置设置或禁用）。
--no-nested	即使配置中设置了 nested = true，也禁用嵌套规则加载。
--backup	启用创建 .bak 备份文件（默认：开启）。
--no-backup	禁用创建 .bak 备份文件。
--skills	启用技能支持（实验性功能，默认：开启）。
--no-skills	禁用技能支持。
--dry-run	预览更改而不实际写入文件。
--local-only	查找配置时跳过 $XDG_CONFIG_HOME。
--verbose / -v	在执行过程中显示详细输出。

常见示例

为所有已配置的代理应用规则：

ruler apply

仅为 GitHub Copilot 和 Claude 应用规则：

ruler apply --agents copilot,claude

仅为 Firebase Studio 应用规则：

ruler apply --agents firebase

仅为 Warp 应用规则：

ruler apply --agents warp

仅为 Trae AI 应用规则：

ruler apply --agents trae

仅为 RooCode 应用规则：

ruler apply --agents roo

使用特定配置文件：

ruler apply --config ./team-configs/ruler.frontend.toml

以详细模式应用规则：

ruler apply --verbose

应用规则但跳过 MCP 和 .gitignore 更新：

ruler apply --no-mcp --no-gitignore

使用方法：revert 命令

revert 命令可以安全地撤销由 ruler apply 所做的所有更改，将您的项目恢复到应用规则之前的初始状态。它会智能地从备份文件（.bak 文件）中恢复文件（如果存在），或者移除那些原本不存在的生成文件。

为什么需要使用 revert？

在尝试不同的规则配置或切换不同项目时，您可能希望：

• 清空所有内容：移除所有由 Ruler 生成的文件，以便重新开始。
• 恢复原始文件：将被修改的文件恢复为它们的原始状态。
• 选择性清理：仅移除特定代理的配置。
• 安全实验：在不用担心永久性更改的情况下试用 Ruler。

主要命令

ruler revert [选项]

选项

选项	描述
--project-root <路径>	指定项目的根目录路径（默认为当前目录）
--agents <agent1,agent2,...>	以逗号分隔的代理名称列表，用于指定要还原的代理（agentsmd、aider、amazonqcli、amp、antigravity、augmentcode、claude、cline、codex、copilot、crush、cursor、factory、firebase、firebender、gemini-cli、goose、jetbrains-ai、jules、junie、kilocode、kiro、mistral、opencode、openhands、pi、qwen、roo、trae、warp、windsurf、zed）
--config <路径>	自定义 ruler.toml 配置文件的路径
--keep-backups	在恢复后保留备份文件（.bak 文件）（默认为不保留）
--dry-run	预览将要执行的更改，但不会实际还原文件
--verbose / -v	在执行过程中显示详细输出
--local-only	仅搜索本地 .ruler 目录，忽略全局配置

常见示例

还原所有 Ruler 更改：

ruler revert

预览将要还原的内容（模拟运行）：

ruler revert --dry-run

仅还原特定代理：

ruler revert --agents claude,copilot

以详细模式还原：

ruler revert --verbose

在还原后保留备份文件：

ruler revert --keep-backups

配置文件 (ruler.toml) 详解

位置

默认位于项目根目录下的 .ruler/ruler.toml。可以通过 --config CLI 选项进行覆盖。

完整示例

# 当未指定 --agents 时，默认运行的代理
# 使用不区分大小写的子字符串匹配
default_agents = ["copilot", "claude", "aider"]

# --- 全局 MCP 服务器配置 ---
[mcp]
# 全局启用或禁用 MCP 传播（默认：启用）
enabled = true
# 全局合并策略：'merge' 或 'overwrite'（默认：'merge'）
merge_strategy = "merge"

# --- MCP 服务器定义 ---
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]

[mcp_servers.remote_api]
url = "https://api.example.com"

[mcp_servers.remote_api.headers]
Authorization = "Bearer your-token"

# --- 全局 .gitignore 配置 ---
[gitignore]
# 启用或禁用自动更新 .gitignore（默认：启用）
enabled = true
# 将受管理的条目写入 .git/info/exclude 而不是 .gitignore（默认：不启用）
local = false

# --- 代理特定配置 ---
[agents.copilot]
enabled = true

[agents.claude]
enabled = true
output_path = "CLAUDE.md"

[agents.aider]
enabled = true
output_path_instructions = "AGENTS.md"
output_path_config = ".aider.conf.yml"

# OpenAI Codex CLI 代理及 MCP 配置
[agents.codex]
enabled = true
output_path = "AGENTS.md"
output_path_config = ".codex/config.toml"

# Codex CLI 的代理特定 MCP 配置
[agents.codex.mcp]
enabled = true
merge_strategy = "merge"

[agents.firebase]
enabled = true
output_path = ".idx/airules.md"

[agents.gemini-cli]
enabled = true

[agents.jules]
enabled = true

[agents.junie]
enabled = true
output_path = ".junie/guidelines.md"

[agents.junie.mcp]
enabled = true
merge_strategy = "merge"

# 代理特定的 MCP 配置
[agents.cursor.mcp]
enabled = true
merge_strategy = "merge"

# 禁用特定代理
[agents.windsurf]
enabled = false

[agents.kilocode]
enabled = true
output_path = "AGENTS.md"

[agents.warp]
enabled = true
output_path = "WARP.md"

配置优先级

1. CLI 标志（例如 --agents、--no-mcp、--mcp-overwrite、--no-gitignore）
2. ruler.toml 中的设置（default_agents、特定代理设置、全局部分）
3. Ruler 的内置默认值（所有代理均启用、标准输出路径、MCP 默认启用且采用 'merge' 策略）

MCP（模型上下文协议）服务器配置

MCP 通过服务器配置为 AI 模型提供更广泛的上下文信息。Ruler 可以管理和分发这些设置到兼容的代理中。

TOML 配置（推荐）

现在您可以在 ruler.toml 中直接使用 [mcp_servers.<name>] 语法定义 MCP 服务器：

# 全局 MCP 行为
[mcp]
enabled = true
merge_strategy = "merge"  # 或者 "overwrite"

# 本地（stdio）服务器
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

[mcp_servers.filesystem.env]
API_KEY = "your-api-key"

# 远程服务器
[mcp_servers.search]
url = "https://mcp.example.com"

[mcp_servers.search.headers]
Authorization = "Bearer your-token"
"X-API-Version" = "v1"

旧版 .ruler/mcp.json（已弃用）

为了向后兼容，您仍然可以使用 JSON 格式；系统会发出警告，鼓励迁移到 TOML 格式。该文件在执行 ruler init 时将不再创建。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project"
      ]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
    }
  }
}

配置优先级

当同时存在 TOML 和 JSON 配置时：

1. TOML 服务器优先于同名的 JSON 服务器。
2. 服务器配置合并自两个来源（除非使用覆盖策略）。
3. 弃用警告会提示您迁移至 TOML 格式（每运行一次显示一次警告）。

服务器类型

本地/stdio 服务器需要 command 字段：

[mcp_servers.local_server]
command = "node"
args = ["server.js"]

[mcp_servers.local_server.env]
DEBUG = "1"

远程服务器需要 url 字段（头部信息可选；对于 OpenHands，如果可能的话，会自动提取 Bearer 授权令牌）：

[mcp_servers.remote_server]
url = "https://api.example.com"

[mcp_servers.remote_server.headers]
Authorization = "Bearer token"

Ruler 使用此配置，并根据 ruler.toml 或 CLI 标志控制的 merge（默认）或 overwrite 策略来处理。

主目录安全性： Ruler 绝不会在您的项目根目录之外写入 MCP 配置文件。任何涉及用户主目录的历史引用（例如 ~/.codeium/windsurf/mcp_config.json 或 ~/.zed/settings.json）已被移除；仅针对项目本地路径进行操作。

OpenAI Codex CLI 注意事项： 若要应用本地 Codex CLI 的 MCP 配置，请将 CODEX_HOME 环境变量设置为您项目的 .codex 目录：

export CODEX_HOME="$(pwd)/.codex"

技能支持（实验性）

⚠️ 实验性功能： 技能支持目前处于实验阶段。技能只会传播到具有原生技能支持的代理；其他代理则会被跳过，并显示警告。

Ruler 可以管理和传播技能到受支持的 AI 代理。技能存储在 .ruler/skills/ 目录中，当您运行 ruler apply 时，它们会自动分发给兼容的代理。

工作原理

技能是专门的知识包，能够通过领域特定的专业知识、工作流程或工具集成来扩展 AI 代理的能力。Ruler 会在您的 .ruler/skills/ 目录中发现技能，并将其传播到兼容的代理：

• 具有原生技能支持的代理： 技能会直接复制到每个代理的原生技能目录中：
  • Claude Code： .claude/skills/
  • GitHub Copilot： .claude/skills/（与 Claude Code 共享）
  • Kilo Code： .claude/skills/（与 Claude Code 共享）
  • OpenAI Codex CLI： .codex/skills/
  • OpenCode： .opencode/skills/
  • Pi Coding Agent： .pi/skills/
  • Goose： .agents/skills/
  • Amp： .agents/skills/（与 Goose 共享）
  • Antigravity： .agent/skills/
  • Factory Droid： .factory/skills/
  • Mistral Vibe： .vibe/skills/
  • Roo Code： .roo/skills/
  • Gemini CLI： .gemini/skills/
  • Junie： .junie/skills/
  • Cursor： .cursor/skills/
  • Windsurf： .windsurf/skills/

技能目录结构

技能可以采用扁平化或嵌套式组织：

.ruler/skills/
├── my-skill/
│   ├── SKILL.md           # 必需：技能说明/知识
│   ├── helper.py          # 可选：附加资源（脚本）
│   └── reference.md       # 可选：附加资源（文档）
└── another-skill/
    └── SKILL.md

每个技能必须包含：

• SKILL.md - 主要技能文件，包含说明或知识库。

技能还可以选择性地包含以下附加资源：

• 带有补充文档的 Markdown 文件
• Python、JavaScript 或其他脚本
• 配置文件或数据

配置

技能支持默认启用，但可以通过以下方式控制：

CLI 标志：

# 启用技能（默认）
ruler apply --skills

# 禁用技能
ruler apply --no-skills

ruler.toml 中的配置：

[skills]
enabled = true  # 或 false 以禁用

非原生代理

如果您为不支持原生技能的代理运行 Ruler，Ruler 将记录警告，并跳过对这些代理的技能传播。

.gitignore 集成

当技能支持启用且 .gitignore 集成生效时，Ruler 会自动将以下目录添加到您管理的 Ruler 区块内的 .gitignore 文件中：

• .claude/skills/（适用于 Claude Code、GitHub Copilot 和 Kilo Code）
• .codex/skills/（适用于 OpenAI Codex CLI）
• .opencode/skills/（适用于 OpenCode）
• .pi/skills/（适用于 Pi Coding Agent）
• .agents/skills/（适用于 Goose 和 Amp）
• .agent/skills/（适用于 Antigravity）
• .factory/skills/（适用于 Factory Droid）
• .vibe/skills/（适用于 Mistral Vibe）
• .roo/skills/（适用于 Roo Code）
• .gemini/skills/（适用于 Gemini CLI）
• .junie/skills/（适用于 Junie）
• .cursor/skills/（适用于 Cursor）
• .windsurf/skills/（适用于 Windsurf）

要求

• 对于具有原生技能支持的代理（Claude Code、GitHub Copilot、Kilo Code、OpenAI Codex CLI、OpenCode、Pi Coding Agent、Goose、Amp、Antigravity、Factory Droid、Mistral Vibe、Roo Code、Gemini CLI、Junie、Cursor、Windsurf）：无需额外要求。

验证

Ruler 会对发现的技能进行验证，并对以下情况发出警告：

• 缺少必需文件（SKILL.md）
• 目录结构无效（没有 SKILL.md 且没有子技能）

警告不会阻止传播，但有助于识别潜在问题。

模拟运行模式

在不进行实际更改的情况下测试技能传播：

ruler apply --dry-run

这将显示哪些技能会被复制。

示例工作流程

# 1. 向您的项目添加一个技能
mkdir -p .ruler/skills/my-skill
cat > .ruler/skills/my-skill/SKILL.md << 'EOF'
# 我的自定义技能

此技能提供了关于...的专业知识。

## 使用方法

在处理该项目时，请始终遵循以下指南：
- 所有新代码均使用 TypeScript
- 为所有功能编写测试
- 遵循现有代码风格
EOF

# 2. 应用到所有智能体（技能默认启用）
ruler apply

# 3. 技能现在可供兼容的智能体使用：
#    - Claude Code、GitHub Copilot 和 Kilo Code：.claude/skills/my-skill/
#    - OpenAI Codex CLI：.codex/skills/my-skill/
#    - OpenCode：.opencode/skills/my-skill/
#    - Pi 编码智能体：.pi/skills/my-skill/
#    - Goose 和 Amp：.agents/skills/my-skill/
#    - Antigravity：.agent/skills/my-skill/
#    - Factory Droid：.factory/skills/my-skill/
#    - Mistral Vibe：.vibe/skills/my-skill/
#    - Roo Code：.roo/skills/my-skill/
#    - Gemini CLI：.gemini/skills/my-skill/
#    - Junie：.junie/skills/my-skill/
#    - Cursor：.cursor/skills/my-skill/
#    - Windsurf：.windsurf/skills/my-skill/

.gitignore 集成

Ruler 会自动管理您的 .gitignore 文件，以确保生成的智能体配置文件不会被纳入版本控制。

工作原理

• 在项目根目录创建或更新 .gitignore
• 将路径添加到由 # START Ruler Generated Files 和 # END Ruler Generated Files 标记的受管区域
• 保留该区域之外的现有内容
• 按字母顺序对路径进行排序，并使用相对的 POSIX 风格路径

示例 .gitignore 部分（示例——实际列表取决于已启用的智能体）

# 您现有的规则
node_modules/
*.log

# START Ruler Generated Files
.aider.conf.yml
.clinerules
AGENTS.md
CLAUDE.md
# END Ruler Generated Files

dist/

控制选项

• CLI 标志：--gitignore、--no-gitignore、--gitignore-local、--no-gitignore-local
• 配置：ruler.toml 中的 [gitignore].enabled 和 [gitignore].local
• 默认值：启用

实际使用场景

场景 1：快速入门

# 在您的项目中初始化 Ruler
cd your-project
ruler init

# 编辑生成的文件
# - 将编码规范添加到 .ruler/AGENTS.md（或继续添加其他 .md 文件）
# - 如有必要，自定义 .ruler/ruler.toml

# 将规则应用到所有 AI 智能体
ruler apply

场景 2：具有嵌套规则的复杂项目

对于包含多个组件或服务的大型项目，可以启用嵌套规则加载，使每个目录都保留自己的规则和 MCP 包：

# 设置嵌套的 .ruler 目录
mkdir -p src/.ruler tests/.ruler docs/.ruler

# 添加组件特定的说明
echo "# API 设计指南" > src/.ruler/api_rules.md
echo "# 测试最佳实践" > tests/.ruler/test_rules.md
echo "# 文档标准" > docs/.ruler/docs_rules.md

# .ruler/ruler.toml
nested = true

# CLI 会从 ruler.toml 继承嵌套模式
ruler apply --verbose

# 可随时通过 CLI 覆盖
ruler apply --no-nested

这样可以在保持根目录 .ruler/ 中全局规则的同时，为项目的不同部分创建特定于上下文的说明。嵌套运行会自动确保每个嵌套配置都处于启用状态，即使子目录尝试将其禁用。

[!NOTE] 第一次执行嵌套处理时，CLI 会打印“嵌套模式为实验性功能，未来版本可能会更改。”预计在后续版本中会有进一步改进。

场景 3：团队标准化

1. 创建 .ruler/coding_standards.md、.ruler/api_usage.md
2. 将 .ruler 目录提交到您的仓库
3. 团队成员拉取更改并运行 ruler apply 来更新他们本地的 AI 智能体配置。

场景 4：针对项目的特定上下文使用 AI

1. 在 .ruler/project_overview.md 中详细说明项目的架构
2. 在 .ruler/data_models.md 中描述主要的数据结构
3. 运行 ruler apply 以帮助 AI 工具提供更相关的建议。

与 NPM 脚本集成

{
  "scripts": {
    "ruler:apply": "ruler apply",
    "dev": "npm run ruler:apply && your_dev_command",
    "precommit": "npm run ruler:apply"
  }
}

与 GitHub Actions 集成

# .github/workflows/ruler-check.yml
name: 检查 Ruler 配置
on:
  pull_request:
    paths: ['.ruler/**']

jobs:
  check-ruler:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 安装 Ruler
        run: npm install -g @intellectronica/ruler

      - name: 应用 Ruler 配置
        run: ruler apply --no-gitignore

      - name: 检查是否有未提交的更改
        run: |
          if [[ -n $(git status --porcelain) ]]; then
            echo "::error::Ruler 配置不同步！"
            echo "请在本地运行 'ruler apply' 并提交更改。"
            exit 1
          fi

故障排除

常见问题

“无法找到模块”错误：

• 确保已全局安装 Ruler：npm install -g @intellectronica/ruler
• 或者使用 npx @intellectronica/ruler

权限拒绝错误：

• 在 Unix 系统上，全局安装可能需要 sudo

智能体文件未更新：

• 检查智能体是否在 ruler.toml 中已启用
• 确认智能体未被 --agents 标志排除
• 使用 --verbose 查看详细的执行日志

配置验证错误：

• Ruler 现在会验证 ruler.toml 的格式，并显示具体的错误信息
• 检查所有配置值是否符合预期的类型和格式

调试模式

使用 --verbose 标志查看详细的执行日志：

ruler apply --verbose

这将显示：

• 配置加载详情
• 智能体选择逻辑
• 文件处理信息
• MCP 配置步骤

常见问题解答

问：我可以为不同的代理使用不同的规则吗？
答：目前，所有代理都会收到相同的拼接规则。如果需要针对特定代理的指令，请在规则文件中添加类似“## GitHub Copilot 特定”或“## Aider 配置”的部分。

问：如何为项目的不同部分设置不同的指令？
答：可以通过在 ruler.toml 中设置 nested = true，或者通过传递 ruler apply --nested 来启用嵌套模式。CLI 默认继承配置设置，但如果需要在某次运行中禁用嵌套模式，可以使用 --no-nested 选项。启用嵌套模式后，Ruler 会从目录层次结构中的每个 .ruler/ 目录加载规则（以及 MCP 设置），并强制子配置保持嵌套状态。如果发生任何嵌套处理，Ruler 还会记录一条警告：“嵌套模式处于实验阶段，未来版本可能会发生变化。”

问：如何临时禁用某个代理的 Ruler 功能？
答：可以在 ruler.toml 的 [agents.agentname] 下将 enabled = false，或者使用 --agents 标志来指定您希望启用的代理。

问：我现有的代理配置文件会怎样？
答：Ruler 在覆盖任何现有文件之前，会先创建带有 .bak 扩展名的备份文件。

问：我可以在 CI/CD 管道中运行 Ruler 吗？
答：可以！在 CI 中使用 ruler apply --no-gitignore 可以避免修改 .gitignore 文件。请参阅上面的 GitHub Actions 示例。

问：如何从使用 instructions.md 的旧版本迁移？
答：只需将 .ruler/instructions.md 重命名为 .ruler/AGENTS.md（推荐）。如果您保留了旧版文件而未提供 AGENTS.md，Ruler 仍会使用它（但不会发出旧版弃用警告）。如果同时存在两者，则优先使用 AGENTS.md；旧版文件的内容仍会在之后被拼接进来。

问：OpenHands MCP 传播如何对服务器进行分类？
答：本地标准输入输出服务器会被归类为 stdio_servers。包含 /sse 的远程 URL 被归类为 sse_servers；其他则被归类为 shttp_servers。如果可能的话，还会从 Authorization 头中提取 Bearer 令牌，并将其放入 api_key 字段中。

问：Zed 的配置现在写在哪里？
答：Ruler 会在项目根目录（而非用户主目录）下生成一个 settings.json 文件，并将 MCP 服务器定义转换为 Zed 的 context_servers 格式，其中包含 source: "custom"。

问：MCP 初始化有哪些变化？
答：ruler init 现在仅会在 ruler.toml 中添加示例 MCP 服务器部分，而不再创建 .ruler/mcp.json 文件。如果该 JSON 文件存在，仍然会被读取，但在名称冲突时，ruler.toml 中的服务器配置会优先生效。

问：Kiro 是否受支持？
答：是的。Kiro 会在 .kiro/steering/ruler_kiro_instructions.md 文件中接收到拼接后的规则。

开发

设置

git clone https://github.com/intellectronica/ruler.git
cd ruler
npm install
npm run build

测试

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 以监听模式运行测试
npm run test:watch

代码质量

# 运行代码检查
npm run lint

# 运行代码格式化
npm run format

贡献

欢迎贡献！请按照以下步骤操作：

1. 分支仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求

如发现错误或有功能需求，请提交问题。

许可证

MIT

---

© 埃莉诺·伯格
ai.intellectronica.net

Ruler 快速上手指南

Ruler 是一个用于集中管理 AI 编程助手指令的工具。它允许你将所有 AI Agent（如 GitHub Copilot、Claude Code、Cursor 等）的配置规则统一存储在 .ruler/ 目录中，并自动分发到各个工具对应的配置文件中，解决多工具配置不一致和维护繁琐的问题。

环境准备

• 操作系统：支持 Windows、macOS、Linux
• 运行时依赖：需要安装 Node.js
  • 版本要求：^20.19.0 或 ^22.12.0 或 >=23
• 前置检查：确保终端中可以正常执行 node -v 和 npm -v

提示：国内用户建议使用 Node.js 国内镜像 安装，或使用 nvm 进行版本管理。

安装步骤

你可以选择全局安装（推荐）或按需使用 npx。

方式一：全局安装（推荐）

适用于频繁使用 CLI 命令的场景。

npm install -g @intellectronica/ruler

加速建议：国内用户可配置 npm 镜像源加速安装：

npm config set registry https://registry.npmmirror.com
npm install -g @intellectronica/ruler

方式二：使用 npx（免安装）

适用于临时试用或单次执行场景。

npx @intellectronica/ruler apply

基本使用

1. 初始化项目

在项目根目录下运行以下命令，生成默认的配置文件结构：

ruler init

执行后将创建：

• .ruler/ 目录：存放所有 AI 指令的中心仓库
• .ruler/AGENTS.md：主要的规则文件（Markdown 格式）
• .ruler/ruler.toml：Ruler 的主配置文件，用于定义目标 Agent 和 MCP 设置

2. 编写规则

编辑 .ruler/AGENTS.md 文件，填入你希望 AI 助手遵守的通用指令。例如：

# 项目规范
- 请使用 TypeScript 编写代码
- 所有函数必须包含 JSDoc 注释
- 禁止使用任何已废弃的 API

你也可以在 .ruler/ 下创建多个 .md 文件（如 coding_style.md、security_rules.md），Ruler 会自动按顺序合并它们。

3. 应用配置

运行以下命令，将规则自动分发到项目中已检测到的 AI 工具配置文件中：

ruler apply

Ruler 会根据项目中的工具类型（如 Cursor、Copilot、Aider 等），自动更新对应的配置文件（如 AGENTS.md、.clinerules、.cursor/mcp.json 等）。

4. 进阶：嵌套规则（可选）

对于大型项目，可以在子目录中创建局部的 .ruler/ 文件夹以定义特定上下文的规则：

# 在 src/ 目录下创建特定规则
mkdir -p src/.ruler
echo "API 层专用规范..." > src/.ruler/api_guidelines.md

# 启用嵌套模式应用规则
ruler apply --nested

此功能允许不同模块拥有独立的 AI 行为指导，同时保持全局规则的一致性。