Правила CLAUDE.md от Карпати + еще 8: шаблон из 12 правил, протестированный на 30 кодовых базах

Конец января 2026 года: Андрей Карпатый публикует тред в X с жалобами на то, как Claude пишет код. Три сценария отказа — скрытые неверные предположения, избыточное усложнение и ортогональный ущерб коду, который не следовало трогать. Форрест Чанг читает тред, упаковывает жалобы в 4 правила поведения в одном файле CLAUDE.md и выкладывает его на GitHub. 5 828 звезд за первый день. 60 000 закладок за две недели. 120 000 звезд к середине 2026 года. Самый быстрорастущий однофайловый репозиторий года. 9 мая 2026 года верифицированный разработчик с ником @mnilax (Mnimiy) опубликовал в X лонгрид с одним из самых смелых инженерных заявлений года: они тестировали шаблон на 30 кодовых базах в течение 6 недель, а затем добавили еще 8 правил, чтобы закрыть пробелы. 2,7 миллиона просмотров, 18 800 закладок. Это полный разбор — и то, что это значит, если вы запускаете Claude внутри Antigravity (или любой другой Agent-First IDE) с GEMINI.md или AGENTS.md файлом.

Оригинальный X-пост от @mnilax, который разбирает эта статья — 2,7 млн просмотров, 18,8 тыс. закладок, 9 мая 2026 г.

1. Виральный момент

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

1. Скрытые неверные предположения. Claude додумывает, что вы имели в виду, строит логику на неверном выводе и никогда не сообщает об этом.
2. Избыточное усложнение. Claude тянется к абстракциям, слоям и универсальным хелперам. Исправление из 4 строк превращается в 40.
3. Ортогональный ущерб. Claude "улучшает" код, который не следовало трогать — пробелы, именование, форматирование, соседние функции, о которых его не просили.

Форрест Чанг прочитал тред и сделал работу, которую не сделал никто другой: он записал то, о чем Карпатый просил неявно. Четыре коротких императивных правила. Один файл. 65 строк. Публичный репозиторий. Темп важен — Форрест не добавлял комментариев, не превращал это в фреймворк и не монетизировал. Только правила.

Это попало в точку. Разработчики, которые каждый день сражались с Claude, внезапно получили способ установки в одну строку: вставьте этот файл в корень вашего репозитория. Метрики говорят сами за себя — 120 000 звезд у файла, в котором нет кода. Большинство этих разработчиков до сих пор используют только эти четыре правила.

2. Оригинальные 4 правила (Карпатый через Форреста Чанга)

Вот база — правила в их исходном виде. Если у вас еще нет CLAUDE.md, начните с этих:

Данные Mnimiy: эти четыре правила закрывают ~40% сценариев отказа в автономных сессиях Claude Code. Остальные ~60% кроются в пробелах, которые оригинальный шаблон не учитывает.

3. Почему потребовалось расширение

Шаблон был написан в январе 2026 года. Экосистема Claude Code в мае 2026 года — это уже совсем другой зверь. В статье выделяются четыре реалии, возникшие после января, которые не охвачены исходными 4 правилами:

• Конфликты агентов. Мультиагентные конфигурации, где два агента редактируют одни и те же файлы и мешают друг другу. Правила Карпати подразумевают один цикл автодополнения. Реальная мультиагентная оркестрация требует правил владения.
• Каскады хуков. Хуки Claude Code срабатывают при каждом вызове инструмента. Без лимитов один "болтливый" хук превращает запрос на 200 токенов в 8 000 токенов.
• Конфликты загрузки навыков. Несколько Навыков с пересекающимися описаниями путают диспетчер сопоставления описаний. В оригинальном шаблоне ничего не сказано о том, как устранять такие неоднозначности.
• Многошаговые рабочие процессы. Если рефакторинг из 6 шагов идет не так на 4-м шаге, это означает, что шаги 5 и 6 строятся на сломанном состоянии. Оригинальный шаблон рассматривает каждый ход Claude как one-shot.

Тезис Mnimiy's: оригинальные 4 правила являются фундаментальными, а не ошибочными. Они просто неполные.

4. 8 новых правил (каждое с моментом, который его породил)

Каждое из них возникло из конкретного инцидента в ходе исследования 30 кодовых баз. В статье показан сначала момент, затем правило. Ниже: та же структура в сокращенном виде.

Правило 5 — Не заставляйте модель выполнять неязыковую работу

Детерминированные решения должны приниматься в детерминированном коде. Политики повторных попыток, маршрутизация, пороги эскалации — а не вызовы LLM. Модель принимает решения по-разному каждую неделю.

Момент: Вызов LLM "решить, стоит ли повторять попытку при 503" работал две недели, а затем начал сбоить, потому что модель стала воспринимать тело запроса как контекст для принятия решения. Политика повторов стала случайной, так как промпт фактически стал случайным.

Правило 6 — Жесткие бюджеты токенов, без исключений

Каждый цикл рискует превратиться в бесконтрольный дамп контекста на 50 000 токенов. Модель не остановится сама по себе. Бюджеты дают вам жесткий предел.

Момент: 90-минутная сессия отладки с итерациями над одним и тем же сообщением об ошибке размером 8KB. К концу Claude предлагал исправления, которые пользователь отклонил 40 сообщений назад. Бюджет токенов прервал бы цикл на 12-й минуте.

Правило 7 — Выявляйте конфликты, а не усредняйте их

Когда две части кодовой базы противоречат друг другу, Claude пытается угодить обеим. В результате получается бессвязный код, который сочетает оба паттерна и не работает корректно ни в одном из случаев.

Момент: В кодовой базе было два паттерна обработки ошибок — async/await с try/catch и глобальный error boundary. Claude написал код, который делал и то, и другое. Ошибки «проглатывались» дважды. Потребовалось 30 минут, чтобы разобраться.

Правило 8 — Сначала читай, потом пиши

«Surgical Changes» Карпатого велят Claude не трогать соседний код. Но они не велят Claude понимать соседний код. Без этого дополнения Claude пишет новый код, который конфликтует с существующим кодом в 30 строках от него.

Тот самый момент: Claude added a function next to an existing identical function it hadn't read. The new one won by import order. The original had been the source of truth for 6 months.

Правило 9 — Тесты обязательны, но они не самоцель

Goal-Driven Execution считает успехом прохождение тестов. На практике Claude пишет код, который проходит поверхностные тесты, ломая при этом поведение в продакшене.

Тот самый момент: 12 тестов для функции аутентификации, все пройдены, но в продакшене аутентификация сломана. Тесты проверяли, что функция возвращает что-то, а не то, возвращает ли она правильный результат. Функция проходила тесты, потому что возвращала константу.

Правило 10 — Длительным операциям нужны чекпоинты

Оригинальный шаблон предполагает разовые взаимодействия. Реальная работа с Claude Code многоэтапна — рефакторинг 20 файлов, создание фич в течение сессии, отладка через несколько коммитов. Без чекпоинтов одна ошибка приводит к потере всего прогресса.

Тот самый момент: Рефакторинг из 6 шагов пошел не так на 4-м шаге. Claude продолжил выполнять шаги 5 и 6 поверх сломанного состояния. Распутывание этого заняло больше времени, чем повторный рефакторинг с нуля.

Правило 11 — Соглашения важнее новшеств

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

Тот самый момент: Claude внедрил React-хуки в кодовую базу на классовых компонентах. Хуки работали. Но они также сломали паттерны тестирования, которые полагались на componentDidMount. Полдня на удаление и переписывание.

Правило 12 — Ошибайся заметно, а не молча

Самые дорогие сбои Claude выглядят как успех. Функция "работает", но возвращает неверные данные. Миграция "завершается", но пропускает 30 записей. Тест "проходит", но assertion был неверным.

Момент: Claude сообщил, что миграция базы данных "завершена успешно." Он молча пропустил 14% записей, столкнувшихся с constraint violation. Пропуск был залогирован, но не выведен наружу. Обнаружено 11 дней спустя, когда отчеты начали выглядеть неправильно.

5. Цифры

Mnimiy отслеживал одни и те же 50 репрезентативных задач в 30 кодовых базах в течение 6 недель в трех конфигурациях: без CLAUDE.md, оригинальные 4 правила, полные 12 правил. Mistake rate — это доля задач, потребовавших исправления или переписывания для соответствия намерению — подсчитано по семи различным типам сбоев (silent wrong assumption, over-engineering, orthogonal damage, silent failure, convention violation, conflict averaging, missed checkpoint).

Основное снижение (41% → 3%) — это очевидный результат. А интересный результат заключается в том, что переход от 4 правил к 12 добавил почти нулевые накладные расходы на compliance (78% → 76%), при этом снизив mistake rate еще на 8 пунктов. Новые правила охватывают типы сбоев, которые не затрагивали исходные 4 — они не конкурируют за один и тот же бюджет внимания.

Это эмпирический аргумент в пользу использования более чем 4 правил. Если бы добавление правил пропорционально снижало compliance, стои

6. Where the Original Template Silently Breaks

Четыре сценария, в которых 4 правила Карпати недостаточно — еще до добавления новых правил. В статье четко указано, что оригинал не ошибочен, он просто ориентирован на задачи января 2026 года:

1. Длительные задачи агентов. Правила нацелены на момент, когда Claude пишет код. Они ничего не говорят о многошаговых пайплайнах. Нет правила бюджета. Нет правила контрольных точек (checkpoint). Нет правила «громкого отказа» (fail-loud). Пайплайны деградируют.
2. Согласованность между несколькими кодовыми базами. "Match existing style" предполагает наличие одного стиля. В монорепозитории с 12 сервисами Claude должен выбрать, какой стиль использовать. Оригинальные правила не говорят ему, как это сделать. Он выбирает случайно или усредняет.
3. Качество тестов. Goal-Driven Execution считает прохождение тестов успехом. Но там не сказано, что тесты должны быть осмысленными. В итоге получаются тесты, которые не проверяют ничего полезного, но придают Claude уверенности.
4. Продакшн против прототипа. Те же 4 правила, которые защищают продакшн-код от избыточного проектирования (over-engineering), замедляют работу над прототипами, где оправданно нужны 100 строк временного каркаса (scaffolding) для поиска направления. "Simplicity First" срабатывает излишне на ранних этапах написания кода.

7. Что не сработало (неудачные эксперименты)

Возможно, самый полезный раздел статьи — не те правила, которые прошли отбор, а паттерны, которые явно не подошли:

• Правила, собранные из социальных сетей. Большинство из них были либо перефразированием 4 правил Карпати, либо узкоспециализированными правилами ("always use Tailwind classes"), которые не масштабируются. Исключены.
• Более 14 правил. Mnimiy протестировал до 18 правил. После 14 соблюдение правил упало с 76% до 52%. Лимит в 200 строк, о котором пишет Anthropic, реален — после него Claude просто понимает, что «правила существуют», но не читает их.
• Правила, зависящие от инструментов. Правило "Always use eslint" молча ломается, если eslint не установлен. Заменено на формулировки, не зависящие от конкретных возможностей: "match the codebase's enforced style."
• Примеры вместо правил. Три примера занимают столько же контекста, сколько ~10 правил, и Claude переобучается (over-fits) под них. Правила абстрактны, примеры конкретны. Используйте правила.
• Расплывчатые усилители. "Be careful," "think hard," "really focus." Compliance ~30% because none of those are testable. Replaced with concrete imperatives like "state assumptions explicitly."
• Identity prompts. Telling Claude to be "senior" doesn't work. Claude already thinks it's senior. The compliance gap is between thinking and doing. Imperatives close it; identity prompts don't.

8. The Mental Model

Strip the article down to its load-bearing sentence and you get this:

This reframes everything. Most developers treat CLAUDE.md as a personal preferences file — a list of stylistic likes and dislikes that grows over time. The article's argument is that a preferences file is the wrong shape. The right shape is a list of failure modes you've actually hit, with one rule per mode.

It also explains why the article ends with a counterintuitive recommendation:

A 6-rule CLAUDE.md tuned to your real failure modes beats a 12-rule one with 6 rules you'll never need.

Don't paste all 12 because someone on X said so. Read them, keep the ones that map to mistakes you've made, drop the rest.

9. Mapping It to Antigravity (GEMINI.md / AGENTS.md)

The article is Claude-focused, but the abstraction is portable. Antigravity reads procedural rules from two files in the same shape:

• GEMINI.md — the Gemini-specific system prompt file. See our GEMINI.md guide.
• AGENTS.md — the cross-tool format (works with Claude Code, Cursor, Antigravity). See our Руководство AGENTS.md.

Оба носят рекомендательный характер, а не обязательный; оба ограничены примерно 200 строками, после чего точность соблюдения правил падает; оба следуют одной и той же дисциплине: "сформулируй правило, без примеров, без расплывчатых усилителей". 12 правил переносятся практически без изменений. Специфические соображения для Antigravity:

1. Правило 6 (бюджеты токенов) становится критически важным, а не опциональным. Квота Antigravity расходуется быстрее, чем в Claude Code. Используйте это правило вместе с нашим руководством по сокращению токенов.
2. Правило 10 (контрольные точки) соотносится с Agent Manager в Antigravity. Если запуск нескольких агентов пойдет не так на 4-м шаге, вам нужно иметь возможность остановить агента и возобновить работу с предыдущего артефакта, а не с самого начала.
3. Правило 7 (выявление конфликтов) помогает при смене моделей. Если вы переключаетесь между Gemini и Claude Opus посреди сессии (как описано в нашем анализе смены моделей), новая модель часто наследует устаревший контекст от старой и пытается согласовать несовместимые паттерны.
4. Правило 12 (явные ошибки) — самое недооцененное для Autopilot. Если вы запускаете auto-accept, скрытые ошибки накапливаются в течение нескольких циклов Cmd-Enter, прежде чем вы их заметите. Заставьте агента выводить каждый пропущенный шаг.

Тот же шаблон, другая среда выполнения, та же логика.

10. Полный шаблон из 12 правил (готов к копированию)

Сохраните это как CLAUDE.md (или GEMINI.md или AGENTS.md) в корне вашего репозитория. В оригинальной статье отмечается: общий размер файлов не должен превышать 200 строк в сумме, включая любые специфичные для проекта дополнения ниже, иначе уровень соблюдения правил снижается.

Это тот самый файл. С ним нужно сделать две вещи:

1. Честно прочитайте все 12 правил. Какие из них соответствуют ошибкам, которые вы реально совершили в этом месяце? Оставьте их. Остальное удалите. Файл из 6 правил, адаптированный под ваши типичные ошибки, эффективнее, чем файл из 12 правил, которые вы никогда не нарушите.
2. Добавьте специфичные для проекта правила ниже. Stack-specific ("always use the Repository pattern"), test-runner ("run pnpm test:unit before reporting done"), error patterns. Keep the total under 200 lines.

11. FAQ