CLAUDE.md, With the Real File I Run Every Day

A CLAUDE.md file is a plain markdown file that Claude Code reads at the start of every session, so it already knows your rules, your layout and your habits before you type a word. You write it once, in normal sentences, and it saves you re-explaining the same things. It's context, not a lock: Claude tries to follow it, and nothing forces it to.

Mine is 205 lines long and it changes often. Below is what the official docs say about it, then the real file, section by section, with the parts worth copying.

What is a CLAUDE.md file?

Each Claude Code session starts with a blank context window. Anthropic's memory page names two things that carry knowledge across sessions: CLAUDE.md files, which you write, and auto memory, which Claude writes about itself. Both load at the start of every conversation.

The docs are plain about what a CLAUDE.md is. Claude treats it "as context, not enforced configuration." The file is delivered as a user message after the system prompt, and there is no guarantee of strict compliance, especially for vague or conflicting lines. If something has to happen every time, the same page says to use a hook instead, because hooks run as shell commands whatever Claude decides.

That distinction shapes how the file should be written. A CLAUDE.md is where I write down what I'd otherwise type into chat again next week.

Where does a CLAUDE.md file go?

There are four places, and they stack rather than override each other. Claude Code reads the files from your working folder and every folder above it, concatenates them, and puts the closest one last.

Source: the memory page, checked 28 October 2026. A CLAUDE.md inside a subfolder loads later, only when Claude reads or edits a file in that subfolder. The project-root file survives /compact, because Claude re-reads it from disk afterwards. To see what actually loaded, run /context and look under Memory files.

Mine is one file at the project root. I don't have a user-level file or any nested ones. That works because it's one workspace with one job.

How is CLAUDE.md different from skills and auto memory?

CLAUDE.md is always loaded, so everything in it costs context in every session. A skill is the opposite: only its short description sits in context, and the full body loads when the skill runs. Anthropic's skills page says to create a skill when "a section of CLAUDE.md has grown into a procedure rather than a fact." My rule of thumb follows from that: facts and rules go in CLAUDE.md, procedures go in a skill. I wrote up the skill side in the Claude Skills guide.

Auto memory is the third thing, and the one people mix up with the file. It's notes Claude writes for itself from your corrections, stored per project in ~/.claude/projects/<project>/memory/. The MEMORY.md index in that folder is "one line per memory," and the first 200 lines or 25KB of it load every session. The topic files behind it are read only when needed.

I keep all three. The figure below is the real inventory on my machine on 28 October.

It's the same idea as the business memory I described in the second brain behind my AI agent, just pointed at one Claude Code workspace. And the chat-app cousin of all this is the Instructions box I covered in five Claude settings worth pressing.

What does a real CLAUDE.md look like?

Mine runs 205 lines, 3,677 words and about 24KB across 15 sections. Git shows 27 commits touching it, though many of those are an automatic nightly sync rather than hand edits. Anthropic's guidance is to target under 200 lines per file, because longer files use more context and reduce adherence. Mine is five lines over, and the lines are long.

The figure shows the real section sizes, with three of them marked in red. I've renamed a few headings to keep private business detail out of it, and the counts are exact.

The largest section is model routing at 34 lines. The smallest is decision wiring at 4.

Which parts of my CLAUDE.md earn their place?

Six patterns do most of the work. Each excerpt below is copied from the real file, shortened, with my name swapped for "me" and anything private removed.

1. A rule for what to do when it doesn't know.

**Assumptions are the enemy.** If the answer isn't in these docs,
ask me. Don't infer it and don't invent a plausible number.
If a doc contradicts what you observe on disk, disk wins; then
fix the doc (or flag it) in the same session.

That's the whole defence against a model filling a gap with something confident. The reasoning behind it is in why AI makes things up. Writing "disk wins" settles which source to trust when two disagree.

2. One home for every fact that changes.

Facts that change get exactly ONE home. Everywhere else points
at it, never a copy. Copies are how this workspace drifted: a
skill count lived in 4 docs and all 4 were wrong.

| Fact                               | Only home                        |
|------------------------------------|----------------------------------|
| Model routing, effort, plan limits | this file, "Token discipline..." |
| Skill roster + total               | .claude/skills/README.md         |
| Phase status, blockers             | BUILD-SEQUENCE.md                |
| Open decisions, doc flags          | wiring-queue.md                  |

A rule in prose rots, so there's also a script for it. scripts/drift-check.cjs is about 700 lines of plain Node. It runs a set of checks against the disk: whether a stated skill count matches the folders, whether a doc's date is far behind its last git edit, whether a retired name is still in use. It runs nightly through my sync job. On 28 October it reported 0 FAIL and 35 WARN, so it's far from clean, but that list is exactly what I'd otherwise never see.

3. A table that says where files go.

| File about                  | Goes to                            |
|-----------------------------|------------------------------------|
| Skill                       | .claude/skills/{name}/             |
| On-demand script            | scripts/                           |
| Audit / research one-off    | audits/{yyyy-mm-dd}-{topic}.md     |
| Transient / regenerable     | .tmp/                              |

If you can't place a file, the file is mis-named. Rename to
clarify its job.

My full table has 18 rows. It's there so Claude doesn't invent a new folder every time it makes something.

4. A short block of hard rules.

## High-friction rules (YOU MUST)
- IMPORTANT: Never commit `.env`, real API keys, or credentials.
  Check `.gitignore` first.
- IMPORTANT: Skills are built via Anthropic's `skill-creator`
  ONLY. Hand-rolled SKILL.md is rejected.
- Every folder has a README.md (3 sections, <=30 lines).
- No spaces in filenames. Atomic commits. Never `git push --force`
  to main.

The capitals are deliberate. I save them for a few lines. Some rules in that block are also enforced by a hook, a small script that refuses a command before it runs. The comment at the top of one of them says it plainly: "Prose told them not to; this refuses." It was added after sub-agents made paid calls nobody had counted. That's the official advice in practice: write the rule down, then enforce the one that can't be allowed to slip.

5. The workflow, as a ritual.

1. I think and plan. Alone, voice notes, walks. I own judgment,
   priority and thinking.
2. I dictate the procedure, the reasoning and the steps to Claude.
3. Claude writes the skill in .claude/skills/{name}/.
4. Future agents activate the skill when its trigger
   description matches the request.

It tells Claude what its job is and what mine is.

6. Wiring a decision, so it isn't just remembered.

When I approve a behaviour, wire it into the relevant agent,
skill or spec IN THE SAME SESSION. Memory alone is not wiring.
If you can't wire now, add a one-line entry to wiring-queue.md
and start the next session by checking it.

Auto memory will happily remember a preference. It won't make the next skill obey it. This line is why my decisions end up in files instead of a pile of notes.

How long should a CLAUDE.md be, and what are the best practices?

Anthropic's page gives four. Aim for under 200 lines. Make each line concrete enough to verify: "Use 2-space indentation" beats "format code properly". Group lines under headers and bullets. And remove contradictions, because if two lines disagree Claude may pick either.

Two more from the same page are worth knowing. Block-level HTML comments in the file are stripped before it reaches Claude, so you can leave notes to yourself for free. The file can pull in others with an @path/to/file import, up to four hops deep, but the docs are clear that imports organise a long file without shrinking its cost, because the imported text loads too.

The page also gives a test for adding a line: add it when Claude makes the same mistake a second time, or when you type the same correction you typed last session. For a check on what's already there, the docs describe /doctor prompt-audit, which looks for outdated or conflicting lines and proposes edits without changing anything.

CLAUDE.md or AGENTS.md: which one does Claude Code read?

Claude Code reads CLAUDE.md. AGENTS.md is the same idea under a different name: agents.md describes it as "a README for agents," stewarded by the Agentic AI Foundation under the Linux Foundation, with OpenAI's Codex among the tools that read it.

Claude Code now reads AGENTS.md too, but only when there's no CLAUDE.md in your working folder or above it. With both present, it reads CLAUDE.md alone. To share one set of rules, the docs suggest a CLAUDE.md that starts with @AGENTS.md, and they say a symlink works too, so the content is read once.

I took the symlink route. My AGENTS.md is a link to CLAUDE.md, so there's one file with two names and nothing to keep in sync. One section of the file is written for Codex or any other agent that ends up editing my reels.

What is the Karpathy CLAUDE.md?

It's a single CLAUDE.md file on GitHub, published under the multica-ai account as andrej-karpathy-skills, with 225.3k stars on 28 October. Its README says it's derived from Andrej Karpathy's public observations about where language models go wrong when they write code. It isn't his file.

It boils down to four principles, which the README states as taglines: Think Before Coding ("Don't assume. Don't hide confusion. Surface tradeoffs."), Simplicity First, Surgical Changes, and Goal-Driven Execution ("Define success criteria. Loop until verified."). There are no project details in it, so you can drop it into any repo.

It isn't one of the files in my workspace, and it's a different kind of file from mine: it governs how Claude codes, where mine governs how one workspace is run. Karpathy does sit behind the memory idea in my own setup, as I wrote in the second brain post.

How do you start a CLAUDE.md file?

Run /init inside a project. Claude reads the codebase and drafts a starting file with the build commands and conventions it finds, and if one already exists it suggests improvements instead of overwriting it. Then cut whatever Claude could work out itself and add what it couldn't.

If you'd rather start by hand, this is the skeleton of mine with the content swapped for placeholders.

# Project name: instructions
One line on what this project is. Loaded every session.

## Rules that never bend
- Never commit secrets. Check .gitignore first.
- If you don't know, ask. Don't invent a number.

## Where things go
| File about | Goes to |
|------------|---------|

## Facts with one home
| Fact | Only home |
|------|-----------|

## How we work
1. ...

Keep it short enough to read in one sitting. If you've never used Claude Code, start here first.

Key takeaways

• A CLAUDE.md is a markdown file Claude Code loads at the start of every session. It's context, not enforcement, so use a hook for anything that must never be skipped.
• It can live at the project root, in ~/.claude/CLAUDE.md, in a local file, or in a subfolder that loads on demand. Anthropic's target is under 200 lines.
• Facts and rules belong in CLAUDE.md. Procedures belong in a skill, which loads only when it runs.
• Claude Code reads AGENTS.md only when no CLAUDE.md exists, so a symlink or an @AGENTS.md import keeps one set of rules for every agent.
• Mine is 205 lines and 15 sections. The patterns I'd keep are "disk wins", one home per fact, a where-files-go table, a short hard-rules block and "memory alone is not wiring".

FAQ

What is a CLAUDE.md file in Claude Code?

A CLAUDE.md file is a markdown file of instructions that Claude Code loads at the start of every session. It holds the rules, layout and habits you'd otherwise re-explain. Anthropic's docs call it context, not enforced configuration, so Claude tries to follow it but nothing guarantees it will.

Where should I put my CLAUDE.md file?

Put it at the project root as ./CLAUDE.md or in ./.claude/CLAUDE.md for rules the whole project shares. Use ~/.claude/CLAUDE.md for personal preferences across every project, and ./CLAUDE.local.md for private notes on one project, added to .gitignore. Files in subfolders load only when Claude works in them.

How long should a CLAUDE.md file be?

Under 200 lines is Anthropic's target per file, because longer files use more context and can reduce how well Claude follows them. Mine is 205 lines, five over. Move anything that matters for only one part of the project into a skill or a path-scoped rule.

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is the file Claude Code reads, and AGENTS.md is the open filename other coding agents such as Codex read. Claude Code reads AGENTS.md only if no CLAUDE.md exists. To keep one set of rules, import it with @AGENTS.md inside CLAUDE.md or make one file a symlink to the other.

What is the difference between CLAUDE.md and Claude Code memory?

CLAUDE.md is instructions you write, while auto memory is notes Claude writes about your corrections and preferences. Both load every session, but only the first 200 lines or 25KB of the MEMORY.md index do, with its topic files read on demand. Use CLAUDE.md for rules and memory for what Claude learns.