Every Claude Code session starts with a fresh context window: what you told Claude last session isn't there. Anything you'd otherwise explain again each time goes in an instruction file: a plain Markdown file of standing instructions. Claude Code calls these CLAUDE.md files, and reads them at the start of every session.
The two you'll use
Your home folder: ~/.claude/CLAUDE.md. Your personal preferences for every project on your computer, like "explain changes in plain English". Only you see it.
The repo root: CLAUDE.md (or .claude/CLAUDE.md). Instructions for this project: how to run the tests, where the Issue tracker is, the coding rules. It's committed, so everyone working on the repo, people and agents alike, gets the same file.
There's also CLAUDE.local.md at the repo root, for your own notes on one project. Add it to .gitignore so it's never committed.
Which ones load
When you start Claude Code in a folder, it loads CLAUDE.md from that folder and from every folder above it, plus your home folder's file. Start it at the root of your FastAPI repo, and it reads ~/.claude/CLAUDE.md and the repo's CLAUDE.md.
A CLAUDE.md inside a subfolder, like app/migrations/CLAUDE.md, doesn't load at the start. It loads the first time Claude works on a file in that subfolder.
They add up
The files don't replace each other. They're all joined together, broadest first: your home folder's file, then the repo's. So the project's instructions come after yours.
Your home folder: ~/.claude/CLAUDE.mdevery project on your computer
The repo root: CLAUDE.mdInstructions for this project
app/migrations/CLAUDE.mdIt loads the first time Claude works on a file in that subfolder.
They're all joined together, broadest first
That means two files can disagree, and then Claude may follow either one. If your home file says "use pip" and the repo says "use uv", fix one of them.
AGENTS.md
Other coding agents read a file called AGENTS.md instead. By default, Claude reads a repo's AGENTS.md only when there's no CLAUDE.md in your folder or above it. If both exist, it reads CLAUDE.md.
Why the Skills care
setup-matt-pocock-skills writes an "Agent skills" block into the repo's CLAUDE.md, or into AGENTS.md if that's the file the repo already has. That block points every Skill at your settings in docs/agents/, which is how they find your Issue tracker (see keeping track).
To see which files loaded in a session, run /context and look under "Memory files".
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's guide, updated 18 January 2026, defines the file: "a markdown file you check into Git that customizes how AI coding agents behave in your repository". His warning in the same guide: a bad instruction file "can confuse your agent, become a maintenance nightmare, and cost you tokens on every request."
He names how it gets that way. The agent does something you don't like. You add a rule to prevent it. You repeat that hundreds of times over months, and the file becomes a "ball of mud".
His post updated 24 February 2026 adds the second problem: CLAUDE.md is global. "Every instruction applies to every session: frontend, backend, docs, database, all of it." His example: a React rule is useful for frontend sessions, "But the next session might be purely backend work where it's completely irrelevant." As he puts it, "Every line you add has a cost that compounds across every session, whether it's relevant or not."
From snapshot/docs/code.claude.com/memory.md, line 53: “The table below lists them in load order, from broadest scope to most specific, so a project instruction appears in context after a user instruction.”
Matt's February 2026 picture: frontend, API and docs sessions all carry the same context. From aihero.dev, 30 October 2026.
His answer to both problems: the ideal file "should be as small as possible."
How it works underneath
It's context, not a setting. Anthropic's docs say Claude treats these files "as context, not enforced configuration". Claude reads them "and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions." That's why the docs ask for instructions concrete enough to check, like "Run npm test before committing" instead of "Test your changes".
Every line costs, every session. Matt calls the limit an instruction budget: "a limit on how many instructions they can follow at once." The docs give a number to aim for: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Splitting a long file with @path imports doesn't help, because imported files "don't reduce its context cost".
Matt's February 2026 picture of an agent's context window, split into phases. From aihero.dev, 30 October 2026.
Where it sits. Matt's January guide put the file right below the system prompt, which matches the docs. His February post's table puts CLAUDE.md content in the system prompt phase. Anthropic's docs, taken 29 October 2026 and so newer, say it "is delivered as a user message after the system prompt, not as part of the system prompt itself." Either way it's loaded before your first message.
What research found. A paper first posted on 12 February 2026 (revised 29 September 2026) tested coding agents with and without these files. The authors found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average." Agents did follow the instructions well. What didn't help were "repository overviews". Their conclusion: the files "are useful for specifying non-standard coding practices". Matt links this paper as the evidence behind his advice.
Matt's bar. Put a line in only if it's both undiscoverable and globally relevant. A list of commands or the framework you use: the agent can find these by reading the repo. Steering for one kind of task belongs in a Skill, which "the agent can pull in when relevant".
A real example
Matt's own CLAUDE.md, as he showed it in February 2026, is one line:
you are on WSL on Windows
"Six words." It's there because WSL has path problems "that the agent can't discover on its own".
His Skills repo shows the other half. At the commit this Course pins, its AGENTS.md is a 9-byte symbolic link to CLAUDE.md, so both names point at one file. That's the setup his January guide suggested, when he wrote "Claude Code doesn't use AGENTS.md". That sentence is now out of date: Anthropic's docs say reading AGENTS.md directly "requires Claude Code v2.1.277 or later." Claude Code's issue #6235, opened on 21 August 2025, asked for AGENTS.md support. A comment there on 18 September 2026 quotes a post announcing it: "Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md."
Where it goes wrong
Rules that get ignored. Issue #19471, opened on 20 January 2026, reports that after the conversation was compacted, "CLAUDE.md is completely ignored without warning." Another user commented on 28 April 2026 that rules were broken in a session with "zero compactions". A bot closed the issue as not planned on 16 June 2026. Anthropic's current docs say the project-root CLAUDE.md "survives compaction": Claude "re-reads it from disk". What gets lost is anything said only in conversation, or a subfolder's file that hasn't loaded again yet. To block an action whatever Claude decides, the docs say to use a hook instead. A hook runs as a shell command at a fixed point, "regardless of what Claude decides to do."
Stale facts. Matt warns that "stale information actively poisons the context". File paths are the worst case: if a file named in your instruction file "gets renamed or moved, the agent will confidently look in the wrong place."
A personal file that switches off the shared one.CLAUDE.local.md counts as a CLAUDE.md. The docs warn that adding one "in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you."
/init, where the sources disagree. Anthropic's docs, the newer source, still suggest running /init "to generate a starting CLAUDE.md automatically." Matt's February post says "Never run init": what it writes "is either trivially discoverable from source or will go stale." The docs add: "Refine from there with instructions Claude wouldn't discover on its own." Matt goes further: "If you find one that was auto-generated, delete it."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't):
Start Claude Code at the repo root and run /context. Note which files are listed under "Memory files".
Write a root CLAUDE.md with only the lines you can't leave out. For each one, ask: could the agent find this by reading the repo? Does it matter for both api/ and web/? If either answer is no, delete it.
Create web/CLAUDE.md from your shell, not by asking Claude, with one rule that only matters to the TypeScript website. Then ask Claude to read a file in web/, and watch for the "Loaded" line with that file's path.
From snapshot/docs/code.claude.com/memory.md, line 86: “Imports help you organize a long file but don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them.”
From snapshot/web/arxiv.org/abs-2602-11988.md, line 30: “Surprisingly, we find that providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average.”
From snapshot/web/arxiv.org/abs-2602-11988.md, line 30: “Specifically, we find that while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful.”
From snapshot/docs/code.claude.com/memory.md, line 380: “Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you.”
From snapshot/docs/code.claude.com/memory.md, line 585: “When it loads, a Loaded line with its path appears in the terminal. To test a new one, create it from your shell rather than asking Claude to write it, then ask Claude to read a file in that subdirectory.”
