Настройка CLAUDE.md для Claude Code
Как использовать файл CLAUDE.md на основе принципов Андрея Карпаты, чтобы повысить предсказуемость и качество работы Claude Code в ваших проектах.
Проблема непредсказуемого поведения LLM
Проблема непредсказуемого поведения LLM
Когда я впервые начал использовать Claude Code в своих проектах, я ожидал, что это будет похоже на работу с опытным junior-разработчиком: даёшь задачу — получаешь результат. Но на практике я столкнулся с тем, что нейросеть часто ведёт себя как очень старательный, но крайне невнимательный стажёр. Она может написать отличный алгоритм, но при этом нарушить архитектуру проекта, использовать не те библиотеки или, что ещё хуже, переписать существующий рабочий код, просто потому что «так выглядит чище».
Проблема здесь не в самой модели, а в отсутствии контекста и жёстких рамок. Без чётких инструкций LLM пытается угадать, как принято писать код именно в вашем проекте, и часто ошибается.
Типичные ошибки при написании кода нейросетями
Если мы посмотрим на процесс разработки с помощью ИИ, то увидим несколько повторяющихся сценариев, которые превращают работу в бесконечный цикл правок.
Во-первых, это нарушение конвенций проекта. Например, вы используете pnpm и строго следуете определённой структуре папок, а Claude Code вдруг решает запустить npm install или создаёт файлы в корне, где их быть не должно.
Во-вторых, это «галлюцинации» в зависимостях. Модель может предложить импортировать модуль, который существует в её обучающей выборке, но которого нет в вашем package.json.
В-третьих, это отсутствие понимания жизненного цикла проекта. Вот типичный пример того, как нейросеть может «сломать» окружение при попытке помочь:
bash# Claude Code может попытаться выполнить это, не проверив текущую среду
npm install some-package --save-dev
Вместо того чтобы проанализировать ваш pnpm-lock.yaml и использовать правильный менеджер пакетов, модель действует по шаблону, который она видела миллион раз в интернете. С практической точки зрения это приводит к конфликтам версий и раздуванию node_modules.
Почему стандартных инструкций недостаточно
Многие пытаются решить эту проблему через системный промпт или общие инструкции в начале чата. Но у такого подхода есть фундаментальный изъян: контекстное окно не бесконечно, а внимание модели рассеивается по мере роста диалога.
Стандартные инструкции — это как попытка объяснить правила дорожного движения на ходу, когда водитель уже выехал на трассу. Они слишком абстрактны. Фраза «пиши чистый код согласно PEP 8» не скажет модели, что в вашем конкретном проекте вы используете специфический декоратор для логирования или определённый стиль обработки ошибок.
Чтобы добиться предсказуемости, нам нужно не просто давать советы, а предоставлять «манифест проекта». Это концепция, которую можно развить на основе идей Андрея Карпаты, где акцент делается на понимании структуры и принципов работы системы.
Вместо того чтобы надеяться на интуицию нейросети, нам нужно внедрить файл CLAUDE.md. Он должен работать как технический стандарт, который модель считывает перед выполнением любой команды. Если в системном промпте — это «характер» модели, то в CLAUDE.md — это «устав» вашего конкретного репозитория. Только так можно минимизировать количество ситуаций, когда ИИ начинает «импровизировать» там, где нужна строгая дисциплина.
Суть подхода Андрея Карпаты
Суть подхода Андрея Карпаты
Когда мы говорим о работе с LLM в контексте разработки, важно понимать, что нейросеть — это не «волшебная палочка», а статистический движок. Если вы даёте ей слишком много свободы без чётких рамок, вы получаете непредсказуемый результат. Андрей Карпата, один из ключевых исследователей в области AI, часто подчёркивает важность структурированного подхода к обучению и взаимодействию с моделями. Его идеи о том, как эффективно подавать данные и контекст, отлично ложатся на использование Claude Code.
С практической точки зрения, работа с ИИ-агентом в терминале напоминает управление джуниор-разработчиком: если вы не опишете стандарты кодинга и структуру проекта, он начнёт «галлюцинировать» или предлагать решения, которые противоречат вашей архитектуре.
Анализ паттернов поведения Claude Code
Claude Code — это мощный инструмент, который работает непосредственно в вашем терминале. Он умеет читать файлы, запускать тесты и выполнять команды. Однако у него есть особенность: без внешних инструкций он полагается на свои внутренние веса и общие паттерны, полученные при обучении.
Если мы посмотрим на типичный цикл работы, то увидим следующие риски:
- Размытие стандартов. Модель может использовать
npmтам, где вы привыкли кpnpm, или предлагатьasync/awaitтам, где в проекте принят другой стиль обработки асинхронности. - Избыточность. Без ограничений агент может попытаться переписать весь файл ради одной функции, нарушая принцип минимальных изменений.
- Ошибки в окружении. Claude Code может попытаться запустить команду, которая не предусмотрена вашим
Makefileилиpackage.json.
Чтобы минимизировать эти риски, нам нужно перевести работу модели из режима «угадывания» в режим «следования протоколу».
Роль контекстного файла CLAUDE.md
Здесь на сцену выходит файл CLAUDE.md. Это не просто текстовый файл с заметками, это конфигурационный манифест вашего проекта для ИИ-агента. Если Docker Compose описывает инфраструктуру, то CLAUDE.md описывает «культуру» кодинга в конкретном репозитории.
Использование этого файла позволяет добиться предсказуемости — того самого качества, которое я ценю в любой системе. Вместо того чтобы каждый раз объяснять Claude, как запускать тесты, вы фиксируете это в одном месте.
Типичная структура CLAUDE.md должна включать три ключевых блока:
- Build & Test Commands: конкретные команды для сборки и проверки кода.
- Code Style Guidelines: правила именования, предпочтения в библиотеках и архитектурные ограничения.
- Project Context: краткое описание того, что делает проект и какие технологии являются ключевыми.
Пример минимально необходимого конфига для Node.js проекта:
markdown# CLAUDE.md - Project Guide
## Build and Test Commands
- Install dependencies: `pnpm install`
- Build project: `pnpm build`
- Run tests: `pnpm test`
- Run specific test: `pnpm test -- <file_path>`
- Linting: `pnpm lint`
## Code Style & Patterns
- Use TypeScript for all new files.
- Prefer functional components and hooks in React.
- Use `pnpm` instead of `npm` or `yarn`.
- Error handling: Always use custom error classes from `@/errors`.
- Testing: Use Vitest for unit tests; avoid Jest.
## Architecture
- Follow the hexagonal architecture pattern.
- Domain logic must be decoupled from infrastructure (DB, API).
С точки зрения системного инженера, наличие такого файла — это как наличие README.md или CONTRIBUTING.md, но оптимизированного под машинное чтение. Когда Claude Code инициализируется в директории, он первым делом ищет этот файл, чтобы синхронизировать свои действия с вашими ожиданиями. Это превращает хаотичный процесс генерации кода в контролируемый пайплайн.
Практическое применение CLAUDE.md
Структура и наполнение файла
Чтобы Claude Code не превращал работу над проектом в хаотичный процесс, ему нужны чёткие границы. Если мы не дадим контекст, нейросеть будет полагаться на свои общие веса, что часто приводит к нарушению архитектуры вашего приложения.
Я подхожу к созданию CLAUDE.md так же, как к написанию системного конфига: никакой воды, только конкретные инструкции, которые повышают предсказуемость. Файл должен служить «единым источником истины» для агента.
С практической точки зрения, я рекомендую разделять содержимое на три логических блока:
- Build & Test Commands: точные команды для сборки, запуска тестов и линтинга. Это избавляет от ошибок вида «я не знаю, как запустить тесты в этом репозитории».
- Code Style & Patterns: правила именования, предпочтительные библиотеки и архитектурные подходы.
- Project Context: описание ключевых связей в проекте, чтобы агент понимал, как изменение в одном модуле может затронуть другие.
Пример базовой структуры файла для проекта на Python:
markdown# CLAUDE.md — Project Guidelines
## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest tests/`
- Run linter: `flake8 .`
- Build package: `python -m build`
## Code Style & Patterns
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer asynchronous programming (asyncio) for I/O operations.
- Error handling: Use custom exception classes defined in `app/exceptions.py`.
- Logging: Use the standard `logging` module; do not use `print()`.
## Architecture Notes
- Services are located in `app/services/`.
- Database models must be defined in `app/models/` using SQLAlchemy.
- Dependency injection is handled via the `dependency_injector` library.
Примеры правил для улучшения генерации кода
Просто перечислить команды недостаточно. Чтобы Claude Code выдавал качественный код, нужно внедрить правила, которые ограничивают его «творчество» в пользу стандартов вашего проекта.
Если вы работаете с инфраструктурным кодом или сложными бэкенд-системами, я советую использовать принцип инженерного подхода Андрея Карпаты, где акцент делается на понимании структуры и минимизации шума.
Вот несколько сценариев, которые я применяю в своей практике:
1. Ограничение использования библиотек Если в вашем проекте уже есть установленный инструмент, не позволяйте нейросети тянуть новые зависимости. Это сохраняет чистоту окружения и предсказуемость билда.
markdown## Dependency Constraints
- Do not add new third-party libraries without explicit permission.
- Use `httpx` instead of `requests` for all HTTP calls.
- Use `pydantic` for all data validation and settings management.
2. Форматирование и документация
Чтобы не тратить время на исправление стиля после каждого коммита, пропишите требования к документации прямо в CLAUDE.md.
markdown## Documentation Standards
- Every public function must have a Google-style docstring.
- All complex logic must be explained with inline comments.
- Update `README.md` if new environment variables are introduced.
3. Работа с тестами Частая проблема — когда агент пишет код, но не пишет к нему тесты или пишет их неэффективно.
markdown## Testing Requirements
- Every new feature must include corresponding unit tests in `tests/unit/`.
- Use `pytest-mock` for all external service mocks.
- Ensure test coverage does not drop below 80%.
С точки зрения эксплуатации, наличие такого файла превращает Claude Code из «умного чат-бота» в полноценного участника процесса разработки, который соблюдает ваши стандарты так же строго, как это делал бы опытный инженер. Если правила прописаны корректно, количество правок в Pull Request сокращается в разы.
Оценка эффективности метода
Когда стоит внедрять файл в рабочий процесс
Использование CLAUDE.md — это не попытка навязать искусственный интеллект самому себе, а способ обеспечить предсказуемость. Если вы работаете над проектом в одиночку, вы и так знаете, где лежат конфиги и какой стиль отступов предпочитаете. Но как только проект разрастается или вы начинаете делегировать задачи Claude Code, возникает эффект «разного понимания».
С практической точки зрения, внедрять файл стоит в трёх случаях:
- Специфический стек и инструменты. Если ваш проект использует нестандартные команды сборки или специфические флаги в
Makefile. Без контекста Claude может попытаться использоватьnpm install, когда в вашем проекте настроенpnpmс жестким управлением версиями. - Строгие стандарты кодирования. Когда важно не просто «чтобы работало», а чтобы код соответствовал архитектуре. Например, если вы придерживаетесь принципов, описанных в курсе Андрея Карпаты, вам нужно явно указать Claude, как структурировать модули.
- Сложные процессы тестирования. Если для запуска тестов недостаточно команды
pytest, а требуется инициализация базы данных в Docker или подгрузка специфических фикстур.
Пример того, как может выглядеть секция команд в CLAUDE.md для проекта на Python:
markdown## Build and Test Commands
- Build project: `make build`
- Run tests: `pytest tests/ --cov=src`
- Linting: `ruff check .`
- Database migrations: `alembic upgrade head`
Когда эти инструкции зафиксированы, Claude Code перестаёт «гадать» и начинает выполнять действия, которые не сломают вашу локальную среду.
Ограничения и возможные сложности
Несмотря на пользу, у этого метода есть свои нюансы. Важно понимать, что CLAUDE.md — это не замена документации и не магическая палочка, которая исправит плохой код.
Во-первых, возникает проблема актуальности. Если вы изменили процесс деплоя или перешли с pytest на unittest, но забыли обновить CLAUDE.md, вы получите обратный эффект: Claude начнет предлагать невалидные команды, что только увеличит время на отладку. Я всегда рекомендую относиться к этому файлу как к части кодовой базы: любое изменение в инфраструктуре должно сопровождаться правкой инструкций для ИИ.
Во-вторых, существует риск перегрузки контекста. Если вы попытаетесь впихнуть в CLAUDE.md всё — от описания бизнес-логики до подробного руководства по настройке сетевых интерфейсов, — модель может начать игнорировать важные инструкции из-за избыточности.
Если мы посмотрим на структуру файла, то увидим, что он работает эффективно только тогда, когда в нём содержатся атомарные, четкие инструкции.
Плохой пример (слишком много воды):
«Мы стараемся писать код так, чтобы он был максимально эффективным и понятным для всех разработчиков, используя современные подходы к архитектуре...»
Хороший пример (конкретика):
«Используй только асинхронные методы
asyncioдля I/O операций. Избегай использования глобальных переменных.»
С точки зрения системного инженера, CLAUDE.md — это своего рода README для автоматизированного агента. Он требует дисциплины, но взамен даёт стабильный результат, который не нужно переделывать за нейросетью вручную.
Заключение
Итоговые рекомендации по внедрению
Если вы только начинаете внедрять CLAUDE.md в свои проекты, не пытайтесь сразу прописать там все правила архитектуры. Это превратит файл в нечитаемый полотно текста, которое модель будет игнорировать. Начните с малого: зафиксируйте команды сборки и структуру проекта.
С практической точки зрения, внедрение этого файла — это не попытка «обучить» ИИ, а способ обеспечить предсказуемость. Когда у Claude Code есть четкая инструкция, как запускать тесты или в каком стиле писать документацию, количество ошибок при автоматическом редактировании кода снижается в разы.
Когда CLAUDE.md перестанет работать
Важно понимать, что этот файл — не магическая таблетка, а контекстное руководство. Есть несколько сценариев, когда его эффективность падает:
- Раздутый контекст. Если вы запишете в
CLAUDE.mdслишком много второстепенных правил, модель начнет путаться в приоритетах. Если файл превышает несколько тысяч символов, Claude может начать «галлюцинировать» или игнорировать важные инструкции в середине текста. - Противоречие с существующим кодом. Если в файле написано «используй только функциональный стиль», а проект написан на классических классах, возникнет конфликт. Инструкции должны дополнять текущую реальность, а не пытаться её переписать на лету.
- Отсутствие актуализации. Проект растёт, меняются инструменты (например, вы перешли с
npmнаpnpm), а файл остался прежним. В итоге Claude Code будет пытаться использовать устаревшие команды, что приведет к ошибкам в терминале.
Чек-лист для проверки конфигурации
Перед тем как зафиксировать CLAUDE.md в репозитории, проверьте его по следующим пунктам:
- Команды сборки и тестов. Убедитесь, что команды в секции
Build/Test Commandsрабочие. Проверьте их вручную:bash# Запустите команду из файла в терминале, чтобы убедиться в её корректности npm run test:unit - Стиль кода. Если вы используете линтеры, укажите это. Например:
markdown
## Code Style - Use TypeScript for all new files. - Follow the project's ESLint configuration. - Use functional components for React. - Структура директорий. Если у вас нестандартная компоновка (например,
src/modulesвместоsrc/components), это должно быть отражено.
Для тех, кто хочет глубже изучить принципы работы с контекстом и эффективного обучения моделей, рекомендую ознакомиться с подходом Andrej Karpathy, который часто обсуждает важность качественных данных и инструкций для LLM.
В конечном счёте, CLAUDE.md — это часть вашей документации. Относитесь к нему так же серьёзно, как к README.md или конфигурации systemd: чем точнее и лаконичнее описание, тем стабильнее работает система.
FAQ
Нужно ли создавать CLAUDE.md для каждого проекта?
Да, если вы хотите добиться предсказуемости. Каждый проект обладает своей спецификой: набором технологий, правилами именования и архитектурными ограничениями. Если вы используете один и тот же стек (например, Docker и Go) во всех своих домашних лабораториях, вы можете создать шаблон, но наполнение должно быть уникальным.
Без этого файла Claude Code будет каждый раз «гадать», как именно вы привыкли запускать тесты или где лежат ваши конфигурационные файлы. С CLAUDE.md вы превращаете ИИ из случайного помощника в инженера, который уже знаком с вашим кодом.
Как CLAUDE.md влияет на скорость работы Claude Code?
Файл работает как контекстный фильтр. Вместо того чтобы тратить токены на анализ всего репозитория в поисках способа запустить сборку, модель сразу обращается к инструкциям. Это сокращает количество итераций и ошибочных команд.
Например, если в проекте используется нестандартный способ запуска тестов, Claude не будет пытаться выполнить стандартный npm test, а сразу применит команду из вашего файла:
markdown## Build and Test Commands
- Build: `make build`
- Test: `go test ./... -short`
- Lint: `golangci-lint run`
Это экономит время и предотвращает ситуацию, когда модель зацикливается на попытках выполнить неверные команды.
Можно ли использовать этот файл с другими моделями?
Смысл файла заключается в передаче контекста, поэтому его можно адаптировать под любую LLM, работающую в режиме агента или чата. Однако Claude Code считывает его автоматически и использует как часть своего системного промпта.
Для других моделей (например, через интерфейс ChatGPT или сторонние IDE) вам придётся вручную копировать содержимое CLAUDE.md в начало диалога. Чтобы не делать это каждый раз, можно использовать подход, описанный в принципах Andrej Karpathy, где инструкции по стилю и структуре кода подаются как фундаментальные правила проекта.
Где хранить файл CLAUDE.md в репозитории?
Файл должен лежать в корневом каталоге вашего проекта. Это стандартное поведение для инструментов, работающих с контекстом репозитория.
Если вы работаете в монорепозитории, где несколько сервисов имеют разные стеки (например, один на Python, другой на Rust), лучше всего разместить отдельные CLAUDE.md в поддиректориях каждого сервиса. Это обеспечит точность инструкций для каждого конкретного окружения.
bash# Структура монорепозитория с локальными инструкциями
my-homelab/
├── services/
│ ├── monitoring/
│ │ ├── CLAUDE.md # Инструкции для Prometheus/Grafana
│ │ └── docker-compose.yml
│ └── storage/
│ ├── CLAUDE.md # Инструкции для ZFS/TrueNAS скриптов
│ └── setup.sh
└── CLAUDE.md # Общие правила проекта
Часто задаваемые вопросы
Зачем нужен CLAUDE.md, если я могу просто давать инструкции в чате?
Инструкции в чате имеют свойство забываться или терять приоритет по мере роста контекста диалога. Файл CLAUDE.md работает как постоянный слой конфигурации, который Claude Code считывает при каждом запуске. С практической точки зрения это обеспечивает предсказуемость: модель всегда будет знать, какой менеджер пакетов использовать и как структурировать код, даже если вы начали новый сеанс работы.
Можно ли использовать один CLAUDE.md для нескольких разных проектов?
Я не рекомендую копировать один и тот же файл во все репозитории, так как это нарушает принцип изоляции контекста. Каждый проект имеет свои особенности: в одном вы используете pnpm, в другом — npm, в одном архитектура строится на микросервисах, а в другом — на монолите. Лучше создать уникальный CLAUDE.md для каждой домашней лаборатории или рабочего проекта, чтобы избежать конфликтов в инструкциях.
Как понять, что инструкции в CLAUDE.md работают эффективно?
Эффективность проявляется в снижении количества ваших правок после того, как Claude Code выполнил задачу. Если вы заметили, что модель снова пытается использовать не тот стиль именования или ошибается в командах сборки, значит, эти правила нужно явно прописать в файле. Хороший CLAUDE.md — это живой документ, который вы дополняете по мере выявления новых паттернов ошибок.
Влияет ли наличие этого файла на скорость работы модели?
Наличие файла практически не влияет на задержку (latency) при генерации ответа, так как объем текста в CLAUDE.md обычно невелик по сравнению с основным кодом проекта. Однако это значительно экономит ваше время в долгосрочной перспективе. Вместо того чтобы тратить ресурсы на исправление архитектурных ошибок, вы сразу получаете результат, соответствующий вашим стандартам.