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

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

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

Зачем Claude Code нужны инструкции

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

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

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

Если мы посмотрим на типичный процесс, то без инструкций мы получаем следующие риски:

1. Нарушение конвенций: ИИ использует double quotes там, где в проекте приняты single quotes.
2. Раздувание зависимостей: вместо использования существующего в проекте utils.py, модель предлагает установить новый пакет.
3. Ошибки в командах: модель может предложить npm install, когда ваш проект работает на pnpm.

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

Роль контекстного файла CLAUDE.md

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

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

С точки зрения структуры, этот файл должен содержать три ключевых блока:

1. Build & Test commands: точные команды для сборки и запуска тестов.
2. Code style guidelines: правила именования, предпочтения в библиотеках и архитектурные паттерны.
3. Project context: краткое описание того, что именно делает этот сервис.

Пример базового CLAUDE.md для небольшого проекта на Python:

markdownКопировать
# Claude Code Project Instructions

## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest tests/`
- Linting: `flake8 .`

## Code Style Guidelines
- Use type hints for all function signatures.
- Prefer Pydantic v2 models for data validation.
- Follow PEP 8 strictly.
- Use asynchronous patterns (async/await) for all I/O operations.
- Error handling: Always use custom exceptions defined in `app/exceptions.py`.

## Project Structure
- `app/` contains the core logic.
- `tests/` contains unit and integration tests.
- `migrations/` contains Alembic database migrations.

Когда этот файл находится в корне репозитория, Claude Code перестаёт гадать. Вместо того чтобы предлагать запуск тестов через python -m unittest, он сразу использует pytest, потому что это явно прописано в инструкции. Это превращает ИИ из непредсказуемого помощника в дисциплинированного участника команды, который соблюдает ваши стандарты.

Методология Андрея Карпатого

Методология Андрея Карпатого

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

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

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

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

1. Нарушение конвенций проекта. Модель может использовать axios там, где в вашем проекте настроен fetch, или предлагать arrow functions, если ваш линтер требует классических объявлений. Это приводит к тому, что после каждого «исправления» вам приходится вручную запускать проверку кода.
2. Неправильный выбор инструментов сборки. Агент может попытаться запустить тесты через npm test, хотя в вашем окружении используется pnpm или специфический скрипт в Makefile.
3. Игнорирование структуры каталогов. Нейросеть часто пытается создать новый файл в корне, вместо того чтобы положить его в /src/components/ или /lib/, что ломает импорты и логику сборки.

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

Как структурировать правила для агента

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

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

Пример грамотно структурированного CLAUDE.md для Node.js проекта:

markdownКопировать
# Project Context: API Gateway

## Tech Stack
- Runtime: Node.js v20 (LTS)
- Framework: Fastify
- Database: PostgreSQL via Prisma
- Testing: Vitest

## Code Style & Patterns
- Use TypeScript for all new files.
- Prefer functional programming patterns; avoid classes unless necessary.
- Error handling: Always use custom error classes from `@/errors`.
- Naming: kebab-case for files, PascalCase for components, camelCase for functions.
- Imports: Use absolute paths starting with `@/`.

## Build & Test Commands
- Install dependencies: `pnpm install`
- Run development server: `pnpm dev`
- Run all tests: `pnpm test`
- Run linting: `pnpm lint`
- Run type check: `pnpm typecheck`

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

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

Практическое применение репозитория

Разбор содержимого файла CLAUDE.md

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

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

Пример содержимого для типичного проекта на Python:

markdownКопировать
# CLAUDE.md — Project Guidelines

## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest tests/`
- Run specific test: `pytest tests/test_module.py`
- Linting: `flake8 .`

## Code Style and Patterns
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Error handling: Use custom exceptions defined in `src/exceptions.py`.
- Async: Prefer `asyncio` for I/O bound operations.

## Project Structure
- `src/` contains the core logic.
- `tests/` mirrors the `src/` directory structure.
- `docs/` contains architectural decision records (ADR).

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

Интеграция инструкций в рабочий процесс

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

Во-первых, при добавлении нового технологического стека (например, если вы решили внедрить Redis для кэширования), первым делом обновите CLAUDE.md. Добавьте туда правила работы с подключениями или специфические команды для очистки кэша.

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

markdownКопировать
## Database Migrations
- Always run `alembic revision --autogenerate` before committing.
- Never delete migration files; use `alembic downgrade` if necessary.

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

1. Вы инициализируете Claude Code в корне репозитория.
2. Агент при старте сканирует окружение и находит CLAUDE.md.
3. Все последующие команды (например, claude "add a new endpoint to the API") выполняются с учётом заданных паттернов.

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

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

Результаты и ограничения

Когда инструкции работают эффективно

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

Инструкции работают лучше всего в трёх сценариях:

1. Соблюдение архитектурных стандартов. Если в вашем проекте принято использовать определённую структуру директорий или специфические паттерны проектирования, пропишите их. Это исключает ситуации, когда Claude предлагает создать новый модуль там, где по логике проекта должен быть сервис в папке /internal/services.
2. Стандартизация команд сборки и тестирования. Это, пожалуй, самый полезный кейс. Вместо того чтобы каждый раз объяснять, как запустить тесты или собрать контейнер, вы фиксируете это в секции Build and Test Commands.
3. Управление стилем кода и линтерами. Если вы используете специфические правила (например, строгий запрет на использование определенных библиотек или требование к именованию переменных), CLAUDE.md поможет модели генерировать код, который сразу проходит проверку CI/CD.

Пример эффективной секции команд в файле:

markdownКопировать
## Build and Test Commands

- Build the project: `make build`
- Run all tests: `go test ./...`
- Run specific test: `go test -run <TestName>`
- Linting: `golangci-lint run`

Когда такие команды зафиксированы, Claude Code не будет пытаться угадать, есть ли у вас npm run test или pytest, а сразу применит проверенный вами метод. Это и обеспечивает ту самую предсказуемость, к которой мы стремимся при настройке любой инфраструктуры.

Почему не стоит перегружать файл правилами

Здесь кроется главная ловушка. Глядя на то, как Андрей Карпатый рассуждает о важности качественного контекста, легко поддаться искушению превратить CLAUDE.md в бесконечную простыню текста. Но избыточность — враг эффективности.

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

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

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

Вместо попытки описать всё, сосредоточьтесь на «узких местах». Если вы видите, что Claude раз за разом ошибается в одном и том же месте — например, неправильно использует systemd unit-файлы для ваших сервисов, — добавьте именно это уточнение:

markdownКопировать
## Code Style & Patterns

- Always use absolute paths in systemd unit files.
- Use `Restart=on-failure` for all service definitions.
- Avoid using `User=root`; always specify a non-privileged user.

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

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

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

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

Чем CLAUDE.md отличается от обычного README.md?

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

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

Я не рекомендую копировать один и тот же файл во все репозитории, так как это нарушает принцип специфичности контекста. Каждый проект имеет свои особенности: в одном вы используете pnpm, в другом — npm, в одном принят snake_case, а в другом — camelCase. Лучше потратить десять минут на создание уникального файла для каждого проекта, чем потом исправлять ошибки, вызванные неверными инструкциями.

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

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