Using CLAUDE.md for Project Context

Every time you start a new Claude Code session, it begins with zero knowledge about your specific project. It does not know your build commands, your coding conventions, or your architecture decisions. The CLAUDE.md file solves this problem by giving Claude Code persistent, project-specific context that it reads automatically on startup.

What You Will Learn

In this lesson, you will learn:

• What CLAUDE.md is and why it matters
• Where to place CLAUDE.md files for different scopes
• What to include (and what to avoid)
• How the hierarchy of multiple CLAUDE.md files works
• Best practices for maintaining your CLAUDE.md over time

---

What Is CLAUDE.md?

CLAUDE.md is a plain markdown file that acts as a set of instructions for Claude Code. Think of it as a README specifically written for your AI coding assistant. When Claude Code starts a session in a directory, it automatically looks for CLAUDE.md files and reads them before you even type your first prompt.

This means you can tell Claude Code things like:

• "We use pnpm, not npm"
• "Our API routes are in src/server/routes/"
• "Always use single quotes in TypeScript files"
• "Run make test to execute the test suite"

Without a CLAUDE.md file, you would need to repeat this context at the beginning of every session. With one, Claude Code already knows your project intimately.

---

Where to Put CLAUDE.md

There are three levels where you can place CLAUDE.md files, each with a different scope.

1. Project-Level (Most Common)

Place a CLAUDE.md file in the root of your project repository:

my-project/
  CLAUDE.md          # <-- Project-level context
  package.json
  src/
  tests/

This is the most common placement. Claude Code reads it whenever you start a session anywhere inside this project. This is where you put build commands, architecture overviews, and team conventions.

2. User-Level (Personal Preferences)

Place a CLAUDE.md file in your home directory's .claude/ folder:

~/.claude/
  CLAUDE.md          # <-- User-level context (applies to ALL projects)

This is for personal preferences that apply across every project you work on. For example, you might specify that you prefer detailed explanations, or that you always want TypeScript over JavaScript.

3. Directory-Level (Subsystem Context)

Place CLAUDE.md files in subdirectories for context specific to that part of the codebase:

my-project/
  CLAUDE.md              # Project-wide context
  src/
    frontend/
      CLAUDE.md          # Frontend-specific context
    backend/
      CLAUDE.md          # Backend-specific context
    database/
      CLAUDE.md          # Database-specific context

When Claude Code works on a file in src/frontend/, it reads the root CLAUDE.md plus the frontend-specific one. This is useful for large monorepos or projects with distinct subsystems.

---

What to Include in CLAUDE.md

A good CLAUDE.md file covers four main areas: build commands, architecture, conventions, and testing.

Build and Development Commands

Always include the commands developers need to run your project:

## Build & Development Commands

- `npm run dev` - Start development server on port 3000
- `npm run build` - Create production build
- `npm run lint` - Run ESLint across the codebase
- `npm test` - Run the Jest test suite
- `npm run db:migrate` - Run database migrations
- `npm run db:seed` - Seed the database with test data

This prevents Claude Code from guessing your build tool or using the wrong package manager.

Architecture Overview

Describe the high-level structure so Claude Code knows where to find things:

## Architecture

This is a Next.js 15 application using the App Router.

### Directory Structure
- `src/app/` - Next.js routes and pages
- `src/components/` - Reusable React components
- `src/lib/` - Utility functions and shared logic
- `src/server/` - Server-side code (API handlers, database)
- `src/types/` - TypeScript type definitions
- `prisma/` - Database schema and migrations

### Key Patterns
- We use Server Components by default; add "use client" only when needed
- Data fetching happens in Server Components, not in client components
- All database access goes through Prisma (never raw SQL)

Coding Conventions

Spell out conventions that might not be obvious from the code alone:

## Coding Conventions

- Use named exports, not default exports
- Prefer `interface` over `type` for object shapes
- Use absolute imports with the `@/` alias (maps to `src/`)
- Error handling: always use custom error classes from `src/lib/errors.ts`
- File naming: kebab-case for files, PascalCase for components
- Never use `any` type - use `unknown` and narrow with type guards

Testing Instructions

Explain how your test suite works:

## Testing

- Unit tests are in `__tests__/` directories next to the code they test
- Integration tests are in `tests/integration/`
- Run a single test: `npm test -- --testPathPattern="users.test"`
- We use Jest with React Testing Library for component tests
- Mock external APIs using MSW (Mock Service Worker)
- Minimum coverage requirement: 80% for new code

---

Complete Example: Next.js Project

Here is a full CLAUDE.md for a typical Next.js project:

# CLAUDE.md

## Project Overview

E-commerce platform built with Next.js 15, TypeScript, and PostgreSQL.
The app serves both B2C customers and B2B wholesale clients.

## Build & Development

- `pnpm dev` - Start dev server (port 3000)
- `pnpm build` - Production build
- `pnpm lint` - ESLint + Prettier check
- `pnpm typecheck` - TypeScript compiler check
- `pnpm test` - Run Vitest unit tests
- `pnpm test:e2e` - Run Playwright E2E tests (requires dev server)
- `pnpm db:push` - Push Prisma schema to database
- `pnpm db:studio` - Open Prisma Studio GUI

## Architecture

- Next.js App Router with Server Components
- Prisma ORM with PostgreSQL
- NextAuth.js for authentication (Google + credentials providers)
- Stripe for payments
- Resend for transactional emails
- Uploadthing for file uploads
- Zustand for client-side state

### Directory Layout
- `src/app/` - Routes (grouped by feature: (shop), (dashboard), (auth))
- `src/components/ui/` - Shadcn/ui base components
- `src/components/features/` - Feature-specific components
- `src/server/` - tRPC routers and server logic
- `src/lib/` - Utilities (db client, auth config, validators)

## Conventions

- Use Shadcn/ui components from `@/components/ui/`
- Validate all inputs with Zod schemas in `src/lib/validators/`
- Use `pnpm` (not npm or yarn)
- Tailwind CSS for styling - no CSS modules or styled-components
- All prices stored as integers (cents) in the database

## Testing

- Vitest for unit tests (`*.test.ts` files)
- Playwright for E2E tests in `tests/e2e/`
- Test database uses Docker: `docker compose up test-db`

---

Complete Example: Python Project

Here is a CLAUDE.md for a Python backend project:

# CLAUDE.md

## Project Overview

REST API for a task management system built with FastAPI and SQLAlchemy.

## Setup & Commands

- `poetry install` - Install dependencies
- `poetry run uvicorn app.main:app --reload` - Start dev server (port 8000)
- `poetry run pytest` - Run test suite
- `poetry run pytest -x -v` - Run tests, stop on first failure
- `poetry run alembic upgrade head` - Run database migrations
- `poetry run alembic revision --autogenerate -m "description"` - Create migration
- `poetry run ruff check .` - Lint the codebase
- `poetry run ruff format .` - Format code
- `poetry run mypy app/` - Type check

## Architecture

- FastAPI with async endpoints
- SQLAlchemy 2.0 with async session
- Alembic for migrations
- PostgreSQL database
- Redis for caching and background job queue
- Celery for background tasks

### Directory Layout
- `app/main.py` - FastAPI app initialization
- `app/api/` - Route handlers organized by resource
- `app/models/` - SQLAlchemy models
- `app/schemas/` - Pydantic request/response schemas
- `app/services/` - Business logic layer
- `app/core/` - Config, security, dependencies
- `tests/` - Pytest tests mirroring app structure

## Conventions

- Use `poetry` for dependency management (not pip directly)
- Type hints on all function signatures
- Pydantic models for all API input/output
- Business logic belongs in `services/`, not in route handlers
- Use dependency injection via FastAPI's `Depends()`
- Environment variables loaded through `app/core/config.py`

## Testing

- Use `pytest` with `pytest-asyncio` for async tests
- Fixtures in `tests/conftest.py` provide test database and client
- Factory functions in `tests/factories.py` for creating test data
- Run single file: `poetry run pytest tests/api/test_tasks.py`

---

How the CLAUDE.md Hierarchy Works

When multiple CLAUDE.md files exist, Claude Code combines them in a specific order:

1. User-level (~/.claude/CLAUDE.md) is read first -- this sets your personal baseline
2. Project-level (repository root CLAUDE.md) is read next -- this adds project-specific context
3. Directory-level (nested CLAUDE.md files) are read last -- these add subsystem-specific details

The files are additive. Information from all levels is combined, with more specific files taking precedence when there is a conflict. For example, if your user-level CLAUDE.md says "use 2-space indentation" but the project-level one says "use 4-space indentation," the project-level instruction wins.

# Example hierarchy in practice:

~/.claude/CLAUDE.md
# "I prefer concise explanations. Use TypeScript when possible."

~/projects/my-app/CLAUDE.md
# "This is a React app. Use pnpm. Run tests with pnpm test."

~/projects/my-app/packages/api/CLAUDE.md
# "This package is a Fastify server. Routes are in src/routes/."

When Claude Code is working on a file in packages/api/, it has context from all three levels.

---

Anti-Patterns: What NOT to Put in CLAUDE.md

Avoid these common mistakes:

Do Not Paste Your Entire Codebase

CLAUDE.md should be a high-level guide, not a code dump. Claude Code can already read your files directly.

<!-- BAD: Don't do this -->
## API Routes
Here is the complete code for every route handler...
(500 lines of code follow)

<!-- GOOD: Do this instead -->
## API Routes
Route handlers are in `src/api/routes/`. Each file exports
a Fastify plugin. See `src/api/routes/users.ts` for a typical example.

Do Not Duplicate What the Code Already Says

If your package.json clearly shows your dependencies, you do not need to list every package in CLAUDE.md. Focus on things that are not obvious from reading the code.

Do Not Write a Novel

Keep CLAUDE.md concise and scannable. Use bullet points, short sections, and headers. If your CLAUDE.md is longer than 200-300 lines, consider splitting into directory-level files.

Do Not Include Sensitive Information

CLAUDE.md is typically committed to your repository. Never put API keys, passwords, or secrets in it.

<!-- BAD -->
## Database
Connection string: postgresql://admin:secret123@prod-db.example.com/myapp

<!-- GOOD -->
## Database
Connection string is in the DATABASE_URL environment variable. See .env.example.

---

How Claude Code Reads CLAUDE.md on Startup

When you launch Claude Code in a project directory, the following happens automatically:

1. Claude Code checks for ~/.claude/CLAUDE.md and reads it if present
2. Claude Code walks up from the current directory to find the nearest git repository root and reads any CLAUDE.md there
3. Claude Code checks the current working directory (and relevant subdirectories) for additional CLAUDE.md files
4. All discovered content is loaded into Claude Code's context before your first prompt

You do not need to reference the file or ask Claude Code to read it. It happens transparently. You can verify this by asking Claude Code:

> What do you know about this project?

Claude Code should be able to answer based on your CLAUDE.md content without you pointing it to any specific file.

---

Tips for Maintaining CLAUDE.md

Your CLAUDE.md should evolve with your project. Here are practical tips:

Use the /init Command

If you are starting from scratch, Claude Code can generate an initial CLAUDE.md for you:

claude
> /init

This analyzes your project and creates a starter CLAUDE.md that you can then customize.

Update After Major Changes

When you make significant changes to your project (new framework, restructured directories, changed build tool), update your CLAUDE.md accordingly. A stale CLAUDE.md is worse than no CLAUDE.md because it gives Claude Code incorrect context.

Review Periodically

Set a reminder to review your CLAUDE.md every month or at the start of each sprint. Ask yourself:

• Are the build commands still accurate?
• Has the directory structure changed?
• Are there new conventions the team has adopted?
• Is anything in CLAUDE.md no longer true?

Let the Team Contribute

Since CLAUDE.md is committed to the repository, treat it like any other code file. Team members can submit pull requests to improve it. Include it in code review when project structure changes.

Keep It Focused

A CLAUDE.md file works best when it tells Claude Code things it cannot easily figure out on its own. The three highest-value categories are:

1. How to run things (build, test, deploy commands)
2. Where things are (directory structure, key files)
3. How you want things done (conventions, patterns, preferences)

---

Hands-On Exercise

Create a CLAUDE.md file for one of your own projects. Start with this template:

# CLAUDE.md

## Project Overview
(One or two sentences describing what this project does)

## Commands
(List your build, test, lint, and other key commands)

## Architecture
(Describe directory structure and key technologies)

## Conventions
(List coding standards and patterns your team follows)

## Testing
(Explain how to run tests and any testing conventions)

Fill in each section, then start a Claude Code session in your project and ask it to describe your project. See how much it already knows from your CLAUDE.md alone.

---

Summary

The CLAUDE.md file is one of the most powerful features in Claude Code because it eliminates the need to repeatedly explain your project. By placing clear, concise instructions in a CLAUDE.md file at the root of your repository, you give Claude Code the context it needs to be immediately productive. Use the three-level hierarchy (user, project, directory) to organize context at the right scope, keep the file up to date, and avoid anti-patterns like pasting entire codebases or including sensitive data.

In the next lesson, we will explore slash commands -- both the built-in ones that Claude Code provides and the custom ones you can create for your own workflows.