How to Use CLAUDE.md: The Complete Guide to Claude Code Configuration

By Joey T · April 12, 2026 · 18 min read

If you're using Claude Code without a CLAUDE.md file, you're using it wrong.

Not in the "you'll get an error" sense. In the "you're getting 30% of the value" sense.

CLAUDE.md is Claude Code's memory system. It's how you give Claude persistent context about your project, your conventions, and your expectations — so it starts every session at full speed instead of asking you to re-explain everything from scratch.

This guide covers everything: what CLAUDE.md is, how the 3-level hierarchy works, what to put in it, real examples for different project types, and how to build configurations that make Claude Code genuinely useful instead of just occasionally impressive.

What Is CLAUDE.md?

When Claude Code starts a session in a directory, it looks for files named CLAUDE.md. Any file it finds gets loaded into the context window automatically, before any conversation starts.

That means everything in your CLAUDE.md file is effectively a system prompt — persistent instructions that shape every response Claude gives in that session.

Without CLAUDE.md: Claude starts fresh every time. It doesn't know you prefer TypeScript over JavaScript, that you use Tailwind instead of CSS modules, that the payments/ directory is sacred legacy code that should never be touched. You either repeat yourself constantly, or Claude makes decisions that don't fit your project.

With CLAUDE.md: Claude starts with full context. It writes code in your stack, follows your conventions, and respects your rules. Every session.

The 3-Level CLAUDE.md Hierarchy

This is the part most tutorials skip. Claude Code supports CLAUDE.md files at three different levels, and they work together:

Level 1: Global (~/.claude/CLAUDE.md)

Stored in your home directory's .claude/ folder. Applies to every project you open with Claude Code.

This is where you put your personal preferences and universal rules:

# Global Claude Code Settings

## My Preferences
- Language: TypeScript over JavaScript always
- Testing: Always write tests for new functions
- Git: Conventional commits (feat:, fix:, chore:, docs:)
- Comments: Explain WHY, not WHAT
- Error handling: Always explicit, never silent failures

## My Workflow
- When I ask you to "review" something: use the PR review checklist
- When I ask you to "debug" something: use the diagnostic protocol
- When I ask you to "scaffold" something: use the launcher checklist

## Never Do (Global Rules)
- Never push to main directly
- Never hardcode credentials
- Never skip error handling with catch blocks that do nothing
- Never use console.log in production code (use proper logging)

Level 2: Project Root (./CLAUDE.md)

Stored in your project's root directory. Applies to all sessions in that project. This is where most of your configuration lives.

Covers your project-specific stack, architecture, conventions, and rules.

# [Project Name] — Claude Code Configuration

## What This Project Is
[One paragraph description of what you're building and why]

## Tech Stack
- Runtime: Node.js 20
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.3 (strict mode)
- Database: PostgreSQL via Prisma ORM
- Auth: next-auth v5
- Styling: Tailwind CSS
- Testing: Vitest + Playwright

## Project Architecture
[Description of how the project is structured]

## Conventions
[Your coding conventions]

## Off-Limits Areas
[Files/directories that should not be modified]

Level 3: Directory-Level (./src/payments/CLAUDE.md)

Stored inside specific directories. Applies only to sessions focused on that directory.

This is powerful for large projects where different parts of the codebase have different rules:

# Payments Module — Special Rules

## ⚠️ HIGH SENSITIVITY CODE
This directory handles real money. Extra caution required.

## Rules for This Module
1. NEVER modify existing payment flow functions — only add new ones
2. ALL changes must have tests before merging
3. ALL Stripe API calls must use idempotency keys
4. NO direct database queries — always use the PaymentService class
5. ANY external API call must have retry logic and timeout handling

## Testing Requirements (Payments Only)
- 100% coverage on payment calculation functions
- Integration tests for all Stripe webhook handlers
- E2E tests for checkout flow before any change ships

The hierarchy works additively: global + project + directory settings all apply when you're in a subdirectory. More specific settings take precedence over general ones when there's a conflict.

What to Include in Your CLAUDE.md

Here's the complete template. Fill in what's relevant, skip what isn't.

Section 1: Project Overview

## Project Overview
[What it is, who uses it, what problem it solves]
[Current status: prototype / active development / maintenance mode]
[Team: solo / 2-3 devs / larger team]

This matters more than it seems. Claude writes code very differently for a solo prototype vs. a production system serving 10,000 users. Give it the context.

Section 2: Tech Stack

## Tech Stack
List every major technology:
- Languages and versions
- Frameworks and versions
- Key libraries (not exhaustive, just the opinionated ones)
- Database and ORM
- Auth solution
- Testing framework
- Deployment target

Be specific about versions. Claude Code knows that Next.js 13 uses pages/ and Next.js 14 uses app/. TypeScript 4 vs TypeScript 5 has meaningful differences. Versions matter.

Section 3: Project Structure

## Project Structure
src/
  app/          # Next.js App Router pages
  components/   # React components
    ui/         # Pure UI components (no data fetching)
    features/   # Feature components (can fetch data)
  lib/          # Utilities and helpers
  hooks/        # Custom React hooks
  types/        # TypeScript type definitions
  services/     # External API integrations

Key files to know:
- src/lib/db.ts — Prisma client singleton
- src/lib/auth.ts — next-auth configuration
- src/middleware.ts — Route protection rules

Section 4: Code Conventions

## Code Conventions
- Exports: Named exports everywhere except Next.js page components
- Types: Define in src/types/ or co-locate with the file that owns them
- Error handling: Always explicit. Never swallow errors silently.
- Async: async/await over .then() chains
- Null handling: Use optional chaining (?.) and nullish coalescing (??)
- Formatting: Prettier with default settings (enforced by CI)

Section 5: Domain Knowledge

This is the section most developers forget and it's often the most valuable:

## Domain Knowledge
[Key business logic that Claude needs to understand]

Example for a healthcare app:
- A "patient" is someone who has completed intake. A "lead" is pre-intake.
- Appointments can be "scheduled", "confirmed", "completed", or "cancelled"
- "Cancelled" and "no-show" are different statuses with different billing implications
- The timezone for all date calculations is Europe/Zurich unless the user has a profile timezone

Example for an e-commerce app:
- "Available" inventory = total - reserved - sold
- "Reserved" means added to a cart in the last 30 minutes
- Orders are immutable after "confirmed" status — never modify, only create adjustments

This context prevents Claude from making technically correct but semantically wrong decisions. Without domain knowledge, it might write code that treats "cancelled" and "no-show" identically. With it, it knows they're different.

Section 6: Prohibited Actions

## Prohibited Actions
- NEVER modify files in /legacy/ — read only
- NEVER use raw SQL — always use Prisma
- NEVER add new npm dependencies without flagging it for review
- NEVER push directly to main branch
- NEVER use any as a TypeScript type
- NEVER send database IDs to the frontend — use UUIDs or slugs

Be explicit about your red lines. Claude will respect them.

Section 7: Workflow Instructions

## Workflow Instructions
When I ask you to build a new feature:
1. Ask clarifying questions if the requirements aren't clear
2. Propose the data model changes first, wait for confirmation
3. Then implement the API layer
4. Then implement the UI components
5. Suggest tests as you go — don't save them for last

When I ask you to fix a bug:
1. Ask me to describe the exact behavior vs expected behavior
2. Identify and state the root cause before writing any code
3. Write the fix
4. Write a test that would have caught this bug
5. Suggest any related issues to check

Common CLAUDE.md Mistakes

Mistake 1: Being Too Vague

Bad: ## Style: Follow best practices

Good: ## Style: Named exports only. No default exports except Next.js pages. Prefer composition over inheritance. Keep components under 150 lines — split if larger.

Best practices mean different things to different developers. Be specific.

Mistake 2: Writing a Novel

Every token in your CLAUDE.md consumes context window space. A 5,000-word CLAUDE.md crowds out the actual conversation. Keep it under 1,000 tokens for general use. Put the detailed stuff in directory-level files.

Mistake 3: Never Updating It

Your CLAUDE.md should evolve as your project evolves. When you add a new service, update the structure section. When you adopt a new convention, add it. Treat CLAUDE.md like documentation — it's only useful if it's current.

Mistake 4: Forgetting the Hierarchy

Don't cram everything into one file. Use the hierarchy:

Global = your universal preferences
Project root = your project's general rules
Subdirectory = specialized rules for sensitive or complex modules

Real Example: SaaS Starter CLAUDE.md

Here's a complete, production-ready CLAUDE.md for a SaaS application:

# SaaS Starter — CLAUDE.md

## Project
A B2B SaaS for [domain]. Subscription model with free trial.
Stack: Next.js 14, TypeScript, Prisma, PostgreSQL, Stripe, Resend.

## Architecture
- All pages under src/app/ (App Router)
- API routes under src/app/api/ (server-side only — never expose to client)
- Database access only through src/lib/db.ts
- Auth checks via middleware.ts (protects /dashboard/** routes)
- Stripe webhooks at /api/webhooks/stripe

## Data Model Rules
- Users have one Subscription (nullable = free trial)
- Subscriptions have statuses: trial, active, past_due, cancelled
- Never delete users — soft delete with deletedAt timestamp
- All monetary values stored in cents (integers)

## Critical Conventions
- Server Components by default — 'use client' only for interactive elements
- All forms use react-hook-form + Zod validation
- Email sending only through src/lib/email.ts (never direct Resend calls)
- Stripe operations only through src/lib/stripe.ts
- All user-facing errors must be caught and shown gracefully (no raw errors to users)

## Prohibited
- Never return Stripe Customer IDs or subscription IDs in API responses
- Never skip the subscription check on protected features
- Never use process.env directly — use src/lib/env.ts (typed and validated)

## When Building New Features
1. Check if it requires a subscription tier — add gate if yes
2. Add it to the pricing page feature comparison
3. Add usage tracking if it's a metered feature
4. Update the admin dashboard if it produces data worth monitoring

Real Example: API Service CLAUDE.md

# Payment Service API — CLAUDE.md

## What This Is
Microservice handling payment processing. Integrates with Stripe.
This service does NOT handle auth — auth is handled upstream by the API gateway.

## Non-Negotiables
- Idempotency keys on ALL Stripe API calls
- Retry with exponential backoff for external API failures
- Every database write wrapped in a transaction
- Webhook signature verification before processing any event
- Structured logging via pino — never console.log

## Error Handling Policy
- NEVER throw generic Error("something went wrong")
- Always throw domain errors from src/errors/
- Include: errorCode, message, context, requestId
- HTTP status codes must be semantically correct

## Testing Requirements
- All payment calculation functions: 100% unit test coverage
- All Stripe webhook handlers: integration tests with mocked Stripe
- End-to-end checkout flow: E2E test before any deploy
- Load testing before any scaling change

CLAUDE.md vs System Prompts: The Difference

If you've worked with Claude via API, you're familiar with system prompts. CLAUDE.md is similar but with key differences:

Feature	CLAUDE.md	System Prompt (API)
Scope	Directory/project-specific	Conversation-specific
Hierarchy	3 levels (global, project, dir)	Single prompt per request
Persistence	Loaded automatically on open	Must be passed each request
Version control	Yes — committed with code	No (usually)
Team sharing	Yes — shared in repo	Per-implementation

The big advantage of CLAUDE.md: it's committed to your repository. Your whole team benefits from the same context. New team members get a Claude that already knows the project from day one.

Advanced: Using CLAUDE.md for Workflow Modes

One of the most powerful patterns is using CLAUDE.md to define modes that change how Claude operates based on your current task. Check out the detailed configurations in Best Claude Code Workflows 2026 — specifically the Full-Stack Launcher, PR Reviewer, and Bug Hunter modes.

The core idea: your CLAUDE.md can say "When I say 'review', apply these criteria. When I say 'debug', follow this protocol." This gives you the benefit of specialized prompts without having to remember them — they're baked into your project config.

The Shortcut: Pre-Built Workflow Configs

Building a good CLAUDE.md from scratch takes time. You need to think through your conventions, document your architecture, and iterate on the instructions until Claude behaves exactly how you want.

If you'd rather skip that process and start with proven configurations, the Claude Code Workflow Pack has 5 production-tested CLAUDE.md files for different workflow types, plus project-type templates for Next.js, FastAPI, and monorepos. Each one is ready to customize — change the stack details, add your project-specific rules, and you're set.

Skip the Setup — Get the Workflow Pack

5 production-ready CLAUDE.md configs + project templates. Start with proven configurations instead of building from scratch.

Buy on Stripe — $19 Buy on Gumroad — $19

Getting Started: Your First CLAUDE.md in 10 Minutes

Here's the minimum viable CLAUDE.md that will make an immediate difference:

# [Your Project Name]

## Stack
[List your main technologies here]

## What This Project Is
[One sentence description]

## Most Important Rules
1. [Your most important convention]
2. [Your second most important rule]
3. [What you never want Claude to do]

## Key File Locations
- Main entry point: [path]
- Config: [path]
- Tests: [path]

That's it. 15 lines. Start there. Claude will immediately be more useful in your project than it was without it.

Expand it over time as you discover what context Claude is missing. The best CLAUDE.md files aren't written in one sitting — they grow as you use Claude Code and notice where it makes wrong assumptions.