Official Documentation: https://code.claude.com/docs/en/memory

My personal Claude.md workflow creation

CLAUDE.md is a plain-text file Claude Code auto-loads at the start of every session in a project. Whatever you put in it becomes persistent context - closer to a system prompt than a readme. The model treats it as higher-priority than its own
defaults, which is exactly what makes it useful and exactly what makes it dangerous if you write it sloppily.

Why it matters

Without CLAUDE.md, every session starts from zero. You end up re-explaining the same conventions, the same security rules, the same "don't touch X" list - and Claude still drifts because there's no written record. With CLAUDE.md, those decisions are one load away.

A few things it reliably changes:

• Consistency across sessions. The same rule enforced 100 times instead of remembered 3 times.
• Override of default behavior. If Claude's default is to add comments everywhere and you want terse code, CLAUDE.md wins.
• Onboarding for the model. Stack, file layout, naming conventions — stuff the model would otherwise have to grep out painfully.
• Guard rails. Security rules, dangerous commands to refuse, things that must never be committed.

What goes in it

A useful CLAUDE.md is short, specific, and load-bearing. Everything in it should change how Claude behaves. If a line could be deleted without any behavior change, delete it.

Sections that earn their keep:

1. Project summary - one paragraph on what this is and who it's for.
2. Stack table - framework, language, styling, database, deployment. Saves 20 grep calls per session.
3. Design tokens / conventions - exact tokens, exact class names, exact file patterns. "Never hardcode hex" is worth a whole section.
4. File structure - annotated tree of the directories that matter.
5. Component boundaries - server vs client, where data fetching lives.
6. Security policy - what to refuse, what to flag, what to never suggest. This is where CLAUDE.md pays for itself.
7. Decisions - do not revisit - closed questions. Stops the model from re-litigating things you already settled.
8. Out of scope - features you explicitly don't want. Stops well-meaning scope creep.

Best practices

• Write rules, not wishes. "Use tokens" is a wish. "Never hardcode hex - use tokens from the table below" is a rule.
• Put the why next to the what when the rule is non-obvious. Claude can extrapolate from "no cookie banners - Umami is cookieless" far better than from "no cookie banners" alone.
• Tables and checklists beat prose. Structured data is easier for the model to apply consistently than paragraphs.
• Keep it under ~500 lines. Every session pays the token cost. Trim anything that's documentation rather than
  instruction.
• Version it. CLAUDE.md lives in git. Treat changes like code - review them.
• No secrets, ever. It's committed. Treat it like source.
• Test it. Start a fresh session, give Claude a task that touches one of the rules, and see if the rule actually fires. If not, the rule is worded too softly.

How to get Opus 4.6 to draft one for you

The trick is to treat the generation like a requirements interview, not a "write me a doc" prompt. A one-line request gets you a generic template. A proper brief gets you something that actually steers behavior.

A prompt that works:

Read the repo. Then draft a CLAUDE.md for it. Include: one-paragraph project summary, a stack table, design conventions I should never revisit, file structure of the directories that matter, component boundaries (server vs client), a security policy section covering package installs / secrets / API routes, and a "decisions - do not revisit" list. Keep it under 400 lines. Every rule must be specific enough that you would actually change your behavior based on it - no vague advice. If you don't know something about the project, ask me before writing it.

The last sentence is the important one. Without it, the model fills gaps with plausible-sounding defaults that may not
match your project. With it, you get a draft that reflects what's actually there plus a short list of questions you can answer in one pass.

After the first draft, iterate: take it into a fresh session, give Claude a real task, and watch where it ignores the file. Those are the rules that need sharper wording.

The broader point

CLAUDE.md is leverage. Ten minutes spent tightening a rule saves the same ten minutes every session for the rest of the
project. The payoff compounds fast - which is also why a sloppy CLAUDE.md is worse than none at all. A vague rule is a rule the model will interpret creatively, and creative interpretation is how you end up with comments on every line and
backwards-compatibility shims you never asked for.

Write it tight. Review it like code. Delete anything that isn't pulling weight.