<p>I use Cursor and Claude Code, sometimes Codex, and I'm about to try OpenCode.
Each tool has its own rules format, and I've been maintaining them separately.
<a href="https://github.com/intellectronica/ruler">Ruler</a> generates each tool's native
config from a single source. Worth setting up.</p>
<h1 id="tool-agnosticism-with-common-rules">Tool agnosticism with common rules</h1>
<p>I'm trying to keep up. There are too many tools. I don't want to migrate things around.
We're using this at work too, since different devs use different tools. Here's how I
set up Ruler to consolidate my Cursor and Claude rules together.</p>
<p>I had this rule in Cursor:</p>
<pre><code class="language-markdown"># Monorepo rules

This git repo is a monorepo. It contains multiple sub-projects.
Do not look for context or cross-reference calls between sub-projects.
Each directory within apps/ and games/ is a sub-project. They shouldn't
share code.
</code></pre>
<p>Claude Code has CLAUDE.md files scattered through the tree:</p>
<table>
<thead>
<tr>
<th>File</th>
<th>Contents</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>CLAUDE.md</code> (root)</td>
<td>Branching: never commit to main, always PR</td>
</tr>
<tr>
<td><code>apps/games/sillyapp/CLAUDE.md</code></td>
<td>iOS build and test commands, simulator lifecycle</td>
</tr>
<tr>
<td><code>apps/blog/.../posts/CLAUDE.md</code></td>
<td>Blog writing voice, formatting rules, structure</td>
</tr>
<tr>
<td><code>apps/games/kid-bot-battle-sim/features/CLAUDE.md</code></td>
<td>Interface details for that feature set</td>
</tr>
</tbody>
</table>
<h1 id="ruler-setup">Ruler Setup</h1>
<pre><code class="language-bash">npm install -g @intellectronica/ruler
</code></pre>
<p>Initialize at the repo root:</p>
<pre><code class="language-bash">ruler init
</code></pre>
<p>This creates a <code>.ruler/</code> directory and a <code>ruler.toml</code> config. Drop your
instructions as Markdown files inside <code>.ruler/</code>, then:</p>
<pre><code class="language-bash">ruler apply
</code></pre>
<h2 id="what-happens-when-you-run-it">What happens when you run it</h2>
<p>Claude Code gets <code>CLAUDE.md</code>. Everything else (Cursor, OpenCode, Codex,
Copilot, 30+ others) gets <code>AGENTS.md</code>. Generated files go into <code>.gitignore</code>
automatically, so only the <code>.ruler/</code> source is committed.</p>
<p>Ruler supports nested directories. A <code>.ruler/</code> at the repo root applies
globally. A <code>.ruler/</code> inside a sub-project applies when an agent is working
there. That matches how Claude Code already loads CLAUDE.md files walking up
the directory tree.</p>
<pre class="mermaid">
graph TD
    A[".ruler/ at repo root\nbranching, monorepo"] --> B[Claude Code]
    A --> C[Everyone Else\nCursor, OpenCode, Codex...]
    E[".ruler/ in sillyapp/\nbuild, test"] --> B
    E --> C
    F[".ruler/ in posts/\nblog style"] --> B
    F --> C
    B --> G[CLAUDE.md]
    C --> H[AGENTS.md]
</pre>
<p>You can symlink ~/.ruler to your dir too if you want global Claude rules.</p>
<h1 id="note-consider-just-using-agentsmd">Note: Consider just using AGENTS.md</h1>
<p>Most tools read <code>AGENTS.md</code>: Cursor, OpenCode, Codex, <del>others</del>. If all you have is
rules, it's not a bad idea to skip all of this and just use that format. I think it
might win. That doesn't help with Skills, though.</p>
<h2 id="skills">Skills</h2>
<p>Rules are basically just fancy prompt context that are always loaded.
Skills are just fancy prompt context loaded on-demand, maybe with some extra files
sometimes. Different tools implement them in different ways:</p>
<ul>
<li>Claude Code: <code>.claude/skills/</code></li>
<li>Cursor: <code>.cursor/skills/</code></li>
<li>Other tools follow the same pattern under their own config directories</li>
</ul>
<p>Ruler figures it out and distributes them for you. Could this all just be a bash
script? Yes. Does it do a bunch of stuff I don't understand too? Also, probably, yes.</p>
<p>Enabled by default. Pass <code>--no-skills</code> to skip it:</p>
<pre><code class="language-bash">ruler apply           # distributes rules + skills
ruler apply --no-skills  # rules only
</code></pre>
<hr>
<h1 id="consolidating-rules-migration-steps">Consolidating rules: Migration steps</h1>
<p>The <code>ruler.toml</code> at the root lists the agents to target:</p>
<pre><code class="language-toml">default_agents = ["claude", "cursor"]
</code></pre>
<p>Content moves from existing config files into <code>.ruler/</code> source files:</p>
<pre><code>.ruler/
  branching.md        # from root CLAUDE.md
  monorepo.md         # from .cursor/rules/monorepo.md (Claude never saw this)
apps/games/sillyapp/
  .ruler/
    build.md          # from sillyapp/CLAUDE.md
apps/blog/blog/markdown/posts/
  .ruler/
    style.md          # from posts/CLAUDE.md
apps/games/kid-bot-battle-sim/features/
  .ruler/
    interfaces.md     # from features/CLAUDE.md
</code></pre>
<p>Root <code>.ruler/branching.md</code> (was only in Claude Code):</p>
<pre><code class="language-markdown"># Branching

Never commit directly to `main`. Always create a branch and open a PR
against main for review.
</code></pre>
<p>Root <code>.ruler/monorepo.md</code> (was only in Cursor):</p>
<pre><code class="language-markdown"># Monorepo

This repo contains multiple independent sub-projects under `apps/` and
`games/`. Do not cross-reference or import code between sub-projects.
Each directory in those folders is its own isolated project.
</code></pre>
<p>The project-specific files (sillyapp build commands, blog style guide)
move into <code>.ruler/</code> inside their directories unchanged. Content stays the
same, location shifts.</p>
<p>Note: the existing hand-written CLAUDE.md files get replaced by generated
versions after <code>ruler apply</code>. Edit the <code>.ruler/</code> source, not the output.</p>


Kyle Pericak

"It works in my environment"

Categories

Tags