AGENTS.md vs CLAUDE.md vs GEMINI.md: The Complete 2026 Comparison of AI Coding Config Files

Three files now compete for the same job: telling an AI coding agent how to work in your repository. AGENTS.md is the open standard. CLAUDE.md is Anthropic’s native format for Claude Code. GEMINI.md is Google’s own convention for Gemini CLI — and it is easy to get wrong, because a lot of published content assumes Gemini CLI reads AGENTS.md out of the box. It does not, unless you configure it to.

This guide compares all three formats on file name, syntax, scope, and hierarchy, verified against the official Anthropic docs, the agents.md spec, and the official Gemini CLI documentation. It also maps which of the major AI coding tools — Claude Code, Codex CLI, Cursor, Gemini CLI, and Windsurf — read which file, so you can configure a repository once and have it work everywhere.

Quick Definitions

• AGENTS.md is an open, tool-agnostic Markdown file that any AI coding agent can read for project instructions, with no required schema or frontmatter.
• CLAUDE.md is Anthropic’s native configuration file for Claude Code, supporting hierarchical scopes, an @import syntax, and path-scoped rules.
• GEMINI.md is Gemini CLI’s default context file, loaded from a global, project, and component-level hierarchy and concatenated into the model’s context on every prompt.

The Three-Way Comparison Table

AGENTS.md: The Open Standard

AGENTS.md has no owner in the traditional sense. It is stewarded by the Agentic AI Foundation under the Linux Foundation, and it started as a shared convention among Sourcegraph, OpenAI, Google, Cursor, and Factory. The pitch is simple: write one file, and every compliant tool reads it the same way.

# AGENTS.md

## Project Overview
Python FastAPI backend with a Postgres database, deployed on Fly.io.

## Coding Standards
- Type hints on all function signatures
- Pydantic models for request/response validation
- Ruff for linting, Black for formatting

## Commands
- Install: uv sync
- Test: uv run pytest
- Run locally: uv run fastapi dev

## Boundaries
- Never edit files under alembic/versions/ directly
- Do not commit .env or any file containing credentials

There is no frontmatter, no required sections, and no tool-specific syntax. That simplicity is the entire value proposition — over 60,000 GitHub repositories use it specifically because it does not lock them into one vendor’s tooling.

CLAUDE.md: Claude Code’s Native Format

Claude Code does not read AGENTS.md. This is explicit in Anthropic’s own documentation: “Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it.”

The recommended pattern is a one-line import:

# CLAUDE.md

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude Code walks up the directory tree from the working directory, loading CLAUDE.md and CLAUDE.local.md at each level in full at launch, then discovers nested CLAUDE.md files in subdirectories and loads them on demand when Claude reads files there. Imports can recurse up to four hops deep. A CLAUDE.local.md at the project root is meant to stay out of version control — add it to .gitignore for sandbox URLs, personal test data, or anything you don’t want your team to see.

For larger projects, .claude/rules/*.md files with paths: frontmatter scope instructions to specific globs, so a rule about src/api/**/*.ts only loads into context when Claude is actually touching those files:

---
paths:
  - "src/api/**/*.ts"
---

# API Rules

- All handlers must validate input with Zod
- Return errors using the shared ApiError class

GEMINI.md: Gemini CLI’s Own Convention (Not AGENTS.md by Default)

This is the part most comparisons get wrong. Gemini CLI’s own documentation states: “Context files, which use the default name GEMINI.md, are a powerful feature for providing instructional context to the Gemini model.” Out of the box, Gemini CLI looks for GEMINI.md, not AGENTS.md.

Gemini CLI’s hierarchy is closer in spirit to CLAUDE.md’s layered model than to AGENTS.md’s flat convention, but the mechanics differ. Instead of a strict override order, Gemini CLI concatenates every file it finds across three levels and sends the combined content with every prompt:

1. Global: ~/.gemini/GEMINI.md — instructions that apply across all your projects.
2. Project: GEMINI.md in the current working directory and each parent directory, up to the project root identified by a .git folder.
3. Component: GEMINI.md files in subdirectories below the working directory, respecting .gitignore and .geminiignore.

Like CLAUDE.md, GEMINI.md supports splitting large files into smaller pieces with an import syntax:

# GEMINI.md

@docs/architecture.md
@docs/testing-guide.md

## Project Conventions
- Feature flags live in config/flags.yaml
- All new endpoints require an OpenAPI spec update

Run /memory show inside Gemini CLI to inspect exactly which files were loaded and in what order, and /memory reload to refresh after an edit. The CLI’s footer displays a live count of loaded context files, which is a useful sanity check in monorepos with many nested GEMINI.md files.

Can Gemini CLI read AGENTS.md instead? Yes, but only after you configure it. The context.fileName setting in settings.json accepts an array of filenames to search for, in priority order:

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

With that setting in place, Gemini CLI will look for AGENTS.md first at every level of the hierarchy, falling back to CONTEXT.md and then GEMINI.md. Without it, Gemini CLI never looks for AGENTS.md — a distinction that matters if you are trying to run a single shared config file across Claude Code, Gemini CLI, and everything else without maintaining duplicates.

Tool Support Matrix

The practical takeaway: AGENTS.md is genuinely universal only for Codex, Cursor, and Windsurf out of the box. Claude Code and Gemini CLI both require a one-time setup step — an import for Claude Code, a settings change for Gemini CLI — before they will treat AGENTS.md as their source of truth.

Where the Three Diverge

Default multi-tool compatibility. AGENTS.md wins here by design — it is the only one of the three built to be read by unrelated tools without configuration.

Depth of the hierarchy. CLAUDE.md has the most granular scope model: managed policy, user, project, and local, plus path-scoped rules that load conditionally based on which files Claude is editing. GEMINI.md’s three-level hierarchy is broader but flatter — it concatenates everything rather than layering it with different precedence rules, and it has no equivalent to path-scoped rules or a gitignored local-override file.

Import mechanics. CLAUDE.md and GEMINI.md both support @file imports for breaking large files into components. AGENTS.md has no import syntax at all — if you want modular AGENTS.md content, your only option is nested per-directory files, not includes within a single file.

Governance and stability. AGENTS.md’s spec is maintained by a neutral foundation, which is exactly why tool vendors have been comfortable building support for it. CLAUDE.md and GEMINI.md are each controlled by a single vendor, and their feature sets can change between minor releases — the max import depth for CLAUDE.md, for example, is documented at four hops as of mid-2026 and has been adjusted before.

Recommended Setup: One Shared File, Two Thin Wrappers

For a repository that needs to work well across Claude Code, Gemini CLI, and any AGENTS.md-native tool:

repo/
  AGENTS.md              ← shared standards: style, commands, structure, boundaries
  CLAUDE.md               ← @AGENTS.md, then Claude-specific config
  GEMINI.md                ← @AGENTS.md, then Gemini-specific config
  .gemini/
    settings.json          ← optional: add "AGENTS.md" to context.fileName

CLAUDE.md:

@AGENTS.md

## Claude Code
Use plan mode before touching src/billing/.

GEMINI.md:

@AGENTS.md

## Gemini CLI
Prefer the built-in web-search tool over shell curl calls.

This keeps the bulk of your instructions in one file, avoids duplication, and gives each tool the specific behaviors only it understands.

FAQ

What is the difference between AGENTS.md and GEMINI.md? AGENTS.md is an open, multi-tool standard read natively by Codex CLI, Cursor, and Windsurf, among others. GEMINI.md is Gemini CLI’s own default context file — Gemini CLI does not read AGENTS.md unless you add it to the context.fileName array in settings.json. Both support nesting, but GEMINI.md also supports a global, user-level file at ~/.gemini/GEMINI.md that AGENTS.md has no equivalent for.

What is the difference between CLAUDE.md and GEMINI.md? Both are vendor-specific context files with hierarchical loading and @file imports, but the hierarchies differ. CLAUDE.md has four distinct scopes with clear precedence (managed, user, project, local) plus path-scoped rules. GEMINI.md has three scopes (global, project, component) that are concatenated rather than layered with override precedence, and it has no direct equivalent to CLAUDE.md’s paths:-scoped rules or gitignored local-override file.

Does Gemini CLI read AGENTS.md automatically? No. Gemini CLI’s default context filename is GEMINI.md. To have it also or instead search for AGENTS.md, add "context": {"fileName": ["AGENTS.md", "GEMINI.md"]} to settings.json. Without that change, an AGENTS.md file in your repo is invisible to Gemini CLI.

Does Claude Code read AGENTS.md automatically? No. Anthropic’s documentation states plainly that Claude Code reads CLAUDE.md, not AGENTS.md. The supported pattern is either an @AGENTS.md import at the top of CLAUDE.md, or a symlink (ln -s AGENTS.md CLAUDE.md) on platforms that support it without elevated privileges.

Can I use the same file for all three tools? Not directly, since each tool looks for a different filename by default. The practical workaround is to keep your actual standards in AGENTS.md, then create a one-line CLAUDE.md and GEMINI.md that each import it with @AGENTS.md, adding only tool-specific sections below the import.

Which file supports path-scoped or conditional rules? Only CLAUDE.md, via the .claude/rules/ directory and YAML paths: frontmatter. Neither AGENTS.md nor GEMINI.md has a native mechanism to load instructions conditionally based on which files are being edited — GEMINI.md’s component-level files come closest, since a GEMINI.md in a subdirectory only contributes to context when Gemini CLI is working in that subtree.

Where do I put global, user-level preferences for each tool? CLAUDE.md: ~/.claude/CLAUDE.md. GEMINI.md: ~/.gemini/GEMINI.md. AGENTS.md has no user-level equivalent — it is designed to be a project file, committed and shared, not a personal configuration layer.

Keep Secrets Out of Your Config Files

AGENTS.md, CLAUDE.md, and GEMINI.md all get committed to version control, and all three end up describing real infrastructure — API base URLs, service names, sometimes example commands that reference environment variables. It’s a short step from there to someone pasting an actual key into a “Commands” section to make an example work. 1Password’s CLI (op run) injects secrets into a process at runtime instead, so your config files can reference op:// vault paths without ever holding a live credential, and every access gets logged.