What is a CLAUDE.md file?

The markdown file Claude reads on startup so it stops asking "what business are we in?" every time you open it.

I type claude in my Headphones.com folder. Before I type a single word of prompt, Claude already knows what my business sells, who my customers are, where the important files live, and what tone I write in. I ask a question that would have taken three paragraphs of setup in a chat tab. The answer comes back in seconds, already in my voice, already referencing the right files.

The thing doing that work is a single text file in the folder. It's called CLAUDE.md. (A [markdown file][3] is just a text file with light formatting. You don't need to be a developer to open one.)

What it is

CLAUDE.md is the brief Claude reads on startup, every session, without you doing anything.

It lives at the root of your project folder, named CLAUDE.md (the capitals matter). When you type claude in that folder from the terminal (which fires up Claude Code), the first thing Claude Code does is read that file and treat it as system context for the conversation that follows. By the time you write your first prompt, Claude already knows whatever you put in there.

There's also a user-level version at ~/.claude/CLAUDE.md in your home directory that applies to every Claude session on your machine, regardless of folder. Claude reads both and combines them. I spend a lot of time on the user-level version because I know it will work with every project I’m working on - and I have multiple companies so I’m working on a lot of things simultaneously.

Why it matters

Before I wrote my first CLAUDE.md I would open a chat tab, paste a context paragraph about my business, ask my question, and lose the conversation when I closed the tab. Sure ChatGPT got “memory” after a while, but I didn’t have much control over what it remembered.

The unlock: without a CLAUDE.md, the first ten minutes of every Claude session is you re-explaining your business and how you like things done. With a CLAUDE.md, Claude fires up with full context. That ten minutes is not the worst thing on its own. The worst thing is the invisible tax. The questions you don't ask because you can't be bothered to re-paste the setup. The decisions you don't run by Claude because the context cost is too high.

A working CLAUDE.md flips the economics. The marginal cost of asking a context-rich question drops to zero. You start asking questions you never used to ask, because they used to be too expensive to set up.

The closest existing DeskTheory piece on this same instinct, applied at the company level rather than the folder level, is [the company brain you can hand to AI][1]. CLAUDE.md is the per-folder version of that same memory pattern.

What a good one looks like

A good CLAUDE.md reads like the onboarding doc you would hand to a smart contractor on their first day, not a config file. Six categories cover almost everything:

• What your business does. Revenue scale, customers, market, business model. Specific numbers beat ranges. "$12M ARR ecommerce, 8,000 paying customers" beats "growing SaaS."
• File and folder conventions. Where things live; how files are named; what NOT to touch. The agent should know where the analytics queries are without having to ask.
• Tone and writing rules. Your voice. What to imitate, what to avoid. (For Desk Theory, that is a summary of voice-profile.md.)
• Common commands and tools. Scripts you run weekly, CLIs the agent should know about. If you use gws to read Gmail or npm run learn to extract voice principles, name them.
• Who is on your team and what they own. First names and roles. Lets Claude write context-aware emails and drafts.
• What NOT to do. Hard boundaries: security, scope, sensitive folders, destructive commands you do not want run without confirmation.

Aim for one screen on a laptop, roughly under 80 lines. CLAUDE.md gets read on every session, so bloat eats your context window. Write tight.

Common mistakes

Treating it like a config file. It is not a settings file; it is a brief. Write it like you are onboarding a smart contractor on day one, not configuring a piece of software.

Stuffing every detail. Claude reads CLAUDE.md every session. Every line costs context window. If a section is not load-bearing, cut it. Aim for under one screen.

Letting it go stale. A CLAUDE.md that says ARR is $5M when it is $12M is worse than no CLAUDE.md. Claude acts on what it reads. Treat it as a living doc; revisit monthly.

Putting secrets in it. CLAUDE.md gets committed to git. No API keys, no passwords, no investor names you would not put in a public deck. If it should not leak, it does not go in.

Writing it once and never iterating. The good CLAUDE.md grows over a few months as you notice what Claude keeps missing. The version you write on Saturday is the worst version of it you will ever have.

Do this next

The thirty-minute setup is its own article: [how to set up your CLAUDE.md file][4]. Walk through it, then come back. The companion primitive is [skills][2], which is what turns a context-rich Claude into one that actually does the work for you.

[1]: /articles/claude-memory [2]: /articles/what-are-skills-in-claude-code [3]: /articles/what-is-a-markdown-file [4]: /workflows/set-up-your-claude-md-file