What is CLAUDE.md? The Complete Guide

Introduction

If you've been using Claude Code for more than a few sessions, you've probably noticed something frustrating: Claude keeps forgetting your project's conventions. Every new conversation starts from scratch. You find yourself repeating the same instructions about your tech stack, coding standards, and file organization.

CLAUDE.md solves this problem. It's Claude Code's project configuration file, a markdown document that lives in your repository and tells Claude everything it needs to know about your project. When Claude Code starts a session in your project directory, it automatically reads CLAUDE.md and applies those instructions to every interaction.

Think of CLAUDE.md as your project's constitution for AI-assisted development. It defines the rules, conventions, and context that Claude should follow, ensuring consistency across every session and every developer on your team.

Why CLAUDE.md Exists

Claude Code was designed with a fundamental insight: context is everything. Without persistent context, every conversation with Claude is like talking to someone with amnesia. You might have the most productive session of your life, establishing perfect patterns and conventions, but the next time you open Claude Code, all that understanding is gone.

CLAUDE.md provides three critical benefits:

Persistent Instructions Across Sessions

Your CLAUDE.md file loads automatically every time Claude Code runs in your project. Instructions you write once apply forever. No more copy-pasting the same context into every conversation.

Project-Specific Context

Every project is different. A React Native app has different conventions than a Django backend. CLAUDE.md lets you encode your project's unique requirements, patterns, and anti-patterns so Claude understands your specific codebase, not just generic best practices.

Team Consistency

When CLAUDE.md lives in your repository, every developer on your team gets the same Claude experience. The junior developer and the tech lead both work with Claude that understands your architecture. No more "Claude does it differently for me" problems.

Where to Put It

CLAUDE.md should live in the root of your project directory. This is the same folder that contains your package.json, .git folder, or other project configuration files.

my-project/
  CLAUDE.md          # <- Here, at the root
  package.json
  src/
    components/
    services/
  tests/

Naming Conventions

The file must be named exactly CLAUDE.md (all caps). Claude Code looks for this specific filename. Variations like claude.md, Claude.md, or CLAUDE.txt won't be recognized.

What to Include in CLAUDE.md

A well-structured CLAUDE.md typically includes these sections:

Project Description

Start with a brief overview of what your project does. This helps Claude understand the domain and make contextually appropriate suggestions.

# Project: TaskFlow

A project management application built for remote teams.
Key features: task boards, time tracking, team chat, reporting.

Target users: Small to medium tech companies (10-100 employees).

Tech Stack

List your technologies explicitly. Claude can infer some things from your code, but being explicit prevents guesswork and ensures Claude uses the right APIs and patterns.

## Tech Stack

- **Frontend:** React 18, TypeScript, Tailwind CSS
- **Backend:** Node.js, Express, PostgreSQL
- **Auth:** Auth0
- **Hosting:** Vercel (frontend), Railway (backend)
- **Testing:** Jest, React Testing Library, Playwright

Coding Conventions

This is where you encode your team's standards. Be specific about the patterns Claude should follow.

## Coding Conventions

- Use functional components with hooks, never class components
- Prefer named exports over default exports
- Use async/await, never raw Promises with .then()
- All API calls go through services/, never directly in components
- Error boundaries wrap every route-level component
- Use descriptive variable names; avoid abbreviations

File Structure Overview

Help Claude navigate your codebase by explaining where things live.

## File Structure

src/
  components/     # Reusable UI components
  features/       # Feature-specific code (screens + logic)
  services/       # API calls and external integrations
  hooks/          # Custom React hooks
  utils/          # Pure utility functions
  types/          # TypeScript type definitions

Do's and Don'ts

Explicit anti-patterns are just as important as patterns. Tell Claude what to avoid.

## Do's and Don'ts

DO:
- Write unit tests for all business logic
- Use existing components from components/ before creating new ones
- Follow the established error handling pattern in services/

DON'T:
- Use any type in TypeScript
- Put business logic in React components
- Use inline styles (use Tailwind classes)
- Create new utility functions without checking utils/ first

Common Commands

Include commands Claude might need to run or help you with.

## Common Commands

- `npm run dev` - Start development server
- `npm run test` - Run test suite
- `npm run lint` - Check for linting errors
- `npm run build` - Production build
- `npm run db:migrate` - Run database migrations

Example CLAUDE.md Files

Here are two real-world examples showing simple and complex configurations.

Simple Project Example

For a straightforward single-platform project, keep CLAUDE.md concise:

# Personal Blog - Next.js

A minimal blog built with Next.js 14 and MDX.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- MDX for content

## Conventions
- Use Server Components by default
- Client Components only when necessary (interactivity)
- Keep components small and focused
- All blog posts live in content/posts/

## Commands
- `npm run dev` - Development
- `npm run build` - Build for production
- `npm run new-post` - Create new blog post template

Complex Multi-Platform Example

For projects with multiple platforms or team members, CLAUDE.md needs more structure:

# FinanceTracker - Multi-Platform App

Personal finance tracking across iOS, Web, and shared backend.

## Architecture Overview
- iOS app (Swift/SwiftUI)
- Web app (React/TypeScript)
- Shared backend (Firebase)

## Critical: Field Naming
ALL platforms MUST use identical field names:
- `userId` (not user_id, userID, or uid)
- `createdAt` (not created_at or timestamp)
- `isActive` (not active or is_active)

See ECOSYSTEM.md for complete schema definitions.

## Platform-Specific Rules

### iOS (ios/)
- Use SwiftUI, not UIKit
- Services go in Services/, ViewModels in ViewModels/
- Follow existing patterns in existing files

### Web (web/)
- React functional components only
- API calls through services/, not in components
- Use Zustand for state management

### Firebase (functions/)
- All functions use TypeScript
- Validate inputs with Zod schemas
- Return consistent { success, data, error } format

## Before Making Changes
1. Check ECOSYSTEM.md for schema definitions
2. Ensure changes work on ALL platforms
3. Run validation: ./scripts/validate.sh

Best Practices

Keep It Focused

CLAUDE.md should be a reference document, not a novel. Aim for 200-500 lines maximum. If you find yourself writing extensive documentation, consider splitting into separate files and referencing them.

Update It As Your Project Evolves

Your CLAUDE.md should grow with your project. When you establish new patterns, add them. When conventions change, update the file. A stale CLAUDE.md is worse than no CLAUDE.md because it actively misleads Claude.

Use Clear Section Headers

Claude parses CLAUDE.md looking for relevant context. Clear headers help it find the right information quickly. Use markdown heading levels consistently.

Include Examples

When describing patterns, show them. A code example is worth a thousand words of explanation. Claude learns patterns best through examples.

## Error Handling Pattern

All service functions should follow this pattern:

async function fetchUser(id: string): Promise<Result<User>> {
  try {
    const user = await db.users.findById(id);
    return { success: true, data: user };
  } catch (error) {
    console.error('fetchUser failed:', error);
    return { success: false, error: error.message };
  }
}

Be Specific Over General

"Write clean code" tells Claude nothing. "Use descriptive function names with verb prefixes (getUser, validateInput, formatDate)" tells Claude exactly what to do.

Common Mistakes to Avoid

Too Long and Verbose

When CLAUDE.md exceeds 1000+ lines, Claude struggles to find relevant context. It may even ignore parts of your file. Keep it concise. Link to detailed docs instead of including everything inline.

Too Vague

Instructions like "follow best practices" or "write good code" are useless. Claude doesn't share your mental model of "best practices." Be explicit about what you expect.

Not Updating It

An outdated CLAUDE.md actively harms your development. If it references deprecated patterns or wrong file structures, Claude will confidently produce incorrect code. Review and update CLAUDE.md quarterly at minimum.

Conflicting Instructions

If one section says "use default exports" and another says "prefer named exports," Claude will get confused. Review your CLAUDE.md for contradictions. When in doubt, remove conflicting instructions and be more specific.

Assuming Claude Remembers Previous Sessions

Even with CLAUDE.md, Claude doesn't remember what you discussed yesterday. Each session is fresh. Don't write instructions that reference previous conversations ("as we discussed, use the new pattern"). Make CLAUDE.md self-contained.

Advanced: Using CLAUDE.md for Multi-Agent Systems

Beyond simple configuration, CLAUDE.md can serve as the foundation for sophisticated development workflows. The Claude Architect framework takes this to the extreme, using CLAUDE.md to coordinate multiple specialist agents working on a single codebase.

In a multi-agent system, CLAUDE.md defines:

• Agent roles and responsibilities - Which agent handles iOS vs Web vs Backend
• Coordination protocols - How agents hand off work and communicate
• Shared specifications - A single source of truth for schemas and contracts
• Protected files - System files that agents cannot modify

This approach transforms Claude from a single assistant into a coordinated development team, where a Project Manager agent routes tasks to specialist agents (iOS Developer, Web Developer, Firebase Developer, etc.), each working within their domain while following the same architectural rules.

Conclusion

CLAUDE.md is the single most important file for getting consistent, high-quality results from Claude Code. It transforms Claude from a generic assistant into a team member who understands your project's specific conventions, patterns, and requirements.

Start simple. Add your tech stack, coding conventions, and file structure. As you discover more things you want Claude to remember, add them. Review and update regularly. Your CLAUDE.md should be a living document that evolves with your project.

The difference between fighting with Claude and collaborating with Claude often comes down to how well you've configured your CLAUDE.md. Take the time to get it right.