The Definitive CLAUDE.md Guide

This guide is for developers setting up Claude Code on an existing project. After reading it, you'll know what to put in a CLAUDE.md, what to leave out, and how to keep it accurate as the project evolves.

Why Most People Get Bad Results

Most people install Claude Code, type something, get a mediocre answer, and conclude "AI isn't that useful yet."

The problem isn't Claude Code. They skipped the one file that makes it work.

Without CLAUDE.md, every session starts blind. Claude Code doesn't know your stack. Doesn't know your coding style. Doesn't know your team uses Tailwind, not styled-components. Doesn't know you hate verbose output. It guesses. And guessing produces average results.

Same person. Same prompt. Night and day difference. The only variable: a CLAUDE.md file.

OK So What Is It Actually?

First, what's a .md file? It's just a text file written in Markdown: a simple way to format text using symbols like # for headings and - for bullet points. You can open it in any text editor. It's not code. If you've ever written a Reddit post or a GitHub README, you've already used Markdown.

CLAUDE.md sits at the root of your project and tells Claude Code how to behave. Think of onboarding a new team member. You wouldn't hand someone a laptop and say "go write code." You'd tell them what the project is, what tech stack you use, how you like things done, and what mistakes to avoid.

That's what CLAUDE.md does. Except this team member reads your instructions perfectly, every single time, and never forgets them.

The Five Things Your CLAUDE.md Needs

Most people write one section and call it done. That gets you maybe 30% of the value.

1. Tell it what it's working with

# CLAUDE.md

This is a Next.js 16 app using App Router, Tailwind CSS, and TypeScript.
Database: Neon Postgres via Drizzle ORM.
Auth: Clerk.
Deploy target: Vercel.

Simple. But you'd be surprised how many people skip this. Without it, Claude Code infers your stack from your package.json every single time. Sometimes it guesses wrong.

"I don't know my tech stack." That's fine. Your tech stack is just the tools and languages your project uses. If you're unsure, run claude /init and Claude scans your project files, detects your framework and language, and writes the CLAUDE.md for you. You don't need to know what "Drizzle ORM" means. Just let it figure it out.

The real shortcut: You can delegate almost all of CLAUDE.md setup to Claude. Say: "Scan my project and create a CLAUDE.md with my tech stack, build commands, and project structure." Done in 10 seconds. Then add your personal preferences on top.

For complex workspaces, point to files instead of inlining everything. CLAUDE.md is an index, not a dump.

Read `docs/architecture.md` for the full system design.
Read `docs/conventions.md` for coding standards.

2. Define how sessions start and end

This is the most underused section. Also the biggest game-changer.

## Session Lifecycle

**Starting**: Read MEMORY.md. Check handoffs/ for the latest handoff. Resume context.
**Ending**: Write a handoff if work is in-progress. Save any corrections to memory.

Without this, every session is stateless. You close the tab, everything's gone. With it, sessions compound. After a month, Claude Code knows your projects, your preferences, and your common patterns without you saying a word.

I know what you're thinking: "That's extra work." It is, for about a week. Then it starts saving 15-20 minutes per session. The math isn't close.

3. Tell it how you communicate

## How I Work

- Direct, no fluff. Skip preambles.
- NO em dashes. Use colons or split sentences.
- Lead with recommendations, not option lists.
- Code should be production-ready, not "here's a starting point."

This matters a lot and nobody talks about it. Without explicit preferences, Claude Code defaults to that verbose, hedging, "here are several approaches you might consider" mode. Polite but useless when you need a straight answer.

Put your communication preferences in CLAUDE.md and every response starts matching how you actually want to work.

4. Set the rules for how it works

## Workflow Rules

1. Plan first for anything non-trivial. Think before coding.
2. One sub-agent per focused task. Keep the main chat clean.
3. After ANY correction from me, save it to memory. Don't make the same mistake twice.
4. Verify before calling it done. Run tests. Check the diff.

Without orchestration rules, Claude Code starts writing code the moment you ask. Sometimes that's fine. For anything complex, you want it to plan first, break down the work, and verify the result. This section is what separates "doing things" from "doing things well."

5. Register your tools

## Available Tools

Skills: `_context/skills/` (keyword-triggered workflows)
Agents: `_context/agents/` (specialist sub-agents)
Rules: `_context/rules/` (coding standards)
Commands: `.claude/commands/` (slash commands)

If Claude Code doesn't know your skills and agents exist, it won't use them. This tells it what it has to work with.

What to Leave Out

Not everything belongs in CLAUDE.md. These four categories actively hurt more than they help:

• Explanations of what the project does. CLAUDE.md is for working instructions, not onboarding docs. Business context belongs in docs/overview.md.
• Information that changes constantly. Version numbers, sprint goals, active tickets. These go stale within days, and an outdated instruction misleads more than blank space.
• Your full coding style guide. Five pages of naming conventions buries the two lines Claude actually needs. Extract the rules that affect output and inline those; link to the rest.
• Anything Claude can already read in the codebase. If it can open the file and infer it, don't repeat it here.

Do this instead: Link to external files. Read docs/architecture.md for system design. keeps CLAUDE.md short and lets Claude pull context on demand rather than loading everything upfront. Your context window will thank you.

The Three Mistakes Everyone Makes

Mistake 1: Dumping everything inline

Your CLAUDE.md is 2000 lines long. It has your entire coding style guide, all your project history, and your life story. Claude Code reads it all at the start of every session, eats a chunk of your context window, and starts ignoring half of it anyway.

Fix: Keep CLAUDE.md under 100 lines. Use it as a table of contents that points to other files. Let Claude Code read those on demand.

Mistake 2: No session lifecycle

You don't define start/end protocols. Every session starts cold. You spend 10 minutes re-explaining what happened yesterday.

Fix: Add the session lifecycle section. Two minutes of investment at the end of each session saves ten at the start of the next. Every single time.

Mistake 3: Being vague

"Write clean code" is not a rule. It's a wish. Claude Code reads that and goes "sure, clean code, got it" and then writes whatever it was going to write anyway.

Fix: Be specific. "Functions under 50 lines. Files under 800 lines. No mutation. Handle errors explicitly. Use early returns." Now Claude Code has actual constraints to follow.

A Realistic Worked Example

Here's a CLAUDE.md for a real backend service: a gRPC service managing warehouse inventory. gRPC is a framework for calling functions across services over a network; it uses proto files (short for Protocol Buffer files) to define the shape of the data being exchanged, instead of JSON. Error handling uses neverthrow, a TypeScript library that returns errors as values rather than throwing exceptions, making every error path visible in the type system.

# CLAUDE.md

## Stack
- Node.js gRPC service. Proto files in /proto define all field names and types.
- TypeScript with neverthrow for error handling. Use Result<T, E>, not try/catch.
- Postgres via Drizzle ORM, migrations in /db/migrations.
- Deploy target: Fly.io

## Build & test
npm run build     # Compiles TypeScript and generates types from proto files
npm run test      # Runs Jest suite (must pass before any commit)
npm run gen       # Regenerates TypeScript types from .proto schema files

## Rules
- Errors: use ok() and err() from neverthrow. No try/catch in service logic.
- Never edit generated files under /proto/generated/. Change the .proto file, then run npm run gen.
- Functions under 50 lines. Files under 400 lines.
- Read docs/architecture.md before touching the inventory sync flow.

Notice what this covers: the stack (with each term explained inline), the commands needed to build and test, and the rules that affect day-to-day output. It doesn't explain what a warehouse is or paste in the full Drizzle ORM docs. That stays in docs/.

A Real CLAUDE.md in Production

This isn't theoretical. Here's a real workspace structure that runs daily across 6 projects:

CLAUDE.md (index, ~80 lines)
├── _context/
│   ├── skills/         (19 workflow skills)
│   ├── agents/         (9 specialist agents)
│   ├── rules/          (10 coding rules)
│   ├── handoffs/       (session continuity)
│   └── memory/         (persistent knowledge)
├── .claude/
│   ├── commands/       (8 slash commands)
│   └── hooks/          (automation triggers)
└── memory/
    ├── MEMORY.md       (index)
    ├── user_*.md       (who you are)
    ├── feedback_*.md   (corrections)
    ├── project_*.md    (active work)
    └── reference_*.md  (external pointers)

Every session starts in under 10 seconds. Zero re-explanation. Corrections from last month still apply. Handoffs from yesterday load automatically.

Took about a week to set up. Saves 30+ minutes daily. The ROI is absurd.

Getting Started (5 Minutes)

You don't need all of this on day one.

Right now: Run claude /init in your project. It generates a basic CLAUDE.md from your codebase. That alone is a massive improvement over nothing.

This week: Add communication preferences and a basic session lifecycle (read memory at start, write handoff at end).

This month: Add orchestration rules as you discover patterns. Add skills for repeated workflows.

The system grows with you. You don't need to architect the whole thing upfront. Start, and let it compound.