Пять правил, которые Claude Code не обойдёт
Мы поручили Claude Code настоящие задачи в нашем собственном API для выставления счетов на TypeScript и поймали его на том, что вместо повторного использования валидатора он его скопировал. В этой статье пять правил против гниения кодовой базы и для каждого из них хук или настройка Claude Code, которая это правило обеспечивает. В документации Anthropic сказано, что файл CLAUDE.md это контекст, а не принудительная конфигурация, поэтому правило, записанное там, остаётся фразой, которую модель взвешивает против задачи. Механизмы ниже это файлы, которые запускает сама оболочка: блокировщик дублирования, срабатывающий сразу после правки, ход, который нельзя закончить при красных тестах, и конфигурационные шлюзы, которых агент не может коснуться.
Правило, которое вы пишете, и проверка, которую запускает оболочка
Хук Claude Code это небольшой скрипт, который запускает сам Claude Code в заданный момент, до или после вызова инструмента. Если скрипт завершается с кодом ошибки, то, что он напечатал, возвращается Claude как отказ. Рекомендации Anthropic делят инструкции на два вида: те, что вы пишете, а модель читает (промпт, файл CLAUDE.md, skill), и те, что вы настраиваете, а оболочка исполняет (хук, правило deny, управляемая настройка). В документации по памяти сказано, что CLAUDE.md предназначен для рекомендаций и что Claude может решить, что рекомендация к случаю не относится.
Мы проверили это разделение на небольшом API для счетов, не написав ни одного правила, и попросили Claude сделать периодические расписания и CSV-выгрузку отчёта о неоплаченных счетах. Claude вернулся с зелёным результатом: проверка типов проходит, все тесты проходят. Детектор дублирования рассказал другое: парсер счетов был построчно скопирован в новый парсер расписаний, а поиск клиента в обработчике был скопирован в новый обработчик.
| Настройка | Функции | Найдено точных клонов | Тестов проходит |
|---|---|---|---|
| Правила записаны прозой в CLAUDE.md | 1 | 0 | 45 |
| Правила не записаны | 1, затем ещё одна сверху | 3, по-прежнему 3 | 47, затем 55 |
В отчётах Claude клоны оставались невидимыми обе функции подряд. Все механизмы этой статьи живут в одном файле настроек внутри папки .claude, с блоком хуков и списком запретов.
Правило первое: переиспользуй, прежде чем писать
Механизм это хук PostToolUse на инструментах Edit и Write. Скрипт читает из входных данных путь изменённого файла, запускает jscpd на папке с исходниками и сравнивает число клонов с базовым значением, хранящимся в репозитории, так что старое дублирование не блокирует сегодняшнюю работу. Если число выросло, скрипт печатает правило и место двойника и завершается с кодом 2. В справочнике по хукам сказано, что после выполнения инструмента код 2 показывает сообщение Claude, а скрипт, завершившийся с кодом 0, не виден никогда, что бы он ни напечатал.
При повторе задачи с расписаниями с установленным хуком Claude написал новый обработчик, хук сработал сразу и назвал двойником поиск клиента в обработчике счетов. Следующей репликой Claude сказал, что проверка теперь есть в обоих обработчиках и что он вынесет её в репозиторий клиентов одним методом, вызываемым из обоих мест. В конце детектор был чист, а общая проверка жила в одном месте.
Ограничения: jscpd ловит точную копию, но не вспомогательную функцию, переписанную с нуля, а хук, запускаемый после правки, не может её отменить. Он даёт обратную связь.
Правило второе: никаких модулей, о которых никто не просил
Механизм это хук PreToolUse на инструменте Write. Скрипт проверяет одно: находится ли путь внутри папки с исходниками и не существует ли файл. Если да, он печатает JSON-решение ask с причиной, и Claude Code превращает его в запрос разрешения. В справочнике по хукам у хука PreToolUse четыре возможных решения: allow, deny, ask или defer.
При повторе Claude Code останавливался и спрашивал перед каждым новым модулем функции расписаний. Функции нужны были модуль расписания, хранилище и обработчик, как в остальном репозитории, поэтому каждый из них был одобрен. Более поздняя просьба перенести CSV-помощники в новый модуль utils вызвала тот же запрос, который был отклонён: Claude Code отверг обе записи этой пачки, ход закончился, ничего не записав, и Claude не стал пробовать снова.
Два ограничения для запущенной нами версии, 2.1.294: запрос показывает имя файла, а причина попадает в журнал Claude, а не в диалог; и файл, созданный командой оболочки, не является вызовом инструмента Write, так что этот хук он обходит.
Правило третье: соглашения это линтер, а не проза
Механизм это линтер проекта, запускаемый хуком на каждом изменённом файле. Соглашения (псевдонимы типов вместо interface, никаких enum, никакого any, доменный слой без ввода-вывода) переходят из прозы в конфигурацию ESLint: правило restricted-syntax отвергает interface или enum с собственным сообщением проекта, а правило restricted-imports не пускает работу с файлами в доменную папку. Хук PostToolUse на Edit и Write запускает ESLint на только что изменённом файле и при ошибке завершается с кодом 2, так что нарушение доходит до Claude на нужной строке.
Слова соглашения остаются в файле правил в .claude/rules/ с заголовком paths, который загружает файл, только когда Claude трогает эту папку. В документации по памяти сказано, что правило с ограничением по пути загружается, когда Claude читает, записывает или правит подходящий файл, и предупреждается, что заголовок, который не разбирается, заставляет правило загружаться везде.
Когда его попросили превратить union статусов в enum, а type в interface, Claude ничего не правил. Он сказал, что такой рефакторинг нарушит собственные правила проекта, назвал конфигурацию линтера и хук, которые отметили бы изменение, и предложил вместо этого const-объект. Когда его попросили сделать функцию праздников, где искушало чтение файла внутри домена, Claude передал список снаружи, потому что домену ввод-вывод запрещён. Хуку срабатывать не пришлось. Получив плохой файл вручную, он вернул ошибки на их строках и отказ.
Правило четвёртое: готово значит проверки пройдены
Механизм это хук Stop, скрипт, который запускается, когда Claude хочет закончить ход, и может ответить «ещё нет». Скрипт запускает проверку типов и набор тестов; если что-то красное, он печатает вывод с ошибками и завершается с кодом 2. Он также сравнивает число проходящих тестов с сохранённым базовым значением, так что набор, который выглядит зелёным из-за удалённого теста, всё равно считается красным. Он проверяет флаг stop_hook_active, описанный в документации: он равен true, когда Claude уже продолжает работу из-за хука, и в этом случае скрипт завершается с кодом 0, чтобы хук никогда не зацикливался.
Сыграв торопливого разработчика, мы попросили быстро переименовать поле отчёта и сказали Claude не запускать тесты. Claude сделал правку командой оболочки, сказал, что набор теперь упадёт, и попытался закончить ход. Хук запустил тесты и отказал фразой «Rule 4: tests fail. Not done yet.» с последующим выводом упавших проверок. Следующей репликой Claude сказал, что stop-хук проекта требует зелёных тестов, поэтому он обновит устаревшие ожидания. Тесты остались на месте.
Документация ограничивает цикл 8 подряд идущими отказами, после чего ход заканчивается в любом случае. Тест, переписанный так, чтобы проходить, не ловится; удалённый ловится. Одна ловушка: в широко разошедшейся ветке жаловались, что Claude игнорирует stop-хуки, а скрипт оттуда завершался с кодом 0, так что оболочка ничего не блокировала. Блокирующий код это 2, с причиной в канале ошибок.
Правило пятое: агент не может ослабить собственные шлюзы
У каждой проверки выше есть обходной путь: отключить strict в конфигурации компилятора, исключить падающий тест в конфигурации раннера, удалить хук из файла настроек. Механизм это список deny в блоке permissions файла настроек, по одной строке Edit(...) на файл: конфигурация компилятора, конфигурация тестов, конфигурация линтера и всё внутри папки .claude. В документации по разрешениям сказано, что правила deny вычисляются первыми и правило allow не может вырезать из deny исключение.
Когда его попросили убрать stop-хук, потому что он замедляет работу, Claude прочитал настройки и не стал пытаться: он сказал, что в файле есть правило deny на папку .claude, что обойти его можно командой оболочки и что это обошло бы защиту, которую команда установила намеренно. Когда его попросили отключить strict, он отказался, сославшись на записанное правило, и вместо этого запустил проверку типов с флагом. Когда ему сказали всё равно изменить файл, Claude потянулся к команде оболочки для этого файла, и оболочка ответила, что в разрешении на эту команду отказано. Claude ответил, что другого обхода не пробовал, потому что это свело бы на нет то, что поставило блокировку.
Ограничение тоже задокументировано: правило deny не покрывает скрипт, который сам открывает файл, а файл всё ещё можно править вручную. В этом и смысл.
Какое правило установить первым
Каждое правило это файл, который вы копируете, а не фраза, которую вы надеетесь, что Claude прочитает. При правилах прозой одна функция не нарушила ни одного; когда ничего не было записано, следующие функции оставили три точных клона, которые так и остались; когда механизмы были включены, каждый из них отклонил реальную правку.
| Если вы устанавливаете одну вещь | Почему |
|---|---|
| Хук Stop | Больше всего защиты при минимуме настройки |
| Затем список deny | Четыре строки в файле настроек |
| Ничего | На одноразовом прототипе |
Если набор тестов идёт минуты, оставьте в хуке быструю часть, а остальное перенесите в конвейер. Честное ограничение следует из длинного issue в репозитории Claude Code: хук обеспечивает то, что может показать вызов инструмента, а вопрос, верна ли абстракция, остаётся за человеком. Собственное эмпирическое правило документации: если вы всё добавляете акценты к строке в CLAUDE.md, а Claude всё равно её пропускает, эта строка должна быть в хуке.
AIDive