Claude Code чаще ошибается там, где проект никак не описан: файлов много, команды проверки не названы, опасные зоны не отмечены, а ожидаемый формат результата остаётся в голове у разработчика.
CLAUDE.md включает свет. В этом файле вы коротко объясняете проект: как его запускать, какие команды считать обязательными, где нельзя трогать без спроса и по каким правилам писать код. Тогда Claude Code меньше гадает и чаще доводит задачу до проверяемого diff.
Если вы уже читали, как установить Claude Code и как использовать Claude Code, эта статья закрывает следующий слой: проектную память. Не общий обзор инструмента, а конкретный файл, который лежит в репозитории и помогает агенту работать как участнику проекта, а не как случайному гостю.
Что такое CLAUDE.md и зачем он нужен проекту?
CLAUDE.md — это файл с инструкциями для Claude Code внутри конкретного проекта. Обычно он лежит в корне репозитория и описывает контекст, который агент должен учитывать при работе с кодом.
Важно: CLAUDE.md не гарантирует безошибочную работу. Файл снижает количество лишних вопросов, догадок и случайных правок, но за безопасность всё равно отвечают права доступа, review, тесты, CI и человек, который смотрит итоговый diff.
Не кладите в CLAUDE.md секреты: токены, пароли, приватные ключи, production DSN, доступы к облакам и внутренним админкам. Агенту нужны правила работы, а не ключи от квартиры.
Хороший CLAUDE.md помогает в задачах, где Claude Code проходит несколько файлов подряд: чинит баг, добавляет тесты, переносит логику, меняет API, готовит миграцию, обновляет документацию. Для серьёзных многофайловых задач это полезнее, чем каждый раз вручную объяснять: «тесты запускаются вот так, generated не трогай, миграции только через этот скрипт».
Что обязательно положить в CLAUDE.md?
Начните с одной страницы. Не пытайтесь превратить файл в устав компании. Агенту нужна рабочая карта проекта: стек, команды, границы, стиль, проверки. Всё остальное можно добавить позже, когда вы увидите повторяющиеся ошибки.
| Раздел | Что написать | Пример |
|---|---|---|
| Контекст проекта | Что делает продукт и какие части репозитория главные | Next.js приложение, API в /app/api, платежи через Stripe, админка в /admin |
| Команды | Как поставить зависимости, запустить dev, тесты, lint, build, форматирование | pnpm install, pnpm dev, pnpm test, pnpm lint, pnpm build |
| Архитектура | Где лежит бизнес-логика, что нельзя смешивать, какие паттерны приняты | Не писать SQL в компонентах; логику заказов держать в src/domain/orders |
| Границы изменений | Что Claude может менять сам, а где нужен approval | Можно править tests и src/ui; миграции, auth и billing только после подтверждения |
| Проверка результата | Что агент обязан запустить перед финалом | После изменений: pnpm lint && pnpm test; для UI описать ручной сценарий проверки |
Команды запуска, проверки и сборки
Команды надо писать буквально. Не «запусти тесты», а конкретно: pnpm test, pytest -q, npm run lint, docker compose up -d, alembic upgrade head. Claude Code работает лучше, когда может выполнить команду и увидеть реальный вывод терминала.
- Установка зависимостей: npm install, pnpm install, uv sync, composer install.
- Локальный запуск: npm run dev, pnpm dev, docker compose up app db.
- Проверки: npm test, pnpm lint, pnpm typecheck, pytest -q, ruff check .
- Сборка: npm run build, pnpm build, go test ./..., cargo test.
- Форматирование: prettier, black, ruff format, gofmt.
- Миграции: prisma migrate dev, alembic revision, rails db:migrate.
- Generated-файлы: какие можно пересоздавать, а какие нельзя править руками.
Отдельно напишите, какие команды дорогие или опасные. Например: не запускать e2e без спроса, потому что они занимают 40 минут; не выполнять миграции на production; не трогать Docker volume с локальной базой.
Архитектурные правила и зоны, где нужен approval
Claude Code умеет уверенно менять много файлов. Это и сила, и риск. В CLAUDE.md надо заранее описать, какие изменения нормальны без вопроса, а какие требуют подтверждения человека.
- Можно без approval: тесты, документация, небольшие UI-правки, рефакторинг внутри одного модуля, исправление очевидной типовой ошибки.
- Нужен approval: зависимости, миграции базы, auth, платежи, роли пользователей, CI/CD, деплой, удаление файлов, массовые переименования.
- Запрещено: коммитить секреты, отключать тесты ради зелёного статуса, менять публичный API без задачи, удалять данные или запускать production-команды.
Формулируйте это жёстко и коротко. Не «будь осторожен с безопасностью», а «не меняй auth/session middleware без approval». Общая просьба звучит вежливо, но в репозитории лучше работают рельсы.
Стиль кода, формат PR и ожидания по проверке
Если в проекте есть стиль, не заставляйте Claude угадывать. Напишите, где держать типы, как называть компоненты, как оформлять ошибки, когда писать unit-тесты, какой формат финального ответа вы ждёте.
Например: «в конце ответа покажи изменённые файлы, команды проверки и риски». Это простая строка, но она дисциплинирует агента. Он не просто пишет «готово», а возвращает следы работы: что поменял, чем проверил, где может болеть.
Пример CLAUDE.md для небольшого проекта
Ниже шаблон, с которого можно начать. Не копируйте его вслепую. Замените команды, папки и ограничения на свои.
# CLAUDE.md
## Обзор проекта
Это приложение на Next.js с небольшим API-слоем и базой данных PostgreSQL.
Основной код продукта лежит в `src/`. API-роуты — в `app/api/`.
Бизнес-логика должна оставаться в `src/domain/`, а не внутри React-компонентов.
## Установка и команды
- Установить зависимости: `pnpm install`
- Запустить дев-сервер: `pnpm dev`
- Прогнать тесты: `pnpm test`
- Линт: `pnpm lint`
- Проверка типов: `pnpm typecheck`
- Сборка: `pnpm build`
- Форматирование: `pnpm format`
## Правила архитектуры
- UI-компоненты держим в `src/components/`.
- Доменную логику держим в `src/domain/`.
- Не обращаемся к базе данных напрямую из React-компонентов.
- Не редактируем сгенерированные файлы в `src/generated/`; меняем исходную схему и регенерируем.
- Предпочитаем небольшие изменения с тестами вместо масштабных переписываний.
## Безопасность и подтверждение
Claude может менять тесты, документацию, UI-компоненты и изолированные доменные модули без вопросов.
Спрашивай подтверждение перед изменением:
- миграций базы данных
- логики аутентификации и сессий
- кода биллинга и платежей
- конфигурации CI/CD
- зависимостей в `package.json`
- публичных контрактов API
Никогда не коммить секреты, токены, приватные ключи или продакшен-доступы.
Никогда не отключай тесты или правила линтера только ради прохождения проверок.
## Ожидания по тестам
Для исправления багов добавляй или обновляй тест, воспроизводящий проблему, когда это уместно.
Перед завершением выполни:
1. `pnpm lint`
2. `pnpm test`
3. `pnpm typecheck`
Если команда падает — сообщи точную ошибку и объясни, что ты менял до этого.
Если не можешь выполнить команду — объясни почему.
## Формат ответа
В конце задачи кратко перечисли:
- какие файлы изменены
- какие проверки запускались и их результат
- риски или ручные проверки, которые ещё нужныТакой файл не пытается заменить документацию. Он даёт Claude Code минимум, без которого агент обычно начинает фантазировать: где лежит логика, какие команды запускать, какие зоны опасны и как отчитываться.
Какие ошибки чаще всего ломают работу Claude Code?
Первая ошибка — писать слишком общо. Фраза «следуй best practices» почти ничего не даёт. Best practices у React, Django, стартапа на пятом месяце и enterprise-монолита будут разными. Лучше написать: «новые API endpoints добавляй в app/api/v1, валидацию делай через zod, ошибки возвращай в формате { error: string }».
Вторая ошибка — делать из CLAUDE.md мусорный ящик. Туда складывают всю историю проекта, спорные решения, устаревшие команды, ссылки на несуществующие сервисы. Через месяц агент читает это как карту, а там половина улиц уже снесена.
Третья ошибка — не указывать проверку. Если в файле нет тестов, линта и сборки, Claude Code будет считать задачу завершённой после изменения файлов. Для серьёзной разработки этого мало. Нужен цикл: изменить, запустить, увидеть ошибку, исправить, снова запустить.
Четвёртая ошибка — класть секреты. Это надо повторить отдельно, потому что соблазн есть: «пусть агент сам подключится к API». Не надо. Для локальной работы используйте .env.example, переменные окружения, тестовые ключи и отдельные инструкции без реальных доступов.
Пятая ошибка — давать агенту слишком широкие права без правил. Если Claude может сам менять миграции, auth, зависимости и CI, маленькая задача может разрастись в опасный набор изменений без понятной причины.
Как поддерживать CLAUDE.md в живом проекте?
CLAUDE.md стареет быстрее, чем README. README читают люди и иногда прощают неточности. Claude Code будет исполнять старую инструкцию буквально: запускать не ту команду, искать код в старой папке, править файл, который больше не является источником правды.
Обновляйте файл не по календарю, а по повторяющимся сбоям. Если агент второй раз тронул generated-файл, добавьте правило про generated. Если снова забыл запустить typecheck, добавьте typecheck в обязательный финальный список. Если постоянно лезет в auth, вынесите auth в зону approval.
- После каждого заметного сбоя спросите: какую одну строку надо добавить, чтобы это не повторилось?
- Раз в 2–4 недели удаляйте устаревшие команды и правила, которые больше не работают.
- Держите файл коротким. Если правило нужно редко, лучше дать его в задаче, а не навсегда прописывать в проектную память.
- Когда меняется стек, структура папок или тестовый runner, обновляйте CLAUDE.md в том же PR.
Рабочий принцип простой: CLAUDE.md должен помогать агенту действовать, а не заставлять его читать внутренний роман проекта. Одна страница точных правил обычно сильнее, чем десять страниц благих пожеланий.
Больше практики — в Telegram
В Telegram-канале Тимура разбираем, как использовать Claude Code, Codex, Cursor и другие AI-инструменты без цирка с «нейросеть всё сделает сама». Практика, команды, ошибки, рабочие связки:
ПодписатьсяКогда одного CLAUDE.md уже мало?
CLAUDE.md закрывает проектный контекст, но не заменяет процесс разработки. Если в команде несколько агентов, сложный monorepo, разные зоны ответственности и строгий review, одного файла мало. Нужны issue-шаблоны, CI, тестовые стенды, правила PR, документация по архитектуре и понятная система approvals.
Для визуального review можно оставить Cursor или Windsurf: удобно смотреть diff, компоненты, навигацию по файлам. Для агентных терминальных циклов и многофайловых задач сильнее подходит Claude Code: он читает проект, меняет файлы, запускает команды и возвращается к ошибкам. В статье про ИИ для программирования этот выбор разобран шире.
AGENTS.md можно рассматривать как соседнюю тему: похожая идея проектных инструкций для агентных инструментов, но с другими соглашениями и сценариями. В этой статье фокус именно на CLAUDE.md для Claude Code, чтобы не смешивать разные форматы в одну кашу.
FAQ
Больше практики — в Telegram
Если внедряете AI-инструменты в разработку и не хотите строить процесс на вере в магию, забирайте практические разборы у Тимура в Telegram:
Подписаться
