Claude Code AGENTS.md support and precedence in version 2.1.277

That is the whole mechanism as the two first-party sources describe it. There is no priority list to configure, no ordering flag and no merge setting. The only control is the /config toggle, and the only trigger is the absence of a CLAUDE.md at the point where Claude Code looks.

The changelog entry and the announcement post state the rule at two different granularities, and the difference decides how you lay out a repo. The changelog says "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead." The post says "if there is no CLAUDE.md in a folder." Plan against the folder wording, because the same release contains a separate line about the "per-directory CLAUDE.md lookup", which describes discovery as running per directory rather than once per repository.

If the lookup runs per directory and the fallback fires on absence, precedence is decided locally, one directory at a time. On that reading, a root CLAUDE.md does not suppress an AGENTS.md three levels down; it governs the directory it sits in. Equally, a stub CLAUDE.md left in a subdirectory by an older tooling script shadows the AGENTS.md next to it, and neither source gives a way to invert that.

The sources do not spell out the full nested ordering, do not say whether parent and child files are concatenated, and do not define the semantics of the @ import syntax. Those are the details a deep monorepo needs, and the changelog does not supply them. It does supply one related performance change: session start-up for SDK and headless (-p) use was improved so the first turn no longer waits on the per-directory CLAUDE.md lookup. The changelog gives no timing numbers for that lookup before or after the change.

The layout that matches this rule is one instruction file per directory that needs one, with no duplicates. A folder holding both files does not get a merge; it gets CLAUDE.md, plus an AGENTS.md that other harnesses still read, leaving two copies to drift apart.

The announcement thread says AGENTS.md support is built off Claude Code mods, described as an upcoming way to customize the Claude Code harness, that this one is a built-in mod, and that you will be able to build custom versions of project instructions yourself. The thread links to the mod's source on GitHub in the anthropics/claude-code repository, and a Hacker News commenter links to the same source under a mods/ path; the full path is truncated in both sources. One commenter asked whether AGENTS.md awareness was simply part of the system prompt and was corrected with the mods link. For anyone building tooling, the distinction matters: project-instruction discovery is presented as a mod rather than a fixed harness behaviour, which is a different extension point from hooks, skills or MCP servers.

Commenters on Hacker News mostly describe removing the workarounds this replaces. One mentions deleting a sync-agent-docs.sh that recursively symlinked AGENTS.md to GEMINI.md and CLAUDE.md. Another posts a global post-checkout git hook that symlinks .agents/skills to .claude/skills, which is a reminder that the fallback covers instruction files only and leaves the skills path unsolved for people with an .agents directory. A third shares a CLAUDE.md whose entire content tells Claude to treat AGENTS.md exactly as it would a CLAUDE.md, at root level and in any subdirectory, ending with an @AGENTS.md line. Neither source documents that import syntax, so treat it as a community pattern rather than specified behaviour.

The design objection is about model-specific prompting. One commenter argues that prompts should be tuned for models and that blindly applying AGENTS.md is probably an antipattern, because it converges every model on a common, ill-defined standard of instruction following: a good local minimum and a bad global one. Others frame the change as a response to user pressure and lost users rather than goodwill. Two commenters raise the adjacent thing neither source addresses, using a Claude subscription inside other harnesses; the changelog and the announcement say nothing about it. The fallback makes the instruction file portable and says nothing about credentials.

Three gaps are worth tracking. First, the backend gap: the changelog says "not yet on Bedrock, Vertex or Foundry" without a version or date, and the same release treats those three separately elsewhere, changing the Bash sandbox instructions there to the first-party wording and reframing workflow scripts' computed agent() prompts as script-authored text. Second, nested and import semantics: the sources establish absence-triggered fallback and a per-directory lookup, and stop there. Third, whether the mods mechanism will let teams define their own precedence, since the thread promises custom project instructions without describing the interface.

Until those are documented, the defensible posture is one instruction file per directory, CLAUDE.md retained wherever a Bedrock, Vertex or Foundry session might run, and a check of the "Project instructions" setting in /config on each machine.