Fundamentals

The Three Tiers of CLAUDE.md

Set up the files Claude reads before every prompt, and get the smartest model to write yours

The Idea

Every time you send a prompt, Claude reads your CLAUDE.md files before it does anything — they're its standing orders. If what's in them is good, they quietly sharpen everything Claude does. If they're messy or bloated, they quietly make everything worse.

Most people know about one CLAUDE.md, in the project root. There are actually three tiers, and the difference between them is just reach: how much of your work each one applies to. The test for where a rule goes: is it true for everything you build? Computer level. True for this project? Project level. True for one corner of it? Folder level.

And here's why this matters more than any individual session: models come and go — you're renting them. These files are yours. Whatever the smartest model writes into them, every future session follows, whichever model it's running on.

The Three Tiers

Computer level

~/.claude/CLAUDE.md

Every project you ever open — read at the start of every session, everywhere.

What belongs here

→How you like to work — plain English first, ask before assuming, push back
→Your personal defaults: package manager, language preferences
→Workflow rules you want everywhere: “run the tests before saying done”

What doesn't: Anything about one specific project — that belongs a tier down.

Starter template — computer level

# How I work - Explain what you're about to do in plain English before you do it. - If my request is ambiguous, state your assumptions and ask before writing code. - Push back when I'm wrong. Never agree just to be agreeable. # My defaults - Package manager: [pnpm / npm / yarn — pick yours] - [Language preferences, e.g. "TypeScript over JavaScript, always"] - Read the existing code before editing it. - If you're not sure something exists — a package, an API, a setting — check or say so. Never fill the gap with something that looks right. - Raise errors explicitly — never swallow them or add fallbacks I didn't ask for. - Keep changes minimal: nothing I didn't ask for, no "improvements" on the way past. # Before you say "done" - Run the project's tests or build if it has them. - Never tell me something works unless you've actually run it. "It should work" is not "it works". - Tell me what you changed, and anything you're not sure about.

Project level

your-project/CLAUDE.md

Everyone and every session in this project — read at the start of every session in this project; shared with your team via git.

What belongs here

→What the project is, the stack, and the commands that run it
→Where things live and the conventions that aren't obvious from the code
→The don'ts: files never to touch, things never to commit

What doesn't: Your personal taste — keep the team file about the project, not about you.

Starter template — project level

# What this project is [One or two sentences: what it does, who it's for.] # Stack - [Framework, language, database, hosting — e.g. Next.js, TypeScript, Supabase, Vercel] # Commands - Run locally: [npm run dev] - Test: [npm test] - Build: [npm run build] # Rules for this repo - [Where things live: "API routes in app/api/", "components in components/"] - [Conventions: naming, the styling system, how errors are handled] - [The don'ts: "never commit .env.local", "don't touch the generated/ folder"] - Secrets stay in env vars — never write a real key into any file. # Gotchas - [Anything Claude keeps getting wrong, or genuinely can't guess from the code]

Folder level

any-folder/CLAUDE.md

Just that corner of the project — only loaded when Claude actually works with files in that folder — costs nothing until then.

What belongs here

→Rules that are true in this folder and nowhere else
→“This is generated, edit the source instead” / “this folder is customer-facing copy”

What doesn't: General project rules — if it's true outside this folder, move it up a tier.

Starter template — folder level

# This folder [What lives here and what it's for.] # Rules that only apply here - [e.g. "Everything in here is customer-facing copy — plain English, no jargon"] - [e.g. "These files are generated — edit the templates in /templates instead"]

Then Make Them Yours

The templates are deliberately generic — the brackets are the point, and none of this needs doing by hand. Open Claude Code in your project and paste this: it fetches the templates, puts each file where it lives, and fills in the brackets by reading your project and asking you whatever it can't infer.

The set-up prompt — one paste does all of it

Please set up my CLAUDE.md files from this repo: https://github.com/oliwoodman/claude-md-templates Grab the three templates (computer, project, folder). Put the computer one at ~/.claude/CLAUDE.md and the project one at this project's root. If I already have a file in either place, merge — don't overwrite. Fill in the bracketed placeholders by looking through this project and asking me questions where you can't infer the answer. Skip the folder template unless a subfolder of this project genuinely needs its own rules. Then show me what you set up.

Prefer to place the files yourself? Copy each template above to the path on its card, then hand Claude this to tailor them to how you actually work:

The refine prompt

I've just added CLAUDE.md template files (computer level and project level, maybe a folder one too). Make them mine: 1. Read them, then read this project: the code, the structure, the README. 2. Fill in every bracketed placeholder from what you find. Where you can't infer the answer, ask me — one question at a time. 3. Cut any line that doesn't match how I actually work, and add the gotchas you can see in this project that the templates miss. 4. Keep every rule at the right tier — computer level for things true everywhere, project level for this build, folder level only if a subfolder genuinely needs its own rules. Never repeat a rule across tiers. Show me the final files before saving them, with a short note on what you changed and why.

The Power Move: Don't Write Them Yourself

The templates above are good starting points. But the real play is getting the smartest model you have access to, to write yours — it digs through your project, asks you how you work, and writes all three tiers itself. You can't keep the model, but you can keep its way of thinking: the standards it sets and how it breaks things down, written into the files every future session follows.

As I write this, that model is Fable — included on the standard plans until 7 July 2026. If you're inside that window, this is the best thing you can spend it on; if you've missed it, the play doesn't change — use the strongest model you can reach. (More ways to spend the window: the Fable list.)

That's how this page itself was made: Fable wrote the templates and the prompts on it, checked against Anthropic's own guidance on these files. The model leaves; what it wrote down stays.

Open Claude Code in your project (or a chat with the project connected) and paste this — it replaces the templates, so you don't need them in place first:

The distill prompt

I want you to write my CLAUDE.md files — the standing instructions every future session will follow. 1. First, look through this project: the code, the structure, the README, and any existing CLAUDE.md files. 2. Then interview me: ask up to 8 questions, one at a time, about how I like to work, what keeps going wrong, how technical I am, and anything you can't infer from the code. 3. Then write three files: - ~/.claude/CLAUDE.md (computer level): only things true for every project I'll ever work on. - CLAUDE.md at this project's root: only things specific to this project — what it is, stack, commands, structure, conventions, gotchas. - If any subfolder genuinely has different rules, a short CLAUDE.md for that folder. Rules for writing them: be specific, never vague ("use 2-space indentation", not "format code properly"). Keep each file well under 200 lines — shorter is better. Include only instructions I'd otherwise have to keep repeating — nothing you can infer from the code itself. Never repeat a rule across two tiers. Where a rule isn't self-evident, add its one-line reason. Every line has to earn its place. Show me each file before saving it, and tell me what you deliberately left out and why.

The Rules That Make These Files Work

Specific beats vague, every time

Format code properly→Use 2-space indentation

"Use 2-space indentation" gets followed. "Format code properly" gets ignored. "Run npm test before committing" gets followed. "Test your changes" gets ignored. If a rule could mean two things, it's not a rule yet. And when a rule isn't self-evident, give it its one-line why — a rule with a reason gets applied to situations you didn't think of; a bare rule gets applied literally.

Short files get obeyed, long files get skimmed

Every line is read every single session, so every line costs context — and a bloated file means the rule you actually care about gets lost in the noise. There's a real budget here: in practice models reliably follow a couple of hundred instructions at most, and Claude Code's own system prompt already spends a chunk of them. Keep each file under 200 lines. The test for every line: would Claude get something wrong without it? If not, delete it.

The tiers add together, they don't override

All three files load into the same session. If two of them contradict each other, Claude picks one arbitrarily — so never repeat a rule across tiers. Each rule lives at exactly one altitude: the highest one where it's still true.

Treat them like a garden, not a monument

When Claude makes the same mistake twice, add a rule. When you notice it already does something without being told, delete that line. If a rule keeps getting broken, mark it IMPORTANT — sparingly. These files earn their keep session after session, but only if you prune them.

Grab all three from GitHub.

Everything on this page — the three templates, the set-up prompt, the distill prompt — lives in one repo, so Claude can fetch it and you can fork it.

View the templates on GitHub

Want ready-made rules for the project tier?

The Coding Guidelines CLAUDE.md — four rules built from Andrej Karpathy's notes on where AI coding goes wrong — drops straight into any project-level file: think before coding, simplicity first, surgical changes, goal-driven execution.

The Honest Bit

Writing a smarter model's thinking into these files doesn't turn a cheaper model into that model — reasoning it does live, in the moment, can't be written down. What you keep is the judgment: the standards, the structure, the way problems get broken down. In practice that's a surprising amount of what made the smart model feel smart. But if a task genuinely needs more horsepower, no file fixes that — that's what the model picker is for.

Want a hand putting this into practice? I do one-to-one AI coaching — wherever you're starting from.Learn more