AGENTS.md vs CLAUDE.md: Which AI Coding Tools Read Which Instruction File

If you use more than one AI coding tool, you have probably met several instruction files: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules, .kiro/steering, .github/copilot-instructions.md. Many tools now read AGENTS.md, which makes it tempting to write one file and delete the rest. That mostly works, but each tool reads it under different conditions, and some only do so with the right version or configuration.

This guide summarizes what each tool's official documentation says, links every source with the date we checked it, and suggests a pattern for sharing one file across tools. Support depends on tool, version, surface and configuration, and vendor docs change often, so treat the table as a starting point and recheck the linked pages for the version you run.

What AGENTS.md is

The AGENTS.md site (checked 2026-11-05) describes it as "a simple, open format for guiding coding agents" and "a README for agents." It is plain Markdown with no required structure or frontmatter. The site says the format "is now stewarded by the Agentic AI Foundation under the Linux Foundation," and suggests sections such as a project overview, build and test commands, code style, testing instructions and security considerations.

For nested files the site's guidance is that "the closest AGENTS.md to the edited file wins." Individual tools do not all implement nesting the same way, as the table below shows.

Which tools read AGENTS.md

Tool	Reads AGENTS.md?	Conditions and notes	Tool-specific files	Source (checked 2026-11-05)
Cursor	Yes	Project root and subdirectories; nested files combine with parents, more specific instructions take precedence. Plain Markdown, no metadata.	.cursor/rules/*.mdc with description, globs, alwaysApply	cursor.com/docs/rules
Claude Code	Yes, conditionally	By default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. Requires v2.1.277 or later. Setting Project instructions to claude-md-and-agents-md loads both.	CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md, ~/.claude/CLAUDE.md	code.claude.com/docs/en/memory
Gemini CLI	Only if configured	Default context file is GEMINI.md. Add AGENTS.md to context.fileName in settings.json to load it.	GEMINI.md (global, workspace and parents, just-in-time subfolders)	geminicli.com/docs/cli/gemini-md
Kiro	Yes	Workspace root, global ~/.kiro/steering/, and subdirectories. "AGENTS.md files do not support inclusion modes and are always included."	.kiro/steering/*.md with inclusion modes always, fileMatch, manual, auto	kiro.dev/docs/steering
Devin Desktop (Windsurf docs)	Yes	AGENTS.md, AGENTS.local.md and AGENT.md are read as always-on rules at the workspace root and in each directory between the root and the current working directory.	.devin/rules/*.md, .devin/global_rules.md; legacy .windsurf/rules/*.md, .windsurf/global_rules.md, .windsurfrules imported by default	docs.devin.ai/desktop/cascade/memories
GitHub Copilot	Depends on surface	AGENTS.md can live anywhere in the repo; the nearest one takes precedence. A single root CLAUDE.md or GEMINI.md is an alternative. Support varies by surface (see below).	.github/copilot-instructions.md, .github/instructions/*.instructions.md with applyTo	Add repository instructions; support matrix
Google Antigravity	Yes	AGENTS.md or GEMINI.md in the workspace folder and parents up to the repo root, both treated as always on; rules are cumulative. Does not load rules from subfolders below the workspace folder.	.agents/rules/*.md (legacy .agent/rules/); global ~/.gemini/AGENTS.md, ~/.gemini/GEMINI.md	antigravity.google/docs/rules

Tool notes

Cursor. The docs say a plain .md file in .cursor/rules is ignored because project rules need the .mdc extension and frontmatter; they point you to AGENTS.md if you want plain Markdown. The legacy .cursorrules file is not mentioned on the current rules page. More in our Cursor rules hub and guide to writing Cursor rules.

Claude Code. The memory docs are the most detailed on this topic:

• With an AGENTS.md and no CLAUDE.md or CLAUDE.local.md on the path, Claude reads AGENTS.md. With both, it reads only the CLAUDE.md files by default.
• Your user-level ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files do not count for that check and keep loading alongside AGENTS.md.
• Adding a personal CLAUDE.local.md does count, so it stops Claude reading AGENTS.md unless you switch Project instructions to claude-md-and-agents-md (in /config, or in user or managed settings under the built-in plugin entry the docs describe).
• AGENTS.local.md, AGENTS.override.md and anything under .agents/ are not read.
• Some sessions cannot read AGENTS.md directly (for example if the built-in plugin is disabled). The documented fallback is a CLAUDE.md that imports it with @AGENTS.md.

To check, run /memory and look for the AGENTS.md path. See our Claude rules hub.

Gemini CLI. Without configuration, Gemini CLI looks for GEMINI.md. The documented way to include AGENTS.md is a settings.json entry such as:

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

/memory show displays the combined context the model receives. A GEMINI.md can also pull in another file with an @file.md import. See our Gemini rules hub.

Kiro. Steering files support inclusion modes, but AGENTS.md does not: it is always included. Use .kiro/steering/ files with fileMatch inclusion when an instruction should apply only to certain paths. The Kiro docs say workspace steering wins over global steering when they conflict; they do not say how AGENTS.md ranks against steering files. See our Kiro rules hub.

Devin Desktop (Windsurf). The old Windsurf memories URL, docs.windsurf.com/windsurf/cascade/memories, now redirects to Devin documentation, which presents the agent as part of Devin Desktop. That page says legacy .windsurf/rules/*.md, .windsurf/global_rules.md and .windsurfrules files are imported by default. Rule files use a trigger: of always_on, glob, model_decision or manual; AGENTS.md files are always on. See our Windsurf rules hub.

GitHub Copilot. GitHub's support matrix lists agent instructions (AGENTS.md, CLAUDE.md or GEMINI.md) for Copilot cloud agent, Copilot code review on GitHub.com and Copilot CLI. Copilot Chat in VS Code lists agent instructions using an AGENTS.md file only. Several other surfaces do not list agent instructions in the matrix; for example, Copilot code review in VS Code and in Visual Studio is listed with repository-wide instructions only. If you rely on those surfaces, keep .github/copilot-instructions.md as well. See our Copilot rules hub.

Google Antigravity. Antigravity reads both AGENTS.md and GEMINI.md and combines them rather than choosing one. It truncates any single rule file over 24,000 bytes, and global plus always-on rules share a 20,000-token budget; when the total is exceeded, the largest files are demoted to pointers the agent reads on demand. See our Antigravity rules hub.

How AGENTS.md relates to CLAUDE.md, GEMINI.md and tool rules

Think of the files in two layers:

1. Shared project instructions that every agent should know: what the project is, how to build and test it, conventions, and things never to do. This is what AGENTS.md is for.
2. Tool-specific instructions that only make sense for one tool, or that need that tool's scoping features: .cursor/rules/*.mdc with globs, .kiro/steering/ with fileMatch, .github/instructions/*.instructions.md with applyTo, .devin/rules/ with triggers, .agents/rules/ in Antigravity, and Claude Code's .claude/rules/.

CLAUDE.md and GEMINI.md sit in between. Each is the native project file for its tool, but other tools may also read them: Copilot accepts a root CLAUDE.md or GEMINI.md as agent instructions, and Antigravity reads GEMINI.md alongside AGENTS.md. That overlap is why duplicated content can appear twice in some tools.

A minimal AGENTS.md

Illustrative example — adapt it to your project; it has not been tested in each tool.

# AGENTS.md

## Project
Next.js 15 app (TypeScript, App Router) with a Postgres database via Prisma.

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Type check: `npm run typecheck`
- Tests: `npm test` (run before proposing a commit)

## Conventions
- Server Components by default; add "use client" only when needed.
- Validate API input with zod at the route boundary.
- Prefer named exports. No default exports in `src/lib`.

## Do not
- Edit generated files in `src/generated/`.
- Change database migrations that are already committed; add a new one.
- Commit secrets or read `.env` files.

## Pull requests
- One logical change per PR, with a short description and test notes.

Keep it short and concrete. Every always-on file is added to the context on every request, and at least one tool (Antigravity) documents a per-file size limit.

Pattern: one shared file plus thin tool-specific overrides

The goal is a single source of truth for shared instructions, with small tool-specific files only where a tool needs them.

1. Put shared instructions in a root AGENTS.md. Add nested AGENTS.md files in subprojects only if the tools you use support nesting (Cursor, Claude Code, Kiro, Devin Desktop and Copilot document it; Antigravity does not load rules below the workspace folder).
2. Claude Code: if you have no Claude-specific instructions, you need nothing else on v2.1.277 or later. If you do, create a CLAUDE.md whose first line is @AGENTS.md, followed by the Claude-only lines. The docs say the import is never read twice. Avoid a symlinked CLAUDE.md if anyone on the team uses Windows; the docs explain why.
3. Gemini CLI: add AGENTS.md to context.fileName in Gemini CLI's settings.json, or keep a GEMINI.md that imports it.
4. Cursor, Kiro, Devin Desktop: nothing extra is required for shared instructions. Use .cursor/rules/*.mdc, .kiro/steering/ or .devin/rules/ only for path-scoped or on-demand rules.
5. Copilot: AGENTS.md covers the surfaces that list agent instructions. For surfaces that only list repository-wide instructions, keep a short .github/copilot-instructions.md with the essentials.

Caveats

• Duplication. Tools that read several files will see repeated content twice. Examples: Antigravity combining AGENTS.md with a GEMINI.md that repeats it, or a Copilot surface reading both copilot-instructions.md and AGENTS.md. Keep overrides to what is different, not a copy.
• Silent fallbacks. In Claude Code, adding a CLAUDE.md or CLAUDE.local.md anywhere on the path switches it off AGENTS.md by default. In Gemini CLI, AGENTS.md is ignored until you configure it.
• Precedence is not uniform. Nearest-file-wins is common but not universal, and some tools combine everything. Do not rely on a subdirectory file overriding a root file unless your tool documents it.
• Versions and surfaces matter. Claude Code's AGENTS.md support has a minimum version; Copilot's varies by IDE and feature. Recheck the vendor docs when you upgrade.
• Instructions are context, not enforcement. Claude Code's docs say Claude treats these files as context, not enforced configuration, and point to hooks when an action must be blocked. The same principle applies to the other tools.

How to verify in your own setup

Rather than trusting any table, including this one, check what each tool actually loaded:

• Claude Code: run /memory and look for the AGENTS.md path.
• Gemini CLI: run /memory show to see the combined context.
• Copilot Chat: the docs say that when Copilot Chat uses .github/copilot-instructions.md, the file appears in the response's References list.
• Any tool: ask the agent to quote the first rule from your project instructions and confirm it matches the file.

Related resources

• Rules hubs: Cursor, Claude, Gemini, Kiro, Windsurf, Copilot, Antigravity
• Rules generator: generate a draft AGENTS.md or a Cursor .mdc rule from your stack, then review and adapt it
• How to write Cursor rules
• Cursor vs Windsurf vs Claude Code