Make the App Yours: Instruction Files Compared

You correct the same thing every session. The agent runs npm test in a project that uses pnpm. It writes a new date helper next to the one you already have. It reaches for a library you deleted six months ago. Every coding agent now ships a file designed to stop exactly this, and every vendor gives it a different name, a different folder and a different set of loading rules.

This guide compares the four you are most likely to meet, then covers the part no vendor writes down: what actually belongs in one of these files, what is quietly eating your context window, and how to tell when the file has gone stale.

The same idea, four implementations

The shapes differ more than the table suggests. Read on for the parts that will bite you.

Claude Code Paid

Anthropic's agentic coding tool for the terminal, IDE, desktop and web

★ 149k · +863 this week

🔥 Claude Pro billed annually: $17/month instead of $20

9.4 Visit ↗

Claude Code: a stack of files, concatenated

Claude Code reads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it. Nothing overrides anything: all discovered files are concatenated, ordered from the filesystem root down, so the file closest to where you launched the session is read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md, which makes it the right home for your own uncommitted notes — sandbox URLs, test accounts, the path to your scratch database. Add it to .gitignore.

Files in subdirectories are not loaded at launch. They load when Claude reads a file in that subdirectory, which is the mechanism that makes a monorepo tolerable: the root file stays small and services/billing/CLAUDE.md only costs you context when the agent goes there.

Two features do real work. @path/to/file imports another file inline, up to four hops deep, and resolves relative to the file containing the import — useful for pulling a shared style guide out of the main file. Block-level HTML comments are stripped before the content reaches the model, so <!-- rewrite this section after the v3 migration --> is a note to yourself that costs nothing.

There is also .claude/rules/, a folder of topic files where each one can carry a paths glob in its frontmatter and load only when the agent touches matching files. If your instructions file is growing because half of it only applies to your React components, that is where the React half belongs.

The line worth memorising is in Anthropic's own documentation: these files are context, not enforced configuration. A rule is a strong suggestion, not a guard rail. If something must never happen, a hook enforces it; the instructions file does not.

Cursor Freemium

The AI-first code editor with agents, background agents and fast autocomplete

Free plan, paid from $20/mo

🔥 Save 20% with annual billing

9.0 Visit ↗

Cursor: rules with a trigger condition

Cursor's project rules live in .cursor/rules as .mdc files, and plain .md files in that folder are ignored — a mistake almost everyone makes once. The interesting difference is that a Cursor rule declares when it applies, through frontmatter: alwaysApply: true for a rule that is always in context, alwaysApply: false with a description for one the agent pulls in when it judges the rule relevant, and alwaysApply: false with a globs pattern for one that attaches when matching files are in play. Leave out all three and the rule only applies when you invoke it by hand.

That is a genuinely better model than one always-on blob, and it is the reason Cursor can tell you to keep rules under 500 lines while Anthropic says 200: a Cursor rule is not necessarily loaded. Personal preferences that follow you across projects go in User Rules, set in the app rather than in the repo.

Cursor also reads AGENTS.md, including nested ones in subdirectories, combining them with parent directories so the more specific instructions take precedence. In practice that is the file to write if you want one thing that works in Cursor and elsewhere, with .cursor/rules reserved for genuinely Cursor-shaped behaviour.

OpenAI Codex Freemium

OpenAI's coding agent for the terminal, IDE and cloud, included with ChatGPT plans

★ 128k · +1.2k this week

9.1 Visit ↗

Codex and the AGENTS.md crowd

The standard itself — what it is, who agreed to it, what goes in it — is covered in our post on AGENTS.md as one instructions file for every agent. What matters here is how Codex actually loads it, because the mechanics are stricter than most people assume.

Codex builds one instruction chain per session. Globally it reads AGENTS.override.md from your Codex home directory if it exists, otherwise AGENTS.md. Then it walks from the repository root down to your current working directory, and in each directory takes the first file it finds: AGENTS.override.md, then AGENTS.md, then any fallback filenames you configured. It concatenates the lot from the root down, joined by blank lines, so files nearer your working directory appear later and effectively override earlier guidance.

The detail that catches people is the byte ceiling. Codex stops adding files once the combined size reaches its limit, 32 KiB by default. In a deep monorepo with instructions at several levels, the file you care about most can be the one that falls off the end. If you have been wondering why a subfolder's rules seem to be ignored, measure the chain before you rewrite it.

Claude Code will also read AGENTS.md directly, but only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md silently stops the AGENTS.md from loading for you. That is the single most confusing interaction in this whole area, and it is documented, but not anywhere you would look before it happened.

GitHub Copilot Freemium

AI pair programmer and coding agent across VS Code, JetBrains, the CLI and GitHub

Free plan, paid from $10/mo

🔥 Free Copilot for verified students

8.7 Visit ↗

Copilot: several files, several surfaces

Copilot spreads the same idea across more files than anyone else. .github/copilot-instructions.md is the repository-wide file. .github/instructions/*.instructions.md files carry an applyTo glob in frontmatter and attach to matching files, with an excludeAgent key to keep a file away from code review or the cloud agent. AGENTS.md can live anywhere in the repository, and the nearest one in the tree wins.

The catch is that support varies by surface. Repository-wide instructions work in chat, the cloud agent and code review. Path-specific instructions work in the cloud agent and code review, but not in chat. AGENTS.md works in the cloud agent only. So a rule that visibly works when the coding agent opens a pull request may do nothing while you type in the sidebar.

In VS Code the picture widens again: it reads AGENTS.md, CLAUDE.md, .claude/rules/*.instructions.md and user-level folders such as ~/.copilot/instructions, each behind its own setting. Useful, and worth knowing the documentation's own warning: when several instruction files apply, they are combined with no guaranteed order. Do not write rules that depend on being read last.

What belongs in the file

Everything above is loading mechanics. The harder question is what to type, and here is where most of these files go wrong.

Four things earn their place:

• Commands that work. The exact test command, the exact build command, the one that lints, the one that regenerates types. Not "run the tests" — the string you would type, including the package manager. This is the single highest-value content in the file.
• Conventions the code does not reveal. That errors return a result object rather than throwing, that migrations are numbered not timestamped, that every new endpoint needs an entry in a registry file. Rules an agent would only learn by breaking them.
• Hard prohibitions, with the reason. "Never edit files in generated/; they come from the schema." "Never add a dependency without asking." The reason matters: a rule with a rationale survives contact with an edge case, a bare rule gets argued around.
• Where things live. Five or six lines of map. "API handlers in src/api/handlers/. Shared types in packages/types. Anything in legacy/ is frozen." This saves the agent a search on every task.

Write each one concretely enough to check. "Use 2-space indentation" beats "format code properly". "Run pnpm test:unit before committing" beats "test your changes". If you cannot tell from the outside whether the agent followed the rule, the model cannot tell either.

What wastes context

The same file usually contains three kinds of filler, and all of them cost you tokens in every single session.

Essays. Paragraphs on why you chose this architecture, what the product is for, how the team thinks about quality. None of it changes what the agent does next.

Duplicated README. If it is already in the README, link to it, or on Claude Code import it with @README so there is one copy rather than two that will disagree in a month.

Anything derivable from the code. The dependency list, the folder tree, the schema, the names of your components. The agent can read those in a second, and your description of them starts rotting the day you write it. Claude Code's own auto-memory feature explicitly skips anything it could derive from the codebase; apply the same test by hand.

Rules that contradict each other. Two instructions that disagree do not average out — the model picks one, arbitrarily, and you get flaky behaviour that looks like a model problem.

A blunt heuristic: if a line has never changed the agent's output, delete it. You will lose a third of the file.

Noticing it has gone stale

Instruction files rot silently, because nothing fails when a rule stops being true. Three cheap habits catch it.

Treat a correction as a bug report. When you correct the agent twice about the same thing, the file is either missing a rule or contains a rule that is being ignored because it is buried in a wall of text. Both are fixable in a minute.

Read it after every dependency change. Swapping a test runner, a package manager or a deployment target invalidates the most valuable lines in the file — the commands. A stale command is worse than no command, because the agent will confidently run it.

Check what actually loaded. Claude Code's /context command lists the memory files in play under Memory files. If a file you expected is missing, you have been writing to nobody. That is the fastest way to catch the CLAUDE.local.md-suppresses-AGENTS.md trap, or a rule saved as .md in a folder that only reads .mdc.

One file, several tools

If you use more than one agent — and most solo builders eventually do — write AGENTS.md as the real file and let the others point at it.

Cursor, Codex and Copilot's cloud agent read AGENTS.md natively. For Claude Code, either let it read AGENTS.md (it does when no CLAUDE.md exists above your working directory), or keep a small CLAUDE.md whose first line is @AGENTS.md and put Claude-specific instructions below it. A symlink also works, with two caveats worth knowing before you choose it: Claude Code's edit tools refuse to write through a symlink and will redirect you to the target, and on Windows a committed symlink can check out as a one-line text file. The import is the safer default.

Keep the shared file to things that are true regardless of which agent reads it. Tool-specific behaviour — Cursor rule triggers, Claude Code hooks, Copilot's applyTo globs — belongs in that tool's own files, kept deliberately short.

Do this next

1. Open your instructions file and delete every line that describes something the agent can read from the code.
2. Check that every command in it still runs. Fix or remove the ones that do not.
3. Move anything that only applies to one folder into a scoped file: .claude/rules/ with paths, a Cursor rule with globs, or a nested AGENTS.md.
4. Start a session and confirm which files loaded, rather than assuming.
5. If you run more than one agent, make AGENTS.md the source and point the rest at it.

Once the file is doing its job, the next thing worth building is a set of skills you can carry between projects and machines — that is a personal skill library you can carry between apps. If you are still choosing your first agent, start at the beginner guides. If you want to write instructions and skills that other people will install, the developer guides cover packaging and distribution, the ecosystem map shows which apps read which formats, and the glossary covers the terms these docs use without defining.

Read the official docs for…

• Claude Code memory files, imports and .claude/rules/ — code.claude.com/docs/en/memory
• Cursor rule types, frontmatter keys and .mdc syntax — cursor.com/docs/context/rules
• Codex AGENTS.md discovery order, override files and size limits — learn.chatgpt.com/docs/agent-configuration/agents-md
• Copilot repository instructions, applyTo and surface support — docs.github.com
• VS Code custom instructions and the settings that enable each file — code.visualstudio.com
• The AGENTS.md format and which tools claim support — agents.md