# Shared agent rules — one core, tested adapters

URL: https://developertoolkit.ai/en/cto-scorecard-guide/shared-agent-rules/
Description: CTO Scorecard Q5: one AGENTS.md core, thin Claude Code, Codex and Cursor adapters, CI checks and fresh-session probes that prove every agent loads it.

Shared agent rules are one versioned instruction core (a root `AGENTS.md`), the thinnest per-tool adapter that makes Claude Code, Codex and Cursor load it, and a test proving each tool did. Rules steer the model; anything that must never happen belongs in permissions, sandboxes, CI and branch protection.

Your repository has a 400-line `CLAUDE.md` written in March, an `AGENTS.md` that the Codex users added in July, and a Cursor rule that still says `npm test` after the move to pnpm. Three agents read three versions of the truth, and nobody can say which one a given session loaded. This page is for the tech lead who owns the shared harness and the CTO answering question 5 of the [CTO Scorecard](/en/cto-scorecard-guide/).

## What a tested shared-rules setup gives you

- A file layout and an `AGENTS.md` core template you can commit today.
- The adapter each tool needs, based on how it discovers instruction files (checked 2026-09-26 against Claude Code 2.1.283 and Codex 0.157.1).
- A written precedence table that settles conflicts by rule, not by load order.
- A deterministic CI check and a fresh-session probe that prove each agent loaded the rules, so nobody has to read transcripts.
- The failure modes that make an agent silently ignore the rules, and how to recover from each.

## How does the CTO Scorecard grade shared rules?

Question 5 asks: "Does the team share agent rules (`CLAUDE.md` / `AGENTS.md` / managed policy)?" Use the table to place the team honestly, then close the gap to the next row.

| Points | Answer | Evidence a reviewer asks for |
| --- | --- | --- |
| 0 | Everyone authors their own, no sharing | none |
| 1 | A "recommended" `CLAUDE.md` in the README | a copy-paste snippet, no enforcement |
| 2 | Per-repo `CLAUDE.md`/`AGENTS.md` committed to main | the file exists; nobody knows whether every tool loads it |
| 3 | Versioned shared core plus tested tool adapters, owners, precedence, change review and external enforcement for hard requirements | `CODEOWNERS` entry, the CI check below, probe results per tool, a list mapping each hard rule to its control |

The jump from 2 to 3 is almost entirely verification. The file is the easy part.

## Split durable truth from tool adapters

Each layer has one job. When a sentence could live in two layers, it belongs in the lower one.

| Layer | Holds | Lives in |
| --- | --- | --- |
| Shared core | repository map, commands, definition of done, protected paths, human gates, owners | root `AGENTS.md` |
| Directory scope | rules for one package, service, language or risk area | `services/billing/AGENTS.md` and similar |
| Tool adapter | discovery glue and genuinely tool-specific behaviour, nothing else | `CLAUDE.md`, a Cursor project rule |
| External enforcement | what must hold even when the model ignores every file above | sandbox, permission rules, CI, branch protection, deploy approval |

The core goes in `AGENTS.md` because it is the format the tools converge on: an open format stewarded by the Agentic AI Foundation under the Linux Foundation, which its site describes as "used by over 60k open-source projects" (agents.md, September 2026). How to write the content itself (what to include, and what to leave out) is covered in [AGENTS.md and CLAUDE.md: concise repository context](/en/developer-scorecard-guide/claude-md-context/).

A layout that works for a monorepo:

```text
AGENTS.md                    # shared core, target under 200 lines
CLAUDE.md                    # adapter: "@AGENTS.md" + Claude-only lines
services/billing/AGENTS.md   # directory scope
services/billing/CLAUDE.md   # adapter: "@AGENTS.md"
.claude/rules/               # optional Claude path-scoped rules (paths: frontmatter)
.github/CODEOWNERS           # rule files owned by the harness owner
scripts/check-agent-rules.sh # deterministic CI check (below)
tests/agent-rules/probe.sh   # fresh-session probe (below)
```

The shared core template, ready to adapt:

```markdown
# AGENTS.md

Rules version: 2026-09-26.1

## Commands
- Install: `pnpm install --frozen-lockfile`
- Unit tests: `pnpm test`
- Types and lint: `pnpm typecheck && pnpm lint`

## Definition of done
- Tests, types and lint pass locally before you open a pull request.
- New behaviour has a test that fails without the change.

## Protected paths (ask a human first)
- `services/billing/migrations/`
- `infra/` and anything that changes production access

## Human gates
- Merging to `main` and deploying are human decisions. Never push to `main`.

## Precedence
- A directory `AGENTS.md` may add constraints. It may not relax a rule in this file.
- If two rules conflict, stop and ask; do not pick one.

## Owners
- This file: @acme/agent-platform. Change it through a pull request.
```

The `Rules version:` line is a canary: every test on this page checks that an agent can quote it.

## How each agent discovers instruction files

Discovery is where shared rules fail, and it differs per tool, so the adapters differ too.

**Claude Code**

Checked against the [memory documentation](https://code.claude.com/docs/en/memory) and Claude Code 2.1.283 on 2026-09-26.

- **Launch:** Claude Code loads `CLAUDE.md`, `.claude/CLAUDE.md` and `CLAUDE.local.md` from the working directory and every directory above it. Files in subdirectories load when Claude reads files there. Everything is concatenated, root first; nothing overrides anything.
- **`AGENTS.md`:** read directly from v2.1.277 (v2.1.281 on Bedrock, Google Cloud, Foundry, gateways and telemetry-off sessions), and by default **only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md`** in the working directory or above. On 2026-10-17 that is both release channels (`stable` v2.1.292, `latest` v2.1.302); builds older than v2.1.277 read `CLAUDE.md` files only.
- **Also read, by Claude Code only:** `.claude/AGENTS.md` in the working directory and above. Codex ignores it, so it is another way for the two tools to diverge; the CI check below fails on it.
- **Not read:** `AGENTS.override.md`, `AGENTS.local.md`, and anything under `.agents/`.
- **Adapter:** a `CLAUDE.md` next to each `AGENTS.md` whose first line is `@AGENTS.md`. The import works on every version and channel, and a version that also reads `AGENTS.md` directly never loads it twice.
- **Alternative:** in `/config`, set **Project instructions** to `claude-md-and-agents-md` to read `CLAUDE.md` and `AGENTS.md` together, deduplicated. It is honoured only in user or managed settings, never in project settings. It also lets a `CLAUDE.local.md` coexist with `AGENTS.md`; under the default, a `CLAUDE.local.md` counts as a `CLAUDE.md` and suppresses `AGENTS.md`. Keep the import adapter anyway, because it works on every channel.

```markdown
@AGENTS.md

## Claude Code only
- Use plan mode for changes under `services/billing/`.
```

- **Check:** run `/context` and confirm the files appear under **Memory files**; `/memory` opens the loaded CLAUDE.md files for editing.

**Codex**

Checked against the `agents_md.rs` and `config_toml.rs` sources at `rust-v0.157.1` and the installed Codex 0.157.1 on 2026-09-26.

- **Launch:** Codex finds the project root (the nearest directory with `.git`, configurable with `project_root_markers`) and collects instructions from the root **down to the working directory**, root first. It never walks above the root.
- **Per directory:** Codex takes the first file that exists from `AGENTS.override.md`, `AGENTS.md`, then any names in `project_doc_fallback_filenames`. An override therefore replaces that directory's `AGENTS.md` for Codex only.
- **Budget:** `project_doc_max_bytes` caps the whole chain at 32 KiB by default. Past the cap Codex truncates, and the deepest files go first.
- **Trust:** since 0.150.0, a project marked untrusted does not supply project-level `AGENTS.md`. A project with no trust entry yet still loads it.
- **Adapter:** none. Codex reads `AGENTS.md` natively.
- **Check:** `codex debug prompt-input` prints the model-visible input as JSON, so you can grep it for the canary without running a task.

```bash
# Terminal, from the directory where engineers start Codex
codex debug prompt-input "noop" | grep -c "Rules version: 2026-09-26.1"
```

**Cursor**

Cursor applies instructions through **Rules** ([cursor.com/docs/rules](https://cursor.com/docs/rules), checked 2026-10-12): project rules are `.mdc` files in `.cursor/rules`, and Cursor also supports `AGENTS.md` in the project root and in subdirectories and reads `CLAUDE.md` the same way. The probe below still decides whether Cursor needs a pointer rule.

- **Adapter:** if the fresh-session probe below shows your build loads `AGENTS.md`, add nothing. Otherwise add one always-applied project rule that points the agent at `AGENTS.md` and holds only Cursor-specific lines, in the format the Rules page specifies today.
- **Do not** paste the core into the rule. A copy is how the `npm test` line in the opening example survived the move to pnpm.
- **Check:** open a new Agent chat and paste the probe prompt from the next section. A pointer rule relies on the model choosing to open `AGENTS.md`, so repeat the probe after every Cursor update.

## Write the precedence down

Neither Claude Code nor Codex resolves conflicts for you. Both concatenate files, and Anthropic's memory page warns that if two rules contradict each other, "Claude may pick one arbitrarily". So precedence is a rule you write, review and test, not a load order you hope for.

| Situation | What wins | How it is enforced |
| --- | --- | --- |
| Directory file contradicts the root | the stricter rule; a directory may add constraints, never relax them | stated in the core; conflict audit in review |
| `AGENTS.override.md` exists | Codex reads it instead of that directory's `AGENTS.md`; Claude Code ignores it | never committed; the CI check fails on it |
| Personal preferences | `CLAUDE.local.md` or user-level files, gitignored | a personal file cannot weaken a hard rule, because hard rules are not in files |
| Organisation-wide rules | managed instructions deployed by IT, such as Claude Code's managed `CLAUDE.md`, which loads before project files | [managed policy across every agent](/en/org/managed-policy/) |
| A rule and a control disagree | the control; fix the rule's wording | the map from each hard rule to its control, reviewed quarterly |

## Roll out shared rules without a big-bang rewrite

1. **Inventory every source.** List each `AGENTS.md`, `CLAUDE.md`, `.claude/rules/` file, Cursor rule and personal default in use, with its scope and owner. The first prompt below does the reading; on the Claude side, `/doctor prompt-audit` (v2.1.283) also flags contradicting `CLAUDE.md` and `AGENTS.md` files.
2. **Choose the canonical core.** Move durable rules into the root `AGENTS.md`, keep it under 200 lines (the size Anthropic's memory page recommends per file), and link to architecture docs instead of pasting them. Use [the ablation protocol](/en/workflows/context/pruning-context-files/) to decide what earns a line.
3. **Replace copies with adapters.** Each `CLAUDE.md` becomes `@AGENTS.md` plus Claude-only lines. Delete the duplicated text in the same pull request, so there is never a period with two live copies.
4. **Map hard rules to controls.** For every "never" in the core, name the control that enforces it: a permission rule, a sandbox mode, a CI job, branch protection. A rule with no control is advice, and the core should say so.
5. **Add the CI check and the probe.** Both are below. The CI check runs on every pull request; the probe runs on rule changes and after tool upgrades.
6. **Assign ownership.** Put the rule files under a `CODEOWNERS` entry, and require every rule change to cite what prompted it: an incident, a review comment, an onboarding failure.

**Copy-paste prompt: inventory the instruction sources**

```text
List every file in this repository that gives a coding agent instructions:
AGENTS.md, AGENTS.override.md, CLAUDE.md, CLAUDE.local.md, .claude/rules/**,
Cursor project rules, and any SessionStart hook that prints instructions.
For each file give: path, which tools load it (Claude Code, Codex, Cursor),
lines and bytes, owner from CODEOWNERS. Then list every rule that appears in
more than one file, every pair of rules that contradict each other, and every
"never" or "always" rule with no enforcing control (permission rule, sandbox,
CI job, branch protection). Output three tables. Do not edit any file.
```

**Copy-paste prompt: refactor into one core and thin adapters**

```text
Refactor this repository's agent instructions into one shared core:
1. Merge durable rules (commands, definition of done, protected paths, human
   gates, owners) into the root AGENTS.md, under 200 lines. Keep the first
   "Rules version:" line and bump its suffix.
2. Replace each CLAUDE.md with "@AGENTS.md" on line 1, followed only by rules
   that apply to Claude Code alone.
3. Keep directory-specific rules in that directory's AGENTS.md, each with a
   CLAUDE.md adapter next to it.
4. Delete every duplicated sentence; do not leave two copies of any rule.
Show the diff and a table mapping each old rule to its new location or to
"deleted: duplicate of <location>". Do not change any file outside these.
```

**Copy-paste prompt: probe a fresh session**

```text
Answer only from the project instructions you were given at session start.
Do not open any file. Reply in exactly four lines:
1. The "Rules version:" line, verbatim.
2. The command that runs the unit tests.
3. May you edit services/billing/migrations/ without asking? Yes or no, and why.
4. Which rule wins if services/billing/AGENTS.md contradicts the root AGENTS.md?
```

## Prove every agent loaded the rules without reading transcripts

Verification has two layers. The deterministic layer checks files and needs no model. The probe layer asks each agent what it loaded and compares the answer with the canary.

**Layer 1: a CI check on every pull request.** It fails when an adapter is missing, when a Codex-only override or a Claude-only `.claude/AGENTS.md` is committed, or when a directory's chain exceeds Codex's default budget. Tested with bash on 2026-09-26.

```bash
#!/usr/bin/env bash
# scripts/check-agent-rules.sh: deterministic, no model calls. Run from the repository root.
set -euo pipefail
fail=0
files=$(find . -name 'AGENTS*.md' -not -path './node_modules/*' -not -path './.git/*')

for f in $files; do
  d=$(dirname "$f")
  case "$f" in
    */AGENTS.override.md) echo "$f: Codex-only override is committed"; fail=1; continue ;;
    */.claude/AGENTS.md) echo "$f: read by Claude Code only; merge it into AGENTS.md"; fail=1; continue ;;
    */AGENTS.md) ;;
    *) continue ;;
  esac
  # Claude Code adapter: a CLAUDE.md next to every AGENTS.md whose first line imports it
  if [ "$(head -n 1 "$d/CLAUDE.md" 2>/dev/null)" != "@AGENTS.md" ]; then
    echo "$d: needs a CLAUDE.md whose first line is @AGENTS.md"; fail=1
  fi
  # Codex budget: every AGENTS.md from the root down to this directory
  total=0; p="$d"
  while :; do
    [ -f "$p/AGENTS.md" ] && total=$(( total + $(wc -c < "$p/AGENTS.md") ))
    [ "$p" = "." ] && break
    p=$(dirname "$p")
  done
  if [ "$total" -gt 32768 ]; then
    echo "$d: AGENTS.md chain is $total bytes, over Codex's 32 KiB default"; fail=1
  fi
done
exit "$fail"
```

**Layer 2: a fresh-session probe per tool.** Run it when a rule file changes and after every tool upgrade. The canary grep is the pass/fail signal; the other three answers are for the owner to skim.

```bash
#!/usr/bin/env bash
# tests/agent-rules/probe.sh: run from the repository root on a trusted checkout
set -euo pipefail
CANARY=$(grep -m1 '^Rules version:' AGENTS.md)
PROBE=$(cat tests/agent-rules/probe-prompt.txt)   # the probe prompt above

codex debug prompt-input "noop" | grep -qF "$CANARY" || { echo "Codex: core not in prompt"; exit 1; }
claude -p "$PROBE" --permission-mode plan > claude.out
codex exec --sandbox read-only --ephemeral -o codex.out "$PROBE"
for out in claude.out codex.out; do
  grep -qF "$CANARY" "$out" || { echo "$out: canary missing"; exit 1; }
done
```

The script has no line for Cursor; its CLI command is `agent` (Cursor docs, checked 2026-10-12), but this page did not test the probe through it, so paste the same probe into a new Agent chat and record the result in the pull request.

Run the probe on the default branch, locally, or on pull requests from branches in the same repository. Never run it from `pull_request_target` or on a fork's code while secrets are in the environment: a contributor's `AGENTS.md` is instructions your agent will follow. The probe uses plan mode and a read-only sandbox so it cannot write, but that is a second line of defence, not the first.

**Sign-off.** The harness owner in `CODEOWNERS` approves every rule change. The pull request carries the CI check result, the probe output per tool, and the incident or review comment that motivated the change. A reviewer checks those artefacts, not the full diff of every transcript. Report the same three items when you answer question 5.

## What breaks when teams share agent rules?

**Claude Code ignores `AGENTS.md`.** Symptom: the probe returns no canary in Claude Code while Codex passes. Cause: someone has a `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above, runs a build older than v2.1.277, or, in some cases, is in the first session after upgrading from 2.1.276 or earlier. Recovery: add the `@AGENTS.md` adapter; it works in all three cases.

**Codex drops the package rules.** Symptom: a rule from `services/billing/AGENTS.md` is followed when Codex starts in `services/billing/` and ignored when it starts at the root. Cause: Codex builds its startup chain only from the root down to the working directory. Recovery: move rules that every session needs into the root core, and tell engineers to start Codex in the package they are changing.

**Codex truncates the chain.** Symptom: the canary is present but a directory rule is missing from `codex debug prompt-input`. Cause: the chain passed 32 KiB and Codex truncated it, logging only a warning. Recovery: cut the core, starting with anything the ablation protocol cannot justify. Raise `project_doc_max_bytes` only after the cut, and only with a written reason.

**Codex and Claude Code disagree on one directory.** Symptom: behaviour differs by tool in one directory only. Cause: an `AGENTS.override.md` that Codex reads and Claude Code ignores. Recovery: delete it, move the content into `AGENTS.md`, and keep the CI check that fails on it.

**Codex loads no project rules at all.** Symptom: an empty instructions block in `codex debug prompt-input` on one machine. Cause: that project is marked untrusted there, because someone declined the trust prompt or `~/.codex/config.toml` sets `trust_level = "untrusted"` for it; since 0.150.0 an untrusted project does not supply project-level `AGENTS.md`. Recovery: set the project to trusted on that machine, and keep the canary check in [the onboarding fixture](/en/cto-scorecard-guide/dev-onboarding-time/).

**The core loads twice.** Symptom: context grows and the fresh-session probe (or asking the session to quote its instructions) shows the core twice: once from the `SessionStart` hook output and once from the loaded file. Cause: a `SessionStart` hook that prints `AGENTS.md` still runs after Claude Code learned to read the file. Recovery: remove the hook; the `@AGENTS.md` import never duplicates.

**A rule is treated as a security control.** Symptom: an agent reads `.env` although the core says "never read `.env`". Cause: instructions steer the model; they do not bind it. Recovery: enforce with permission rules or a sandbox, reviewed as code in [shared hooks governance](/en/cto-scorecard-guide/shared-hooks-governance/), and keep the sentence in the core only as an explanation of the control.

**Policy by duplication creeps back.** Symptom: the inventory prompt finds the same rule in three files. Cause: a migration command or a well-meaning engineer copied text instead of importing it. Both Claude Code and Codex offer `/import` for another tool's configuration; run it once during migration, then run the inventory prompt and delete the copies.

## Where to go next after shared agent rules

Before this page: [make the codebase agent-ready](/en/workflows/harness/agent-ready-codebase/) and read [how teams share context and rules](/en/teams/adopt/team-collaboration/). After it, package procedures that do not belong in always-loaded rules as skills, and move hard requirements into reviewed controls.

- [Q6 · Shared skills](/en/cto-scorecard-guide/shared-skills/) — Package tested procedures that should load on demand, not in every session.
- [Q18 · Shared hooks governance](/en/cto-scorecard-guide/shared-hooks-governance/) — Review and test the runtime controls that enforce your hard rules.
- [Managed policy across every agent](/en/org/managed-policy/) — Enforce one organisation-wide policy that project files cannot weaken.
- [Shape a backlog for agents](/en/teams/agent-ready-backlog/) — The next step on the tech lead track: tasks an agent can finish and prove.
