Your Brain File: CLAUDE.md
CLAUDE.md is the file your agent reads every single session. It's the difference between an assistant that starts from scratch every conversation and one that already knows who you are, what you do, and how you want to be talked to.
- A persistent context file your agent reads automatically before every session.
- A working nine-section structure with concrete examples for what goes in each one.
- A pattern for keeping it sharp as your work and your priorities evolve.
Read this with Claude.
Want to read the guide AND fill in your own CLAUDE.md as you go? Hand the whole flow to Claude in one paste.
How this fits in the OS.
Claude Code installed and a workshop folder where the file can live.
Your personalization answers, working preferences, safety rules, and project context.
More consistent behavior across every later build, prompt, and troubleshooting session.
The problem this solves.
Think about the last time you brought in a new assistant, consultant, or colleague. How much time did you spend just explaining context? Here's how we work. Here's what I care about. Here's the background on this project. Here's how I like things formatted.
That's exhausting. And you do it every time with Claude. Every new chat starts completely blank. Claude has no idea who you are, what you do, what you've already tried, or what you care about.
CLAUDE.md fixes this.
It's a plain text file that lives in your workshop folder. When Claude Code starts, it automatically reads this file. Every interaction in that session begins with Claude already knowing everything inside it. It's your persistent context: the briefing memo your agent reads before every single session.
What this looks like in practice.
The fastest way to feel what CLAUDE.md does is to see the same request handled both ways.
"I need help writing an email to a client."
"Sure. What's the context? Who's the client? What's the project? What tone are we going for?"
"I need help writing an email to Sally at Pinnacle."
"On it. I'll use your formal-but-warm tone, reference the Q3 proposal we discussed last month, and keep it in bullets since she prefers those over long paragraphs."
Same request. Completely different starting point. The agent isn't smarter. It just knows you.
The nine sections of a good CLAUDE.md.
These are the nine sections /personalize fills in. Each one serves a specific job.
You don't write these nine sections from scratch. The /personalize command walks you through each one in plain English, drafts your answers, and writes them into your CLAUDE.md. You read the draft and approve before save.
(no-suggest).
/what-do-i-have, so the agent knows which shortcuts you already have.
As CLAUDE.md evolves, you do not have to update it manually either. Ask Claude in plain English: "Claude just drafted an email and almost sent it without my review. Add a rule to my CLAUDE.md: always confirm before any external send." Claude reads the file, suggests the edit, and writes it once you approve. Best paired with the discipline in Keep it tight: add a line when something goes wrong; cut a line when it stops mattering. This is also the easiest way to add the two useful sections /personalize does not create for you: just ask Claude to add a Rules section (your non-negotiables, like "don't send anything externally without confirming") and a My Machines section (your OS and specs, so the agent picks the right commands).
Garbage in, garbage out.
The difference between a mediocre CLAUDE.md and a great one is specificity. Compare:
"I'm a business owner."
"I want Claude to be helpful."
"I run a 7-person marketing agency in Nashville. We do brand strategy and content for mid-market B2B companies."
"Always confirm before sending external messages. Give me options when I ask for creative direction, not just one answer. Never use jargon I'd have to explain to a client."
Think of it like writing a job description for an assistant you're hiring full-time. What would they need to know on day one to do their job well?
Keep it tight.
Specificity matters. So does brevity. CLAUDE.md gets read at the start of every session, which means every line in it costs context. A bloated brain file slows the agent down and crowds out the room it has to think.
Boris Cherny, who leads Claude Code at Anthropic, runs a sharp version of this. His team's CLAUDE.md exists to capture corrections, not generic best practices. His operating rule: "Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time." And the discipline that follows: "Ruthlessly edit your CLAUDE.md over time. Keep iterating until Claude's mistake rate measurably drops." (Source: howborisusesclaudecode.com.)
For calibration: Boris's own example CLAUDE.md is around 30 to 50 lines. Most well-tuned brain files land between 50 and 300 lines. Anything past 500 lines is usually a sign there is bloat to cut, not depth to keep.
What that looks like in practice:
- Add when Claude trips. Notice Claude got something wrong? One sentence in CLAUDE.md telling it not to do that again. Move on.
- Cut when something stops mattering. Project finished? Rule no longer applies? Delete the line. The file is not an archive.
- Document the surprising, not the obvious. If Claude already does it right by default, the rule is not earning its keep. Reserve the file for the local gotchas Claude could not guess.
Every line should be there because Claude needed to be told.
What not to put in CLAUDE.md.
Three pitfalls that come up most:
- Secrets, API keys, passwords. CLAUDE.md gets read every session, and if your folder is tracked in git, the file gets committed alongside your code. Secrets belong in your password manager, never in the brain file.
- Third-person descriptions of yourself. Write "I run a marketing agency," not "Sally runs a marketing agency." The file speaks to Claude on your behalf, so first person reads more naturally and avoids the awkward agent-refers-to-you-in-third-person responses that follow.
- Long-form prose or autobiography. The file is an operating manual, not a story. If a paragraph reads like a memoir rather than a rule or a fact, it probably belongs in a doc your agent reads, not the briefing it loads every session.
My Tools and Accounts, and the no-suggest tag.
The My Tools and Accounts section is the inventory of what Claude can reach. As you wire up MCPs (Gmail, Calendar, Notion, the rest), this is where you list them. Accuracy matters. Claude will not suggest a tool it does not know you have.
The workshop template uses a categorized format with specifics in brackets, so Claude knows which of each tool to reach for:
## My Tools and Accounts
**Email:** [Gmail, account: sally@acme.com]
**Calendar:** [Google Calendar]
**Communication:** [Slack workspace: AcmeTeam]
**Project management:** [Notion]
**Note-taking:** [Obsidian vault at: ~/Documents/notes]Two patterns that pay off:
- Be specific about which account. Two Gmail accounts? Name them. Slack in a specific workspace? Say so. Claude reaches for the right one when you say "draft an email" or "post in Slack."
- Update it as your stack changes. Wire up a new MCP? Add it here. Stopped using a tool? Cut the line. The list should reflect today, not three months ago.
If a tool keeps coming up unprompted and you do not want that, add (no-suggest) after the name. Example: Bland (no-suggest). Claude can still use it when you ask directly, but won't bring it up on its own. Most people never need this; it's there if you do.
What changes for you.
The file is small. What it does to your working pattern isn't. Three shifts you'll feel:
- You stop re-explaining yourself every session. The mental overhead of "where do I start, how much context do I need to give" is gone. You start in the middle of the conversation, every time.
- You start writing instructions instead of giving commands. Your inputs change from "do this specific thing" to "here's how I want this kind of thing handled going forward," because you know it'll stick.
- You realize CLAUDE.md is one of the most valuable documents you own. Six months in, it's a living record of your role, your priorities, your working style, and everything your AI OS needs to serve you well. It's an asset, not a setup step.
The aha moment usually hits the third or fourth session, when Claude responds with a fluency that surprises you and you realize the file you wrote in one sitting is doing more work than you expected.
More than one brain file.
You are not limited to one CLAUDE.md. Claude Code reads the CLAUDE.md from whatever folder you are working in, which means you can have a different brain file for every project, client, or workspace.
Two patterns worth knowing:
- Per project. Each project folder gets its own CLAUDE.md with context specific to that work: client preferences, project conventions, deadlines, codebase rules, who the stakeholders are. Open the folder in Claude Code and the agent picks up the project context automatically. No more re-explaining the project every session.
- Per client. If you serve multiple clients, each client folder can have its own CLAUDE.md with their tone, brand voice, things to never mention, pricing rules. Switch clients by switching folders. The agent adjusts.
You can also keep a user-level CLAUDE.md in your home directory (~/.claude/CLAUDE.md on Mac, C:\Users\You\.claude\CLAUDE.md on Windows) that applies to every folder you open. Best for things that are true about you regardless of project: your name, your communication preferences, your default autonomy level. The project-level CLAUDE.md layers on top of the user-level one, adding the project-specific context. Set the universals once at the user level, the specifics per folder.
Most people start with one CLAUDE.md in their workshop folder. As your work expands, you create more. Each new context becomes its own briefed agent the moment you set foot in that folder.
Keeping it current.
CLAUDE.md is only as good as what's in it. The best users update it regularly. Good moments to update:
- When you finish a big project
- When your role or priorities change
- When you add a new tool or integration
- When you notice Claude keeps misunderstanding something about you
You do not have to do this by hand. The "Pro move" aside near the top of this card covers the pattern: tell Claude what changed, in plain English, and let it write the edit for you.
Where to go next.
Reading about CLAUDE.md is one thing. Writing yours is the actual work. Three natural next moves: