Writing a CLAUDE.md File: Standing Orders for Your AI

Photo by Aaron Burden on Unsplash

A CLAUDE.md file is a plain-text markdown file that gives your AI assistant persistent instructions it reads at the start of every session. Think of it as the standing orders you'd otherwise re-type into chat every single time: how your project is laid out, which commands to run, the conventions to follow, the mistakes never to repeat. Instead of re-explaining your codebase each morning, you write it down once, and Claude loads it automatically. For a non-technical founder, this one file is the difference between an assistant that acts like it just met your project and one that behaves like it's worked on it for months. This guide covers what to put in it, what to leave out, and why the file works the way it does.

TL;DR

• A CLAUDE.md is persistent memory: instructions your AI reads at the start of every session so you stop repeating yourself.
• Keep it under 200 lines. Longer files consume more context and get followed less reliably.
• Put facts that are true in every session: project layout, build and test commands, conventions, "always do X" rules.
• It's guidance, not enforcement. For rules that must always run (like signature checks before a commit), use a hook instead.
• Add to it the moment you type the same correction twice. That's the signal a fact belongs on disk, not in chat.

What is a CLAUDE.md file, and why does it matter for non-devs?

A CLAUDE.md file is a markdown document you write in plain English that your AI assistant loads into context at the start of every conversation. Each session with Claude Code begins with a fresh, empty memory. The model doesn't remember yesterday's conversation, your project's quirks, or the correction you made an hour ago. The CLAUDE.md is one of two mechanisms that carry knowledge across that gap, per Anthropic's own memory documentation.

For an engineer, this is a convenience. For a non-technical founder, it's closer to load-bearing. An engineer can open a file, read the code, and infer the conventions. You and I can't reliably do that. If Claude doesn't know that your API handlers live in a specific folder, or that this project uses one package manager and not another, it will guess, and its guesses look plausible enough that you won't catch the wrong one until something breaks.

The CLAUDE.md closes that gap by making the project's rules explicit. When I ship anything on Coding Capybaras, the assistant already knows the three-region architecture, the import conventions, and the forbidden patterns, because they're written down in a file it reads before it does anything else. I'm not relying on it to infer them, and I'm not re-typing them.

The honest framing: this file doesn't make your AI smarter. It makes it consistent. Consistency is what you actually want when you can't audit the output line by line yourself. That same instinct — moving the checkpoint earlier, before a change lands — is why plan mode matters so much for non-developers, and the CLAUDE.md is the written-down version of the same idea.

What belongs in a CLAUDE.md (and what doesn't)

The test for what goes in the file is simple: is this a fact Claude should hold in every single session? Build commands, project layout, coding conventions, and "always do X" rules pass that test. A one-off instruction for today's task does not.

The official guidance is to add something to your CLAUDE.md the moment one of these happens: Claude makes the same mistake twice, a code review catches something it should have known, you type the same correction you typed last session, or a new teammate would need the same context to be productive. Each of those is a signal that a piece of knowledge is living in your head (or in a throwaway chat message) when it should live on disk.

Here's what earns a spot:

• Build and test commands. "Run pnpm test before committing" beats "test your changes." Concrete and verifiable.
• Project layout. Where things live. "API handlers live in src/api/handlers/" saves Claude from inventing a path.
• Conventions that differ from defaults. Two-space indentation, a specific import style, the naming pattern you use.
• Forbidden patterns. The things that must never happen. On Coding Capybaras, "never import the Stripe SDK outside one specific file" is written down because the whole architecture depends on it.

Here's what does not belong:

• Multi-step procedures. If it's a workflow that only matters sometimes, it should be a skill, which loads on demand instead of every session.
• Instructions for one part of the codebase. Those belong in a path-scoped rule that loads only when Claude touches matching files.
• Pasted code. Reference the file that shows the pattern; don't copy the code into your instructions.
• Anything you can't state concretely. "Format code properly" is noise. Claude can't verify it, so it mostly ignores it.

The discipline here is subtraction as much as addition. A bloated instruction file is a real failure mode, and I'll come back to it.

Where does the file go? Understanding scope

CLAUDE.md files can live in several places, and each location has a different reach. This is the part that confuses people first, so here's the full map from Anthropic's documentation, ordered from broadest scope to most specific:

| Scope | Location | What it's for | Shared with | | --- | --- | --- | --- | | Managed policy | System directory (set by IT) | Org-wide standards, compliance | Everyone in the org | | User instructions | ~/.claude/CLAUDE.md | Your personal preferences, all projects | Just you, everywhere | | Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Team-shared project rules | Your team, via source control | | Local instructions | ./CLAUDE.local.md | Personal notes for one project | Just you, this project |

For most solo founders, two of these matter. The project CLAUDE.md sits at the root of your repository and holds everything true about this project — it's checked into version control, so if you add a collaborator later, they inherit the same context automatically. The user CLAUDE.md sits in your home directory and holds preferences that follow you across every project, like "explain changes in plain English before applying them."

The files load in order, broadest first, so a project instruction is read after a user instruction. When Claude Code starts, it walks up the directory tree from wherever you launched it and concatenates every CLAUDE.md it finds along the way. They stack; they don't overwrite each other. The Claude Code memory docs lay out the full resolution order if you're running something more complex than a single repo.

One quiet detail worth knowing: you don't have to write the file from a blank page. Running /init inside Claude Code analyzes your codebase and generates a starting CLAUDE.md with the build commands, test instructions, and conventions it can discover on its own. You refine from there, adding the things it couldn't infer. That's the fastest way for a non-technical founder to get a usable file: let the tool draft it, then correct it.

Why keeping it short actually matters

The single most counterintuitive rule: a longer CLAUDE.md is not a better CLAUDE.md. The official target is under 200 lines per file. Past that, the file consumes more of the context window and, paradoxically, gets followed less reliably.

Here's the mechanism, in plain terms. Everything Claude reads — your CLAUDE.md, the system prompt, your conversation, the files it opens — shares one finite budget called the context window. Every line of instruction you add spends part of that budget. Worse, an over-stuffed instruction file is one Claude starts to skim; when there are too many rules competing for attention, adherence to any single one drops. A tight 80-line file that Claude follows every time is worth more than a 400-line file it half-ignores.

This is the same dynamic behind why your AI assistant seems to get worse three hours into a session: context is a budget, not an infinite pool, and bloat has a cost. The CLAUDE.md is the one part of that budget you control directly, so spend it deliberately.

The practical rules that keep the file tight:

• Use headers and bullets, not paragraphs. Claude scans structure the way you do. Organized sections beat dense prose.
• Be specific enough to verify. Every vague instruction is wasted tokens. If you can't check whether Claude followed it, it probably didn't.
• Prune conflicts. If two rules contradict each other, Claude may pick one at random. Review the file periodically and cut the stale entries.
• Push detail into rules and skills. If instructions only matter for one folder, scope them to that folder so they load only when relevant, instead of riding along in every session.

When a project genuinely needs more than 200 lines of guidance, the answer isn't a longer CLAUDE.md — it's splitting instructions into path-scoped rules under a .claude/rules/ directory, each covering one topic and loading only when Claude works with matching files. That keeps the always-on file lean while still capturing everything.

CLAUDE.md is guidance, not a guarantee

The trap I want to save you from: treating CLAUDE.md as a rulebook that's enforced. It isn't. Anthropic is explicit that CLAUDE.md content is delivered to Claude as context, not as a hard configuration layer. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.

For a non-technical founder, this matters most when the instruction is safety-critical. If your rule is "always verify the webhook signature before processing" or "never push directly to main," a CLAUDE.md suggests that behavior. It doesn't force it. Most of the time suggestion is enough. But for the handful of rules where "most of the time" isn't good enough, the right tool is a hook — a shell command that runs automatically at a fixed point, like before every commit, and executes regardless of what Claude decides.

The mental model I use: CLAUDE.md is for behavior you want to shape, hooks are for behavior you need to force. Code style, project layout, conventions, and "prefer X over Y" all belong in CLAUDE.md. "This check must run before this action, no exceptions" belongs in a hook. Getting that split right is part of knowing when to trust your AI assistant and when to slow down.

There's also a second memory system worth mentioning, because it complements the file. Claude Code can accumulate its own notes automatically — build commands it discovers, debugging insights, preferences you express in passing — in a separate auto-memory store. You write the CLAUDE.md; Claude writes auto memory. The two together mean you're explicitly stating what matters while the tool quietly learns the rest. You can browse and edit everything it saved with the /memory command, which is worth doing occasionally so nothing stale is steering the assistant.

If it ever feels like Claude is ignoring your file, run /context and check that the CLAUDE.md actually loaded under "Memory files." A file that isn't loading is invisible to the assistant, and that's a more common cause of "it's not listening to me" than genuine non-compliance.

A real CLAUDE.md, in pieces

Abstractions only get you so far, so here's how the ideas above show up in an actual file. The CLAUDE.md at the root of Coding Capybaras opens with a short description of what the repo is and how it relates to the upstream boilerplate it's built from. That's context Claude can't infer by reading code — the relationship between two repositories lives in a human's head until someone writes it down.

Then it establishes the architecture in a few tight bullets: three regions, what each one is for, and which one is off-limits for normal work. This is the highest-value block in the whole file. It's four or five lines, and it prevents the single most expensive category of mistake — the assistant confidently editing the wrong layer of the app because it had no way to know the layers existed.

After that comes a "forbidden patterns" section written as a flat list of nevers. Never edit the routing files by hand. Never import the payments SDK outside the one file that's allowed to. Never query one region's database tables from another region's code. Each rule is one line, concrete enough to verify, and stated as an absolute. Claude scans that list the same way you would, and because each entry is specific rather than aspirational, it actually holds.

The thing I'd point a first-time founder to is what the file doesn't contain. There's no tutorial on how Stripe works. No pasted code. No paragraph explaining the philosophy of clean architecture. Every line is a fact about this project that Claude would otherwise have to guess. When a rule started needing three paragraphs of nuance, that was the signal it belonged somewhere else — a path-scoped rule or a skill — not in the always-loaded file. The result stays lean enough that Claude reads all of it, every session, and that reliability is the entire point.

If you want to see the pattern in practice, it's the same discipline behind writing prompts that actually ship: say the specific true thing, cut everything else, and trust that concision beats completeness.

Frequently asked questions

How long should my CLAUDE.md file be?

Aim for under 200 lines. Longer files consume more of the context window and, counterintuitively, get followed less reliably because Claude starts skimming an overloaded file. If you need more guidance than that, split it into path-scoped rules that load only when Claude works with matching files.

What's the difference between CLAUDE.md and a skill?

A CLAUDE.md holds facts true in every session and loads automatically at startup. A skill packages a multi-step workflow and loads only when it's relevant to the task at hand. Rule of thumb: if it's an "always" fact, it's CLAUDE.md; if it's a "sometimes" procedure, it's a skill.

Do I need to write CLAUDE.md by hand?

No. Run /init inside Claude Code and it drafts a starting file by analyzing your codebase — build commands, test instructions, and conventions it can discover. You then refine it, adding the project-specific facts it couldn't infer on its own. Letting the tool draft it is the fastest path for a non-technical founder.

Will Claude always follow what's in my CLAUDE.md?

No, and this is important. CLAUDE.md is guidance delivered as context, not enforced configuration. Claude tries to follow it, but compliance isn't guaranteed, especially for vague instructions. For rules that must run every time without exception, use a hook, which executes as a shell command regardless of what Claude decides.

Should CLAUDE.md be committed to version control?

The project-level CLAUDE.md should be, yes. Committing it means any collaborator you add later inherits the same project context automatically, and changes go through review like any other file. Keep personal, machine-specific notes in a separate CLAUDE.local.md that you add to .gitignore.

Where to start this week

If you take one thing from this, make it this: the next time you type a correction into chat that you also typed last session, stop and put it in your CLAUDE.md instead. That single habit is what turns the file from a nice idea into the thing that actually makes your AI assistant consistent. Run /init to get a first draft, trim it under 200 lines, and add to it every time you catch yourself repeating a rule.

A good CLAUDE.md is the closest thing a non-technical founder has to institutional memory for their codebase. It's also one of the first files you'll find in every region of Coding Capybaras — the free boilerplate I built for founders shipping SaaS with AI coding tools — precisely because giving the assistant clear standing orders is what keeps a non-engineer in control of the build.