CLAUDE.md: Your Project's AI Memory File Explained

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that provides Claude Code with project-specific instructions and context. Think of it as onboarding documentation for your AI pair programmer.

When Claude Code starts, it automatically reads:

1. →Project CLAUDE.md: .claude/CLAUDE.md or CLAUDE.md at your project root
2. →User CLAUDE.md: ~/.claude/CLAUDE.md for personal preferences across all projects
3. →Parent directories: CLAUDE.md files in parent folders (for monorepos)

This layered system lets you define global preferences while overriding them per-project.

Why CLAUDE.md Matters

Without CLAUDE.md, Claude Code:

• →Doesn't know your coding conventions
• →May suggest patterns that don't match your codebase
• →Needs repeated explanations of your architecture
• →Might touch files it shouldn't

With a well-crafted CLAUDE.md, Claude Code:

• →Follows your team's coding standards
• →Understands your architecture and patterns
• →Knows which areas are off-limits
• →Provides consistent, project-appropriate assistance

What actually goes in a good CLAUDE.md (and what doesn't)

The CLAUDE.md discourse has matured significantly since the file became a standard part of Anthropic's Claude Code workflow. The threads on r/ClaudeAI, r/ChatGPTCoding, and r/ExperiencedDevs show a pattern: teams that start with exhaustive CLAUDE.md files rewrite them within weeks once they realise what actually moves the needle.

What consistently helps:

• →The 3-5 decisions that shape your codebase. Framework choice, testing philosophy, error-handling style, database patterns, naming conventions. Claude uses these as anchors when it writes code.
• →A brief "do not touch" list. Vendor folders, generated code, specific sensitive paths. The denylist is more valuable than the allowlist because most files are fine.
• →The exact commands to run tests, lint, typecheck, build. Claude uses these without re-inferring them, saving tokens and preventing wrong-command errors.
• →Named examples of good patterns. "See src/api/users.ts for the canonical controller structure." Pointer-to-example beats prose description.
• →Non-obvious invariants. Anything a senior engineer would explain on day one that isn't documented elsewhere.

What quietly hurts:

• →Full architectural essays. Claude reads CLAUDE.md on every start. Long documents consume context budget and dilute the high-signal sections.
• →Information available from running the tooling. Don't duplicate package.json content, tsconfig, or ESLint config. Claude reads those natively.
• →Aspirational standards you don't enforce. If the codebase routinely violates a rule, Claude will too, but it'll waste tokens pretending to follow it. Either enforce it in CI or remove it from CLAUDE.md.
• →Company branding, project history, marketing copy. Irrelevant to code generation.
• →Secrets, credentials, or internal URLs. Treat CLAUDE.md as publicly visible. Use .env and git-secrets instead.

Advanced patterns that actually scale:

• →Layered CLAUDE.md files. A root CLAUDE.md for monorepo-wide conventions; per-package files for specific context. Anthropic's docs describe the merge behaviour.
• →User-level ~/.claude/CLAUDE.md for personal preferences. Preferred language, verbosity, commit message style. Keeps project-level files focused on the codebase.
• →Periodic pruning. A CLAUDE.md that grew organically is usually 40% noise. Set a reminder quarterly to strip anything that isn't earning its tokens.
• →.claudeignore is as important as CLAUDE.md. Keep auto-generated files, lockfiles, and large data fixtures out of Claude's context entirely.

The honest framing: CLAUDE.md is a leverage tool, not a documentation project. The best CLAUDE.md files in 2026 are shorter than the earliest examples, more opinionated, and ruthlessly focused on what changes Claude's output. If a section doesn't measurably improve what Claude writes, it's costing you tokens and attention for no gain. Treat it as production code: review it, prune it, verify it works.

Creating Your First CLAUDE.md

Quick Start with /init

The fastest way to create a CLAUDE.md is with the /init command:

> /init

Claude Code will:

1. →Scan your project structure
2. →Identify frameworks, languages, and patterns
3. →Generate a tailored CLAUDE.md file
4. →Ask if you want to customize it

Manual Creation

Create a file at your project root:

touch CLAUDE.md
# or
mkdir -p .claude && touch .claude/CLAUDE.md

Start with this template:

# Project: [Your Project Name]

## Overview
[Brief description of what this project does]

## Tech Stack
- [Language/Framework 1]
- [Language/Framework 2]
- [Database]
- [Other tools]

## Project Structure
[Key directories and their purposes]

## Conventions
[Coding standards and patterns to follow]

## Important Notes
[Things Claude should know or avoid]

CLAUDE.md Structure Best Practices

1. Project Overview

Start with the big picture so Claude understands context:

# Project: E-Commerce Platform

## Overview
A B2B e-commerce platform for wholesale distributors. Handles inventory 
management, order processing, and multi-tenant storefronts.

## Business Context
- Primary users: Warehouse managers and procurement teams
- Peak usage: Monday-Friday, business hours
- Critical flows: Order placement, inventory sync, invoice generation

2. Tech Stack

Be specific about versions and configurations:

## Tech Stack

### Frontend
- Next.js 14 with App Router
- TypeScript 5.3 (strict mode)
- Tailwind CSS 3.4
- React Query for data fetching

### Backend
- Node.js 20 LTS
- Express.js with TypeScript
- Prisma ORM 5.x
- PostgreSQL 15

### Infrastructure
- Vercel (frontend)
- Railway (backend + database)
- Redis for caching
- S3 for file storage

3. Project Structure

Map out your directory structure:

## Project Structure

- **apps/web/** - Next.js frontend
- **apps/api/** - Express backend
- **packages/ui/** - Shared component library
- **packages/config/** - Shared configuration
- **packages/types/** - Shared TypeScript types
- **prisma/schema.prisma** - Database schema
- **prisma/migrations/** - Migration files
- **scripts/** - Development and deployment scripts

### Key Directories
- `apps/web/app/`: Next.js App Router pages and layouts
- `apps/api/src/routes/`: API endpoint handlers
- `packages/ui/src/components/`: Reusable UI components

4. Coding Conventions

Define standards Claude should follow:

## Coding Conventions

### TypeScript
- Use strict mode, no `any` types without justification
- Prefer interfaces over types for object shapes
- Use Zod for runtime validation

### React Components
- Functional components only
- Custom hooks in `hooks/` directory
- Use named exports, not default exports

### Naming
- Components: PascalCase (e.g., `UserProfile.tsx`)
- Utilities: camelCase (e.g., `formatDate.ts`)
- Constants: UPPER_SNAKE_CASE
- Database tables: snake_case

### File Organization
- One component per file
- Co-locate tests: `Component.tsx` → `Component.test.tsx`
- Shared types in `types/` directory

### Git
- Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`
- Branch naming: `feature/`, `fix/`, `chore/`
- Squash merge to main

5. Important Notes and Restrictions

Tell Claude what to avoid:

## Important Notes

### Off-Limits Areas
- **DO NOT** modify `/apps/api/src/billing/` - handled by external payment team
- **DO NOT** change database schema without creating a migration
- **DO NOT** commit `.env` files or expose API keys

### Critical Considerations
- All API endpoints must validate input with Zod schemas
- Database queries must use Prisma transactions for multi-table updates
- Frontend routes require authentication middleware

### Known Issues
- The legacy `/api/v1/` routes are deprecated but still used by mobile app
- Redis connection sometimes fails in dev - restart with `npm run redis:restart`

### External Dependencies
- Stripe webhook signatures must match `STRIPE_WEBHOOK_SECRET`
- SendGrid templates are managed in their dashboard, not in code

6. Common Tasks

Provide guidance for frequent operations:

## Common Tasks

### Adding a New API Endpoint
1. Create route handler in `apps/api/src/routes/`
2. Add Zod schema in `apps/api/src/schemas/`
3. Register route in `apps/api/src/index.ts`
4. Add tests in `apps/api/src/routes/__tests__/`

### Creating a Database Migration
```bash
cd apps/api
npx prisma migrate dev --name description_of_change

Running Tests

npm run test          # All tests
npm run test:unit     # Unit tests only
npm run test:e2e      # End-to-end tests

Local Development

npm run dev           # Start all services
npm run dev:web       # Frontend only
npm run dev:api       # Backend only

---

## Advanced CLAUDE.md Patterns

### Dynamic Content with Commands

Include live data from your project:

```markdown
## Current Dependencies

Main dependencies from package.json:
- See `package.json` for full list

## Recent Changes

Check recent commits with:
```bash
git log --oneline -10

### Environment-Specific Instructions

```markdown
## Environment Notes

### Development
- Use `.env.local` for local overrides
- Database: Local PostgreSQL on port 5432
- API runs on http://localhost:3001

### Staging
- Database: Railway staging instance
- Requires VPN for access

### Production
- Never run migrations directly
- Changes require PR review from 2 team members

Team Roles and Ownership

## Team Ownership

| Area | Owner | Notes |
|------|-------|-------|
| Frontend | @frontend-team | All `/apps/web/` |
| API | @backend-team | All `/apps/api/` |
| Database | @data-team | Schema changes need review |
| Payments | @billing-team | External - don't modify |
| DevOps | @platform-team | CI/CD and infrastructure |

Integration with Custom Commands

Reference your custom slash commands:

## Custom Commands

We have custom slash commands for common workflows:

- `/deploy-staging` - Deploy current branch to staging
- `/db-migrate` - Run pending database migrations
- `/generate-types` - Regenerate TypeScript types from Prisma

See `.claude/commands/` for implementation details.

For more on custom commands, see Custom Slash Commands in Claude Code: Build Your Own.

CLAUDE.md Locations and Priority

Claude Code reads multiple CLAUDE.md files in a specific order:

User-Level CLAUDE.md

Create ~/.claude/CLAUDE.md for personal preferences:

# Personal Preferences

## Coding Style
- I prefer explicit type annotations
- Use descriptive variable names
- Add comments for complex logic

## Communication
- Explain your reasoning briefly
- Show diffs for file changes
- Ask before making large refactors

## Tools I Use
- VS Code with Vim keybindings
- iTerm2 on macOS
- Prefer npm over yarn

Monorepo Pattern

For monorepos, use multiple CLAUDE.md files:

• →my-monorepo/CLAUDE.md - Root: shared conventions
• →apps/web/CLAUDE.md - Frontend-specific
• →apps/api/CLAUDE.md - Backend-specific
• →packages/ui/CLAUDE.md - Component library-specific

Root CLAUDE.md:

# Monorepo: My Platform

## Shared Conventions
- All packages use TypeScript strict mode
- Shared types in `/packages/types/`
- Use workspace dependencies: `"@myorg/ui": "workspace:*"`

App-specific CLAUDE.md:

# Frontend App

Inherits from root CLAUDE.md.

## Additional Conventions
- Use Next.js App Router patterns
- Server components by default
- Client components marked with 'use client'

Managing CLAUDE.md with /memory

The /memory command provides an interface for editing memory files:

> /memory

This opens an interactive menu to:

• →View current CLAUDE.md content
• →Edit project CLAUDE.md
• →Edit user CLAUDE.md
• →See what Claude remembers

Updating Memory Mid-Session

You can also add to Claude's memory during a conversation:

> Remember that we're migrating from REST to GraphQL. 
> New endpoints should use GraphQL, but maintain REST compatibility.

Claude will offer to add this to your CLAUDE.md.

Real-World CLAUDE.md Examples

Example 1: React + TypeScript SaaS

# Project: TaskFlow - Project Management SaaS

## Overview
A Trello-like project management app with real-time collaboration.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict)
- Prisma + PostgreSQL
- Socket.io for real-time
- Tailwind + Radix UI

## Architecture
- Feature-based folder structure: `/features/[feature]/`
- Each feature has: components/, hooks/, api/, types/
- Shared UI in `/components/ui/` (Radix-based)

## Conventions
- React Query for server state
- Zustand for client state
- Zod for validation (shared between client/server)
- No `any` types - use `unknown` and narrow

## Critical Rules
1. All database writes must be in transactions
2. Real-time events go through `/lib/realtime/emit.ts`
3. Never store sensitive data in client state
4. All API routes need authentication middleware

Example 2: Python FastAPI Backend

# Project: DataPipeline API

## Overview
REST API for data processing pipeline management.

## Tech Stack
- Python 3.11
- FastAPI + Pydantic v2
- SQLAlchemy 2.0 + PostgreSQL
- Celery + Redis for async tasks
- Docker Compose for local dev

## Project Structure

- **src/api/** - FastAPI routes
- **src/models/** - SQLAlchemy models
- **src/schemas/** - Pydantic schemas
- **src/services/** - Business logic
- **src/tasks/** - Celery tasks
- **src/utils/** - Helpers

## Conventions
- Type hints required everywhere
- Docstrings for public functions (Google style)
- Async/await for I/O operations
- Dependency injection via FastAPI Depends

## Commands
- `make dev` - Start development server
- `make test` - Run pytest
- `make lint` - Run ruff + mypy

## Important
- Long-running tasks MUST use Celery, not synchronous endpoints
- All endpoints need OpenAPI documentation
- Database migrations via Alembic only

Example 3: Mobile App (React Native)

# Project: FitTrack Mobile

## Overview
Fitness tracking app with workout logging and progress analytics.

## Tech Stack
- React Native 0.73 + Expo SDK 50
- TypeScript
- React Query + Zustand
- React Navigation 6

## Conventions
- Functional components with hooks
- Styles: StyleSheet.create, not inline
- Icons: @expo/vector-icons only
- Animations: Reanimated 3

## Platform Notes
- Test on both iOS and Android before PR
- Use Platform.select for platform-specific code
- Safe area handling via react-native-safe-area-context

## Off-Limits
- Don't modify native modules without tech lead approval
- Don't add native dependencies without checking Expo compatibility
- Push notifications handled by external service

## Testing
- Jest for unit tests
- Detox for E2E (run on CI only)

Troubleshooting CLAUDE.md

Claude Isn't Following Instructions

1. →Check file location: Must be CLAUDE.md or .claude/CLAUDE.md at project root
2. →Verify syntax: Ensure valid Markdown formatting
3. →Be specific: Vague instructions get vague results
4. →Restart session: Claude loads CLAUDE.md at session start

Instructions Conflicting

If user and project CLAUDE.md conflict, project wins. Be explicit:

## Override User Preferences
For this project, ignore personal preferences about:
- We use Yarn, not npm
- We use tabs, not spaces

CLAUDE.md Getting Too Long

Keep it focused. Move detailed documentation elsewhere:

## Documentation
- API docs: `/docs/api/`
- Architecture: `/docs/architecture.md`
- Onboarding: `/docs/onboarding.md`

Claude can read these files when needed.

In Brief

1. →

   CLAUDE.md is project memory: It persists context across sessions so Claude understands your project deeply.

2. →

   Use /init to get started: Let Claude generate an initial CLAUDE.md, then customize it.

3. →

   Be specific and structured: Clear sections for overview, tech stack, conventions, and restrictions.

4. →

   Layer your configurations: User-level for personal preferences, project-level for team standards.

5. →

   Keep it maintained: Update CLAUDE.md as your project evolves-it's living documentation.

Ready to Get Structured Outputs from AI?

Now that Claude understands your project through CLAUDE.md, it's time to learn how to get consistent, structured responses.

In our Module 2, Structured Outputs, you'll learn:

• →How to get reliable JSON, tables, and formatted responses
• →Techniques for consistent output formatting
• →Schema definition and validation patterns
• →Real-world examples of structured prompting

→ Explore Module 2: Structured Outputs