CLAUDE.md от Карпатого: как один файл улучшает работу Cla...

CLAUDE.md от Карпатого: как один файл улучшает работу Claude Code

Разбираем проект andrej-karpathy-skills — набор правил для Claude Code, основанный на наблюдениях Андрея Карпатого о типичных ошибках LLM при написании кода.

Откуда взялся этот файл и почему он набрал 15 000 звёзд

Андрей Карпатый и его наблюдения за LLM-кодингом

Андрей Карпатый — фигура в индустрии настолько известная, что объяснять кто он не совсем обязательно. Директор Tesla AI, бывший руководитель направления компьютерного зрения в Tesla Autopilot, один из ключевых исследователей в области глубокого обучения. Когда он публикует наблюдения о том, как работают большие языковые модели, — это не теоретические рассуждения из академической башни, а выводы человека, который ежедневно пишет код с помощью LLM и видит паттерны ошибок на собственном опыте.

В начале 2026 года Карпатый поделился набором наблюдений о типичных проблемах, которые возникают при использовании Claude Code и подобных инструментов. Суть сводилась к нескольким пунктам: LLM склонны усложнять там, где можно сделать проще; генерируют избыточный код вместо использования существующих библиотек; не всегда следуют стилю проекта; и — что особенно важно — повторяют одни и те же ошибки от запроса к запросу, если не дать им явных инструкций.

Эти наблюдения быстро разлетелись по сообществу. Их пересылали в Slack-чатах, цитировали в Twitter, обсуждали на Reddit. Но наблюдения — это одно, а рабочий инструмент — совсем другое. И тут в игру вступил разработчик под ником multica-ai.

Как разработчик превратил наблюдения в CLAUDE.md

Репозиторий multica-ai/andrej-karpathy-skills появился на GitHub в апреле 2026 года и за считанные недели набрал более 15 000 звёзд. Цифра впечатляющая для проекта, который по сути представляет собой один-единственный markdown-файл.

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

Вот как это работает на практике. Вы создаёте файл CLAUDE.md в корне проекта:

markdownКопировать
# Project Guidelines

## Code Style
- Use existing libraries before writing custom implementations
- Prefer simple, readable solutions over clever ones
- Follow the existing project conventions strictly

## Common Pitfalls to Avoid
- Do not add unnecessary abstractions
- Do not generate boilerplate when a library function exists
- Do not change code that was not explicitly requested to change

Claude Code при каждом обращении к файлам проекта учитывает содержимое этого файла. Это работает как системный промпт, который вы задаёте один раз и забываете о нём — он применяется автоматически.

Разработчик multica-ai структурировал рекомендации Карпатого в несколько секций: стиль кода, типичные ошибки, предпочтительные подходы к архитектуре. Каждая секция — это конкретное, измеримое правило, а не абстрактные пожелания. Например, вместо «пиши чистый код» — «не создавай новые абстракции, если задачу можно решить двумя вызовами стандартной библиотеки».

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

Для тех, кто администрирует серверы и автоматизирует процессы, аналогия близка к тому, как работает .editorconfig или .gitignore: один файл в правильном месте — и поведение инструмента меняется предсказуемо. Принцип тот же, только вместо настроек редактора мы задаём правила для языковой модели.

Что внутри: структура и ключевые правила

Принцип «предсказуемых ошибок»

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

Репозиторий multica-ai/andrej-karpathy-skills набрал 15 000 звёзд на GitHub за считанные недели. Причина — в практической применимости. Вместо абстрактных рассуждений об «инженерии промптов» автор взял конкретные наблюдения Карпатого о том, как LLM пишут код, и превратил их в структурированный файл CLAUDE.md.

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

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

Конкретные инструкции для Claude Code

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

Типичная структура файла из проекта Карпатого выглядит так:

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

## Code Style
- Не добавляй проверки на null/undefined там, где тип гарантирует значение
- Не дублируй логику, которая уже есть в вызываемой функции
- Не оборачивай каждую строку в try/catch — обрабатывай ошибки на уровне слоя

## Architecture
- Новый код размещай в соответствии с существующей структурой пакетов
- Не создавай вспомогательные функции «на вырост» — YAGNI в действии

## Testing
- Тесты пиши только для публичного API, не для внутренних утилит
- Моки используй на границах интеграции, не внутри бизнес-логики

Ключевой принцип — конкретика. Вместо расплывчатого «пиши чистый код» даётся явное указание: «не добавляй проверки на null, если TypeScript-тип исключает undefined». Модель способна следовать таким правилам, потому что они бинарны — либо проверка нужна, либо нет.

Для сравнения: вот пример неэффективной инструкции и её рабочей замены:

markdownКопировать
# Плохо — модель не понимает, что конкретно вы имеете в виду
- Пиши хороший код

# Хорошо — модель может верифицировать выполнение правила
- Не используй `any` в TypeScript. Если тип неизвестен — используй `unknown`
  с последующим сужением через type guard

Файл можно положить в корень репозитория (проектные правила) или в домашнюю директорию ~/.claude/CLAUDE.md (глобальные правила для всех проектов). Приоритет: проектные переопределяют глобальные.

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

Практическое применение: как интегрировать в свой проект

Установка и базовая настройка

Проект andrej-karpathy-skills набрал 15 тысяч звёзд за считаные недели — и это не мем, а вполне рабочий инструмент. Суть простая: один файл CLAUDE.md в корне репозитория, и Claude Code начинает писать код заметно аккуратнее.

Во-первых, убедитесь, что у вас установлен Claude Code. Проверить версию можно так:

bashКопировать
claude --version

Если команда не найдена — ставим через npm:

bashКопировать
npm install -g @anthropic-ai/claude-code

Теперь к самому файлу. Клонируем репозиторий с правилами Карпатого:

bashКопировать
cd /path/to/your/project
curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

После этого открываем проект в Claude Code:

bashКопировать
claude

Файл подхватится автоматически — Claude Code ищет CLAUDE.md в текущей дирекрии при каждом запуске сессии. Никаких дополнительных настроек не требуется.

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

Адаптация правил под конкретный стек

Стандартный CLAUDE.md из репозитория — это общая база. Для реального проекта его нужно кастомизировать. Вот как я адаптировал правила под свой стек на Docker Compose и PostgreSQL.

Открываем файл и добавляем секцию под конкретный проект:

markdownКопировать
## Project-specific rules

### Stack
- Backend: Python 3.11, FastAPI
- Database: PostgreSQL 16, asyncpg
- Cache: Redis 7
- Reverse proxy: Caddy
- Orchestration: Docker Compose

### Database conventions
- Always use migrations (Alembic), never auto-generate schema
- Table names: snake_case, plural (e.g., `user_sessions`)
- Every table must have `created_at` and `updated_at` timestamps
- Use `ON DELETE CASCADE` only when explicitly requested

### Docker conventions
- Multi-stage builds for all services
- Non-root user in containers
- Health checks for every service
- No `latest` tags — pin exact versions

### What NOT to do
- Do not use `docker exec` for database queries — use migration files
- Do not add indexes without explaining the query pattern they optimize
- Do not use `SELECT *` in production code

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

Для инфраструктурных проектов, которые я веду на домашнем сервере, добавляю отдельную секцию:

markdownКопировать
## Infrastructure context

- Proxmox VE 8.2, cluster of 3 nodes
- TrueNAS SCALE for storage (ZFS, NFS exports)
- All services run in LXC containers or VMs, never bare metal
- Backups: daily ZFS snapshots, weekly offsite via rsync
- Monitoring: Prometheus + Grafana, alerts via Alertmanager

### Server naming convention
- Nodes: winnie, piglet, owl, rabbit (Winnie-the-Pooh characters)
- Use hostname, never IP addresses in configurations

Такой контекст экономит время на каждой сессии: не нужно объяснять архитектуру заново. Модель сразу знает, что сервер называется «winnie», а не «192.168.1.10», и что бэкапы уже настроены через ZFS-снапшоты.

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

Мои наблюдения: что из этого применимо к инфраструктуре

Параллели с Ansible и декларативными конфигурациями

Если вы работали с Ansible больше двух минут, вы знаете главную боль: плейбук запустился без ошибок, но результат не тот. Не потому что Ansible плохой, а потому что в плейбуке не учли какой-то нюанс — порядок задач, идемпотентность, зависимость от состояния системы.

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

Вот эти правила:

1. Не доверяй модели — проверяй. Модель не знает контекста вашей системы. Она не знает, что на сервере уже крутится PostgreSQL 16, а не 14, и что вы используете ZFS, а не ext4.
2. Ограничивай свободу. Чем больше свободы даёт LLM, тем более креативные ошибки он совершает. Лучше чётко указать, какие файлы можно менять, а какие — только читать.
3. Требуй объяснений. Перед тем как менять что-либо, модель должна объяснить, что она собирается сделать и почему.
4. Разбивай задачи. Большие задачи нужно декомпозировать на маленькие шаги, каждый из которых можно проверить.

С практической точки зрения, это в точности то, что мы делаем в Ansible. Вот пример — допустим, мы просим Claude Code настроить Nginx на сервере. Без контекста модель сгенерирует что-то универсальное. С CLAUDE.md — она будет знать, что у нас конкретно за сервер и какие правила приняты в проекте.

markdownКопировать
# CLAUDE.md — пример для инфраструктурного проекта

## Правила работы с инфраструктурой

### Что можно менять
- Файлы конфигурации в `/etc/nginx/` — только после согласования с описанием изменений
- Docker Compose файлы в директории `/opt/services/`
- Скрипты в `/opt/scripts/` — только если они идемпотентны

### Что нельзя менять без явного указания
- `/etc/fstab` — требует отдельного обсуждения
- Конфигурацию ZFS-пулов
- Правила iptables/nftables

### Формат описания изменений
Перед внесением изменений в любой конфигурационный файл:
1. Укажи путь к файлу
2. Объясни, что именно будет изменено
3. Объясни, почему это изменение необходимо
4. Укажи, как откатить изменение

### Соглашения
- Все серверы названы в честь персонажей советских мультфильмов
- Основной сервер: Винни-Пух (192.168.1.10)
- Реплика: Пятачок (192.168.1.11)
- Мониторинг: Сова (192.168.1.12)
- Бэкапы: Кролик (192.168.1.13)

Когда я впервые попробовал этот подход на своём домашнем кластере, результат был заметен сразу. Раньше Claude Code мог сгенерировать конфиг для Caddy, который работал бы на чистой Ubuntu, но ломал мою существующую связку с DNS-чallenge через Cloudflare. С CLAUDE.md, где описана текущая архитектура, модель сразу учитывала этот контекст.

Интересно, что сам Карпатый провёл мысленный эксперимент: если ошибки предсказуемы, их можно предотвратить с помощью правил. Это в точности философия, которую я применяю к инфраструктуре уже много лет. Помните анекдот про 1 апреля, когда я отключаю мониторинг? Так вот, в этом году Кролик заметил отсутствие алертов через 14 минут — потому что у нас есть правило: если метрики не приходят больше двух минут, это инцидент. Предсказуемость реакции на предсказуемые проблемы.

Когда системный подход к LLM оправдан, а когда — избыточен

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

Вот мой практический критерий: подход с правилами оправдан, когда стоимость ошибки превышает стоимость написания этих правил. Разберу на конкретных примерах из моей практики.

Когда оправдано:

• Продуктивная инфраструктура. Когда на сервере крутится Plex с семейной медиатекой, Nextcloud с документами и бэкап фотографий — каждая ошибка в конфигурации потенциально означает потерю данных или простой сервиса. Жена не оценит, если Plex не запустится после обновления в три часа ночи.

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

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

Когда избыточно:

• Разовые задачи. Написать скрипт для миграции данных между двумя серверами, который запустится один раз и будет удалён — не нужен CLAUDE.md. Достаточно здравого смысла и проверки результата.

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

• Простые односерверные установки. Если у вас один Raspberry Pi с Pi-hole и больше ничего, полноценный CLAUDE.md — это как покупать промышленный серверный шкаф для хранения трёх книг.

Практический совет: начните с минимального набора правил и расширяйте его по мере возникновения проблем. Мой первый CLAUDE.md для домашнего кластера содержал ровно три правила: не трогать ZFS-пулы, согласовывать изменения в Nginx и всегда делать бэкап перед обновлением. Этого хватило, чтобы предотвратить два потенциальных инцидента в первый же месяц.

С практической точки зрения, вот как я рекомендую внедрять правила:

1. Заведите файл CLAUDE.md в корне репозитория с инфраструктурой
2. Начните с 5–7 самых критичных правил — тех, которые предотвращают самые дорогие ошибки
3. Добавляйте новое правило каждый раз, когда LLM совершает ошибку, которую можно было предотвратить
4. Раз в квартал пересматривайте правила — удаляйте устаревшие, уточняйте неясные

Этот подход работает не потому, что он сложный, а потому, что он системный. Как и всё в инфраструктуре, что стоит делать.

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

Что такое CLAUDE.md и как он влияет на поведение Claude Code?

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

Как правильно добавить CLAUDE.md в свой проект?

Достаточно скопировать файл в корень репозитория и отредактировать его под свои нужды. Claude Code ищет его автоматически, но рекомендуется проверить, что файл действительно подхватывается: запустите claude в терминале и проверьте, что правила отображаются в начале сессии. Важно адаптировать правила под стек вашего проекта — то, что работает для Python-библиотек, может не подойдти для Go-микросервисов.

Можно ли использовать CLAUDE.md с локальными моделями вместо Claude Code?

Да, существуют форки вроде OpenClaude, которые позволяют использовать те же принципы с моделями Ollama, LM Studio и другими локальными LLM. Однако официальная поддержка Claude Code ограничена моделями Anthropic. Если вы работаете в изолированной среде, где нет доступа к облачным сервисам, стоит рассмотреть локальные альтернативы — но будьте готовы к тому, что качество исполнения правил может отличаться.

Нужно ли регулярно обновлять содержимое CLAUDE.md?

Не так часто, как обновляют зависимости в package.json, но периодически пересматривать правила имеет смысл. Когда вы добавляете новые библиотеки, меняете архитектуру или переходите на другую версию языка, набор «запретов» и «рекомендаций» может устаревать. Лично я обновляю свой CLAUDE.md раз в месяц — обычно это занимает 15–20 минут, но экономит часы на исправление LLM-решений.

Почему именно Карпатого правила получили 15 000 звёзд, а не другие наборы?

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