CLAUDE.md is a configuration file you place in your project that Claude Code reads at the start of every session. It’s one of the most powerful features of Claude Code — instead of re-explaining your project, your conventions, and your preferences every time you start a new chat, you write them down once and Claude Code follows them automatically.
What is CLAUDE.md?
CLAUDE.md is a plain text Markdown file that sits in the root of your project (alongside your README.md or package.json). When Claude Code starts in that directory, it reads this file first and treats its contents as standing instructions for the entire session.
Think of it as a briefing document — everything Claude Code needs to know about your project, your preferences, and how you want it to work.
Why Use CLAUDE.md?
Without CLAUDE.md, you’d need to tell Claude Code the same things at the start of every session: what the project does, how to run the tests, which files to leave alone, what coding conventions you follow. With CLAUDE.md, you write it once and never repeat yourself.
Creating Your First CLAUDE.md
Create a file called CLAUDE.md in the root of your project. The name must be uppercase. Here’s a solid starter template:
# Project Overview
[Brief description of what this project does]
# Tech Stack
- Language: Python 3.11
- Framework: FastAPI
- Database: PostgreSQL (async via SQLAlchemy)
- Testing: pytest
# How to Run
- Dev server: `uvicorn app.main:app --reload`
- Tests: `pytest tests/ -v`
- Migrations: `alembic upgrade head`
# Coding Conventions
- Use async/await throughout — no synchronous database calls
- All new functions must have docstrings
- Follow PEP 8 formatting
- Use type hints on all function signatures
# Important Files
- `app/main.py` — application entry point
- `app/models/` — SQLAlchemy models
- `app/routes/` — API route handlers
# Do Not Modify
- `migrations/` — never edit migration files directly
- `.env` — never read or expose environment variable valuesWhat to Include in CLAUDE.md
Project context
A brief description of what the project does and who uses it. This helps Claude Code make sensible decisions when it has a choice of approaches.
How to run things
The exact commands to start the dev server, run tests, apply migrations, and build the project. Claude Code uses these when it needs to verify changes.
Your coding conventions
Naming conventions, formatting rules, patterns you prefer or avoid. The more specific the better — “use camelCase for variables” is more useful than “write clean code”.
Files and folders to leave alone
Explicitly list anything Claude Code should never modify — lock files, generated code, sensitive configuration, third-party code checked into the repo.
Key architecture notes
Anything about the project structure that isn’t obvious — why certain patterns are used, which service handles what, dependencies between modules.
CLAUDE.md at Different Levels
You can have multiple CLAUDE.md files in a project:
- Root level — applies to the whole project
- Subdirectory level — applies only when Claude Code is working in that folder. Useful for monorepos where the frontend and backend have different conventions.
A global CLAUDE.md in your home directory (~/.claude/CLAUDE.md) applies to every project — good for personal preferences that don’t change between projects.
Keeping CLAUDE.md Useful
- Update it when the project changes — outdated instructions are worse than none
- Keep it focused — include what Claude Code actually needs, not documentation for human readers
- Commit it to your repo — your whole team benefits from consistent Claude Code behaviour
- Add a “current focus” section during sprints: “We are currently building the payment flow — prioritise this area”
