How to Write a CLAUDE.md File: Pin What You Keep Explaining Twice

Chat-based AI tools let you save custom instructions ahead of time, so you don't have to re-explain them in every conversation. Claude Code has something similar: a CLAUDE.md file it reads automatically at the start of every session.

"Our client always wants reports written in this exact format." If you're retyping that sentence every time you open a new Claude Code session, that's the signal.

Last lesson sorted out what each of the five extension points replaces. Today you build the one that pays off first: an actual CLAUDE.md file. Just here for CLAUDE.md syntax? This lesson alone covers it. The file format itself doesn't change much, but the commands and settings screens around it can shift release to release, so cross-check the official docs if you're reading this well after today.

CLAUDE.md

CLAUDE.md is a markdown file holding instructions that apply to a project, to how you personally work, or to an entire organization. Claude Code reads the whole thing at the start of every session. Write down the rule you'd otherwise re-explain by hand each new session, and you never have to say it again.

Where CLAUDE.md lives: three spots

CLAUDE.md isn't a file with one home. It's confusing enough that "claude.md location" shows up as a top autocomplete query on its own. Out of everywhere the official docs list, here are the three spots an individual or small team actually uses.

What matters is that all three overlap. Per the official docs, these files don't override each other; they all get appended into context together. Start a session and the home CLAUDE.md loads first, followed by the project's. If the two disagree, Claude has to make a call, and it usually favors the more specific one, meaning whichever it read second: the project's. Worth remembering that this is judgment, not an enforced rule.

Let's use this lesson's running example, a monthly client content report, to walk through it. A personal habit like "I prefer plain statements over formal endings" goes in your home file. It follows you into every project you open. A rule specific to this one client, like "the first column of this report's table is always the publish date," goes in the project root. If it's a shared repo, commit it to version control so your teammates see it too. And if there's something you shouldn't commit at all, this client's login details, say, write it in ./CLAUDE.local.md and add it to .gitignore. It loads alongside the project's CLAUDE.md but stays visible only to you. (There's also an org-wide CLAUDE.md an IT department can push out, but that's a big-organization concern this lesson skips.)

What to write in CLAUDE.md: make it checkable

Building one is the fastest way to learn. Let's write the monthly client content report's format and notation rules into the project root's CLAUDE.md.

# Monthly Client Content Report Rules
 
## Format
- Report titles follow "{Client Name} {Month Year} Content Report"
- The table's first column is always the publish date (YYYY-MM-DD), second column is the channel name
- Don't abbreviate channel names: write "Instagram," not "IG"
 
## Notation
- Comma-separate numbers at the thousands place (12,345)
- Percentage changes get one decimal place plus a sign (+3.2%, -1.5%)
- Any sentence comparing to last month must cite the number it's based on, in parentheses

The official docs' advice is to write specifically enough that you can check whether Claude followed it. "Clean up the table" is weaker than "the first column is the publish date." "Make numbers readable" is weaker than "comma at the thousands place." You should be able to look and tell, at a glance, whether the rule got followed. Group things under markdown headers and lists, and Claude reads the structure the same way a person would.

If starting from a blank file feels daunting, try /init first. Claude Code scans your project's code, works out build commands, test steps, and folder structure, and drafts a CLAUDE.md for you. If a project already has one, it won't overwrite it; it'll suggest improvements instead. But /init can't fill in anything that isn't visible from the code itself: projects with no code at all, or report formats and notation rules like the ones above. That part you write by hand, the way the example does.

What to leave out of CLAUDE.md: length is cost

Length is cost, directly. The official docs explain that the entire contents of CLAUDE.md gets loaded into the context window at the start of every session, and rides along with every request after that. The longer the conversation runs, and the longer the file itself is, the more tokens you burn repeating the same thing over and over. That's why the official recommendation caps a single CLAUDE.md at 200 lines. Go past it and you're not just spending more context; the odds that Claude misses a rule that actually matters go up too.

I paid that cost myself without ever noticing. It started with not really looking over the CLAUDE.md that got auto-generated the first time, and just writing on top of it. Every so often Claude would drift from a rule it usually followed, and each time that happened I'd bolt on more emphasis and push the priority up a notch. A file that started at a handful of lines blew past 100 before I knew it, and I kept working with it in that state for a good while longer. I only learned later, once I actually studied this, that this wasn't the way to do it. What a rule needs when it starts drifting isn't more emphasis piled on top. It needs a cleanup.

So what should you cut? The test is: if you delete this line, does Claude actually make a mistake? If not, cut it. What the official docs flag as exclusions tend to be exactly what shows up in practice: anything Claude can work out on its own from the code or folder structure, information that changes often (this month's rate, this week's deadline), long explanations or tutorials, or a full API reference (link to it instead). In our scenario, "walk through the whole report-building process from start to finish" belongs in a skill, which the next lesson leads into, not in CLAUDE.md.

One more thing worth flagging from this scenario: a line like "this month's deadline is the 25th" is better left out of CLAUDE.md. It's wrong the moment next month starts, and nobody's coming back to fix the file every cycle. If a deadline changes every time, just tell Claude in the prompt that time, not in the file.

The style question, how to phrase what you write, has already come up once. The principle from the project instructions lesson, write the behavior you want instead of stacking up a long list of things not to do, applies here too. Adding one more "write it like this" tends to land better than another "don't write it like that."

One more thing you'll run into in practice: editing CLAUDE.md mid-session doesn't take effect in that same session. Claude Code reads the file once, at the start of the session, and holds onto it. Your edit only kicks in after /clear, /compact, or opening a fresh session. If you're wondering "I just fixed this, why isn't it working," this is usually why.

How is this different from AGENTS.md?

There's a reason "claude.md agents.md" shows up together in autocomplete. It's the confusion that comes from working in a repo shared with other coding agents besides Claude Code. The answer here is clean: the official docs state plainly that Claude Code reads CLAUDE.md, and CLAUDE.md alone. It does not read AGENTS.md.

If your repo already gives instructions to other agents through AGENTS.md, the official recommendation is to create a new CLAUDE.md that imports it. Put @AGENTS.md on its own line at the top of the file, and Claude Code pulls that content in at the start of every session. Add whatever's Claude-Code-specific below it.

@AGENTS.md
 
## Claude Code only
- Use Plan Mode for anything under src/billing/

If there's nothing extra to add for Claude Code specifically, a plain symlink works too: ln -s AGENTS.md CLAUDE.md (on Windows this needs admin rights, so use the @AGENTS.md import instead there). The choice is simple: if there's even one thing you need to tell Claude Code alone, import with @AGENTS.md. If there's truly nothing to add, the symlink is enough.

This blog's own repo is built exactly this way. The first few lines state that AGENTS.md is the source of truth, then @AGENTS.md pulls it in, followed by a list of skills registered for Claude Code specifically. The core rules, prohibitions, build commands, content structure, live in AGENTS.md alone, and Claude Code just borrows them. If other tools touch this repo too, like the Codex CLI covered in the CLI track, this structure means you never have to maintain two separate copies of the rules.

What automatic memory is: a record Claude keeps on its own

There's one more thing besides CLAUDE.md. Claude Code ships with automatic memory turned on by default. True to the name, you don't write it; Claude does. While working through a session, Claude decides on its own what's worth saving: corrections you made, decisions or progress that aren't visible from the code, where to find something you'll want later. It saves this as an index file called MEMORY.md plus topic files, inside a memory/ folder under a project-specific folder in ~/.claude/projects/, and the start of the index file (up to 200 lines or 25KB, whichever comes first) loads automatically at the start of every session. Open /memory to toggle it or browse what's accumulated. Default is on.

Does this split look familiar? It's the same structure from Track 1's lesson on memory and custom instructions, carried straight over into the terminal. What the web AI quietly saved as "memory" becomes automatic memory in the terminal; what you wrote by hand and pinned as "custom instructions" becomes CLAUDE.md. Only the names and the setting change; the roles stay the same.