AGENTS.md: One Context File for Every Coding Agent (Codex, Gemini, Claude)

You spent an afternoon writing a clean CLAUDE.md. Your agent finally stopped guessing your stack and started running the right test command. Then a teammate opens the same repo with Codex, you try Gemini CLI on a side branch, and none of that hard-won context carries over. Each tool wants its own file, in its own place.

AGENTS.md is the answer to that mess: one plain-Markdown file, at the root of your repo, that any coding agent reads before it touches your code.

What AGENTS.md actually is

No magic. It is a Markdown file named AGENTS.md, usually at the repository root, that an agent loads as standing instructions before it starts working. Think of it as the README you write for your AI teammates instead of your human ones: what the project is, how to build and test it, the conventions to respect, and the traps to avoid.

It is an open convention, already read by Codex and a growing list of agent tools, with the explicit goal of being portable across them. One file, many agents, instead of one bespoke file per tool.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Right now the landscape is split by tool:

• CLAUDE.md is what Claude Code looks for.
• GEMINI.md is Gemini CLI's convention.
• AGENTS.md is the cross-tool standard, read by Codex and others, designed to be the neutral one.

The content is almost identical in all three: project context, commands, conventions. The only real difference is the filename each tool reads by default. That is exactly why duplicating the same rules into three files by hand is a losing game (more on keeping them in sync below).

If you work mostly in Claude Code, our CLAUDE.md guide goes deep on the Claude-specific structure. AGENTS.md is the provider-neutral sibling of that file.

What to put in it

Keep it short and high-signal. An agent reads this on every task, so every line competes for attention. The essentials:

• The stack, in one breath. "Next.js 16, TypeScript, Prisma, MariaDB." No history, no marketing.
• Commands that matter. How to install, run, build, test and lint. Exact commands: npm test, not "run the tests."
• Conventions. Naming, file layout, error handling, the patterns you actually enforce in review.
• A directory map. Two lines on where things live, so the agent stops grepping blindly.
• Read-before-touch rules. "Read docs/payments.md before editing anything under billing/." This single habit prevents a lot of damage.
• Hard don'ts. "Never create a branch without being asked." "No absolute machine paths in committed files."

The mistakes that make agents ignore it

A context file fails quietly. The agent does not throw an error, it just drifts. The usual causes:

1. Too long. A 600-line file buries the five rules that matter. Cut anything the agent can infer from the code itself.
2. Contradictions. "Always write tests" in one section, "skip tests for prototypes" in another. The agent picks one at random.
3. Machine-specific paths. /Users/you/project/... in a committed file breaks for every teammate, and for every agent on every other machine. Keep paths relative.
4. Stale commands. The test command changed six months ago, the file did not. Now the agent runs the wrong thing with full confidence.
5. No priorities. Everything is "important," so nothing is. Put the non-negotiables first and label them.
6. Documentation dumping. This is instructions, not a wiki. Link out to your docs, do not paste them in.

Keeping one context across providers

Here is the practical part most guides skip. If you, or your team, run more than one agent CLI, you do not want three drifting copies of the same rules.

Two clean approaches:

• One canonical file, thin pointers. Keep everything in AGENTS.md and make CLAUDE.md and GEMINI.md one-line files that say "see AGENTS.md," or symlink them. One source of truth, every tool fed.
• One file, shared by convention. If your tools can be pointed at a custom path, aim them all at AGENTS.md and delete the rest.

Either way the rule is the same: write the context once, not once per provider. That is also the only way it stays correct, because a single file is the only file people actually maintain.

When you run several agents at once

A repo-level AGENTS.md answers "what is this project." It does not answer "who is this agent." When you run a Backend agent, a Frontend agent and a QA agent in parallel on the same code, each one needs the shared project context plus its own role.

That is the layer AgentsRoom adds on top of your AGENTS.md. Each agent gets a dedicated role with its own system prompt (DevOps, Frontend, Security and more), so the shared file stays lean while each agent still knows its job. It is provider-agnostic by design, so the same setup runs Claude, Codex or Gemini side by side, and your repeatable instructions live in a Prompt Library instead of being retyped into every session.

When you reach that point, the method for running several agents in parallel without losing track is the natural next read.

The takeaway

Write one AGENTS.md. Keep it short, keep it current, keep it portable. Point every tool at it instead of maintaining a file per agent. Your context stops being tied to whichever CLI you happened to start with, and your agents, whichever ones you run, start from the same page.

Want every agent on one screen, each with its own role and your shared context? Download AgentsRoom, connect your provider, and put your fleet to work.