Claude Code Now Reads AGENTS.md. Here's Why That Actually Matters.

Published 2026-09-19

Claude Code just started reading AGENTS.md as a fallback when a project has no CLAUDE.md. One line in a changelog. Small change on paper. I run Claude Code across several active projects at once, every one of them with its own CLAUDE.md holding real, current instructions. This change means a file that used to be inert in my setup can now, under the right conditions, actually get read and acted on. Worth taking seriously, not skimming past.

What Changed

Claude Code now checks for AGENTS.md when CLAUDE.md is missing, and uses it instead. Before this, a project without a CLAUDE.md just had no project-level instructions at all.

This is not Claude Code inventing a new convention. AGENTS.md is a format other AI coding tools already use for the same purpose, project-specific instructions read at the start of a session.

Claude Code reading it too is a step toward one shared convention, instead of every tool wanting its own file.

Why This Matters If You Run More Than One Tool

Most people using Claude Code seriously are not using only Claude Code. Codex, ChatGPT, and other agent tooling all have their own take on a project instructions file.

Some projects end up with more than one of these files sitting in the repo root at the same time.

Until now, that was mostly harmless for Claude Code specifically. If a project had an AGENTS.md left over from a different tool's setup, Claude Code simply ignored it.

That's changed. An AGENTS.md that was never meant for Claude Code can now become the thing Claude Code actually reads, the moment CLAUDE.md is absent.

The Real Failure Mode

The dangerous case is a project with a real, current CLAUDE.md sitting next to a stale AGENTS.md that predates it, left behind from an earlier scaffold or a different tool's setup and never deleted. A project with no instruction files at all is the easy case, nothing to get confused about there.

Before this change, that stale file was dead weight. CLAUDE.md was read, AGENTS.md was not, so an outdated file just sat there doing nothing. I have one project where a leftover AGENTS.md from an old starter template describes a generic architecture the project no longer uses at all.

That file only stayed harmless because nothing read it. This change is exactly the kind of shift that turns dead weight into a real liability, in some future project, on some session where CLAUDE.md briefly does not exist yet or gets misnamed.

A session picking up the wrong file would confidently work from architecture that has not been true for months.

How I Handle This In My Own Projects

My fix is simple, just consistently applied. Every project gets exactly one canonical instructions file, and if a legacy file exists alongside it for any reason, that legacy file gets an explicit note at the top saying it is outdated and should not be trusted.

That note matters more now than it did last week. Before, a stale file being wrong didn't cost anything, since nothing read it. Now, on the right conditions, something will.

I also check what instruction files actually exist in a project at the start of a new phase of work, not just once at setup. Projects grow, templates get copied in, old scaffolding lingers.

A five-minute check beats debugging a session that confidently worked from year-old assumptions. It's the same discipline that matters in running a scheduled agent reliably: the failure that costs you is the one that looks like success from the outside.

This is the same instinct behind building a multi-agent pipeline on Claude and the Gmail API: each piece working on its own says nothing about whether the whole system can be trusted.

A config file convention is a small piece. It is exactly the kind of small piece that quietly decides whether an agent is working from the truth.

What To Check Before You Trust Either File

If you run Claude Code across multiple projects, the practical move is a quick audit, not a rewrite. Look for any project that has both a CLAUDE.md and an AGENTS.md sitting in the same root.

Where both exist, decide which one is actually current and either delete the other or mark it clearly as legacy. Where only an AGENTS.md exists from a different tool's setup, check whether its contents are still accurate before assuming Claude Code reading it now is neutral.

Tool convergence on instruction files is a genuinely good direction. It means less duplicated setup per tool, and eventually, one file that works everywhere. But convergence also means a leftover file from an old setup stops being invisible and starts being live. Worth an audit before that surprises you mid-session.