What Should I Put in CLAUDE.md?
Put in CLAUDE.md the facts and preferences Claude can't work out by looking at your files: what this folder is for, how you want things written, how Claude should check its own work, where things live, and anything you've had to correct twice. Keep it short and specific, and group it under a few plain headings.
CLAUDE.md is a plain text file that Claude Code reads at the start of every session, so it is the one place where you write something once and stop repeating it. I'm not a developer, and my own CLAUDE.md is mostly about how I want Claude to talk to me and how I want it to work, not about code. This post gives you the same thing for your situation: what goes in, what stays out, a starter to copy, and where the file lives.
Where the CLAUDE.md File Lives
There are a few places the file can go, and the docs list them from widest to narrowest. Here they are as a folder picture, using a made-up folder called my-business:
- Your whole computer (every project): your home folder > .claude > CLAUDE.md. The path is ~/.claude/CLAUDE.md, where ~ means your home folder. This is for preferences that follow you everywhere.
- One project: my-business > CLAUDE.md. This sits at the top of the folder you open in Claude Code, and it holds instructions for that folder.
- One project, private to you: my-business > CLAUDE.local.md. Same idea, but for notes you don't want to share with anyone else who uses the folder.
- Deeper folders: my-business > newsletter > CLAUDE.md. Claude loads a file in a subfolder only when it starts working with files in that subfolder.
Claude Code reads the CLAUDE.md in the folder you started in and in every folder above it, and it joins them together instead of picking one. That means the folder you open matters. If you open a different folder than the one that holds your CLAUDE.md, Claude won't see it.
Not sure which file to start with? Start with a project file in the folder you work in most. Add a personal ~/.claude/CLAUDE.md later for things that are true everywhere, like how you like to be spoken to.
What Belongs in a CLAUDE.md
Anthropic's guidance is that a CLAUDE.md works best when it only holds what Claude couldn't work out from your files. Every line takes a little of Claude's attention on every task, whether it's relevant or not. Their test for what stays: how to confirm work is right, places where things are misleading, decisions that aren't written down anywhere, and anything you've had to correct twice already.
Here is that test translated for someone who isn't writing code:
- What this folder is and who it's for. One or two lines: 'I run a bookkeeping practice for freelancers. This folder holds my client emails and my newsletter drafts.' Claude can't guess your business.
- How you want things written. Words to use, words you hate, how formal it is, a file that shows the tone you want. Specific beats general every time.
- How to check the work. The docs say the most useful line is often the one that tells Claude how to confirm it's done. For you, that may be 'reread the draft against the brief and list anything missing' or 'open the page and tell me what you see'.
- Where things live. 'Drafts go in the drafts folder. Finished work goes in the done folder.'
- What not to touch. A folder or file Claude should leave alone.
- Things you've told it twice. This is the best section. Anthropic's advice is to add a line the second time you make the same correction.
The docs also say to be concrete enough that a line can be checked. 'Use 2-space indentation' works better than 'format code nicely.' The same holds for writing: 'Use short sentences and plain words' works better than 'write well.'
What to Leave Out
- Things Claude can figure out by reading your files, like a list of what's in each folder. Anthropic's /doctor prompt-audit command (covered below) flags this kind of content.
- Long, multi-step procedures. The docs say to move those into a skill, which is a saved set of instructions Claude loads only when it's relevant. See Claude Code skills vs MCP servers.
- Rules that can never be broken. The docs say CLAUDE.md shapes Claude's behavior but isn't enforced, and a rule with no exceptions belongs in a hook, which is a setting that runs automatically. Adding the word IMPORTANT, per the docs, probably won't fix a line Claude ignores.
- Contradictions. If two lines disagree, Claude may pick one arbitrarily. Delete the one you don't mean.
- Passwords, keys and private numbers. This is my advice, not Anthropic's: a CLAUDE.md is a plain text file that can be shared, so write it like a document someone else might read.
Length matters too. The docs recommend staying under 200 lines per file, because longer files use more of Claude's attention and make it follow them less reliably. Group lines under headings so the file stays easy to scan.
A Copy-Paste Starter for Non-Coders
Two ways to get this on your computer. The fast way is to paste the message below into Claude Code with your project folder open. Claude will interview you and write the file.
- Create a file named CLAUDE.md in this folder. Use these five headings: About me and this folder, How I like you to write, How to work with me, Where things live, Things I've told you twice. Interview me one question at a time, then fill in each heading with short, specific bullet points from my answers. Keep the whole file under 60 lines and show it to me before you save it.
The other way is to copy the starter below yourself. Each line is one line of the file. A line starting with a hash mark is a heading, and a line starting with a dash is a bullet. Ignore the dots the page adds, and swap each bracketed part for your own words. Ask Claude to create the file for you ('create CLAUDE.md in this folder with the text below') so it gets the right name and plain text format.
- # About me and this folder
- - I run [what you do, in one sentence]. This folder holds [what's in it].
- - The people I write for are [your audience or clients].
- # How I like you to write
- - Plain words and short sentences. No jargon unless I use it first.
- - Never use these words: [words you hate].
- - For the tone I want, match the examples in [a file name].
- # How to work with me
- - Before you change or delete a file, tell me which one and why, and wait for my yes.
- - If my request could mean two things, ask me one question before you start.
- - When you finish, tell me in two sentences what you changed and where to find it.
- - Before you say you're done, check your work against my request and list anything that's missing.
- # Where things live
- - Drafts go in [folder name]. Finished work goes in [folder name].
- - Never touch [folder or file name].
- # Things I've told you twice
- - [Each time you correct Claude a second time, add the correction here.]
That is under 20 lines. It will grow slowly, which is how it should grow. The 'Things I've told you twice' section is the one that earns its keep.
What to Add for Your Kind of Project
The starter works for most folders. If your project is one of these four common types, add a few lines on top of it.
Extra lines to add to the starter, by project type
| Project type | Add these to your CLAUDE.md |
|---|---|
| Web app or SaaS | The framework and language by name, where pages and shared code live, the exact commands to start it, test it and deploy it, and a line like 'never touch production data'. |
| Client or agency build | Whose project it is, which environment is the practice one and which is live, what Claude may touch, what is in scope, and 'never share client logins'. |
| Automation or scripts | What triggers it, what it reads and what it changes, how to do a safe test run, and 'never send, delete or spend without asking me first'. |
| Content or marketing site | Who the site speaks to, a short do and do-not list for the voice, where new pages go, and how to preview a change before it goes live. |
In every case, name the real folder, file and command instead of describing them. Keep it current: when you change how the project works, change the line in the same sitting, because an out-of-date file is worse than a short one.
Before and After: What a CLAUDE.md Changes
Here is an example of what changes. Say you run a small bakery and you write your weekly newsletter with Claude. Without a CLAUDE.md, you start each session by explaining yourself again. With one, you skip straight to the work.
An example: the same request, without and with a CLAUDE.md
| Before (no CLAUDE.md) | After (with CLAUDE.md) | |
|---|---|---|
| What you type | 'Write this week's newsletter. It's for my bakery customers. Keep it friendly, no emojis, short sentences, and don't mention prices. Put it in the drafts folder.' | 'Write this week's newsletter about the new sourdough.' |
| What Claude knows | Only what you typed in this one message | Who the customers are, the tone, the no emojis rule, and where drafts go, from the file |
| Next week | You type the same five rules again | You type one sentence again |
The five rules you'd otherwise type become five lines in the file. And when you notice you corrected something again, like 'don't start with a question,' you add that line once.
How to Check It Worked and Keep It Healthy
To confirm Claude loaded your file, type /context all and look under Memory files. Your CLAUDE.md should be listed. To open or edit it any time, type /memory, which lists your CLAUDE.md files and opens whichever you pick. If a file you choose doesn't exist yet, /memory creates it first.
There is also a built-in command, /init, which creates a starting CLAUDE.md. The docs describe it as analyzing your codebase for build commands and conventions, so it is built for code projects. If your folder is documents and drafts, the interview message above will give you a better first file.
Every few weeks, run /doctor prompt-audit (it needs Claude Code version 2.1.283 or later). Anthropic describes it as a check for instructions that are outdated, point to files that don't exist, or contradict each other. It gives you a report, and nothing changes until you ask Claude to apply the edits.
Common Problems
- Claude doesn't seem to know what's in my file: open the folder where the file lives in Claude Code, then run /context all. The file must be in the folder you started in or one above it.
- Claude follows some lines and not others: make each line specific and short, and cut contradictions. The docs say vague or conflicting lines are followed less reliably.
- The file keeps growing: if it passes about 200 lines, move the long or one-off material into a skill and keep the rest.
- Claude ignores a rule I truly can't have broken: CLAUDE.md is guidance, not enforcement. A hook is the tool for that.
- I'm not sure my text file saved right: ask Claude to create or edit the file instead of making it yourself, so the name and format are correct.
Where to Go Next
Once your CLAUDE.md is in place, What is plan mode? shows how to use it on bigger jobs, and Claude Code skills vs MCP servers explains where long procedures belong instead. For rules that can never be broken, see hooks that earn their keep. If you want other people to build alongside, Claude Code Club is $9/month.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is a CLAUDE.md file?
It is a plain text file of instructions that Claude Code reads at the start of every session. You write it in ordinary language, and it carries your preferences and project facts into every new conversation.
Where do I put my CLAUDE.md file?
Put a project file named CLAUDE.md at the top of the folder you open in Claude Code, or a personal one at ~/.claude/CLAUDE.md for every project. Claude reads the files in the folder you started in and the folders above it.
How long should a CLAUDE.md be?
Anthropic's docs recommend under 200 lines per file. Longer files use more of Claude's attention and are followed less reliably, so keep it short and specific.
Do I need to run /init?
No. /init creates a starting CLAUDE.md by analyzing a code project. If you aren't writing code, you can paste the starter above or ask Claude to interview you and write the file.
Will Claude always follow my CLAUDE.md?
Mostly, but not with a guarantee. The docs say Claude treats CLAUDE.md as context, not enforced configuration. Specific, short, non-contradicting lines work best, and rules that can never be broken belong in a hook.
Last reviewed by Duncan Rogoff on November 9, 2026
