Библиотека процессных скиллов: чиню повторяющиеся ошибки ИИ-агента

ИИ-агентыПроцесс

После нескольких месяцев плотной работы с кодящим агентом я заметил простую вещь: список моих претензий перестал расти. Ошибки повторялись, и повторялись одинаково — независимо от языка, фреймворка и размера репозитория.

  • Уверенно строит не то: расплывчатая просьба достраивается догадками, а несовпадение вылезает, когда код уже написан.
  • Говорит «готово» без проверки: тесты были зелёными десять минут назад, до последних правок.
  • Одобряет собственную работу.
  • Срезает процесс под давлением: «дедлайн через три часа», «прод лежит, чини как хочешь».
  • Забывает поправки: вы исправили, агент извинился, через три сессии всё то же самое.
  • Не доводит до конца: работа осталась на ветке, версия не поднята, changelog забыт.

Ни одна из этих ошибок не про стек. Значит, и лечение должно быть общим. Я собрал десять коротких документов — скиллов, — каждый из которых закрывает один такой провал. В описании скилла стоит триггер, и агент подтягивает нужный сам, когда ситуация подходит. Это не справочники по технологиям, а дисциплина процесса.

Пример первый: «три задачи, быстро»

Просьба: переименовать кнопку, добавить колонку в базу и поменять формулу метрики. К вечеру. Без правила агент применяет ко всему один режим — либо разводит церемонию вокруг переименования, либо катит изменение схемы без обсуждения.

Скилл classifying-tasks говорит: объём процесса определяется ценой ошибки, а не размером просьбы. Каждый пункт классифицируется отдельно, тир объявляется вслух до начала работы — чтобы у меня был шанс возразить. И отдельно: дедлайн меняет объём работы, но не набор проверок.

Половина скилла — таблица рационализаций, то есть фраз, которыми модель сама себе разрешает срезать угол (скиллы написаны по-английски, там же живёт и вся остальная обвязка):

“Deadline is tight, I’ll run a compressed pipeline” → Compression = silently making the user’s product decisions. Negotiate scope down instead: ship fewer items at full discipline.

“It’s just one small column” → Columns come with contracts, defaults, migrations, and consumers. Classify by blast radius, not line count.

Это оказалось важнее самих правил. Правило агент нарушает не потому, что не знает его, а потому, что придумывает уважительную причину. Названная вслух причина работает хуже.

Пример второй: своя работа всегда выглядит хорошей

«Если уверен — мержи, я тебе доверяю». Скилл getting-second-opinion отвечает на это прямо: контекст, который написал решение, не видит его дефектов — те же слепые пятна писали и код, и тесты к нему. Поэтому тесты и зелёные.

Самое ценное в этом скилле — как формулируется задание ревьюеру. Не «отревьюй код», а враждебный бриф с конкретной мишенью: «попробуй опровергнуть, что этот лимитер атомарен при нескольких инстансах». Ревьюеру, которому сказали, что атаковать, есть что искать; вежливому — нечего, и он хвалит.

Вторая деталь: ревьюер не имеет права одобрять то, что на самом деле является решением человека, — падать открытым или закрытым при сбое, что делать со старыми данными. Такие вопросы вынимаются из ревью и задаются одним сообщением, а не закапываются в вердикт «выглядит хорошо».

Пример третий: поправки не доживают до следующей сессии

Поправка, сказанная в чате, умирает вместе с контекстом. Скилл codifying-learnings требует на каждую поправку двух действий: починить конкретный случай и закрепить правило в самом механическом слое, который подходит. Лестница простая: правило линтера лучше строки в CLAUDE.md, строка в CLAUDE.md лучше памяти. Машины не забывают, люди и модели — забывают.

И граница ответственности: строку в CLAUDE.md или в память агент добавляет сам и сообщает об этом; правку линтера, CI или хуков — только предлагает с точным текстом изменения, потому что этот конфиг общий для команды. Триггер — первая поправка, а не вторая, раздражённая.

Как это включается

Установка — просто симлинки в папку скиллов:

for d in skills/*/; do ln -sfn "$(pwd)/$d" ~/.claude/skills/"$(basename "$d")"; done

Дальше — тонкий слой в CLAUDE.md проекта: где лежат спеки, чем проверяется сборка, какие решения требуют согласования. И одно правило, на понимание которого ушло больше всего времени: проектный файл должен ссылаться на скилл по имени, а не пересказывать его процесс. Если пересказать — модель следует пересказу и до самого скилла не доходит.

# Task dispatcher
Classify every request with the classifying-tasks skill before acting.
Heavy tasks → delivering-heavy-features skill. Shipping → shipping-a-release skill (explicit ask only).

Где это слабо

Скилл — это склонность, а не гарантия. Я проверял их так же, как проверяют код через тесты: сначала фиксировал, как агент проваливает задачу без скилла, потом писал скилл, потом давал ту же задачу свежему агенту и смотрел, изменилось ли поведение. Это ловит грубые дыры, но статистики у меня нет: я не могу сказать, насколько реже агент срезает углы. Кто утверждает обратное про свои промпты — скорее всего, тоже не измерял.

Второе: одноимённые проектный и глобальный скилл перекрываются ненадёжно — известная открытая проблема. Пришлось разводить имена и прописывать маршрутизацию явно.

Третье, и главное: правила стоят внимания. Десять — это уже граница, за которой дисциплина начинает превращаться в шум, а агент — выбирать, что из этого читать. Так что следующий скилл я, скорее всего, буду добавлять, удаляя другой.

← Все посты