how to
How to write a CLAUDE.md file (with a template for non-developers)
To write a CLAUDE.md file, create a plain text file called CLAUDE.md in the folder where you run Claude Code, and fill it with the things you would otherwise re-explain every session: who you are, how you like to work, what Claude may and may not do, and where your files live. Keep it short (Anthropic suggests under 200 lines), write concrete rules instead of vague wishes, and update it whenever Claude makes the same mistake twice.
That is the whole idea. The rest of this guide shows you how to do it well, gives you a template you can copy, and covers the mistakes that make a CLAUDE.md quietly stop working.
If you have never opened Claude Code before, start with Claude Code for non-developers and come back. This guide assumes you can open it in a folder and type a message.
What a CLAUDE.md file actually is
Every Claude Code session starts with a blank memory. Anthropic's docs put it plainly: each session begins with a fresh context window. Yesterday's conversation is gone. If you told Claude last week that your clients are founders, not big companies, it does not know that today.
A CLAUDE.md file fixes this. It is a markdown file (plain text with a few symbols like # for headings and - for bullets) that you write and that Claude reads at the start of every session. Think of it as the briefing note you would hand a new assistant on their first morning, except the assistant reads it again every single morning.
A few facts from the official documentation worth knowing:
- Where it lives. The most common spot is the project folder itself:
./CLAUDE.mdor./.claude/CLAUDE.md. There is also a personal one at~/.claude/CLAUDE.mdthat applies to every project on your computer, and aCLAUDE.local.mdfor personal notes on one project that you don't want to share. - It loads automatically. CLAUDE.md files in the folder you launch from, and in the folders above it, load when Claude Code starts. Files in subfolders load when Claude works in those subfolders.
- It is guidance, not a lock. Claude treats the file as context, not enforced configuration. It will usually follow your rules, and the more specific and concise they are, the more consistently it does. If something must never happen, the docs point you to hooks, a separate feature that can block an action outright.
- There is a separate "auto memory". Claude Code can also keep its own notes about your corrections and preferences. That is Claude writing for itself. CLAUDE.md is you writing for Claude. You want both, but this guide is about the one you control.
Two built-in commands help:
/initgenerates a starting CLAUDE.md for you. Claude looks at the folder and writes a first draft. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it./memorylists your CLAUDE.md files and lets you open any of them in an editor. Picking one that doesn't exist yet creates it.
And to check which files actually loaded in a session, run /context and look under "Memory files".
One honest note: /init was built with code projects in mind. It looks for build commands and test instructions. In a folder full of client notes and proposals it will produce something, but you will rewrite most of it. That's fine. The five steps below are what you rewrite it into.
Why bother: the difference it makes
Without a CLAUDE.md, every session starts with you typing the same paragraph: "I'm a leadership coach, I work with first-time managers, keep emails short, never send anything without asking me." You forget a line, and the answer comes back generic.
With one, you open the folder and say "draft a follow-up for today's call with Sara". Claude already knows you, your clients, your tone and where Sara's notes are. That is the gap between a chatbot and something that feels like it works for you. If you are weighing this against a Claude Project in the browser, which has its own instructions box, Claude Code vs Claude Projects walks through the tradeoffs.
How to write a CLAUDE.md for your business, step by step
Open your work folder in Claude Code. Either run /init and clean up what it writes, or run /memory, pick the project file, and start from empty. Then work through these five sections in order.
Step 1: Say who you are and what the business does
Three to six lines. Who you are, what you sell, who you sell it to, and what a good week looks like. Claude can't infer any of this from your files, and it shapes every answer.
Be concrete. "I help people grow" tells Claude nothing. "I'm a career coach for mid-level engineers moving into management. I sell a 12-week programme and one-off sessions" tells it a lot.
Step 2: Write down how you work
This is your working style: tone, length, language, formats, the things you correct over and over. Anthropic's advice is to make instructions concrete enough to check. Their examples are about code ("use 2-space indentation" rather than "format code properly"), but the same rule applies to you:
- "Emails under 120 words, no greeting longer than one line" instead of "keep it short".
- "British English, no exclamation marks" instead of "sound professional".
- "Give me three options, then your pick" instead of "help me decide".
A good test: could you look at Claude's answer and say yes or no to whether it followed the rule? If not, rewrite the rule.
Step 3: Set what it may and may not do
This section matters more for a business than for a code project, because your files contain clients. List the limits plainly:
- what it can do on its own (read notes, draft documents, reorganise folders),
- what needs your yes first (anything sent to a client, deleting files, anything involving money),
- what it never does (share one client's details in another client's document, invent testimonials).
Remember the earlier point: these are instructions, not locks. They work well in practice, and in its default permission mode Claude Code also asks before it uses a tool for the first time, like editing a file or running a command. But for a hard "never", don't rely on a sentence alone.
Step 4: Map where things live
Claude can look around your folder, but it works faster and makes fewer mistakes with a map. A few lines are enough:
clients/holds one folder per client, withnotes.mdand session summaries.offers/has your current prices and programme descriptions.templates/has your proposal and invoice templates.
If you keep a longer document you want Claude to read too, like your service descriptions, you can pull it in with an import. Writing @offers/services.md on its own line inside CLAUDE.md loads that file alongside it. Imports keep the main file tidy, but the docs note they don't make it cheaper: the imported file still counts toward what Claude has to read.
Step 5: Add the corrections you keep repeating
The docs suggest adding to CLAUDE.md when Claude makes the same mistake a second time, or when you type the same correction you typed last session. This section starts empty and grows. Every time you catch yourself saying "no, I told you, we don't call them customers", that sentence goes here.
You can ask Claude to do it for you: "add this to CLAUDE.md". It will edit the file.
A copy-paste CLAUDE.md template for coaches and consultants
Copy this into a file called CLAUDE.md in your work folder, then replace everything in square brackets. Delete lines that don't apply. Don't add more until you need them.
# Working with [Your name]
## Who I am
- I'm [name], a [coach / consultant] for [who you serve].
- I sell [main offer, e.g. a 12-week programme] and [secondary offer].
- My clients are usually [describe them in one line].
- A good week for me: [e.g. 12 client sessions, one newsletter, two proposals out].
## How I work
- Write in [British / American] English. Plain words, short sentences.
- Emails: under [120] words, one-line greeting, end with one clear next step.
- When I ask for a decision, give me 2 to 3 options and say which you'd pick and why.
- Never use these words: [e.g. "synergy", "unlock", "journey"].
- Call them "[clients / members]", never "[customers / users]".
## What you may and may not do
- You may: read and organise anything in this folder, draft documents and emails, summarise notes.
- Ask me first before: deleting or moving client files, anything that sends a message, anything involving money or prices.
- Never: put one client's details in another client's document. Never invent quotes, results or testimonials.
## Where things live
- clients/[client-name]/ : one folder per client. notes.md has the running notes.
- offers/ : current prices and programme descriptions. Treat these as the truth.
- templates/ : proposal, onboarding email and invoice templates.
- drafts/ : put anything new here until I approve it.
## Corrections I keep making
- [Add a line here every time you correct Claude twice.]
That is about 30 lines. Most people's first version should look like this, not like a 20-page manual.
A realistic example
Say you're Maya, a business coach for therapists starting private practice. Her filled-in "who I am" reads: "I'm Maya, a business coach for therapists opening a private practice. I sell a 3-month launch programme and single strategy sessions. My clients are clinically strong and nervous about selling."
Now she opens the folder and types: "Draft a follow-up for Jonas after today's session, use my notes." Claude reads her CLAUDE.md, finds clients/jonas/notes.md from the map, writes under 120 words in her tone, saves it to drafts/, and doesn't send anything because her rules say ask first. She didn't explain any of that in the message. That's the payoff.
Common mistakes (and how to fix them)
It's too long. The most common one. Anthropic's guidance is to target under 200 lines per CLAUDE.md file, because longer files take up more of Claude's attention and reduce how well it follows them. If yours has grown into a manual, move the long procedures out. A multi-step process like "how I prepare a proposal" belongs in a skill (a saved, reusable set of instructions Claude loads only when the task comes up), not in the file Claude reads every time.
The facts are stale. You raised your prices in March and CLAUDE.md still says the old ones. Claude will happily quote them. Context rots quietly. Prices, current clients, this quarter's focus and team members change; your file has to change with them. If something changes often, keep it in its own file (like offers/prices.md) and point to it, so there is one place to update.
The rules contradict each other. "Always keep emails short" in one place and "always include a full recap" in another. The docs warn that when two instructions conflict, Claude may pick one arbitrarily. Read the whole file once a month with that in mind.
The rules are vague. "Be professional" and "do good work" don't change anything. If you couldn't check whether Claude followed it, it isn't a rule yet.
Treating it as a security system. It's a briefing, not a lock. Combine it with Claude Code asking before it acts, and keep a real backup of anything you can't lose.
Writing it once and forgetting it. A CLAUDE.md that never changes after week one is almost always out of date by week six.
Keeping it current
A simple routine works:
- When it repeats a mistake, add one line under "Corrections I keep making".
- When something in the business changes (prices, a new client, a new offer), update the file the same day. Ask Claude to do it: "update CLAUDE.md, the launch programme is now €1,800".
- Once a month, read the whole thing. Cut anything outdated, merge duplicates, move long procedures into their own files. Claude Code also has a built-in audit for this: running
/doctor prompt-auditasks Claude to look for outdated or conflicting instructions and propose edits, and nothing changes until you approve them. - Check it loaded with
/contextif Claude seems to be ignoring you. If your file isn't listed there, Claude can't see it.
Limitations to know about
A CLAUDE.md is a strong habit, not magic. Claude can still misread a rule or forget one in a very long session. It only covers what you wrote down, so gaps in the file become gaps in the answers. And it is one file: once your business has many recurring jobs, one file starts to strain, which is why Claude Code adds skills, rules folders and imports on top.
It also lives in one folder. If you use Cursor or another editor alongside Claude Code, they have their own ways of storing instructions; Claude Code vs Cursor covers how the two differ.
Where the AI-OS fits
Full disclosure: I built the AI-OS. It's a one-time setup that turns Claude Code into an operating system for your work, and a structured CLAUDE.md is the heart of it. Instead of one file, it ships a kernel CLAUDE.md plus separate files for context (who you are, current priorities, boundaries), a knowledge folder, and starter skills, so the parts that change often aren't buried in the file Claude reads every time. I run my own app, studio and content on it.
You don't need it to write a good CLAUDE.md. The template above, kept short and updated, will get most people a long way. The AI-OS is for when you want that structure already built, with a weekly habit of adding one new skill. If you want the bigger picture of what that means, read what is an AI operating system.
Next step
Copy the template, fill in the five sections in under 30 minutes, and use Claude Code for a week. Every time you correct it twice, add a line. At the end of the week, read the file top to bottom and cut what didn't earn its place. If you're still setting up Claude Code itself, the setup guide walks through the install.