CLAUDE.md: улучшение поведения Claude Code по Karpathy

Один файл CLAUDE.md, основанный на наблюдениях Андрея Карпатьева, помогает Claude Code работать более предсказуемо и эффективно.

Проблема и цель CLAUDE.md

Когда я начинал работать с терминальными агентами вроде Claude Code, я ожидал, что они сразу поймут архитектуру моего проекта. Но на практике всё оказалось иначе. Вместо того чтобы стать полноценным участником команды, нейросеть часто превращается в навязчивого стажёра: она делает много лишних движений, ошибается в путях к файлам и, что самое неприятное, постоянно нарушает сложившиеся в проекте правила оформления кода.

Если вы используете Claude Code для работы в своей домашней лаборатории или на рабочем проекте, вы наверняка сталкивались с ситуацией, когда агент начинает «галлюцинировать» относительно структуры директорий или предлагает использовать библиотеки, которые в вашем стеке запрещены.

Типичные ошибки LLM при генерации кода

Основная проблема при работе с LLM в контексте кодинга — это отсутствие контекста о «традициях» конкретного репозитория. Модель обучалась на миллиардах строк кода, и её стандартное поведение — это усреднённое решение. В инженерной практике «усреднённое» часто означает «неправильное для данного проекта».

С практической точки зрения я выделяю три критические ошибки:

Нарушение стиля и линтеров. Агент может написать рабочий код, но он будет конфликтовать с вашим Prettier или ESLint. В итоге вам приходится тратить время на исправление форматирования, которое должен был сделать сам инструмент.
Неверные команды сборки. Модель может попытаться запустить npm run dev, хотя в вашем проекте используется make build или специфический скрипт внутри Makefile.
Игнорирование архитектурных паттернов. Если вы используете чистую архитектуру или строгое разделение слоёв, LLM может попытаться внедрить логику базы данных прямо в контроллер, потому что «так проще».

Пример того, как это выглядит в логах:

bash
# Ожидаемый результат:
$ make test

# То, что пытается сделать Claude Code без контекста:
$ pytest tests/  # Ошибка: в проекте используется go test

Почему нужен единый конфиг

Чтобы добиться предсказуемости, нам нужно ограничить поле маневра модели. Мы не можем заставить её «просто работать лучше», но мы можем дать ей четкую инструкцию, которая будет служить якорем. Идея, которую продвигает Андрей Карпатьев, заключается в использовании файла CLAUDE.md.

Этот файл работает как локальный манифест проекта. Вместо того чтобы каждый раз объяснять агенту в чате, как запускать тесты или в каком стиле писать комментарии, вы фиксируете это в одном месте. Это похоже на то, как я настраиваю systemd юниты для своих сервисов: вместо того чтобы запускать процессы вручную с кучей флагов, я описываю состояние системы один раз, чтобы оно всегда было воспроизводимым.

Единый конфиг решает две задачи:

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

Внутри этого файла мы описываем три ключевых аспекта:

Build/Test commands: конкретные команды для сборки, запуска тестов и линтинга.
Code style: правила именования, предпочтения по библиотекам и запреты.
Project structure: краткое описание того, где лежат важные компоненты.

Такой подход превращает Claude Code из непредсказуемого генератора текста в инструмент, который соблюдает правила вашей инженерной культуры.

Ключевые принципы из наблюдений Карпатьева

Когда мы работаем с ИИ-агентами вроде Claude Code, основная проблема заключается не в их «интеллекте», а в размытии контекста. Если вы даёте модели слишком много свободы без чётких рамок, она начинает гадать. А в системном администрировании или разработке гадание — это прямой путь к поломке окружения.

Андрей Карпатьев в своих размышлениях о взаимодействии с LLM подчёркивает, что эффективность агента напрямую зависит от того, насколько плотно мы ограничили его поле деятельности и насколько прозрачны правила игры. Файл CLAUDE.md служит своего рода «конституцией» проекта, которая превращает хаотичные попытки ИИ угадать ваши намерения в предсказуемый рабочий процесс.

Ясные инструкции и контекст

Первый принцип — это избавление от двусмысленности. Если в проекте принято использовать make для сборки, а не npm run build, об этом должно быть сказано прямо. Без этого Claude может попытаться использовать стандартные для него инструменты, которые просто не установлены в вашей системе или не соответствуют принятым стандартам.

В CLAUDE.md стоит прописать не только команды, но и стиль написания кода или логику обработки ошибок. С практической точки зрения, это экономит время на проверку того, что нагенерировал агент.

Пример секции для файла CLAUDE.md, описывающей правила работы с проектом:

markdown
## Build and Test Commands

- Build the project: `make build`
- Run tests: `make test`
- Linting: `make lint`

## Code Style Guidelines

- Use functional programming patterns where possible.
- Error handling: always wrap asynchronous calls in try/catch blocks.
- Naming: use snake_case for all database schema definitions.

Когда у модели есть такой справочник, она перестаёт тратить токены на «размышления» о том, как правильно запустить тесты, и сразу переходит к делу. Это и обеспечивает ту самую предсказуемость, к которой мы стремимся при настройке любого автоматизированного процесса.

Изоляция окружения и зависимости

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

Карпатьев акцентирует внимание на том, что агент должен иметь чёткое представление о границах своего окружения. Если ваш проект живет внутри Docker-контейнера, инструкции в CLAUDE.md должны явно указывать, что все команды нужно выполнять через docker exec.

Если мы посмотрим на типичную структуру проекта, то лучше всего зафиксировать способ взаимодействия с окружением следующим образом:

markdown
## Environment Context

- This project runs inside a Docker container.
- To run any command within the environment, use: `docker compose exec app <command>`
- Do not attempt to install packages directly on the host machine.
- Database is accessible via `localhost:5432` only through the container network.

С точки зрения системного инженера, это напоминает настройку прав доступа в sudoers. Мы не запрещаем пользователю (в данном случае — агенту) выполнять действия, но мы строго определяем, через какие инструменты и в каких границах эти действия допустимы. Такой подход минимизирует риск того, что Claude попытается обновить системные библиотеки там, где это не требуется.

Практические рекомендации

Настройка параметров модели

Когда мы работаем с Claude Code, важно понимать: модель — это не магия, а инструмент, чья предсказуемость напрямую зависит от контекста. Если вы просто бросаете задачу в терминал, вы получаете максимально «размытый» результат. Использование файла CLAUDE.md позволяет задать жесткие рамки, которые превращают LLM из собеседника в дисциплинированного инженера.

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

Например, если ваша домашняя лаборатория построена на базе Docker и вы используете строго определённые версии образов, это должно быть прописано. Вместо того чтобы каждый раз объяснять, почему нельзя использовать latest, вы один раз фиксируете это в правилах.

Пример структуры секции для CLAUDE.md, которая помогает модели придерживаться стандартов:

markdown
## Code Style & Patterns
- Use strictly typed TypeScript for all new services.
- Prefer functional programming patterns over classes.
- All Dockerfiles must use multi-stage builds to minimize image size.
- Use `tini` as an init process in all Docker containers to handle signals correctly.
- Error handling: Always wrap async calls in try/catch and log via the internal logger.

Такой подход гарантирует, что Claude не будет предлагать вам «решения на коленке», а будет генерировать код, который сразу готов к деплою в вашу инфраструктуру.

Тестирование и отладка

Самая большая проблема при работе с AI-агентами в терминале — это галлюцинации, когда модель уверена, что код работает, хотя он падает на первой же строчке. Чтобы минимизировать этот риск, в CLAUDE.md необходимо четко определить команды для запуска тестов и проверки состояния системы.

Я всегда придерживаюсь принципа: если модель не может сама запустить тест и увидеть ошибку, она не должна предлагать исправление. Вы должны предоставить ей «рельсы», по которым она будет проверять свою работу.

Во-первых, укажите команды для быстрого запуска тестов. Во-вторых, опишите, как именно нужно интерпретировать вывод. Если вы используете pytest или jest, Claude должен знать, какой флаг использовать для получения подробного лога.

Вот как может выглядеть раздел тестирования в вашем конфигурационном файле:

markdown
## Test Commands
- Run all unit tests: `npm test`
- Run a single test file: `npm test -- <path_to_file>`
- Check linting errors: `npm run lint`
- Verify Docker build: `docker compose build --no-cache`

## Debugging Workflow
- If a test fails, analyze the stack trace in the terminal output.
- Check logs using `docker compose logs -f <service_name>` before proposing a fix.
- Always verify that new environment variables are added to `.env.example`.

Если вы опираетесь на идеи Андрея Карпатьева, то понимаете: эффективность работы с нейросетями — это не про «удачный промпт», а про создание правильной среды обитания для модели. Чем меньше у неё пространства для воображения и чем больше жестких технических инструкций, тем выше предсказуемость результата.

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

Интеграция в рабочий процесс

Когда мы говорим о работе с ИИ-агентами вроде Claude Code, главная проблема — это «галлюцинации» в контексте управления проектом. Без чётких инструкций модель начинает гадать, как именно в вашем окружении запускаются тесты или как разворачивается локальная среда. Файл CLAUDE.md решает эту задачу, превращая хаотичные попытки модели угадать команды в предсказуемый алгоритм.

С практической точки зрения, это не просто текстовый файл, а своего рода «манифест поведения» для агента, который минимизирует количество лишних запросов и ошибок.

Автоматизация через скрипты

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

Если вы используете Docker для разработки, не заставляйте Claude Code разбираться в структуре ваших docker-compose.yaml файлов каждый раз. Вместо этого создайте обёртки.

Сначала создадим простой скрипт для запуска тестов, например, scripts/test.sh:

bash
#!/bin/bash
# Скрипт для запуска тестов в изолированном контейнере
# Используем --rm, чтобы не оставлять мусор в системе
docker compose run --rm app pytest "$@"

Затем добавьте описание этих команд в ваш CLAUDE.md. Это даст модели четкое понимание, какой инструмент использовать. Пример секции в файле:

markdown
## Build and Test Commands

- Run tests: `bash scripts/test.sh [args]`
- Build project: `docker compose build`
- Check linting: `npm run lint`

Такой подход обеспечивает предсказуемость: модель точно знает, что для проверки кода нужно вызвать конкретный скрипт, а не пытаться запустить pytest напрямую в хостовой системе, где может не быть нужных зависимостей.

Документация и поддержка

Второй важный аспект — это поддержание актуальности контекста. По наблюдениям, которые транслирует Андрей Карпатьев, ИИ-агенты работают значительно лучше, если у них есть «карта местности». В рамках CLAUDE.md это реализуется через краткие технические заметки о структуре проекта и правилах написания кода.

Не нужно переписывать весь README.md. Здесь важны только те детали, которые влияют на принятие решений при написании кода. Например, если вы используете специфический стиль именования или архитектурный паттерн, это должно быть зафиксировано.

Пример того, как может выглядеть секция документации в CLAUDE.md:

markdown
## Project Standards

- Architecture: Hexagonal architecture. Keep domain logic pure from infrastructure.
- Naming: Use snake_case for Python functions and variables.
- Error Handling: Always wrap database operations in try-except blocks and log via the internal logger.
- Database: PostgreSQL. Use Alembic for all migrations.

Если вы добавите в этот файл инструкции по работе с миграциями, Claude Code не будет пытаться менять схему базы данных «на лету» через SQL-запросы, а будет использовать установленный в проекте инструмент.

С точки зрения системного инженера, такой файл — это часть вашей документации как кода (Documentation as Code). Чем точнее вы опишете правила игры в CLAUDE.md, тем меньше времени вы потратите на исправление ошибок, которые модель совершила из-за непонимания контекста.

Часто задаваемые вопросы

Как правильно оформить CLAUDE.md, чтобы Claude Code «понял» мою проектную структуру?

Сначала разместите файл в корне репозитория и разделите его на логические блоки: описание корневых каталогов, правила именования файлов, список запрещённых зависимостей и примеры команд сборки. Укажите, где находятся конфиги линтеров (.eslintrc, .prettierrc) и как их запускать, чтобы модель знала, какие стили нужно соблюдать. Такой явно заданный контекст избавит от «гаджета» в предположениях модели.

Нужно ли перечислять каждый файл и каталог в CLAUDE.md?

Перечисление в виде полного списка часто приводит к ошибкам, потому что модель может не распознать шаблоны. Лучше описывать каталоги с помощью паттернов (например, config/*.js) и фиксировать только исключения, а не каждое отдельное имя. Это упрощает поддержку и уменьшает риск того, что агент «потеряется» в структуре.

Как заставить Claude Code не предлагать запрещённые библиотеки?

В отдельном разделе CLAUDE.md укажите список запрещённых пакетов и причину их запрета (например, лицензия, конфликт с текущим стеком). Добавьте в инструкцию для агента, что любые предложения о новых зависимостях должны проходить проверку через npm list или yarn why. Регулярное обновление этого списка будет поддерживать предсказуемость поведения.

Что делать, если Claude Code пишет код, не соответствующий моему стилю форматирования?

Включите в CLAUDE.md пункт «Стиль кода», где описаны требуемые команды: npx prettier --write . или eslint --fix. Сообщите агенту, что перед коммитом код должен быть отформатирован, и приведите пример корректного вызова formatter‑а. При указании конкретного инструмента модель будет меньше рисковать нарушить ваш линтер.

Нужно ли обновлять CLAUDE.md, когда меняются скрипты сборки или архитектура проекта?

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