CLAUDE.md as a Business Operating System

Most CLAUDE.md files are a glorified list of npm scripts.

CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Developers fill it with test commands and branch rules. It works far better as the standards layer for an entire business: brand voice, offer logic, client SOPs, compliance rules, and the decision history behind all of it. Loaded on demand, not all at once.

That reframe is the whole post. Same file, same head term, completely different job.

What is CLAUDE.md and how does it actually work?

CLAUDE.md is a markdown file that Claude Code loads into context automatically when a session starts. You do not have to reference it. You do not have to paste it. It is simply there, treated as standing instruction, on every message you send in that directory.

That automatic part is the entire mechanic. Everything else in this post is a consequence of it.

There are three locations, and they stack:

Your project root. A CLAUDE.md in the folder you launch Claude Code from. This is the main one. Rules here apply to all work in that project.

Any subdirectory. A CLAUDE.md inside a nested folder gets pulled in when Claude works on files in that folder. Rules that only matter for one client, one product, or one channel live here instead of cluttering the root.

Your home directory. A file at ~/.claude/CLAUDE.md follows you into every project on the machine. This is where personal working preferences go. How you want to be talked to. What you never want asked twice.

When rules conflict, the more specific file wins. Project beats global. Subdirectory beats project. That is the same inheritance model as CSS, and it behaves the way you would expect.

The second mechanic that makes business use possible is imports. Inside any CLAUDE.md you can write a line like @brand/voice.md and Claude Code will pull that file's contents in as part of the memory load. Imports can nest, and Claude Code resolves them several levels deep, so a small root file can act as an index for a much larger library.

That is the complete technical surface. A markdown file, an inheritance order, an import syntax, three commands. Everything after this is judgment about what to put inside.

Why do developers use CLAUDE.md and businesses don't?

Because developers found it first and their use case was obvious.

An engineer opens Claude Code, gets annoyed that it keeps running the wrong test command, writes the right one into CLAUDE.md, and never gets annoyed again. The feedback loop is tight and the payoff is immediate. Multiply that by twenty small annoyances and you get the standard dev CLAUDE.md: build commands, lint rules, folder conventions, "never commit to main."

Useful. Also tiny.

The business version has a slower feedback loop and a much larger payoff. Nobody writes down their brand voice because nothing breaks visibly when they don't. The email just comes out a little generic. The landing page sounds like everyone else's landing page. The client deliverable needs two rounds of edits instead of zero. Those costs are real but they are diffuse, so they never trigger the "write this down" reflex the way a failing test command does.

Here is the thing operators miss. Every one of those diffuse costs is the same failure the developer solved. The model does not know your standard, so it defaults to the average of everything it has read. Generic output is not a model quality problem. It is a missing standards file. And you do not need to be a developer to write one. Claude Code works just as well as a file and operations agent.

There is a second reason, and it is more uncomfortable. Most businesses cannot write their standards down because they do not have any. Voice lives in the founder's head. Pricing rules live in whatever the founder said on the last sales call. The SOP is "ask Sarah." Writing CLAUDE.md forces you to convert tribal knowledge into declarative text, and that conversion is the actual work. The AI just gave you a reason to finally do it.

That is the underrated benefit. The file makes you legible to yourself before it makes you legible to the model.

What goes in a business CLAUDE.md?

Five layers. In this order, because each one constrains the next.

Layer one: identity and constraints

Who the business is, who it serves, and what it will not do. Short. Ten to twenty lines.

This layer answers the questions that change every other answer. What is the company. Who is the customer. What are the brands and how are they kept separate. What can never appear in output.

The constraints half matters more than the identity half. "We are a company that helps founders" produces nothing useful. "Never make income claims, never imply guaranteed outcomes, never use the client's competitor names in copy" produces a measurably different draft every time.

Write constraints as absolutes with no wiggle room. Models are good at following hard rules and bad at calibrating soft preferences. "Avoid being too salesy" is noise. "Never use exclamation points in email subject lines" is signal.

Layer two: voice

How the business sounds. This is the layer with the highest return per line written, and almost nobody has it documented.

Voice is not adjectives. "Professional but approachable" is worth nothing. Voice is rules, patterns, and a banned list.

Rules: sentence length, paragraph length, reading level, whether you use contractions, whether you use questions, how you open, how you close.

Patterns: two or three named structures you actually use, described mechanically. A hook pattern. A proof pattern. A transition pattern.

Banned list: the exact words and constructions that mean a draft has failed. This is the single most effective thing in the entire file because it is unambiguous, checkable, and it catches the specific tells that make AI copy read as AI copy.

Then include samples. Two or three paragraphs of real published work, marked as reference. A model calibrates faster from one good example than from a page of description.

Layer three: offers and funnel logic

What you sell, what each thing costs, who it is for, and which piece of content points to which offer.

This layer is where AI output usually falls apart in a way that is expensive rather than embarrassing. The draft is fine. The call to action is wrong. It sends cold traffic to a high-intent offer, or it sends a warm audience back to the top of the funnel, and the whole piece underperforms for a reason nobody diagnoses.

So write the routing explicitly. Cold traffic goes here. Warm audience goes there. This content type always points to that destination. One call to action per piece, never two.

Include the reasoning, not just the rule. "Cold traffic goes to the free training because cold audiences need the education step before a paid offer converts" survives the day someone asks why. The bare rule does not.

Layer four: standard operating procedures

One file per repeatable output type. Blog post. Email. Sales page. Client onboarding. Weekly report. Proposal.

Each SOP contains the format, the required sections, the length target, the quality bar, and the checklist that has to pass before the work ships.

This is where the operating system claim stops being a metaphor. When the SOP is written down, "write me a client onboarding email" stops being a creative request and becomes an execution request. The model is not inventing your process. It is running it.

Write SOPs as steps, in order, with decision points made explicit. If a step depends on a condition, state the condition and both branches. Ambiguity in an SOP is where the model improvises, and improvisation is exactly what you built the file to prevent.

Layer five: decision history

The layer everyone skips and the one that compounds hardest.

A decision log is a running record of choices the business made, when, and why. We moved pricing in March and here is what drove it. We killed that channel and here is what we saw. We tried the two-step funnel and it lost to the one-step.

Why this matters for an AI operating system: without history, every session starts from zero and re-suggests the thing you already tried and rejected. With history, the model can say "you tested that in March, it lost, here is a different angle." That is the difference between a tool that generates and a partner that reasons over your actual context.

It also solves the handoff problem completely. A new contractor reading your decisions folder understands the business in an hour rather than a month. Same file, two audiences, no extra work.

What does the file tree look like?

Here is the structure. It lives in an Obsidian vault, which is just a folder of markdown files with backlinks and a graph view sitting on top. Obsidian is not required. It is a nice reading surface for humans over the exact same files Claude Code reads.

business-os/
├── CLAUDE.md                    # the router. small. read every session.
├── brand/
│   ├── identity.md              # who we are, who we serve, brand separation
│   ├── voice.md                 # rules, patterns, banned list, samples
│   └── compliance.md            # hard prohibitions, approved framing
├── offers/
│   ├── catalog.md               # every offer, price, audience, promise
│   ├── funnel-routing.md        # which content points where, and why
│   └── positioning.md           # category, differentiation, competitors
├── sops/
│   ├── blog-post.md
│   ├── email.md
│   ├── short-form-video.md
│   ├── sales-page.md
│   ├── client-onboarding.md
│   └── weekly-report.md
├── clients/
│   ├── CLAUDE.md                # rules that apply to all client work
│   ├── acme/
│   │   ├── CLAUDE.md            # acme-specific voice, constraints, contacts
│   │   └── brand-guide.md
│   └── northwind/
│       ├── CLAUDE.md
│       └── brand-guide.md
├── decisions/
│   ├── 2026-03-pricing-restructure.md
│   ├── 2026-05-killed-paid-social.md
│   └── 2026-06-funnel-consolidation.md
└── reference/
    ├── metrics-definitions.md   # what we mean by activation, retention, etc.
    └── tools.md                 # what we use and what it is for

Three structural choices are doing all the work here.

The root CLAUDE.md is small. It is an index and a router, not a document. It gets loaded on every single message, so every line in it is a tax you pay forever. Keep it under one screen.

Client folders carry their own CLAUDE.md. When Claude works on files inside clients/acme/, that client's rules load automatically. Acme's voice never bleeds into Northwind's newsletter because the two rule sets never occupy the same context at the same time. This is the cleanest solution to multi-brand work I have found, and it requires no configuration beyond putting a file in a folder.

Decisions are dated files, never one big log. One decision per file, named with the date. They are individually linkable, individually loadable, and they never turn into a five thousand line document nobody opens. Obsidian's backlinks let you jump from a pricing SOP to every decision that touched pricing.

The whole thing is version controlled. That matters more than it sounds. When output quality changes, you can diff the standards file and see exactly what you changed and when. Your business rules become reviewable the same way code is reviewable.

How does the routing logic work?

This is the part that separates a working setup from a bloated one.

The naive approach is to put everything in CLAUDE.md. Voice, offers, every SOP, all of it. It works for about a week. Then the file is four thousand words, it loads on every message including "what time is it," and the signal you care about is buried under nine sections that are irrelevant to the task at hand.

The fix is a router. The root CLAUDE.md holds only what is universally true, plus a map that tells Claude which files to read for which kind of work.

Routing block for your root CLAUDE.md

## Always applies

@brand/identity.md
@brand/voice.md
@brand/compliance.md

## Load by task

Before writing a blog post, read sops/blog-post.md.
Before writing an email, read sops/email.md.
Before writing short-form video copy, read sops/short-form-video.md.
Before writing anything with a call to action, read offers/funnel-routing.md.
Before any client work, read the CLAUDE.md in that client's folder.
Before recommending a strategy change, scan decisions/ for prior attempts.

Two mechanisms, deliberately different.

The @ imports are always on. Voice, identity, and compliance apply to every piece of work regardless of type, so they get pulled in every session. These three files are the reason output sounds like your business instead of like a language model. They earn their permanent slot.

The task map is conditional. It costs a handful of lines in the root file, and the actual SOP loads only when the work calls for it. Writing an email does not drag your sales page SOP and your client onboarding checklist into context alongside it.

The phrasing of the routing lines is doing real work. "Before writing a blog post, read sops/blog-post.md" is an instruction with a trigger condition and an action. Compare that to "SOPs are in the sops folder," which is a fact the model has no reason to act on. State the trigger, state the file, state that it happens before the work starts.

You can push this further with a rule I keep near the top of every business root file:

The SOP enforcement rule

If a task type has an SOP and you have not read it this session, read it
before producing output. Do not work from memory of a similar SOP.

That one line prevents the most common failure in a mature setup: the model pattern-matches to a similar procedure it read earlier and produces something that is almost right.

The routing model also handles a real operational problem, which is that different people need different depth. A contractor writing one blog post loads the root file and the blog SOP. That is their whole onboarding. You, doing strategy work, pull in the decisions folder and the offer catalog. Same repository, different depth of load, no duplicated documentation.

This is the same principle behind well-built AI agent workflows that run real operational work. Do not give an agent everything. Give it the right thing, at the right moment, and make the retrieval condition explicit.

What is context engineering and why does it decide whether this works?

Context engineering is the practice of deciding what information a model sees, in what form, and at what moment. It is the discipline that replaced prompt engineering once models got good enough that phrasing stopped being the bottleneck.

The core constraint: a model can only reason over what is in front of it. Not what is in your head, not what is in a file it did not read, not what you explained three sessions ago. This is why AI agents forget everything between sessions unless you build the memory layer yourself. There is no continuity by default. Every session is a stranger with excellent general knowledge and zero specifics about you.

CLAUDE.md is the simplest possible answer to that problem. It is a file that gets read every time, so the specifics are never missing.

But loading context has a cost, and understanding the cost is what separates a setup that improves output from one that degrades it.

Cost one: attention dilution. Instructions compete. When a file contains eighty rules and only six are relevant to the current task, the six get less weight than they would alone. This is not a hard failure. It is a slow quality drift that is hard to attribute, which makes it worse. A tight file where every loaded rule is relevant produces sharper output than a comprehensive file where most rules are noise.

Cost two: contradiction risk. The more you load, the more likely two rules disagree. If your voice file says short sentences and your sales page SOP says build long rhythmic momentum, the model has to pick, and it will pick unpredictably. Loading them separately means it never has to arbitrate.

Cost three: staleness surface. Every line in an always-on file is a line you have to keep true. A big file goes stale faster than a small one, and stale rules are worse than no rules because the model follows them with full confidence.

So the three practical principles:

Load what is always true, always. Load everything else on demand. Voice is always true. Your sales page structure is not. That distinction determines whether something goes in the root file or behind a routing rule.

Prefer specific over comprehensive. Ten precise rules beat fifty vague ones every time. If a rule cannot be violated in an obvious way, it is not a rule, it is a vibe, and it should be cut.

Make retrieval conditions explicit. Do not rely on the model to decide when a file is relevant. Tell it the trigger. "Before X, read Y" is the highest-leverage sentence pattern in this entire system.

This is also why the format matters. Markdown headers, short declarative lines, one idea per line. Not because the model requires it, but because that structure makes each rule independently retrievable and independently checkable. A wall of prose forces the model to infer which parts apply. A list does not.

What are the CLAUDE.md best practices that actually matter?

Nine rules. These come from breaking it repeatedly.

One fact per line. Not one topic per paragraph. One fact per line. "Blog posts run 1,200 to 2,000 words" is a line. "Blog posts should be substantial and well-researched with appropriate length for the topic" is a wish.

Write rules that can be violated. Test every line by asking whether you could look at a draft and say definitively that it broke this rule. If you cannot, rewrite it or cut it. "Never use em dashes" passes. "Write with clarity" fails.

Include the why on anything non-obvious. Rules without reasons get followed literally in situations where they should not apply, and they get quietly abandoned by humans who do not understand them. One clause of reasoning makes a rule durable. "Cold traffic goes to the free training, because cold audiences need an education step before a paid offer converts."

Ban specific words, not general tones. A banned list is the highest-precision instrument in the file. "Do not sound like AI" is unusable. A list of eighteen specific words and three specific sentence constructions is enforceable on every single draft.

Put examples in. Two paragraphs of real published work outperform a page of description. Label them clearly as voice reference so they are not mistaken for content to reuse.

Keep the root file under one screen. If you scroll, you are paying a tax on every message for content most messages do not need. Move it out and route to it.

Date anything time-sensitive. Pricing, product status, team structure, tool stack. A dated line tells you at a glance whether it needs review. An undated line rots invisibly and gets followed as gospel.

Use the # shortcut in the moment. The best rules are written the second you notice something wrong. You correct an output, you think "it should have known that," and that thought is the rule. Start a message with # and it goes into memory immediately. Rules written during a scheduled documentation session are generic. Rules written at the moment of friction are precise.

Prune monthly. Set a recurring block. Read the root file top to bottom. Delete anything no longer true. Delete anything that has never once changed an output. A file that only grows becomes a file nobody trusts, and a standards file nobody trusts is worse than no file at all.

The copy-paste template

Here is a working root file. It is filled in with realistic content rather than blanks, because a template full of empty slots teaches you nothing about the level of specificity required. Replace the contents, keep the structure and the specificity.

Root CLAUDE.md template

# Business Operating System

## Identity

We build and sell software and training for independent operators.
Two brands, kept fully separate:

- Sprint: consumer, subscription, operator-facing.
- ScaleUp: B2B, done-for-you, agency-facing.
Never mix positioning, audience, or offers between the two.

Primary audience: founders and operators, semi-technical, systems thinkers,
allergic to hustle-culture framing.

## Hard constraints

Never make income claims or imply guaranteed outcomes.
Never use fake scarcity or countdown pressure.
Never cite a statistic that is not from a named, dated source.
Never describe an unshipped product as available.
Never use square-bracket placeholders in finished output. Write the real line
or cut it.

## Always applies

@brand/voice.md
@brand/compliance.md
@offers/catalog.md

## Load by task

Before writing a blog post, read sops/blog-post.md.
Before writing an email, read sops/email.md.
Before writing short-form video copy, read sops/short-form-video.md.
Before writing anything containing a call to action, read
offers/funnel-routing.md.
Before any client work, read the CLAUDE.md inside that client's folder.
Before proposing a strategy change, scan decisions/ for prior attempts.

If a task type has an SOP and you have not read it this session, read it
before producing output. Do not work from memory of a similar SOP.

## Working preferences

When asked to write something, write it. Do not offer five options.
Note the one tradeoff worth flagging, then deliver.
Flag any claim you cannot defend before the draft ships, not after.
Ask before doing anything that sends, publishes, or spends.

And the voice file it imports, which is where most of the quality lives:

brand/voice.md template

# Voice

## Rules

Fifth grade reading level. Short words, short sentences.
Paragraphs run two to three sentences, 40 to 60 words maximum.
One idea per line when the line needs to land.
Use contractions. Write like a peer, not a teacher.
Open with a specific claim, never with context-setting.
Never explain what the piece is about to do.

## Banned

Em dashes. Use periods, commas, or parentheses.
These words: delve, unlock, supercharge, seamless, elevate, harness,
game-changer, dive in, unleash.
These constructions: "it's not just X, it's Y", "in today's fast-paced world",
"the landscape of".
Stacked exclamation points. "Click here." "Read more."

## Patterns

The build reveal: "I built a thing that does X in Y minutes."
The contrarian operator take: "Most people use AI like a smarter search box.
That is not leverage."
The reclaimed-time proof: "I have not opened a laptop before 10am in
three months."

## Reference

Two to three paragraphs of real published writing go here, marked clearly
as voice reference and not as content to reuse.

Copy both blocks. Put the first at your project root as CLAUDE.md. Put the second at brand/voice.md. You have a working system in about ten minutes, and the remaining work is filling it with things that are true about your business instead of mine.

How do you keep CLAUDE.md from going stale?

Three habits. Without them the file decays into a museum of what the business used to be, and the model follows outdated rules with complete confidence.

Capture at the moment of friction. Every time you correct an output, that correction is a rule you did not have. Do not save it for later. Use # and write it down while the specific wording of the correction is fresh. Later you will write "be more direct" instead of the actual thing you meant, which was "cut the first paragraph, it is always warm-up."

Log decisions the day you make them. New file in the decisions folder, named with the date. Four lines is enough. What we decided. What drove it. What we expect. What would make us reverse it.

That last line is the one people leave out and the one that pays. A decision with a stated reversal condition is testable. Six months later you can check whether the condition fired instead of arguing from memory about whether it was the right call.

Prune on a schedule. Monthly, thirty minutes. Read the root file and every always-on import. Three questions per line. Is it still true. Has it ever changed an output. Would a new contractor understand it without asking.

Delete on any no. The instinct is to keep everything because deleting feels like losing work. Deleting is the work. Every stale line degrades every future session.

The compounding effect is what makes this worth the discipline. Month one, the file makes output sound like your business. Month six, it encodes procedures so a contractor can run them. Month twelve, the decision log means the model can reason about strategy with real historical context instead of generic advice. The value curve is not linear, and almost everyone quits before it bends.

What breaks when people try this?

Five failure modes, in the order I see them.

The file grows and nobody prunes. Most common by far. Everything gets added, nothing gets removed, and by month three the root file is four thousand words of accumulated sediment. Output quality drops and nobody connects it to the file, because the file is the thing that was supposed to fix quality. Fix: a hard length cap on the root file and a monthly prune that actually happens.

Vibes instead of standards. The file fills with things like "maintain a professional yet conversational tone" and "ensure content is engaging." These feel like standards and change nothing. Fix: the violation test. If you cannot point at a draft and say definitively that it broke the rule, it is not a rule.

Silent contradictions. Two rules disagree, the model picks one, and the pick is inconsistent across sessions. You experience this as the AI being unreliable, when actually you gave it an unresolvable instruction. Fix: when output is inconsistent on a specific dimension, search the file for both rules governing it. There will be two.

No owner. The file is everyone's responsibility, which means it is nobody's. It stops reflecting reality within a quarter. Fix: one named person owns the root file and the always-on imports. SOPs can be owned by whoever runs that process.

Treating it as configuration instead of documentation. People write it in AI-speak, cryptic and abbreviated, as if optimizing for the machine. Then no human reads it, and it drifts from reality unchecked. Fix: write it so a smart new hire could read it and understand the business. That constraint keeps it honest, keeps it useful for onboarding, and costs nothing, because clear writing is what the model wants anyway.

Where markdown stops being enough

Honest limits, because a file has them.

CLAUDE.md holds what is always true. It does not hold what happened. It has no idea what you worked on yesterday, what you decided in a conversation last week, or that a task you started on Tuesday is still open. It is a standards layer, not a memory system. Those are different problems and the file only solves one of them.

You feel the gap the moment your work spans sessions. You explain a project's state, do good work for an hour, close the terminal, and tomorrow explain the same state again. The standards carry over perfectly. The situation does not.

You can push against this manually. A context/current.md file you update at the end of each session, routed in at the start of the next one, gets you a surprising distance. I ran that pattern for months and it works. It also requires you to remember to write it, which means it fails exactly when you are busy, which is exactly when you need it.

That gap is what I am building Focus Pilot to close. Layered memory that separates standing rules from situational state, so the operating standards stay stable while the working context updates itself. Agents that coordinate with each other and carry what they learned into the next run instead of starting cold. Connected accounts so the memory reflects what actually happened in the business rather than what you remembered to type. I am building it in public, and the build is not finished. What exists today is the architecture and the working pieces I use daily.

The reason I am telling you this in a post about a markdown file: build the file first anyway. Every standard you write down now transfers directly into any memory system you adopt later, including mine. The hard part was never the storage format. The hard part is having explicit standards at all, and that work is portable.

Start with markdown. It costs nothing and it is the input to everything that comes after.

Your first ninety minutes

Not a week. Ninety minutes, today.

Minutes 0 to 10. Install Claude Code if you have not. Make a folder for your business. Run /init. Delete whatever it generated that is about code.

Minutes 10 to 30. Write the identity and hard constraints block. Who you are, who you serve, and the five things that must never appear in output. The constraints are more valuable than the identity. Spend the time there.

Minutes 30 to 60. Write brand/voice.md. Rules, banned list, two patterns. Then paste in two paragraphs of your own published writing that you actually liked, marked as reference. This is the single highest-return half hour in the whole process.

Minutes 60 to 80. Pick the one thing you produce most often. Blog posts, client emails, proposals, whatever it is. Write that SOP. Format, sections, length, quality bar. Add the routing line to your root file.

Minutes 80 to 90. Use it. Ask for the thing you just wrote an SOP for. Watch what comes out. Fix the first thing that is wrong by adding a rule with # rather than by editing the output.

That last step is the habit that matters. Every future correction becomes a rule instead of a re-explanation, and the file writes itself from there.

You now have a business operating system. It is a folder of markdown files. It will not look impressive and it will change how everything you produce comes out.

If you want to see the full system running, the standards layer plus the agent workflows that execute against it plus the memory layer that keeps it from forgetting between sessions, I walk through the whole thing in a free training.

Watch the free masterclass