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

Next Steps

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