Most people who use Claude Code write a CLAUDE.md file once, put ten bullet points in it, and call it done. Then they wonder why Claude keeps making the same mistakes, ignoring project conventions, or responding like a generic assistant rather than someone who knows their codebase inside and out.
The file is not the problem. The approach is.
CLAUDE.md is not a configuration toggle. It is the difference between Claude operating as a capable but amnesiac contractor and Claude operating as a senior team member who has been embedded in your project for months. Getting that distinction right is the entire game of Claude Code power usage.
This guide covers what CLAUDE.md actually does, the five mistakes that undermine it, the four-section structure that consistently produces the best results, and when it makes sense to use a production-tested Brainfile configuration instead of building from scratch.
Every time you start a Claude Code session, Claude reads CLAUDE.md before doing anything else. This is not a one-time setup step — it happens on every session, every time. The file loads as project context automatically, which means everything in it is active from the first message.
This is fundamentally different from how most people think about configuration files. It is not a .gitignore or a tsconfig.json that constrains a tool. It is closer to a briefing document that Claude reads before showing up to work. The quality of that briefing determines the quality of everything that follows.
Claude does not have persistent memory between sessions by default. Every session is a fresh start. CLAUDE.md is the mechanism that bridges that gap — it is how you make Claude's behavior consistent and project-aware across every session without repeating yourself.
The mental model that works: Imagine hiring a new contractor every morning. The person is brilliant, but they arrive knowing nothing about your project. CLAUDE.md is the document you hand them on the way in. What would you put in it? That question is more useful than any list of best practices.
A CLAUDE.md written during the first week of a project is already stale by week three. The tech stack changes. New conventions emerge. Decisions get made. If your file does not evolve with the project, Claude is working from an outdated briefing — and outdated context is often worse than no context, because Claude will confidently follow rules that no longer apply. Treat CLAUDE.md like living documentation. Update it when anything significant changes.
There is a practical limit to how much of a single file Claude will apply with full reliability. Once you pass roughly 15 rules in a single file, the later rules start competing with the earlier ones for attention. The fix is not to write fewer rules — it is to use the .claude/rules/ subdirectory, where domain-specific rules live in separate files and load contextually. Your main CLAUDE.md should be a focused briefing, not a policy manual. Put the policy manual in rules/.
Vague rules produce vague compliance. "Write clean code" means nothing. "Write clean code — for example: prefer explicit variable names over short abbreviations (userCount not uc), return early on errors rather than nesting, keep functions under 30 lines" produces something Claude can actually apply. For every behavioral rule, include at least one concrete example of what you mean. The delta in output quality between rules-with-examples and rules-without is not small.
"Be helpful" is not an instruction. "Always respond in under 200 words unless the question requires code or step-by-step instructions" is an instruction. The specificity test: could two different people read this rule and independently produce the same output? If the answer is no, the rule is too vague. Every instruction in CLAUDE.md should be verifiable. If you cannot tell whether Claude is following it, you cannot enforce it.
Claude is much more useful when it knows where things live. What is the entry point? Where do tests go? What is the naming convention for new files? Which directories are generated and should never be edited manually? Without this map, Claude guesses — and guesses correctly often enough to seem reliable, but incorrectly often enough to create subtle problems. A project architecture section is not optional for any non-trivial project. It is the difference between Claude knowing your codebase and Claude learning it by trial and error every session.
After running Claude Code across multiple projects and thousands of sessions, the structure that produces the most consistent results has four sections. Every section earns its place. None is interchangeable with the others.
What this project is, in plain terms. Not the marketing description — the operational one. What does this thing do? Who uses it? What is the primary language? What are the business constraints Claude should always keep in mind? This is the context that frames every subsequent instruction. Without it, Claude treats every task as isolated. With it, Claude treats every task as part of a coherent whole.
The technical facts Claude needs to never guess about. Language versions. Key dependencies. File structure. Which directories matter and what lives in each one. How builds work. Where environment variables come from. How tests are run. These are the facts that, when wrong, cause Claude to write syntactically valid but contextually broken code. Get them in the file. Keep them current.
Numbered, specific behavioral instructions with examples. Not a wish list — a set of verifiable requirements. Each rule should have a number (so you can reference it in session: "follow rule 7"), a single clear instruction, and an example of what compliance looks like. If a rule applies only to a specific domain (API changes, UI components, database queries), it belongs in a separate file in .claude/rules/, not in the main file.
The current sprint, recent decisions, and active blockers. This is the section that makes Claude feel like a team member rather than a tool. What are you building right now? What was decided in the last architectural discussion? What is on hold and why? This section changes frequently — update it at the start of each sprint or when anything significant shifts. It is the highest-leverage section because it turns Claude from a general project assistant into a collaborator on exactly what you are doing today.
The gap between a weak CLAUDE.md and a strong one is not the length. It is the specificity. Here is what both ends of the spectrum look like in practice.
# My Project This is a web app. Use React and TypeScript. Be helpful and write clean code. Don't break things. Follow best practices.
This file loads on every session and accomplishes almost nothing. Claude does not know what kind of web app this is, where files go, what "clean" means in this context, or which best practices apply. It will give generically reasonable responses and guess constantly.
# PROJECT IDENTITY This is a B2B SaaS dashboard for financial analysts. Users are non-technical. Primary constraint: all UI must be accessible (WCAG 2.1 AA), all data must be handled without client-side persistence (no localStorage, no cookies for data). # STACK Language: TypeScript 5.3, strict mode Framework: Next.js 14 App Router (no pages/ directory) State: Zustand — no Redux, no Context for app state Styling: Tailwind CSS — no inline styles, no CSS modules Tests: Vitest + Testing Library — tests live in __tests__/ next to the file API: all calls go through /lib/api.ts — never fetch() directly in components # FILE STRUCTURE app/ → Next.js routes and layouts components/ → shared UI components lib/ → utilities, API client, type definitions __tests__/ → tests (mirror the source structure) public/ → static assets only, never generated # RULES 1. No any types. Use unknown and narrow it, or define a proper interface. Bad: const data: any = response.json() Good: const data = (await response.json()) as ApiResponse 2. Responses in under 200 words unless the task requires code or steps. Never summarize after giving an answer. Just stop. 3. Before editing a component, read it fully. Do not guess at props or state. 4. When adding a new route: update app/, add a test, update the nav if visible. # CURRENT CONTEXT Sprint: Data export feature (CSV + PDF). Design is approved in /docs/export-spec.md. Blocker: PDF rendering library choice not finalized — don't start PDF work yet. Decision log: Switched from react-query to Zustand for server state on 2026-04-20. Do not use react-query anywhere in new code.
This is not longer for the sake of being longer. Every line closes a gap where Claude would otherwise guess. The result is a session where Claude knows the project, follows the conventions, and asks about blockers rather than working around them.
Once your main CLAUDE.md is solid, three additional mechanisms make the system significantly more powerful.
Any file placed in .claude/rules/ is loaded as additional context for the session. This is where domain-specific rules live without cluttering the main file. Common patterns: database-rules.md for all ORM and migration conventions, api-rules.md for endpoint design standards, ui-rules.md for component architecture decisions. Claude reads all of them. You maintain them separately. Neither set competes with the other for the attention budget in a single file.
Hooks execute automatically on Claude Code events — before a session starts, after a response, when a file is modified. They are shell scripts or commands that run without Claude's involvement. Common uses: run the linter after every code change, auto-commit when a session ends, check for secrets before any file write. Hooks turn Claude Code from a responsive assistant into a system that actively maintains quality rather than waiting to be asked.
Skills are reusable slash commands — /deploy, /test, /review — that encode multi-step workflows as a single instruction. Where a rule tells Claude how to behave, a skill tells Claude what to do when invoked. A well-built skill for your deployment process is worth more than a page of instructions about how to deploy, because Claude executes the exact steps rather than improvising from guidelines.
Building a production-quality CLAUDE.md, a complete rules/ directory, working hooks, and a set of tested skills from scratch takes weeks. Most people who attempt it go through several rounds of frustration — rules that sound correct but produce unexpected behavior, hooks that break in edge cases, context sections that drift out of sync with the actual project state.
This is not a skill gap. It is an iteration problem. A good CLAUDE.md is not written — it is refined across hundreds of sessions until the rough edges are gone. That refinement takes time that most teams do not have.
Brainfile is what that refinement produces. The Brainfile OS ships with:
CLAUDE.md framework built across thousands of production sessions, with behavioral laws that have been stress-tested against real edge cases — not theoretical ones.claude/rules/ directory with domain-specific files for common workflow categories: knowledge management, content generation, pipeline automation, code qualitybrain/ memory layer that persists your decisions, preferences, and project state across sessions — the structural equivalent of Claude having been on your team for monthsThe alternative is spending six to eight weeks building something that approximates this — and then maintaining it yourself as Claude Code evolves. Both paths get you to the same destination. The question is how much of your time you want to spend on the infrastructure versus the work the infrastructure enables.
For more on how the full Brainfile OS is structured across its seven layers, see The 7 Layers of the Brainfile OS: Why CLAUDE.md Is Just the Beginning. For the practical case on what a production configuration replaces in your monthly SaaS stack, see How to Replace $500/Month in SaaS Bills with One Claude Code Configuration.
The Brainfile OS ships with a production-tested CLAUDE.md, a complete rules/ directory, hooks, skills, and a memory layer. You get the result of thousands of sessions of refinement on day one — not after six weeks of trial and error.
Brainfile is $99/mo or $999/yr. 14-day free trial, no conditions.
See Pricing — Start Free TrialThe test for a well-written CLAUDE.md is simple: open a fresh Claude Code session with no conversation context, ask Claude to describe the project and explain the current rules, and see what comes back. If Claude's answer matches what you would tell a new team member, the file is working. If Claude's answer is vague, generic, or incorrect, the file needs work.
Run this test after every significant update to CLAUDE.md. It takes two minutes and catches more problems than any manual review of the file itself.
The investment in a well-structured CLAUDE.md compounds with every session. The better the briefing, the less time you spend correcting Claude, re-explaining context, or unwinding decisions Claude made with incomplete information. Over a month of daily sessions, the difference between a weak file and a strong one is measured in hours — not minutes.