CLAUDE.md Masterclass: Write Memory Files That Actually Work
Every developer using Claude Code has a CLAUDE.md file. Most of them are bad. They are either too long, too vague, written in the wrong voice, or structured in a way that wastes context tokens. This guide covers what actually works, based on patterns from teams shipping production software with agentic workflows every day.
The 200-Line Rule
Your root CLAUDE.md file should be under 200 lines. This is not arbitrary. Claude Code loads this file into context at the start of every session, and every token in it competes with your actual conversation for attention. A 500-line CLAUDE.md filled with architectural details from six months ago actively hurts performance -- the model spends attention on stale context instead of your current task.
If you find yourself pushing past 200 lines, it is a signal that you need to split your memory into a hierarchy (covered below). The root file should contain only what applies to every single session, regardless of what you are working on.
What Belongs in the Root CLAUDE.md
- Build commands -- how to run, test, lint, and deploy
- Project structure -- key directories and what lives where
- Coding conventions -- naming, file organization, patterns to follow
- Hard rules -- things the agent must never do (e.g., never modify migration files directly)
- Current priorities -- what you are actively working on this week
Write in Imperative Voice
This is the single highest-impact change most developers can make to their CLAUDE.md files. Compare these two approaches:
Passive (Weak)
The project uses TypeScript with strict mode enabled.
Components are generally organized by feature.
Tests should ideally be placed next to their source files.
We prefer named exports over default exports.Imperative (Strong)
Use TypeScript strict mode. Never use `any`.
Organize components by feature in src/features/.
Place tests next to source: Component.test.tsx.
Use named exports. Never use default exports.The imperative version is shorter, clearer, and leaves zero room for interpretation. When Claude reads "Tests should ideally be placed next to their source files," it treats this as a suggestion it can override. When it reads "Place tests next to source," it treats it as a rule. The difference in agent compliance is significant.
Write every line in your CLAUDE.md as if you are writing a build script, not a wiki page. Commands, not descriptions.
Memory Hierarchy: Root, Subdirectory, and User
Claude Code supports a three-level memory hierarchy, and using it properly is what separates a mediocre CLAUDE.md setup from a great one.
Level 1: Project Root CLAUDE.md
Lives at the project root. Loaded on every session. Contains global rules, build commands, and project-wide conventions. Under 200 lines.
Level 2: Subdirectory CLAUDE.md Files
Live inside specific directories (e.g., src/api/CLAUDE.md, src/components/CLAUDE.md). Only loaded when Claude reads or writes files in that directory. This is where you put domain-specific context.
# src/api/CLAUDE.md
All API routes return { data, error } shape.
Use Zod for request validation. Schema goes in route.schema.ts.
Rate limiting is handled by middleware -- do not add per-route limits.
Database queries go through src/lib/db.ts, never raw SQL in routes.Subdirectory files keep specialized knowledge scoped to where it is needed. The agent only sees the API conventions when it is working on API code, which keeps the context window focused.
Level 3: User-Level Memory
Lives at ~/.claude/CLAUDE.md. Applies to every project. Use this sparingly -- only for universal preferences like your preferred commit message format, your timezone, or tools you always want available.
Shared Team Patterns
When a team shares a codebase, CLAUDE.md becomes a shared artifact -- and this introduces coordination challenges. Here are patterns that work well for teams.
Commit the Root CLAUDE.md
Your root CLAUDE.md should be version-controlled. It is project documentation, and it should evolve with the codebase. When someone adds a new convention or changes the build process, the CLAUDE.md update should be part of the same pull request.
Use .claude/ for Personal Overrides
Team members who want personal customizations can create .claude/CLAUDE.md (gitignored) for preferences that differ from the team standard. This keeps the shared file clean while allowing individual flexibility.
Review CLAUDE.md Changes in PRs
Treat CLAUDE.md changes with the same rigor as code changes. A bad memory entry can cause every team member's agent to produce subtly wrong output. Review memory changes carefully, and test them by running a session with the updated file before merging.
Team CLAUDE.md Anti-Patterns
- One person owns it: CLAUDE.md should be a shared responsibility. If only one person updates it, it drifts from reality.
- Never pruning: Old conventions accumulate. Schedule a monthly review to remove outdated entries.
- Conflicting instructions: When two entries contradict each other, the agent picks one unpredictably. Resolve conflicts immediately.
- Too many exceptions: If your CLAUDE.md is full of "except when X, then Y," simplify the rules or split into subdirectory files.
How Beam Streamlines the Workflow
Managing CLAUDE.md files manually works, but it introduces friction. You have to remember to update the file after each session, remember to install it before starting a new one, and keep track of which memory applies to which project.
Beam's Install Memory and Save Memory buttons eliminate this friction. When you start a session, click Install Memory and Beam writes your project memory file into the correct .claude/ location. When you finish a session, click Save Memory and Beam captures the current state -- new decisions, updated conventions, architectural changes -- back into your memory file.
This one-click workflow means your memory is always current. No forgetting to update. No stale context. No starting a session and realizing the agent does not know about the database migration you ran yesterday.
For teams, Beam's project system lets each workspace maintain its own memory configuration. Switch between projects and the correct CLAUDE.md is automatically scoped to the active workspace. No cross-contamination between projects.
A Complete CLAUDE.md Template
Here is a battle-tested template you can adapt for your own projects. It stays under 200 lines and covers everything an agent needs for a productive session.
# ProjectName
## Build
- Dev: npm run dev (port 3000)
- Build: npm run build
- Test: npm run test -- --watch
- Lint: npm run lint -- --fix
- Type check: npx tsc --noEmit
## Structure
- src/app/ -- Next.js routes and layouts
- src/components/ -- Shared UI components
- src/features/ -- Feature modules (auth, billing, dashboard)
- src/lib/ -- Utilities, DB client, API helpers
- prisma/ -- Schema and migrations
## Rules
- TypeScript strict mode. Never use `any` or `as unknown`.
- Named exports only. No default exports.
- Components: function declarations, not arrow functions.
- Tests next to source: Feature.test.tsx.
- Commits: conventional format (feat:, fix:, chore:).
- Never edit prisma/migrations/ directly. Use `npx prisma migrate dev`.
## Patterns
- API: return { data, error } from all endpoints.
- State: use server components by default. Add "use client" only for interactivity.
- Auth: NextAuth v5 with GitHub provider. Session in src/lib/auth.ts.
- Styling: Tailwind CSS. No inline styles. No CSS modules.
## Current Sprint
- Building user settings page (profile, notifications, billing)
- Refactoring dashboard to use streaming with Suspense
- Fix: timezone display bug in activity feedAdapt the sections to your stack, but keep the structure: Build, Structure, Rules, Patterns, Current Work. Every section earns its place by directly influencing how the agent writes code.
One-Click Memory Management
Beam's Install and Save Memory buttons keep your CLAUDE.md current across every session. No manual file editing, no stale context.
Download Beam Free