CLAUDE.md как мозг вашего проекта

Почему CLAUDE.md — самый важный файл в вашем проекте

CLAUDE.md — это файл, который Claude Code автоматически читает в начале каждого разговора. Это ваш способ сказать AI: «Вот как работает этот проект, вот правила, вот как мы здесь делаем вещи». Без него Claude Code работает вслепую — угадывает соглашения, не знает вашей архитектуры и раз за разом спрашивает о том, что можно было сказать один раз.

Хороший CLAUDE.md кардинально меняет качество результата. Плохой CLAUDE.md хуже, чем его отсутствие — он засоряет контекст нерелевантной информацией и тратит токены. В этом уроке вы научитесь проектировать CLAUDE.md, который реально работает.

Три уровня конфигурации

Claude Code имеет трёхуровневую систему конфигурации. Каждый уровень имеет свой охват и назначение. Понимание этой системы критически важно — большинство людей используют только один уровень и упускают 80% потенциала.

1. Глобальный CLAUDE.md (~/.claude/CLAUDE.md)

Файл в домашней директории. Применяется ко ВСЕМ проектам, над которыми вы работаете. Здесь хранятся ваши личные предпочтения — правила форматирования, предпочитаемый язык, используемые инструменты, ваш стиль кодирования. Не меняйте его от проекта к проекту — это антипаттерн.

# ~/.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. Проектный CLAUDE.md (./CLAUDE.md)

Файл в корне проекта. Коммитится в git — общий для всей команды. Содержит специфичную для проекта информацию: архитектуру, соглашения, API-эндпоинты, процесс деплоя. Это, безусловно, самый важный уровень.

# 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. Пользовательский проектный CLAUDE.md

Файл по пути ~/.claude/projects/<путь-к-проекту>/CLAUDE.md. Это ваша личная конфигурация для конкретного проекта — не коммитится, невидима для коллег. Идеально подходит для настройки локальной разработки, ваших заметок или инструкций, которыми вы не хотите делиться с командой.

# ~/.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

Что должно быть в CLAUDE.md

• Команды для запуска — как запустить проект, как запустить тесты
• Структура директорий — где что лежит, как организованы файлы
• Соглашения — именование, форматирование, паттерны, которые использует проект
• Правила тестирования — что мокать, что не мокать, как писать тесты
• Архитектурные решения — почему код организован именно так
• Обзор API — эндпоинты, авторизация, ключевые потоки
• Процесс деплоя — как деплоить, какие окружения существуют

Что НЕ должно быть в CLAUDE.md

• Весь исходный код — Claude Code читает его самостоятельно при необходимости
• Подробная документация API — генерируйте её из кода (OpenAPI)
• История изменений — для этого есть git log
• Списки задач — они относятся к вашему трекеру задач
• Чувствительные данные — пароли, API-ключи, токены

Как Claude Code читает CLAUDE.md

Claude Code автоматически читает файлы CLAUDE.md в начале каждого разговора. Порядок: глобальный, затем проектный, затем пользовательский проектный. Все три конкатенируются в системный промпт. Это означает, что более поздние файлы могут переопределять инструкции из более ранних — проектный CLAUDE.md может переопределить глобальные предпочтения.

Директива @import

CLAUDE.md поддерживает директиву @file, которая встраивает содержимое другого файла. Это крайне удобно для организации — вместо одного огромного файла вы получаете модульную структуру.

# ~/.claude/CLAUDE.md

@RTK.md
@coding-style.md

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

Импортируемый файл встраивается в месте расположения директивы. Можно держать отдельные файлы для разных областей — инструменты, стиль кода, правила рабочего процесса — и импортировать их из главного CLAUDE.md.

Реальный пример: production CLAUDE.md

Следующий пример — упрощённая версия реального CLAUDE.md из production-проекта на Django. Обратите внимание на структуру — он начинается с того, что важнее всего (как запустить проект), и постепенно переходит к деталям.

# 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

Антипаттерны: чего не делать

• Слишком длинный CLAUDE.md (500+ строк) — тратит токены, важная информация теряется в шуме
• Дублирование кода — не вставляйте целые файлы, Claude Code читает их самостоятельно
• Расплывчатые инструкции («пиши хороший код») — будьте конкретны («используй select_related для ForeignKey»)
• Устаревшая информация — CLAUDE.md должен быть актуальным, устаревшие инструкции приводят к неверным решениям
• Инструкции, которые вы никогда не используете — если Claude Code об этом не спрашивает, ему не нужно это знать