Claude Code gains fallback support for AGENTS.md

How project instructions are loaded now

Claude Code finally has a practical fallback for AGENTS.md: when no CLAUDE.md-family files are found, the tool uses the project's standard instruction file instead. As of September 24, 2026, this is the behavior described in the Claude Code documentation. It is a small change, but it significantly reduces the hassle of maintaining parallel files.

Claude Code first checks for CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md in the working directory and throughout its parent directory chain. Only when none of those files exists does it load AGENTS.md. The documentation also specifies the interface message: Claude read AGENTS.md instead of CLAUDE.md.

The key point is that this is a fallback path, not an automatic merge of every instruction source. If even one CLAUDE.md-family file is found, AGENTS.md is skipped by default. Joint loading can be enabled in the Project instructions setting with the value claude-md-and-agents-md.

I would first verify not merely whether a file was loaded, but which instructions take priority in the real project tree. An old CLAUDE.local.md forgotten higher up the hierarchy can silently disable the expected fallback. The convenience here depends on transparent discovery: one extra file can change the context source for an entire session.

What this changes for repositories

The main benefit is straightforward: projects that use AGENTS.md no longer need a separate CLAUDE.md solely for Claude Code compatibility. Less duplication means fewer chances for two instruction sets to drift apart and give the agent conflicting rules.

For teams that already maintain CLAUDE.md, behavior changes very little. But during a gradual move to a shared AGENTS.md, the strict fallback condition matters: as long as an old file remains somewhere in the directory chain, the new source will not activate. This is one of those cases where a forgotten configuration matters more than a polished announcement.

The update may look minor, yet it has real engineering value: Claude Code becomes easier to integrate into repositories that use one common agent-instruction file. The remaining challenge is no longer the format itself, but predictable behavior when local and parent-level settings conflict.

We previously covered how parallel Claude Code agents can review pull requests and surface race conditions in CI/CD workflows. That workflow also depends on giving agents clear repository-level instructions, which AGENTS.md now simplifies.