CLAUDE.md as Your Project Brain

Why CLAUDE.md is the most important file in your project

CLAUDE.md is a file that Claude Code reads automatically at the start of every conversation. It's your way of telling the AI: 'This is how this project works, these are the rules, this is how we do things here.' Without it, Claude Code works blind — guessing conventions, unaware of your architecture, and repeatedly asking things you could tell it once.

A good CLAUDE.md dramatically changes output quality. A bad CLAUDE.md is worse than none at all — it floods the context with irrelevant information and wastes tokens. In this lesson, you'll learn to design a CLAUDE.md that actually works.

Three layers of configuration

Claude Code has a three-layer configuration system. Each layer has a different scope and purpose. Understanding this system is crucial — most people use only one layer and miss 80% of the potential.

1. Global CLAUDE.md (~/.claude/CLAUDE.md)

A file in your home directory. Applies to ALL projects you work on. This is where your personal preferences go — formatting rules, preferred language, tools you use, your coding style. Don't change it per-project — that's an anti-pattern.

# ~/.claude/CLAUDE.md

## Preferences
- Write code in English, comments in English
- Prefer functional approaches over OOP where it makes sense
- Always use type hints in Python
- Commit with Conventional Commits format

## Tools
- Package manager: uv (never pip)
- Formatter: ruff
- Test runner: pytest

## Communication
- Be concise, don't apologize
- When unsure, just do it and show me the result

2. Project CLAUDE.md (./CLAUDE.md)

A file at the project root. Committed to git — shared with your entire team. Contains project-specific information: architecture, conventions, API endpoints, deployment process. This is by far the most important layer.

# MyApp Backend

Django + Django Ninja REST API.

## Quick Start
    docker compose up -d db
    uv run python manage.py migrate
    uv run python manage.py runserver 0.0.0.0:8000
    uv run pytest
    uv run ruff check .

## App Structure
    app_name/
      models.py
      api/
        routers.py         # Django Ninja Router
        endpoint_name.py   # One file per endpoint group
        schemas.py         # Pydantic schemas
      tests/
        test_*.py

## Testing Rules
- ALL tests MUST hit a real Postgres database
- NO mocking of models, ORM queries, or database operations
- Mocking is ONLY allowed for 3rd party HTTP API calls

## Architecture Notes
- Global ObjectDoesNotExist handler — no try/except in endpoints
- Two NinjaAPI instances — public + internal with API key auth
- Trailing slash enforcement via APPEND_SLASH=True

3. User project CLAUDE.md

A file at ~/.claude/projects/<path-to-project>/CLAUDE.md. This is your personal configuration for a specific project — not committed, invisible to colleagues. Perfect for local development setup, your notes, or instructions you don't want to share with the team.

# ~/.claude/projects/-Users-john-myapp/CLAUDE.md

## My local setup
- Dev server runs on port 8008 (not default 8000)
- I use branch naming: john/<ticket-id>-<description>

## Current context
- Working on payment system refactor
- Comgate API credentials are in .env.local

What belongs in CLAUDE.md

• Quick start commands — how to run the project, how to run tests
• Directory structure — where things live, how files are organized
• Conventions — naming, formatting, patterns the project uses
• Testing rules — what to mock, what not to, how to write tests
• Architectural decisions — why the code is organized the way it is
• API overview — endpoints, auth, key flows
• Deployment process — how to deploy, what environments exist

What does NOT belong in CLAUDE.md

• Entire source code — Claude Code reads it on its own when needed
• Detailed API docs — generate those from code (OpenAPI)
• Change history — that's what git log is for
• TODO lists — those belong in your issue tracker
• Sensitive data — passwords, API keys, tokens

How Claude Code reads CLAUDE.md

Claude Code reads CLAUDE.md files automatically at the start of every conversation. The order is: global, then project, then user project. All three are concatenated into the system prompt. This means later files can override instructions from earlier ones — the project CLAUDE.md can override global preferences.

The @import directive

CLAUDE.md supports an @file directive that inlines the contents of another file. This is extremely useful for organization — instead of one massive file, you get a modular structure.

# ~/.claude/CLAUDE.md

@RTK.md
@coding-style.md

## Memory maintenance
When you change project infrastructure, update the memory files.

The imported file is inlined at the directive location. You can have separate files for different areas — tools, coding style, workflow rules — and import them from the main CLAUDE.md.

Real example: production CLAUDE.md

The following example is a simplified version of a real CLAUDE.md from a production Django project. Notice the structure — it starts with what matters most (how to run the project) and progresses to details.

# PraktickAI Backend

Django + Django Ninja REST API for auth, courses, payments.

## Quick Start
    docker compose up -d db
    uv run python manage.py migrate
    uv run python manage.py runserver 0.0.0.0:8008
    uv run pytest
    uv run ruff check .
    uv run mypy .

## Testing Rules
- ALL tests MUST hit a real Postgres database
- NO mocking of models or ORM queries — ever
- Mocking ONLY for 3rd party HTTP APIs (Comgate via respx)
- Every endpoint: success, validation errors, auth errors, edge cases

## Content System (i18n)
Content lives in files, not the database.
```
content/courses/ai-start/
  _course.json          # Shared: slug, difficulty, price
  cs/_meta.json          # Czech: title, description
  cs/01-lesson.json      # Czech lesson content
  en/_meta.json          # English metadata
  en/01-lesson.json      # English lesson content
```

## Key Patterns
- Global ObjectDoesNotExist handler — no try/except boilerplate
- Two NinjaAPI instances — public (JWT) + internal (API key)
- Trailing slash enforcement — APPEND_SLASH=True
- Non-root Docker — app user, gunicorn with access logs

Anti-patterns: what not to do

• Overly long CLAUDE.md (500+ lines) — wastes tokens, important info gets lost in noise
• Duplicating code — don't paste entire files, Claude Code reads them on its own
• Vague instructions ('write good code') — be specific ('use select_related for ForeignKey')
• Outdated information — CLAUDE.md must be current, stale instructions lead to wrong decisions
• Instructions you never use — if Claude Code doesn't ask about it, it doesn't need to know