What Is the CLAUDE.md File? Guide + Examples (2026)

You built your app with Claude Code. It came out great. You close the terminal. The next day you come back, open Claude... and it forgot everything: your architecture, your conventions, the decisions you made together. You start from scratch.

The CLAUDE.md file is the fix for that. It sounds boring, but it's probably the single most important part of using Claude Code well.

What Is the CLAUDE.md File?

CLAUDE.md is a text file that gives Claude Code persistent memory about your project: architecture, code conventions, and important decisions. Claude reads it automatically at the start of every session, so it doesn't forget how your project works between chats. Without it, Claude starts blank every time.

What Is It For?

It makes Claude respect, without you repeating yourself:

• Architectural decisions —why you chose tRPC over REST, etc.
• Code conventions —naming, validation, error handling
• Patterns it should follow (and the ones it should avoid)

The payoff: less regression, more consistency, and living documentation that also helps onboarding.

How to Create a CLAUDE.md

Inside your project, run:

/init

Claude reviews the whole project, analyzes the structure, and generates a starter CLAUDE.md. That's your starting point —you refine it from there.

Add Rules in Real Time with #

While you chat, you can add a rule straight to the file with the # command:

# Always use error boundaries on components that make API calls

Get in the habit of doing this whenever you notice a pattern you want Claude to follow (or stop breaking).

What a CLAUDE.md Looks Like

A well-built file looks like this:

# CLAUDE.md
 
Guidance for Claude Code when working in this repository.
 
## Architecture
- **Frontend**: React 18 + Vite, SPA
- **Backend**: Express.js REST API with SQLite
- **Communication**: frontend calls the backend at /api/
 
## Key Patterns
- Use Zod for input validation on all endpoints
- Error boundaries on components with API calls
- Follow existing naming conventions
 
## What NOT to Do
- NEVER use `any` in TypeScript
- NEVER commit secrets

The Hierarchy: You Can Have Several CLAUDE.md Files

Claude Code supports multiple files at different levels, and combines them:

~/.claude/CLAUDE.md          # Your global preferences
~/dev/CLAUDE.md              # Team/org standards
~/dev/my-project/CLAUDE.md   # Project knowledge
~/dev/my-project/backend/CLAUDE.md  # Backend patterns

Simple rule: the most specific wins. Claude reads every file that applies and prioritizes the guidance closest to what you're touching.

The 3 Mistakes That Cost Me Hours

1. Outdated CLAUDE.md. I added features and didn't update the file. Claude "forgot" decisions and recreated old code. Updating it is part of the workflow, not optional.
2. Too long. Once it passed ~150 lines, Claude started ignoring parts. Keep the core file short and move details to @docs/.
3. No "What NOT to Do" section. Documenting only what you want isn't enough —Claude needs to know what to avoid.

Healthy CLAUDE.md Checklist

• Tech stack documented
• Main commands (dev, test, build)
• At least 3 "do not" rules
• At least 1 dated decision
• Under 150 lines (the core file)
• Committed to git —it's code, not optional docs

Your next step (don't close the tab):

• Plan Mode in Claude Code — plan before executing
• Claude Pro vs Max 2026 — which plan you need
• Free course: Claude Code Mastery — includes the memory & CLAUDE.md module