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

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

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

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

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

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

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

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

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

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

Пример типичного «кривого» решения, когда модель не знает о наличии вспомогательных утилит:

typescript
// Claude Code может сгенерировать это, не зная, что у вас есть @/utils/date-formatter
// Вместо использования вашего стандарта, она пишет нативный JS, который не проходит линтер
const formatDate = (date: Date) => {
  return date.toLocaleDateString('ru-RU', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  });
};

Почему контекст решает всё

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

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

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

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

Build & Test commands: точные команды, которые модель должна запускать для проверки себя.
Code Style: конкретные правила (например, «используй только функциональные компоненты»).
Architecture patterns: описание того, как данные должны перемещаться по системе.

Без этого файла вы работаете с «умным, но неопытным стажёром». С файлом CLAUDE.md вы работаете с инженером, который знает ваш стек и не задаёт глупых вопросов.

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

Суть подхода к структурированию инструкций

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

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

С практической точки зрения, CLAUDE.md должен содержать три критических компонента:

Build & Test Commands: Точные команды, которые модель должна использовать для проверки своего кода.
Code Style & Patterns: Правила именования, предпочтительные библиотеки и архитектурные паттерны.
Project Context: Краткое описание того, что делает проект и какие технологии являются «золотым стандартом».

Если мы посмотрим на структуру файла, он должен выглядеть примерно так:

markdown
# Project Context: Microservice 'Piatachok'

This is a Python-based service for processing telemetry from Proxmox nodes.

## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest tests/`
- Linting: `ruff check .`
- Build docker image: `docker build -t piatachok:latest .`

## Code Style Guidelines
- Use type hints for all function signatures.
- Prefer `asyncio` for I/O operations.
- Error handling: Always wrap network calls in custom exception classes defined in `errors.py`.
- Logging: Use `structlog` with JSON formatting.
- Naming: Use snake_case for variables and functions, PascalCase for classes.

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

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

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

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

Во-вторых, нарушение архитектурной целостности. Без четких инструкций модель может начать внедрять решения, которые противоречат вашему подходу. Например, вы используете FastAPI и строго придерживаетесь Dependency Injection, а Claude Code вносит в проект старый добрый глобальный объект конфигурации, потому что так «проще».

В-третьих, «раздувание» кода (Code Bloat). Модели склонны писать избыточные конструкции, если им не задать ограничение на лаконичность.

Чтобы минимизировать эти риски, я рекомендую добавить в раздел правил (Style Guidelines) блок, запрещающий определенные действия. Это работает даже лучше, чем прямые указания.

Пример расширения конфига для борьбы с избыточностью:

markdown
## Anti-Patterns (Do NOT do)
- Do not use `os.path`; always use `pathlib`.
- Do not implement manual retry logic; use the `tenacity` library.
- Do not add new dependencies without asking; check `pyproject.toml` first.
- Avoid large functions; if a function exceeds 50 lines, refactor it into smaller components.

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

Создание и применение файла CLAUDE.md

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

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

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

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

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

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

markdown
# CLAUDE.md — Project Guidelines

## Project Context
This is a microservice for processing telemetry data using Go and PostgreSQL.
Architecture: Hexagonal (Ports and Adapters).

## Code Style & Patterns
- Use functional options pattern for constructors.
- Error handling: wrap errors with context using `fmt.Errorf("...: %w", err)`.
- Naming: interfaces should end with 'er' (e.g., 'Repository', 'Store').
- No global state; use dependency injection via constructors.

## Build & Test Commands
- Build: `go build -o bin/app ./cmd/server`
- Test: `go test ./... -v`
- Lint: `golangci-lint run`
- Migration: `migrate -path ./migrations -database "$DB_URL" up`

Обратите внимание на раздел команд. Это критически важно. Вместо того чтобы Claude Code пытался угадать, как запустить тесты в вашем специфичном окружении, вы даёте ему готовый рецепт. Это исключает ситуацию, когда агент запускает npm test, в то время как ваш проект требует yarn test.

Примеры правил для соблюдения архитектуры проекта

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

Чтобы этого избежать, нужно прописывать правила на уровне ограничений. Если вы используете, например, Clean Architecture или Hexagonal, это должно быть зафиксировано.

Вот пример того, как можно описать строгие правила для проекта на Python с использованием FastAPI:

markdown
## Architectural Constraints
- Layered Architecture: strictly separate `domain`, `use_cases`, and `infrastructure` layers.
- Domain models must be pure Python classes (dataclasses) with no dependencies on external libraries.
- Infrastructure layer (DB, API clients) must implement interfaces defined in the domain layer.
- Dependency Injection: use `dependency_injector` library for all service wiring.

## Strict Prohibitions
- DO NOT import `sqlalchemy` or `pydantic` inside the `domain/` directory.
- DO NOT use `print()` for logging; always use the `logger` instance from `app.core.logging`.
- DO NOT add new dependencies to `pyproject.toml` without explicit confirmation.

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

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

Практическое внедрение в рабочий процесс

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

Как файл влияет на точность выполнения команд

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

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

Пример структуры раздела с командами в CLAUDE.md:

markdown
## Build and Test Commands

- Build the project: `docker compose build`
- Run all tests: `docker compose exec app pytest`
- Run a specific test: `docker compose exec app pytest tests/test_module.py`
- Linting: `docker compose exec app ruff check .`
- Database migrations: `docker compose exec app alembic upgrade head`

Когда эти инструкции прописаны, Claude Code при запросе «проверь, всё ли работает» не будет пытаться выполнить npm test или go test, если ваш проект развёрнут в Docker. Это делает поведение агента линейным и ожидаемым.

Поддержание актуальности инструкций

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

Я придерживаюсь правила: любое изменение в пайплайне разработки или в способе развёртывания должно сопровождаться правкой CLAUDE.md. Это похоже на ведение документации в Ansible: если вы изменили роль, вы должны обновить описание переменных, иначе автоматизация сломается.

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

Context: краткое описание архитектуры (например, «Backend на FastAPI, БД в PostgreSQL»).
Style Guide: правила именования и предпочтения в библиотеках (например, «используй только асинхронные методы async/await»).
Commands: те самые команды для сборки и тестирования, о которых мы говорили выше.

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

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

Заключение

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

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

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

Снижение когнитивной нагрузки: вам не нужно каждый раз объяснять ИИ, как запускать тесты или где лежат конфиги.
Стабильность кода: правила линтинга и стандарты именования, прописанные в файле, работают как невидимый guardrail.
Быстрый онбординг: новый разработчик (или вы сами через полгода) сразу поймёт структуру проекта, просто взглянув на документацию в корне.

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

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

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

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

Чек-лист для проверки конфигурации

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

Команды запуска: Указаны ли конкретные команды для сборки, тестирования и линтинга?
Стиль кода: Есть ли четкие инструкции по использованию (например, «используй только функциональные компоненты» или «предпочитай Type Hints»)?
Архитектурные паттерны: Описано ли, где лежат бизнес-логика, а где — интерфейсы?
Обработка ошибок: Указано ли, как именно проект должен обрабатывать исключения?

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

Для поддержания порядка в проекте я рекомендую всегда держать актуальным список команд. Если вы добавили новый скрипт в package.json или Makefile, обновите CLAUDE.md немедленно. Это занимает минуту, но экономит часы отладки в будущем.

FAQ

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

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

Если у вас есть общие стандарты (например, использование определённого стиля именования или запрет на использование конкретных библиотек), лучше создать один эталонный файл и копировать его в новые репозитории. Это избавляет от необходимости каждый раз объяснять ИИ, что в этом проекте мы используем pnpm вместо npm или что тесты запускаются через pytest, а не unittest.

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

yaml
- name: Copy CLAUDE.md to new project
  template:
    src: templates/CLAUDE.md.j2
    dest: "{{ project_path }}/CLAUDE.md"

Как этот файл помогает избежать ошибок в логике?

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

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

Пример секции в CLAUDE.md, которая снижает риск логических ошибок:

markdown
## Logic & Error Handling
- Always use the `Result` pattern for service layer methods.
- Database transactions must be managed via the `UnitOfWork` class.
- Never use bare `except:`; always catch specific exceptions defined in `exceptions.py`.

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

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

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

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

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

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

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

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

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

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

Как не перегрузить файл лишними инструкциями?

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

Поможет ли CLAUDE.md исправить ошибки в уже написанном коде?

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