Last checked: October 6, 2026. This replaces the earlier May 2026 answer. The original publication date and URL are retained.
Does Claude Code read AGENTS.md?
Yes, in supported versions and sessions. Direct loading requires Claude Code v2.1.277 or later. By default, a working-directory or ancestor CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md makes Claude use the CLAUDE files instead. Otherwise, AGENTS.md can load directly. Your user-level ~/.claude/CLAUDE.md and managed instructions do not trigger that fallback. See the official loading rules.
A filename alone is therefore not enough to diagnose missing instructions. Check the installed version, the directory where the session starts, and its parent directories before changing a working setup.
Choose a setup for your repository
| Situation | Practical choice |
|---|---|
| Existing AGENTS.md-only repository | Check direct loading before adding another file. |
| Working CLAUDE.md import | Keep it unless you have a specific reason to migrate. |
| Shared rules plus Claude-specific notes | Use the import below, with Claude-only notes after it. |
| Mixed or older client versions | Prefer a setup each team member can verify locally. |
A CLAUDE.md wrapper remains supported:
@AGENTS.md
## Claude-specific notes
- Run the billing integration tests before changing billing behavior.The current import documentation specifies a maximum of four hops. Relative imports resolve from the importing file. External imports have approval requirements; do not assume every colleague has approved them.
Verify before removing a wrapper
This is a suggested review checklist, not a test we ran in your environment:
- Record the Claude Code version and session working directory.
- Inspect the relevant instruction files, including parent directories and local files.
- Inspect
/memoryor/contextfor the loaded files. Before v2.1.280, directly loaded AGENTS.md files were not listed there; ask Claude what its project instructions say on those versions. - Try one harmless, project-specific instruction and inspect the result.
- Review the change with teammates before removing an import or symlink.
Instruction loading and reliable instruction following are different checks. Keep shared instructions concise and avoid maintaining contradictory copies.
When direct loading is unavailable
Older versions or a disabled built-in AGENTS.md plugin can require the CLAUDE.md import. Some upgrade sessions and pre-v2.1.281 configurations have additional exceptions. Consult the official availability notes before diagnosing a missing file as a project error.
Project instructions in /config can change the default. An existing wrapper need not be removed merely because a newer version supports direct loading. The official migration guidance explains the choices.
FAQ
Is the old “Claude Code never reads AGENTS.md directly” answer still correct?
No. Use the version and loading conditions above. The earlier unconditional answer is outdated.
Must I delete CLAUDE.md?
No. Keep a working import, especially when it also holds Claude-specific notes. Review your actual setup before changing it.
How deep can imports go?
The current documented maximum is four hops. Keep the chain shorter where practical so a reviewer can follow it.
Has this guide tested my repository or every other agent?
No. This update checks Claude Code documentation. Verify your own installed clients and loaded files; it does not claim identical behavior across tools.