Nested `AGENTS.md` not loaded when a file in its directory is `@`-mentioned (nested `CLAUDE.md` is)

Status Open

Reported on v2.1.287

Maintainer reply None cached

Activity 0 comments · opened Oct 1, 2026

Description

With native AGENTS.md support (v2.1.277+) and the default Project instructions setting (claude-md-or-agents-md), a subdirectory's AGENTS.md loads when Claude opens a file there with the Read tool. It does not load when the user @-mentions a file in that directory.

A nested CLAUDE.md does load on @-mention. Nested AGENTS.md should load on the same triggers as nested CLAUDE.md. Other harnesses (Codex, Cursor, etc.) pick up subdirectory AGENTS.md files.

Environment

Claude Code 2.1.287, macOS
pluginConfigs["agents-md@builtin"].options.instructionFiles = "claude-md-or-agents-md" (default)
Monorepo with a root AGENTS.md and no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above

Steps to reproduce

Repo with AGENTS.md at the root, no CLAUDE.md anywhere at or above the working directory.
Add pkg-a/AGENTS.md and pkg-a/server.ts. Add pkg-b/CLAUDE.md and pkg-b/package.json. Neither folder has the other instruction file.
Start a session at the repo root. The root AGENTS.md loads as expected.
Send @pkg-a/server.ts …. pkg-a/AGENTS.md is not attached.
Send @pkg-b/package.json …. pkg-b/CLAUDE.md is attached automatically.
Have Claude open any file in pkg-a/ with the Read tool. pkg-a/AGENTS.md is now attached.

Expected

In step 4, pkg-a/AGENTS.md is attached, the same way pkg-b/CLAUDE.md is in step 5.

Actual

A nested AGENTS.md loads only after a Read tool call in its directory. The @-mention path triggers nested loading for CLAUDE.md but not for AGENTS.md.

Notes

The docs ("When Claude Code reads AGENTS.md") say a subdirectory AGENTS.md loads "when Claude opens a file there with the Read tool". So this may be documented behaviour, but it doesn't match nested CLAUDE.md. The docs' "Where AGENTS.md differs from CLAUDE.md" table doesn't list this difference.
Related: #93403 (nested CLAUDE.md and skills not loaded when files are reached through Bash or Grep), #6235 (AGENTS.md support).

View original on GitHub ↗