AGENTS.md vs CLAUDE.md: Which Files Your Coding Agents Actually Read

Claude Code reads CLAUDE.md and not AGENTS.md, most other agents read AGENTS.md, and an import is what lets the two coexist, because the specification fixes nearest-file precedence and leaves cross-filename behavior to each tool.

A repository carries AGENTS.md at the root and CLAUDE.md beside it, plus an earlier-priority .cursorrules file. A developer opens the checkout in Zed, whose instruction loader uses .cursorrules and skips both maintained files. Every agent in that repository now works from a different rule set, and the mismatch remains hidden until an agent breaks a convention one of the files states plainly.

AGENTS.md is a plain Markdown instruction file that may appear at a repository root or in nested directories. What belongs inside the file is covered by the guide on building an AGENTS.md; this page is about which tool opens which filename. This guide is for an engineer or platform owner who already maintains one of these files and is adding a second tool to the repository. It covers which filename each tool reads and what each tool does with nested or conflicting files. Every behavior reflects the vendor's own documentation page as read on September 8, 2026.

The Spec Leaves Tool Precedence Underspecified

The AGENTS.md specification, stewarded by the Agentic AI Foundation under the Linux Foundation, answers the conflict question in one sentence of its frequently asked questions (FAQ): "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." The same page states that the format has no required fields and uses standard Markdown with any headings the author likes. It says agents read the nearest file in the directory tree so each subproject can ship its own instructions.

That nested-file line implies traversal, since something has to walk the tree to find the file closest to the edited path. Each of the implementations below answers the remaining context-assembly questions its own way.

"Closest file wins" reads as override semantics, where one file applies and the others do not. The tools that adopted the format resolved the same conflict in different ways.

AGENTS.md vs. CLAUDE.md by Tool

Five tools have confirmable behavior for these two filenames, and their pages disagree both on which file to open and on what to do with a nested copy.

Three Augment Code surfaces read both filenames directly, and for two of the three that reading happens during review. Cosmos, Augment Code's unified cloud agents platform available on all paid plans, is where that matters most. Its Deep Reviewer Expert runs autonomously inside a code review pipeline and checks a change against repository guidance such as AGENTS.md and CLAUDE.md. The two files that shape how code gets written therefore also set what a reviewer holds it to. Code Review discovers and applies either filename automatically where a repository already carries one, and its review guidelines cover what else it reads. Auggie, the Augment Code CLI, places CLAUDE.md ahead of AGENTS.md when both exist, which is the clearest sign that the specification settles nothing: two tools can read both filenames and still disagree about which one leads. A checkout opened by several agent desktop apps inherits all of these precedence orders at once, one per tool, on the same set of files.

Three Ways Tools Resolve a Conflict

Three resolution models are in use and no two agree. Codex and Claude Code concatenate files root down, Zed takes the first match on a fixed list, and Cascade in Devin Desktop scopes each file to the directory holding it. One repository tree therefore hands three different instruction sets to three agents, and none of them reports that it did.

Concatenation, Root Down

The Codex instruction guide documents how Codex assembles its instruction chain once per run. It walks from the Git root down to the working directory and checks override and standard names before configured fallback names. Codex concatenates the selected files root first and joins them with blank lines. A file closer to the working directory overrides earlier guidance by appearing later in the combined prompt.

Codex adds two implementation details to the nearest-file rule. AGENTS.override.md skips the AGENTS.md beside it, so edits to the maintained file no longer reach the model from that directory. Codex caps the combined size through project_doc_max_bytes, 32 KiB by default. It skips empty files and stops adding files once that cap is reached, so in a long chain the deepest file is the one most likely to fall off the end. CLAUDE.md enters this chain only when a team adds it to project_doc_fallback_filenames. Because Codex includes at most one file per directory, a directory holding both files contributes its AGENTS.md.

The same shape applies to the other filename. Claude Code's memory documentation says it loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it: "All discovered files are concatenated into context rather than overriding each other." Ordering runs from the filesystem root down, so for foo/bar/ Claude Code reads foo/CLAUDE.md before foo/bar/CLAUDE.md. Within one directory, Claude Code appends CLAUDE.local.md after CLAUDE.md. That behavior directly denies the spec's override reading because a root CLAUDE.md rule that a nested file contradicts still reaches the model in full. Claude Code handles files below the working directory differently: it discovers them but loads them only when it reads files in those subdirectories.

First Match, No Traversal

Zed reads exactly one project instruction file. Its instructions page, read against Zed 1.18.1 on the stable channel, lists the candidates in the order it checks them: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. The first match wins and the search stops. Nothing traverses the directory tree, so a nested AGENTS.md has no role in Zed at all. A repository carrying both files gives Zed the AGENTS.md at position seven, and Zed never opens the CLAUDE.md at position eight. A .cursorrules sits at position two, five places ahead of AGENTS.md, so that dotfile decides the whole project's instructions on its own.

Personal instructions live at ~/.config/zed/AGENTS.md, and project instructions override personal ones where the two conflict.

The same Zed instructions warn that External Agents and Terminal Threads may read their own native instruction files directly, outside Zed's instruction loader. Zed's external agents page says Claude Agent may read CLAUDE.md directly. A CLAUDE.md that Zed's own agent skips at position eight can therefore reach Claude Agent running inside the same editor. One checkout then feeds two agents different files: Zed's agent works from whatever matched first on the nine-name list, and Claude Agent works from CLAUDE.md.

Location-Scoped Globs

Cascade infers a file's scope from where it sits in the tree, with no frontmatter involved. The Cascade AGENTS.md page says it matches AGENTS.md case-insensitively across the workspace and searches parent directories up to the Git root, feeding the same rules engine as .devin/rules/ and the legacy .windsurf/rules/. Windsurf became Devin Desktop on June 2, 2026, which is why that page carries Devin branding, as its product FAQ records. A root-level file becomes an always-on rule whose full content enters the system prompt on every message. A subdirectory file becomes a glob rule with an auto-generated <directory>/** pattern, and it applies only when Cascade reads or edits files inside that directory.

A nested AGENTS.md can therefore be committed, correct and never read, because the agent spent the session in a sibling directory. Under concatenation the same file would have loaded on every run.

On the CLAUDE.md side, the paths frontmatter in .claude/rules/ gives a team the explicit glob that Cascade infers from location.

Running Both Files in One Repository

Keep AGENTS.md as the single source in a repository that serves both tools, and make CLAUDE.md a thin wrapper that imports it. Claude Code's import syntax uses @path/to/import, so a CLAUDE.md that carries only the cross-tool import and Claude-specific additions reads like this.

@AGENTS.md

## Claude Code additions

Run the full test suite before proposing a commit.
Never edit files under generated/.

At launch, Claude Code expands @AGENTS.md and loads its contents into context alongside the CLAUDE.md that references it, then reads the Claude-specific lines after it. Relative paths resolve against the file containing the import, not the working directory, so the wrapper behaves the same from any subdirectory a developer launches in. The parser skips Markdown code spans and fenced code blocks, so a path a team wants to mention without importing, such as @README, needs backticks.

With no Claude-specific content, a symlink hands Claude Code the same bytes Codex reads.

ln -s AGENTS.md CLAUDE.md

After that command, Claude Code loads the AGENTS.md content under the CLAUDE.md name, and any edit to AGENTS.md reaches both tools. That leaves nowhere to put Claude-specific lines, since both names resolve to the same bytes. On Windows, creating a symlink requires Administrator privileges or Developer Mode, and Claude Code directs Windows users to the @AGENTS.md import.

The commands reference documents /import for Claude Code v2.1.213 or later. The command migrates a Codex or Gemini CLI configuration by appending a one-time copy of the instruction file to CLAUDE.md, and carries over Model Context Protocol (MCP) servers, commands, subagents and skills. Its --dry-run flag previews the result and --yes skips the interactive picker. An @AGENTS.md import reads the current AGENTS.md at every launch, so one edit reaches both tools. /import produces a copy that stops tracking AGENTS.md the moment either file changes. The two files then drift unless a developer reruns the command or deletes the copy.

Path-specific rules live in .claude/rules/ as Markdown files with a paths frontmatter field. Claude Code loads a rule with paths when it reads a matching file, so a TypeScript convention arrives the moment the agent opens a matching source file and stays out of context during a documentation edit. Claude Code loads a rule written without paths at launch and applies it everywhere, so a service-specific rule missing that field reaches the model on every run in every directory.

In a monorepo, Claude Code's claudeMdExcludes setting keeps other teams' CLAUDE.md files out of a developer's context, as the same memory documentation records. The setting takes glob patterns or absolute paths and is valid in user, project, local and managed scopes. For managed deployments, that page also describes claudeMd in managed-settings.json, which holds CLAUDE.md content as a Markdown string. Claude Code loads it before user and project CLAUDE.md and honors it in managed and policy settings only. Setting it in user, project or local settings has no effect.

What Goes Wrong in a Repository Carrying Both

Repositories carrying both filenames fail when loaders silently choose different files, byte caps remove local rules, or copied instructions drift. Each correction below targets the mechanism that creates the mismatch.

• Invisible AGENTS.md under a first-match loader: Delete the instruction dotfiles for tools the team no longer runs, or fold their content into AGENTS.md, so the first match on Zed's list is the file you maintain. Until then a stale .cursorrules or .windsurfrules supplies Zed's entire rule set and the committed AGENTS.md is never opened.
• Leaf instructions dropped at the byte cap: Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. Run wc -c on each AGENTS.md between the root and your deepest working directory; if the total approaches 32,768 bytes, trim the root file or raise project_doc_max_bytes in the Codex configuration. Trimming the root file is usually the better move, since a raised cap sends every file between the root and the working directory to the model on each run. Rerun wc -c after the trim to confirm the total sits under the cap.
• Duplicated rules that drift: A convention copied into both AGENTS.md and CLAUDE.md may get edited in only one file. The tools then enforce different versions. Replace the copy with the @AGENTS.md import so CLAUDE.md holds only what Claude Code alone needs. Grep both filenames for the rule's wording afterward; a single hit, in AGENTS.md, tells you no second copy survived the swap.
• One tree, two loading rules: Write nested files so they read correctly under different loading scopes. Codex loads the file unconditionally. Cascade waits for directory access and Zed never loads it. Keep anything every agent must know in the root file.
• Managed policy no project setting can remove: Check managed-settings.json before assuming the repository's own files are the whole context. Claude Code does not allow claudeMdExcludes to exclude a managed policy CLAUDE.md, so an organization-wide instruction keeps applying whatever the project or local settings say. The managed file itself sits outside the checkout. macOS uses /Library/Application Support/ClaudeCode/CLAUDE.md. Linux and Windows Subsystem for Linux (WSL) use /etc/claude-code/CLAUDE.md; Windows uses C:\Program Files\ClaudeCode\CLAUDE.md. Read the path for your platform and match its contents against the rule you could not trace.

What to Do Next

One AGENTS.md plus an @AGENTS.md import is cheaper to maintain, and it holds only while Claude Code's import syntax and Zed's list order keep working. Duplicated files survive any one bridge breaking and drift the moment someone edits a single copy. Choose the import for a repository where you control which tool versions your team runs, and accept duplication only where a mandatory tool cannot import.

Then list every instruction filename in the repository, dotfiles included, and check each against its own tool's documentation for two facts: whether that tool reads the file at all and what it does with a nested copy.

git ls-files | grep -Ei '(^|/)(agents?(\.override)?\.md|claude(\.local)?\.md|gemini\.md|\.rules|\.cursorrules|\.windsurfrules|\.clinerules|copilot-instructions\.md)$'

That command prints every committed match across the tree; a CLAUDE.local.md sitting in .gitignore will not appear and needs a separate find. Run the same check against whatever reviews a change as well as whatever writes it, because a review Expert in Cosmos reads AGENTS.md and CLAUDE.md the same way an authoring agent does, and a file invisible to one is invisible to the other.

Frequently Asked Questions

Related Reading

• 8 Best AI Coding Assistants by Job [Updated August 2026]
• 9 Open-Source Agent Orchestrators for AI Coding (2026)
• 6 Best Spec-Driven Development Tools for AI Coding in 2026
• 5 Best Agentic Development Environments for Enterprise Teams in 2026
• Best AI PR Automation Tools for Engineering Teams 2026