CLAUDE.md — The Persistent Memory Layer Claude Pretends You Know About

There's a file that makes Claude remember your preferences, your voice, your workflows, and your constraints across every conversation. It's called CLAUDE.md. Almost no one uses it correctly. The ones who do get a compounding advantage.

The problem CLAUDE.md solves is memory. Out of the box, every conversation with Claude starts from zero. You spend the first 10 minutes re-explaining your brand voice, your stack, your preferences, your constraints. That's wasted time, and worse, it's inconsistent. You explain it differently each time, and Claude's outputs vary as a result.

CLAUDE.md is a text file you drop in your project folder. Every time Claude Code runs in that folder, it reads the file first. Your preferences become persistent context. Your voice becomes baked into every output. The shift from ephemeral to persistent context is one of the single biggest productivity moves you can make if you're using Claude regularly.

Here's what goes in a good CLAUDE.md.

Project context. What are you building. Who is it for. What stage is it at. What's the north-star goal. Two paragraphs is usually enough. Any agent reading this should know what they're walking into in 30 seconds. This paragraph is also the one you reread when you come back to the project after a break and need to re-ground yourself — which is a nice side benefit.

Voice and tone. If content output matters, define it. Example — direct, Gen Z friendly, no buzzwords, short paragraphs. Give the model two or three examples of what good sounds like and two or three examples of what bad sounds like. This works better than any amount of adjective stacking. Show, don't tell. The contrast between good and bad examples is especially powerful because it teaches the model the edge.

Technical stack. What language, what framework, what database, what deploy target. Include specific version numbers if they matter. If you're on Next.js 16 with Cache Components, say so. The model won't guess right without this. If you're on Cloudflare Workers versus Vercel Functions, the implementation advice diverges. Precision here saves you from getting code that assumes a different stack.

"You explain it differently each time, and Claude's outputs vary as a result."

Constraints. The hard nos. The things that should never appear in output. If you refuse to use em-dashes as hyphens, write it. If you never mention certain brands, write it. If you always follow a specific content formula, write it. Constraints are where CLAUDE.md earns its keep. A model with good constraints produces dramatically better output than a model with good encouragement.

Commands and workflows. If there are specific commands the model should run — npm scripts, deploy commands, test runners — list them. This saves the model from guessing and saves you from correcting. Include the failure modes too. "If the build fails with error X, run command Y." That kind of detail turns CLAUDE.md into a runbook.

Who's on the team. If multiple people work with the model, name them and note their roles. If you're a solo founder, note that too. The model treats solo founders differently than it treats a team member contributing to a shared codebase, and it should. Solo founder context means the model can take more initiative. Team context means it should be more cautious and ask more clarifying questions.

The mistakes people make with CLAUDE.md are predictable.

They write too much. A 50-page CLAUDE.md is worse than a 2-page one. The model has to read it every time, and the longer it is, the more likely it drifts. Keep it under 500 lines. Link out to other files for deep details. A lean, high-signal CLAUDE.md beats a sprawling one every time. Signal density matters more than volume.

They write too vaguely. "Use a professional tone" is useless. "Use direct, Gen Z friendly tone with contractions, short paragraphs, no buzzwords, and no em-dashes as hyphens" is actually useful. Specificity beats adjectives. A good rule — if a sentence in your CLAUDE.md could be copy-pasted into anyone else's CLAUDE.md without changes, it's probably too vague.

They never update it. Your preferences evolve. Your stack evolves. Your voice evolves. Update the file monthly or whenever something changes. Treat it like documentation. Stale docs are worse than no docs because they mislead. A CLAUDE.md that's six months out of date will produce outputs that feel slightly off in ways you can't articulate. Keep it fresh.

They don't version control it. CLAUDE.md should live in your repo, reviewed in pull requests, updated with changelog discipline. It's operational code. Treat it that way. When something goes wrong with output quality, you can diff the last commit and often find the cause.

One more thing most people miss. You can have multiple CLAUDE.md files. A global one in your home directory that applies everywhere. A project-level one that applies to this specific codebase. Claude Code reads them in hierarchy — global first, then project. Your global file holds preferences that cross every project — how you like to work, your communication style, your standard constraints. Your project file holds the specifics. Layered memory.

The advanced pattern is to modularize. A CLAUDE.md that points to a prompts folder, a constraints folder, an examples folder. Instead of cramming everything into one file, you let the file be a table of contents that links into detailed reference material. The model still gets the full context when it needs it, but the top-level file stays scannable for you.

There's also a team coordination angle. When multiple humans work on a project, the CLAUDE.md becomes the shared contract. Your teammate doesn't guess at your conventions. They read the file. The onboarding time for a new collaborator drops from days to an hour.

One undersold benefit is that writing a good CLAUDE.md forces you to articulate things about your project you've never written down. Your brand voice. Your architectural principles. Your workflow conventions. The act of writing them out clarifies your own thinking. Half of the CLAUDE.md's value is created by the author, not the reader.

Spend an hour this week writing your first CLAUDE.md. Put it in your biggest active project. Watch the quality of output jump immediately.

Start free at mentorme.com — community, 2 courses, AI Operator Stack, and the skill library.