AGENTS.md: one instructions file for every coding agent

Short answer: AGENTS.md is a plain Markdown file at the root of your repository that tells coding agents how to work in it: how to build, test, and what not to touch. Codex, Cursor and OpenCode read it on their own. Claude Code reads it only when there is no CLAUDE.md, so add a line @AGENTS.md to your CLAUDE.md. Gemini CLI needs one setting. Do that, and one file covers your whole team.

What AGENTS.md is

AGENTS.md is an open format for giving instructions to AI coding agents. Think of it as a README for agents. It started at OpenAI, where Codex originated it, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The site says more than 60,000 open source projects use it.

There is no schema. It's ordinary Markdown, and agents read it as context at the start of a session. Codex also reads AGENTS.md files in subfolders, from the repo root down, and supports an AGENTS.override.md (Codex docs).

An example AGENTS.md

Keep it short and specific. Agents follow concrete commands better than general advice.

# AGENTS.md

## Setup
- Node 22, pnpm. Install with `pnpm install`.
- Copy .env.example to .env.local before running anything.

## Commands
- Dev server: `pnpm dev` (port 3000)
- Type check: `pnpm tsc --noEmit`
- Tests: `pnpm test` (run before you say you're done)

## Code style
- TypeScript strict. No `any`.
- Server code lives in src/server. UI in src/components.

## Rules
- Never edit files in src/generated; run `pnpm codegen` instead.
- Never push or deploy. Open a branch and stop.
- Database changes go in a new migration file, never edit old ones.

Which tools read AGENTS.md

Tool	Reads AGENTS.md?	Its own file	What to do
Codex	Yes, natively	AGENTS.md (plus AGENTS.override.md)	Nothing
Cursor	Yes, at the root and in subfolders	.cursor/rules/*.mdc	Nothing
OpenCode	Yes, first choice	Falls back to CLAUDE.md	Nothing
Claude Code	Since v2.1.277, but only when there is no CLAUDE.md	CLAUDE.md	Put @AGENTS.md in CLAUDE.md
Gemini CLI	Only if configured	GEMINI.md	Set context.fileName

Sources: Cursor rules, OpenCode rules, Claude Code memory, Gemini CLI. The agents.md site also lists Jules, Aider, Zed, Warp, VS Code and the GitHub Copilot coding agent, Devin, Amp, Windsurf, Kilo Code and RooCode.

The Claude Code catch

This is the one that trips teams up. If your repository has a CLAUDE.md, Claude Code loads only CLAUDE.md and ignores AGENTS.md. The fix is a one-line import. CLAUDE.md:

@AGENTS.md

## Claude Code only
- Use subagents for codebase searches.

The @ line pulls AGENTS.md into Claude's context, and anything below it applies to Claude only.

The Gemini CLI setting

Gemini CLI reads GEMINI.md by default. Point it at AGENTS.md in .gemini/settings.json:

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

A setup for a mixed team

If one person uses Claude Code, another Cursor and a third Codex, this keeps everyone's agent on the same rules:

1. AGENTS.md is the source of truth. All shared rules, commands and conventions go there.
2. CLAUDE.md is a pointer. It starts with @AGENTS.md and adds only Claude-specific notes.
3. Gemini settings point at AGENTS.md, checked into the repo.
4. Cursor rules stay small. Use .cursor/rules only for things that are truly Cursor-only.
5. Review changes to AGENTS.md like code. It changes how every agent on the team behaves.

Coagy's own repository works this way: its CLAUDE.md just says to read AGENTS.md.

What AGENTS.md doesn't cover

AGENTS.md holds the rules you write down ahead of time. It doesn't hold what the agents learn while they work: why a decision was made last Tuesday, which approach already failed, what your teammate's agent is changing right now.

That's the part Coagy adds for teams. It shows every developer's Claude Code, Codex, Gemini CLI and Cursor sessions in one workspace, and keeps a shared project memory that every agent can search. Free for up to 4 developers. More on this in how to make Claude Code remember between sessions and how to share Claude Code context with your team.

Questions

What is AGENTS.md?

AGENTS.md is a Markdown file in your repository that gives AI coding agents instructions, such as build and test commands, code style and rules. It is an open format that started at OpenAI and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

Does Claude Code read AGENTS.md?

Since version 2.1.277, Claude Code reads AGENTS.md, but only when the repository has no CLAUDE.md. If you have a CLAUDE.md, add the line @AGENTS.md to it so Claude Code imports AGENTS.md.

Does Gemini CLI support AGENTS.md?

Only if you configure it. Gemini CLI reads GEMINI.md by default. Set context.fileName to include AGENTS.md in its settings.json, for example ["AGENTS.md", "GEMINI.md"].

Should I use AGENTS.md or CLAUDE.md?

If anyone on your team uses a tool other than Claude Code, keep shared rules in AGENTS.md and make CLAUDE.md import it with @AGENTS.md, adding only Claude-specific notes below. Codex, Cursor and OpenCode read AGENTS.md directly.

Does Cursor read AGENTS.md?

Yes. Cursor reads AGENTS.md at the repository root and in subfolders, alongside its own .cursor/rules files and team rules.