All 5 AI packs for $39 →
← All posts
AGENTS.md · CLAUDE.md · Cursor rules · How-to

AGENTS.md vs CLAUDE.md vs Cursor rules vs copilot-instructions.md: which file each coding agent reads

Published · Facts checked against official vendor pages on October 22, 2026 · Rankings are independent of sponsorships

Every coding agent reads a project instruction file, but they don't all read the same one, and the rules for which file wins differ in ways that quietly break setups. Claude Code, for example, ignores your AGENTS.md by default as soon as a CLAUDE.md exists. We read the current docs for Cursor, Claude Code, OpenAI Codex, GitHub Copilot and Gemini CLI on October 22, 2026. Here is what each one loads, and a setup that lets one file brief all of them.

Tools in this post

SCursorSClaude CodeAOpenAI CodexAGitHub CopilotAGemini CLI

The short version

Write one AGENTS.md at the repo root and treat it as the source of truth. Cursor, Codex and Copilot on GitHub read it directly, Claude Code reads it when there's no CLAUDE.md, and Gemini CLI reads it once you add it to its context file names.

Add tool-specific files only for what's tool-specific: scoped .cursor/rules/*.mdc rules in Cursor, a CLAUDE.md that imports AGENTS.md plus Claude-only notes, and subagents in .claude/agents/.

Keep it short. Claude Code's docs suggest under 200 lines per CLAUDE.md, Cursor suggests under 500 lines per rule, and Codex stops adding instruction files at 32 KiB by default.

Cursor: .cursor/rules/*.mdc and AGENTS.md

Cursor's project rules live in .cursor/rules/ and must use the .mdc extension. A plain .md file in that folder is ignored, because it has no frontmatter. Three frontmatter fields decide when a rule loads: alwaysApply: true includes it in every chat; globs attaches it when a matching file is in context; a description alone lets the agent decide when it's relevant; and with none of them you have to @-mention the rule.

Cursor also reads AGENTS.md as a plain-Markdown alternative, in the project root and in subdirectories. Nested files combine with their parents, and the more specific one takes precedence. On top of project rules there are User Rules (your global preferences) and, on Team and Enterprise plans, Team Rules from the dashboard. Precedence is Team, then Project, then User. Two details catch people out: rules don't affect Cursor Tab, and an @file mention inside a rule isn't inlined. The agent reads that file only when it needs it, so put anything that must always be in context in the rule body.

Free examples: our always-on Next.js core rule and the new Supabase rule, which loads when the agent decides a task touches Supabase. More on the editor itself on our Cursor page.

Claude Code: CLAUDE.md, with AGENTS.md as a fallback

Claude Code loads project instructions from ./CLAUDE.md or ./.claude/CLAUDE.md, personal ones from ~/.claude/CLAUDE.md, and private per-project notes from CLAUDE.local.md (add that one to .gitignore). Files in parent directories load at launch; CLAUDE.md files in subdirectories load when Claude works with files there. You can split instructions into .claude/rules/*.md, and a paths frontmatter field scopes a rule to matching files.

Since v2.1.277, Claude Code can read AGENTS.md directly, but only when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If both exist, it reads only CLAUDE.md by default. The fix Anthropic's docs recommend is to put @AGENTS.md at the top of CLAUDE.md and add Claude-specific instructions below it, or to change the Project instructions setting in /config to read both. Run /context to confirm which memory files loaded.

Subagents are separate Markdown files with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (all your projects). Only name and description are required. Our free CLAUDE.md template, code-reviewer and new planner subagents are ready to drop in. See our Claude Code page for plans.

OpenAI Codex: AGENTS.md, layered from global to folder

Codex reads AGENTS.md before doing any work. It starts with a global file in ~/.codex (AGENTS.override.md if it exists, otherwise AGENTS.md), then walks from the project root down to your current directory. In each folder it takes at most one file: AGENTS.override.md first, then AGENTS.md, then any names you list in project_doc_fallback_filenames. Files are concatenated root-down, so the closest file appears last and wins on conflicts.

Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. A sprawling root file can silently crowd out a folder-specific one, so keep the root short and push detail into nested files. To check what loaded, ask Codex to summarize its current instructions. Plans are on our OpenAI Codex page.

GitHub Copilot: copilot-instructions.md, path files and AGENTS.md

GitHub's docs list three kinds of repository instructions for Copilot on GitHub. Repository-wide instructions go in .github/copilot-instructions.md. Path-specific ones go in .github/instructions/NAME.instructions.md with an applyTo glob in the frontmatter; on GitHub.com these are currently used only by the Copilot cloud agent and Copilot code review. And agent instructions can be one or more AGENTS.md files anywhere in the repo, where the nearest one takes precedence. A single CLAUDE.md or GEMINI.md in the root also works.

When a path-specific file matches, Copilot uses it together with the repo-wide file. Personal instructions take priority over repository ones, which take priority over organization ones, but all relevant sets are sent. For code review, Copilot reads instructions from the head branch of the pull request, so you can test changes to them in the same PR. Our free copilot-instructions.md for Next.js follows the structure GitHub recommends. Plans are on our GitHub Copilot page.

Gemini CLI: GEMINI.md, or AGENTS.md if you configure it

Gemini CLI loads ~/.gemini/GEMINI.md, then GEMINI.md files in your workspace and its parent directories, and picks up more as tools touch other folders. It supports @file.md imports, and /memory show prints exactly what it sent. To make it read your shared file, set context.fileName in settings.json to a list such as ["AGENTS.md", "GEMINI.md"].

Note that Gemini CLI's docs now say that for unpaid-tier and Google One users it was replaced by Antigravity CLI on June 18, 2026. Details are on our Gemini CLI page.

A setup that works across all five

1. Write a short root AGENTS.md with the project summary, exact commands, layout, rules and definition of done. Our free AGENTS.md starter has all of those sections.

2. Add a CLAUDE.md whose first line is @AGENTS.md, followed only by Claude-specific notes. Without the import, Claude Code skips AGENTS.md as soon as CLAUDE.md exists.

3. Add scoped Cursor rules in .cursor/rules/ for stack-specific guidance that shouldn't load on every request, such as a Supabase or testing rule with a description or globs.

4. If you use Copilot code review or its cloud agent, add a short .github/copilot-instructions.md for build and validate steps, or rely on AGENTS.md.

5. In Gemini CLI, add AGENTS.md to context.fileName.

6. Add a rule only after you've seen the agent repeat a mistake, and check what actually loaded (/context in Claude Code, /memory show in Gemini CLI, the References list in Copilot Chat) instead of assuming. Cursor's and Anthropic's docs both make this point: specific, short instructions get followed more reliably.

Want the full set for one stack instead of single files? The Cursor Rules: Next.js 16 pack has 12 scoped rules plus AGENTS.md and CLAUDE.md, and the Claude Code Agent Kit packages 12 subagents, 8 skills and 3 safety hooks as an installable plugin.

FAQ

Does Cursor read AGENTS.md?
Yes. Cursor's docs list AGENTS.md as a plain-Markdown alternative to .cursor/rules, supported in the project root and in subdirectories, with nested files combined and the more specific one taking precedence.
Does Claude Code read AGENTS.md?
Yes, from v2.1.277, but by default only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. To use both, put @AGENTS.md at the top of CLAUDE.md or change the Project instructions setting in /config.
Do Cursor rules need the .mdc extension?
Yes. Cursor's docs say project rules in .cursor/rules must use .mdc; a plain .md file there is ignored because it has no frontmatter. Use AGENTS.md if you want plain Markdown.
How big can AGENTS.md be for Codex?
Codex stops adding instruction files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default. You can raise it in ~/.codex/config.toml or split instructions across nested folders.
Where do GitHub Copilot custom instructions go?
Repository-wide instructions go in .github/copilot-instructions.md, path-specific ones in .github/instructions/NAME.instructions.md with an applyTo glob, and agent instructions can be AGENTS.md files anywhere in the repo.

Free and paid rules for your agents

Related changelog

Sources

Prices change often. Always confirm on the vendor's site before buying. See the full tier lists and the changelog.

+ Your logo here