Skip to main content
CLAUDE.md

CLAUDE.md Deep Guide

CLAUDE.md is persistent context that Claude reads at the start of every session. A well-crafted one dramatically improves output quality.

File Hierarchy

Claude Code reads CLAUDE.md files at multiple levels, from broadest to most specific:

  1. ~/.claude/CLAUDE.md — Global preferences (applies to all projects)
  2. ./CLAUDE.md — Project root (main project context)
  3. ./src/CLAUDE.md — Subdirectory overrides (specialized context for that area)

All levels are merged. Subdirectory files add to (not replace) the project root file. Place information at the most specific level where it applies.

The Precision Principle

For every line in your CLAUDE.md, ask: if I remove this, will Claude make a mistake?

  • If yes → keep it
  • If no → remove it

A shorter, precise CLAUDE.md outperforms a long, generic one. Every token in the context window has a cost — irrelevant context dilutes Claude's attention on what matters.

What to Include

Build & Test Commands

The most impactful content. Claude will use these to run, test, and lint your code:

## Build & Test
- npm run dev        # start dev server (port 3000)
- npm test           # run all tests
- npm test -- -t "auth"  # run tests matching "auth"
- npm run lint       # eslint check
- npm run typecheck  # tsc --noEmit

Architecture & Key Files

## Architecture
- Monorepo: apps/web (Next.js), apps/api (Express), packages/shared
- Database: PostgreSQL via Prisma (schema at prisma/schema.prisma)
- Auth: NextAuth.js with JWT strategy
- Key entry: apps/web/src/pages/_app.tsx

Coding Conventions

Only include conventions that Claude would get wrong without explicit instruction:

## Conventions
- Use server actions instead of API routes for mutations
- All dates stored as UTC, displayed in user timezone
- Error boundaries wrap each route segment
- Never use any; prefer unknown + type narrowing

Project-Specific Warnings

## Warnings
- The payments module uses Stripe API v2023-10-16 (NOT latest)
- Do not modify migration files after they've been applied
- The legacy/ directory is being phased out; do not add new code there

Generating & Updating

  • /init — Auto-generate a CLAUDE.md by scanning your project
  • # key — Interactively update CLAUDE.md during a session (Claude suggests additions based on the conversation)
  • Manual editing — Treat it like any other config file; review and trim regularly

Anti-Patterns

  • Dumping your entire README — CLAUDE.md is not documentation. It is operational context.
  • Listing every file — Claude can explore the filesystem. Only list files that are non-obvious entry points.
  • Generic coding advice — "Write clean code" adds nothing. "Use server actions instead of API routes" is actionable.
  • Never updating — Your project evolves. Revisit CLAUDE.md when major architecture changes happen.

Why does concise context beat more context?

LLMs have a finite context window. Every irrelevant token competes for attention with the tokens that matter. Understanding this attention mechanism is key to effective prompt engineering — whether in CLAUDE.md or any other prompt.

Learn Prompts & Structured Output fundamentals

Next Steps