Developer Tools
Why Claude Code Can See AGENTS.md but Still Load CLAUDE.md Instead
An AGENTS.md file existing in the repository does not prove it loaded. Claude Code's documentation, checked September 28, requires version 2.1.277 or later and gives project-path CLAUDE files default precedence. Version-specific restrictions matter: the docs distinguish earlier provider limitations from current support.
Citation-ready: Claude Code's documented AGENTS.md support is conditional on version, session capability and instruction-file precedence; the presence of the file is not evidence that the session used it.
Evidence boundary: Current official documentation audit, not a September 21 release announcement or hands-on compatibility test. No telemetry, hooks, permissions or local configuration were changed. Publication note: Prepared for September 21, delayed by a deployment failure, and published September 28 after source revalidation. Original event dates are retained; this is not a new September 28 announcement.
What happened and why it matters
Instruction discovery is conditional behavior. A nearby local file or unsupported session can explain an apparent compliance problem before the model ever reasons about the instructions.
Primary evidence
Primary reference: Claude Code current memory and project-instruction documentation. Kaleido Field checked the event date and the article's attributed facts against this source.
| Source date | Current documentation retrieved September 28, 2026; exact feature release date not established |
|---|---|
| Checked by Kaleido Field | September 28, 2026, CST |
| Source function | developer tools -> project instruction discovery and evidence of loading |
A local exception can change the default
Project-path CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md take default precedence; user-level and managed files do not trigger that check. Inspect the installed version, relevant files and selected Project instructions setting before diagnosing an ignored instruction.
The current docs say a setting change applies from the next message and in new sessions. Check the observed load signal. The earlier /memory listing issue was fixed in version 2.1.280.
The compatibility boundary has changed
Direct support remains unavailable before 2.1.277, when the built-in agents-md plugin is disabled, and in some first sessions after upgrading from 2.1.276 or earlier. Bedrock and telemetry-disabled restrictions are described as pre-2.1.281 limitations; update the client rather than treating those restrictions as permanent.
A CLAUDE.md import remains a documented fallback. Do not weaken privacy or managed protections for optional instruction discovery. Our agent-maintenance analysis distinguishes reading proposed configuration from authorization to change it.
Evidence boundary
Current official documentation audit, not a September 21 release announcement or hands-on compatibility test. No telemetry, hooks, permissions or local configuration were changed.
FAQ
Should telemetry or managed security controls be weakened to enable direct AGENTS.md loading?
No. The documentation provides an import fallback; this article does not recommend changing those protections.