AGENTS.md and Cross-Harness Portability

What it takes off your plate: four repo briefs that fight each other

The first thing you can run right now

# Make AGENTS.md the canonical file. Claude Code v2.1.277+ with no CLAUDE.md in the repo: do nothing
# Verify: a new session prints  no CLAUDE.md found; AGENTS.md loaded: <path>
# To load both files: /config -> Project instructions -> claude-md-and-agents-md

# On older versions, or to append Claude-only text, the two earlier recipes still work (content is read once) --
# (1) symlink: simplest when you need no Claude-specific text; prints nothing on success
ln -s AGENTS.md CLAUDE.md
# On Windows a symlink needs Administrator or Developer Mode; use (2) instead

# (2) import: leaves you a place to append Claude-only instructions
# contents of CLAUDE.md:
@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

# Verify: open a new session, run /context, confirm CLAUDE.md is under Memory files

# Gemini CLI takes one setting to accept AGENTS.md (.gemini/settings.json)
{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }
# Inspect what got concatenated: /memory show      Rescan: /memory reload

# Already have Cursor / Copilot rules and want them inside Claude Code
/import                # v2.1.213+, also carries over MCP, commands, subagents, skills

The difference between /import and /init is worth memorizing. /init reads your old rules and regenerates a CLAUDE.md — by default from .cursor/rules/, .cursorrules and .github/copilot-instructions.md; with CLAUDE_CODE_NEW_INIT=1 it also reads AGENTS.md, .devin/rules/, .windsurf/rules/ and .clinerules. /import appends a one-time copy and brings MCP servers, commands, subagents and skills along with it. The first one merges; the second one moves house.

The mechanism: it works because it specifies almost nothing

Three loading semantics; do not conflate them

• Concatenation: Claude Code reads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it and concatenates them, ordered from the filesystem root down — so the file closest to where you launched is read last. Codex does the same from the git root to the current directory, stacked on top of a global ~/.codex/AGENTS.md.
• Nearest wins: Copilot's stated behavior is that the nearest AGENTS.md in the directory tree takes precedence, rather than everything being merged.
• Path-scoped: loaded only when the agent touches a matching file. Claude Code's .claude/rules/*.md use a paths: field in YAML frontmatter, Copilot's .instructions.md use applyTo, Cursor's .mdc use globs. AGENTS.md itself has no such capability — that is the price of being the common denominator.

A property that gets overlooked

The Claude Code docs are explicit: CLAUDE.md content is delivered as a user message after the system prompt. It is context, not enforced configuration. So "I wrote it down and it still ignores me" is not a bug, it is the nature of this layer. To pin an action down — lint must run before every commit, say — the documented answer is a hook, which fires as a shell command at a fixed lifecycle event regardless of what the model decides. The same holds for AGENTS.md, only more so: across harnesses you do not even know whether the other tool has hooks at all.

Real usage and limits: what belongs in the file and what does not

The official trim criteria, verbatim enough to copy

Turned around: to decide whether a line belongs in AGENTS.md, ask three questions. (1) Would a new teammate need to be told this? Yes → keep it. (2) Could the agent find it with one grep? Yes → delete it. (3) Is it true only inside one subdirectory? Yes → move it to a path-scoped rule (.claude/rules/ with paths:) instead of spending context on it every session.

Three boundaries

Nesting may not load the way you assume. Codex walks "git root to current directory", not "every subdirectory". Issue #13288 in openai/codex (opened 2026-03-02, now closed) reports exactly this: launched at the repo root and editing code under go/, the go/AGENTS.md is never merged in. Claude Code's subdirectory CLAUDE.md files, by contrast, are loaded on demand — they enter context when Claude reads a file in that directory. The same nested layout behaves differently under the two harnesses.

Monorepos get polluted by other teams' briefs. Claude Code offers claudeMdExcludes, matched as globs against absolute paths. Put it in .claude/settings.local.json and it stays on your machine:

{ "claudeMdExcludes": ["**/monorepo/CLAUDE.md"] }

Personal preferences do not belong in the canonical file. CLAUDE.local.md (gitignore it) is for your sandbox URLs and test data. Across git worktrees it only exists in the one where you created it, so the docs suggest importing from your home directory instead: @~/.claude/my-project-instructions.md. A new trap: adding a CLAUDE.local.md to a repo that relies on AGENTS.md stops Claude Code from reading AGENTS.md by default (it counts as "having a CLAUDE.md"); to read both, set Project instructions to claude-md-and-agents-md.

The cost and the alternatives: one file for many agents means the lowest common denominator

Three routes, an order of magnitude apart in cost

• A · native loading, or one symlink. Claude Code v2.1.277+ reads AGENTS.md directly in a repo with no CLAUDE.md, with nothing to set up; on older versions add ln -s AGENTS.md CLAUDE.md (the docs confirm the content is read once either way). No dependencies, no maintenance, one canonical file. When it stops being enough: when tools need different wording (you want only Claude in plan mode, say) — switch to the @AGENTS.md import and append below it. Once a CLAUDE.md exists it is the only file read by default, so that import line is not optional.
• B · ruler (roughly 2.9k stars, MIT, per its GitHub repo page, 2026-09). What it kills: hand-syncing config files across dozens of agents. How to use it: npx @intellectronica/ruler apply, canonical text in .ruler/AGENTS.md, distributed to CLAUDE.md, AGENTS.md, .aider.conf.yml and more; the README lists 30 targets (Copilot, Claude Code, Cursor, Windsurf, Cline, Aider, Codex CLI, Gemini CLI, Goose, Zed, Jules and others) and it manages MCP config too. When not to install it: if your team uses one or two agents, the generated artifacts and the CI drift check cost more than they save.
• C · rulesync (roughly 1.4k stars, MIT, per its GitHub repo page, 2026-09). What it kills: the same problem, but its strength is the reverse direction. How to use it: npm install -g rulesync; rulesync import pulls existing configs into .rulesync/, and rulesync convert --from cursor --to copilot,claudecode does a one-shot format conversion without adopting its workflow at all; rulesync generate is the steady-state command. Beyond rules it covers ignore files, MCP, commands, subagents, skills and hooks. When not to install it: if you only need one migration, run convert and uninstall — do not leave a generator living in the repo.

What you can do without installing anything

Make AGENTS.md canonical: Claude Code (v2.1.277+), Copilot and Codex read it natively, and Gemini CLI needs one context.fileName change; on an older Claude Code add one ln -s. Those few steps cover almost everyone's needs at zero cost. A generator only starts paying for itself once "each tool also needs its own paragraph" becomes the norm — at that point you are no longer maintaining one file but a template plus N diffs.