Feature Request: native AGENTS.md support (duplicate of #6235, filed deliberately)

Summary

Claude Code still does not natively read AGENTS.md. This is a deliberate duplicate — please close it against #6235 and the rest of the pile. The point of filing it is the pile.

Prior art (all still open)

| Issue | Opened | 👍 | Comments |
|---|---|---|---|
| #6235 Feature Request: Support AGENTS.md. | 2025-08-21 | 4407 | 341 |
| #31005 Support for AGENTS.md and .agents/skills/, the community has been asking since August 2025 | 2026-03-05 | 262 | 16 |
| #34235 support AGENTS.md as a native context file alongside CLAUDE.md | 2026-03-14 | 86 | 14 |
| #62371 Support global ~/.agents/AGENTS.md along with project-level | 2026-05-26 | — | 3 |
| #69151 Claude Code needs AGENTS.md support, repository-aware tool selection | 2026-06-17 | — | — |

#6235 has been open for ~11 months with 4.4k upvotes — one of the most-upvoted issues in the repo — and there is still no native support.

Why the CLAUDE.md workaround is not a fix

The standard answers are "symlink it" or "@import it from CLAUDE.md". Both are worse than they sound:

• Symlinks are actively broken. #66559: Claude refuses to write CLAUDE.md when it is a symlink.
• @import is unreliable across directories. #78697: @import in an ancestor CLAUDE.md does not expand on subdirectory launch. #78216: @imports in a parent-directory CLAUDE.md are silently ignored.
• It does not scale to nested scopes. AGENTS.md is used as a hierarchical instruction surface — one per directory, deeper files overriding parents. Reproducing that with a parallel tree of CLAUDE.md files that each @import a sibling means maintaining two files per scope forever, with the import bugs above sitting under all of it.

Concrete impact

In a monorepo where AGENTS.md is the scoped instruction surface, every subdirectory carries one, and CI enforces that a manifest change updates the nearest map in the same commit:

check-agents-map: map drift
  - manifest change requires updating nearest map: hosts/AGENTS.md (touch it in the same commit)

Claude Code does not load those files, so it edits against the parent CLAUDE.md and gets rejected at the push gate — after the work is done. Every other agent in the same repo (Codex, and anything else following the AGENTS.md convention) reads them natively.

The convention is now shared across the ecosystem. Claude Code is the one that needs a workaround, and the workarounds have their own open bugs.

Ask

Read AGENTS.md natively, with the same discovery and precedence rules as CLAUDE.md:

• Load AGENTS.md at every level CLAUDE.md is loaded (project root, nested directories, ~/.claude/).
• When both exist in the same directory, load both; CLAUDE.md wins on conflict.
• Deeper files override shallower ones, matching the convention's existing semantics.
• No new configuration required to turn it on.

Closing this as a duplicate is the correct action. Please also say something on #6235.