Настройка CLAUDE.md для Claude Code
Как использовать файл CLAUDE.md на основе советов Андрея Карпаты, чтобы повысить предсказуемость и качество работы Claude Code в ваших проектах.
Проблема непредсказуемости AI-агентов
Проблема непредсказуемости AI-агентов
Когда я впервые начал использовать Claude Code для автоматизации рутинных задач в своей домашней лаборатории, я столкнулся с классической проблемой: агент работал отлично на простых задачах, но начинал «галлюцинировать» или ломать архитектуру, как только дело доходило до специфики конкретного проекта.
Проблема не в самой модели, а в отсутствии контекста. AI-агент — это не опытный инженер, который знает историю ваших решений, а очень эрудированный стажёр. Если вы не дадите ему чётких правил игры, он будет действовать на основе наиболее вероятных паттернов из своей обучающей выборки, а не на основе того, как принято писать код именно в вашем репозитории. Это убивает предсказуемость — главный критерий качественной инфраструктуры.
Типичные ошибки при написании кода через LLM
Без строгого контекста работа с агентами часто превращается в бесконечный цикл правок. Я выделил три основные ошибки, с которыми сталкиваются почти все:
- Нарушение принятых стандартов оформления. Агент может использовать
tabsвместоspacesили выбрать стиль именования переменных, который противоречит вашемуESLintилиPrettier. В итоге вы тратите больше времени на исправление форматирования, чем на проверку логики. - Использование устаревших или неподходящих библиотек. Если в вашем проекте используется
FastAPI, а агент решит, что для решения задачи лучше подойдётFlask, он создаст лишнюю сложность и раздует зависимости. - Игнорирование специфики окружения. Это критично при работе с контейнеризацией. Агент может написать скрипт, который ожидает наличия
sudoили определённых путей в/etc/, хотя ваш сервис работает внутри легковесного образа на базеAlpine Linux.
Пример того, как выглядит «непредсказуемый» код, который агент может выдать без инструкций:
python# Агент решил использовать стандартную библиотеку,
# хотя в проекте уже настроен pydantic для валидации
import json
def process_config(data):
# Это сработает, но нарушит единый стиль обработки ошибок в проекте
return json.loads(data)
Почему стандартных инструкций недостаточно
Многие пытаются решить проблему через системный промпт или общие инструкции в интерфейсе чата. Но для Claude Code этого мало. Когда агент работает непосредственно с файловой системой, ему нужен локальный, проектно-ориентированный «якорь».
Стандартные инструкции слишком размыты. Они говорят: «Пиши чистый код» или «Соблюдай PEP 8». Но они не говорят: «В этом проекте мы используем poetry для управления зависимостями, а все тесты запускаем через pytest с флагом --cov».
Как отмечает Андрей Карпата, эффективность работы с LLM напрямую зависит от того, насколько точно вы задаёте рамки (constraints) и контекст. Использование файла CLAUDE.md позволяет перенести эти рамки из вашей головы непосредственно в рабочую директорию проекта. Это превращает агента из случайного исполнителя в предсказуемый инструмент, который понимает:
- Как именно запускать сборку проекта.
- Какие команды использовать для тестирования.
- Какую структуру директорий соблюдать.
Вместо того чтобы каждый раз объяснять агенту, что «у нас тесты лежат в папке tests/unit и запускаются командой make test», вы один раз фиксируете это в конфигурационном файле. Это и обеспечивает ту самую предсказуемость, которая необходима, чтобы не превратить разработку в хаос.
Концепция CLAUDE.md от Андрея Карпаты
Роль контекстного файла в работе Claude Code
Когда мы работаем с ИИ-агентами вроде Claude Code, основная проблема заключается не в «интеллекте» модели, а в дефиците контекста. Модель видит ваш код, но она не знает ваших локальных стандартов, специфики сборки или того, как именно вы привыкли запускать тесты. Без дополнительных инструкций агент начинает гадать, что приводит к непредсказуемым результатам: он может предложить использовать npm, когда ваш проект завязан на pnpm, или попытаться запустить тесты через pytest, игнорируя специфические флаги конфигурации.
Файл CLAUDE.md решает эту проблему, выступая в роли «краткого технического задания» для агента. Если рассматривать Claude Code как стажёра, то CLAUDE.md — это документ, который вы оставляете ему на столе в первый рабочий день. Вместо того чтобы каждый раз объяснять, как поднять окружение, вы фиксируете это в одном месте.
С практической точки зрения, наличие этого файла превращает хаотичные попытки агента угадать команды в предсказуемый рабочий процесс. Модель при каждом обращении к проекту считывает этот файл и использует его как набор жестких правил. Это минимизирует количество ошибок в командах и позволяет агенту сразу переходить к решению инженерной задачи, а не тратить токены на выяснение того, как работает ваш Makefile.
Основные принципы из наблюдений инженера
В основе концепции использования подобных контекстных файлов лежат идеи, которые транслировал Андрей Карпатый, подчеркивая важность предоставления модели четких, структурированных и лаконичных инструкций. Если мы посмотрим на подход опытного инженера, то поймём: чем меньше в инструкциях «воды» и чем больше конкретных команд, тем выше качество работы.
Я выделяю три ключевых принципа, которые стоит перенести в ваш CLAUDE.md:
- Минимализм и конкретика. Не нужно писать «Мы используем современные стандарты разработки». Вместо этого напишите: «Используй TypeScript 5.x и строгую типизацию».
- Справочник команд. Агент должен точно знать, как выполнять основные операции. Это избавляет от ситуации, когда Claude Code пытается выполнить
make test, а у вас настроен запуск черезgo test ./.... - Стилистические гайдлайны. Если в проекте принято использовать функциональный стиль в React или определённый формат именования переменных, это должно быть зафиксировано.
Пример грамотно структурированного CLAUDE.md для небольшого проекта на Python выглядит следующим образом:
markdown# Claude Code Project Guide
## Build and Run Commands
- Install dependencies: `pip install -r requirements.txt`
- Run application: `python main.py`
- Run tests: `pytest tests/ --cov=app`
- Linting: `flake8 app/`
## Code Style and Patterns
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer asynchronous programming (asyncio) for I/O operations.
- Error handling: Always wrap network calls in try-except blocks with specific exceptions.
## Testing Requirements
- All new features must include unit tests in the `tests/` directory.
- Use `pytest-mock` for all external service mocking.
С точки зрения предсказуемости, такой файл работает как предохранитель. Если вы добавите в него секцию с командами, Claude Code будет использовать именно их. Например, если вы решите изменить способ запуска тестов, вам достаточно будет обновить одну строку в CLAUDE.md, и агент мгновенно подстроится под новую реальность проекта. Это гораздо эффективнее, чем пытаться исправлять ошибки в каждом отдельном диалоге.
Практическое применение инструкций
Структура идеального CLAUDE.md
Когда я внедряю новые инструменты в свою домашнюю лабораторию, я всегда ищу способ сделать их работу предсказуемой. Claude Code — это мощный инструмент, но без контекста он склонен к галлюцинациям или, что ещё хуже, к написанию кода, который нарушает сложившуюся архитектуру вашего проекта. Файл CLAUDE.md служит своего рода «конституцией» для ИИ-агента.
Опираясь на идеи Андрея Карпаты, эффективный контекст должен быть максимально сжатым и прикладным. Не нужно писать полотна текста о том, как прекрасен ваш проект. Нужны конкретные инструкции, которые агент сможет использовать как чек-лист.
Я рекомендую разделять CLAUDE.md на три логических блока:
- Build & Test Commands: точные команды для сборки, запуска тестов и линтинга. Никаких «запустите тесты», только конкретика.
- Code Style & Patterns: правила именования, предпочтительные библиотеки и архитектурные паттерны.
- Project Context: краткое описание того, что делает проект и какие ключевые зависимости в нём используются.
Пример базовой структуры файла для проекта на Python:
markdown# CLAUDE.md — Project Guidelines
## Build and Test Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest tests/`
- Run linter: `flake8 .`
- Run type checker: `mypy src/`
## Code Style and Patterns
- Use type hints for all function signatures.
- Prefer functional programming patterns over heavy OOP where possible.
- Follow PEP 8 strictly.
- All asynchronous code must use `asyncio`.
- Error handling: Use custom exception classes defined in `src/exceptions.py`.
## Project Architecture
- Core logic resides in `src/core/`.
- API layer is implemented via FastAPI in `src/api/`.
- Database migrations are managed by Alembic.
Примеры правил для соблюдения архитектуры проекта
С практической точки зрения, самая большая проблема при работе с ИИ — это когда он начинает «лечить» проект, внедряя решения, которые противоречат вашему стеку. Например, вы используете FastAPI и SQLAlchemy с асинхронным драйвером, а агент внезапно предлагает синхронный вызов, который заблокирует event loop.
Чтобы этого избежать, в секцию Code Style and Patterns нужно добавить максимально жесткие ограничения. Если у вас есть специфические требования к структуре директорий или способу обработки ошибок, пропишите их явно.
Вот пример того, как можно описать правила для проекта на Node.js/TypeScript, чтобы агент не нарушал границы слоёв:
markdown## Architectural Constraints
- **Layered Architecture**: Strictly separate Business Logic (Services), Data Access (Repositories), and Transport (Controllers).
- **Dependency Injection**: Use `InversifyJS` for all service injections. Do not instantiate classes directly in controllers.
- **Data Validation**: Use `Zod` for all input validation at the API boundary.
- **Error Handling**: Never use `console.log` for errors. Use the internal `Logger` service.
- **Database**: All queries must go through the Repository layer. Direct access to the ORM in the Service layer is prohibited.
Если вы работаете с инфраструктурным кодом, например, на Ansible, правила могут выглядеть иначе:
markdown## Ansible Best Practices
- Use `collections` instead of legacy modules.
- All tasks must include a `name` attribute.
- Variables must be defined in `group_vars/` or `host_vars/`, never hardcoded in roles.
- Use `ansible-lint` to verify all playbooks before suggesting changes.
Такой подход превращает Claude Code из «умного собеседника» в предсказуемого участника процесса разработки. Вы тратите чуть больше времени на описание правил в начале, но экономите часы на ревью кода, который не нужно переписывать из-за нарушения архитектуры.
Результаты внедрения в рабочий процесс
Снижение количества итераций исправления ошибок
Когда я впервые начал использовать Claude Code в своих проектах, главной проблемой была «разболтанность» модели. Без чётких инструкций ИИ часто предлагал решения, которые противоречили архитектуре проекта: например, пытался добавить новую зависимость там, где мы используем только стандартную библиотеку, или предлагал стиль написания тестов, отличный от принятого в команде.
Внедрение CLAUDE.md позволяет задать жёсткие рамки. Вместо того чтобы на каждой итерации объяснять: «Нет, мы не используем axios, у нас только fetch», вы прописываете это один раз в секции Tech Stack.
С практической точки зрения, это превращает бесконечный цикл «исправь это — теперь это» в предсказуемый процесс. Если в файле указаны конкретные команды для запуска тестов и линтера, Claude не будет гадать, как проверить код.
Пример эффективной секции для управления качеством в CLAUDE.md:
markdown## Development Workflow
### Build and Test
- Build project: `npm run build`
- Run tests: `npm test`
- Run specific test: `npm test -- <file_path>`
- Linting: `npm run lint`
### Code Style
- Use functional components for React.
- Prefer explicit type definitions over `any` in TypeScript.
- Error handling: Always wrap asynchronous calls in try/catch blocks with custom error logging.
Благодаря этому, когда вы просите: «Добавь новый эндпоинт в API», Claude Code сначала смотрит в CLAUDE.md, видит команду для линтинга и понимает, что после написания кода нужно выполнить npm run lint. Это исключает этап, когда вы вручную ловите ошибки форматирования, которые ИИ допустил по невнимательности.
Улучшение качества генерации кода
Качество кода напрямую зависит от контекста. Андрей Карпата в своих советах по работе с LLM подчёркивает важность предоставления модели правильных паттернов. В контексте Claude Code файл CLAUDE.md служит тем самым «компасом», который удерживает генерацию в рамках вашей инженерной культуры.
Если ваш проект использует специфическую структуру директорий или сложные паттерны проектирования (например, Clean Architecture), Claude может начать «галлюцинировать» и разбрасывать логику по случайным папкам.
Чтобы этого избежать, я рекомендую добавить в файл описание структуры проекта. Это не просто список папок, а правила их использования.
Пример описания архитектурных правил:
markdown## Project Structure & Patterns
- `src/domain`: Contains pure business logic. No dependencies on frameworks.
- `src/infrastructure`: Implementation of interfaces (DB, external APIs).
- `src/application`: Use cases that orchestrate domain objects.
Rule: Business logic must never import from `src/infrastructure`.
Когда правила прописаны явно, предсказуемость работы возрастает. Вместо того чтобы предлагать «решение на коленке», Claude начинает генерировать код, который сразу готов к интеграции в существующую систему.
Если мы посмотрим на процесс рефакторинга, то увидим разницу: без CLAUDE.md модель может переписать метод, сделав его короче, но нарушив инкапсуляцию. С правильно настроенным файлом она будет следовать вашим правилам, даже если это требует написания чуть более объёмного, но архитектурно верного кода.
Заключение
Когда CLAUDE.md становится необходимостью
Подводя итог, стоит разделить использование этого файла на два сценария. Если вы просто экспериментируете с Claude Code, файл может показаться избыточным. Но как только проект перерастает уровень «один скрипт на коленке», отсутствие инструкций начинает работать против вас.
С практической точки зрения, CLAUDE.md решает главную проблему LLM-агентов — галлюцинации в контексте ваших локальных правил. Без него модель может предложить использовать npm install, когда в вашем проекте строго прописан pnpm, или попытаться запустить тесты через pytest, хотя вы используете unittest.
Если вы хотите добиться предсказуемости, внедряйте этот файл сразу после инициализации репозитория. Это не «дополнительная работа», а инвестиция в то, чтобы не тратить время на исправление синтаксических ошибок, которые агент совершил просто потому, что не знал о ваших предпочтениях.
Резюме по внедрению
Чтобы ваш рабочий процесс оставался стабильным, я рекомендую придерживаться трёх принципов при наполнении файла:
- Лаконичность. Не пишите мемуары. Claude Code должен быстро сканировать файл. Вместо «Мы предпочитаем использовать библиотеку X, потому что она более производительная», пишите «Use library X for all async operations».
- Конкретика в командах. Всегда указывайте точные команды для сборки, тестирования и запуска. Если у вас сложный процесс, лучше дать пример команды, чем описывать его словами.
- Строгость стандартов. Если проект требует определённого стиля кода (например, строгое использование типов в TypeScript), это должно быть первой строкой в разделе
Code Style.
Для тех, кто хочет глубже изучить философию работы с контекстом в современных AI-инструментах, рекомендую ознакомиться с советами Андрея Карпаты, где он рассуждает о важности качественного контекста для моделей.
Чек-лист готовности проекта
Перед тем как оставить проект на откуп агенту, проверьте, покрыты ли в CLAUDE.md следующие аспекты:
- Build commands: Как собрать проект (например,
make buildилиdocker-compose build). - Test commands: Как запустить тесты и как просматривать отчеты.
- Code style: Основные правила (отступы, именование, использование конкретных паттернов).
- Architecture notes: Краткое описание того, где лежат важные компоненты (например, «Logic is in
/src/core, API definitions in/src/api»).
Если эти пункты заполнены, Claude Code превращается из «умного чат-бота» в полноценного участника вашей команды, который понимает правила игры в вашем репозитории.
FAQ
Как Claude Code понимает содержимое CLAUDE.md?
Claude Code работает по принципу контекстного окна. Когда вы запускаете инструмент в директории проекта, он сканирует файловую систему на предмет специальных инструкций. Файл CLAUDE.md служит своего рода «бортовым журналом» или техническим заданием, которое загружается в контекст при каждом запросе.
Если файл настроен правильно, модель не тратит токены на угадывание того, как запускать тесты или какой стиль именования использовать в вашем проекте. Вместо того чтобы каждый раз спрашивать: «А как мне собрать этот проект?», Claude Code просто читает инструкцию. Это и обеспечивает ту самую предсказуемость, о которой так часто говорят инженеры.
Нужно ли добавлять в CLAUDE.md все инструкции проекта?
Нет, и это важный момент. Если вы попытаетесь запихнуть в файл всё — от описания архитектуры до списка всех переменных окружения — вы быстро исчерпаете полезный объем контекста.
С практической точки зрения, в CLAUDE.md стоит включать только то, что критично для автоматизации рутины:
- Команды для сборки, запуска и тестирования.
- Правила оформления кода (style guide).
- Специфические паттерны проектирования, принятые в вашей команде.
Если инструкция слишком длинная, Claude может начать игнорировать детали в середине текста. Лучше иметь короткий, но точный файл, чем огромную «простыню» текста.
Можно ли использовать CLAUDE.md для разных окружений?
На текущий момент Claude Code ищет файл именно в корне проекта. Если у вас монорепозиторий с несколькими сервисами, я рекомендую использовать один общий CLAUDE.md в корне, но с четким разделением по секциям.
Например, если у вас есть сервис на Python и фронтенд на React, структура может выглядеть так:
markdown## Python Service (Backend)
- Build: `make build-backend`
- Test: `pytest tests/`
- Style: Follow PEP 8
## React App (Frontend)
- Build: `npm run build`
- Test: `npm test`
- Style: Use functional components and Tailwind CSS
Это позволит модели быстро переключаться между контекстами разных частей системы, не путая команды npm и pip.
Как проверить, что Claude Code действительно учитывает файл?
Самый простой способ — это провести небольшой тест. Создайте в CLAUDE.md заведомо странную, но безобидную инструкцию. Например, добавьте требование: «При написании комментариев всегда используй только эмодзи 🐧».
Затем задайте вопрос по коду:
Claude, объясни, что делает эта функция.
Если в ответе появились пингвины — значит, инструкции подтянулись. Если нет — проверьте, что файл лежит в корне рабочей директории и у Claude есть права на его чтение.
В чем разница между CLAUDE.md и .clauderc?
Эти файлы решают разные задачи. .clauderc — это конфигурация самого инструмента (настройки поведения, глобальные параметры), а CLAUDE.md — это контекст конкретного проекта.
Если вы хотите, чтобы Claude всегда вел себя определенным образом во всех ваших проектах (например, всегда использовал определенный формат вывода), это настраивается через конфигурацию инструмента. Но если вам нужно, чтобы он знал, что в проекте «Винни-Пух» тесты запускаются через go test ./..., это место только для CLAUDE.md.
Часто задаваемые вопросы
Где именно нужно размещать файл CLAUDE.md?
Файл должен находиться в корневом каталоге вашего проекта, там же, где расположен .git. Это позволяет Claude Code при инициализации сессии сразу считывать инструкции и применять их ко всему контексту репозитория. Если проект разбит на монорепозиторий с несколькими сервисами, вы можете создать отдельные файлы в поддиректориях, чтобы задать специфические правила для каждого компонента.
Можно ли использовать CLAUDE.md для описания команд сборки и тестирования?
Да, это одна из самых полезных практик для обеспечения предсказуемости. Вместо того чтобы каждый раз объяснять агенту, как запустить тесты или собрать контейнер, пропишите конкретные команды в секции Build and Test commands. Это исключит ошибки, когда агент пытается использовать npm test там, где в вашем проекте настроен pytest или специфический скрипт в Makefile.
Как CLAUDE.md помогает избежать конфликтов с существующим стилем кода?
Файл служит своего рода «техническим заданием» на уровне проекта, которое ограничивает свободу действий модели. Если вы укажете в нем правила именования, предпочтительные библиотеки или требования к документации, агент будет использовать их как приоритетный контекст. С практической точки зрения это превращает «эрудированного стажёра» в инженера, который соблюдает установленный в команде стандарт.
Нужно ли обновлять CLAUDE.md при изменении архитектуры проекта?
Безусловно, этот файл — не статичная документация, а живой инструмент управления контекстом. Если вы перешли с Debian на Alpine Linux или заменили PostgreSQL на Redis, правила в CLAUDE.md должны быть обновлены незамедлительно. Игнорирование этого процесса приводит к тому, что агент начинает предлагать решения, которые технически верны, но архитектурно несовместимы с вашим текущим окружением.