Karpathy-Inspired Guidelines: четыре принципа, которые делают Claude Code адекватнее

В декабре 2025 года Андрей Карпатый опубликовал в X заметку о типичных проблемах LLM в роли кодеров. Пост собрал огромный резонанс — ребята из сообщества быстро оформили его в готовый к использованию набор инструкций для Claude Code. Сейчас этот репозиторий multica-ai/andrej-karpathy-skills набрал 189 тысяч звёзд и стал одним из самых популярных skill-паков для AI-кодинга.

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

Что не так с LLM-кодерами

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

«Модели делают неверные предположения от вашего имени и просто бегут вперёд, не проверяя. Они не управляют своим замешательством, не ищут уточнений, не подсвечивают противоречия, не показывают trade-off, не спорят, когда стоило бы.»

«Они обожают усложнять код и API, раздувать абстракции, не убирают мёртвый код… реализуют конструкцию на 1000 строк там, где хватило бы 100.»

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

Звучит знакомо, правда? Все эти штуки я видел в своей работе с агентами сотни раз. Самое неприятное — второе: когда модель тихо выбирает интерпретацию задачи, делает 800 строк «на вырост», а ты обнаруживаешь это через два часа в PR-ревью.

Четыре принципа

Весь набор — это по сути четыре коротких правила. У каждого есть название, простая формулировка и набор конкретных поведенческих установок.

1. Think Before Coding

Не предполагай. Не прячь замешательство. Показывай trade-off.

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

Принцип заставляет модель:

• Явно проговаривать допущения — если не уверена, спросить, а не угадывать
• Показывать несколько интерпретаций — не выбирать молча, когда есть неоднозначность
• Спорить, когда есть основания — если есть более простой подход, сказать об этом
• Останавливаться, когда непонятно — назвать, что именно неясно, и попросить уточнить

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

2. Simplicity First

Минимум кода, который решает задачу. Никакой спекуляции.

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

Правило говорит:

• Никаких фич сверх того, что просили
• Никаких абстракций ради однократного использования
• Никакой «гибкости» и «конфигурируемости», которую не запрашивали
• Никакой обработки ошибок для невозможных сценариев
• Если 200 строк можно свести к 50 — переписать

Тест: согласился бы старший инженер, что это переусложнение? Если да — упрощай.

Это зеркально к первому принципу. Если первый учит думать ДО написания кода, то этот — думать ВО ВРЕМЯ и не плодить лишнее.

3. Surgical Changes

Трогай только то, что должен. Убирай только за собой.

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

Правила для редактирования существующего кода:

• Не «улучшай» соседний код, комментарии, форматирование
• Не рефактори то, что не сломано
• Подстраивайся под существующий стиль, даже если сделал бы иначе
• Если видишь неотносящийся мёртвый код — упомяни, но не удаляй

Когда твои изменения создают сирот:

• Убирай импорты, переменные, функции, которые ТВОИ изменения сделали неиспользуемыми
• Не трогай уже существующий мёртвый код, если не просили

Тест: каждая изменённая строка должна напрямую следовать из запроса пользователя.

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

4. Goal-Driven Execution

Определи критерии успеха. Крутись, пока не подтвердил.

Это, пожалуй, самый неочевидный, но мощный принцип. Он превращает императивные задачи в декларативные цели с проверяемыми результатами.

Вместо «добавь валидацию» — «напиши тесты на невалидные входы, потом сделай, чтобы они проходили».
Вместо «почини баг» — «напиши тест, который его воспроизводит, потом почини».
Вместо «отрефактори X» — «убедись, что тесты проходят до и после».

Для многошаговых задач — короткий план с проверками:

1. [Шаг] → проверить: [что]
2. [Шаг] → проверить: [что]
3. [Шаг] → проверить: [что]

Сильные критерии успеха позволяют LLM крутиться в цикле самостоятельно. Слабые («сделай, чтобы работало») требуют постоянных уточнений.

Карпатый формулирует это так:

«LLM исключительно хороши в зацикливании, пока не достигнут конкретных целей… Не говорите ей, что делать, — задайте критерии успеха и смотрите, как она работает.»

Этот принцип перевернул моё отношение к написанию задач для агентов. Когда я формулирую результат как «есть зелёные тесты на X, Y, Z» вместо «добавь валидацию» — качество работы сразу растёт. Агент сам решает, как туда добраться, и может итерировать без моего участия.

Как установить

Есть три пути, в зависимости от того, что вам нужно.

Вариант A: плагин для Claude Code (рекомендуемый)

Изнутри Claude Code добавляем маркетплейс:

/plugin marketplace add forrestchang/andrej-karpathy-skills

Потом ставим сам плагин:

/plugin install andrej-karpathy-skills@karpathy-skills

После этого принципы доступны во всех ваших проектах через механизм плагинов.

Вариант B: CLAUDE.md в конкретном проекте

Для нового проекта:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Для существующего (дописываем в конец):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Подходит, когда хочется, чтобы правила действовали только в рамках одного репозитория. Например, если у вас опенсорс-проект, куда контрибьютят разные люди, и вы не хотите глобально настраивать Claude Code.

Вариант C: Cursor

В репозитории лежит готовый Cursor rule в .cursor/rules/karpathy-guidelines.mdc. Это значит, что в Cursor правила подхватятся автоматически. Подробности — в CURSOR.md.

Что в итоге получите

Авторы выделяют несколько сигналов, что принципы реально работают:

• Меньше лишних изменений в diff — появляется только то, что просили
• Меньше переделок из-за переусложнения — код сразу простой
• Уточняющие вопросы приходят ДО реализации — а не после ошибок
• Чистые, минимальные PR — никаких «заодно подправил»

У меня лично первые два пункта видны сразу. Когда в CLAUDE.md есть Simplicity First и Surgical Changes, модель реже уходит в «давай я ещё улучшу» и реже расковыривает соседний код. Это сокращает ревью с получаса до пяти минут.

Кастомизация под проект

Базовый набор принципов намеренно общий. Под свой проект стоит добавить блок типа:

## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

То есть четыре принципа Карпатого остаются как культурный слой, а поверх них — ваши инженерные конвенции.

Важный нюанс про trade-off

Принципы сдвинуты в сторону осторожности, а не скорости. Авторы прямо об этом пишут: для тривиальных задач (исправить опечатку, поменять имя переменной) включать всю машинерию не нужно. Это инструмент для нетривиальной работы, где цена ошибки высока.

Цель — снизить число дорогих промахов в серьёзных задачах, а не затормозить работу на простых.

Что в репозитории ещё

Помимо самого CLAUDE.md, в репозитории есть:

• EXAMPLES.md — примеры применения принципов на конкретных задачах
• CURSOR.md — инструкция по настройке для Cursor
• .claude-plugin/ — манифест плагина
• skills/karpathy-guidelines/ — skill в формате Claude Code

Лицензия — MIT, можно использовать в коммерческих проектах, форкать и адаптировать.

Итог

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

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

Репозиторий: github.com/multica-ai/andrej-karpathy-skills