Как написать CLAUDE.md — инструкции для Claude Code

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

Что такое CLAUDE.md и где он лежит

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

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

Быстрый старт — команда /init в сессии: Claude Code изучит репозиторий и предложит черновик CLAUDE.md. Редактировать файлы удобно через /memory, а проверить, что именно загрузилось, — через /context (раздел Memory files).

Что писать в CLAUDE.md

Пишите то, что иначе пришлось бы объяснять агенту заново: команды сборки, соглашения, устройство проекта, правила «всегда делай X». Хороший сигнал добавить строку — агент второй раз совершает одну и ту же ошибку.

Инструкции должны быть проверяемыми: «отступ 2 пробела» вместо «форматируй аккуратно», «запускай npm test перед коммитом» вместо «тестируй изменения».

Стек и команды

## Tech Stack
- Python 3.11, FastAPI, PostgreSQL
- Package manager: poetry

## Build & Test
- Install: `poetry install`
- Run: `poetry run uvicorn src.main:app --reload`
- Test: `poetry run pytest tests/` — must pass before commit
- Lint: `ruff check src/ && mypy src/`

Стиль и структура

## Code Style
- Type hints required for all functions
- Google-style docstrings for public APIs
- Max line length: 100

## Project Structure
- `src/api/routes/` — HTTP handlers
- `src/models/` — SQLAlchemy models
- `migrations/` — Alembic migrations

Запреты и важный контекст

## Rules
- Never edit existing migrations, only add new ones
- Never commit `.env` or credentials
- Multi-tenant app: every query must filter by tenant_id
- DB access is async: use `async_session()`

Учтите: CLAUDE.md — это контекст, а не жёсткие настройки. Если действие нужно запретить гарантированно, в Claude Code для этого есть правила разрешений и хуки.

Чего не писать

• Секреты. Никаких ключей, паролей и токенов: проектный CLAUDE.md лежит в git, а его текст отправляется модели при каждом запросе.
• Всю вики проекта. Не копируйте документацию целиком. Укажите путь: «архитектура описана в docs/ARCHITECTURE.md» — агент прочитает файл, когда он понадобится.
• Длинные примеры кода. Одна-две строки как образец, а не целые скрипты.
• Историю проекта. Кто и когда начинал проект, агенту для работы не нужно.
• Противоречия. Если два правила спорят, агент может выбрать любое. Периодически вычищайте устаревшее.

Отдельно про импорты: строка вида @docs/guide.md в CLAUDE.md подключает файл целиком при запуске. Это удобно для организации, но контекст не экономит. Если файл нужен изредка, упоминайте его путь в обратных кавычках без @. Для правил, которые касаются только части кода, в документации Claude Code описана папка .claude/rules/ с привязкой к путям — такие правила подгружаются, только когда агент работает с подходящими файлами. А HTML-комментарии <!-- ... --> вырезаются до отправки модели, ими можно оставлять заметки для людей.

Почему короткий файл дешевле

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

Пример на ценах Zukko для claude-sonnet-5 ($0,30 за 1M входных токенов), 100 обращений к модели в день:

Разница — около $4 в месяц только на этом файле. У официального API Anthropic повторяющийся контекст частично оплачивается по цене чтения из кэша (около 10% входной цены), а в Zukko кэшированные токены стоят как обычные входные. Поэтому при работе через Zukko размер CLAUDE.md сильнее влияет на счёт, и лаконичность окупается напрямую.

Шаблон для начала

## Project: MyApp
FastAPI backend for an internal CRM.

## Tech Stack
- Python 3.11, FastAPI, PostgreSQL 14, poetry

## Commands
- Install: `poetry install`
- Run: `poetry run uvicorn src.main:app --reload`
- Test: `poetry run pytest` — must pass before commit
- Lint: `ruff check . && mypy src/`

## Code Style
- Type hints required, Google-style docstrings, line length 100

Этого достаточно, чтобы агент перестал гадать о командах и правилах.

Как подключить Claude Code к Zukko

Claude Code работает через Zukko с теми же CLAUDE.md. Достаточно двух переменных в ~/.claude/settings.json в блоке env: ANTHROPIC_BASE_URL = https://api.zukko.pro (без /v1) и ANTHROPIC_AUTH_TOKEN = ваш ключ fetch_.... Ключ создаётся на странице API-ключей↗, полная настройка — в инструкции по Claude Code↗.

Частые вопросы

Нужен ли CLAUDE.md, если есть README?

Да, у них разные задачи. README объясняет проект людям, CLAUDE.md даёт агенту короткие правила работы: команды, запреты, соглашения. Можно сослаться на README из CLAUDE.md, но не копировать его.

Кто видит CLAUDE.md?

Проектный CLAUDE.md — обычный файл в репозитории: его видят все, у кого есть доступ к коду, и он отправляется модели как часть контекста. Личные заметки по проекту храните в CLAUDE.local.md и добавьте его в .gitignore.

Можно ли ссылаться на внешние страницы?

Можно, но агенту придётся отдельно загрузить страницу (если вы это разрешите), а это лишний шаг и лишние токены. Надёжнее положить нужную выжимку в локальный файл и указать путь к нему.

Работает ли CLAUDE.md в расширении VS Code?

Да. Расширение использует тот же Claude Code, поэтому CLAUDE.md, ~/.claude/CLAUDE.md и CLAUDE.local.md загружаются так же, как в терминале.