AIDive

Я поймал Claude Code на копипасте. 5 правил без обхода

AIDive · Опубликовано

Кодинг-агенты

Пять правил, которые 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 всё равно её пропускает, эта строка должна быть в хуке.

Бесплатные материалы

Источники

Частые вопросы

Принуждает ли Claude Code к соблюдению правил из CLAUDE.md?
Нет. В документации Anthropic сказано, что CLAUDE.md и файлы правил загружаются как контекст, а не как принудительная конфигурация, и что Claude может решить, что рекомендация не относится к делу. Правило, не допускающее исключений, принадлежит хуку, правилу deny или управляемой настройке.
Что такое хук Claude Code?
Скрипт, который Claude Code запускает в заданный момент: до или после вызова инструмента либо когда Claude хочет закончить ход. Когда скрипт завершается с кодом 2, то, что он напечатал в stderr, возвращается Claude как отказ; скрипт, завершившийся с кодом 0, не виден никогда.
Как не дать Claude Code копипастить вспомогательные функции?
С помощью хука PostToolUse на Edit и Write, который запускает детектор дублирования вроде jscpd на папке с исходниками, сравнивает число клонов с сохранённым базовым значением и при его росте завершается с кодом 2 и местом двойника. Он ловит точные копии, но не переписанные функции.
Как заставить Claude Code запускать тесты, прежде чем он скажет, что готово?
С помощью хука Stop, который запускает проверку типов и набор тестов и завершается с кодом 2 и выводом ошибок, пока что-то красное. Проверяйте флаг stop_hook_active и завершайтесь с кодом 0, когда он равен true, чтобы хук не зацикливался; Claude Code ограничивает цикл 8 подряд идущими отказами.
Может ли Claude Code отключить собственные хуки или изменить tsconfig.json?
Не при наличии списка deny. Правила deny Edit(path) в файле настроек на tsconfig.json, конфигурации тестов и линтера и папку .claude применяет оболочка: в нашем тесте sed через Bash на tsconfig.json был отклонён до того, как модель коснулась файла. Скрипт, который сам открывает файл, не покрывается, а вручную файл по-прежнему можно править.
Почему мой хук Stop никогда не блокирует?
Обычно потому, что он завершается с кодом 0. Для блокировки нужен код 2 с причиной в stderr; скрипт, заканчивающийся на cat с кодом 0, позволяет ходу закончиться каждый раз.

Похожие видео