# One Rules Source for Every Agent: AGENTS.md, Ruler and rulesync

URL: https://developertoolkit.ai/en/ecosystem/frameworks/rules-sync/
Description: Keep one set of agent rules for Claude Code, Codex and Cursor: the AGENTS.md import, Ruler and rulesync, and a CI check that fails on drift.

Rules sync means keeping a single source for the instructions coding agents read, so Claude Code, Codex and Cursor follow the same build commands and conventions. For plain rules, an `AGENTS.md` imported from a one-line `CLAUDE.md` is enough. Ruler and rulesync generate each agent's file from one source when you also sync MCP servers, skills or more agents.

Your repository has a 140-line `CLAUDE.md` that the Claude Code users keep current, an `AGENTS.md` that someone wrote for Codex in the spring, and a `.cursor/rules/` folder nobody has opened since. Last week the test command changed from `npm test` to `pnpm test:unit`. Only `CLAUDE.md` got the edit, so the Codex and Cursor sessions still run the old command, fail, and "fix" the failure their own way.

This page is for the developer or tech lead who owns that repository's agent setup. It assumes you already know what goes into a rules file (see [AGENTS.md and CLAUDE.md: concise repository context](/en/developer-scorecard-guide/claude-md-context/)). It shows the no-tool setup first, then rulesync and Ruler with commands we ran on 2026-09-26, and a CI job that fails the pull request when the generated files drift from the source.

**Versions on this page**

Checked on 2026-09-26: Claude Code 2.1.283 (`latest` channel) and the Claude Code memory documentation; codex-cli 0.157.1 and the `openai/codex` source on the same day; `rulesync` 21.0.0 and `@intellectronica/ruler` 0.3.44 from npm. We ran both tools in a scratch Git repository: rulesync `import`, `generate`, `generate --check` and `generate --delete`, and Ruler `init` and `apply`. Every "observed" output below comes from those runs. cursor.com was unreachable on that day; what this page says about how Cursor loads `AGENTS.md` comes from Cursor's documentation, checked 2026-10-12.

## What you get from a single rules source

- A table of which file each agent reads, including the Claude Code rule that trips most teams: `AGENTS.md` is skipped when a `CLAUDE.md` exists.
- The zero-dependency setup: `AGENTS.md` plus a one-line `@AGENTS.md` import.
- A worked rulesync migration: `import` → edit → `generate --targets claudecode,codexcli,cursor`.
- The Ruler equivalent, and the default that hides its output from Git.
- A GitHub Actions job that fails a pull request when someone hand-edits a generated file.
- Where a path-scoped rule lands in each agent, including the one agent that loses the scope.
- Three copy-paste prompts: merge scattered rules into one file, migrate the repository to rulesync, and prove each agent loaded the rules.

## Which rules file does each agent read?

Each agent has a native file. The sync problem exists because they differ.

| Agent | Native file | Reads `AGENTS.md`? | Detail that matters |
| ----- | ----------- | ------------------ | ------------------- |
| Claude Code | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` | Only when none of those three exists in the working directory or above it (v2.1.277; both release channels on 2026-10-12) | With both files present, Claude Code reads `CLAUDE.md` only, unless you import `AGENTS.md` from it |
| Codex | `AGENTS.md` | Yes, natively | Since 0.150.0 an untrusted project does not supply its project-level `AGENTS.md`; `project_doc_max_bytes` defaults to 32768 bytes (32 KiB) in the Codex source, and content past it is truncated |
| Cursor | Project rules in `.cursor/rules/` | Yes, in the project root and in subdirectories, and it reads `CLAUDE.md` the same way (Cursor docs, checked 2026-10-12) | rulesync writes `.cursor/rules/overview.mdc`; Ruler writes only `AGENTS.md` for its `cursor` agent id |

Three Claude Code details come from its memory documentation and change the setup:

- **The fallback is either-or by default.** The **Project instructions** setting in `/config` defaults to `claude-md-or-agents-md`. `claude-md-and-agents-md` loads both, `claude-md` ignores `AGENTS.md`, and `managed-only` drops every project file.
- **A repository cannot switch that setting for the team.** The value lives under the built-in `agents-md` plugin's entry in `pluginConfigs`, and Claude Code ignores it in project and local settings files. It is read from `~/.claude/settings.json`, a `--settings` file or managed settings.
- **The fallback depends on the Claude Code version.** It needs v2.1.277, or v2.1.281 on Amazon Bedrock, Google Cloud, Foundry, LLM gateways and telemetry-off sessions. Both release channels have it since `stable` reached v2.1.287 (checked 2026-10-12). A teammate on an older build gets no `AGENTS.md` fallback at all; only an import reaches them.

So the fallback helps a repository that ships `AGENTS.md` alone and a team whose Claude Code is all at v2.1.277 or later (v2.1.281 on cloud providers). For every other case, use the import.

## Do you need a sync tool at all?

Start with the smallest setup that covers your agents, and add a generator only when a row below applies.

| Your situation | Use | Why |
| -------------- | --- | --- |
| Claude Code and Codex, plain Markdown rules | `AGENTS.md` + `@AGENTS.md` in `CLAUDE.md` | No generator to forget to re-run; one file, two agents |
| You also need Cursor's `.cursor/rules/*.mdc` files, glob-scoped rules or Copilot's instructions file | rulesync | It writes each tool's native rules format from one source |
| You want the same MCP servers, skills, subagents, hooks or permissions in every agent | rulesync | Its features cover `rules`, `mcp`, `subagents`, `commands`, `skills`, `hooks`, `permissions` |
| Five or more agents, rules as concatenated Markdown, minimal config | Ruler | 30+ agent ids; one folder of Markdown files concatenated into each agent's file |
| One agent only | Its native file | A sync layer adds a moving part and buys nothing |

## Share AGENTS.md with Claude Code through an import

This is the setup to try first. `AGENTS.md` is the source of truth; `CLAUDE.md` is one line plus anything that only Claude Code needs.

1. Move the shared rules into `AGENTS.md` at the repository root. Keep build and test commands, conventions, and "never do X" rules there. The prompt after these steps does the merge for you.

2. Replace `CLAUDE.md` with an import:

   ```markdown
   @AGENTS.md

   ## Claude Code only
   - Use the Explore subagent before editing more than three files.
   ```

   Claude Code expands `@path` imports at launch, reads the imported file first, then the rest of `CLAUDE.md`. Relative paths resolve from the file that contains the import, and imports nest up to four hops. An `@path` inside backticks or a fenced code block stays literal text.

3. Check that each agent loaded the rules.

     **Claude Code**

       Start a new session, run `/context` and confirm `CLAUDE.md` appears under **Memory files**. The import never loads `AGENTS.md` twice, whatever the **Project instructions** value is.

     **Codex**

       Confirm the project is trusted, because an untrusted project does not supply its `AGENTS.md` (0.150.0). Then run the verification prompt below in a new session.

     **Cursor**

       Cursor supports `AGENTS.md` in the project root and in subdirectories, combines nested files with their parent directories (the more specific instructions take precedence), and reads `CLAUDE.md` the same way (Cursor docs, checked 2026-10-12). Run the verification prompt below in a new Agent chat. If the answer does not quote your rules, generate `.cursor/rules/` with rulesync as shown in the next section.

**Copy-paste prompt: merge scattered rules into one AGENTS.md**

```text
Read CLAUDE.md, AGENTS.md, every file under .cursor/rules/ and .github/copilot-instructions.md if they exist.
Produce one AGENTS.md at the repository root that:
- keeps every rule that applies to all agents, deduplicated;
- resolves conflicts by checking package.json scripts and CI config, and lists each conflict you resolved with the evidence;
- puts build, test, lint and typecheck commands first, exactly as CI runs them;
- stays under 150 lines;
- leaves out anything that names one tool's features (subagents, slash commands, Cursor modes) and lists those lines separately at the end of your reply.
Do not delete the old files. Show me the diff of AGENTS.md only.
```

A symlink (`ln -s AGENTS.md CLAUDE.md`) also works, with two costs from the Claude Code documentation: the Edit and Write tools refuse to write through it, and a Windows clone without `core.symlinks` checks it out as a one-line text file. Prefer the import in a mixed-OS team.

## Sync rules to every agent with rulesync

rulesync keeps its source in `.rulesync/` and writes each tool's native files. This worked example migrates a repository whose rules live in `CLAUDE.md` and `.claude/rules/` today, following the path `import` → edit → `generate`.

1. Install rulesync and pin the version. The package name is `rulesync`, and the target ids are `claudecode`, `codexcli` and `cursor`, not `claude` or `codex`.

   ```bash
   npm install -g rulesync@21.0.0
   # or: brew tap dyoshikawa/rulesync https://github.com/dyoshikawa/rulesync && brew install rulesync
   ```

   Install is the same for every agent; rulesync and Ruler are standalone CLIs, not plugins.

   rulesync published majors 18, 19, 20 and 21 between 2026-09-24 and 2026-09-26 (npm registry), so an unpinned `npx rulesync` can change your output between two CI runs.

2. Import what you have. Skip `rulesync init` in a repository that already has rules (see the caution after these steps).

   ```bash
   rulesync import --targets claudecode
   mv .rulesync/rules/CLAUDE.md .rulesync/rules/overview.md
   ```

   Observed: `import` copies `CLAUDE.md` to `.rulesync/rules/CLAUDE.md` as a root rule and each `.claude/rules/*.md` file to its own rule. The rename is optional; without it the Cursor file is called `CLAUDE.mdc`.

3. Write a minimal `rulesync.jsonc` at the repository root, so every later command, including the CI check, needs no flags:

   ```jsonc
   {
     "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json",
     "targets": ["claudecode", "codexcli", "cursor"],
     "features": ["rules"],
     "delete": false
   }
   ```

   `"delete": false` keeps rulesync from removing files it did not write. Add `"mcp"` to `features` once `.rulesync/mcp.jsonc` holds your servers. Cursor reads `AGENTS.md` and `CLAUDE.md` directly (Cursor docs, checked 2026-10-12), so the `cursor` target writes a Rules copy of text Cursor already reads: keep `cursor` in `targets` for Cursor-only or glob-scoped rules, and drop it when you have none.

4. Edit the source. The root rule after the rename looks like this:

   ```markdown
   ---
   root: true
   targets: ["*"]
   description: "Project overview, commands and hard rules"
   globs: ["**/*"]
   ---

   # Commands
   - Install: `pnpm install --frozen-lockfile`
   - Test: `pnpm test:unit` (CI runs exactly this)
   - Typecheck: `pnpm typecheck`

   # Hard rules
   - Never bind a `Date` to D1; convert to an ISO string first.
   - Every pull request links an issue and lists the commands you ran.
   ```

   `targets: ["*"]` sends the rule to every tool; list tool ids to narrow it. A block such as `cursor: { alwaysApply: true }` in the frontmatter passes an option to one tool's format (rulesync file-format reference).

5. Generate the native files, preview first if you like:

   ```bash
   rulesync generate --dry-run
   rulesync generate
   ```

   Observed output: `CLAUDE.md`, `AGENTS.md` and `.cursor/rules/overview.mdc`, plus one file per non-root rule (next table). rulesync lists only files whose content changed, so right after `import` the Claude Code files may not appear in the output. Run `rulesync doctor` for a read-only configuration check.

6. Commit `.rulesync/`, `rulesync.jsonc` and the generated files together. Committed output is what Codex cloud tasks, review bots and a fresh clone see without running rulesync.

**rulesync init and --delete remove hand-written rules**

`rulesync init` (21.0.0) scaffolds a `rulesync.jsonc` with `"delete": true`, targets `codexcli`, `claudecode` and `opencode` (no `cursor`), and a sample `.rulesync/rules/overview.md` of generic guidelines. In our run, `init` followed by `import` concatenated that sample into the generated `CLAUDE.md`, and `rulesync doctor` reported no problem. `generate --delete`, or `"delete": true`, deleted a hand-written `.claude/rules/billing.md` and `.cursor/rules/legacy.mdc` that rulesync had not imported. Import first, then write the config yourself.

### Where does a path-scoped rule land in each agent?

A root rule loads everywhere. A non-root rule with `globs` is where the agents differ, and this is the detail the rulesync README does not spell out. We generated this rule and read the output:

```markdown
---
root: false
targets: ["*"]
globs: ["src/billing/**"]
---
Billing: amounts are integer cents.
```

| Agent | Observed output (rulesync 21.0.0) | Scope kept? |
| ----- | --------------------------------- | ----------- |
| Claude Code | `.claude/rules/billing.md` with `paths: [src/billing/**]` | Yes: loads when Claude reads a matching file |
| Cursor | `.cursor/rules/billing.mdc` with `globs: src/billing/**` | Scoped in the file; project rules are `.mdc` files in `.cursor/rules` with `description`, `globs` and `alwaysApply` frontmatter, and they apply to Agent chat only (Cursor docs, checked 2026-10-12) |
| Codex | The rule text appended to the root `AGENTS.md` | No: every Codex session loads it, and it counts toward the 32 KiB budget |

So every scoped rule you add costs Codex context in every session. For a monorepo, the rulesync file-format reference documents an `agentsmd.subprojectPath` option that writes a nested `AGENTS.md` per package instead; we did not run it.

What each agent receives, and how to confirm it:

**Claude Code**

    `CLAUDE.md` at the root and scoped rules in `.claude/rules/`. Because `CLAUDE.md` exists, the default **Project instructions** mode ignores the generated `AGENTS.md`, so the rules load once. Confirm with `/context` under **Memory files**. Do not switch to `claude-md-and-agents-md` here: it would load the same rules twice.

**Codex**

    `AGENTS.md` at the root, its native file, with scoped rules appended. Keep it under the 32 KiB `project_doc_max_bytes` default (`wc -c AGENTS.md`), and trust the project so Codex reads it.

**Cursor**

    `.cursor/rules/overview.mdc` and one `.mdc` per scoped rule. Open a new Agent chat and run the verification prompt below.

**Copy-paste prompt: migrate this repository to rulesync**

```text
Migrate this repository's agent rules to rulesync 21.0.0 without losing any rule.
1. List every existing rules file: CLAUDE.md, .claude/rules/*, AGENTS.md, .cursor/rules/*.
2. Run `npx -y rulesync@21.0.0 import --targets claudecode`. Do not run `rulesync init`.
3. Rename .rulesync/rules/CLAUDE.md to overview.md.
4. Create rulesync.jsonc with targets claudecode, codexcli, cursor; features rules; "delete": false.
5. Diff AGENTS.md and every .cursor/rules file against .rulesync/rules/. Any rule that exists only there: add it to the right .rulesync rule and tell me which one.
6. Run `npx -y rulesync@21.0.0 generate`, then `npx -y rulesync@21.0.0 generate --check`.
7. Show me `git status` and `git diff --stat`. Do not commit.
Stop and ask before deleting any file.
```

**Copy-paste prompt: prove the agent loaded the shared rules**

```text
Without opening any file, answer from the instructions you were given at session start:
1. Which file or files did your project instructions come from?
2. What is the exact command to run the unit tests?
3. Quote the rule about binding values to D1 word for word.
If you do not have an answer from your loaded instructions, say "not loaded" rather than reading the repository.
```

Run the second prompt in a fresh session of each agent after every rules change. An agent that answers "not loaded" or reads the file first did not get the rules at startup.

## Sync rules with Ruler

Ruler concatenates Markdown from `.ruler/` and writes it to each agent's file. The package is `@intellectronica/ruler`; npm `ruler` is an unrelated assertion library last published in 2013.

```bash
npm install -g @intellectronica/ruler@0.3.44   # Node.js ^20.19, ^22.12 or >=23 (package engines)
ruler init                                     # creates .ruler/AGENTS.md and .ruler/ruler.toml
ruler apply --agents claude,codex,cursor       # writes CLAUDE.md and AGENTS.md, and edits .gitignore
ruler revert                                   # restores .bak files and removes generated files
```

Ruler's agent ids are `claude`, `codex` and `cursor`, so a rulesync command pasted into Ruler fails, and the other way round.

**Ruler hides its own output from Git by default**

`ruler apply` adds a `# START Ruler Generated Files` block to `.gitignore` that lists `/AGENTS.md`, `/CLAUDE.md` and `/.codex/config.toml`. A clone that has not run Ruler, a Codex cloud task and a PR reviewer then see no rules at all. To commit the output, run `ruler apply --no-gitignore` or set `enabled = false` under `[gitignore]` in `.ruler/ruler.toml`.

Two more behaviours to know before you adopt it. Ruler reads a repository-root `AGENTS.md` first, before `.ruler/AGENTS.md`, so a generated root `AGENTS.md` is fed back in on the next `apply` unless it is ignored. And its last npm release is 0.3.44 from 2026-06-30, although the repository was pushed on 2026-09-23.

## Ruler or rulesync?

| | rulesync 21.0.0 | Ruler 0.3.44 |
| - | --------------- | ------------ |
| Source | `.rulesync/` + `rulesync.jsonc` | `.ruler/*.md` + `ruler.toml` |
| Claude Code / Codex / Cursor ids | `claudecode`, `codexcli`, `cursor` | `claude`, `codex`, `cursor` |
| Cursor output | `.cursor/rules/*.mdc` | `AGENTS.md` |
| Beyond rules | MCP, skills, subagents, commands, hooks, permissions | MCP, skills, subagents |
| Git default | You decide; `rulesync gitignore` adds entries on request | Adds generated files to `.gitignore` |
| Scoped rules | Native per tool; appended to `AGENTS.md` for Codex | Concatenated into each agent's single file |
| Drift check | `generate --check`, exit 1 on drift (we ran it) | No check flag in `apply --help`; use `git diff` |
| Release pace | Four majors in three days (Sept 2026) | Last npm release 2026-06-30 |

Popularity as of 2026-09-26 (GitHub search API, our research pass): agentsmd/agents.md 24,617 stars, intellectronica/ruler 2,934, dyoshikawa/rulesync 1,474. The agents.md site says the format is "used by over 60k open-source projects". Both sync tools are single-maintainer projects; stars measure attention, not reliability.

## Fail the pull request when rules drift

A generator only helps if nobody edits its output by hand. This job runs on every pull request that touches rules and fails when the committed files differ from what the source generates. It uses the `pull_request` trigger, holds no secrets and needs only read access.

```yaml
# .github/workflows/rules-drift.yml
name: rules-drift
on:
  pull_request:
    paths:
      - ".rulesync/**"
      - "rulesync.jsonc"
      - "CLAUDE.md"
      - "AGENTS.md"
      - ".claude/rules/**"
      - ".cursor/rules/**"
      - ".github/workflows/rules-drift.yml"
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Generated rules match .rulesync/
        run: npx -y rulesync@21.0.0 generate --check
```

`--check` reads targets and features from `rulesync.jsonc`, writes nothing, and exits 1 when a generated file would change. In our run, one line appended by hand to `AGENTS.md` produced `Files are not up to date. Run 'rulesync generate' to update.` and exit code 1; the untouched repository printed `✓ All files are up to date.` and exit code 0.

If you make this job a required check, drop the `paths:` filter: GitHub leaves a required check pending on any pull request that the filter skips, and that pull request cannot merge.

The example pins `actions/checkout` and `actions/setup-node` by their `v7` tag for readability. A tag can be moved, so on a protected branch pin each action to its full commit SHA with the version as a trailing comment.

A second pattern works for any generator, including Ruler. It is our suggestion, not a feature of either tool: regenerate, then let Git decide.

```yaml
      - name: Generated rules match the source (git variant)
        run: |
          npx -y rulesync@21.0.0 generate
          git diff --exit-code -- CLAUDE.md AGENTS.md .claude/rules .cursor/rules
          test -z "$(git status --porcelain -- CLAUDE.md AGENTS.md .claude/rules .cursor/rules)"
```

The last line catches a generated file that is new and untracked, which `git diff` alone misses. For Ruler, replace the first line with `npx -y @intellectronica/ruler@0.3.44 apply --agents claude,codex,cursor --no-gitignore`. Add a `CODEOWNERS` entry for `.rulesync/` (or `.ruler/`) so the rules owner approves every change to the source, and one for `.github/workflows/rules-drift.yml`: on `pull_request` GitHub runs the workflow from the pull request's merge ref, so without that review a pull request could edit the check itself.

## How do you know the agents follow the synced rules?

A green drift check proves the files match. It does not prove that any agent obeys them. Verify the behaviour in three layers, cheapest first:

1. **Load check.** The verification prompt above, in a fresh session of each agent, after every rules change. The rules owner runs it and pastes the three answers into the pull request.
2. **Enforce what matters in code, not prose.** Rules are context, not enforcement; the Claude Code memory documentation calls them "context rather than enforced configuration". Put "tests must pass" in CI and a pre-commit hook; keep the rule text as the explanation.
3. **Measure a rules change before you roll it out.** Run a fixed set of tasks against the old and new rules and compare pass rates, as in [evaluating CLAUDE.md changes](/en/ecosystem/observability/evals-coding-agents/).

The tech lead signs off on the source change; CI signs off on the generated files.

## What does a shared rules file cost in context?

Every line in the root rules file loads into every session of every agent before the first prompt. Claude Code's documentation targets under 200 lines per `CLAUDE.md`, because longer files consume more context and reduce adherence. Codex truncates project docs at `project_doc_max_bytes` (32768 bytes by default in the source), so the rules at the end of a long generated `AGENTS.md`, which is where rulesync appends scoped rules, are the ones Codex loses. Imports do not reduce the cost: an `@AGENTS.md` import loads at launch like the file itself. The saving from a sync tool is duplication you avoid, not tokens. To cut tokens in Claude Code and Cursor, move file-type rules into glob-scoped rules (`globs:` in rulesync); for Codex, use nested `AGENTS.md` files, which Codex concatenates from the project root down to the directory it starts in (Codex source, 2026-09-26). Then follow [pruning context files](/en/workflows/context/pruning-context-files/).

**Traps from old tutorials (checked 2026-09-26)**

- **"Claude Code ignores AGENTS.md"** is out of date since v2.1.277. The opposite claim is also wrong: with a `CLAUDE.md` present, Claude Code reads only `CLAUDE.md` by default.
- **Package names.** Ruler is `@intellectronica/ruler`; npm `ruler` is unrelated. npm `agents-md` is a third-party tool, not the agentsmd project, and npm `agentsmd` does not exist.
- **Target ids.** rulesync uses `claudecode` and `codexcli`; Ruler uses `claude` and `codex`.
- **A `CLAUDE.local.md` counts as a `CLAUDE.md`.** Adding a personal one to an `AGENTS.md`-only repository silently stops Claude Code from reading `AGENTS.md` for you.
- **`rulesync gitignore` always emits `AGENTS.md` entries**, whatever your targets, according to its configuration guide. Run it only if you have decided not to commit generated files.

## What breaks when you sync rules across agents?

**Codex follows old rules after an edit.** Symptom: `AGENTS.md` changed but Codex runs the old test command. Cause: someone edited `CLAUDE.md` or the source and never regenerated, or the project is untrusted in Codex. Recovery: run `rulesync generate`, commit, and add the drift job; mark the project trusted.

**Claude Code ignores `AGENTS.md` for one teammate.** Symptom: the verification prompt answers "not loaded" on one machine only. Cause: a `CLAUDE.local.md` or `.claude/CLAUDE.md` on the path, a Claude Code build older than v2.1.277, or **Project instructions** set to `claude-md`. Recovery: add the `@AGENTS.md` import to a committed `CLAUDE.md`, which works on every version and setting except `managed-only`.

**Rules load twice.** Symptom: `/context` lists both `CLAUDE.md` and `AGENTS.md` under **Memory files**, with the same content in each. Cause: a generator wrote identical content to both files and the user chose `claude-md-and-agents-md`. Recovery: return to the default mode, or generate `CLAUDE.md` as the one-line import.

**A hand edit disappears.** Symptom: a fix to `CLAUDE.md` is gone after the next `generate`. Cause: generated files are output; `generate` overwrites them from the source. Recovery: make the edit in `.rulesync/rules/`. Start the root rule's body with `<!-- Generated from .rulesync/rules/. Edit there. -->`; in our run rulesync copied that line to the top of `CLAUDE.md` and `AGENTS.md`, so humans and agents see where the source is.

**Hand-written rules vanish after the first generate.** Symptom: `.claude/rules/` or `.cursor/rules/` files that nobody imported are gone. Cause: `"delete": true` from `rulesync init`, or `--delete`. Recovery: restore them with `git checkout -- .claude/rules .cursor/rules`, run `rulesync import` for each tool that owns them, and set `"delete": false`.

**Reviewers and cloud agents see no rules.** Symptom: the rules work locally, but a Codex cloud task or review bot ignores them. Cause: Ruler's default `.gitignore` block, or `rulesync gitignore`. Recovery: remove the entries, commit the output, and keep the drift check.

**A rulesync upgrade changes the output.** Symptom: the drift job fails on the first rules pull request after someone bumped the pinned version. Cause: an unpinned or bumped major. Recovery: pin the same version locally and in CI, and bump it in its own pull request with the regenerated files.

## Where to go next with shared agent rules

- [Pruning context files](/en/workflows/context/pruning-context-files/) — Cut the root rules file down to what every session needs.
- [Claude Code memory system](/en/claude-code/build/memory-system/) — CLAUDE.md scopes, imports, path-scoped rules and auto memory.
- [The agent-ready codebase](/en/workflows/harness/agent-ready-codebase/) — What else a repository needs before agents work in it unattended.
- [Evaluating CLAUDE.md changes](/en/ecosystem/observability/evals-coding-agents/) — A/B a rules change on a fixed task set before rolling it out.
- [Codex: AGENTS.md](/en/codex/quick-start/agents-md/) — How Codex discovers, layers and trusts AGENTS.md files.
- [Avoiding lock-in](/en/org/lock-in-and-portability/) — Why a portable rules file is one of the assets that survives a tool switch.
- [Beyond the big three](/en/ecosystem/agent-tools/other-coding-agents/) — The other agents a rules source may need to reach.
- [Agentic development frameworks compared](/en/ecosystem/frameworks/) — The methodologies you run on top of a shared rules file.
