ruler

一份规则，同步所有 AI 编码助手

Ruler 是一个 TypeScript 编写的命令行工具，用于把同一套编码规则同步应用到所有主流 AI 编程助手。它解决的核心问题是：当团队同时使用 Cursor、Claude Code、GitHub Copilot、Codex、Aider、Windsurf 等多个编码代理时，每个工具都有自己的规则文件格式和存放位置，维护多份规则既繁琐又容易不一致。Ruler 让你只维护一份规则源文件，通过一条命令自动生成或更新各代理所需的规则配置，确保所有 AI 助手遵循相同的编码规范、项目约定和上下文提示。它支持集中式规则管理、多代理适配、可重复执行的同步流程，适合需要统一 AI 编码行为、减少重复配置的团队和个人开发者，让规则维护从多份变成一份。

开源 unknown 编程开发

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 2927

维护状态活跃

是否开源是

定价模式 unknown

项目数据

分类编程开发

开发团队intellectronica

所属国家

官网地址https://okigu.com/ruler

GitHubhttps://github.com/intellectronica/ruler

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议MIT

主要语言TypeScript

技术栈/模型agents,ai,aider,claude-code,codex,cursor,github-copilot,vibe-coding,windsurf

GitHub 星标★ 2927

30天Star增速

HF 下载量

上线时间2025-05-20 00:00:00

最近更新2026-09-15 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-17

浏览次数0

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

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

安装与启动步骤

1确认 Node 版本

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

官方推荐用于 CLI 场景的安装方式，安装后可在任意项目目录直接调用 ruler 命令。
```
npm install -g @intellectronica/ruler
```
3一次性试用

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

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先做试运行

用 --dry-run 预览本次会写入哪些文件，不会真正改动磁盘，适合首次确认配置是否正确。
```
ruler apply --dry-run
```
6执行规则同步

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

revert 会还原 apply 造成的改动：有 .bak 备份则从备份恢复，否则删除原本不存在的生成文件。
```
ruler revert
```
8从源码构建(可选)

想本地开发或改造 Ruler 本身时，克隆仓库后安装依赖并构建。
```
git clone https://github.com/intellectronica/ruler.git
cd ruler
npm install
npm run build
```

关键配置

配置项	必填	说明	示例
`default_agents`	否	未通过 --agents 指定时默认启用的代理列表	`["copilot", "claude"]`
`[agents.].enabled`	否	按代理开启或关闭规则生成	`[agents.claude] enabled = true`
`[agents.claude].output_path`	否	指定 Claude 规则文件的输出路径	`CLAUDE.md`
`[agents.aider].output_path_instructions`	否	分别指定 Aider 的指令文件与配置文件路径	`AGENTS.md / .aider.conf.yml`
`[agents..mcp].merge_strategy`	否	该代理 MCP 配置的合并策略	`merge`
`[mcp_servers.]`	否	在 ruler.toml 中直接定义 MCP 服务器	`[mcp_servers.my-server]`

如何确认成功

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

常见问题

Q：apply 改错了怎么恢复？

A：执行 ruler revert，它会从 .bak 备份恢复文件，或删除此前不存在的生成文件，把项目还原到使用 ruler 之前的状态。

Q：只想对部分助手生效怎么办？

A：用 CLI 参数 --agents 指定本次要用的代理；CLI 优先级最高，会覆盖 ruler.toml 中的默认代理设置。

Q：不小心覆盖了已有配置怎么办？

A：先跑 ruler apply --dry-run 预览将写入的文件，确认无误再正式执行；已执行的可通过 revert 借助 .bak 备份还原。

Q：TOML 和 JSON 的 MCP 配置冲突时以谁为准？

A：同名服务器以 TOML 为准，两边来源的服务器会合并（除非使用 overwrite 策略），并会提示迁移到 TOML 的弃用警告。

注意事项

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

核心亮点

一份规则源文件自动分发到 Cursor、Claude Code、Copilot、Codex、Aider、Windsurf 等主流代理，消除多份规则不一致的问题
TypeScript 实现，可通过 npm 安装，命令行操作简单，适合集成到现有开发流程或 CI 中
覆盖当前活跃的 AI 编码工具生态，减少团队切换或新增代理时的规则迁移成本

不足之处

项目相对年轻，星标约 2900，长期维护和社区生态仍需观察
对各代理规则格式的适配依赖上游工具变化，可能出现同步滞后或兼容问题

适用场景

团队同时使用多个 AI 编码助手，需要统一编码规范和项目约定
个人开发者在不同编辑器/代理间切换，希望规则一次编写处处生效
将 AI 规则同步纳入 CI 或脚手架，保证新成员和代理开箱即用同一套规则

替代项目

aider、continue

项目介绍

ruler 是一个编程开发领域的开源项目，官方简介：Ruler — apply the same rules to all coding agents。项目使用 TypeScript 开发，在 GitHub 上获得 2927 星标。

上一篇：vim-llm-agent

下一篇：spec-kitty