What is CLAUDE.md?

Understanding CLAUDE.md Files

CLAUDE.md is a markdown configuration file that provides persistent instructions to Claude Code, Anthropic's CLI-based AI coding assistant. It defines project context, coding standards, and preferences that Claude references in every conversation. This file is essential for consistent AI-assisted development across your codebase.

Think of CLAUDE.md as Claude Code's memory system. Without it, Claude starts each session with no knowledge of your project's conventions, preferred patterns, or unique requirements. With a well-crafted CLAUDE.md, Claude understands your project from the first prompt.

Where Does CLAUDE.md Go in Your Project?

CLAUDE.md files can be placed in multiple locations, each with different scope:

• Project root (most common) — Create CLAUDE.md and commit it to git for team sharing
• Personal settings — Use CLAUDE.local.md and add to .gitignore for personal preferences
• Global settings — Place at ~/.claude/CLAUDE.md to apply to all sessions
• Subdirectories — Additional CLAUDE.md files in child directories for component-specific rules

How Claude Code Reads Your CLAUDE.md

Claude Code automatically loads CLAUDE.md contents and prepends them to every prompt. The file is read when you start a session, and changes are picked up on subsequent messages. You can also use the /init command to generate a starter CLAUDE.md for your project.

CLAUDE.md File Structure

There's no required format for CLAUDE.md files, but a clear structure helps Claude understand your project better. Here's a recommended template:

# Project Overview

This is a Next.js 14 e-commerce application using App Router, TypeScript, and Tailwind CSS.

## Tech Stack

- Next.js 14 with App Router
- TypeScript (strict mode)
- Tailwind CSS for styling
- Prisma with PostgreSQL
- NextAuth.js for authentication

## Project Structure

```
src/
├── app/           # Next.js App Router pages
├── components/    # React components
├── lib/           # Utility functions
├── hooks/         # Custom React hooks
└── types/         # TypeScript type definitions
```

## Code Style

- Use functional components with hooks
- Prefer named exports over default exports
- Use `async/await` over Promise chains
- Keep components under 200 lines
- Use TypeScript strict mode

## Testing

- Run tests with `npm test`
- Use Jest for unit tests
- Use Playwright for E2E tests
- Maintain >80% coverage

## Common Commands

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run lint` - Run ESLint
- `npm run test` - Run tests

Best Practices for Writing CLAUDE.md

Keep Instructions Concise

The contents of CLAUDE.md are prepended to your prompts, consuming part of your token budget. A bloated file costs more and can introduce noise. Use short, declarative bullet points instead of long paragraphs.

Focus on the Three W's

• WHAT — Your tech stack, project structure, dependencies
• WHY — The purpose of the project and its components
• HOW — How Claude should work on your project (e.g., use bun instead of npm)

Include Specific Commands

Document common bash commands, test commands, and build processes. This helps Claude execute the right commands without asking.

Iterate and Refine

Your CLAUDE.md becomes part of Claude's prompts, so treat it like any frequently used prompt. Experiment with different instructions to see what produces the best results. Use the # key to add instructions on the fly.

CLAUDE.md Examples by Project Type

React/Next.js Project

# Next.js E-commerce App

## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS + shadcn/ui
- Prisma + PostgreSQL
- Stripe for payments

## Conventions
- Use Server Components by default
- Client Components only when needed (interactivity, hooks)
- Colocate components with their routes
- Use Zod for validation
- All API routes in app/api/

## Commands
- `pnpm dev` - Development
- `pnpm build` - Production build
- `pnpm db:push` - Push schema changes
- `pnpm db:studio` - Open Prisma Studio

Python Backend Project

# FastAPI Backend Service

## Stack
- Python 3.12
- FastAPI + Pydantic v2
- SQLAlchemy 2.0 + Alembic
- PostgreSQL
- Poetry for deps

## Structure
- src/api/ - Route handlers
- src/models/ - SQLAlchemy models
- src/schemas/ - Pydantic schemas
- src/services/ - Business logic
- tests/ - Pytest tests

## Style
- Use async/await everywhere
- Type hints required
- Docstrings for public functions
- Black + isort formatting

## Commands
- `poetry run uvicorn src.main:app --reload`
- `poetry run pytest`
- `poetry run alembic upgrade head`

AGENTS.md — Multi-Agent Configuration

AGENTS.md is a companion file for more advanced Claude Code setups. While CLAUDE.md provides general project context, AGENTS.md defines specific agent behaviors for complex workflows. You can use both files together.

Use AGENTS.md when you need to define multiple specialized agents or when your project requires different behaviors in different contexts.

Common CLAUDE.md Mistakes to Avoid

Managing CLAUDE.md Files Across Projects

If you work on multiple projects, managing CLAUDE.md files across all of them can become tedious. You might want to share common patterns, keep track of what's in each file, or quickly update configurations across repositories.

Tools like ClaudeMDEditor provide a visual interface for managing all your AI coding assistant config files — including CLAUDE.md, .cursorrules, copilot-instructions.md, and more — from one place.

Related Guides

Frequently Asked Questions

Manage Your CLAUDE.md Files Visually

ClaudeMDEditor lets you browse, edit, and organize CLAUDE.md files across all your projects. Plus it handles .cursorrules, copilot-instructions.md, and more.

One-time purchase for macOS Tahoe (26+)