Skip to content
AI & Tools

AGENTS.md, CLAUDE.md, Copilot Instructions and Cursor Rules: What Each Agent Actually Reads

AIDToolStack EditorialNovember 7, 20268 min read
AGENTS.mdClaude CodeGitHub CopilotCursorCodex
Share:Twitter

A repository that three people work on with three different agents tends to grow three different instruction files. Someone runs /init in Claude Code and commits a CLAUDE.md. Someone else adds .github/copilot-instructions.md. A Cursor user drops rules into .cursor/rules/. Six months later the test command differs in two of them and nobody knows which file each agent actually reads.

The good news is that this has mostly converged. As of November 2026, AGENTS.md is read by every major coding agent, either natively or with one line of config, with a few chat surfaces as exceptions. The details still differ in ways that bite: which file wins when two exist, whether nested files load, and how much text gets read before the rest is silently dropped. This post is the map, built from each vendor's current docs.

What AGENTS.md actually is

AGENTS.md is plain Markdown in your repository that tells coding agents how to work on the project: build steps, test commands, conventions. The site calls it a README for agents, kept separate so your human README stays readable. There's no schema and no required sections. It's now stewarded by the Agentic AI Foundation under the Linux Foundation, and the site lists support from Codex, Jules, Gemini CLI, Cursor, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Windsurf, Junie, Amp, Kilo Code, Augment Code and GitHub Copilot's coding agent, among others.

Its one real rule is about precedence in monorepos: put an AGENTS.md in each package, and "the closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." That's the spec's intent. How each tool implements "closest wins" is where it gets interesting.

Tool by tool

Matrix showing which instruction files Codex, Claude Code, Copilot, Cursor and Gemini CLI read by default as of November 2026
Matrix showing which instruction files Codex, Claude Code, Copilot, Cursor and Gemini CLI read by default as of November 2026

OpenAI Codex

Codex has the most precise rules. Its AGENTS.md docs are precise:

  1. Global: it reads ~/.codex/AGENTS.override.md if it exists and isn't empty, otherwise ~/.codex/AGENTS.md (or the same under CODEX_HOME).
  2. Project: it walks from the project root (usually the Git root) down to your current directory. In each directory it takes at most one file, checking AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames.
  3. It concatenates them root first, so the file nearest your working directory comes last and overrides broader guidance.

Two gotchas. The combined size is capped by project_doc_max_bytes, which is 32 KiB by default; once it's hit, Codex stops adding files. And the chain is built once per run (once per session in the TUI), so edits mid-session need a restart. If your team already has a TEAM_GUIDE.md, you can teach Codex to read it:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Claude Code

Claude Code has its own file, CLAUDE.md, at several levels: an organisation-managed one (for example /etc/claude-code/CLAUDE.md on Linux), your personal ~/.claude/CLAUDE.md, the project's ./CLAUDE.md or ./.claude/CLAUDE.md, and a gitignored ./CLAUDE.local.md for personal notes. Per the memory docs, files from the working directory and every directory above it load at launch and are concatenated root first; CLAUDE.md files in subdirectories load on demand when Claude reads or edits something there.

The big change this year: since v2.1.277 Claude Code reads AGENTS.md itself. The default rule is "either/or", not "both":

What's in your repoWhat Claude reads by default
AGENTS.md, no CLAUDE.md or CLAUDE.local.md in cwd or aboveAGENTS.md
AGENTS.md plus a CLAUDE.md or CLAUDE.local.mdOnly the CLAUDE.md files
A CLAUDE.md containing @AGENTS.mdCLAUDE.md with AGENTS.md imported

The trap is in the second row. CLAUDE.local.md counts, so creating one for your own scratch notes in an AGENTS.md repo quietly stops Claude from reading AGENTS.md. You can change the behaviour with the Project instructions setting in /config (claude-md-and-agents-md reads both). Claude Code also ignores AGENTS.override.md, AGENTS.local.md and anything under .agents/, so Codex's override trick doesn't carry over.

The docs suggest keeping each CLAUDE.md under 200 lines and moving path-specific guidance into .claude/rules/*.md files with a paths: frontmatter field, which only load when Claude touches matching files. Imports via @path help organisation but don't save context, because imported files load with their parent. I covered the rest of the Claude Code setup in Claude Code tips: CLAUDE.md, skills, permissions and hooks.

GitHub Copilot

Copilot has the most file types and the most surface-dependent behaviour. Per GitHub's repository instructions docs:

  • .github/copilot-instructions.md applies repository-wide.
  • .github/instructions/NAME.instructions.md files apply to paths matched by an applyTo glob in frontmatter; an excludeAgent key can hide a file from "code-review" or "cloud-agent".
  • AGENTS.md files can live anywhere in the repo, and "the nearest AGENTS.md file in the directory tree will take precedence." Alternatively, a single CLAUDE.md or GEMINI.md at the root works.

Which surface reads what is the part people miss. GitHub's support matrix says the cloud agent, Copilot CLI and code review on GitHub.com read AGENTS.md, CLAUDE.md and GEMINI.md (code review also reads REVIEW.md). VS Code chat reads AGENTS.md only. JetBrains and Visual Studio chat don't read agent files at all, and Copilot Chat on GitHub.com only reads the repository-wide file. So if your JetBrains users rely on chat, the shared conventions still need to be in copilot-instructions.md. My Copilot post goes further into prompt files and custom agents.

Cursor

Cursor's rules live in .cursor/rules/ and must use the .mdc extension; plain .md files in that folder are ignored. Frontmatter decides when a rule loads:

---
description: Conventions for the payments API handlers
globs: src/payments/**/*.ts
alwaysApply: false
---
Use the Money type for all amounts. Never use floats for currency.

alwaysApply: true loads it in every chat; a description alone lets the agent decide; globs attaches it when matching files are in context; neither means you @-mention it manually. Cursor also reads AGENTS.md in the root and in subdirectories, combining nested files with their parents, more specific ones taking precedence. Team rules beat project rules, which beat user rules. Cursor's guidance is to keep rules under 500 lines.

Gemini CLI

Gemini CLI reads GEMINI.md from ~/.gemini/, from your workspace directories and their ancestors, and just-in-time from subdirectories when a tool touches files there. It concatenates everything; /memory show prints exactly what the model gets. Per its GEMINI.md docs, you switch it to AGENTS.md in .gemini/settings.json:

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

One caveat that will date: Google announced in May 2026 that Gemini CLI stopped serving individual Google AI Pro/Ultra and free Code Assist users on 18 June 2026, in favour of the new Antigravity CLI. Organisations on Code Assist Standard/Enterprise and paid API keys keep access. I couldn't find Antigravity CLI documentation on instruction files, so I'm not making claims about it.

How "nearest wins" really plays out

Directory tree showing how Codex, Claude Code and Copilot combine a root AGENTS.md with a nested one
Directory tree showing how Codex, Claude Code and Copilot combine a root AGENTS.md with a nested one

Most tools don't pick one file. Codex, Claude Code, Gemini CLI and Cursor all concatenate ancestor files, ordering them so the most specific comes last. That means a root file saying "use npm" and a package file saying "use pnpm" are both in context, and you're relying on the model to prefer the later one. Claude's docs say it plainly: if two instructions contradict each other, Claude may pick one arbitrarily. Don't write nested files that override; write nested files that add.

A setup that works across all of them

Here's what I'd do in a repo where people use different agents:

  1. Make AGENTS.md the source of truth. Put the commands, test and lint steps, directory map and hard rules there.
  2. If you need Claude-specific content, create CLAUDE.md with @AGENTS.md as the first line, then your extras. That keeps working in sessions where Claude can't read AGENTS.md directly (older versions, or the plugin disabled), and the docs say the import never causes a double read.
  3. Add one line of Gemini config (above) and, for Aider, read: AGENTS.md in .aider.conf.yml, as the AGENTS.md site suggests.
  4. Keep .github/copilot-instructions.md short and only for surfaces that don't read agent files, or skip it if nobody uses Copilot chat in JetBrains or Visual Studio.
  5. Use path-scoped rules (.claude/rules/, .cursor/rules/, .instructions.md) for the long tail instead of one giant file. Codex has no path-scoped equivalent beyond nested AGENTS.md, so mind the 32 KiB cap.

What goes in the file matters more than which file it is. The things that pay off are the things an agent can't infer: the exact test command for one package, the generated directories it must not edit, the migration step that has to run after schema changes. "Write clean code" is wasted tokens.

Instruction files are not a security control

Two warnings worth taking seriously.

First, these files are context, not enforcement. Claude's docs say so directly and point you to a PreToolUse hook or permissions.deny if something must never happen. The same is true for every tool here. If "never run terraform apply" matters, block it in the agent's permission config, not in prose.

Second, an instruction file is something the agent obeys, which makes it an injection target. A pull request that edits AGENTS.md is effectively editing the agent's instructions for anyone who runs an agent on that branch. Anthropic's GitHub Action handles this by restoring CLAUDE.md, .claude/ and .mcp.json from the base branch before running on a PR. Review changes to these files as carefully as changes to CI config; the same reasoning is behind the attacks in our post on MCP tool poisoning and prompt injection.

Quick checklist

  • One AGENTS.md at the root, nested ones that add rather than contradict.
  • CLAUDE.md = @AGENTS.md plus Claude-only extras, and be careful with CLAUDE.local.md.
  • Gemini context.fileName set; Cursor rules in .mdc, not .md.
  • Under 200 lines per file is a sane target; Codex stops reading files past 32 KiB by default.
  • Anything that must never happen goes in permissions or hooks, not instructions.
  • Treat diffs to instruction files like diffs to .github/workflows/.

If you're still choosing between agents, Claude Code vs OpenAI Codex compares the two that take these files most seriously.

AE

Written by AIDToolStack Editorial

Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.

Sources

  1. agents.md/
  2. learn.chatgpt.com/docs/agent-configuration/agents-md
  3. code.claude.com/docs/en/memory
  4. docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
  5. docs.github.com/en/copilot/reference/custom-instructions-support
  6. cursor.com/docs/context/rules
  7. geminicli.com/docs/cli/gemini-md/
  8. developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/
  9. github.com/anthropics/claude-code-action/blob/main/docs/security.md

Related Posts

Explore on AIDToolStack

Discover tools and servers featured in our directory.

MCP Servers

Trigger.dev Jobs MCP ServerManage Trigger.dev background jobs from your AI coding assistant. Monitor job runs, trigger tasks manually, inspect execution logs, manage schedules, and debug failed runs. The server provides operational visibility into your background job infrastructure — see which tasks are running, queued, or failed, and take action. Your AI can help diagnose job failures from execution logs, retry failed tasks, and optimize concurrency configurations for better throughput.Tailscale Network MCP ServerManage your Tailscale mesh VPN network from your AI coding assistant. View connected devices, manage ACLs, configure exit nodes, check device status, and manage DNS settings. The server provides visibility into your Tailscale network — see which machines are online, troubleshoot connectivity issues, manage network access policies, and configure routes. Useful for developers managing distributed infrastructure where Tailscale provides secure networking between services.Portainer Docker MCP ServerManage Docker environments through Portainer's API from your AI coding assistant. Control containers, images, networks, and volumes across multiple Docker hosts and Kubernetes clusters. The server provides tools for container lifecycle management, image pulling and building, stack deployment, and resource monitoring. Portainer's multi-environment management makes this server particularly valuable for teams managing containers across development, staging, and production environments.

Reviews

Sign in to leave a review.

No reviews yet. Be the first!

Comments

Sign in to leave a comment.

No comments yet. Be the first!

Sponsor Our Newsletter

Reach thousands of developers who are actively evaluating AI tools, MCP servers, and dev infrastructure. Our weekly newsletter goes to engaged technical decision-makers.

Growing subscriber baseHigh open rates

All sponsored content is clearly labeled per our editorial policy.