CLAUDE.md Best Practices: Templates + What to Delete

You correct Claude on the same three things every session. It forgets your stack, ignores your naming rules, and rewrites files you told it never to touch. The fix isn't a longer prompt. It's a CLAUDE.md that actually works, and most people bloat theirs until it stops working entirely.

Quick answer: A good CLAUDE.md follows these best practices: keep it under ~200 lines, state your commands, conventions, and the why behind each rule, and delete everything Claude can already infer. CLAUDE.md is the memory file Claude Code reads at the start of every session, so without it Claude begins each conversation with a blank context window and repeats the same mistakes.

What is CLAUDE.md and why it's the biggest lever on output quality

CLAUDE.md is a plain markdown file that Claude Code reads automatically when it starts working in your project. Think of it as the standing instructions you'd give a sharp contractor on day one: here's how we do things, here's what not to touch, here's why. Without it, every session starts from zero and you become the quality check, correcting the same mistakes on repeat.

The reason it matters more than any single prompt is that it persists. A good prompt fixes one message. A good CLAUDE.md fixes every message. This is the same setup discipline we cover in how to set up Claude Code for your business — the memory file is where most of the quality difference actually lives.

Here's the counterintuitive part: more is not better. The instinct is to dump everything you know into the file so Claude never gets it wrong. That instinct is what breaks it.

Why a bloated CLAUDE.md makes Claude worse (context rot)

A bloated CLAUDE.md makes Claude less accurate, not more, because everything in it competes for space in the context window. This is called context rot: as you cram in more text, the model gets worse at using any single piece of it.

The Chroma 2025 context rot study put numbers on this. Model accuracy dropped from roughly 95% to around 60% as input length grew, per a breakdown by maketocreate. That's not a rounding error. That's the difference between an agent you trust and one you have to double-check.

So a 600-line CLAUDE.md documenting every edge case doesn't make Claude careful. It buries the five rules that actually matter under 595 lines of noise, and Claude starts missing the ones you care about most. Every line you add is a line competing with your commands and conventions for attention.

The practical takeaway: treat CLAUDE.md like a budget, not a bucket. Aim for under ~200 lines. If a rule earns its place, it stays. If Claude can figure it out from the code, delete it.

The CLAUDE.md template a non-developer can copy

Here's a complete CLAUDE.md template built for a founder or no-code builder, not a professional developer. Copy it, replace the bracketed parts with your details, and delete any section you don't need. It covers the four things that carry almost all the value: commands, conventions, the why intent, and hard boundaries.

# Project: [what this project is, one sentence]

## Commands
- Run the app: [exact command, e.g. npm run dev]
- Run tests: [exact command]
- Deploy: [exact command or "ask me before deploying"]

## Conventions
- File naming: [e.g. kebab-case for files, PascalCase for components]
- Where things live: [e.g. all pages in /app, shared logic in /lib]
- Style: [e.g. match the existing patterns in this repo, don't introduce new libraries]

## Why (intent behind the rules)
- We keep dependencies minimal because [reason].
- We test before deploy because [reason].
- Match existing patterns because consistency matters more than cleverness here.

## Never do this
- Never touch [specific file/folder, e.g. .env or /config].
- Never commit secrets or API keys.
- Never rewrite working code unless I ask.

## When unsure
- Ask a clarifying question instead of guessing.
- Prefer the smallest change that solves the problem.

That's it. Under 30 lines and it already outperforms most 400-line files, because every line does a job. The why section is the part most people skip and the part that matters most. When Claude understands intent, it makes better calls on the cases you didn't spell out.

The one section people always forget: intent

State the why behind your rules, because intent generalizes and rules don't. If you write "use TanStack Query" with no reason, Claude follows it literally. If you write "use TanStack Query so we're not managing loading states by hand," Claude understands the goal and applies it to situations you never listed.

This is the difference between an agent that follows orders and one that makes good decisions. One line of intent replaces ten lines of edge cases.

What to delete from your CLAUDE.md right now

Delete anything Claude can infer from your code, anything it already knows, and anything you wrote once and never enforced. Here's the checklist.

A useful test: read each line and ask would a sharp new hire need this written down, or would they figure it out? If they'd figure it out, delete it.

Bloated CLAUDE.md vs lean CLAUDE.md

The difference shows up in every session. Here's the same file two ways.

Common pitfalls

The mistakes that turn a good CLAUDE.md into a useless one are predictable. Watch for these.

FAQ

Where does the CLAUDE.md file go?

Put CLAUDE.md in the root of your project folder, where Claude Code will read it automatically at the start of each session. You can also keep a personal one in your home directory for preferences that apply across every project.

How long should a CLAUDE.md be?

Aim for under ~200 lines, and most good ones are far shorter than that. The goal is every line earning its place. A lean 30-line file usually beats a bloated 400-line one because context rot degrades accuracy as the file grows.

What's the difference between CLAUDE.md and a prompt?

A prompt fixes one message; CLAUDE.md fixes every message. The prompt is what you type right now, while CLAUDE.md is the standing memory Claude reads every session, so anything you'd otherwise repeat belongs in the file.

Do I need to know how to code to write a CLAUDE.md?

No. CLAUDE.md is plain English in a markdown file. You're writing instructions, not code. Fill in the commands you already run, your naming conventions, and what Claude should never touch, and you're done.

What should I never put in a CLAUDE.md?

Never put secrets or API keys in CLAUDE.md, since it's a plain text file often committed to your repo. Also skip framework documentation, generic best practices, and folder trees Claude can read itself. All of it wastes context.

If you want the copy-paste CLAUDE.md files, Claude Code use cases, and the masterclass that walks through setting all of this up the right way, join the free Claude Community. 7,800+ builders are sorting out exactly this kind of setup together.