Настройка CLAUDE.md для Claude Code по методу Карпати

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

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

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

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

Типичные ошибки LLM при написании кода

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

Во-первых, это нарушение консистентности. Допустим, в вашем проекте принято использовать pnpm для управления зависимостями и vitest для тестов. Агент, не имея чётких указаний, может внезапно запустить npm install или попытаться написать тесты на jest. Это не просто лишние действия — это засорение рабочей среды и потенциальные конфликты в lock-файлах.

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

Пример типичного «разброда» в командах, который может спровоцировать агент:

bash
# Агент пытается использовать npm, хотя в проекте только pnpm
npm install lodash

# Или пытается запустить тесты через yarn, ломая кэш
yarn test

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

Почему стандартных промптов недостаточно

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

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

Стандартный промпт — это попытка договориться на словах. Но для предсказуемого результата нам нужен «контракт».

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

Вместо того чтобы каждый раз напоминать: «Используй только async/await, не используй промисы через .then()», мы должны внедрить это правило в файл, который Claude Code считывает автоматически при инициализации. Именно здесь на сцену выходит CLAUDE.md. Этот файл служит не просто справкой, а набором жестких ограничений и стандартов, которые делают поведение агента управляемым.

Роль файла CLAUDE.md в рабочем процессе

Принцип работы контекстного файла

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

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

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

Пример минимального, но эффективного содержимого CLAUDE.md для проекта на Python:

markdown
# Project Context: My-Awesome-App

## Build and Test Commands
- Install dependencies: `pnpm install`
- Run tests: `pytest tests/`
- Linting: `ruff check .`

## Code Style Guidelines
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer composition over inheritance.

Как инструкции влияют на поведение Claude Code

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

Инструкции в CLAUDE.md влияют на три ключевых аспекта работы Claude Code:

Выбор инструментов (Tool Use). Если в файле указано, что сборка проекта происходит через make build, агент не будет пытаться искать docker-compose или запускать скрипты вручную. Это экономит токены и время.
Соблюдение архитектурных паттернов. Вы можете явно запретить использование определённых библиотек. Например, если вы переходите на FastAPI и хотите избавиться от старого Flask, это стоит зафиксировать.
Формат вывода. Вы можете задать правила именования файлов или структуру коммитов.

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

Если мы посмотрим на процесс отладки, то наличие CLAUDE.md превращает Claude Code из «умного чат-бота» в полноценного участника команды. Допустим, вы просите исправить ошибку:

bash
claude "fix the bug in auth service"

Без контекстного файла агент может создать новый файл с тестом, который не вписывается в вашу структуру. С правильно настроенным CLAUDE.md, где прописано Tests location: /tests/unit, он пойдёт именно туда, используя существующий стек. Это и обеспечивает ту самую предсказуемость, которая критически важна при работе с автоматизированными инструментами.

Практическое применение навыков Карпати

Анализ структуры репозитория

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

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

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

markdown
## Project Structure

- `src/core/` — основная бизнес-логика и доменные модели.
- `src/api/` — эндпоинты и контроллеры.
- `tests/unit/` — юнит-тесты (используется Vitest).
- `scripts/` — вспомогательные bash-скрипты для автоматизации.
- `docs/` — техническая документация проекта.

To find specific logic, look into `src/core/`. 
To run tests, use `npm test`.

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

Установка правил кодинга и стандартов проекта

Самая большая проблема при работе с ИИ-агентами — это «дрейф стиля». Вы можете настроить линтеры, но Claude Code всё равно может предложить решение, которое технически верно, но архитектурно чуждо вашему проекту. Например, использовать async/await там, где у вас приняты промисы, или внедрять новые зависимости без согласования.

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

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

markdown
## Coding Standards

### Style Guidelines
- Use TypeScript for all new files; avoid `any` at all costs.
- Prefer functional programming patterns over OOP where possible.
- All exported functions must have JSDoc comments explaining parameters and return values.
- Use arrow functions for component definitions.

### Architecture Rules
- Business logic must reside in `src/core/`, never in `src/api/`.
- Dependency injection is required for all service classes.
- Error handling: always use the custom `AppError` class from `@/errors`.

### Common Commands
- Build project: `npm run build`
- Run linting: `npm run lint`
- Execute migrations: `npx prisma migrate dev`

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

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

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

Повышение точности генерации

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

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

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

Пример секции в CLAUDE.md для контроля стиля кода:

markdown
## Code Style & Patterns

- Use functional programming patterns where possible.
- Error Handling: Always wrap asynchronous calls in a custom `AppError` class.
- Logging: Use the internal `logger.info()` method instead of `console.log()`.
- Type Safety: Strict TypeScript mode is mandatory; no `any` types allowed.

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

Снижение количества итераций исправления ошибок

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

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

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

Без CLAUDE.md:

Вы просите написать тест.
Claude генерирует тест под jest.
Вы запускаете npm test и получаете ошибку.
Вы пишете: «У нас используется vitest, переделай».
Claude переделывает, но ошибается в импортах.

С CLAUDE.md:

Вы просите написать тест.
Claude считывает секцию Testing Workflow из CLAUDE.md.
Claude сразу генерирует код под vitest и запускает его командой npx vitest run.

Пример блока для автоматизации рабочих процессов в CLAUDE.md:

markdown
## Development Workflow

### Testing
- Run tests using: `npm run test:unit`
- Always ensure coverage is above 80% before finalizing a task.

### Build & Deploy
- Build command: `docker compose build`
- Deployment is handled via Ansible; do not attempt manual SSH deployment.

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

Заключение

Итоги внедрения

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

С практической точки зрения, метод Андрея Карпати работает за счёт снижения когнитивной нагрузки на LLM. Вместо того чтобы каждый раз «угадывать», как принято в вашем репозитории, Claude Code обращается к единственному источнику истины.

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

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

Избыточная детализация. Если вы попытаетесь описать в файле каждый чих, вы получите огромный контекст, который будет «съедать» токены и размывать внимание модели. Правила должны быть лаконичными.
Конфликт с существующей документацией. Если в CLAUDE.md написано использовать pytest, а в README.md указан unittest, возникнет неопределённость. Держите документацию в синхронизации.
Отсутствие автоматизации. Файл — это лишь декларация. Если вы прописали в CLAUDE.md, что тесты должны запускаться через npm test, но при этом в package.json этот скрипт сломан, Claude Code будет совершать ошибки, несмотря на инструкции.

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

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

markdown
# Project Rules

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

## Code Style
- Use functional options pattern for constructors.
- Prefer explicit error handling over panics.
- Follow standard Go project layout.

## Architecture
- Services must be stateless.
- Database migrations are located in /migrations.

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

FAQ

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

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

Если у вас есть общие стандарты (например, использование определённого стиля именования или запрет на конкретные библиотеки), их можно вынести в глобальные настройки окружения, но проектные нюансы лучше держать локально. Например, в одном проекте вы используете pnpm, а в другом — npm. Без указания этого в CLAUDE.md модель может начать предлагать команды, которые просто не сработают в вашем окружении.

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

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

Если в вашем CLAUDE.md прописано строгое правило, например:

markdown
## Code Style
- Use functional components for React.
- Always use TypeScript interfaces instead of types.

То для проверки выполните команду в терминале Claude Code: Create a simple button component.

Если модель создаст компонент с использованием type ButtonProps = ... вместо interface ButtonProps, значит, инструкции либо не подтянулись, либо они сформулированы слишком размыто. Если же вы видите interface, значит, механизм работает.

Также можно проверить, видит ли модель файл, запросив её текущий контекст: What are the coding standards defined in this project?

Влияет ли размер файла на скорость работы Claude Code?

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

Увеличится задержка (latency) перед началом генерации ответа.
Модель может начать игнорировать инструкции в середине или конце файла из-за эффекта «потери в середине» (lost in the middle).

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

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

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

Нужно ли добавлять в CLAUDE.md описание всех существующих файлов проекта?

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

Как понять, что правила в CLAUDE.md работают эффективно?

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

Можно ли использовать CLAUDE.md для обучения агента новым библиотекам?

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

Где лучше хранить CLAUDE.md в структуре репозитория?

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