If you use more than one coding agent on the same project, you have probably noticed you are writing the same context repeatedly. Claude Code reads CLAUDE.md. Codex CLI reads AGENTS.md. Gemini CLI reads GEMINI.md. Same project, same conventions, three files.

How we got here

Each tool shipped its own convention before anyone agreed on one, which is the usual way of things. The interesting development is AGENTS.md: released by OpenAI in August 2025, then transferred to the Linux Foundation's Agentic AI Foundation in late 2025, alongside Anthropic's Model Context Protocol and Block's Goose.

It has real traction. By May 2026 the foundation counted more than 170 member organisations, and AGENTS.md had been adopted across more than 60,000 open-source repositories, with contributions from the teams behind Codex, Amp, Jules, Cursor and Factory.

The wrinkle: as of April 2026, Claude Code still reads CLAUDE.md and does not natively pick up AGENTS.md. So the standard exists, and the most popular agent is not yet using it.

The pragmatic fix today

Write the real content once, and make the other files point at it.

# AGENTS.md is the source of truth
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

Symlinks work because every tool just reads a file at a path. Commit them and git preserves the link. The cost is that you lose the ability to say something to only one agent — usually a fine trade.

If you do need per-tool notes, keep a thin file per tool that carries only the differences, and have the shared body live in something like docs/context.md that each one references.

What actually belongs in these files

The common failure is writing a README for humans. An agent has already read your code; it does not need the tour. What it cannot infer is:

  • Commands. How to run tests, the formatter, the build. Exact invocations.
  • Conventions with teeth. "Never use multi-column grids in this admin panel" is useful. "Write clean code" is not.
  • Traps. The migration that must not be re-run. The service that deletes things. The config that looks unused and is not.
  • Decisions already made. So the agent stops re-proposing an approach you rejected months ago.

Keep it short. A 400-line instruction file competes with the actual code for the model's attention.

The part nobody has solved

Instruction files are the easy half. The hard half is session context — what the agent has already tried, what failed, what it learned in the last two hours. That lives in each tool's own history format, and switching agents mid-task means throwing it away.

Nobody has a good answer to this yet, including us. It is the most interesting unsolved problem in multi-agent workflows, and worth watching.

A small habit that helps

When an agent works something out that took effort — an obscure build flag, a subtle ordering requirement — have it append the finding to the shared instruction file before you close the session. Otherwise that knowledge dies with the conversation, and the next agent, or the next you, rediscovers it from scratch.