Which instruction file does your coding agent actually read? AGENTS.md, CLAUDE.md, Cursor and Copilot

wilzap — Fri, 30 Oct 2026 14:48:32 +0000

Disclosure: this article was drafted with an AI assistant and edited and fact-checked by me against each tool's documentation on Oct 30, 2026. I made the free files linked below and I also sell a larger set; that is mentioned once, at the end. These tools change often, so re-check the linked pages before you rely on a detail.

The problem

You add an AGENTS.md. A teammate adds a CLAUDE.md. Someone else adds .cursor/rules. A month later nobody knows which file the agent actually used, and two of them say different things.

Here is what each tool's documentation says today.

Claude Code

From the memory docs:

If your repo has an AGENTS.md and no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it, Claude Code reads your AGENTS.md. This needs v2.1.277 or later.
If any of those CLAUDE.md files exist, Claude reads the CLAUDE.md files only by default.
CLAUDE.local.md counts for that check. A personal, uncommitted CLAUDE.local.md can quietly stop Claude from reading the team's AGENTS.md for you.
If your CLAUDE.md contains @AGENTS.md, the file is imported once, so nothing loads twice.
The "Project instructions" setting in /config can be changed to read both files.
Run /memory (or /context) to see which instruction files were loaded.

The docs also say to aim for under about 200 lines per CLAUDE.md, and that these files are context, not enforcement. If something must happen every time, use a hook.

A CLAUDE.md that shares the rules and adds Claude-only notes:

@AGENTS.md

## Claude Code
- Use plan mode for changes that touch more than two files.
- Run /clear between unrelated tasks.

Cursor

Cursor's rules docs describe project rules as .mdc files in .cursor/rules. The frontmatter fields decide when a rule is included:

`alwaysApply`	`description`	`globs`	What happens
`true`	n/a	n/a	Always included
`false`	n/a	set	Attached when a matching file is in context
`false`	set	not set	The agent reads the description and decides
`false`	not set	not set	Only when you `@`-mention the rule

Two details that trip people up: a plain .md file in .cursor/rules is ignored (it must be .mdc), and Cursor also reads AGENTS.md, including nested ones in subdirectories. Cursor's own advice is to keep each rule under 500 lines and split big ones into focused rules.

GitHub Copilot

The Copilot docs list three kinds of repository instructions:

.github/copilot-instructions.md for the whole repository.
.github/instructions/NAME.instructions.md with an applyTo glob, for specific paths.
AGENTS.md anywhere in the repo (the nearest one wins), or a single CLAUDE.md or GEMINI.md at the repo root.

Path-specific files are currently supported only for the Copilot cloud agent and Copilot code review on GitHub.com, so check which Copilot surface you use.

A structure that avoids drift

This is the structure the free files below use, not the only way:

One AGENTS.md as the shared source of truth.
CLAUDE.md = @AGENTS.md plus Claude-only lines, as above.
Cursor and Copilot files kept consistent with the same content. Generating them from one source stops the files disagreeing; copying by hand does not.

If the overlap bothers you, the other honest option is to keep only the file for the single tool your team uses.

What belongs inside

Three kinds of lines earn their place; cut the rest:

Facts about the repo. Exact commands (pnpm test, uv run pytest), where things live.
Guards against mistakes agents are known to make, taken from official docs rather than vibes.
Verification steps. "Run typecheck, lint and tests, and say which ones ran."

Cursor's docs make a similar point: do not copy whole style guides (use a linter), and do not document every command the agent already knows.

Example guards for Next.js 16, from the upgrade guide:

params, searchParams, cookies(), headers() and draftMode() must be awaited. Synchronous access was removed in 16.
middleware.ts is renamed proxy.ts, with an exported proxy function. proxy runs on the Node.js runtime only, so a project that needs the Edge runtime keeps middleware.
next lint was removed, and next build no longer lints. Run ESLint or Biome directly.

One line each. If the agent already follows a line without being told, delete it.

What this does not do

I have not benchmarked any of this against specific models, and I am not claiming it makes an agent better by some percentage. Rules are context. An agent can still ignore them. Tests, CI and code review stay the real gate. If you want to know whether a line earns its place, run the same few tasks with and without it and compare test results, not impressions.

Free files, and a paid set

Free to use, no signup (MIT licensed): a Next.js 16 + TypeScript pack and a Python + FastAPI pack, each as AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc and .github/copilot-instructions.md: github.com/imwilzap/agent-rules-kit-lite. Corrections welcome as issues.
Disclosure: I also sell a six-stack version (adds Go, Rust, Django and React Native) with a playbook PDF and a QA checklist for CAD 3.33: Agent Rules Kit on Gumroad. It has a 7-day money-back guarantee. You do not need it to use anything above.

DEV Community: wilzap