shady2k-skills

Зачем я сделал ещё один набор скиллов

В разработке с агентами мне не хватало не очередного промпта о том, как правильно писать код. Проблема появлялась раньше: в проекте становилось непонятно, что делать дальше, работа прыгала между задачами, а трекер постепенно превращался в склад идей, старых эпиков и статусов, которым уже нельзя верить.

На проекте, из которого вырос shady2k-skills, это было хорошо видно. В трекере накопилось 933 открытых задачи, 773 из них считались готовыми к работе, а 82 из 83 задач «в работе» не менялись больше двух дней. Когда готово почти всё, очередь уже ничего не говорит о приоритете. А когда работа внезапно находит баг или архитектурную дыру, они сразу прыгают вперёд и отодвигают исходную задачу ещё на неделю-другую.

Готовые процессные наборы вроде superpowers и spec-kit оказались для меня слишком тяжёлыми. Более лёгкие скиллы приятнее в работе, но у них другая проблема: совет можно вызвать, а можно забыть. Если никто не запустил нужный скилл, никакого процесса нет. Форму репозитория и часть идей рабочих скиллов я взял из mattpocock/skills; сам процесс и обязательные проверки выросли уже из моих задач.

Так появился shady2k-skills: лёгкие инструкции для агента плюс небольшие исполняемые проверки там, где правило действительно должно быть обязательным.

Как устроен процесс

Работа делится на пять уровней: видение продукта, milestone с целью ближайшей версии, feature с одним наблюдаемым результатом, этап и конкретная задача или баг. Подробно раскладывается только ближайший горизонт. Будущие версии остаются крупными идеями, пока не придёт их время — иначе агент успеет подробно распланировать то, что потеряет смысл раньше реализации.

Этап должен давать самостоятельный проверяемый результат, а задача — помещаться в одну рабочую сессию агента. Зависимости появляются только там, где одной работе действительно нужен результат другой. Порядок строк в трекере и вложенность сами по себе работу не блокируют, поэтому независимые features и этапы можно выполнять параллельно.

Отдельно существует бюджет находок: заранее оговорённое количество багов и архитектурных проблем, которые текущая работа может поглотить. Остальные находки не пропадают, но уходят в backlog и уже не могут автоматически вытеснить feature из плана.

Что входит в набор

Сейчас в репозитории 16 скиллов. Они разделены по назначению, но собираются в один маршрут от идеи до принятого результата.

Работа с backlog:

• ask-shady2k — читает проект, трекер и историю Git, объясняет текущее состояние и рекомендует следующий шаг, ничего не меняя;
• setup-shady2k-skills — подключает существующий трекер, настраивает правила проекта и проверяет, что обязательные проверки действительно работают;
• to-milestone — фиксирует результат ближайшей версии, её границы и бюджет находок;
• to-stages — делит feature на проверяемые этапы и задачи для отдельных агентов-исполнителей;
• to-backlog — сохраняет новую идею, баг или долг в правильной очереди, не проталкивая их вперёд;
• groom-backlog — восстанавливает рабочую очередь из накопившегося склада задач;
• close-out — после принятия работы обновляет документы и закрывает то, что действительно закончено.

Проектирование и разработка:

• brainstorming — помогает обдумать идею, найти альтернативы и возразить по существу; разговор не обязан закончиться задачей;
• to-research — отвечает на ограниченный вопрос по первичным источникам;
• to-prototype — строит маленький выбрасываемый эксперимент, когда спор дешевле проверить кодом;
• to-spec — описывает поведение feature и сценарии, по которым его будут принимать;
• diagnose-bug — воспроизводит проблему и проверяет гипотезы по одной;
• model-domain — ведёт словарь проекта и сохраняет причины плохо обратимых решений;
• take-task — проводит готовую feature через реализацию, проверки и review до одного зелёного pull request.

Работа вокруг разработки:

• handoff — передаёт состояние длинной работы в новую сессию, не заставляя следующего агента восстанавливать всё по переписке;
• report-to-shady2k — готовит анонимизированный отчёт о проблеме в самих скиллах и отправляет его только после явного подтверждения пользователя.

Часть скиллов запускается только по просьбе или с согласия человека: ориентация в проекте, установка, изменение границ работы, автономный запуск feature, handoff и отправка отчёта. Исследование, диагностику или обновление спецификации агент может подключить сам, когда этого требует уже согласованная работа.

Почему одних инструкций недостаточно

Скилл может сказать агенту, что у каждой задачи должен быть критерий готовности. Но текст в SKILL.md не мешает модели забыть это правило на длинной сессии. Поэтому набор отделяет рекомендации от гарантий.

Проверка backlog следит за горизонтом планирования, критериями готовности, зависимостями, задачами, которые уже кто-то взял, и доказательствами выполненной работы. Отдельная проверка не даёт коммиту потерять связь с задачей. Проверка документов связывает требования, сценарии, задачи и запись о приёмке. Режим можно выбрать под зрелость проекта: только отчёт, блокировка новых нарушений или полная блокировка.

Зелёная проверка backlog не означает, что код работает: тесты, review и приёмка проверяются отдельно. Проверки также не скажут, хорошо ли сформулировано требование и правдиво ли приложенное доказательство. Они ловят то, что проверяется механически, и не заменяют собой инженерное решение.

Как выглядит обычная работа

Почти любую сессию можно начать вопросом «что дальше?». ask-shady2k ничего не меняет: он собирает картину продукта, прогресса, рисков и доступных путей, а затем рекомендует одно действие. После перерыва это полезнее, чем сразу хватать первую задачу со статусом ready.

Планирование идёт в основном рабочем каталоге и само по себе не создаёт ни веток, ни временных файлов. Если разговор приводит к работе, агент сохраняет согласованное решение, заводит отдельную рабочую копию и перед запуском одним списком приносит вопросы, без которых автономная реализация может остановиться. После команды на запуск take-task ведёт feature по своей ветке до одного pull request: мелкие решения принимает и записывает сам, а архитектурную развилку, существенный риск или изменение требований возвращает владельцу.

В итоге pull request объясняет, что сделано, как это проверить и какие решения агент принял сам. Слияние остаётся приёмкой владельца. После него close-out закрывает задачи и обновляет состояние проекта.

Портативность

shady2k-skills не содержит собственного трекера и не привязан к Claude Code, Codex или другой конкретной агентской среде. Трекер подключает сам проект: он даёт адаптер к своему трекеру и описывает местные команды, а скиллы работают через этот контракт. Для Claude Code и Codex есть манифесты плагинов; агенты, которые читают обычные SKILL.md, могут установить тот же набор отдельными скиллами.

Настройка бывает личной или командной. В личном режиме проверки и Git hooks действуют только в рабочей копии одного разработчика. Командный режим затрагивает общий репозиторий и CI, поэтому включается как отдельное решение, а не исподтишка вместе с установкой плагина.

Текущее состояние

В наборе уже работают проверки backlog, связи коммитов с задачами и жизненного цикла документов. Репозиторий тестирует манифесты, переносимый протокол и примеры нарушений, на которых проверки должны падать.

Но проект пока не закончен. Новый сквозной сценарий — от разговора и планирования до автономной реализации целой feature и одного pull request — ещё нужно полностью проверить на живом проекте. Именно там станет видно, какие правила помогают закончить работу, а какие только красиво выглядят в документации.

Исходники, установка и актуальное описание всех скиллов находятся в репозитории проекта. История решений и ограничений процесса собрана в docs/design.md.