If the project root has both CLAUDE.md and AGENTS.md, but a subdirectory only has AGENTS.md, how do they combine?
They don't combine — this is evaluated independently at each directory level. The root reads only its CLAUDE.md because one exists there; the subdirectory reads its AGENTS.md because no CLAUDE.md exists at that level. It's normal, not a bug, for different levels to end up sourcing from different files — but if you're not aware of this, it's easy to wrongly assume the subdirectory rules are being merged with the root's under one unified logic.
In practice, it's safer to standardize on one file-naming strategy across an entire project rather than mixing the two conventions across directory levels.
Would an individual developer ever realistically use managed-only mode?
Almost never. This mode is designed for enterprise organizations that need centralized governance — where a company wants every developer's Claude Code to follow one set of rules pushed down by IT or a platform team, with no ability for individual machines to override it, precisely to prevent inconsistent CLAUDE.md or AGENTS.md files from causing divergent behavior across a team. Individual projects or small teams generally don't need this level of lockdown; claude-md-or-agents-md or claude-md-and-agents-md is sufficient.
If you're on a corporate account and notice instructionFiles is set to managed-only while your own CLAUDE.md has no effect at all, that's typically a deliberate platform-team decision, not a misconfiguration.
If a team switches to claude-md-and-agents-md, which file wins when the two conflict?
Public documentation doesn't clearly define a resolution order for direct conflicts. The safer practical assumption is that both files' content gets fed to the model as instructions, and if they directly contradict each other (one says use tabs, the other says use spaces), the outcome depends on how the model itself weighs two simultaneously present instructions — not on a clearly defined override rule.
Teams using this mode should therefore treat AGENTS.md as the broader, cross-tool convention and CLAUDE.md as a narrower, Claude Code-specific addition, and actively avoid letting the two files give contradictory instructions on the same point.
After upgrading to a version that supports AGENTS.md, do I need to manually change anything for this to take effect?
The default mode, claude-md-or-agents-md, is already the post-upgrade default. If your project never had an AGENTS.md to begin with, nothing changes — Claude Code still reads only CLAUDE.md exactly as before. The behavior only shifts if your project (or some subdirectory within it) already has an AGENTS.md with no corresponding CLAUDE.md — in that case, this update means Claude Code starts reading content that was previously ignored entirely, so it's worth checking whether that AGENTS.md's rules (which may target other tools' specific syntax) are actually appropriate for Claude Code.
The safest move after upgrading is to run /status once to confirm the active instructionFiles mode and which file paths are actually being read, before deciding whether any adjustment is needed.
If your team uses Claude Code alongside other AI coding tools (Cursor, Aider, or anything else that follows the open AGENTS.md convention outside the Claude Code ecosystem), one of the more annoying maintenance costs has been keeping near-duplicate instruction files in sync — a CLAUDE.md for Claude Code and an AGENTS.md for everything else, both needing the same edit twice, drifting apart the moment someone forgets one. A recent Claude Code release adds native support for reading AGENTS.md as an instruction file. This piece walks through the actual precedence logic, the four configuration modes, and an easy-to-miss interaction with CLAUDE.local.md that can cause real confusion.
The core rule is simple but easy to misread: at every directory level, Claude Code looks for CLAUDE.md first, and only falls back to reading AGENTS.md in that same directory when no CLAUDE.md exists there. This is not a merge-both mechanism — it's a per-directory either/or check. That means if your project root has both files, Claude Code reads only CLAUDE.md; whatever is in AGENTS.md is silently ignored, even if it happens to be the more current version maintained for other tools. The upside is that if you already have a well-maintained AGENTS.md from using other tools, Claude Code can adopt it as-is with zero rewriting. The downside is that the moment someone drops an empty or stale CLAUDE.md into that same directory — even accidentally — the AGENTS.md content stops applying entirely, with no warning that this happened.
This behavior is controlled by the instructionFiles field in settings.json, with four possible values:
CLAUDE.md. Never falls back to AGENTS.md even when no CLAUDE.md exists — the most conservative, explicit mode, for teams that don't want any implicit fallback behavior.CLAUDE.md at each directory level, falling back to AGENTS.md only when absent — the either/or logic described above.CLAUDE.md to hold Claude Code-specific additions (like slash command conventions) layered on top of an AGENTS.md that holds cross-tool project rules shared with your whole toolchain — both get loaded, not treated as mutually exclusive.Which mode fits depends on your collaboration setup: teams using only Claude Code should generally set claude-md to avoid any surprise file reads; teams running a mixed toolchain are usually better served by claude-md-and-agents-md, so each file does its own job instead of silently overriding the other.
A detail that's easy to overlook in practice is how CLAUDE.local.md (an uncommitted, machine-local instruction file) interacts with AGENTS.md. CLAUDE.local.md takes priority over an AGENTS.md in the same directory — even under claude-md-or-agents-md mode with no CLAUDE.md present, if a CLAUDE.local.md exists, it overrides the AGENTS.md rather than being combined with it. That means if you left an old CLAUDE.local.md on your machine from some earlier debugging session, and your team later migrates fully to an AGENTS.md convention, your local Claude Code is still effectively reading that forgotten local file — producing behavior that diverges from your teammates in a way that's genuinely hard to diagnose unless you specifically remember that stray local file exists.
If your engineering org already runs, or is considering, multiple AI coding tools side by side, this native support directly cuts the time cost of maintaining duplicate instruction files and lowers the risk of instruction drift degrading output quality inconsistently across tools. Before rolling this out, check your current instructionFiles mode via /status or directly in settings.json, and audit every directory level in your project for a stray CLAUDE.local.md — it's more common than you'd expect, especially after anyone has done local debugging or personal configuration and forgotten to clean it up.