Short answer: CLAUDE.md is a plain-text file that Claude Code reads automatically at the start of every session. It holds the standing context about your business, what you sell, where your files live, the rules the agent must never break, and how you talk to clients, so the agent stops starting from scratch. It is just a text file whose name ends in .md, you can have Claude create it for you, and it lives on your local computer where the agent reads it, backed up in GitHub so it is safe and shared. Codex users have the same thing under a different name: AGENTS.md.
What a CLAUDE.md actually is
Every time you open a fresh session with an AI agent, it wakes up with amnesia. It does not remember what your business does, which tools you use, what you told it last week, or the one rule you never want it to break. So you explain it all again. And again.
A CLAUDE.md ends that. It is a plain-text file that Claude Code looks for and reads automatically, before you type a single thing, at the start of every session. Whatever you put in it becomes standing context the agent always has. Think of it as the operating manual your AI employee reads before every shift, or the onboarding doc that means you never have to onboard them twice.
Codex users have the exact same thing under a different name, AGENTS.md. It works the same way. If you use both tools, you keep one file and point the other at it, which I will cover below.
Why it matters more than any clever prompt
The quality of what an agent does for you depends less on the wording of your request and more on how much it already understands about your business. A CLAUDE.md is the single highest-leverage thing you can set up, because it upgrades every session that comes after it.
Without one, the agent guesses. It uses a tone that is not yours, misses that a client is a major account, or touches something it should have left alone, all because nobody told it the context that lives in your head. With one, it drafts in your voice, respects your rules, and knows where things are. This is the concrete version of a habit I keep coming back to: connect it to your real business before you decide it cannot help. The CLAUDE.md is how the context stays connected between sessions instead of evaporating every time you close the laptop.
A bad CLAUDE.md and a good one
A CLAUDE.md fails in two directions: too vague to act on, or so bloated the agent ignores it. Start with the vague kind, because it is the most common first draft. It reads like a mission statement and gives the agent nothing it can actually use.
# About my business I run a consulting business. Please be helpful and professional. Help me with marketing and operations, and write in a friendly tone.
Now a strong one. Notice it names real systems, real rules, and how you actually talk, the things the agent cannot guess but desperately needs.
# Business context for my AI agent ## What we do People-operations consulting for mid-size manufacturers (200 to 2,000 employees). We sell HR audits, fractional HR support, and leadership training. ## Systems, and where things live - Email and calendar: Google Workspace (connected) - CRM and deals: HubSpot (connected) - Proposals and contracts: Google Drive, under /Clients// - Invoicing: QuickBooks ## Standing rules - Draft only. Never send anything to a client without my approval. - Anonymize client names in anything public or on the website. - Never quote a price below $8,000 without asking me first. ## How we talk to clients Direct, warm, no jargon. Match the tone in my sent emails. We say "we," not "I." ## Key people - Mike: partner, joins client sales calls with me. ## Do not - Do not touch anything in the /Archive folder. - Do not change pricing or copy on the live website.
The strong version is not longer for its own sake. Every line is something the agent would otherwise get wrong. That is the test for what belongs in the file: would the agent make a mistake without this? If yes, it goes in. If it is a vague nicety, leave it out.
Anthropic's own rules for a good CLAUDE.md
You do not have to guess at this. Anthropic publishes exactly what makes a CLAUDE.md work, and their guidance is refreshingly blunt: their docs say a bloated CLAUDE.md causes the agent to ignore your real instructions. Here are their rules, in plain business terms.
The one test that governs everything. For every line, Anthropic tells you to ask: would removing this cause the agent to make a mistake? If not, cut it. A CLAUDE.md holds the things the agent would get wrong without being told, and nothing else.
Keep it short. Anthropic caps it at about 200 lines and warns that longer files get followed less, because the rules that matter get lost in the noise. Aim for one page. Experienced users go shorter.
Anthropic even gives an include-and-exclude list. Translated out of developer language, it comes down to this.
| Put in (things it would get wrong without) | Leave out (noise that gets it ignored) |
|---|---|
| The exact tools you use and where files live | Anything the agent can already figure out on its own |
| Rules that differ from the obvious default | Generic advice like "be helpful" or "write clean code" |
| Standing rules and traps, like "never send to a client without my approval" | Anything that changes week to week |
| How you talk to clients, with one real example | Long explanations or tutorials |
| Key people and their roles | Passwords, keys, or anything secret |
Be specific enough to check. Anthropic's own examples are "use 2-space indentation," not "format code properly." Your business version: "never quote below $8,000 without asking me," not "price things appropriately." A rule you cannot grade is a rule the agent will not follow.
Treat it as a living document. Anthropic says to prune it when things go wrong and check it into version control so it improves over time. A stale CLAUDE.md is worse than none, because it feeds the agent confidently wrong information. Update it the moment the agent makes the same mistake twice.
The mistakes that make an agent ignore your CLAUDE.md
When an owner tells me their CLAUDE.md "does not seem to do anything," it is almost always one of these. They are the patterns that quietly break the file.
- Bloat. The most common one by far. People keep adding, on the theory that more context is better. It is the opposite. Independent research found that stuffing an agent's context file can make it perform worse than having no file at all, and Anthropic's own docs warn that a bloated file causes the agent to ignore your real instructions. More is not better. Sharper is.
- Vague platitudes. "Be helpful. Write professionally. Do your best." The agent already tries to do all of that. Lines it cannot measure are lines it skips, and they push your real rules further down the page.
- Rules that contradict each other. If one line says one thing and another says the opposite, the agent picks one at random and you can never tell which. Read the whole file through and delete the conflicts.
- A file that has gone stale. The systems moved, the prices changed, a rule stopped applying, but the file still says the old thing. Now the agent is confidently wrong, which is worse than knowing nothing. Treat it as a living document.
- Step-by-step how-tos. A CLAUDE.md holds standing facts and rules, not procedures. If you catch yourself writing a five-step recipe, that is a skill you build once, not a memory file.
What you need to create an .md file
This is where people freeze, because ".md file" sounds technical. It is not. Here is everything it requires.
- It is just a plain-text file. The only requirement is that its name ends in
.mdinstead of.txt. That is the whole format. - Markdown is plain text with light formatting. A
#at the start of a line makes a heading.##makes a smaller heading. A-makes a bullet. That is 90 percent of what you will ever use. No code, no software to buy. - You do not need to be technical. If you can write a Google Doc, you can write a CLAUDE.md.
You have three ways to make one, easiest first:
- Ask the agent to write it for you. This is the best option, and it is the one I use. With your email, calendar, CRM, and files already connected, paste the prompt below into Claude Code. It reads your real business and drafts the file for you, and it bakes in Anthropic's rules so the draft comes back tight instead of bloated.
- Run the
/initcommand. In Claude Code, typing/initgenerates a starting CLAUDE.md by looking at your setup. Then you refine it. - Write it by hand. Open any plain-text editor, type the sections from the good example above, and save the file as
CLAUDE.md. Done.
Here is the prompt. It assumes your systems are connected, and it hands the agent Anthropic's best practices so you do not have to.
Draft my CLAUDE.md file. Do not interview me first. Use what you can already see. Read everything you can access about my business: my website, email history, calendar, CRM and deals, invoices, proposals, contracts, client folders, and files. Then write a CLAUDE.md that follows Anthropic's best practices: - Keep it to about one page. Every line must be something you would get wrong without being told. If removing a line would not cause a mistake, leave it out. - Be specific enough to check. Not "price things well" but "never quote below $X without asking me." - Put in: what we sell and who buys it, the systems we use and where things live, the standing rules you must never break, how we talk to clients (match my real sent emails), and the key people. - Leave out: anything you can already figure out, generic advice, anything that changes weekly, long explanations, and never any passwords or keys. - Use short markdown headings and bullets so it is easy to scan. Show me the draft first and let me correct it. After I approve it, save it as CLAUDE.md.
Where to store it: local computer or GitHub?
Here is the honest answer to the question everyone asks. It is not stored "in the desktop app." The desktop app reads the file from your computer's own files. So the file has to live on your local computer, and that is not optional, because that is the only place the agent looks.
Two locations on your computer matter:
- Your global business memory: a file at
~/.claude/CLAUDE.md. This one loads in every session, on every project, automatically. Your core business context goes here. It is personal to your machine. - Per-project context: a
CLAUDE.mdplaced inside a specific project folder. The agent reads it when you are working in that project. Use this for anything specific to one website, one client, or one system.
So where does GitHub come in? GitHub is not where the agent reads the file from day to day. GitHub is where you keep it safe and shared:
- Backup and history. Your business memory is too valuable to live in only one place. In GitHub it is versioned, so you can see every change and never lose it.
- It travels with the project. Commit a project's CLAUDE.md to its GitHub repo, and the context follows the project anywhere, including onto a teammate's machine.
- Your team's agents inherit it. When you hand a project to someone else, their agent reads the same CLAUDE.md and starts with the same understanding you have. That is how a business scales this instead of it living in one person's head.
The short version: keep the working copy on your local computer where the agent reads it, and back it up in GitHub so it is safe, versioned, and shareable. Do both, because they do different jobs.
What about Claude Cowork?
A lot of business owners are starting in Claude Cowork rather than the Claude Code terminal, so it is worth being precise. CLAUDE.md is a Claude Code feature, it is a file Claude Code reads off your computer. Claude Cowork, the newer workspace for getting real work done without a terminal, does the same job through a different door: it has its own Instructions, a global instructions field in settings that applies to every session, and folder instructions tied to a project you point it at.
So the principle is identical on both surfaces, give the agent your standing business context once so it does not start cold, and the six rules above apply just the same: keep it short, be specific, no secrets, keep it current. Only the mechanism changes. In Claude Code you write a CLAUDE.md file. In Cowork you paste that same context into its Instructions. If you use both, keep one clear write-up of your business and put it in both places. The worst version, on either surface, is the one you never create.
Common questions
What is a CLAUDE.md file?
CLAUDE.md is a plain-text file that Claude Code reads automatically at the start of every session. It holds standing context about you and your business, what you do, your systems, your rules, and your voice, so the agent does not start from scratch each time. Think of it as the operating manual your AI employee reads before every shift.
Why does my AI agent need a CLAUDE.md?
Without one, the agent begins every session as a stranger who knows nothing about your business, so you re-explain the same context over and over and it makes avoidable mistakes. With one, it starts already knowing what you sell, where your files live, and the rules it must never break. It is the difference between onboarding a new hire every morning and having a team member who remembers.
How do I create a .md file?
A .md file is just a plain-text file whose name ends in .md. Markdown means plain text with light formatting: a hash for a heading, a dash for a bullet. You need no special software and no coding. The easiest way is to ask Claude Code to create it for you, or run the /init command, which drafts one by looking at your setup. You can also write it by hand in any text editor and save it as CLAUDE.md.
Where should I store my CLAUDE.md file?
It must live as a file on your local computer, because that is where Claude Code reads it automatically. Two spots matter: ~/.claude/CLAUDE.md is your global business memory that loads in every session, and a CLAUDE.md inside a project folder holds context for that project. It is not stored inside the desktop app; the app reads the file from your computer. Back it up and version it in GitHub so it is safe, travels with the project, and your team's agents get the same context.
What is the difference between CLAUDE.md and AGENTS.md?
They do the same job for different tools. Claude Code reads CLAUDE.md; Codex reads AGENTS.md. They are not interchangeable on their own. If you use both tools, keep one AGENTS.md and make your CLAUDE.md import it, so both agents read the same base context and you maintain it in one place.
Does Claude Cowork use CLAUDE.md?
Not as a file. CLAUDE.md is a Claude Code feature. Claude Cowork uses its own Instructions instead: a global instructions field in settings and per-folder instructions on the projects you point it at. The idea is the same, give the agent standing context so it does not start from scratch, but in Cowork you paste that context into the app rather than saving a CLAUDE.md file. If you use both, keep the same business context in both places.
How long should a CLAUDE.md be?
Short. Aim for about one page, and treat 200 lines as a hard ceiling. The file is re-read at the start of every session, so length has a real cost, and past a certain size the agent starts ignoring parts of it. Experienced users keep theirs well under a page. A tight, specific file beats a long, thorough one every time.
Why is my CLAUDE.md being ignored?
Usually because it is too long, so the important rules get lost in the noise, or because a rule is too vague to act on, or because two rules contradict each other. Remember that a CLAUDE.md is guidance, not a hard lock, so for anything that must never happen, like sending to a client without approval, keep a human approval step rather than relying on the file alone. Prune it, sharpen the vague lines, and remove the conflicts.
What makes a good CLAUDE.md versus a bad one?
A bad one is vague and generic: "I run a business, be helpful and professional." A good one is specific and short: what you sell and who buys it, the exact systems you use and where files live, the standing rules the agent must never break, how you talk to clients, and a short do-not list. Keep it to about a page. Specific beats long, because a bloated file is both ignored and expensive to read every session.
Set this up once and every session after it gets better, because the agent finally knows the business the way you do. It is the closest thing there is to giving your AI a memory. Start today: open your agent and ask it to draft your CLAUDE.md from what it already knows.
Go further: the Fable 5 prompt library has a ready-to-run prompt that builds this file for you, and here is how a prompt becomes an agent you can trust and how to turn your SOPs into agents.