AGENTS.md vs CLAUDE.md: Claude Code now falls back to AGENTS.md

Teams that use more than one coding agent have been maintaining the same instructions several times over: a CLAUDE.md for Claude Code, an AGENTS.md for Codex and others, and assorted rules files for everything else. That changed on 18 September. Claude Code now reads AGENTS.md when a project has no CLAUDE.md, which settles most of the AGENTS.md vs CLAUDE.md question — as long as you understand that it is a fallback, not a merge.

What changed in Claude Code 2.1.277

The Claude Code changelog entry for version 2.1.277, dated 18 September 2026, reads: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config (not yet on Bedrock, Vertex or Foundry)."

Three details matter:

• It is a fallback. If a CLAUDE.md exists, Claude Code uses it and ignores AGENTS.md by default. The two files are not combined.
• It is configurable. The behaviour can be changed in the Project instructions setting.
• It is not everywhere yet. Teams running Claude Code through Amazon Bedrock, Google Vertex or Microsoft Foundry do not get it yet.

What is AGENTS.md?

AGENTS.md describes itself as "a simple, open format for guiding coding agents, used by over 60k open-source projects" — a README for agents. It is plain Markdown with no required fields: setup and test commands, code style, conventions, and anything else an agent needs that would clutter a human README. The site lists a growing set of tools that read it, including OpenAI's Codex, Google's Jules, Aider, goose, opencode, Zed, Warp and VS Code. Claude Code's fallback puts the most widely used holdout on the same file.

Should I use AGENTS.md or CLAUDE.md?

For most teams using more than one agent: make AGENTS.md the single source of truth, and do not create a CLAUDE.md unless you need Claude-specific instructions. The rules of thumb:

• One agent, Claude Code only: either works. AGENTS.md keeps your options open.
• Several agents: use AGENTS.md. Delete duplicated content from tool-specific files.
• Claude-specific needs: if you keep a CLAUDE.md, remember that Claude Code will then ignore AGENTS.md by default. Keep the shared content in AGENTS.md and reference it, or change the setting deliberately and document it.
• Bedrock, Vertex or Foundry users: keep a CLAUDE.md for now, or check the changelog for when support arrives.

Why instruction drift is a quality problem

This looks like housekeeping, but it affects output quality. When two agents on the same repository follow different instructions — one told to use the new logging library, one not — the codebase drifts in two directions at once, and reviewers catch the inconsistency late or not at all. Agents also retain nothing between sessions beyond what you give them, a point we covered in what persists between agent turns, so the instruction file is the only durable memory most of them have.

That makes the instruction file part of the codebase in every sense: versioned, reviewed and kept current. It is the same principle behind keeping agent knowledge in version control rather than in each tool's settings.

What to put in AGENTS.md

1. Commands. How to install, build, run tests, lint and type-check — exactly, as copy-pasteable lines.
2. Conventions that tools cannot infer. Which of two patterns in the codebase is the current one; which modules are deprecated; naming rules.
3. Boundaries. Directories agents must not edit, generated files, secrets handling, and actions that always need a human.
4. Definition of done. Which checks must pass before a change is ready, and what a good pull request description contains.
5. Pointers, not copies. Link to architecture docs rather than pasting them; long files dilute the instructions that matter.

Keep it short enough that a person will actually review changes to it. The file is instructions, not documentation.

AGENTS.md vs CLAUDE.md: mistakes to avoid

• Keeping a stale CLAUDE.md "just in case". An empty or outdated CLAUDE.md silently wins over a well-maintained AGENTS.md, so Claude Code follows the worse instructions.
• Copying content between files. Duplicates drift within weeks. If a tool needs its own file, keep only what is genuinely specific to it there.
• Assuming every environment behaves the same. A developer on the desktop app and a pipeline on Bedrock can currently read different files from the same repository.
• Writing it once. Instructions go out of date as the codebase changes. Review the file when conventions change, not when an agent gets something wrong.

How to move to one instruction file

1. Collect every agent instruction file in the repository and diff them. The differences are usually accidental.
2. Merge the shared content into AGENTS.md and resolve conflicts on purpose.
3. Remove or reduce tool-specific files, keeping only genuinely tool-specific settings.
4. Make changes to AGENTS.md go through code review like any other file.
5. Run the same small task with each agent and compare the results. If they diverge, the instructions are still ambiguous.

Consistent instructions also make automated review more reliable — part of why teams like Duolingo can auto-approve a share of pull requests. If your team runs several coding agents and the output does not look like one team wrote it, our AI engineering services team can help set up shared instructions, review rules and checks.