CLAUDE.md Files

How CLAUDE.md Works (Visual)

What is CLAUDE.md?

CLAUDE.md is a Markdown file that lives in your project repository. When you start a Claude Code session, Claude automatically reads it and treats its contents as persistent instructions. Every conversation begins with Claude already knowing what you wrote in that file.

This is different from a regular README. A README is for humans browsing your repo. CLAUDE.md is for Claude — it's optimized for things an AI coding assistant needs to know: where code lives, what commands to run, which patterns to follow, and which mistakes to avoid.

File Hierarchy

Claude doesn't just read one CLAUDE.md. There's actually a hierarchy of files, and they merge together to form the final set of instructions Claude sees.

1. Project root — /CLAUDE.md

This is the main one. It lives in the root of your project, right next to your package.json or pyproject.toml. It covers project-wide rules that apply everywhere in the codebase. This file should be committed to version control so the whole team shares the same instructions.

2. User-level — ~/.claude/CLAUDE.md

This is your personal instruction file. It applies to every project you work on with Claude Code. Use it for personal preferences that don't belong in a shared repo — like your preferred commit message style or your editor quirks.

3. Nested directories — subdirectory/CLAUDE.md

You can place a CLAUDE.md in any subdirectory. When Claude is working on files in that directory, it picks up the local CLAUDE.md too. Great for monorepos where different packages have different conventions.

# File hierarchy example
~/.claude/CLAUDE.md           # User-level (personal prefs)
my-project/
  CLAUDE.md                   # Project root (shared team rules)
  packages/
    api/
      CLAUDE.md               # Nested (API-specific conventions)
    frontend/
      CLAUDE.md               # Nested (frontend-specific conventions)

What to Put in CLAUDE.md

The best CLAUDE.md files are concise and actionable. Here's what works well:

Project overview

A 2-3 sentence description of what the project is, what stack it uses, and how it's deployed. Claude uses this to make better decisions about file structure and tooling.

Architecture notes

Where code lives, how the project is organized, and what the key directories are. Think of this as the map Claude consults when it needs to find or create files.

Key commands

How to run the dev server, how to run tests, how to build, how to deploy. Claude will use these when you ask it to "run the tests" or "start the server."

Code style and conventions

Naming conventions, formatting rules, import ordering, preferred patterns. This prevents Claude from writing code that "works but looks wrong" to your team.

Important rules

Hard constraints that Claude must never violate. Things like "never delete migration files" or "always use the logger, never console.log." Mark these clearly.

Naming conventions

File naming patterns, variable naming styles (camelCase vs snake_case), component naming rules, database column conventions.

What NOT to Put in CLAUDE.md

• Secrets and credentials — Never put API keys, passwords, or tokens in CLAUDE.md. It's a committed file. Use environment variables instead.
• Large file contents — Don't paste entire config files. Reference them by path instead: "See tsconfig.json for TypeScript settings."
• Things derivable from code — Claude can read your code. Don't explain what every function does — it can figure that out. Focus on why decisions were made, not what the code does.
• Frequently changing info — Don't put sprint goals or current ticket numbers. CLAUDE.md should be relatively stable.
• Duplicate README content — If your README already explains the project structure, just point Claude to it rather than copying the text.

Example CLAUDE.md

Here's a realistic CLAUDE.md for a Python/FastAPI project. Notice how each section is short, specific, and actionable.

# My API Project

## Project Overview
FastAPI REST API for user management. Python 3.12, PostgreSQL,
deployed on Railway via Docker. Monorepo with frontend in /web.

## Architecture
- `app/` — FastAPI application code
  - `app/routers/` — API route handlers (one file per resource)
  - `app/models/` — SQLAlchemy ORM models
  - `app/schemas/` — Pydantic request/response schemas
  - `app/services/` — Business logic (routers call services, never DB directly)
- `tests/` — Pytest tests (mirror the app/ structure)
- `alembic/` — Database migrations

## Key Commands
- Dev server: `uvicorn app.main:app --reload`
- Tests: `pytest -x --tb=short`
- New migration: `alembic revision --autogenerate -m "description"`
- Apply migrations: `alembic upgrade head`
- Lint: `ruff check . --fix`
- Format: `ruff format .`

## Code Style
- Use snake_case for everything (files, functions, variables)
- Type hints on ALL function signatures — no exceptions
- Pydantic models for all request/response bodies
- Services return domain objects, routers convert to responses
- Keep routers thin — business logic goes in services/

## Important Rules
- NEVER delete or modify existing Alembic migration files
- NEVER use `print()` — use `structlog.get_logger()` instead
- NEVER commit .env files or hardcode secrets
- All database queries go through the service layer
- Every new endpoint needs a test in tests/

Best Practices

Keep it concise

Aim for under 200 lines. Every line consumes tokens in Claude's context window. If your CLAUDE.md is longer than your README, something's wrong. Trim ruthlessly.

Update it regularly

When your team adopts a new convention or changes a command, update CLAUDE.md the same day. Stale instructions are worse than no instructions — they actively mislead Claude.

Version control it

Commit CLAUDE.md to your repo. It's part of your project's developer experience, just like your linter config or your Makefile. Review changes in PRs so the team agrees on what Claude should know.

Don't duplicate your README

Your README explains the project to humans. CLAUDE.md gives Claude working instructions. There's overlap, but they serve different audiences. If Claude needs to know something that's already in the README, just reference the README path.

Use clear formatting

Headings, bullet points, code blocks. Claude parses Markdown natively, so well-structured CLAUDE.md files are easier for it to follow. Avoid long prose paragraphs.