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

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

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

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

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

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

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

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

Нарушение локальных конвенций. Модель может предложить использовать async/await там, где в проекте приняты промисы, или импортировать модули через абсолютные пути, хотя вы используете относительные.
Галлюцинации в командах окружения. Агент может попытаться запустить тесты командой npm test, хотя в вашем проекте настроен vitest с особыми флагами.
Контекстный дрейф. В процессе долгой сессии агент начинает забывать о специфических ограничениях, например, о том, что база данных доступна только через определённый Docker-контейнер.

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

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

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

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

Методика, которую часто обсуждают в контексте обучения и работы с моделями (включая идеи, которые транслирует Андрей Карпатый), подразумевает, что качество вывода напрямую зависит от качества предоставленного контекста. Для Claude Code таким инструментом становится файл CLAUDE.md.

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

bash
# Пример того, как агент может ошибиться без контекста
# Он может попытаться установить пакет напрямую в систему, а не в контейнер
pip install requests 

# А с правильно настроенным контекстом в CLAUDE.md он выполнит:
docker exec -it dev_container pip install requests

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

Методика Андрея Карпаты для улучшения ответов

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

Когда мы работаем с Claude Code или любым другим CLI-инструментом на базе LLM, главная проблема — это не отсутствие знаний у модели, а потеря контекста и «галлюцинации» в архитектуре. Если вы просто просите «добавь эндпоинт в API», модель может создать новый файл, нарушив существующую структуру проекта, или использовать библиотеку, которая у вас не установлена.

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

Нарушение консистентности. Модель пишет код в одном стиле (например, использует async/await), а в остальном проекте принят другой подход или используются специфические обёртки для обработки ошибок.
Игнорирование локального окружения. Claude может предложить команду npm install, хотя в вашем проекте используется pnpm, или попытаться запустить тесты через pytest, когда у вас настроен go test.
Избыточность и «раздувание» кода. Без указания на предпочтение лаконичности, LLM склонна генерировать многословные функции, которые сложно поддерживать.

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

Принципы формирования инструкций

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

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

Во-первых, команды должны быть максимально конкретными. Вместо описания «как тестировать», мы даём готовые строки, которые агент может просто скопировать и выполнить.

Пример структуры CLAUDE.md для проекта на Python:

markdown
# Claude Code Project Guidelines

## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run linter: `flake8 .`
- Run tests: `pytest tests/`
- Run application: `python main.py`

## Code Style Guidelines
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer list comprehensions over explicit loops where readable.
- Error handling: Use custom exception classes defined in `exceptions.py`.
- Documentation: Use Google-style docstrings.

## Architecture Patterns
- All API endpoints must be defined in `app/api/routes.py`.
- Use SQLAlchemy for all database interactions; avoid raw SQL.
- Dependency injection is required for service layers.

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

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

Практическое применение файла CLAUDE.md

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

Чтобы Claude Code перестал гадать, как именно вы привыкли писать код, файл CLAUDE.md должен работать как техническое задание, которое не меняется. Если мы посмотрим на подход Андрея Карпаты к обучению моделей, то увидим общую закономерность: чем меньше неопределённости в контексте, тем выше предсказуемость результата. В случае с LLM — это ваш главный инструмент.

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

Build & Test Commands: Конкретные команды для сборки, запуска тестов и линтинга. Никаких «используйте npm test» — только точные инструкции, например, npm run test:unit.
Code Style & Patterns: Правила именования, предпочтения в архитектуре (например, «используем только функциональные компоненты») и запрещённые приёмы.
Project Context: Краткое описание того, что делает проект и где лежат ключевые модули.

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

Примеры конфигурации для проекта

Поскольку каждый проект уникален, я подготовил два шаблона. Первый — для типичного веб-приложения на TypeScript, второй — для системного проекта на Python.

Пример для Node.js / TypeScript проекта

В веб-разработке часто возникает проблема, когда модель предлагает использовать устаревшие методы или забывает про строгую типизацию. Чтобы этого избежать, настройте файл следующим образом:

markdown
# CLAUDE.md — Project Guidelines

## Build & Test Commands
- Install dependencies: `npm install`
- Build project: `npm run build`
- Run tests: `npm test`
- Linting: `npm run lint`
- Type check: `npm run type-check`

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

## Project Structure
- `/src/components`: UI components (atomic design).
- `/src/hooks`: Custom React hooks.
- `/src/services`: API interaction logic.
- `/src/types`: Global TypeScript definitions.

Пример для Python / FastAPI проекта

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

markdown
# CLAUDE.md — Backend Guidelines

## Build & Test Commands
- Install: `pip install -r requirements.txt`
- Run server: `uvicorn main:app --reload`
- Run tests: `pytest`
- Lint: `flake8 .`
- Format: `black .`

## Code Style
- Follow PEP 8 strictly.
- Use type hints for all function signatures (Pydantic models for request/response).
- Use `async/await` for all database and I/O operations.
- Dependency Injection: Use FastAPI's `Depends` for all service layers.
- Documentation: Every public function must have a Google-style docstring.

## Project Context
- This is a FastAPI microservice for processing telemetry data.
- Database: PostgreSQL via SQLAlchemy (async driver).
- Core logic resides in `/app/services`.

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

Применение CLAUDE.md делает работу с кодом предсказуемой. Вы тратите меньше времени на исправление мелких ошибок в стиле и больше — на проектирование архитектуры. Это и есть переход от «написания кода на коленке» к системному подходу.

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

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

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

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

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

Пример того, как секция правил в CLAUDE.md предотвращает ошибки в типизации:

markdown
## Code Style & Patterns
- Use TypeScript for all new files; avoid `any` at all costs.
- Follow the Repository pattern for database access.
- Error handling: always wrap async calls in try/catch blocks and use the custom `AppError` class.
- Imports: use absolute paths starting with `@/`.

Теперь, когда вы попросите: claude "Add a new user registration endpoint"

Модель не просто набросает код, а будет вынуждена использовать @/ для импортов и обернуть логику в try/catch с использованием AppError. Предсказуемость кода возрастает, потому что ограничения заданы на уровне системного контекста, а не случайного диалога.

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

Второй важный аспект — это сокращение цикла «запрос — ошибка — исправление». В инженерной практике это называется сокращением Time-to-Feedback. Без файла инструкций значительная часть времени уходит на то, чтобы объяснить Claude, как запускать тесты или где лежат логи.

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

Вместо того чтобы каждый раз писать: claude "Run the tests for the auth module using vitest"

Вы просто пишете: claude "Test the auth module"

Для этого в CLAUDE.md должна быть настроена секция Build & Test Commands:

markdown
## Build & Test Commands
- Install dependencies: `npm install`
- Run development server: `npm run dev`
- Run unit tests: `npm test -- <path_to_file>`
- Run linting: `npm run lint`
- Build project: `npm run build`

Когда Claude Code видит этот блок, он автоматически подтягивает нужные команды для выполнения задач. Это избавляет от ситуации, когда модель пытается запустить pytest в проекте на Jest.

С точки зрения процесса, это превращает Claude из «умного собеседника» в полноценного участника CI/CD цикла внутри вашей локальной среды. Вы тратите меньше времени на проверку того, правильно ли модель поняла окружение, и больше — на проектирование логики.

Заключение

Итоги применения CLAUDE.md

Во-первых, файл CLAUDE.md служит как единый контекст для модели, что снижает вероятность «галлюцинаций» и повышает точность генерируемого кода. Пример типичного содержимого:

markdown
# CLAUDE.md
## Описание задачи
Необходимо реализовать скрипт, который автоматически резервирует базу данных PostgreSQL и отправляет архив в S3.

## Ограничения
- Использовать только официальный клиент `awscli`.
- Не допускать прямого доступа к портам базы изнутри контейнера.
- Логировать все операции в `journald`.

## Пример входных данных
{
  "db_name": "analytics",
  "backup_dir": "/backups",
  "s3_bucket": "my-backups"
}

Справочная ссылка на официальную документацию awscli.

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

Типичные ошибки LLM и как их исправлять

Недостаточная конкретика – модель генерирует команды с произвольными путями.
Решение: указывайте точные пути и имена контейнеров. Пример проверочной команды:
```
bash
docker exec my_container ls -l /backups
```
Отсутствие примеров – без демонстрации ожидаемого вывода модель может выбрать неверный формат.
Решение: добавляйте в CLAUDE.md пример вывода команды:
```
bash
aws s3 cp /backups/analytics_2024-10-01.tar.gz s3://my-backups/
```

Неявные зависимости – модель может забыть установить требуемый пакет.
Решение: явно указывайте зависимости в блоке ## Ограничения:

markdown
- Пакет `awscli` версии 2.x должен быть установлен.

Если при генерации кода появляются ошибки «command not found», проверьте, что все зависимости перечислены в CLAUDE.md и тестируйте команды вручную перед автоматизацией.

Практические рекомендации по поддержке CLAUDE.md

Версионирование – храните файл в Git, делайте коммиты при изменении требований. Это позволяет откатиться к проверенной версии, если новая конфигурация приводит к регрессии.
CI‑проверка – добавьте шаг в pipeline, который запускает docker run --rm -v $(pwd)/CLAUDE.md:/work/CLAUDE.md my_image cat /work/CLAUDE.md и проверяет, что файл не пустой и содержит секцию ## Описание задачи.

Тесты на практике – после генерации кода выполните его в изолированном контейнере и убедитесь, что все шаги из CLAUDE.md выполнились без ошибок. Пример скрипта:

bash
# test_claude.sh
set -euo pipefail
docker build -t claude-test .
docker run --rm claude-test bash -c 'source /work/CLAUDE.md && ./generate.sh'

Следуя этим рекомендациям, вы сможете максимально использовать возможности Claude Code, минимизировать типичные ошибки LLM и обеспечить предсказуемость работы ваших скриптов.

FAQ

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

Да, если вы хотите добиться предсказуемости. Каждый проект имеет свой контекст: разные стандарты именования, специфические способы запуска тестов или нюансы архитектуры. Если вы используете один и тот же файл для микросервиса на Go и для фронтенда на React, Claude начнет путаться в командах и стиле кода.

С практической точки зрения, лучше всего держать CLAUDE.md в корне репозитория. Это позволяет Claude Code сразу подхватить инструкции при инициализации сессии в конкретной директории.

Как CLAUDE.md влияет на стоимость токенов?

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

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

markdown
# CLAUDE.md (оптимизированный вариант)

## Build & Test
- Build: `make build`
- Test: `go test ./...`
- Lint: `golangci-lint run`

## Style Guide
- Use functional options pattern for constructors.
- Error handling: wrap errors with context using `fmt.Errorf`.

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

Можно ли использовать этот подход с другими моделями?

Методика, вдохновленная подходом Андрея Карпаты, универсальна. Хотя файл называется CLAUDE.md специально для инструмента Claude Code, сама идея предоставления модели «карты проекта» работает с любой продвинутой LLM.

Если вы работаете через интерфейс ChatGPT или используете другие CLI-инструменты, вы можете назвать файл иначе, например .cursorrules (для Cursor) или просто PROJECT_CONTEXT.md. Главное — подавать этот файл в системный промпт или прикреплять его к чату в начале сессии.

Где хранить файл конфигурации?

Единственно верное место — корень вашего проекта. Это стандарт де-факто для инструментов, работающих с контекстом репозитория.

Если вы работаете в монорепозитории, у вас есть два пути:

Один общий файл в корне: подходит для небольших проектов, где все сервисы пишутся на одном стеке.
Раздельные файлы в поддиректориях: если у вас в одном репозитории лежат и API на Python, и мобильное приложение, создайте services/api/CLAUDE.md и services/mobile/CLAUDE.md.

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

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

Где именно нужно размещать файл CLAUDE.md?

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

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

Да, это одна из самых полезных функций файла. Вместо того чтобы каждый раз объяснять агенту, как запустить линтер или тесты, пропишите эти команды в секции Build/Test. Это обеспечит предсказуемость: агент будет использовать именно ваш vitest или make test вместо стандартных команд, которые он привык видеть в обучающей выборке.

Не замедлит ли наличие этого файла работу модели?

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

Как понять, что инструкции в файле работают эффективно?

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

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

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