Short answer: The single highest-leverage Claude Code best practice is not a prompt trick or a plugin. It is a markdown file at ~/.claude/CLAUDE.md that the tool reads automatically at the start of every session. Mine holds my business context, standing rules, project locations, brand voice, and hard boundaries. It turns every session from a cold start into a briefed staff member. If I could only keep one thing from my entire AI setup, this file is it.
Key Takeaways
- CLAUDE.md is a plain markdown file Claude Code loads automatically at the start of every session, no setup beyond creating it.
- Without it, every session starts cold and you re-explain your business, stack, tone, and rules. That tax compounds across hundreds of sessions.
- The file should hold rules, not conversation: mission, never-do lists, project paths, credential policy, voice, and review gates.
- Every repeated correction is a missing rule. Write it down once and the mistake stops across all future sessions.
- Never put credentials in the file. Put the rule for where credentials live instead.
- A first useful version takes about 30 minutes to write and pays back the same week.
Most people who use Claude Code do not know this file exists. The ones who do often do not realize how much it changes things. This post is the full walkthrough: what the file is, what mine contains, what belongs in yours, and the mistakes I made so you can skip them.
The file most Claude Code users never create
Claude Code is Anthropic's command-line agent. You type what you want in plain English and it reads files, writes code, runs commands, and finishes tasks. The official documentation covers the mechanics well. What it undersells is a simple behavior: at the start of every session, the tool looks for a file called CLAUDE.md and loads whatever it finds into context before you type a single word.
There are two places it looks. A global file at ~/.claude/CLAUDE.md applies to everything you do on the machine. A per-project CLAUDE.md in any folder applies when you work in that folder. Both get read. That means anything you write in those files becomes a standing instruction the AI follows in every session, automatically, forever, until you change it.
Without the file, every session starts cold. You re-explain your business, your tone, your stack, your rules, your projects, every time. You correct the same mistakes. You watch it suggest WordPress when you moved everything to Vercel a year ago. You catch it writing in a corporate voice you have never once used. None of that is the model being dumb. It is the model being unbriefed.
With the file, the session starts the way a good staff meeting starts: everyone already knows the mission, the rules, and where things live. The first message you type is the actual work.
What cold starts actually cost
Put numbers on it, because the cost hides in small pieces. Before I built my file, a typical session started with three to five minutes of context setting: what the business is, what the project is, where the code lives, what not to touch. Call it four minutes. I run multiple sessions a day across three businesses. At even six sessions a day, that is 24 minutes of daily re-briefing, roughly two hours a week, over a hundred hours a year. For nothing. The same sentences, retyped.
The retyping is not even the worst part. The worst part is what happens when you skip it because you are in a hurry. The AI fills the gaps with defaults. Defaults are how you get a config file overwritten, a credential pasted into code, an email drafted in a voice that is not yours, or a suggestion to rebuild something that already exists and works. Every one of those costs more than the four minutes would have.
My file ended both problems at once. The briefing happens in milliseconds at session start, and the dangerous defaults are overridden by written rules. I estimate the file saves me the hundred hours a year directly and prevents a mistake that would have cost real money about once a month.
What actually lives in my file
Mine has grown with the businesses, but the structure has stayed stable. Here are the sections, in the order they appear, with why each one earns its place.
1. Mission, in two sentences
The top of my file states what all of this is for: building a portfolio of real estate and businesses I own outright, with AI doing everything AI can do so I spend my time on the things only a human can do. That sounds soft, but it is load-bearing. When an agent has to make a judgment call between two approaches, the mission is the tiebreaker. An AI that knows the goal is owner time and portfolio compounding makes different micro-decisions than one optimizing for clever code.
2. The never-do list
The most valuable section, and the one I recommend everyone write first. Mine includes: never touch specific config files directly, never set multiple API keys at once, never hardcode credentials anywhere, never use WordPress for any site, never ask me to paste a key manually. Every line exists because something went wrong once. That is the pattern to internalize: a never-do list is not written in advance, it is accumulated. Each entry is a scar with a lesson attached.
3. Credential policy
My file tells every session to check my password manager's CLI first before asking for any credential, and exactly which vault to look in. The keys themselves are never in the file. This one rule removed an entire category of friction and an entire category of risk. Sessions stopped asking me to paste secrets, and secrets stopped appearing in files where they did not belong.
4. Project locations
A plain list: this business's site lives here, that tool lives there, the deal pipeline is in this folder. Without it, the AI searches, guesses, or asks. With it, "fix the pricing section on the landing page" resolves to the right folder on the first try. This section alone kills half the back-and-forth in a working session.
5. Brand voice and writing rules
Warm, direct, human, no corporate speak, and no em dashes anywhere in copy. Fonts, colors, tone. Anyone who has tried to keep AI writing on-voice knows the drift problem: it slides toward the generic middle. A written voice spec in the standing file keeps every draft, every email, every page starting from my voice instead of the internet's average voice.
6. Protected systems and review gates
Some things are irreplaceable. My file names them and sets the rule: build changes in a branch, never deploy to production without me reviewing staging and explicitly saying deploy. This is the human review gate written down as infrastructure. The AI does not have to remember it or infer it. It reads it, every session, before it can forget.
7. Decision authority
After an agent once drafted a full pricing strategy that looked so polished it nearly went live before I noticed I had never approved it, I added a rule: anything an agent writes that touches pricing, offers, or public claims is a draft until I explicitly adopt it, and every strategy doc carries a status line saying which it is. That rule turned a near-miss into a system. This matters more as you run more AI, not less. The failure mode of a good AI team is not bad work. It is unapproved work that looks approved.
How to write your first one in 30 minutes
You do not need to be technical. If you can write a one-page memo to a new assistant, you can write this file. Here is the sequence I give clients.
Minutes 1 to 5: the mission. Two or three sentences. What is the business for, and what is AI's job inside it. Do not overthink the wording. You will sharpen it later.
Minutes 5 to 15: the never-do list. Think back over the last month of AI use. Every time you corrected the same thing twice, that is an entry. Every tool you have abandoned, name it so the AI stops suggesting it. Every file or system that must not be touched, list it. Aim for five to ten lines.
Minutes 15 to 22: locations and stack. Where do your projects live. What is your stack: hosting, frameworks, database, email. One line each. The AI should never have to guess whether you deploy to Vercel or somewhere else.
Minutes 22 to 28: voice. Three to six rules for how you sound. Include the negative rules, they work better than the positive ones. "No corporate speak" and "no em dashes" do more work than "be friendly."
Minutes 28 to 30: review gates. Name the one or two things that must never ship without your eyes on them. Money, pricing, public claims, production deploys. Write the gate as a rule.
Save it to ~/.claude/CLAUDE.md, start a new session, and ask the AI to do something you do weekly. You will feel the difference in the first exchange.
What belongs in the file, and what does not
The file is for rules, not conversation. This table is the sorting logic I use.
| Content | In CLAUDE.md? | Why |
|---|---|---|
| Mission and business context | Yes | Tiebreaker for every judgment call the AI makes. |
| Never-do rules and past-mistake lessons | Yes | Cheapest way to stop a repeated error permanently. |
| Project paths and stack choices | Yes | Kills guessing and wrong-folder work. |
| Voice and formatting rules | Yes | Prevents drift toward generic AI writing. |
| Credential policy (where keys live) | Yes | Sets the retrieval rule without exposing anything. |
| Actual credentials or API keys | Never | The file is plain text read into every session. Keys go in a password manager. |
| Today's task details | No | Session context, not standing rules. It goes stale by tomorrow. |
| Long documentation or SOPs | No | Link or reference the doc's path instead. Keep the file lean. |
| Rules you hope you might need someday | No | Speculative rules rot. Add rules when reality earns them. |
The one-sentence test: if you would say it to a new hire on their first day and expect it to still be true in three months, it belongs in the file. If it is about this week's work, it does not.
How the file compounds when you run more than one agent
I run AI agents across three businesses: an AI voice product, a lending brand, and my consulting and acquisition work. The standing file is what keeps them coherent. Every session, every agent, every model starts from the same mission, the same rules, the same boundaries. When I switch models or a new model ships, the file carries over untouched. My accumulated operating knowledge is not trapped inside any one tool or vendor. It is a text file I own.
That portability is worth sitting with. Most AI setups are stacked on a specific product, and when the product changes, the setup dies. A markdown file survives every migration. I have changed models, changed tools, and restructured my whole agent team since I first wrote mine. The file came along each time and got sharper. If you want the deeper version of how the multi-agent side works, I wrote up how I run a 10-agent AI team across three businesses, and the standing file is the foundation under all of it.
Where this shows up in acquisitions
The clearest example of the file paying for itself is deal screening. I look at multifamily deals in the 24-unit-and-up range and small local service businesses. My standing rules encode my buy box: what markets, what structures I will consider, what automatically kills a deal, and the rule that AI prepares the screen but never makes the buy decision. When a listing or a CIM comes in, a session can produce a first-pass screen that is actually aligned with how I buy, because the criteria are standing context rather than something I retype per deal.
Before the file, every screening session needed the buy box re-explained, and any shortcut meant the AI evaluated the deal against generic criteria that are not mine. After the file, screening a new deal starts at the analysis instead of the briefing. Multiply that across every deal that crosses my desk in a year and it is days of owner time returned. The same pattern shows in my AI deal flow system for multifamily: the pipeline does the volume, the standing rules keep the volume pointed at what I would actually buy.
Maintaining the file so it stays true
A standing file only works if it stays accurate, and there are two failure modes. The first is staleness: a rule that was true in March and wrong by June. A stale rule is worse than no rule because the AI follows it confidently. The second is bloat: rules pile up, the file balloons, and the important rules drown in the noise.
My maintenance system is two habits. First, the twice rule: every time I correct the AI on the same thing a second time, I stop and add the rule right then, in the moment, not later. A repeated correction is a missing rule, full stop. Second, a monthly prune: I read the file top to bottom once a month and delete or rewrite anything that is no longer true. The read takes ten minutes. It is the highest-ROI ten minutes in my AI operation.
Keep the global file to rules that apply everywhere, and push project-specific rules down into per-project CLAUDE.md files. My global file holds mission, credentials policy, voice, and never-dos. The file inside each project holds that project's stack quirks, deploy process, and local landmines. The layering keeps both files short enough to stay true.
The mistakes I made so you do not have to
I wrote it too long at first. My early version tried to document everything, including how-to content that belonged in separate docs. Sessions got noisier, not sharper. The fix was ruthless: rules stay, explanations move out, documentation gets referenced by path instead of pasted in.
I let dead rules linger. I kept a rule about a tool I had stopped using, and the AI kept accommodating a workflow that no longer existed. Now the monthly prune catches these.
I wrote positive rules when negative ones work better. "Write warmly" did less than "no corporate speak, no em dashes, no fake urgency." Negatives are testable. The AI either violated the rule or it did not.
I forgot the file is not private magic. It is plain text loaded into context. Anything in it shapes every session, including things you wrote carelessly. Treat every line as an instruction that will be followed literally by something very fast and very consistent, because it will be.
I waited too long to write it at all. I used Claude Code for weeks before creating the file, re-explaining myself every session and assuming that was just the cost of the tool. It was not. It was the cost of an unbriefed tool. If you are getting started with AI in your business more broadly, the same lesson generalizes, and I cover the wider version in how to integrate AI into your small business: the setup work that feels optional is usually the work that determines whether the whole thing pays off.
How to know it is working
Three measures, all simple. First, count corrections: how many times per week do you re-explain something the AI should already know? That number should trend toward zero, and every remaining correction should become a new line in the file. Second, time to useful output: how long from opening a session to the first genuinely usable result? Mine dropped from minutes of setup to essentially immediate. Third, incident rate: how often does the AI do something you explicitly did not want? Each incident is either a missing rule or an unclear one, and both are fixable in the file within a minute.
If those three numbers do not improve within two weeks of writing the file, the file is wrong, not the idea. Usually the fix is deleting vague lines and replacing them with specific ones.
FAQ
What is a CLAUDE.md file?
A plain markdown file that Claude Code reads automatically at the start of every session. It holds your standing instructions: business context, rules, project locations, voice, and boundaries, so you never re-explain them.
Where does the CLAUDE.md file live?
The global file lives at ~/.claude/CLAUDE.md and applies to every session on the machine. A per-project CLAUDE.md in any folder adds rules specific to that project. Claude Code reads both.
How long should a CLAUDE.md file be?
Short enough to stay true. Mine is a few hundred lines after a year of accumulation. Every line should be a rule you actually want enforced. A bloated file with stale rules is worse than a short accurate one.
What should never go in a CLAUDE.md file?
Credentials, API keys, passwords, or anything sensitive. The file is plain text loaded into every session. Put the rule for where credentials live in the file, never the credentials themselves.
Do I need to be technical to use one?
No. It is a text file written in plain English. If you can write a one-page memo briefing a new assistant, you can write a CLAUDE.md.
How often should I update it?
Every time the AI makes the same mistake twice, add the rule immediately. Then prune the whole file monthly so dead rules do not accumulate.
Does this work with other AI tools?
The specific auto-loading behavior is Claude Code's, but the principle ports everywhere: a written standing brief beats repeated verbal context in any AI tool that accepts instructions. The file itself is portable text you own, independent of any vendor.
Work With Me
If you want help turning AI from a pile of tools into a business operating system, with standing rules, review gates, and owner-level clarity, book a strategic AI consulting call. This file is usually the first thing we build together, because everything else runs better on top of it.
Author
Tamara Ashworth, 7-figure agency exit, 15-person team, and $60M in client revenue generated. Learn more about Tamara.
This content is for informational purposes only and reflects my operating perspective. It is not legal, tax, financial, or investment advice.