Обязателен ли CLAUDE.md для Claude Code? Проверил Karpathy Skills на 10 реальных тикетах

Сначала цифры. Чтобы понять, работают ли Karpathy Skills (поведенческие правила сообщества в CLAUDE.md), я взял 10 реальных тикетов, зафиксировал Claude Opus 4.8 и менял только наличие четырёх принципов Karpathy. За неделю запомнились такие результаты:

Был и разочаровывающий случай — тикет с правкой одной константы: правила почти не помогли, зато добавился лишний раунд «уточнить допущения». Ниже — и успехи, и провалы, плюс финальная версия CLAUDE.md из нашего репозитория (её ищут по Claude Code Rules / Claude Code Prompt).

Почему Claude Code лезет не туда

Дело не в «слабой модели», а в том, что цель по умолчанию расходится с инженерной: быстрее выдать «законченно выглядящий» патч — больше абстракций, соседние файлы, меньше вопросов про неоднозначность. Andrej Karpathy на X описал четыре хронических симптома: код до уточнений, over-engineering простых задач, «заодно поправлю соседний файл», «готово» вместо проверяемой цели.

Весной 2026 сообщество упаковало это в CLAUDE.md на несколько десятков строк (forrestchang/andrej-karpathy-skills, Karpathy Skills). Нового рантайма нет — только четыре поведенческих контракта, которые Claude Code читает каждую сессию. Мне нужны были не слухи, а I tested it — какие цифры.

Что такое Karpathy Skills

В названии Skills, по форме — файл инструкций проекта. Это не Skills OpenAI GPT и не плагин SKILL.md OpenHuman. Claude Code при старте сессии читает CLAUDE.md в корне (и эквивалент из глобального плагина) и до первой строки вашего запроса задаёт, как агент думает и режет diff.

Четыре принципа соответствуют upstream CLAUDE.md:

• Think Before Coding: назвать допущения, вынести неоднозначность, предложить более простой путь — не молча выбрать одну трактовку.
• Simplicity First: минимум кода для задачи; отказ от лишних абстракций, конфигов и слоёв «на будущее».
• Surgical Changes: только нужные строки; без «улучшения» соседнего кода и форматирования; свой мёртвый код убрать, чужой legacy — только отметить.
• Goal-Driven Execution: багфикс и валидация как проверяемая цель (сначала падающий тест, потом зелёный); у многошаговых задач — verify на каждом шаге.

Два пути: плагин Claude Code /plugin install andrej-karpathy-skills@karpathy-skills или слияние upstream CLAUDE.md в корень — ниже «финальная версия» готова к копированию.

Как устроен эксперимент

Переменные под контролем (прогон на Mac mini M4 Cloud Mac — tmux и xcodebuild без обрывов; цифры воспроизводимы и на локальном Mac):

• 10 реальных тикетов: 4 мелких Swift-фичи, 2 переименования через файлы, 2 добавления тестов, 2 CI-скрипта.
• Модель фиксирована: claude-opus-4-8, Effort high, без минорных апдейтов в ту же неделю.
• Единственная переменная: контроль — старый CLAUDE.md без Karpathy; эксперимент — четыре принципа + две командные строки ниже.
• Каждый тикет дважды (A→B или через день) — чтобы сгладить «сегодня агент в ударе».

Пять метрик — то, что реально съедает время на ревью:

Результаты по 10 тикетам

Таблица — медианы (n=10, не официальный бенч). Если запомнить одно число: несвязанный diff −78%.

18% → 4% по несвязанным путям — файлов всё ещё много, но «заодно отформатировали Payment» исчезло из diff: кривая Surgical Changes. 5/10 → 8/10 первого CI — в основном Goal-Driven Execution: чаще сначала падающий тест, потом реализация.

Где эффект максимален

• Переименования / смена сигнатур через файлы: −78% несвязанного diff ощущается сильнее всего; CR перестаёт быть «минным полем».
• Мелкие фичи с размытым ТЗ: Think Before Coding вытаскивает гипотезы заранее; откат 3 → 1 итерация (PAY-1842, AUTH-901).
• Тесты + реализация: растёт доля «с первого зелёного»; формулировка «красный → зелёный» в CLAUDE.md стабилизирует поведение.

Не путать с графом знаний кода: граф отвечает «где править», CLAUDE.md — «не трогай лишнее».

Где почти нет эффекта (с провалом)

Разочарование: одна константа. Тикет CFG-77: maxRetryCount 3→5, путь указан. С Karpathy агент всё равно спросил: «Менять ли стратегию backoff и дефолты в unit-тестах?» — +1 раунд уточнений, diff такой же чистый, как без правил, +4 минуты суммарно. При кристально ясной точечной правке осторожность четырёх принципов даёт почти нулевой выигрыш.

Ещё почти бесполезно:

• Длинный командный CLAUDE.md уже дублирует Karpathy — убывающая отдача.
• Нет тестов / xcodebuild — Goal-Driven не замыкается, остаётся «вроде готово».
• Только чат, без записи в репозиторий — CLAUDE.md не загружается.

Моя финальная CLAUDE.md (копировать)

Ищут CLAUDE.md, Claude Code Rules, Claude Code Prompt — нужен готовый текст в репозиторий. Ниже слияние четырёх принципов Karpathy и двух iOS-правил команды (тело на английском — так модель следует стабильнее; пояснения вокруг — по-русски):

# CLAUDE.md — Karpathy rules + Vuncloud iOS team

## Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: state assumptions; if unclear, ask; if a simpler approach exists, say so.

## Simplicity First
Minimum code that solves the problem. Nothing speculative.
No extra abstractions, config, or error handling for impossible cases.

## Surgical Changes
Touch only what you must. Don't "improve" adjacent code or formatting.
Match existing style. Mention unrelated dead code; don't delete unless asked.

## Goal-Driven Execution
Transform tasks into verifiable goals (tests first when applicable).
Multi-step: list plan with verify check per step.

## Vuncloud: Build Verification (custom)
After code changes to Swift/ObjC targets, run before claiming done:
  xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'
Report exit code. If tests fail, fix or stop — do not claim success.

## Vuncloud: Path Allowlist (custom)
Unless the user explicitly expands scope, only edit paths they named
or standard paired test paths (e.g. Sources/Foo/ ↔ Tests/Foo/).

Upstream одной командой:

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

# or per-project:
curl -fsSL -o /tmp/karpathy-claude.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# merge paragraphs; do not overwrite existing CLAUDE.md

Для Cursor: синхронизируйте .cursor/rules/karpathy-guidelines.mdc с тем же смыслом. При замере Karpathy фиксируйте claude-opus-4-8, не смешивайте с апгрейдом модели — см. гайд по длинным сессиям Opus 4.8.

Cloud Mac для длинных сессий (Claude Code → tmux → Mac mini)

Здесь Cloud Mac уместнее OpenHuman: цепочка замкнута — длинная сессия Claude Code → tmux против обрыва SSH → xcodebuild на той же машине → выделенный Mac mini. A/B, ночной агент и CR через часовые пояса боятся сна ноутбука; в пилоте Cloud Mac давал только стабильную среду, сами цифры повторяются локально.

• tmux + Claude Code: обрыв SSH не убивает сессию (пример в статье про Opus 4.8).
• CLAUDE.md на постоянном томе: правила и monorepo вместе, настройки не теряются.
• Жёсткая Goal-Driven приёмка: Build Verification в CLAUDE.md — отчёт только после прогона Scheme.
• Облачный Mac CI на той же машине — правка и проверка сразу.

Фрагмент скрипта для A/B

TASK_ID="PAY-1842"
git diff --stat main...HEAD > "/tmp/${TASK_ID}-stat.txt"
git diff --name-only main...HEAD | wc -l | awk '{print "files_changed=" $1}'
# unrelated paths: manual or allowlist compare
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16' \
  | tee "/tmp/${TASK_ID}-xcodebuild.log"
echo "exit=$?" >> "/tmp/${TASK_ID}-xcodebuild.log"

В Claude Code формулируйте задачу через цель — так четвёртый принцип срабатывает стабильнее:

Цель: добавить проверку неположительных значений в CheckoutViewModel.validateAmount.
Проверка: 1) unit-тесты на 0, отрицательные числа и NaN; 2) xcodebuild test -scheme YourApp проходит;
Область: только Sources/Checkout/ и соответствующие Tests/. Не трогать UI-тему и другие модули.

Частые вопросы (FAQ)

Karpathy сам написал CLAUDE.md? Принципы из его наблюдений на X; файл собрало сообщество (Forrest Chang и др.). Karpathy ретвитил репозиторий — ориентируйтесь на README upstream.

Конфликт с memory / описанием проекта Claude Code? Нужно слияние: четыре принципа в начале, дальше — ваши naming, ветки, команды тестов.

Заменяет code review? Нет. Шум в diff падает, но merge gate, ручной CR и security scan остаются обязательными.

Cursor? Копия в .cursor/rules/; в одном git — тот же смысл, что в Claude Code.

Можно цитировать проценты? Цитируйте свой A/B. Таблица здесь — пилот Vuncloud (n=10, без строгого двойного слепого протокола).

Итог

Karpathy Skills я измерил — не «вообще полезно или нет». 10 тикетов, Opus 4.8 фиксирован: несвязанный diff ~ −78%, первый зелёный CI +30 п.п.; правка константы почти не помогает. Ценность — CLAUDE.md в репозитории: четыре принципа Karpathy плюс ваши правила сборки и путей. Для Claude Code 7×24 Mac mini Cloud Mac + tmux естественнее OpenHuman: агент, терминал и Xcode должны жить на одном macOS.