Перейти к содержанию

Claude Code

Плагин Poka-Yoke для Claude Code: 81% против 42%

8 мин чтения

Текст написан ИИ-моделью по источникам, на которые ведут ссылки, и сверен с ними второй моделью. Как мы работаем

Всё о теме: Claude Code: версии и изменения →
Изображение: github.com

Разработчик под ником rainmanjam 25 августа выложил на Show HN плагин Poka-Yoke. В нём 11 навыков для Claude Code, сканер опасных мест в коде и готовые заготовки для pre-commit, CI, линтера и хуков. Цель у набора одна: на каждую находку агент предлагает механизм, после которого ошибку уже нельзя совершить, и прямо говорит, что его решение делает невозможным.

Замеры автор выложил в репозитории на Github. Без навыков модели называют, что исключает их проектное решение, в 42% случаев, с навыками в 81%. Это посчитано по 80 оценённым вердиктам на шести семействах моделей. Всего за бенчмарком стоит 591 прогон. Оценщик вслепую сверяет каждый ответ с заранее написанными проверками и не знает, какая конфигурация его выдала.

Лестница из трёх ступеней

Метод и название взяты у Сигео Синго, инженера, который в 1960-х формализовал poka-yoke («защиту от ошибок») в производственной системе Toyota. Сначала термин звучал как baka-yoke, «защита от дурака», потом его смягчили. Синго не требовал от рабочих быть внимательнее, он перестраивал саму операцию. Сборщики забывали положить пружину внутрь переключателя, и он велел сначала выкладывать обе пружины в чашку. Если пружина осталась в чашке, ошибка видна сразу, до того как деталь уйдёт дальше.

Плагин переносит это на код буквально: каждая находка раскладывается по двум осям. Первая ось описывает, что происходит в момент ошибки. Она устроена как лестница, и брать нужно самую высокую ступень, какую можно себе позволить. Высшая ступень, контроль: ошибка невозможна. Тип не скомпилируется, в схеме стоит NOT NULL или CHECK, аргумент обязателен, действие запрещено через PreToolUse, ветка защищена. Ступенью ниже предупреждение: ошибиться можно, но об этом сразу скажут ошибка линтера, упавший шаг CI или проверка в рантайме. Третья ступень, обнаружение: ошибка уходит в прод, и её потом ловят тесты, мониторинг или сверка. Документация, комментарии и «будьте внимательны» стоят на нулевой ступени и защитой не считаются вовсе.

Комментарий, докстринг, страница вики, чеклист ревью или строка в CLAUDE.md «не делай X» - не poka-yoke. Это обучение, а обучение деградирует. Устройство не деградирует.

Вторая ось - три способа обнаружения у Синго, переложенные на код. Контактный метод спрашивает, может ли неправильное вообще встать на место: отдельные типы, брендированные ID, единицы измерения в самом типе. Метод фиксированного значения проверяет, может ли пройти неполный набор или неверный счёт: исчерпывающий match, обязательные поля, проверка числа затронутых строк, валидация конфига при старте. Метод последовательности ловит шаги не в том порядке: typestate, машины состояний, ключи идемпотентности, RAII и defer. По словам автора, три линзы, прогнанные по одному интерфейсу, находят то, что пропускает обычное ревью.

Результат аудита выглядит как карточка. Пример из README: в transfer() из src/payments/transfer.ts счета можно перепутать местами, вызвав transfer(dst, src). Деньги уйдут в обратную сторону, код скомпилируется, пройдёт ревью и ничем не выдаст ошибку в рантайме. Защиты сейчас нет. Предложенное устройство - разные типы SourceAccount и DestinationAccount, ступень «контроль». В находке всегда названа ошибка и никогда тот, кто её совершил: у совета «разработчику стоило быть внимательнее» нет реализации.

Чем приходится платить

Загруженный метод меняет, на что модель обращает внимание, а внимание конечно. В тех же 591 прогоне сдвиги видны в обе стороны (без навыков → с навыками):

  • конкретное устройство на каждую находку вместо «добавьте валидацию»: 62% → 100%;
  • называет, что решение делает невозможным: 42% → 81%;
  • отмечает, что pre-commit можно обойти и его надо дублировать в CI: 35% → 92%;
  • опознаёт сырую SQL-интерполяцию как вектор инъекции: 92% → 69%;
  • объясняет, почему молча неверное число опаснее упавшего пайплайна: 54% → 31%.

Вывод автор формулирует прямо. Если нужно найти конкретный баг, берите ревьюера, а если нужно поменять форму кода так, чтобы целый класс багов в нём перестал выражаться, берите плагин. «Этот размен и есть продукт, а не оговорка к нему», - говорится в README.

Где навыки помогают, а где мешают

Основная матрица: 13 сценариев, четыре модели Claude, две конфигурации, 445 прогонов. В девяти сценариях пользователь уже предложил или применил недостаточное исправление, и если модель с ним соглашается, она теряет баллы. Остальные четыре (design и три сценария build-*) - задачи с нуля, где проблему никто не поднимал, и там видно, к чему модель тянется сама. Бенчмарк меряет готовность возразить.

Fable 5 растёт с 88,7% до 97,0% (+8,3 п. п., 95-процентный интервал от +1,1 до +15,5), Sonnet 5 с 79,8% до 88,5% (+8,6 п. п., от +2,2 до +15,1), Haiku 4.5 с 58,2% до 71,1% (+12,9 п. п., от +0,9 до +24,9). У Opus 5 прибавка всего 3,6 пункта, с 92,7% до 96,4%, и нижняя граница интервала +0,2. Ноль не попадает ни в один из четырёх интервалов, но у Opus 5 и Haiku 4.5 нижние границы стоят почти на нём. Ответы при этом идут дольше: у Opus 5 со 130 до 172 секунд, у Haiku 4.5 с 40 до 60.

Прибавка зависит от того, сколько модели не хватало. По 52 ячейкам «сценарий × модель» корреляция базового результата с приростом составляет r = −0,52. Ячейки, стартовавшие ниже 50%, прибавляют в среднем 19 п. п., а стартовавшие выше 95% теряют 0,9. В среднем навыки закрывают 36% оставшегося запаса. Длина ответа связана с приростом слабо, r = 0,30. Самые большие сдвиги видны в сценариях, где надо строить защиту, а не искать опасность: ops на Haiku 4.5 с 29% до 92%, build-endpoint на Fable 5 с 61% до 100%, agent-guardrails на Sonnet 5 с 59% до 91%. Из 52 ячеек 30 выросли, 13 не изменились, 9 упали. При полном отсутствии эффекта упасть должны были бы около 18, а по симуляции на реальном числе прогонов 95-процентный диапазон составляет 12-25.

Исключение - самая слабая модель на задачах «построй». На build-задачах Haiku 4.5 теряет 8,6 п. п. и тратит в 2,12 раза больше времени. На эндпоинте возврата платежа Opus 5 идёт с 83,3% до 100%, а Haiku 4.5 падает с 44,4% до 33,3%. Автор объясняет это так: маленькая модель тратит бюджет на метод и выдаёт меньше самого кода. Он оговаривается, что пока это гипотеза, и прямо не рекомендует плагин в этой конфигурации. Разброс у Haiku 4.5 тоже растёт: стандартное отклонение по сценариям было 16,7, стало 24,1.

Вне Claude Code измерили два рантайма. Codex на gpt-5.6-terra в read-only песочнице вырос с 74,2% до 91,0% (+16,8 п. п.) на всех 13 сценариях, agy на Gemini 3.1 Pro в plan mode с 64,6% до 78,1% (+13,5 п. п.) на 12 из 13. В общий средний результат их не включали: ответ Codex занимает 50-200 слов против 400-800 у Claude, и честно сравнивать можно только прирост внутри одного рантайма.

Ограничения автор перечисляет сам. Оценивает модель Haiku 4.5, человек в этом не участвует. Проверки написал автор навыков, до прогонов, но независимой такую оценку не назовёшь. Каждый прогон - первая реплика свежей сессии, так что цифры показывают потолок, а не то, что останется к вечеру с накопленным контекстом. Базовая линия - модель вообще без навыков. Сравнения с CLAUDE.md или AGENTS.md, где команда уже записала свои правила, не проводилось, хотя автор называет именно этот файл альтернативой, с которой плагин на деле конкурирует. Контрольная группа с другим структурированным методом спроектирована, но не запущена.

Часть цифр по ходу пришлось исправлять. Сначала authz на Sonnet 5 выглядел как регрессия на 16 пунктов, но причина нашлась в самом бенчмарке: aggregate() по умолчанию брала --runs равным трём и после семи прогонов на ячейку учла 264 из 486. А правка навыка agent-guardrails для Haiku 4.5 не удержалась: в момент внедрения она давала 88%, а в закоммиченных прогонах осталось 33%, меньше исходных 38%. Старую цифру автор оставил в таблице рядом с новой.

Сам не вызывается

Навыки срабатывают только по явному вызову. Свежим агентам с установленным плагином дали десять реалистичных запросов, среди них UX удаления рабочего пространства, изоляция тенантов и пятничная миграция с удалением колонки. Ни один запрос не вызвал навык poka-yoke, а один агент явно перебрал навыки и выбрал hookify. Автор считает это свойством платформы и ссылается на сборник жалоб в трекере Claude Code, где навыки игнорируются даже при точном совпадении запроса с описанием, и на разбор Скотта Спенса. Три переписывания описаний через оптимизатор skill-creator ничего не изменили. В комплекте есть хук assets/devices/claude-hooks/suggest_poka_yoke.py: он сверяет промпт со словарём каждого режима и подставляет инструкцию с именем нужного навыка. Сам автор относит его к ступени «предупреждение» и для важного советует вызывать навык руками.

Установка из маркетплейса - /plugin marketplace add rainmanjam/poka-yoke, затем /plugin install poka-yoke@poka-yoke. Начинать автор советует с /poka-yoke:design, пока у кода ещё нет вызывающих. Остальные режимы: audit, retro, ops, authz, ux, data, llm, guardrails и agent-guardrails. Навык можно попросить и словами: «poka-yoke this repo». Чтобы закоммитить плагин для всей команды, навыки копируют в .claude/skills/ проекта. Плагин ставится на 19 рантаймов, у десяти из них есть родной манифест, но поведение проверено только в Claude Code, Codex и Antigravity, остальные манифесты CI проверяет лишь структурно. Режим audit в plan mode agy не работает: он запускает встроенный сканер, а этот режим выполнять команды не даёт. Лицензия MIT.

Сканер без зависимостей

Детектор написан на Python 3.9+ и использует только стандартную библиотеку. Он смотрит код на TypeScript, Python, Go, Rust и SQL и ищет соседние параметры одного типа (для Python через настоящий разбор AST), проглоченные ошибки, удаления без ограничений, длительности без единиц, деньги во float, парсинг без валидации и повторяемые операции без ключа идемпотентности. В каталоге 28 типов опасностей, текстом обнаруживаются 20, остальные 8 требуют суждения. Шаблонных правил 42, по умолчанию включены 19: для остальных 23 сканер называет линтер, который справится лучше, а флаг --all всё равно запускает их. Ложные срабатывания на шаблонных правилах автор признаёт заранее: это цена проверки без настройки и установки.

Попробовать сканер можно вообще без плагина: склонировать репозиторий в /tmp/poka-yoke и запустить python3 /tmp/poka-yoke/plugins/poka-yoke/scripts/cli.py detect --paths /absolute/path/to/your/repo. Путь к проекту должен быть абсолютным, иначе он отсчитается от клона.

Пока никто не написал. Будьте первым.

Присоединяйтесь к разговору

Войдите, чтобы оставить комментарий. Он появится после модерации.