Настройка CLAUDE.md для Claude Code
Разбираем, как использовать файл CLAUDE.md на основе принципов Андрея Карпаты, чтобы повысить точность и предсказуемость работы Claude Code в проектах.
Проблема непредсказуемости LLM в разработке
Проблема непредсказуемости LLM в разработке
Когда я впервые начал использовать Claude Code в своих проектах, я столкнулся с классической проблемой: агент работает отлично, пока задача не выходит за рамки очевидного. Он может написать чистый код, но при этом нарушить архитектурный паттерн, который я использую в проекте, или — что ещё хуже — использовать библиотеку, которая в моей среде считается устаревшей.
Проблема не в самой модели, а в том, как она воспринимает контекст. Без чётких инструкций LLM пытается угадать намерения разработчика, опираясь на свои веса, а не на специфику вашего репозитория. Это создаёт хаос: в одном PR вы видите использование async/await, а в следующем — старые колбэки, потому что агент «решил», что так будет проще.
Почему Claude Code ошибается
Основная причина ошибок — размытие контекста. Когда вы запускаете агента в большом репозитории, он сканирует файлы, строит дерево зависимостей и пытается понять, как всё работает. Но у него нет «памяти» о ваших предпочтениях и правилах, которые не прописаны явно в коде.
С практической точки зрения ошибки обычно делятся на три типа:
- Нарушение стиля (Style drift). Агент пишет код, который работает, но выглядит чужеродно. Например, вы используете функциональные компоненты в React, а он вдруг предлагает классовый подход.
- Ошибки в инструментарии. Если в проекте настроен специфический процесс сборки или тестирования, агент может попытаться запустить стандартную команду вроде
npm test, которая в вашем случае не сработает. - Галлюцинации API. Без явного указания версий используемых библиотек агент может использовать методы, которые были удалены в последних минорных обновлениях.
Если мы посмотрим на типичный процесс отладки, то увидим, что мы тратим больше времени на исправление «стилистического мусора», чем на саму разработку. Это убивает предсказуемость — ключевой параметр любой инженерной системы.
Роль контекста в работе агента
Чтобы агент работал не как «умный чат-бот», а как полноценный участник команды, ему нужен жесткий каркас. В индустрии это часто называют «Context Steering». Если опираться на принципы, которые транслирует Андрей Карпата, эффективная работа с нейросетями строится на предоставлении максимально структурированного и релевантного контекста.
Для Claude Code таким инструментом становится файл CLAUDE.md. Это не просто текстовый файл с комментариями, это своего рода «конфигурация поведения» для агента внутри конкретной директории.
Вместо того чтобы каждый раз в промпте писать: «Используй только TypeScript, не используй any и запускай тесты через pnpm», вы один раз фиксируете это в файле. Это позволяет перевести взаимодействие из режима «постоянных уточнений» в режим «предсказуемого исполнения».
С точки зрения архитектуры, CLAUDE.md выполняет роль локального манифеста. Когда агент обращается к проекту, он первым делом считывает этот файл, и его дальнейшие действия — выбор команд, написание кода и структура ответов — корректируются согласно этим правилам. Это минимизирует вероятность того, что агент совершит ошибку, которая в нормальных условиях была бы очевидна любому члену команды.
Принципы Андрея Карпаты для работы с кодом
Принципы Андрея Карпаты для работы с кодом
Когда мы говорим об эффективном взаимодействии с LLM, важно понимать, что модель — это не «магический шар», а статистический движок. Андрей Карпата, один из ключевых исследователей в области ИИ, часто подчёркивает, что успех работы с нейросетями зависит не от сложности промпта, а от качества контекста и структуры задачи.
В контексте Claude Code это означает, что если вы просто бросаете задачу в терминал, вы полагаетесь на удачу. Чтобы добиться предсказуемости, нужно превратить процесс из «угадай, что я хочу» в «выполни по чёткому алгоритму». Файл CLAUDE.md служит тем самым внешним слоем памяти, который фиксирует правила игры для модели в рамках конкретного проекта.
Типичные ошибки при генерации кода
С практической точки зрения, большинство проблем при работе с Claude Code возникают из-за избыточной свободы действий. Без жёстких рамок модель склонна к двум крайностям: либо к чрезмерному усложнению (overengineering), либо к игнорированию принятых в проекте паттернов.
Если мы посмотрим на типичный процесс разработки, можно выделить три критические ошибки:
- Нарушение архитектурного стиля. Модель может предложить использовать
async/awaitтам, где в вашем проекте приняты промисы, или внедрить новую библиотеку вместо уже используемой. - Галлюцинации в путях и зависимостях. Без указания структуры проекта Claude может попытаться импортировать модуль, которого не существует, или использовать устаревший API.
- Отсутствие контекста окружения. Модель не знает, что ваш проект работает под
Alpine Linuxили что вы используете специфическую версиюNode.js.
Чтобы минимизировать эти риски, в CLAUDE.md нужно прописать не только «что делать», но и «чего не делать». Например, если вы используете строгий линтинг, это должно быть зафиксировано:
markdown## Code Style Constraints
- Always use functional components for React.
- Avoid using any external libraries not listed in package.json.
- Use TypeScript strict mode; no 'any' types allowed.
Как структурировать инструкции для модели
Чтобы Claude Code работал эффективно, инструкции в CLAUDE.md должны быть атомарными и проверяемыми. Вместо размытых формулировок вроде «пиши чистый код», используйте конкретные технические требования.
Я рекомендую разделять файл на три логических блока: контекст проекта, технический стек и инструкции по выполнению команд. Это создаёт ту самую предсказуемость, которая необходима для автоматизации.
Во-первых, опишите команды для запуска и тестирования. Это позволит Claude самостоятельно проверять свои изменения. Если модель знает, как запустить тесты, она не просто выдаст код, а убедится, что он не сломал существующую логику.
markdown## Build and Test Commands
- Install dependencies: `npm install`
- Run development server: `npm run dev`
- Run unit tests: `npm test`
- Linting check: `npm run lint`
Во-вторых, задайте правила именования и структуру файлов. Это избавляет от необходимости каждый раз объяснять, где лежат ваши компоненты или эндпоинты.
В-третьих, добавьте раздел с «памятью» о принятых решениях. Если вы решили использовать Zod для валидации схем, зафиксируйте это. Это превращает CLAUDE.md в живой документ, который эволюционирует вместе с проектом.
Пример правильной структуры раздела с правилами:
markdown## Project Patterns
- Error handling: Use the custom `AppError` class from `@/utils/errors`.
- Data fetching: Always use `react-query` for asynchronous state.
- Styling: Use Tailwind CSS utility classes; avoid writing raw CSS.
Такой подход позволяет превратить Claude Code из простого помощника в полноценного участника команды, который соблюдает стандарты вашего репозитория так же строго, как и вы сами.
Создание и внедрение CLAUDE.md
Создание и внедрение CLAUDE.md
Чтобы Claude Code перестал гадать, как именно вы пишете код, ему нужно дать контекст. Файл CLAUDE.md работает как «инструкция по эксплуатации» вашего проекта для ИИ. Если вы просто запустите инструмент в корне репозитория, он будет пытаться угадать стиль, паттерны и команды сборки, основываясь на общих знаниях. Это путь к непредсказуемости: сегодня он использует npm, а завтра решит, что ваш проект — это yarn.
С практической точки зрения, создание этого файла — это способ стандартизировать поведение модели. Мы опираемся на идеи Андрея Карпаты, который подчеркивает важность четких инструкций и контекста для эффективной работы нейросетей. В случае с Claude Code, файл должен содержать три ключевых блока: команды для управления проектом, стандарты кодирования и правила архитектуры.
Создайте файл в корне вашего проекта:
bashtouch CLAUDE.md
Структура файла для вашего проекта
Я рекомендую не перегружать файл лишней информацией, но сделать его максимально плотным по смыслу. Чем меньше в CLAUDE.md «воды» и общих фраз, тем выше точность следования инструкциям.
Типовая структура выглядит так:
- Build and Test Commands: Конкретные команды, которые Claude должен использовать для проверки работоспособности кода.
- Code Style: Правила именования, предпочтения в синтаксисе и запреты.
- Architecture Patterns: Как компоненты должны взаимодействовать друг с другом.
Пример наполнения для проекта на Python (FastAPI):
markdown# CLAUDE.md — Project Guidelines
## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest tests/`
- Linting: `flake8 .`
- Run application: `uvicorn main:app --reload`
## Code Style
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer asynchronous programming (async/await) for I/O operations.
- Use Pydantic models for all request/response schemas.
- Documentation: Use Google-style docstrings.
## Architecture Patterns
- Dependency Injection: Use FastAPI's `Depends` for all service layers.
- Error Handling: Return custom exception classes that map to HTTP status codes.
- Database: Use SQLAlchemy 2.0 declarative mapping.
Если вы работаете в среде, где сборка требует специфических флагов или переменных окружения, обязательно укажите их. Например, если тесты не пройдут без поднятого Docker-контейнера, Claude должен знать, что сначала нужно выполнить docker-compose up -d.
Примеры правил для соблюдения архитектуры
Самая большая проблема при работе с ИИ-агентами — это когда они начинают «раздувать» проект, добавляя новые сущности там, где это нарушает логику. Чтобы этого избежать, в секцию архитектуры нужно вписать жесткие ограничения.
Если ваш проект использует микросервисную архитектуру или строгое разделение на слои (Layered Architecture), это должно быть прописано явно.
Вот пример правил для проекта на TypeScript, который использует Clean Architecture:
markdown## Architecture Patterns
- Layered Structure: Strictly separate Domain, Use Cases, and Infrastructure layers.
- Domain Entities: Must be pure TypeScript classes with no dependencies on external libraries.
- Repository Pattern: All database access must go through interfaces defined in the Domain layer.
- No Direct Imports: Use absolute paths (e.g., `@app/services/...`) instead of relative paths (`../../services/...`).
- Side Effects: Keep Use Cases pure; side effects (logging, DB, API calls) must be handled by injected adapters.
С точки зрения системного инженера, такие правила обеспечивают предсказуемость. Когда Claude Code предложит решение, он сначала сверится с этим списком. Если он попытается импортировать библиотеку напрямую в слой Domain, он увидит противоречие в своих же инструкциях.
Для эффективного внедрения начните с малого: запишите команды, которыми вы пользуетесь ежедневно. По мере того как вы будете замечать, что Claude совершает одну и ту же ошибку (например, забывает про обработку ошибок или использует не тот формат даты), добавляйте это в CLAUDE.md как новое правило. Это и есть процесс настройки системы, а не просто написание текста.
Практическое применение и тестирование
Проверка эффективности новых правил
Когда вы добавляете в CLAUDE.md новый набор инструкций — например, требование использовать systemd вместо кастомных скриптов инициализации — важно не просто верить на слово, что это работает. Инструменты вроде Claude Code работают на основе контекста, и если контекст перегружен противоречивыми указаниями, предсказуемость падает.
С практической точки зрения, я рекомендую использовать метод «контрольного запроса». После внесения изменений в файл, не просите ИИ сразу написать сложный код. Вместо этого дайте задачу на проверку понимания.
Например, если вы обновили правила оформления коммитов или структуру директорий, выполните проверку через CLI:
bash# Задаем вопрос о правилах проекта, чтобы проверить, подхватил ли Claude контекст из CLAUDE.md
claude "Какие правила именования файлов для сервисов в этом проекте я установил?"
Если ответ не соответствует вашему CLAUDE.md, значит, файл либо слишком объёмный и важные части «вымываются» из контекстного окна, либо правила сформулированы двусмысленно.
Ещё один способ — запуск тестового цикла. Если вы внедряете новые правила для работы с базой данных (например, обязательное использование миграций вместо прямого ALTER TABLE), попробуйте скомандовать:
bash# Просим спроектировать изменение, опираясь на текущие инструкции
claude "Нужно добавить колонку 'last_login' в таблицу users. Опиши план действий согласно нашим стандартам."
Если Claude Code предложит выполнить SQL-запрос напрямую, не упомянув инструмент миграций, значит, правило в CLAUDE.md недостаточно весомое. В этом случае стоит переформулировать его, используя более императивный стиль, как это советует Андрей Карпата в своих рассуждениях о структурировании знаний для моделей.
Поддержание актуальности документации
Файл CLAUDE.md — это не статичный документ, а живой манифест вашего проекта. Самая частая ошибка — превратить его в «кладбище инструкций», где старые правила конфликтуют с новыми технологиями. Если вы перешли с Docker Compose на Kubernetes (k3s), но в файле всё ещё прописаны команды docker-compose up, Claude будет генерировать нерабочий код.
Чтобы избежать этого, я придерживаюсь правила: любое изменение в архитектуре инфраструктуры или в процессе разработки должно сопровождаться обновлением CLAUDE.md.
Для автоматизации контроля я рекомендую добавить проверку наличия файла в ваш CI/CD пайплайн или хотя бы в pre-commit хуки. Это не проверит содержание, но гарантирует, что разработчики не забудут обновить инструкции при изменении окружения.
Пример простого скрипта для проверки актуальности (можно добавить в Makefile или package.json):
bash#!/bin/bash
# Простейшая проверка: если изменился docker-compose.yml, проверяем наличие обновлений в CLAUDE.md
if git diff --name-only | grep -q "docker-compose.yml"; then
echo "Внимание: Изменения в Docker Compose. Убедитесь, что инструкции в CLAUDE.md актуальны."
# Здесь можно добавить exit 1, чтобы заблокировать коммит, если это критично
fi
Если проект разрастается, не пытайтесь запихнуть всё в один файл. Хотя Claude Code и хорошо справляется с чтением CLAUDE.md, избыточный объем снижает точность. В таких случаях лучше оставить в корневом файле только высокоуровневые принципы и ссылки на специализированные инструкции, если ваш инструмент поддерживает чтение дополнительных файлов контекста.
Предсказуемость работы ИИ напрямую зависит от чистоты его «инструкций по эксплуатации». Регулярный аудит CLAUDE.md — это такая же часть администрирования проекта, как и обновление пакетов в apt.
Заключение
Итоговые рекомендации по внедрению
Если вы решили внедрить CLAUDE.md в свои проекты, не пытайтесь сразу описать в нём всю архитектуру системы. Это плохая практика: файл превратится в нечитаемый массив данных, который будет только путать модель.
Начните с малого. Сначала зафиксируйте правила именования и основные команды сборки. Когда почувствуете, что Claude Code начинает ошибаться в контексте или использовать не те паттерны, добавляйте новые секции. Главная цель этого файла — обеспечить предсказуемость. Если вы видите, что ИИ-ассистент раз за разом предлагает вам запустить npm run build вместо вашего кастомного скрипта, значит, пора внести это правило в CLAUDE.md.
Когда CLAUDE.md перестанет работать
Этот файл — не статичная документация, а живой инструмент. Он перестаёт приносить пользу в двух случаях:
- Избыточность (Overengineering). Если файл разрастается до нескольких тысяч строк, Claude начнет терять фокус. В этом случае лучше разбить инструкции на логические блоки и оставлять в
CLAUDE.mdтолько самые критичные правила, а детализацию вынести вREADME.mdили документацию кода. - Устаревание инструкций. Если вы сменили стек (например, перешли с
pytestнаgo test) или изменили структуру каталогов, но не обновили файл, Claude Code станет вашим главным источником ошибок.
Практический чек-лист перед завершением
Чтобы убедиться, что ваш файл настроен правильно, проверьте его по следующим пунктам:
- Команды доступны и актуальны. Попробуйте выполнить команды из файла в терминале. Если они не работают — Claude не сможет ими пользоваться.
- Стиль кода описан конкретно. Вместо «пиши чистый код» используйте «используй функциональный стиль, избегай глубокой вложенности и всегда добавляй type hints для аргументов функций».
- Секция Build & Test на месте. Без чёткого описания того, как проверить работоспособность изменений, Claude Code может выдать код, который просто не собирается.
Принципы, которые лежат в основе эффективного управления контекстом ИИ, во многом перекликаются с подходом Андрея Карпаты к обучению моделей: качество входных данных и чёткость инструкций напрямую определяют качество результата. Если вы настроите этот процесс системно, Claude Code станет не просто чат-ботом, а полноценным участником вашей команды разработки.
FAQ
Нужно ли создавать CLAUDE.md для каждого проекта?
Да, если вы хотите добиться предсказуемости. Каждый проект имеет свою специфику: структуру директорий, стиль именования переменных, используемые фреймворки и команды для запуска тестов.
Если вы будете использовать один общий файл для всех репозиториев, Claude начнет путаться. Например, в одном проекте вы используете npm test, а в другом — pytest. Без контекста модель может попытаться запустить неверную команду, что приведет к ошибкам в консоли и лишним итерациям исправления. С практической точки зрения, лучше держать CLAUDE.md в корне каждого репозитория. Это превращает файл в своего рода «инструкцию по эксплуатации» конкретной кодовой базы.
Как CLAUDE.md влияет на расход токенов?
Влияние есть, но оно оправдано. Когда вы запускаете Claude Code, содержимое CLAUDE.md подаётся в контекстное окно модели в качестве системных инструкций. Это увеличивает количество входных токенов при каждом запросе.
Однако, если не использовать этот файл, вам придётся вручную прописывать контекст в каждом промпте: «используй только Composition API», «пиши тесты на Vitest», «не меняй структуру папки /src/components». Это создаст гораздо больший избыточный расход токенов и сделает общение с моделью менее эффективным. Правильно структурированный файл экономит ресурсы за счёт того, что модель сразу понимает правила игры и не тратит попытки на «угадывание» вашего стиля.
Можно ли использовать этот подход с другими моделями?
Этот подход основан на принципах предоставления четкого контекста, которые популяризировал Андрей Карпата, и он применим практически к любой продвинутой LLM.
Если вы работаете не через Claude Code, а через API или другие интерфейсы (например, Cursor или Windsurf), вы можете адаптировать этот файл. Для моделей вроде GPT-4o или DeepSeek вы можете переименовать его в .cursorrules или просто добавить инструкции в системный промпт. Суть остаётся прежней: чем меньше неопределённости в инструкциях, тем выше качество кода.
Что делать, если Claude игнорирует правила из файла?
Если модель начинает нарушать установленные правила, скорее всего, они сформулированы слишком размыто. Модели плохо понимают абстракции вроде «пиши чистый код». Им нужны конкретные ограничения.
Проверьте файл на следующие ошибки:
- Избыточность. Если в файле 100 строк текста, важные инструкции тонут в «воде». Сокращайте.
- Противоречия. Убедитесь, что правила не конфликтуют друг с другом.
- Отсутствие примеров. Вместо «используй модульный стиль», напишите:
markdown
## Style Guide - Use functional components only. - Export components as named exports: `export const MyComponent = ...`
Если проблема сохраняется, попробуйте явно указать в чате: «Придерживайся правил из CLAUDE.md». Если это помогает, значит, инструкции в файле недостаточно приоритетны для текущего контекста. В таком случае стоит вынести самые критичные правила в начало файла.
Часто задаваемые вопросы
Где лучше хранить CLAUDE.md в структуре проекта?
Файл должен находиться в корневом каталоге вашего репозитория, чтобы Claude Code мог обнаружить его при инициализации сессии. Если ваш проект представляет собой монорепозиторий с несколькими независимыми сервисами, имеет смысл создать отдельные файлы CLAUDE.md в директориях каждого сервиса. Это обеспечит предсказуемость: агент будет применять специфичные правила сборки и тестирования именно для того контекста, в котором он сейчас работает.
Как CLAUDE.md влияет на расход токенов?
С практической точки зрения наличие этого файла немного увеличивает объем контекста, передаваемого модели при каждом запросе, так как инструкции считываются как часть системного промпта. Однако этот расход окупается за счёт сокращения количества итераций: вам не придётся тратить токены на исправление ошибок, вызванных непониманием архитектуры или неверными командами сборки. В долгосрочной перспективе использование файла делает работу агента более эффективной и экономичной.
Нужно ли дублировать правила из .eslintrc или .prettierrc?
Не стоит копировать туда технические детали форматирования, которые и так описаны в конфигурационных файлах линтеров. CLAUDE.md предназначен для высокоуровневых инструкций: архитектурных паттернов, правил именования, специфики работы с API или команд для запуска тестов. Если линтер уже умеет проверять отступы или точки с запятой, доверьте это инструментам, а в файле сосредоточьтесь на логике, которую автоматика не может уловить.
Что делать, если Claude Code игнорирует инструкции из файла?
Если агент продолжает нарушать правила, проверьте, не слишком ли они размыты. Вместо абстрактного «пиши чистый код» используйте конкретные указания, например: «Используй только функциональные компоненты и хуки React, избегай классовых компонентов». Также убедитесь, что инструкции не противоречат друг другу и не перегружены лишней информацией, которая может размыть фокус внимания модели.