The CLAUDE.md System

CLAUDE.md is your project's persistent memory. It tells Claude everything it needs to know about your codebase.

What is CLAUDE.md?

CLAUDE.md is a special markdown file that Claude reads at the start of every session. It contains:

Project overview and architecture
Development commands and workflows
Coding standards and conventions
Important context and decisions

Creating Your CLAUDE.md

Create a file named CLAUDE.md in your project root:

# Project: My Awesome App
 
## Overview
A Next.js e-commerce platform with Stripe payments.
 
## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Prisma ORM with PostgreSQL
- Redis for caching
- Stripe for payments
 
## Commands
- `npm run dev` - Start development server
- `npm run test` - Run test suite
- `npm run build` - Production build
 
## Architecture
- `/app` - Next.js pages and routes
- `/lib` - Shared utilities
- `/components` - React components
- `/prisma` - Database schema
 
## Conventions
- Use TypeScript strict mode
- Components use PascalCase
- Utilities use camelCase
- Always add tests for new features

What to Include

Always Include

Tech stack - Languages, frameworks, databases
Commands - How to run, test, build
Architecture - Folder structure overview
Conventions - Coding standards

Optionally Include

Current focus - What you're working on
Known issues - Bugs or technical debt
API patterns - How endpoints work
Testing strategy - What to test and how

CLAUDE.md Hierarchy

Claude reads CLAUDE.md files at multiple levels:

~/CLAUDE.md              # Global (user-level)
./CLAUDE.md              # Project root
./src/CLAUDE.md          # Directory-specific

More specific files override general ones.

Pro Tips

Keep It Updated

Update CLAUDE.md as your project evolves:

> Add to CLAUDE.md that we now use Zod for validation

Be Specific About Preferences

## Preferences
- Prefer functional components over class components
- Use named exports, not default exports
- Always destructure props in function signature

Include Common Mistakes

## Common Mistakes to Avoid
- Don't use `any` type - always define proper types
- Don't forget to handle loading states
- Always await database calls

CLAUDE.md Evolution Over Time

Your CLAUDE.md shouldn't be static. Here's how it should grow:

Week 1: The Basics

# My Project
 
## Tech Stack
- React 18 + TypeScript
- Node.js + Express
- PostgreSQL
 
## Commands
- `pnpm dev` - development
- `pnpm test` - tests

Month 1: Emerging Patterns

# My Project
 
## Tech Stack
[...]
 
## Code Patterns
- Use Zod for input validation
- Error boundaries on API call components
- Naming: camelCase for variables, PascalCase for components
 
## Architectural Decisions
- 2024-01-15: Chose tRPC over REST for type-safety
- 2024-01-20: Migrated from SQLite to PostgreSQL for concurrency

Month 3: Mature Document

# My Project
 
## Tech Stack
[...]
 
## Code Patterns
[Refined patterns with examples]
 
## Architectural Decisions
[Log of important decisions]
 
## What NOT To Do
- NEVER use `any` in TypeScript
- NEVER do raw SQL queries (use ORM)
- NEVER commit secrets
 
## Onboarding
1. Clone repo
2. Copy .env.example to .env
3. Run `pnpm install && pnpm dev`
4. Read docs/architecture.md

Signs of a Healthy CLAUDE.md

Sign	What It Means
Has dates	Decisions have temporal context
Has "Do NOT"	You've learned from mistakes
Updated monthly	It's alive, not abandoned
Juniors understand it	Useful for onboarding

For Teams: Organizational CLAUDE.md

If you work in a team, you need a clear hierarchy:

Recommended Structure

~/.claude/CLAUDE.md              # Personal preferences (not shared)
~/company/CLAUDE.md              # Company standards (shared)
~/company/project/CLAUDE.md      # Project rules (shared)

Organizational Template

# [Company] - Development Standards
 
## Principles
- Ship > Perfect
- Tests for critical code
- Document decisions, not code
 
## Approved Stack
- Frontend: React 18, Next.js 14+
- Backend: Node.js 20+, tRPC
- DB: PostgreSQL (production), SQLite (dev)
- Hosting: Vercel (frontend), Railway (backend)
 
## Conventions
- Commits: Conventional Commits (feat, fix, docs, etc)
- Branches: feature/*, fix/*, hotfix/*
- PRs: Require 1 approval minimum
 
## Security
- Secrets in environment variables, NEVER in code
- Use tokens with minimum privilege
- Rotate API keys every 90 days
 
## What Claude Should NOT Do
- Modify files in /config/production/
- Execute deploy commands
- Access production secrets

Governance: Who Updates What

File	Who Approves	Frequency
Org CLAUDE.md	Tech Lead/CTO	Quarterly
Project CLAUDE.md	Team Lead	Monthly
Personal CLAUDE.md	Individual	Free

Common Errors

Error 1: Outdated CLAUDE.md

The error: Added features but didn't update CLAUDE.md with new decisions.

The cost: Claude "forgot" architectural decisions and recreated old code. Had to refactor twice.

The lesson: Updating CLAUDE.md is part of the development workflow, not optional.

Error 2: CLAUDE.md Too Long

The error: My CLAUDE.md had 500 lines. Claude processed it but ignored important parts.

The cost: Inconsistencies because Claude couldn't absorb everything.

The lesson: Keep main CLAUDE.md under 150 lines. Use @docs/ for details.

Challenge: Create Your CLAUDE.md

Before continuing, create a CLAUDE.md for your current project:

Run /init in your project
Review what Claude generated - it's a starting point
Add a "What NOT To Do" section with 3 rules minimum
Add a date to at least one architectural decision
Commit the file - it's code, not optional documentation

Next Steps

In the next lesson, you'll learn advanced context management for large projects.