The CLAUDE.md Pattern: Give Your AI a Developer's Brain

March 2026 · 8 min read

Every Claude Code session starts with a blank slate. No memory of yesterday's work, no knowledge of your conventions, no understanding of the 47 specific ways your project works. So Claude guesses. And those guesses are different every time.

There's a simple fix: a file called CLAUDE.md in your project root.

Claude Code reads this file automatically at the start of every session. It becomes your project's constitution — the non-negotiable rules that prevent the most common and most expensive mistakes.

What Goes in CLAUDE.md

A good CLAUDE.md has four sections, and the whole thing should be under 100 lines. Longer than that and Claude may skip or misweight parts of it.

1. Project Overview (3 lines max)

What the project is, what stack it uses, where it lives. Not your product roadmap. Just enough for Claude to orient itself:

## Project Overview
Task management app. Django + HTMX, PostgreSQL, Redis sessions.
- Live: https://app.example.com
- Service: taskapp (systemd)

2. Critical Rules

This is the section that pays for itself. These aren't style preferences — they're landmines. Things where getting it wrong causes real bugs that take real time to find.

The key technique: show both the correct AND incorrect way. Claude learns from contrast:

### Authentication — Django sessions, NOT tokens
# CORRECT
request.user.id

# WRONG — we don't use DRF token auth
from rest_framework.authentication import TokenAuthentication

If you only show the correct pattern, Claude might generate something slightly different that "seems fine" but breaks your specific setup. Showing the wrong pattern with an explicit prohibition is surprisingly effective at preventing it.

3. Architecture Quick Reference

A navigational aid, not documentation. Help Claude find things fast:

## Architecture
- 12 Django apps in `apps/`
- Models: import from `apps.core.models`
- Auth: `@login_required` decorator
- Frontend: HTMX + Alpine.js, no build step

4. Explicit Prohibitions

Things Claude might reasonably try that it absolutely should not:

## Do NOT
- Run migrations locally (use staging server)
- Install new packages without asking
- Use class-based views (project uses function views)
- Create new patterns when existing ones work

The Rules File Routing Table

One powerful addition is a table at the top that points Claude to detailed rules based on what it's about to edit:

## BEFORE EDITING ANY FILE, READ THE RELEVANT RULES DOC
| If you're touching... | Read first            |
|---|---|
| `apps/*.py`           | `docs/APP_RULES.md`   |
| `models.py`           | `docs/DB_RULES.md`    |
| `templates/`          | `docs/TEMPLATE_RULES.md` |

This keeps CLAUDE.md short while ensuring Claude gets the detailed context it needs for whatever it's working on.

What Happens Without It

On a production project I built over several months, here's what I tracked before and after implementing CLAUDE.md:

Before: Approximately 30% of Claude Code output needed correction — wrong import paths, incorrect auth patterns, deprecated function calls, inconsistent naming.

After: Corrections dropped to under 5%, mostly for edge cases not covered by the rules. The rules caught the other 25% automatically.

That's not a small improvement. On a project where Claude writes hundreds of lines per day, going from 30% rework to 5% rework is the difference between AI-assisted development being productive and being a net time sink.

Principles for Writing Good Rules

Be specific, not philosophical. "Write clean code" means nothing. "Use datetime.now(timezone.utc), never datetime.utcnow()" prevents a real bug.

Add rules reactively. When Claude makes a mistake, don't just fix it — add a rule that prevents it from ever happening again. Your CLAUDE.md grows from real pain points, not hypothetical ones.

Keep it scannable. Tables, code blocks, and short bullet points. If Claude has to parse dense prose to find the rule, it'll miss it.

Update it. CLAUDE.md is a living document. When you change a convention, update the rules. Stale rules are worse than no rules — they actively teach Claude the wrong thing.

Get Started in 5 Minutes

Create a file called CLAUDE.md in your project root. Add your project overview in 3 lines. Think of the last 3 times Claude Code did something wrong in your project. Write a rule for each one with correct/incorrect examples. Add a "Do NOT" section with your top prohibitions.

That's it. Your next Claude Code session will be noticeably better.

Want the complete system — including QUICKREF.md, ADR patterns, documentation templates, and the full case study of building a 37,000-line SaaS? Get the Agent Playbook Pro guide.