Средний

Настройка CLAUDE.md для Claude Code

Алексей Кузнецов
Алексей Кузнецов
Системный администратор13 ноября 2026 г.16 мин чтения

Разбираем, как файл CLAUDE.md на базе идей Андрея Карпаты помогает улучшить поведение Claude Code и сделать процесс разработки более предсказуемым.

Настройка CLAUDE.md для Claude Code

Разбираем, как файл CLAUDE.md на базе идей Андрея Карпаты помогает улучшить поведение Claude Code и сделать процесс разработки более предсказуемым.

Проблема непредсказуемости LLM в кодинге

Проблема непредсказуемости LLM в кодинге

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

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

Типичные ошибки при работе с Claude Code

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

Во-первых, это нарушение стиля кодирования. Например, если ваш проект использует строгую типизацию в TypeScript, модель может начать предлагать решения с использованием any, просто потому что это кратчайший путь к выполнению задачи.

Во-вторых, неверный выбор инструментов. Представьте, что в вашем проекте для работы с базой данных используется Prisma, а Claude внезапно начинает писать прямые SQL-запросы через pg. Это не просто ошибка — это создание технического долга в ту же секунду, когда код был сгенерирован.

К типичным ошибкам также относятся:

  • Использование устаревших API-методов, которые были удалены в последних версиях библиотек.
  • Игнорирование структуры тестов: модель пишет функционал, но не создает тесты или пишет их в стиле, который не проходит ваш CI/CD.
  • Неправильное управление зависимостями: вместо добавления пакета через npm install или pnpm add, модель может просто прописать его в package.json вручную, что нарушает целостность lock-файла.

Почему стандартных системных инструкций недостаточно

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

Проблема в том, что контекстное окно LLM ограничено, а объем информации о проекте (структура папок, зависимости, правила линтинга, способы запуска тестов) может быть огромным. Если пытаться запихнуть всё это в один запрос, модель начнёт терять фокус.

Здесь на помощь приходит концепция, которую развивает Андрей Карпатый в своих материалах о работе с агентами LLM OS. Идея заключается в том, чтобы предоставить модели «локальную память» или набор правил, которые всегда находятся под рукой и описывают именно текущую рабочую среду.

Стандартные инструкции говорят: «Пиши чистый код». Файл CLAUDE.md говорит: «В этом проекте мы используем pnpm, тесты запускаются через vitest, а для оформления коммитов используем conventional commits».

Разница между этими подходами — в предсказуемости. Когда у модели есть локальный файл с правилами, она перестаёт гадать и начинает следовать протоколу. Это превращает Claude Code из непредсказуемого генератора кода в инструмент, который понимает правила игры в вашем конкретном проекте.

Применение методологии Андрея Карпаты

Анализ паттернов поведения нейросетей

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

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

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

Например, если ваш проект использует pytest с определёнными фикстурами, это должно быть прописано явно. Без этого агент может начать генерировать тесты на unittest, что заставит вас тратить время на рефакторинг за ним.

Перенос инженерного подхода в промпты

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

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

Вот пример структуры CLAUDE.md, которую я использую в своих проектах для обеспечения предсказуемости:

markdown
# Claude Code Project Standards

## Build and Test Commands
- Install dependencies: `npm install`
- Run development server: `npm run dev`
- Execute tests: `npm test -- --watchAll=false`
- Linting: `npm run lint`

## Code Style Guidelines
- Use TypeScript for all new files; avoid `any` at all costs.
- Prefer functional components and hooks over class components.
- Error handling: Always wrap asynchronous calls in try/catch blocks and use the custom `AppError` class.
- Naming: Use PascalCase for components, camelCase for functions and variables.

## Project Architecture Patterns
- Services must be stateless.
- Data fetching is handled exclusively via the `useQuery` hook from TanStack Query.
- All API interactions must go through the `/src/api` layer.

Заметьте, здесь нет фраз вроде «старайся писать чистый код». Вместо этого — конкретные команды и архитектурные ограничения.

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

bash
# Пример запроса к Claude Code для проверки соблюдения стандартов
claude "Check if the latest changes in /src/services follow the stateless requirement defined in CLAUDE.md"

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

Практическая настройка CLAUDE.md

Структура и наполнение конфигурационного файла

Чтобы Claude Code перестал гадать, какой стиль написания кода вы предпочитаете, ему нужно дать чёткий контекст. Файл CLAUDE.md работает как локальный манифест проекта. Если мы посмотрим на подход, который популяризировал Андрей Карпата, то увидим, что успех взаимодействия с ИИ зависит не от сложности промпта, а от структурированности инструкций.

Я не сторонник огромных полотен текста, в которых модель теряет нить повествования. Для предсказуемого поведения лучше всего работает разделение на три логических блока: технический стек, правила оформления и команды для управления проектом.

Создайте файл CLAUDE.md в корне вашего репозитория. Вот пример того, как я структурирую его для своих проектов на базе Python и Docker:

markdown
# Project Context: My-Service-API

## Tech Stack
- Language: Python 3.11+
- Framework: FastAPI
- Database: PostgreSQL (via SQLAlchemy)
- Containerization: Docker Compose
- Testing: Pytest

## Code Style & Patterns
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer composition over inheritance.
- Error handling: Use custom exception classes defined in `app/exceptions.py`.
- Documentation: All public methods must have Google-style docstrings.

## Common Commands
- Build: `docker compose build`
- Run tests: `pytest tests/`
- Linting: `ruff check .`
- Format: `black .`

С практической точки зрения, наличие раздела Common Commands экономит массу времени. Вместо того чтобы каждый раз просить Claude «запусти тесты», он просто возьмёт готовую команду из файла. Это исключает ошибки, когда модель пытается использовать npm test в проекте на Python.

Примеры правил для улучшения качества кода

Просто перечислить стек недостаточно. Чтобы Claude Code не превращал ваш проект в свалку из «решений на коленке», нужно внедрить специфические правила. Чем конкретнее вы опишете запреты, тем выше будет предсказуемость результата.

Если вы работаете с инфраструктурой или сложной логикой, добавьте в секцию Code Style & Patterns правила, которые отражают ваш инженерный подход.

Например, если вы хотите, чтобы вся работа с базой данных проходила строго через асинхронные сессии, пропишите это явно:

markdown
## Strict Rules
- Database: Always use `AsyncSession` from `sqlalchemy.ext.asyncio`. 
- No synchronous DB calls in route handlers.
- Logging: Use the structured logger from `app.core.logger`. Do not use standard `print()`.
- Environment: Always fetch configuration from `pydantic-settings` (BaseSettings).

Ещё один важный момент — работа с тестами. Я часто сталкиваюсь с тем, что ИИ пишет тесты, которые проходят, но не проверяют граничные случаи. Чтобы этого избежать, добавьте инструкцию:

markdown
## Testing Requirements
- Every new feature must include a corresponding test file in `tests/`.
- Use `pytest-mock` for all external service dependencies.
- Ensure coverage for edge cases (e.g., empty inputs, connection timeouts).

С точки зрения эксплуатации, такие правила превращают Claude из простого «генератора текста» в полноценного участника процесса разработки, который соблюдает архитектурные границы вашего проекта. Если вы добавите эти инструкции, модель перестанет предлагать print() для отладки и начнет использовать ваш настроенный логгер, что критически важно для последующего анализа логов в production-среде.

Результаты внедрения в рабочий процесс

Результаты внедрения в рабочий процесс

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

Снижение количества галлюцинаций

Основная проблема любого AI-агента — склонность к «творчеству» там, где нужны строгие стандарты. Без файла контекста Claude Code может предложить использовать библиотеку, которой нет в вашем package.json, или применить синтаксис, который не поддерживается вашей версией Python.

Внедрение CLAUDE.md решает эту проблему за счёт жесткой фиксации технологического стека и правил написания кода. Если в файле прописано, что для работы с базой данных мы используем только SQLAlchemy и строго следуем паттерну Repository, модель перестанет предлагать прямые запросы через psycopg2.

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

markdown
## Project Structure
- Core logic: `src/core/`
- API handlers: `src/api/`
- Database migrations: `migrations/`
- Tests: `tests/unit/` and `tests/integration/`

## Coding Standards
- Use Type Hints for all function signatures.
- Error handling: Always wrap I/O operations in try-except blocks with custom exceptions from `src/core/exceptions.py`.
- Database: Use SQLAlchemy ORM; no raw SQL allowed.

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

Ускорение итераций разработки

Второй важный аспект — это скорость. В обычном режиме вы тратите время на то, чтобы объяснить Claude, как запустить тесты, как собрать проект или как развернуть окружение. С CLAUDE.md эти инструкции становятся частью «памяти» агента.

Я добавил в файл секцию Build and Test Commands. Теперь, когда я прошу Claude «исправь баг в модуле авторизации», он не просто пишет код, а сразу знает, какую команду выполнить, чтобы проверить результат. Ему не нужно спрашивать: «А как мне запустить тесты?».

Пример типичного блока команд в CLAUDE.md:

markdown
## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run linting: `flake8 src/`
- Run unit tests: `pytest tests/unit`
- Run integration tests: `pytest tests/integration`
- Build Docker image: `docker build -t my-app:latest .`

С точки зрения рабочего процесса, это сокращает цикл обратной связи. Если вы используете Docker для локальной разработки, наличие команды сборки в контексте позволяет агенту самостоятельно проверять работоспособность изменений в контейнере.

Если мы посмотрим на типичный цикл разработки, то без CLAUDE.md он выглядит так:

  1. Запрос на изменение кода.
  2. Генерация кода.
  3. Попытка запуска (ошибка, так как неверная команда).
  4. Поиск команды запуска в README.
  5. Повторный запрос.

С внедрённым файлом этот цикл схлопывается до двух шагов:

  1. Запрос на изменение кода.
  2. Генерация и автоматическая проверка через команды из CLAUDE.md.

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

Заключение

Итоги по внедрению CLAUDE.md

Если подходить к вопросу системно, то CLAUDE.md — это не просто текстовый файл с инструкциями, а способ перенести ваш инженерный опыт и стандарты проекта в контекст LLM. Без него Claude Code работает в режиме «угадай, что имел в виду автор», что неизбежно ведёт к ошибкам в архитектуре или стиле кода. С ним вы получаете предсказуемость.

С практической точки зрения, внедрение этого файла даёт три ключевых преимущества:

  1. Снижение когнитивной нагрузки. Вам не нужно каждый раз объяснять модели, как запускать тесты или в каком формате писать коммиты.
  2. Единообразие кодовой базы. Даже если над проектом работают разные люди (или разные агенты), стиль кода остаётся консистентным.
  3. Ускорение циклов разработки. Модель сразу понимает структуру проекта и не тратит токены на сканирование лишних директорий.

Когда этот подход перестанет работать

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

Если ваш проект разрастается до масштабов монолита с сотнями микросервисов, один файл перестанет справляться. В такой ситуации я рекомендую использовать иерархический подход: держать общий CLAUDE.md в корне репозитория для глобальных правил, а в поддиректориях с критически важными компонентами (например, /services/auth или /packages/core) создавать локальные инструкции.

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

Резюме по настройке

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

  1. Определите базовый стек и команды управления (build, test, lint).
  2. Зафиксируйте архитектурные паттерны (например, использование Dependency Injection или конкретную структуру папок).
  3. Пропишите правила именования и обработки ошибок.

Пример минимально необходимого набора команд в файле может выглядеть так:

markdown
## Build and Test Commands
- Build project: `npm run build`
- Run tests: `npm test`
- Run specific test: `npm test -- <path_to_file>`
- Linting: `npm run lint`

## Code Style Guidelines
- Use functional components for React.
- Prefer explicit type annotations over inference.
- Error handling: Always wrap async calls in try/catch blocks with custom Error classes.

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

FAQ

Как добавить свои правила в CLAUDE.md?

Чтобы добавить новые инструкции, вам не нужно переписывать весь файл. Достаточно дополнить существующие секции или создать новую, если правило касается специфического процесса. Я рекомендую структурировать дополнения по принципу «от общего к частному».

Если вы хотите, чтобы Claude Code всегда следовал определённому стилю написания тестов или использовал конкретную библиотеку для работы с датами, добавьте это в раздел Guidelines. Например, если в вашей домашней лаборатории вы используете только pytest для тестирования Python-скриптов, пропишите это явно:

markdown
## Testing Guidelines
- Always use `pytest` for unit tests.
- Mock all network calls using `unittest.mock`.
- Ensure test coverage includes edge cases for configuration parsing.

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

Влияет ли этот файл на расход токенов?

Да, влияет, и это стоит учитывать при планировании сессий. Каждый раз, когда вы инициируете диалог или Claude Code анализирует контекст, содержимое CLAUDE.md передаётся в системном промпте.

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

  1. Увеличение стоимости каждой итерации (если вы используете платные API).
  2. Снижение «внимания» модели к текущему коду, так как часть контекстного окна будет занята чтением правил.

Чтобы сохранить предсказуемость и не раздувать расход, придерживайтесь лаконичности. Вместо длинных объяснений используйте короткие императивные команды. Вместо «Пожалуйста, старайся всегда использовать двойные кавычки в JSON-файлах» пишите «Use double quotes in all JSON files».

Нужно ли обновлять файл при смене стека технологий?

Безусловно. CLAUDE.md — это не статичный документ, а живой инструмент управления поведением агента. Если вы решили переехать с pip на poetry или заменить Nginx на Caddy в своих конфигурационных сценариях, файл нужно обновить незамедлительно.

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

При смене стека я рекомендую действовать по следующему алгоритму:

  1. Удалите устаревшие инструкции из секций Build Commands и Test Commands.
  2. Добавьте новые команды для работы с актуальным инструментом.
  3. Проверьте, не остались ли в разделе Style Guidelines упоминания старых библиотек.

Для более глубокого понимания того, как концепция структурирования знаний влияет на работу моделей, можно ознакомиться с материалами Андрея Карпаты, на идеи которых опирается этот подход.

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

Нужно ли добавлять CLAUDE.md в .gitignore?

Нет, этот файл должен быть частью репозитория. Его задача — задать стандарты разработки для всех, кто использует Claude Code в рамках данного проекта. Если вы оставите его только у себя локально, то при работе другого разработчика (или при развёртывании CI/CD с использованием ИИ-агентов) возникнет та самая непредсказуемость, о которой мы говорили выше.

Как CLAUDE.md влияет на безопасность кода?

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

Можно ли использовать один CLAUDE.md для нескольких проектов?

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

Что делать, если Claude Code игнорирует инструкции из файла?

Сначала убедитесь, что файл находится в корневом каталоге проекта и называется именно CLAUDE.md. Если это не помогает, попробуйте упростить формулировки: вместо абстрактных советов используйте прямые императивы, например: «Всегда используй интерфейсы вместо типов для описания объектов». Если проблема сохраняется, проверьте, не перекрывают ли текущие инструкции в сессии чата те правила, которые вы прописали в конфигурационном файле.

Поделиться:TelegramX / TwitterVK