ruler

环境要求

• Node.js ^20.19.0 || ^22.12.0 || >=23
• 可访问 npm 源（全局安装或使用 npx）
• 一个需要统一 AI 助手规则的项目目录
• 如需从源码构建：本机具备 git 与 npm

安装与启动步骤

1. 1确认 Node 版本

   先检查本机 Node.js 版本是否满足 ^20.19.0 || ^22.12.0 || >=23，版本不符会导致安装或运行失败。

   node -v

   复制

2. 2全局安装 Ruler

   官方推荐用于 CLI 场景的安装方式，安装后可在任意项目目录直接调用 ruler 命令。

   npm install -g @intellectronica/ruler

   复制

3. 3一次性试用

   不想全局安装时，可用 npx 执行一次性命令；README 以 apply 为例。

   npx @intellectronica/ruler apply

   复制

4. 4编写 ruler.toml

   在项目根目录创建 ruler.toml，按需启用代理并指定输出文件；未写的项走内置默认值。

   [agents.claude]
   enabled = true
   output_path = "CLAUDE.md"
   
   [agents.aider]
   enabled = true
   output_path_instructions = "AGENTS.md"
   output_path_config = ".aider.conf.yml"
   
   [agents.cursor.mcp]
   enabled = true
   merge_strategy = "merge"

   复制

5. 5先做试运行

   用 --dry-run 预览本次会写入哪些文件，不会真正改动磁盘，适合首次确认配置是否正确。

   ruler apply --dry-run

   复制

6. 6执行规则同步

   正式运行 apply，Ruler 会按配置把同一份规则生成/更新到各 AI 助手的规则文件中。

   ruler apply

   复制

7. 7撤销生成的更改

   revert 会还原 apply 造成的改动：有 .bak 备份则从备份恢复，否则删除原本不存在的生成文件。

   ruler revert

   复制

8. 8从源码构建(可选)

   想本地开发或改造 Ruler 本身时，克隆仓库后安装依赖并构建。

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

   复制

关键配置

如何确认成功

运行 ruler apply --dry-run 会列出将写入的文件；正式 apply 后确认 CLAUDE.md、AGENTS.md 等目标文件已按配置生成。

常见问题

注意事项

• 当前为 Beta Research Preview，建议先在测试环境验证，问题反馈到 GitHub Issues。
• 配置优先级为：CLI 参数 > ruler.toml 设置 > Ruler 内置默认值。
• revert 依赖 .bak 备份文件，执行 apply 后不要手工删除这些备份。
• skills 默认启用，subagents 默认关闭，需要用 --subagents 显式开启。