One Repo, Many Agent CLIs: Keeping AGENTS.md and CLAUDE.md in Sync

Updated October 4, 2026 · first published August 20, 2026 · by the AQ team

Claude Code reads AGENTS.md natively as of version 2.1.277, released on September 18, 2026: in a project with no CLAUDE.md, it loads AGENTS.md as its project instructions automatically. That changes the default advice for running several agent CLIs against one repository. The simplest setup is now a single AGENTS.md and no CLAUDE.md at all, which Codex, Cursor, OpenCode, GitHub Copilot, and Claude Code all read natively as of October 2026. The @AGENTS.md import and the committed symlink, previously the only bridges, are now fallbacks: you still need one on Claude Code versions before 2.1.277, and a CLAUDE.md anywhere in or above your working directory still takes precedence whenever both files exist. This guide covers the new default, the precedence rules that decide which file Claude Code actually reads, and what to do with the per-tool trees (skills, commands, rules) that still refuse to converge.

Why one repo ends up with three instruction files

AGENTS.md started as OpenAI's convention for Codex in August 2025 and has since become the cross-tool standard: it was donated to the Linux Foundation's Agentic AI Foundation in December 2025, and Codex, Cursor, OpenCode, and GitHub Copilot all read it natively as of October 2026.

Claude Code was the notable holdout until September 18, 2026. For over a year, Anthropic's documentation was explicit that Claude Code read CLAUDE.md and not AGENTS.md, the GitHub request to change that was the most upvoted on the tracker and marked not planned, and guides like this one taught an import or symlink bridge as the only option. Version 2.1.277 reversed that. The changelog entry reads, in full: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config." Version 2.1.281 extended the support to sessions on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled, which had initially been excluded.

The drift problem the old bridges solved has not disappeared, though. A repository that contains both files still feeds Claude Code only CLAUDE.md by default, so a team that fixes the test command in AGENTS.md while an old CLAUDE.md lingers gets exactly the stale-instructions failure this guide has always been about: someone updates one file, the other goes stale, and a week later one CLI "ignores the conventions." It did not ignore anything. It read the other file.

Step 1: make AGENTS.md the only file humans edit

Pick AGENTS.md as the canonical file because it is the one every tool now agrees on. Put in it exactly what every agent needs in every session: build and test commands, project layout, naming conventions, and the "always do X" rules a new teammate would need. Keep it concise; Anthropic's guidance for CLAUDE.md (specific, verifiable instructions, kept short) applies equally well here, since Claude Code loads this file directly. Everything else in this guide exists to make sure no second file competes with this one.

Step 2: decide whether Claude Code still needs a bridge

On Claude Code 2.1.277 or later, the default behavior (Anthropic calls the setting "Project instructions", value claude-md-or-agents-md) is:

So if your repo has nothing genuinely Claude-specific, the cleanest setup is one AGENTS.md and no CLAUDE.md anywhere. In an interactive session you can confirm it loaded: Claude Code prints a line such as "no CLAUDE.md found; AGENTS.md loaded" at session start, and /context shows the file under Memory files. One documented gotcha: a personal, uncommitted CLAUDE.local.md counts as a CLAUDE.md for the precedence check, so adding one silently stops Claude Code from reading AGENTS.md for you alone. Also note the lookalike files Claude Code does not read: AGENTS.local.md, AGENTS.override.md (a Codex convention), and anything under a .agents/ directory.

If you want different behavior, /config exposes four Project instructions values as of October 2026: the default (CLAUDE.md, or AGENTS.md when no CLAUDE.md exists), claude-md-and-agents-md (both files, with each directory's CLAUDE.md first; an AGENTS.md already pulled in by an import or symlink is not read twice), claude-md (ignore AGENTS.md entirely), and managed-only (only an organization's managed instructions). The catch for teams: that setting is personal. It lives in your user settings, not the repository, so you cannot set it once for everyone by committing a file to the repo.

That is why the old bridge keeps a job. A CLAUDE.md whose first line is the import travels with the repository and gives every teammate the same result on any Claude Code version:

# CLAUDE.md
@AGENTS.md

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

Use the import bridge when any of these hold: someone on the team runs a Claude Code version before 2.1.277 (or before 2.1.281 on Bedrock, Vertex AI, or an LLM gateway); you have genuinely Claude-specific instructions to add below the import; or you want both files loaded without asking every teammate to change a personal setting. The committed symlink (ln -s AGENTS.md CLAUDE.md) still works too, with the same caveat as always: on Windows, creating symlinks needs administrator privileges or Developer Mode, and a checkout without core.symlinks enabled produces a plain text file containing the literal path, so mixed-OS teams should prefer the import. Whichever bridge you choose, verify it in your next session with /context.

Step 3: the trees that do not symlink

The single-file setup solves prose instructions. Three per-tool directory trees remain, and pretending they are one tree causes more pain than accepting a small amount of duplication.

Skills mostly converge. Claude Code loads skills from .claude/skills/ and Codex loads them from .codex/skills/ (project) or ~/.codex/skills/ (personal), and as of August 2026 both use the same layout: a folder per skill containing a SKILL.md with name and description frontmatter, plus optional scripts and references. Because the format is shared, a skill folder can be symlinked or copied between the two trees, and repo-level skills travel to everyone on clone. If your team keeps reusable workflows anywhere, keep them here.

Commands and prompts do not. Claude Code's custom slash commands live in .claude/commands/ inside the repo. Codex's equivalent, custom prompts in ~/.codex/prompts/, is personal rather than repo-shared, and OpenAI now marks custom prompts deprecated in favor of skills. The practical rule: put team workflows in skills, which both tools share and version, and treat slash commands as personal sugar.

Rules stay per-tool. Cursor's .cursor/rules/*.mdc files carry metadata and globs; Claude Code's .claude/rules/ files use paths frontmatter for the same job (and keep loading even when project instructions come from AGENTS.md). They do not map one to one, so keep them for genuinely path-scoped instructions ("all API handlers must validate input") and resist the urge to mirror universal conventions into them. Universal conventions belong in AGENTS.md, once.

Step 4: clean up the old workarounds, then guard against drift

If you set Claude Code up to read AGENTS.md before it could do so on its own, Anthropic's memory documentation now says what to do with each workaround, as of October 2026:

A CLAUDE.md containing @AGENTS.md: safe to leave. The import is never loaded twice whichever Project instructions value anyone uses, and it keeps covering teammates on older versions. Delete the CLAUDE.md only if it holds nothing else and everyone is current. A CLAUDE.md that tells Claude in words to "read AGENTS.md": replace it with the import or delete it; a worded instruction only works if the model decides to open the file. A symlinked CLAUDE.md: keep or delete, either way the content loads once; note that Claude Code's editing tools refuse to write through a symlink and point at the target instead. A SessionStart hook that prints AGENTS.md: remove it, because once Claude Code reads the file directly the hook puts a second copy in the context.

Migration tooling helps in both directions: Claude Code's /init incorporates existing Cursor rules and Copilot instructions into the file it generates, its /import command (v2.1.213 and later) does a one-time copy of another agent's setup (AGENTS.md, commands, skills, MCP servers), and OpenCode's opencode.json accepts an instructions array that references existing files without duplicating them.

Then make regression impossible. With native support, the cheapest guard is structural: no CLAUDE.md in the repo at all, so there is nothing to drift. For repos that keep a bridge, a CI step that fails when CLAUDE.md stops being thin still earns its keep:

# ci: CLAUDE.md must stay a symlink or an AGENTS.md import
if [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  grep -q "@AGENTS.md" CLAUDE.md || {
    echo "CLAUDE.md must import AGENTS.md, not duplicate it"
    exit 1
  }
fi

Teams that must keep real copies (some hosted environments reject symlinks) should diff the copies in CI instead, and fail the build on divergence. Either way the property you are enforcing is the same: one file humans edit, everything else derived or deleted.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. The one-repo-many-CLIs situation this guide describes is AQ's normal operating mode: agents run as real CLIs (Claude Code, Codex, Cursor Agent, Kimi, Grok, or plain shells) in persistent tmux sessions on your team's VM, often several different CLIs against the same repository in the same week.

Two properties of that setup make the single-source-of-truth discipline pay off. First, every AQ workspace gets its own isolated git worktree on a fresh branch, with dependencies installed automatically, so whichever CLI a teammate launches reads the committed AGENTS.md (or its bridge, where one is still needed) exactly as it exists on that branch; there is no per-machine copy to go stale. Second, the sessions themselves are visible: teammates can open the same workspace and watch the same live session, so when an agent does ignore a convention, someone sees it in the transcript rather than discovering it in review. Sessions survive a closed laptop and resume from any device, each engineer signs into the CLIs with their own Claude or OpenAI account, and agents commit, push, and open PRs that AQ tracks per workspace.

AQ has two plans: Free is a personal sandbox for one person (AQ creates a private machine in an isolated network, nothing to install, no time limit), and Team is $50 per user per month in early access (standard $200, billed monthly, rate locked for your first 12 months) covering VMs you connect from your own cloud or a dedicated always-on AQ-managed VM. If your team is already juggling Claude Code and Codex against one repo, the setup in this guide works anywhere, and AQ is where it stops depending on every laptop being configured the same way. See also: carrying context between Claude Code and Codex and running multiple AI coding agents in parallel.