What is CLAUDE.md?

In An agent in a folder we said that if you do only one thing, ask for a CLAUDE.md at the root of the folder. The question that follows in our bootcamps is what to put in it, and how much. This guide answers both.

What the file does

Each Claude Code session starts fresh, without what you told it in the last one. Anything Claude should know about your work, and cannot see by reading the folder, belongs in CLAUDE.md.

Think of it as the note you would leave a capable colleague on their first morning.

Where the file lives

There can be more than one CLAUDE.md, and Claude Code reads them all (Anthropic, How Claude remembers your project).

The project file at the root of the folder is the one the team shares, and the one this guide is mostly about. Your own file in ~/.claude/ holds preferences for every project, and IT can place an organisation file on every machine.

A CLAUDE.md in a subfolder is read when Claude works in that folder. Personal notes about one project go in CLAUDE.local.md. It is meant for you alone, so ask Claude to keep it out of the files the team shares.

In the Claude desktop app, the Code tab reads the same files. When you work in a local folder in Claude Cowork, Claude also reads a CLAUDE.md there, and the folder instructions in Customize do the same job.

What to put in it

Here is a CLAUDE.md for a folder where Claude helps produce a monthly report to an investment committee.

Write each line so it can be checked. "Percentages to one decimal" can be checked, while "Keep the numbers tidy" cannot. You do not have to write the file yourself. /init writes a quick first draft, and this prompt gives you our five headings.

YouCopy

Write a CLAUDE.md for this folder with five headings, what the folder is for, sources, conventions, checks and limits, and where things are. Ask me about anything you cannot see in the files.

How long it should be

Anthropic recommends keeping each CLAUDE.md under 200 lines. A longer file fills more of what Claude can keep in view during a session, and Claude follows it less reliably. When Claude keeps ignoring a rule, a long file is often the reason, and adding IMPORTANT or capital letters rarely helps.

The best way to improve the file is to ask Claude to do it. Claude can compare the file with the folder and point out what is unclear, out of date or contradictory, and what it could work out from the files.

YouCopy

Check whether CLAUDE.md is set up as well as it can be for what we work on in this folder.

Read the suggestions before you accept them. A line Claude wants to cut may be one only you know is true.

Point to the details in other files

CLAUDE.md does not have to hold everything. It can work as a map, with one line for each longer instruction kept elsewhere in the folder, saying when to read it.

A line can also point to a script, a small program Claude runs to check its own work, such as confirming that the tables add up. A script gives the same answer every time, as Deterministic and non-deterministic AI explains.

Put @ in front of a file name, as in @docs/report-style.md, and Claude reads that document in every session, so it counts towards the length. Without the @, the file stays out of the session until Claude reads it for a task.

Our own file for this website grew too long before we learned this. Now it holds a few hard rules and a table of where everything else lives.

YouCopy

Move the detailed instructions in CLAUDE.md into separate files. Leave one line in CLAUDE.md for each, saying when to read it.

CLAUDE.md, memory, skills and hooks

CLAUDE.md is one of four places where Claude Code keeps what it should know.

Auto memory is what Claude notes for itself, on your machine only. When you say "remember that I prefer tables to bullet points", the note goes there. When you say "add this to CLAUDE.md", it goes in the file the team shares.

Skills hold procedures that only matter for some tasks, such as the quarterly version of the report. A hook is a check that runs every time, whether or not Claude remembers the rule. You can ask Claude Code to write one for you.

YouCopy

Write a hook that blocks edits to the data/exports folder.

CLAUDE.md and AGENTS.md

Other AI coding tools, such as OpenAI's Codex, Cursor and most of GitHub Copilot's agent features, read their instructions from a file called AGENTS.md. If your team uses more than one tool, write the shared instructions once, in AGENTS.md.

Add the line @AGENTS.md to CLAUDE.md, and Claude Code reads the shared file too. Anything that only concerns Claude goes below that line. If a folder has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md, Claude Code reads the AGENTS.md on its own.

What changed with Opus 5.5

Some CLAUDE.md advice written for older models no longer holds. In Getting the most out of Opus 5.5, written by Addy Osmani and published by Anthropic, three of the tips apply to CLAUDE.md.

Opus 5.5 always thinks before it replies and chooses how deeply, so lines that ask it to think can go. On a long task it sometimes stops to report instead of carrying on. Tell it when to stop and how the summary at the end should look.

YouCopy

Add a rule to CLAUDE.md. When a step does not need me, keep going. Stop and ask only when you cannot continue without me, or before you delete or overwrite anything.

We go through the whole guide in Anthropic's tips for working with Claude Opus 5.5.

How the file improves over time

Anthropic's rule of thumb is to add a line when Claude makes the same mistake twice, or when you type a correction you typed last session.

The first lines are simple. In January you remind Claude that returns are net of fees, in February that numbers come from the fund system, not email, and in March that Fund C has moved to the EUR share class.

The later lines are about how you think. In April you ask Claude to open with what changed and why, and in May to use the holdings to explain any gap of more than two percentage points to the benchmark. By June the draft needs few corrections.

Share the file through git, so one person's correction helps the whole team, and date each decision so a later reader can see which rule is newer.

This is what we mean by AI capital, knowledge a team writes down once and keeps using.

Where to start

Open a folder you already work in and type /init in Claude Code. It writes a first draft, or suggests improvements if the file already exists.

Then add the two or three things you find yourself repeating.

Then end each working session with this prompt, and read the lines it adds, because a wrong line repeats itself in every session.

YouCopy

Add what we learned today to CLAUDE.md.

When one part of the file turns into a procedure, move it into a skill, as described in Claude skills for you, your team and the company.