Writing a Great CLAUDE.md

Why CLAUDE.md matters

Claude Code auto-loads the project root’s CLAUDE.md into context at the start of every session. Write it well once and the same guidance applies to every session — no repeating yourself.

A good CLAUDE.md immediately improves answer quality and reduces wrong assumptions and repeated mistakes.

Two locations

If both exist, user-global loads first and project follows — project-specific rules effectively take precedence.

Bootstrap a draft

/init

Claude Code analyzes the project and produces a draft. Refining the draft is faster than writing from scratch.

Five principles

1. Short and structured

It’s loaded into every session, so longer means less token budget. Aim for one or two screens.

2. “How to handle it” beats “what’s there”

Skip the full directory tree — describe what each key directory is for and the commands you actually run. Claude can explore files itself.

3. State only the don’ts that matter

Spell out the rules where breaking them is hard to undo or project-specific.

## Rules
* Never commit or push without explicit user instruction
* Don't add error handling for impossible scenarios
* Don't introduce new dependencies without approval

Don’t let that list grow, though. Anthropic reports that with Claude 5 generation models, rigid rules conflict with what the user actually asks for and cost you more than they help. Drop taste-level rules like “never write comments” and keep the ones that cause real problems when violated — see Context engineering for Claude 5.

4. Put commands in code blocks

Build/dev/test commands should be in code blocks so Claude copies and runs them exactly.

## Commands
\```bash
npm run build       # production build
npm run dev         # dev server (port 3030)
npm test            # unit tests
\```

5. Document recurring workflows

Tasks like adding content, running migrations, or shipping a release belong here as procedures.

Solid structure example

# Project Name

## Overview
One paragraph on what the project does.

## Stack
* Frontend: Next.js 15, Tailwind CSS
* Backend: Node.js, Prisma, PostgreSQL
* Hosting: Cloudflare Pages

## Commands
\```bash
npm run dev
npm run build
npm test
\```

## Layout
* src/app — Next.js App Router pages
* src/components — UI components
* prisma/ — DB schema and migrations

## Conventions
* Function components only
* State via Zustand
* Tests with Vitest

## Rules
* Commit/push only on explicit instruction
* Confirm before adding new dependencies

Common mistakes

• ❌ Pasting the full directory tree — Claude can explore
• ❌ Mixing languages — pick one and stay consistent
• ❌ Feature descriptions (those belong in the README)
• ❌ Generic best practices (“write readable code”) — keep it project-specific
• ❌ Long lists of taste-level don’ts — they conflict with the model’s judgment
• ❌ Repeating instructions that already live in the system prompt or a skill — they drift apart

Move detailed rules into Skills

When CLAUDE.md grows, extract recurring workflows (content authoring, migration procedures) into separate Skill files. Leave a short pointer in CLAUDE.md saying “for X, invoke skill Y.”

Next steps

• Andrej Karpathy Skills — a CLAUDE.md template plugin distilling Karpathy’s principles
• Superpowers — pair with CLAUDE.md for stronger workflow consistency
• Build a Skill — extract rules into reusable Skills
• Context engineering for Claude 5 — the latest guidance on cutting length and removing rules