# What is a CLAUDE.md file and what goes in it?

> A CLAUDE.md file is the memory file Claude Code reads at the start of every session. What belongs in it, what to leave out, and the one rule for when to add a line.

By Matt Burns, BeingAINative. Canonical: https://beingainative.com/answers/what-is-a-claude-md-file  
Published: 2026-08-16

## The short answer

A CLAUDE.md file is a plain markdown file sitting in the root of your project that Claude Code reads at the start of every single session. Why does it exist? Because every session starts with an empty head. Without the file, you're re-explaining your project every morning like the movie Groundhog Day.

What goes in it is the stuff you'd otherwise type twice: how to run the thing, where files live, what you always want, what you never want.

Run /init in a fresh project and Claude will write a first draft for you by reading your codebase. Anthropic's guidance says keep the whole file under about 200 lines, because longer files get followed less consistently.

Here's the fastest way I can explain this file: it's the difference between a coworker with a memory and a very smart stranger who shows up new every morning.

## When do you actually add a line?

Anthropic's own guidance nails the trigger, and I follow it: add to CLAUDE.md when Claude makes the same mistake a second time, or when you catch yourself typing the same correction you typed last session ([memory docs](https://code.claude.com/docs/en/memory)).

Not before. This matters.

A file you write in advance out of imagination is mostly guesses, and every guess costs context on every session for the rest of the project's life.

![One CLAUDE.md sheet feeds three terminal windows, and every terminal opens with the file's lines already at the top of its screen above the prompt.](https://beingainative.com/_astro/claude-md-in-out.Cv0rDsBK.svg)

My test for whether a line belongs: could you check it yourself in five seconds? "Run npm test before committing" passes. "Test your changes" sounds like an instruction, but it functions as a mood.

## What does a good one look like?

Let's make it concrete:

```markdown
# CLAUDE.md

## Commands
- `npm run dev` starts the local site at localhost:4321
- `npm run build` runs the checks before anything ships

## House rules
- All colors come from src/styles/tokens.css, never hardcoded
- Ask before installing a new dependency
```

Short, checkable, specific to this project. That's the whole recipe.

Anthropic's guidance is to keep the whole file under about 200 lines, because longer files get followed less consistently ([memory docs](https://code.claude.com/docs/en/memory#write-effective-instructions)).

And if you have rules that only apply to some files, those can move into `.claude/rules/` with a `paths` frontmatter ([path-scoped rules](https://code.claude.com/docs/en/memory#path-specific-rules)), so they only load when Claude actually touches matching files. Context is money. Spend it on purpose.

## Does this work outside of code?

Yes, and this is the part most explainers skip entirely.

Claude Code runs in any folder. Any folder. So a CLAUDE.md works for your newsletter drafts, your client notes, or your brand guidelines exactly the way it works for a codebase. Mine carries writing rules, not compiler flags: banned words, voice notes, the works.

![Two folders hold different papers, one with code files like app.ts and one with drafts like draft.md, and the same bright CLAUDE.md sheet stands at the front of both.](https://beingainative.com/_astro/claude-md-any-folder.D-ZCPo-B.svg)

If you're setting up Claude Code from scratch, this file is one piece of a twenty-minute setup, and the wider walkthrough lives in the [writing section](/writing). Every major coding agent has grown its own version of this memory file too, and I compare how [Codex, Claude Code, and Cursor](/guides/codex-vs-claude-code-vs-cursor) each handle theirs.