Claude Code finally supports AGENTS.md, and quietly fixes a much more expensive problem, Simon Dixon

I shared the quick version of this in today’s video. This is the bit that deserves more than sixty seconds.

Anthropic has finally taught Claude Code a filename the rest of the coding-agent world already knows: AGENTS.md.

That sounds like a tiny compatibility change. And, to be fair, part of it is. Maintaining two copies of the same Markdown file is hardly the greatest hardship facing humanity.

But if you use several coding agents on the same project - especially if you get one agent to review another agent’s work - this removes a surprisingly irritating source of drift.

Anthropic also added a second feature that I care about even more: custom subagents can now skip all that project context when they do not need it.

That one will let me delete a hack, stop setting fire to tokens and generally live a slightly happier life.

Let me explain.

What are CLAUDE.md and AGENTS.md?

Coding agents need more than your latest prompt.

They need to know things like:

how the project is structured
which libraries and patterns you use
how to run the tests
what they should never change
the strange but important reason one particular folder must not be “cleaned up”

Claude Code traditionally gets those instructions from CLAUDE.md.

A project file might contain rules such as:

# Project instructions

- Use TypeScript in strict mode.
- Run the relevant tests before declaring a task complete.
- Do not introduce a second component library.
- Database migrations must be backwards-compatible.

You can also place more specific instruction files deeper in a project.

A frontend file might describe the design system, accessibility rules and component patterns.

A database file might explain the ORM, migration process and SQL conventions used by the team.

When the agent works in one of those areas, it can load the local instructions alongside the broader project rules.

It is a genuinely useful system. You just need to keep the files lean because instruction files are context, and context is not free.

One repository, three slightly different rulebooks

Here is what this looks like in a real project:

~/.codex/AGENTS.md Codex personal defaults
~/.gemini/GEMINI.md Gemini personal defaults
~/.claude/CLAUDE.md Claude personal defaults

inkie/
├── AGENTS.md Shared repository rules
├── CLAUDE.md Optional Claude-only layer
├── apps/
│ └── web/
│ ├── AGENTS.md Rules for the web application
│ ├── CLAUDE.md Optional Claude-specific web rules
│ └── src/
│ └── route.ts ← The file being worked on
└── services/
 └── api/
 └── AGENTS.override.md Codex-only override, if genuinely needed

Imagine the agent is working on apps/web/src/route.ts.

The relevant instructions sit above that file: personal defaults, repository-wide rules and the more specific rules for the web application.

The important wrinkle is that each coding harness walks that tree differently.

Codex

Codex starts with ~/.codex/AGENTS.md, then works down from the repository root towards the active directory.

For our example, that gives it:

~/.codex/AGENTS.md
 ↓
inkie/AGENTS.md
 ↓
inkie/apps/web/AGENTS.md
 ↓
inkie/apps/web/src/route.ts

Instructions closer to the active directory take precedence when they conflict with broader rules.

Within each directory, AGENTS.override.md wins over AGENTS.md. That is useful for a genuine exception, although scattering emergency overrides around a repository is also an excellent way to create a treasure hunt for your future self.

Gemini

Gemini CLI uses GEMINI.md by default. It can load a global file and discover additional context files through the workspace and its ancestor directories.

If you want Gemini to join the AGENTS.md party, you must configure that filename explicitly:

{
 "context": {
 "fileName": ["AGENTS.md", "GEMINI.md"]
 }
}

Without that configuration, dropping an AGENTS.md into the repository does not magically make Gemini read it.

Claude

Claude has personal and managed instructions outside the repository, while project CLAUDE.md files are discovered through the directory hierarchy.

Files above the working directory load at startup. More specific files become relevant when Claude starts reading files inside their subtree.

Its new AGENTS.md support has two distinct modes:

claude-md-or-agents-md

This is the default. Claude reads CLAUDE.md when one exists and falls back to AGENTS.md when it does not.

claude-md-and-agents-md

This explicitly tells Claude to read both.

The ancestor-file trap

There is one slightly sharp edge hiding in that default mode:

root/
├── CLAUDE.md ← selected by the default mode
└── somefolder/
 ├── AGENTS.md ← not loaded
 └── task.ts ← active file

Even though Claude is working inside somefolder, the root CLAUDE.md means it does not directly load the nested AGENTS.md in the default claude-md-or-agents-md mode.

To make both files apply, select claude-md-and-agents-md.

Alternatively, move the shared instructions into AGENTS.md and remove the root CLAUDE.md if you no longer need a Claude-specific layer.

This is exactly the sort of behaviour that looks obvious once somebody explains it and mildly haunted until they do.

So the larger diagram is not showing one universal inheritance system with three different logos stuck on it. The files may look similar, but each harness has its own discovery rules.

If you use several of them, standardising the shared content is only half the job. You also need to configure each tool so it actually reads the files you have standardised on.

The problem: Claude had its own special filename

Most of the coding-agent world has settled around AGENTS.md as the shared version of this idea.

Claude Code, meanwhile, used CLAUDE.md.

This becomes annoying when a project is worked on by more than one harness.

That is nearly every serious project I work on.

I will often use Claude Code to build something, then ask Codex or Gemini to review the result. They notice different things. An agent reviewing its own work can have the same blind spots as the agent that wrote it. Giving the code to a different model is a cheap way to get another perspective.

I do the reverse as well. If Codex writes something, I might ask Claude to review it.

The reviewer still needs to understand the project rules. There is not much value in a second opinion if the second agent has not been told what “correct” means for that repository.

Until now, that often meant maintaining something like this:

my-project/
├── CLAUDE.md
├── AGENTS.md
└── ...

Sometimes the files were identical. Sometimes one imported or pointed towards the other. Sometimes they started identical and quietly drifted apart until two agents had been given different versions of reality.

The code was shared.

The rulebook was forked.

Lovely.

What Claude Code supports now

From Claude Code 2.1.277, Claude can read AGENTS.md directly as project instructions.

There is one important detail hiding behind the headline: Claude does not automatically combine CLAUDE.md and AGENTS.md by default.

Its default behaviour is:

if it finds CLAUDE.md, it reads that
if it does not find CLAUDE.md, it looks for AGENTS.md
if both exist, CLAUDE.md wins

You can change this under Project instructions in /config.

Claude currently offers four modes:

Mode	Behaviour
`claude-md-or-agents-md`	Read `CLAUDE.md`, falling back to `AGENTS.md` when it is absent
`claude-md-and-agents-md`	Read both files
`claude-md`	Only read Claude’s native instruction files
`managed-only`	Only read centrally managed organisation instructions

If both files genuinely contain useful, separate instructions, claude-md-and-agents-md is the mode you want.

If the same shared rules should apply to every coding agent, you can put those rules in AGENTS.md and stop maintaining a duplicate CLAUDE.md.

That is the route I expect most multi-agent projects to take.

If you are migrating an existing repository, check what Claude has actually loaded rather than assuming the filenames did what you meant. As the ancestor-file trap shows, a parent CLAUDE.md can change what happens to an AGENTS.md further down the tree.

The direct support is not available in every hosted environment yet either. Anthropic’s release notes currently exclude Bedrock, Vertex and Foundry.

Still, for the normal Claude Code setup, this is a very welcome bit of housekeeping.

The more interesting change: `omitClaudeMd`

The second change solves a problem that has cost me considerably more than a duplicated Markdown file.

Claude Code can launch subagents for smaller pieces of work.

A main agent might delegate jobs such as:

searching the repository
classifying a log entry
finding references to an API
checking a migration
reviewing one small piece of a larger change

These agents often have deliberately narrow jobs.

Historically, though, custom subagents also inherited the project’s CLAUDE.md context.

That sounds sensible until your main agent has a lot of context.

My agents have a bit of a soul

The main agents inside the Inkie platform are long-running specialists.

They have an identity, a role, useful background and context about the work they do. Calling this a “soul” is possibly a little dramatic, but it is weekend-level accurate.

That context is useful for the main agent.

It is not useful for a tiny subagent whose entire job is something like:

Classify this result and return one of three labels.

But every time I spawned one of those narrow agents, it could receive the same large project instruction file.

The classifier did not need the agent’s life story.

The search worker did not need its personality.

The small reviewer did not need months of accumulated lore about how the wider system worked.

They were being handed a novel before being asked to check the spelling of one word.

Multiply that across lots of small subagent calls and the wasted context adds up rather quickly.

The workaround I was using

I fixed this months ago, but the fix was not pretty.

Instead of linking all the rich context directly from CLAUDE.md, I used a session-start hook to tell the main agent who it was and which additional files it needed to load.

The main conversation received the identity and long-term context.

The small subagents did not.

It worked, but it was an implementation trick built around the way Claude Code happened to load context. Those are the sorts of tricks that make you feel clever on Tuesday and slightly nervous three months later.

Now Claude Code has a proper switch for it.

A custom subagent can include this in its definition:

---
description: Classifies log entries into a small set of known categories
tools: Read, Grep
omitClaudeMd: true
---

That one line tells Claude Code not to load the usual user, project and local instruction files into that subagent.

Despite the name, it also skips AGENTS.md files that were loaded as project instructions.

Centrally managed organisation policy still applies, which is exactly what you would want. A project should not be able to make a worker conveniently forget the company’s safety rules.

The built-in Explore and Plan agents already skip project instructions. This option gives the same sort of control to narrow custom agents you define yourself.

omitClaudeMd requires Claude Code 2.1.271 or newer.

Do not switch it on everywhere

This is not a “make subagents cheaper” button that should be added to every agent file.

Some subagents absolutely need the project instructions.

A code reviewer may need to know your architecture rules.

A migration agent needs the database conventions.

A UI agent needs to know which component library it is allowed to use, unless you enjoy discovering that it has installed three more.

Use omitClaudeMd when the delegation prompt contains everything the subagent needs to do its narrow job correctly.

If the agent needs one or two rules from the wider project context, put those rules directly in its instructions or delegation prompt.

The question is not:

Can I save some tokens here?

It is:

Can this agent complete its task correctly without the project rulebook?

If the answer is yes, leave the rulebook behind.

What I am changing

My projects use more than one coding harness, so I am going to treat the instructions as two layers.

Shared project rules will live in AGENTS.md.