Flori
Log inGet started

Flori / Guides

CLAUDE.md and AGENTS.md: one set of instructions for every coding agent

By the Flori team · Published · Updated

Make AGENTS.md the one place for your project instructions. Codex, Cursor and Google’s Antigravity read it directly. Claude Code reads CLAUDE.md, and by default it reads AGENTS.md only when the project has no CLAUDE.md. So either let Claude Code read AGENTS.md on its own, or give it a one-line CLAUDE.md that imports it. Keep these files for instructions that rarely change, and keep the state of the work somewhere else.

Which file each tool reads

ToolReadsWatch out for
Claude CodeCLAUDE.md files: yours at ~/.claude/CLAUDE.md, the project’s at ./CLAUDE.md or ./.claude/CLAUDE.md, and a personal CLAUDE.local.md. It loads them from the current folder and every folder above it and combines them. Files in subfolders load when needed.From version 2.1.277 it reads AGENTS.md directly, by default only when the project has no CLAUDE.md or CLAUDE.local.md. To read both, set Project instructions to claude-md-and-agents-md in /config. It does not read AGENTS.override.md, AGENTS.local.md or a .agents/ folder.
CodexAGENTS.md: one in ~/.codex/ for your preferences, then up to one per folder from the project root down to the folder where you start Codex. Where AGENTS.override.md exists, it reads that instead.By default it reads up to 32 KiB of these files.
CursorAGENTS.md in the project root and in subfolders, plus project rules in .cursor/rules.Project rules must be .mdc files. “A plain .md file in .cursor/rules is ignored by the rules system.”
Antigravity (Google)AGENTS.md or GEMINI.md in the project and in any subfolder, plus global files such as ~/.gemini/AGENTS.md. No setting needed.It truncates any single rule file over 24,000 bytes. Google replaced its Gemini command-line tool with Antigravity’s for unpaid and Google One users on June 18, 2026.

Pick one of three setups

Anthropic documents several ways to use AGENTS.md with Claude Code. These three cover most projects.

  1. AGENTS.md only. If you have no Claude-specific instructions and everyone runs Claude Code 2.1.277 or later, skip CLAUDE.md. Claude Code then reads AGENTS.md as the project instructions.
  2. A one-line CLAUDE.md that imports AGENTS.md. Use this when you have notes that only apply to Claude Code, or when some sessions run an older version. The import works on every version.
  3. Both files, read together. Set Project instructions to claude-md-and-agents-md in Claude Code’s /config.

Whichever you pick, put the shared instructions in AGENTS.md at the project root:

# AGENTS.md

## Project
[One paragraph: what this is, who uses it, what matters most]

## Commands
- Install: [command]
- Test: [command]
- Lint and format: [command]
- Run locally: [command]

## Conventions
- [Language, framework and style rules a reviewer would enforce]
- [Where new code goes and how files are named]

## Boundaries
- Ask before: [deploys, migrations, deleting data, adding dependencies]
- Never: [commit secrets, edit generated files, push to the main branch]

## Definition of done
- [Tests that must pass, docs to update, how to ask for review]

## Session handoff
If HANDOFF.md exists, read it before starting work and update it before you stop.

For setup 2, create CLAUDE.md next to it:

@AGENTS.md

## Claude Code only
- [Anything that applies only to Claude Code, such as preferred subagents or commands]

Cursor and Antigravity pick up AGENTS.md without extra setup. If you also keep rules in .cursor/rules, make sure they are .mdc files. If you still use the Gemini command-line tool on a work or API-key account, add AGENTS.md to its context file names in .gemini/settings.json:

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

What belongs in the file, and what does not

Put in AGENTS.mdKeep out of it
Commands to install, test, lint and runThe status of today’s task
Conventions a reviewer would enforceDecisions that are still being discussed
Boundaries: what needs approval, what is never allowedPasswords, keys or customer data
What done means for a changeLong documentation; link to it instead
A pointer to the handoff fileThe handoff itself

Keep it short. Anthropic says CLAUDE.md files “over 200 lines consume more context and may reduce adherence.” Instructions that change every day are not instructions. They are project state, and they belong in a handoff file or a shared project record.

Mistakes that break it without warning

Get a first draft quickly

In Claude Code, /init drafts a CLAUDE.md, and if it finds existing Codex or Gemini configuration it offers to carry it over. Move the shared parts into AGENTS.md, and keep only the import line and Claude-only notes in CLAUDE.md. Then cut anything a reviewer would not enforce.

Frequently asked questions

Does Claude Code read AGENTS.md?

Yes, from version 2.1.277. By default it does so only when the project has no CLAUDE.md or CLAUDE.local.md. To keep a CLAUDE.md as well, import AGENTS.md from it with a line that reads @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config.

Do I still need a CLAUDE.md?

Only if you have instructions that apply to Claude Code alone, or if some sessions run a version older than 2.1.277. Otherwise AGENTS.md on its own works.

Where do my personal preferences go?

In your user-level file: ~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex, Customize → Rules for Cursor, and ~/.gemini/AGENTS.md or ~/.gemini/GEMINI.md for Antigravity.

Can AGENTS.md tell the agent what to work on next?

It can point to where that lives. Put “read HANDOFF.md first” in AGENTS.md, and keep the next step in the handoff file or your task list, where it can change daily without touching the instructions.

Sources

Checked October 19, 2026. Vendors change these pages often, so check the source before you rely on a plan detail.

Keep exploring

Start your workspace