Средний

CLAUDE.md: улучшение поведения Claude Code по Karpathy

Алексей Кузнецов
Алексей Кузнецов
Системный администратор10 ноября 2026 г.12 мин чтения

Один файл CLAUDE.md, основанный на наблюдениях Андрея Карпатты, исправляет типичные ошибки LLM‑кода, делая работу с AI‑инструментами предсказуемой.

CLAUDE.md: улучшение поведения Claude Code по Karpathy

Один файл CLAUDE.md, основанный на наблюдениях Андрея Карпатты, исправляет типичные ошибки LLM‑кода, делая работу с AI‑инструментами предсказуемой.

Общие принципы работы CLAUDE.md

Общие принципы работы CLAUDE.md

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

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

Структурирование команд

Одна из типичных проблем — когда модель предлагает команды, которые не подходят под вашу среду. Например, она может попытаться использовать npm install, хотя в вашем проекте настроен pnpm, или предложить запустить тесты через pytest, когда вы используете unittest.

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

Пример правильной структуры раздела команд в файле:

markdown
## Build and Test Commands

- Build the project: `docker compose build`
- Run all tests: `docker compose exec app pytest`
- Run a single test: `docker compose exec app pytest tests/test_module.py`
- Linting: `flake8 .`
- Format code: `black .`

Если вы работаете в домашней лаборатории и разворачиваете сервисы через systemd, добавьте инструкции и для этого. Модель должна знать, что для перезапуска сервиса нужно использовать sudo systemctl restart service_name, а не пытаться искать конфиги внутри контейнера.

Ясные ограничения контекста

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

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

В этом подразделе стоит прописать:

  1. Стиль кода: например, использование только аннотаций типов (type hinting) или запрет на использование определенных библиотек.
  2. Правила изменения файлов: запрет на рефакторинг существующих функций без явного запроса.
  3. Структура проекта: где лежат конфиги, где — логи, а где — исходный код.

Пример описания ограничений:

markdown
## Coding Standards and Constraints

- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Do not refactor existing logic unless explicitly asked to "refactor".
- All new environment variables must be added to `.env.example`.
- Use `logging` module instead of `print()` for all output.

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

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

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

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

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

Избыточные запросы

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

Типичный сценарий: вы просите добавить новую зависимость, и вместо того, чтобы просто выполнить команду, модель начинает спрашивать: «Вы уверены, что хотите использовать версию X?», «Мне нужно обновить lock-файл?», «Вы хотите запустить тесты после установки?».

Чтобы это исправить, в CLAUDE.md нужно прописать явный алгоритм действий. Вместо того чтобы полагаться на интуицию модели, мы задаём правила. Например, если мы работаем с npm, мы фиксируем, что любые изменения в package.json должны сопровождаться автоматическим запуском npm install.

Пример секции для файла конфигурации:

markdown
## Workflow Rules

- При добавлении любой библиотеки через npm, всегда выполняй `npm install` сразу после изменения package.json.
- Если команда завершилась с ошибкой, не предлагай решение сразу, а сначала выполни `npm test`, чтобы понять масштаб проблемы.
- Не запрашивай подтверждение на выполнение команд чтения (cat, ls, grep), если они не затрагивают системные файлы.

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

Неправильный формат инструкций

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

Например, вы используете systemd для управления сервисами в своей домашней лаборатории, а Claude предлагает создать docker-compose.yml для задачи, которая решается простым unit-файлом. Или, что ещё хуже, она использует double quotes там, где в вашем проекте строго заданы single quotes.

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

Если мы посмотрим на подход, который предлагает Андрей Карпата, ключевым фактором является предоставление модели «карты» проекта. В контексте формата инструкций это выглядит так:

markdown
## Coding Standards

- Используй только `async/await` для асинхронных операций; избегай использования `.then()`.
- Все конфигурационные файлы должны быть в формате YAML.
- Для логирования используй стандартный `journald` через `systemd-cat`, не пиши кастомные логгеры в файлы.
- При написании скриптов на Python всегда проверяй наличие type hints.

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

Оптимизация взаимодействия с AI‑инструментами

Оптимизация взаимодействия с AI-инструментами

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

Именно здесь на помощь приходит концепция файла CLAUDE.md. Если опираться на наблюдения Андрея Карпатты, работа с AI-агентами становится предсказуемой только тогда, когда вы передаёте ему не просто код, а правила игры.

Использование контекстных подсказок

Типичная ошибка при работе с Claude Code — позволить модели самой решать, как структурировать тесты или как именовать переменные. В итоге через неделю вы обнаружите, что в одном модуле используется snake_case, а в другом — camelCase, хотя проект строго следует одному стандарту.

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

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

markdown
# CLAUDE.md — Project Guidelines

## Build and Test Commands
- Build: `make build`
- Run tests: `pytest tests/`
- Lint: `ruff check .`
- Type check: `mypy .`

## Code Style
- Use type hints for all function signatures.
- Follow PEP 8 strictly.
- Prefer composition over inheritance.
- Error handling: Use custom exceptions defined in `src/errors.py`.

## Architecture Notes
- Services must be stateless.
- Database migrations are managed via Alembic.
- All external API calls must go through the `Gateway` class.

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

Автоматизация повторяющихся задач

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

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

Создайте единую команду в Makefile или скрипте, которую модель сможет вызвать. Например, если мы работаем с Docker-контейнерами в домашней лаборатории, удобно иметь команду для полной проверки окружения:

makefile
# Makefile для автоматизации проверок
.PHONY: check-all

check-all:
	@echo "Starting full validation suite..."
	docker-compose up -d db redis
	pytest tests/integration
	ruff check .
	docker-compose down

Теперь, вместо того чтобы объяснять Claude: «сначала подними базу в докере, потом запусти тесты, а потом всё убери», вы просто даёте инструкцию в CLAUDE.md:

markdown
## Workflow
- To validate changes, always run `make check-all`.
- Do not attempt to run tests without the database container being active.

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

Мониторинг и поддержка качества кода

Логирование и анализ ошибок

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

С практической точки зрения, Claude должен не просто «исправить ошибку», а сначала проанализировать логи. Если вы работаете с Docker-контейнерами, не позволяйте модели гадать, почему сервис не поднялся. Инструктируйте её всегда проверять вывод docker logs или journalctl.

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

markdown
## Error Handling & Logging
- Always check logs before proposing a fix.
- For systemd services, use: `journalctl -u <service_name> -n 50 --no-pager`
- For Docker containers, use: `docker logs <container_id> --tail 50`
- If an error is encountered, analyze the stack trace and explain the root cause before applying changes.
- Do not suppress errors; ensure all exceptions are caught and logged with context.

Если вы настраиваете мониторинг в домашней лаборатории, например, через стек Prometheus и Grafana, добавьте в правила требование проверять метрики. Это поможет избежать ситуации, когда ИИ «чинит» утечку памяти, просто перезапуская процесс, вместо того чтобы найти причину в коде.

Регулярные ревью и рефакторинг

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

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

Во-первых, определите критерии, при которых требуется рефакторинг. Во-вторых, укажите предпочтительные инструменты проверки. Если вы используете Python, это может быть ruff или mypy; если Go — golangci-lint.

Пример блока для управления качеством кода:

markdown
## Code Quality & Refactoring
- Prioritize readability and predictability over cleverness.
- After any significant change, run the local linter: `make lint` or `ruff check .`
- If a function exceeds 50 lines, propose a refactor to split it into smaller, testable units.
- Maintain strict typing: always use type hints in Python or explicit types in TypeScript.
- Ensure that all new logic is accompanied by a corresponding test case in the `tests/` directory.

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

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

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

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

Как CLAUDE.md помогает избежать лишних правок в коде?

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

Повлияет ли наличие этого файла на расход токенов?

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

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

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

Поделиться:TelegramX / TwitterVK