Sumit Pandey разобрал феномен, мимо которого трудно пройти: один файл CLAUDE.md из репозитория andrej-karpathy-skills собрал около 91 000 звёзд на GitHub без единой строки кода — четыре поведенческих правила, превращённые из наблюдений Карпатого. „Думай перед кодом“, „сначала простота“, „хирургические правки“, „исполнение по цели“. Pandey ставит точный диагноз и заканчивает фразой, которая и сделала статью громкой: «it is winning because it is not a layer. It is a contract». Я держу большой многослойный CLAUDE.md поверх машинного контекст-роутинга — и именно поэтому хочу с этим тезисом поспорить. Не опровергнуть. Уточнить границу, за которой он перестаёт работать.
Мой тезис: он прав для медианы, но «контракт» и «слой» — не оппозиция, а две точки на одной шкале
Pandey прав в главном: для медианного пользователя плоский файл из четырёх правил — это не упрощение от бедности, а заработанная простота. Большинство проектов должны начинать именно так. Но я бы развернул его метафору. «Контракт» и «слой» — это не противоположности, между которыми надо выбрать. Плоский файл — это контракт ровно до тех пор, пока одного листа правил хватает, чтобы выразить все обязательства. Слои (мой трёхосевой роутинг — это уже опубликованная история, и я её здесь не пересказываю) — это не отказ от контракта, а заработанная сложность, за которую платишь ровно один раз: когда у тебя появляется проблема, которую плоский файл физически не способен записать без противоречий. До этого момента слои — лишний шум. После — плоский файл сам становится шумом, и правила в нём гниют.
Где он прав: четыре правила закрывают реальный разрыв, и вирусность — голос за проблему
Сильнее всего в статье не сами правила, а честность про то, почему они нужны. Pandey описывает свои провалы дословно: агент к трёхстрочному кэшу пристроил dependency injection и класс с восемью методами; другой агент при починке парсинга даты «reformatted the entire file» и переписал несоседние функции. Я узнаю каждую строчку — это не экзотика, это default. Правила очевидны сеньору и неочевидны модели; ровно этот разрыв файл и закрывает. И вирусность Pandey трактует точно: 91 000 звёзд — это «not a vote on the file. It is a vote on the problem». Тихие допущения, переусложнение, расползание скоупа — три стены, в которые упирается каждый, кто всерьёз работает с агентами. Файл называет их простым языком и ставится за тридцать секунд. Согласен полностью: барьер входа решает, и для большинства это правильный первый и единственный шаг.
Где он неполон: «улучшает распределение поведения» — это и есть линия разрыва
Самая важная фраза статьи — не громкая, а тихая, в разделе оговорок: файл «improves the distribution of behavior. It does not guarantee specific behavior». Pandey честно кладёт её на стол и идёт дальше. Я на ней останавливаюсь, потому что здесь проходит шов, который и определяет, что вообще можно писать в CLAUDE.md.
Markdown-инструкция — это вероятностное смещение, а не гарантия. Для мягких предпочтений этого достаточно: стиль именования, выбор фреймворка, политика тестов, «не рефактори соседний код». Если модель в одном случае из двадцати нарушит стиль — я переживу, ревью поймает. Но есть класс правил, для которых «улучшенное распределение» — это провал, а не успех. Комплаенс и безопасность прода нельзя выражать как предпочтение. Прецедент, который промпт не способен записать честно: «для удалёнок вида github.com/OEM-WEB/* коммиты и PR не должны содержать трейлер Co-Authored-By: Claude». Плоский поведенческий файл может это попросить. Он не может это обеспечить — потому что инструкция-проза по определению необязательна к исполнению, а юридическое требование заказчика на «улучшенное распределение» не делится.
Отсюда моя жёсткая линия в авторинге. Мягкие предпочтения живут в markdown — там им и место, и плоского файла там хватает почти всем. Комплаенс и prod-safety я механизирую: детект удалёнки перед коммитом, гейт именованного одобрения перед действиями над продом, инъекция нужного контекста хуком на старте сессии. Не потому что я люблю слои — я их не люблю, они стоят сопровождения. А потому что промпт неисполним по своей природе, и единственный способ превратить «попросил» в «гарантировал» — вынести правило из прозы в исполняемый механизм. Это и есть тот случай, где «контракт-как-текст» Pandey ломается и должен уступить место «контракту-как-обвязке».
Что с этим делать: начни плоско, расслаивай только когда масштаб заставит
Из этого выходит правило, по которому я бы строил CLAUDE.md сегодня — и оно почти всегда даёт ответ «оставайся плоским».
Начинай с плоского файла. Четыре правила Pandey плюс твои конвенции проекта — именование, фреймворк, тесты. Это контракт, и для одного проекта в одной организации он самодостаточен. Не строй роутинг, которого нет повода строить.
Не расслаивай по вкусу — расслаивай по тревожному сигналу. Чтобы это не было отговоркой, нужен фальсифицируемый порог. Мой триггер на слои срабатывает, когда выполнено хотя бы одно: (а) у тебя две и более организации с конфликтующими комплаенс-правилами, которые плоский файл не запишет без самопротиворечия; либо (б) появилось правило, которое нужно гарантировать, а не попросить — то есть нарушение стоит не ревью, а инцидента. Пока ни один из порогов не сработал — плоский файл строго лучше. Слои, добавленные раньше, — это сложность, за которую ты платишь без проблемы, которую она решает.
Раздели то, что просишь, и то, что обеспечиваешь. Прежде чем дописать строку в CLAUDE.md, спроси: это предпочтение или обязательство? Предпочтение — в markdown, и спасибо Pandey за то, что показал, как мало для этого нужно. Обязательство — из прозы в механизм: хук, гейт, проверка перед коммитом. Если правило важно ровно настолько, что «улучшенного распределения» мало, — значит, ему не место в файле, который только улучшает распределение.
Итог короткий. Pandey прав, и его правота важнее, чем кажется по громкости тезиса: почти всем нужен плоский контракт, и почти все его переусложняют. Но плоский файл и многослойный роутинг — не лагеря, а два конца одной шкалы заработанной сложности. Начинай слева. Двигайся вправо, только когда у тебя на руках комплаенс-проблема, которую лист правил не выражает, или требование, которое прозу нельзя оставить просьбой. И тогда честный вывод из статьи Pandey не «контракт победил слои», а «пиши в прозе всё, что можно попросить, и механизируй всё, что обязан гарантировать».