Claude Reads AGENTS.md, Not AGENTS.override.md • The Weighted Average

Teams sharing instructions between coding agents should audit filenames before deleting their Claude compatibility file: Claude Code v2.1.277 adds native AGENTS.md support, but not Codex’s AGENTS.override.md convention. Comparing the vendors’ discovery rules leaves 1 of 2 default Codex project-instruction filenames recognized by Claude’s direct AGENTS loader—a portability boundary, not a model-quality score.

The shared filename hides different loading rules

The release changes a real maintenance decision. A repository without a CLAUDE.md can now supply its AGENTS.md directly, while the Project instructions setting controls alternatives. Gihyo’s account of the September 18 announcement describes the new support and the preceding workaround of importing AGENTS.md from CLAUDE.md. Teams maintaining duplicated prose can reduce that duplication. Teams already using an import may have little reason to change anything immediately.

The denominator comes from OpenAI’s instruction-discovery documentation. At each project directory, Codex checks AGENTS.override.md before AGENTS.md, then configured fallback names, and includes at most one file there. Anthropic’s memory documentation explicitly excludes AGENTS.override.md from direct loading. Of those two default Codex filenames, one intersects with Claude’s AGENTS convention: 1 ÷ 2 = 50% of the filename set. That does not mean half of a repository’s instructions disappear; actual coverage depends on where its rules live.

The failure case is quite ordinary. A team may put shared project guidance in AGENTS.md and specialized instructions in a nested override file. Codex can prefer that override when launched in the relevant directory. Claude’s new support does not establish equivalent discovery. A successful startup on both tools therefore proves less than the team might think. The important question is whether the same task receives the same operative build, test, and review requirements.

Claude’s default has another condition. Its documentation says a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it takes precedence over direct AGENTS loading. User-level managed context has separate rules. A root-only search can miss a parent file that explains why the new behavior did not activate. Diagnose the directory chain before assuming the release failed or copying instructions into yet another location.

There are 4 Project instructions modes in Anthropic’s documentation: default fallback, both file families, CLAUDE.md only, and managed-only startup. They are configuration choices, not four different compatibility guarantees. The settings apply at supported user or managed configuration scopes; project and local settings do not control this option. A repository cannot assume that committing a preferred setting silently standardizes every developer’s client.

The published AGENTS mod documentation further narrows equivalence. Subdirectory discovery occurs when Claude reads a text file there, rather than establishing universal parity with every other tool’s traversal. The main memory guide also says AGENTS files in directories supplied through the relevant additional-directory mechanism do not load like CLAUDE files. A format shared across tools is useful precisely when these differences remain explicit.

Keep the bridge until every execution path passes

The cheapest safe migration may be no migration. Anthropic says an existing CLAUDE.md containing an AGENTS.md import can remain, and the imported content is not loaded twice under the combined setting. Keep that bridge when any production path still needs it. Removing a tiny compatibility file is not worth losing instructions in a background job, provider-specific session, or developer environment that has not acquired the new capability.

Availability is narrower than the version number alone. The release notes exclude Bedrock, Vertex, and Foundry initially. The current memory guide additionally identifies sessions that do not fetch the required feature flags, telemetry-disabled configurations, the first session after upgrade, and hook/plugin restrictions. The right response is not to relax organizational privacy settings for a filename convenience. Preserve the import when the chosen operating policy makes direct support unavailable.

The cost is principally audit and migration effort, not a published new feature fee. Inspect where instructions are authored, which files are maintained independently, and which jobs depend on overrides. Put genuinely shared requirements into a shared source, while retaining tool-specific behavior where needed. Do not flatten specialized requirements merely to make the directory listing look cleaner. A smaller file count can conceal a larger behavioral divergence.

Our Brig analysis distinguished a named integration from a verified runtime. Apply the same standard here. A compatibility test should launch the actual tool and provider from the actual working directory, then verify that task-specific requirements arrived. Asking the agent to summarize its instructions can help diagnose loading, but an independently checked build or review artifact should prove that consequential requirements were followed.

Observability also differs. Anthropic says directly loaded AGENTS.md does not appear in the normal memory-file list and does not trigger InstructionsLoaded hooks; an imported file follows the usual CLAUDE path. A team whose audit process relies on those signals should not remove its bridge until the replacement evidence is acceptable. Invisible in that list does not mean absent from context, but neither should absence be casually dismissed during a compliance check.

The strongest counterpoint is a simple repository: no overrides, no conflicting parent file, and supported clients. For that team, direct loading can remove a workaround without changing substantive instructions. The verdict changes when the actual execution matrix demonstrates parity, not when a feature announcement adds the word support. Conversely, one unattended path missing a required rule is enough reason to retain compatibility while investigating.

Today’s AI Employees lead separates portable instructions from proven operation. Claude’s addition is welcome progress toward shared authoring, not a universal execution contract. Consolidate duplicate prose now where it is safe; retire compatibility files only after the relevant paths pass. The shared filename is a starting point. The loaded instructions are the product.