Lesson 40 of 44 · Track 4: Automate and code with AI

CLAUDE.md and AGENTS.md: how to write instruction files for AI coding agents

Beginner14 min6 steps2 videosFree · no login
The short answer

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.

Start a free mock interviewOut loud, with a voice interviewer · by Tough Tongue AI
  1. 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.

    1. Session starts
    2. Agent reads instruction files
    3. You give a task
    4. Agent works with your rules in mind
    5. It runs your test command to check
    Key idea

    Every line is read on every task, so each line should change what the agent does.

  2. 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 2026
    Three of five tools read AGENTS.md as is; Gemini CLI needs a setting, Claude Code an import
    ToolMain fileAGENTS.mdRules for one folder
    Claude CodeCLAUDE.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 CodexAGENTS.md (also ~/.codex/AGENTS.md, AGENTS.override.md)Yes, nativelyAn AGENTS.md in the subfolder
    Cursor.cursor/rules/*.mdc, or AGENTS.mdYes, root and subfoldersA 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 CLIGEMINI.md (also ~/.gemini/GEMINI.md)If you set context.fileName to AGENTS.mdA 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. 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–2026
    Rules the agent can’t guess help; long overviews mostly add cost
    StudyWhat they testedWhat they found
    ETH Zurich, arXiv 2602.11988 (Feb 2026, rev. Sep 2026)Coding agents with and without context files, both LLM-written and developer-writtenNo 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.mdMedian 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 commonCommands 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 idea

    Write down what is non-standard about your project. Skip what the agent can read for itself.

  4. 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 idea

    Shouting does not help: Anthropic says piling on IMPORTANT “mostly makes Claude over-apply the rule”.

  5. 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 workflow

    Worked workflow: cleaning up jobtrack’s instruction file

    Input

    A 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.

    1. 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.

    2. 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.ts
    3. Remove 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.

    4. 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.

    5. 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.

    6. 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.

    Output

    A 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. 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 rules
    Key idea

    Root file for what is true everywhere; a small file in a folder for what is true only there.

From the people who built it

Straight from the source

The original idea, then the same idea taken apart, then how you use it today.

Ryan Lopopolo, OpenAI
Engineer on the OpenAI team that built a product with Codex writing the code
Harness engineering: leveraging Codex in an agent-first world (Feb 2026)
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.
Thibaud Gloaguen, Martin Vechev and team, ETH Zurich
Researchers who measured whether context files help coding agents
Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv, 2026)
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.
7 terms

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.
2 videos · plays here

Watch

Hand-picked from the people who explain this best. The video loads only when you press play.

How I Write My AGENTS.md Files - Best Practices
NeuralNine

A practitioner builds a real AGENTS.md section by section. Compare his file with the checklist in step 4.

Delete your CLAUDE.md (and your AGENT.md too)
Theo - t3․gg

A strong opinion on the 2026 research in step 3. Watch it after the lesson and decide where you agree.

Checker · 14 checks from Anthropic, OpenAI, Cursor, GitHub and ETH Zurich · 21 Nov 2026 · no AI

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.

    Claude Code docs: best practices

  • 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.

    GitHub blog: lessons from 2,500 agents.md files

  • 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.

    Claude Code docs: memory

  • 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).

    GitHub blog: lessons from 2,500 agents.md files

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.

Hands-on · 10 minutes or less

Try it

Audit your own instruction file in 10 minutes

  1. 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.
  2. 2Paste it into the checker above and fix every “Fix” item first (a key or password in the file means change that key).
  3. 3Delete any line the agent could learn by reading the code. Ask of each line: would the agent do something different without it?
  4. 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.
  5. 5Start a fresh session and ask “what are the rules for this project?” In Claude Code, /memory shows which files loaded.
Claude Code docs: memory and CLAUDE.md
Practise this lesson with an AI tutor

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.
3 questions · instant feedback

Check yourself

Pick an answer to see if you are right, and why.

Question 1

Question 1 of 3

Your team uses Claude Code and Cursor. What is the simplest setup?

Question 2

Question 2 of 3

Which line is most worth keeping in an instruction file?

Question 3

Question 3 of 3

Claude keeps ignoring a rule that must happen every time. What does Anthropic suggest?

Lesson 40 of 44

Done? Keep going

Mark this lesson complete to keep your place. Progress is saved on this device, no login.

Up next · Lesson 41 · 12 minPrompting vs RAG vs fine-tuningStart with prompting, always. Add RAG (retrieval-augmented generation) when the model is missing knowledge, such as your private documents or facts that change often. Use fine-tuning only when the model is missing behaviour, like a strict format or style, that good prompts and examples cannot fix. Let a small test set decide, not hype.← Previous: Claude Code vs Cursor vs Codex
People also ask

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.

14 sources · checked Nov 2026

Sources and further reading

Free to start · runs in your browser · by Tough Tongue AI

Going for an AI role? Practise the interview.

Talk to an AI interviewer about what you just learned and get feedback on every answer.

  1. Pick a round

    PM case, consulting case, AI engineer round or a speaking coach

  2. Answer out loud

    The interviewer follows up on what you actually said

  3. Read the feedback, go again

    What was strong, what was thin, then a retry

Start a free mock interviewOut loud, with a voice interviewer · by Tough Tongue AI