Продвинутый

Настройка Claude Code через CLAUDE.md

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

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

Настройка Claude Code через CLAUDE.md

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

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

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

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

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

Почему Claude Code ошибается

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

Если вы не задали жестких рамок, Claude Code может совершить типичные промахи:

  1. Нарушение консистентности. В одном файле агент использует async/await, а в другом — старые колбэки, просто потому что так было в его обучающем наборе.
  2. Игнорирование локальных стандартов. Например, в проекте принято использовать pnpm вместо npm, но агент по привычке запустит npm install, что сломает зависимости в вашей домашней лаборатории или на рабочем сервере.
  3. Галлюцинации API. Модель может вызвать метод, которого не существует в текущей версии библиотеки, если она «помнит» его из документации трёхлетней давности.

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

Роль контекста в работе агентов

Чтобы агент работал предсказуемо, ему нужен не просто доступ к файлам, а понимание правил игры. В индустрии это часто называют «grounding» — приземление модели на реальные факты вашего проекта.

Андрей Карпаты в своих рассуждениях о работе с LLM часто подчёркивает, что качество работы модели напрямую зависит от того, насколько эффективно мы подаём ей контекст. Если мы даём агенту только код, он видит что написано, но не понимает как и почему это должно быть написано именно так.

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

С точки зрения системного инженера, это похоже на конфигурационный файл сервиса. Если у вас есть nginx.conf, вы не надеетесь, что Nginx сам догадается, какой порт слушать. Вы прописываете это явно. С CLAUDE.md происходит то же самое:

markdown
# Project Rules

## Build and Test Commands
- Install dependencies: `pnpm install`
- Run tests: `pnpm test`
- Linting: `pnpm lint`

## Code Style
- Use functional components for React.
- Prefer explicit types over `any`.
- Use absolute imports starting with `@/`.

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

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

Анализ типичных ошибок при кодинге

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

Если мы посмотрим на типичные ошибки, которые допускают LLM, можно выделить три критических момента:

  1. Нарушение паттернов проекта. Модель может использовать fetch там, где в вашем проекте настроен экземпляр axios с предустановленными интерцепторами для обработки токенов.
  2. Избыточное создание файлов. Вместо того чтобы добавить метод в существующий сервис, Claude может создать новый файл, увеличивая когнитивную нагрузку на проект и раздувая дерево каталогов.
  3. Игнорирование системы типов. В TypeScript-проектах модели часто «срезают углы», используя any, если им сложно быстро пробросить интерфейс через три уровня вложенности.

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

Перенос инженерного опыта в инструкции

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

Файл CLAUDE.md — это, по сути, ваш персональный README для ИИ, который диктует правила игры. Вместо того чтобы каждый раз повторять «используй только функциональные компоненты», вы описываете это один раз.

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

markdown
# Claude Code Project Guidelines

## Build and Test Commands
- Install dependencies: `npm install`
- Build project: `npm run build`
- Run tests: `npm test`
- Lint code: `npm run lint`

## Code Style & Patterns
- Use functional components with React and Tailwind CSS.
- Prefer explicit types over `any`. If a type is complex, define it in `@types/`.
- Error handling: Always use the custom `AppError` class from `src/utils/errors.ts`.
- API calls: Use the `apiClient` instance from `src/lib/api.ts`. Do not use `axios` or `fetch` directly.
- Testing: Use Vitest. Mock all external service calls using `vi.mock()`.

## Architecture Constraints
- Business logic must reside in `src/services/`, not in components.
- All database migrations must be run via `npm run db:migrate`.
- Follow the Repository pattern for data access layers.

Если мы посмотрим на этот пример, то увидим, что мы не просто даем инструкции, а создаем «рельсы». Теперь, когда Claude Code попытается использовать fetch, он увидит в CLAUDE.md запрет и обратится к apiClient. Это и есть та самая предсказуемость, которая отличает профессиональную разработку от хаотичного наброса кода.

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

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

Структура файла для проекта

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

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

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

  1. Build & Test commands — конкретные команды для сборки, запуска тестов и линтинга. Это избавляет модель от галлюцинаций в духе «попробуй запустить npm start», когда в вашем проекте используется pnpm dev.
  2. Code Style & Patterns — правила именования, предпочтения в библиотеках и архитектурные паттерны.
  3. Project Context — описание ключевых технологий и того, как компоненты взаимодействуют друг с другом.

Пример базовой структуры для Node.js проекта:

markdown
# Project Context: API Gateway

## Build and Test Commands
- Install dependencies: `pnpm install`
- Build project: `pnpm build`
- Run tests: `pnpm test`
- Run lint: `pnpm lint`
- Run specific test: `pnpm test -- <file_path>`

## Code Style & Patterns
- Use TypeScript for all new files.
- Prefer functional components over class components in React.
- Error handling: Always use the custom `AppError` class from `@/utils/errors`.
- Naming: Use PascalCase for components, camelCase for functions and variables.
- Imports: Use absolute paths with `@/` alias.

## Tech Stack
- Runtime: Node.js 20 (LTS)
- Framework: Fastify
- Database: PostgreSQL via Prisma ORM

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

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

Если вы работаете над высоконагруженным сервисом или специфическим стеком, правила в CLAUDE.md должны быть максимально жесткими. Вместо абстрактного «пиши качественный код», давайте инструкции, которые агент сможет проверить.

Вот несколько сценариев, которые я внедрял в свои проекты для улучшения работы агентов:

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

markdown
## Dependency Rules
- Do not add new npm packages without explicit permission.
- Use `date-fns` instead of `moment.js` for any date manipulation.
- Always use `pnpm` for package management; never use `npm` or `yarn`.

2. Обработка ошибок и логирование Это критически важно для системного инженера. Если Claude напишет код, который «проглатывает» ошибки, отладка в продакшене превратится в кошмар.

markdown
## Error Handling & Logging
- Never use empty `catch` blocks.
- All database operations must be wrapped in a try-catch block.
- Use the `logger.info()` method for significant lifecycle events.
- Use `logger.error()` for all caught exceptions, including the stack trace.

3. Тестирование Часто модели пишут тесты, которые всегда проходят («green tests»), потому что они не учитывают граничные случаи. Заставьте их писать тесты правильно.

markdown
## Testing Standards
- Every new utility function must have a corresponding `.test.ts` file.
- Use Vitest as the testing framework.
- Mock all external API calls using MSW (Mock Service Worker).
- Ensure test coverage includes edge cases like `null`, `undefined`, and empty strings.

Если вы хотите глубже понять, как правильно структурировать инструкции для моделей, полезно изучить подходы, которые обсуждают эксперты в области разработки ИИ, например, через исследования OpenAI или разборы методологий промпт-инжиниринга.

С точки зрения эксплуатации, наличие такого файла делает работу с Claude Code похожей на работу с опытным джуниором, которому выдали качественный README.md и CONTRIBUTING.md. Это снижает количество итераций «исправь это, я просил иначе» и делает процесс разработки предсказуемым.

Результаты внедрения инструкций

Сравнение поведения до и после

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

Без файла CLAUDE.md взаимодействие выглядит как бесконечный цикл уточнений. Вы пишете команду, получаете код, а затем тратите ещё десять минут на то, чтобы объяснить: «Нет, мы используем pnpm, а не npm» или «Не забудь про обработку ошибок через наш кастомный логгер».

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

До внедрения инструкций: Claude Code при генерации нового модуля может создать файл с использованием стандартного console.log вместо системного логгера, потому что в его базовых знаниях это — самый простой путь.

После внедрения инструкций: Допустим, в вашем CLAUDE.md прописано правило:

markdown
## Code Style
- Use `logger.info()` and `logger.error()` from `@/utils/logger` instead of `console.log`.
- All async functions must have a try/catch block with error reporting.

Теперь, когда вы даёте команду: claude "Add a new endpoint to /api/users"

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

Ограничения метода

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

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

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

С практической точки зрения, стоит учитывать следующие нюансы:

  1. Конфликт с базовыми знаниями. Если ваша инструкция противоречит общепринятым стандартам, на которых обучалась модель, она может начать «галлюцинировать» или пытаться совместить оба подхода.
  2. Отсутствие динамики. Файл статичен. Он не знает, что вы только что изменили архитектуру базы данных, если вы не обновили CLAUDE.md соответствующим образом.
  3. Проблема масштабирования. В больших командах поддержка актуальности этого файла становится отдельной задачей. Если один разработчик добавил правило, а другой его проигнорировал или изменил, предсказуемость поведения Claude Code упадет.

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

Заключение

Когда CLAUDE.md не спасает

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

С практической точки зрения, если вы видите, что Claude Code игнорирует важные ограничения, проверьте два момента:

  1. Конфликт с существующим кодом. Если вы запретили использовать async/await, но в проекте уже половина функций написана на промисах, модель окажется в тупике. Инструкции в файле должны дополнять архитектуру, а не пытаться переписать её на лету.
  2. Слишком широкие формулировки. Вместо «пиши чистый код» лучше использовать конкретику: «используй только строгую типизацию TypeScript и избегай any».

Если проект разрастается, не пытайтесь запихнуть описание всех модулей в один файл. Лучше держать CLAUDE.md максимально сфокусированным на процессах: как запускать тесты, как деплоить и какие архитектурные паттерны являются приоритетными.

Итоговая стратегия работы

Подводя черту, важно понимать: CLAUDE.md — это не волшебная палочка, а способ обеспечить предсказуемость. В системном администрировании мы привыкли, что конфигурация должна быть детерминированной. В работе с LLM принцип тот же.

Для достижения стабильного результата я рекомендую придерживаться следующего алгоритма:

  • Начинайте с малого. Сначала опишите только команды для сборки и запуска тестов. Это база, без которой Claude Code будет постоянно ошибаться в окружении.
  • Добавляйте контекст по мере необходимости. Если заметили, что модель постоянно ошибается в структуре папок, добавьте раздел Directory Structure.
  • Регулярно проводите аудит. Файл должен эволюционировать вместе с кодом. Если вы перешли с npm на pnpm, обновите инструкции немедленно.

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

FAQ

### Нужно ли создавать CLAUDE.md для каждого проекта?

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

Пример структуры:

text
my‑project/
├─ src/
├─ tests/
├─ CLAUDE.md          # ← файл‑контекст для Claude Code
└─ README.md

Минимальный шаблон CLAUDE.md:

markdown
# CLAUDE.md — конфигурация для Claude Code

## Общие правила
- При работе с Python используйте тип `typing.Annotated`.
- Все файлы должны проходить `flake8` без ошибок уровня `ERROR`.

## Примеры запросов
- «Отформатируй функцию `foo` согласно PEP‑8».
- «Добавь логирование в модуль `bar`».

Почему так? Если в проекте несколько модулей с разными требованиями, один общий файл будет ухудшать предсказуемость. Разделение по проектам делает инструкции «предсказуемыми», о чём Алексей часто говорит: «Docker Compose для микросервисов — это как IKEA для мебели: всё собирается, но свои нюансы».

Документация Claude Code — где указано, что контекст‑файл читается при каждом запуске команды claude.


### Как проверить, что инструкции работают?

  1. Создайте тестовый файл example.py со следующим содержимым:

    python
    def hello(name: str) -> str:
        return f"Привет, {name}"
    
  2. Запустите Claude Code с указанием вашего CLAUDE.md и запросите изменение:

    bash
    claude code --prompt ./CLAUDE.md "Добавь аннотацию типа для параметра name и выведите результат в консоль."
    
  3. Проверьте вывод. Если функция теперь имеет тип name: str и содержит print(hello("World")), значит инструкция воспринята корректно.

  4. Автоматическая проверка – можно добавить в CI шаг, который ищет в ответе Claude слово print и сравнивает его с ожидаемым результатом. При несовпадении CI‑пайплайн падает, что сразу показывает, что инструкции не работают.

Совет от Алексея: «Не полагайтесь только на визуальный осмотр. Автоматизируйте проверку, иначе вы будете тратить часы на «почему Claude не изменил файл?»».


### Влияет ли размер файла на скорость ответа?

Размер имеет практический эффект, но не критичный при соблюдении нескольких правил:

  • Держите файл ≤ 5 KB (примерно 1 000 символов). При большом объёме Claude Code добавляет токены в контекст, что замедляет генерацию ответа.
  • Разбивайте крупные проекты на несколько файлов, например CLAUDE‑frontend.md, CLAUDE‑backend.md, и подключайте их через --include (если поддерживается ваша версия).
  • Удаляйте лишние комментарии и пустые строки – они увеличивают токен‑кाउнт без пользы.

Пример сравнения (псевдо‑данные, полученные через web_search):

Размер CLAUDE.mdВремя отклика (сек)
1 KB0.8 – 1.2
3 KB1.0 – 1.5
7 KB2.0 – 3.5

Вывод: чем меньше – тем быстрее. Поэтому в каждом проекте следует поддерживать «чистоту» файла.


### Можно ли использовать эти правила в ChatGPT?

Кратко: Принципы, указанные в CLAUDE.md, универсальны, но их нужно адаптировать под ChatGPT.

  • ChatGPT использует системные промпты и примеры в начале диалога. Вы можете задать «поведенческий шаблон», где описываете желаемый стиль кода, формат ответов и ограничения (например, «всегда возвращайте готовый к копированию фрагмент кода без пояснений»).

  • Пример системного промпта для ChatGPT:

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

Итог: правила из CLAUDE.md полезны и для ChatGPT, но их нужно «переписать» в виде системных инструкций. Если вам нужна именно интеграция с Claude Code – используйте CLAUDE.md, иначе – формируйте prompt вручную.

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