§

Why a Good CLAUDE.md Is the File That Makes the System Hum

Jason

·

A PARA-organized vault, Obsidian as the editor, and Claude wired in via the filesystem MCP — none of it works until you give the model a CLAUDE.md to read first. Every session begins with a fresh context window. Without a CLAUDE.md, Claude opens the vault and has to figure out from scratch who you are, what you do, who your team is, and what conventions matter. With one, the model orients in about ten seconds.

This post is the third in a short series. The first one covered the stack — Obsidian and Claude wired together via filesystem MCP. The second covered the organizing method, Tiago Forte's PARA. This piece is about the single file that makes both of those work, and what to put in it. Anthropic's official term for that file is CLAUDE.md.

What CLAUDE.md is

CLAUDE.md is a markdown file you place at the top of a project or a vault. Claude reads it at the start of every session. That is the entire definition. The file exists because every Claude session begins with a fresh context window — the model has no memory of your last conversation, your team, your tools, your conventions, or your project structure. Without something that loads automatically, the model spends the first part of every session asking questions you already answered last week.

Anthropic's documentation on the file puts the framing plainly: "Each Claude Code session begins with a fresh context window." The CLAUDE.md file is how that fresh window gets oriented. Anthropic describes the file's role as a place to write down "what you'd otherwise re-explain." It is loaded as a user message right after the system prompt and before anything you type, so by the time you ask your first question, the model has already read who you are, what you do, and how you want to be helped.

The convention started in Claude Code, but it works the same way for Claude Desktop with a filesystem MCP server pointed at your vault. Point the model at the CLAUDE.md file early — explicitly, the first time you connect — and the effect carries across sessions for as long as that vault is mounted. The format is plain markdown. Anthropic is explicit: "There's no required format for CLAUDE.md files, but keep it short and human-readable."

Why CLAUDE.md is the highest-leverage file in a vault

There is a real ceiling on how much information a language model can act on at once. The HumanLayer guide to writing CLAUDE.md cites a working figure that has held up across model generations: a frontier model can reliably follow somewhere around 150 to 200 distinct instructions in a single context window. Claude Code's own system prompt occupies roughly 50 of those slots before you write anything. That leaves on the order of 100 to 150 usable instruction slots for your CLAUDE.md and your active conversation combined.

This is the constraint that makes CLAUDE.md the highest-leverage file in the vault. The same constraint explains why bad CLAUDE.md files actively hurt. A 600-line CLAUDE.md does not give the model more guidance. It gives the model more instructions than the model can hold, and the model quietly starts dropping some of them — including the ones that mattered. Anthropic's docs put the practical target at "under 200 lines." HumanLayer's guide pushes harder and recommends under sixty for most cases. The discipline is to write the file as if every line cost real money, because in attention terms every line does.

A good CLAUDE.md gives the model the smallest set of facts that lets it behave like a colleague who already knows the operator. Bad ones describe edge cases, list every command, paste in style guides, and try to cover everything the model might ever need. Those get ignored.

What belongs in a CLAUDE.md

After comparing a handful of well-tended examples — Anthropic's own documentation samples, HumanLayer's templates, the CLAUDE.md files inside open-source repositories that take the convention seriously, and the one we maintain for Not Really Wines (NunnCurtis Labs' fictional demo winery, which we run as a public showcase of this kind of vault setup) — six sections show up in almost every CLAUDE.md that earns its keep.

  1. Who I am. Two or three sentences identifying the person Claude is working alongside. Role, what they own, what they trust the team to handle. This is the most important section by far, because it tells the model what kind of help to offer.

  2. Who the project, business, or organization is. Mission, products, stage. What the operation does and what success looks like for it. Not a marketing paragraph — a working summary.

  3. Voice / style preferences. How the person wants to be talked to, and how anything they write should sound. Plain over clever. Compliance words to keep or avoid. The tells that mark drafts as not-in-our-voice.

  4. What is off-limits or requires approval. Files Claude must not modify. External messages Claude can draft but not send. Domains where Claude should flag before acting. This is the section that prevents expensive mistakes.

  5. What kind of help you want. The list of things the human wants the model to do most often. Synthesis. Drafting. Surfacing blind spots before a decision. Recurring reports. Naming this explicitly raises the hit rate dramatically.

  6. How to find things. A short index of the vault layout — which folder holds what, where to start, where to never write. For a PARA-organized vault, this is where the model learns the folder semantics.

The order matters less than the presence of each section. A CLAUDE.md that covers all six tends to land under 150 lines without much effort to trim it.

A worked example: the NRW CLAUDE.md

To make the structure concrete, here is how Not Really Wines opens its CLAUDE.md. The full file lives in the NRW vault at D:\NRW Vault\CLAUDE.md and runs about 140 lines.

The identity section is two short paragraphs:

I'm Maren Holloway, Co-Founder & CEO of Not Really Wines. […] I do the strategy, the brand, the press, the wholesale relationships, and the books-on-the-back-of-the-envelope. I trust my team to do their parts. My job is to make sure they have what they need and that we don't run out of money before this turns into something.

Tone preference for me: plain, fast, friendly. Don't soften bad news. Don't pretend. If I ask a question, give me your best answer first; I'll ask for context if I need it.

Six sentences. Claude now knows who is on the other side of the conversation, what they prioritize, and how to phrase answers. That is more behavioral guidance than most CLAUDE.md files extract from three hundred lines.

The organization section is similarly tight: NRW is premium non-alcoholic wine, vacuum-distilled from Sonoma fruit, three SKUs (Chardonnay, Pinot Noir, Rosé), a subscription program called The Society, around thirty wholesale accounts. Mission, products, stage, retention story. Forty lines, all working.

The team roster is a markdown table with one row per person, three columns: name, role, what they own. Diego Reyes owns production. Priya Sandhu owns DTC and The Society. Tessa Brennan owns hospitality. When Claude needs to draft a wholesale outreach email, it knows Jordan Miyake is the person whose voice and context that email should reflect, because the table told it so.

The off-limits section is explicit:

Don't modify financial spreadsheets in 2_Areas/Operations/Finance/ or anywhere Marcus's name is on the file. Read only.

Don't send external messages without me reading the draft first. Drafting and queueing is fine.

Two short paragraphs, two hard rules. The model now defaults to drafting press replies rather than sending them, and treats Marcus Chen's finance files as read-only, without anyone re-explaining either policy every session.

The "what I'd love help with" section is the one most CLAUDE.md files miss. It tells the model what the human wants assistance on, in their own words:

Stepping back and thinking through a question before I jump to action. Most of my mistakes are from moving too fast.

Drafts in our voice — emails, social, press, wholesale outreach. Save me from the blank page.

Surfacing what I'm missing before I commit. "What am I likely not considering?" is a question I want to ask you a lot.

That section turns the model from a generic assistant into a specific collaborator.

What does not belong in a CLAUDE.md

The same Anthropic and HumanLayer sources are equally clear about what to leave out, and the rule of thumb is consistent across all of them.

Anything Claude will learn after one session of working in the vault. Anthropic's documentation puts it directly: "Do not waste CLAUDE.md lines on things Claude will learn after one session of working in your codebase." Run /memory periodically to see what Claude has figured out on its own. Anything the model already knows from working in the vault does not need a line in CLAUDE.md.

Style guides and large rule sets. These belong in .claude/rules/ files, which Anthropic added precisely so you can keep CLAUDE.md short while still scoping detailed rules to specific file paths. A 400-line code-style document forced into CLAUDE.md will dilute every other instruction in the file.

Every command and every utility. Lists of npm scripts, build steps, and one-off commands belong in a README or a Makefile. Claude can read those when the model needs them. Forcing all of them into CLAUDE.md punishes every other session that does not need to know about that one command.

Anything you would use an LLM as a linter for. HumanLayer's phrasing is sharp on this: "Never send an LLM to do a linter's job." Indentation, formatting, import ordering — set up the deterministic tool and call it. CLAUDE.md lines spent on style enforcement compete for context against lines that require judgment.

Raw /init output that has not been edited. Running /init produces a starter file based on what the model can infer from the project. Anthropic recommends it as a starting point. HumanLayer is more skeptical and reminds writers that the result still needs human editing before it earns its place in every session. Treat /init like a draft, never a finished file.

How CLAUDE.md connects to the rest of the stack

The reason this file matters so much for the broader workflow comes down to where it sits in the chain. PARA gives the model spatial structure — which folder is for active work, which is for reference, which is for history. Obsidian keeps the whole vault as plain markdown anything can read or write. The filesystem MCP lets Claude reach the vault directly, without API plumbing. CLAUDE.md is what tells the model who it is helping and what the rules are.

Without that last piece, the other three are inert. The model can see the folders, read the files, and write into them, but has no idea what behavior is correct. The first question of every session becomes what do you do here? and the model answers with generic LLM advice instead of the answer the business needs.

With CLAUDE.md in place, the same vault behaves like a coworker who already knows the operator. The folder structure tells the model where things are. The frontmatter on each file tells it the state of those things. CLAUDE.md tells it what kind of help to offer and what guardrails to respect. The stack hums because the components are pointed at each other deliberately, rather than sitting in the same vault unconnected.

A quick checklist if you are writing one now

If you are about to write a CLAUDE.md from scratch, the shortest path to a useful one is to draft six sections in this order, then trim:

  1. Two or three sentences on who you are and what kind of answers you want.
  2. Three or four sentences on what the organization is and what success looks like.
  3. A voice / style block that names the tells that mark drafts as off-voice.
  4. A short list of what is off-limits or needs approval.
  5. A short list of the help the operator wants the model to offer most often.
  6. A two-line map of the vault structure, with one line per folder.

Aim for under 150 lines once all six sections are in. Then read it back as a new colleague would. Cut any line a colleague would already know after a day in the vault. The remaining lines are the ones that earn their place in every session.

If you run a winery and want help setting up an Obsidian vault, a PARA structure, and a CLAUDE.md that orients Claude to your specific operation — institutional knowledge, harvest history, distributor relationships, voice — that is the work we do at NunnCurtis Labs.

Resources

← All insights