CLAUDE.md best practices: teach Claude Code your business, not just your stack

Every Claude Code tutorial tells you to create a CLAUDE.md. Almost none tell you what separates a useless one from one that quietly upgrades every single session. We have read a lot of them, and the pattern is consistent: most CLAUDE.md files describe the stack and stop.

Next.js, TypeScript, Postgres, run tests with npm test. Fine. But Claude Code can discover most of that by reading your repo. What it can never discover on its own is everything that lives outside the code.

What Claude Code cannot infer from your repo

• Who pays you. "B2B, ops managers at 10 to 50 person logistics companies, non technical" changes every UI copy decision, every error message, every email.
• How you price. If Claude knows the Pro plan is $49 with a 14 day trial and no credit card upfront, the billing code, the pricing page and the dunning emails stop contradicting each other.
• How you sound. Plain, direct, no exclamation marks, no "unleash". Without this, every generated sentence sounds like every other AI product.
• What is off limits. Never touch the migrations folder, never auto-update dependencies, all payments code needs a test before merge.

This is the difference between a contractor who just arrived and one who has been in your company a year. Same skills, different context, completely different output.

A structure that works

Keep it under 150 lines. Facts, not essays. Here is the skeleton we ship with every kit, trimmed:

# CLAUDE.md

## Product
One paragraph: what it does, for whom, why they pay.

## Customers
Who they are, how technical, what they fear.

## Pricing
Plans, prices, trial policy, refund policy.

## Voice
3 rules + 5 banned words.

## Stack
Only what is not obvious from the repo:
versions pinned on purpose, infra, deploy steps.

## Hard rules
The things that must never happen, one per line.

Two details that matter more than they look:

• Write rules as behavior, not policy. "Stripe webhooks must verify signatures before touching the database" beats "be careful with security". One is checkable, the other is decoration.
• Keep procedures out. Step by step processes belong in skills, where they load on demand. CLAUDE.md is loaded every session, so every line has a permanent token cost. If you are unsure of the difference, read our guide on subagents, skills and commands.

Use folder-level CLAUDE.md files for the tricky corners

Claude Code also reads CLAUDE.md files in subdirectories when it works there. That is the right place for context that only matters locally: billing/CLAUDE.md explains your Stripe object model, emails/CLAUDE.md holds the lifecycle map. The root file stays short, and the deep context is exactly where the work happens.

Maintain it like code

A CLAUDE.md is never finished. The loop that works:

1. When Claude does something wrong that context would have prevented, add one line.
2. When you change pricing, positioning or policy, update it the same day, in the same commit if you can.
3. Once a month, delete what no longer earns its tokens.

Why this multiplies with agents

A single Claude session forgets everything when it ends. But specialized agents inherit CLAUDE.md on every run, forever. Write "we never discount" once, and the pricing strategist, the email marketer and the copywriter all respect it, every time, without being reminded. The file is small; the leverage is not.

Every claudecrew kit ships with a CLAUDE.md template built for exactly this: ten minutes of filling in blanks, and all 89 agents read your business before they touch your code.