CLAUDE.md and AGENTS.md: how to write instruction files for AI coding agents
CLAUDE.md and AGENTS.md are plain Markdown files in your project that a coding agent reads at the start of every session. Claude Code reads CLAUDE.md; Codex, Cursor, GitHub Copilot and many others read AGENTS.md, so write your rules once in AGENTS.md and add a one-line CLAUDE.md that imports it. Keep it short (Anthropic targets under 200 lines) and put in only what the agent cannot work out from the code: the exact test and lint commands, misleading places, team decisions and hard limits.
- 1
What is an instruction file?
A coding agent starts every session with a blank memory. An instruction file is a note it reads first, every time: how to run the tests, which old pattern not to copy, what it must never touch. The agents.md site calls AGENTS.md “a README for agents”.
It is plain Markdown with no required fields. Claude Code’s docs are clear that the agent treats it “as context, not enforced configuration”: it is advice the model weighs, not a lock. Anything that must happen every time belongs in a hook or a permission rule instead.
- Session starts
- Agent reads instruction files
- You give a task
- Agent works with your rules in mind
- It runs your test command to check
Key ideaEvery line is read on every task, so each line should change what the agent does.
- 2
Which file does each tool read?
Each tool started with its own file name. AGENTS.md is the shared one: it is now stewarded by the Agentic AI Foundation under the Linux Foundation, and agents.md says it is “used by over 60k open-source projects”. Codex, Cursor, GitHub Copilot, Gemini CLI (with one setting) and many others read it.
Claude Code is the exception to watch. Its memory page (checked 21 Nov 2026) says it reads CLAUDE.md, not AGENTS.md, and tells you to create a CLAUDE.md that imports it with the line @AGENTS.md. InfoWorld reported on 21 Sep 2026 that version 2.1.277 also falls back to AGENTS.md when no CLAUDE.md exists, but only when Claude Code can load Anthropic’s feature flags (not on Bedrock or Vertex, or with telemetry off). The import works in every case, so use it. On Mac or Linux a symlink also works (ln -s AGENTS.md CLAUDE.md); on Windows Anthropic says use the import.
CLAUDE.md that shares AGENTS.md (Anthropic’s documented way) @AGENTS.md ## Claude Code only Use plan mode for changes under src/billing/.5 coding agents · each tool’s docs · checked 21 Nov 2026Three of five tools read AGENTS.md as is; Gemini CLI needs a setting, Claude Code an importTool Main file AGENTS.md Rules for one folder Claude Code CLAUDE.md (also ~/.claude/CLAUDE.md, CLAUDE.local.md) Import it: put @AGENTS.md in CLAUDE.md .claude/rules/*.md with paths in the header OpenAI Codex AGENTS.md (also ~/.codex/AGENTS.md, AGENTS.override.md) Yes, natively An AGENTS.md in the subfolder Cursor .cursor/rules/*.mdc, or AGENTS.md Yes, root and subfolders A rule with globs in its header GitHub Copilot .github/copilot-instructions.md, or AGENTS.md (or a root CLAUDE.md / GEMINI.md) Yes, nearest file wins .github/instructions/*.instructions.md with applyTo in the header Gemini CLI GEMINI.md (also ~/.gemini/GEMINI.md) If you set context.fileName to AGENTS.md A GEMINI.md in the subfolder 3 options comparedSwipe → Source: Claude Code docs: memory, OpenAI Codex: AGENTS.md, Cursor docs: rules, GitHub docs: repository custom instructions, Gemini CLI docs: GEMINI.md · 21 Nov 2026 - 3
Does an instruction file actually help?
Less than most guides suggest, and it depends on what you write. A 2026 ETH Zurich study found that providing context files “does not generally improve task success rates” while “increasing inference cost by over 20% on average”. The same paper found the instructions were followed well, and that repository overviews “are not helpful”.
A second 2026 study, on 10 repositories and 124 pull requests, found AGENTS.md went with a 28.64% lower median runtime and 16.58% fewer output tokens at similar completion. Read together: a short file of rules the agent could not guess saves wasted work; a long tour of the codebase mostly costs tokens.
3 studies of real instruction files · 2025–2026Rules the agent can’t guess help; long overviews mostly add costStudy What they tested What they found ETH Zurich, arXiv 2602.11988 (Feb 2026, rev. Sep 2026) Coding agents with and without context files, both LLM-written and developer-written No general gain in task success; inference cost up over 20% on average; overviews not helpful Lulla et al., arXiv 2601.20404 (Jan 2026) 10 repositories, 124 pull requests, agent run with and without AGENTS.md Median runtime 28.64% lower, output tokens 16.58% lower, similar completion GitHub blog, 2,500+ agents.md files (Nov 2025) What public files that work have in common Commands early, one real code example, clear always / ask first / never rules; most fail by being vague 2 options comparedSwipe → Each study measured different agents and tasks, so the numbers are not comparable with each other.Source: ETH Zurich: Evaluating AGENTS.md (arXiv 2602.11988), Lulla et al.: AGENTS.md and agent efficiency (arXiv 2601.20404), GitHub blog: lessons from 2,500 agents.md files · 21 Nov 2026 Key ideaWrite down what is non-standard about your project. Skip what the agent can read for itself.
- 4
What should you put in, and what should you leave out?
Anthropic’s best-practices page says the file works best when it holds only what Claude couldn’t work out from the code. Here is its list of what to put in, plus what to leave out. Be exact: Anthropic’s memory docs suggest “Use 2-space indentation” over “Format code properly”, and “Run npm test before committing” over “Test your changes”.
- Put in: the exact test, typecheck and lint commands, and how to run one test file.
- Put in: places where the code misleads, like an old pattern new code must not copy.
- Put in: decisions that aren’t in the repo (which error helper, how deploys work) and anything you’ve corrected twice.
- Leave out: long architecture and folder tours (the ETH study found overviews “are not helpful”; one line on where new code goes is fine), style rules your linter enforces (list the lint command instead), and secrets.
- Move out: multi-step procedures to a skill; rules for one folder to a path-scoped rule; anything that must happen every time to a hook (a script the tool always runs).
- Older guides, including Anthropic’s own 2025 blog post, suggest a project map; the 2026 docs and research favour cutting it to the parts the code hides.
A starter AGENTS.md to copy (fill in your own) ## Commands - Install: <install command> - Done means this passes: <test + lint + typecheck> - One test file: <command> ## Things the code won’t tell you - <old pattern new code must not copy> - <team decision, e.g. which error helper> ## Boundaries - Always: <e.g. add a test for a behaviour change> - Ask first: <e.g. new dependency, schema change> - Never: <e.g. edit migrations by hand, commit .env>Key ideaShouting does not help: Anthropic says piling on IMPORTANT “mostly makes Claude over-apply the rule”.
- 5
Worked example: from a /init draft to a short AGENTS.md
Running /init in Claude Code writes a first draft by studying your project. Anthropic’s advice: “From there the work is mostly removing lines.” Here is that cut on a fictional Next.js job tracker, run through the checker on this page.
Worked workflowWorked workflow: cleaning up jobtrack’s instruction file
InputA 60-line draft (~425 tokens): project overview, a 13-line architecture section (mostly a folder tour), style rules, a database URL with a password, an 8-step release list and two “write clean code” lines. Checker: 1 of 11 checks pass.
Delete what the agent can read
The overview and folder tour describe what is already in package.json and the folders. Keep one line for the misleading place: lib/legacyApi.ts must not be copied.
Replace style rules with the command
Five formatting lines become one: the lint command that enforces them. Vague lines (“format code properly”, “be careful”) are deleted or turned into exact rules.
pnpm typecheck && pnpm lint && pnpm test pnpm vitest run tests/stages.test.tsRemove the secret, keep the name
The connection string with a password goes; the file now says DATABASE_URL lives in .env.local. Anyone who saw the old file should get that password changed.
Fix the contradiction and the shouting
“IMPORTANT: Never use any” and “Use any only when…” pull in opposite directions. The linter now owns that rule, and the three IMPORTANT / YOU MUST lines are gone.
Move the procedure, add limits
The 8-step release list moves to docs/release.md (in Claude Code it could become a skill). Three boundary lines are added: always add a test, ask first before a new dependency, never hand-edit migrations.
Rename to AGENTS.md and import it
The file becomes AGENTS.md so Codex, Cursor and Copilot read it too; CLAUDE.md holds one line, @AGENTS.md.
OutputA 29-line AGENTS.md (~277 tokens) with commands at the top, four facts the code hides, three limits plus a pointer to the release doc, and one real code example. Checker: 7 of 7 checks pass. Load both versions in the checker below to see each finding.
- 6
Where do the files live, and how do they combine?
Tools look in more than one place and join what they find. Claude Code walks up from the folder you start in and reads every CLAUDE.md on the way; files in subfolders load when the agent works there; “all discovered files are concatenated” rather than replacing each other. A personal CLAUDE.local.md (kept out of git) is read last at its level.
Codex reads from the project root down to your folder, and files closer to your folder “override earlier guidance because they appear later”. It stops adding files at 32 KiB by default. agents.md’s rule for nested files: “the closest one takes precedence.”
- Keep it alive: when you correct the agent the same way twice, add one line.
- Review changes to the file in pull requests, like code.
- Delete rules that point at files or tools you no longer use. In Claude Code, /doctor prompt-audit flags rules that contradict each other or point at missing files.
A monorepo with one shared file and one per app my-repo/ ├── AGENTS.md # shared: commands, limits ├── CLAUDE.md # @AGENTS.md ├── apps/web/ │ └── AGENTS.md # web-only rules, read when working here └── apps/api/ └── AGENTS.md # api-only rulesKey ideaRoot file for what is true everywhere; a small file in a folder for what is true only there.
Straight from the source
The original idea, then the same idea taken apart, then how you use it today.
- 1 · Understand
- A huge instruction file failed them. Their fix: a short AGENTS.md, roughly 100 lines, that works as a map, “not a 1,000-page instruction manual”, pointing to deeper docs.
- 2 · Break it down
- Context is scarce: a giant file crowds out the task and the code.
- Big manuals go stale fast, and stale rules mislead the agent.
- Treat AGENTS.md as a table of contents; keep detail in linked docs.
- They checked the docs with linters and CI so the map stayed true.
- 3 · Use it
- If your file is growing, move each long section into its own doc and leave one line in AGENTS.md saying when to read it.
- 1 · Understand
- Across several models and agents, context files did not generally raise task success but raised cost by over 20%. Agents did follow the instructions; overviews of the repository did not help.
- 2 · Break it down
- Following instructions is not the same as solving more tasks.
- Overviews repeat what the agent finds by reading the code.
- The useful part is non-standard practice the agent could not guess.
- Measure any change to your file before trusting it.
- 3 · Use it
- Before adding a line, ask whether the agent would act differently without it. If not, leave it out.
Words to know
- CLAUDE.md
- Claude Code’s instruction file. Lives in the project (shared), in ~/.claude/ (just you) or as CLAUDE.local.md (just you, this project).
- AGENTS.md
- The shared, open instruction-file format read by Codex, Cursor, GitHub Copilot, Gemini CLI (with one setting) and many other agents.
- /init
- A Claude Code command that writes a first CLAUDE.md by studying your project. Treat it as a draft to cut down.
- @import
- A line like @AGENTS.md inside CLAUDE.md that pulls another file in. It organises text but does not reduce what is loaded.
- Lint and typecheck
- Commands that check code automatically: a linter flags style and common mistakes, a typecheck catches wrong types. Listing them lets the agent check its own work.
- Hook
- A script the tool always runs at a set moment, such as before a command or after an edit. Use it for rules that must never be skipped.
- Path-scoped rule
- A rule file that applies only to matching files, e.g. .claude/rules/ with paths:, Cursor globs or Copilot applyTo.
Watch
Hand-picked from the people who explain this best. The video loads only when you press play.
A practitioner builds a real AGENTS.md section by section. Compare his file with the checklist in step 4.
A strong opinion on the 2026 research in step 3. Watch it after the lesson and decide where you agree.
Check your CLAUDE.md or AGENTS.md
Paste your file, or load the messy draft and the cleaned-up version from the worked example. Each finding links to the page its rule comes from.
Checked in your browser; nothing is sent anywhere. Still, never paste a real key.
1 of 11 checks pass, 2 to fix, 8 to improve.
- Lines
- 60
- target under 200
- Tokens
- ~425
- read on every task
- Checks
- 1 of 11
- pass
- Fix
Looks like a connection string with a password
Instruction files are usually committed to the repo. Anthropic: don’t include API keys, credentials or database connection strings. Put the variable name (e.g. DATABASE_URL in .env) instead, and rotate any key that was ever committed.
Line 43 · Anthropic: Using CLAUDE.md files
- Fix
No build, test or lint command
Anthropic’s first item for the file: “the exact test, typecheck, and lint commands, and how to run a single test file”. GitHub found commands in an early section are what helpful files share.
- Improve
5 vague lines the agent can’t act on
Anthropic’s example: write “Use 2-space indentation” instead of “Format code properly”. GitHub: “Most agent files fail because they’re too vague.” Replace each with the exact rule or delete it.
Line 29, 35, 44, 59 · Claude Code docs: memory
- Improve
3 shouted lines (IMPORTANT, YOU MUST…)
Anthropic: current models “follow a plainly worded line, and piling on emphasis mostly makes Claude over-apply the rule.” If a rule must happen every time, make it a hook or a deny rule.
Line 36, 37, 38 · Claude Code docs: best practices
- Improve
A 13-line overview or structure section
ETH Zurich (2026) found repository overviews “are not helpful”, and Anthropic says the agent reads the repo itself. Keep only what the code hides: a misleading old folder, the one place new code must go.
Line 11 · ETH Zurich: Evaluating AGENTS.md (arXiv 2602.11988)
- Improve
5 formatting rules but no lint command
Anthropic: if the repo has a linter or formatter, “the single most useful line in your CLAUDE.md is the command that runs it.” Let the tool enforce style and list the command instead.
Line 30, 31, 32, 33 · Claude Code docs: best practices
- Improve
No clear limits
GitHub: “Set clear rules using always do, ask first, never do.” For example: never edit migrations by hand; ask first before adding a dependency.
- Improve
Rules both against and for “any”
Check the two lines agree. Anthropic: “if two rules contradict each other, Claude may pick one arbitrarily.” Keep one rule, or say plainly when each applies.
Line 37, 39 · Claude Code docs: memory
- Improve
An 8-step numbered list inside the file
Anthropic: “If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead.” It then loads only when needed.
Line 48 · Claude Code docs: memory
- Improve
1 repeated line
The same rule twice costs context twice and drifts apart when someone edits one copy.
Line 59 · Claude Code docs: best practices
- Good
60 lines: under the 200-line target
Short enough that every line can earn its place. Keep pruning as the project changes.
- Note
No code block
Optional. If a style rule needs explaining, one short real snippet usually says it better than a paragraph (GitHub’s finding).
Tokens are a rough count (about 4 characters each, OpenAI’s rule of thumb for English). Pattern checks can’t judge whether a rule is right for your project; they catch the common mistakes. Rules checked 21 Nov 2026.
Try it
Audit your own instruction file in 10 minutes
- 1Open your project’s CLAUDE.md or AGENTS.md. No file yet? In Claude Code type /init; in Codex or Cursor create AGENTS.md at the project root.
- 2Paste it into the checker above and fix every “Fix” item first (a key or password in the file means change that key).
- 3Delete any line the agent could learn by reading the code. Ask of each line: would the agent do something different without it?
- 4Add the one command that checks the work (tests + lint) near the top, and one “never” rule for the thing you most fear the agent touching.
- 5Start a fresh session and ask “what are the rules for this project?” In Claude Code, /memory shows which files loaded.
It checks what you understood, then gives you a small real task to try.
Read the prompt
Be my patient tutor. I just studied this lesson: "CLAUDE.md and AGENTS.md". Summary: CLAUDE.md and AGENTS.md are plain Markdown files in your project that a coding agent reads at the start of every session. Claude Code reads CLAUDE.md; Codex, Cursor, GitHub Copilot and many others read AGENTS.md, so write your rules once in AGENTS.md and add a one-line CLAUDE.md that imports it. Keep it short (Anthropic targets under 200 lines) and put in only what the agent cannot work out from the code: the exact test and lint commands, misleading places, team decisions and hard limits. Key terms: CLAUDE.md, AGENTS.md, /init, @import, Lint and typecheck, Hook. Do this, one step at a time, waiting for me each time: 1. Ask me to explain the main idea in my own words. Correct me kindly with one concrete example. 2. Ask 4 questions, easy to hard. After each answer, say what was right and what was missing. 3. Give me one small workflow I can try in 10 minutes that uses this idea in real work or study. Walk me through it step by step and check my result. 4. End with 3 lines: what I now know, what I should practise, what to learn next.
Check yourself
Pick an answer to see if you are right, and why.
Done? Keep going
Mark this lesson complete to keep your place. Progress is saved on this device, no login.
Questions people ask
What is the difference between CLAUDE.md and AGENTS.md?
They do the same job. CLAUDE.md is the file Claude Code reads; AGENTS.md is the open format read by Codex, Cursor, GitHub Copilot, Gemini CLI (with one setting) and others. If you use more than one tool, write the rules in AGENTS.md and put @AGENTS.md in CLAUDE.md, as Anthropic’s docs describe.
How long should CLAUDE.md be?
Anthropic targets under 200 lines per CLAUDE.md, because longer files use more context and reduce adherence. Cursor says keep rules under 500 lines, and Codex stops reading instruction files at 32 KiB by default. OpenAI’s own team kept its AGENTS.md to roughly 100 lines and pointed to deeper docs.
Should I use /init to write my CLAUDE.md?
Yes, as a draft. /init studies your project and writes a starting file. Then cut it: delete folder tours and anything the agent can read from the code, add your exact test and lint commands, and add the rules you have had to repeat.
Sources and further reading
- Claude Code docs: memory (CLAUDE.md, imports, AGENTS.md)
- Claude Code docs: best practices
- Anthropic: Using CLAUDE.md files (Nov 2025)
- AGENTS.md (agents.md)
- OpenAI Codex: custom instructions with AGENTS.md
- Cursor docs: rules
- GitHub docs: repository custom instructions for Copilot
- Gemini CLI docs: GEMINI.md
- Gloaguen et al. (ETH Zurich): Evaluating AGENTS.md, arXiv 2602.11988 (Feb 2026, rev. Sep 2026)
- Lulla et al.: On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, arXiv 2601.20404
- GitHub blog: How to write a great agents.md (Nov 2025)
- OpenAI: Harness engineering (Ryan Lopopolo, Feb 2026)
- InfoWorld: Claude Code now also accepts AGENTS.md (21 Sep 2026)
- OpenAI Help: what are tokens (4 characters rule of thumb)