improve — аудит кодовой базы и планирование для дешёвых моделей

Паттерн «дорогой моделью думаем, дешёвой делаем» набрал популярность в 2025 году, но до сих пор не было элегантной реализации в формате agent skill. Проект improve от shadcn закрывает эту нишу: навык проводит аудит кодовой базы и пишет детальные планы, которые может исполнить любая модель — даже слабая.

Идея

Модели отличаются по цене и качеству. Самые способные стоят дорого, но именно они лучше всего справляются с задачами, где интеллект накапливается: анализ архитектуры, оценка рисков, написание спецификаций. Исполнение плана — задача более механическая, и с ней справляются более дешёвые модели.

вы          →  /improve                    (дорогая модель, советует)
plans/       →  001-fix-n-plus-one.md       (самодостаточные спецификации)
другой агент →  реализует, тестирует, шипает (дешёвая модель, исполняет)

Навык никогда не модифицирует исходный код. Единственный побочный эффект — файлы в директории plans/. Продукт — это план, а не реализация.

Установка

npx skills add shadcn/improve

Работает в любом агенте, поддерживающем формат Agent Skills. Планы — обычный Markdown, поэтому их может подхватить любой агент или даже человек.

Команды

Навык предоставляет набор команд для разных сценариев:

Типичный рабочий процесс

1. Откройте агент в репозитории и запустите /improve (или /improve quick для экономии токенов).
2. Навык проводит аудит и возвращает таблицу находок. Вы выбираете нужные: «plan 1, 3 and 5».
3. Планы сохраняются в plans/ — по файлу на каждую находку, плюс индекс с рекомендуемым порядком. Они написаны для ревью.
4. Передайте план любому агенту, или пусть навык выполнит его сам: /improve execute 001. Навык запускает дешёвую модель в изолированном worktree, ревьюит diff и возвращает вердикт. Мёрж — всегда за вами.
5. В следующей сессии /improve reconcile обновит бэклог: проверит, что завершённое не сломалось, обновит устаревшее, архивирует выполненное.

Как работает аудит

Разведка. Навык изучает репозиторий: стек, конвенции, точные команды сборки/теста/линта. Всё это становится верификационными шлюзами в каждом плане.

Аудит. Параллельно запускаются сабагенты по девяти категориям: корректность, безопасность, производительность, покрытие тестами, технический долг, зависимости и миграции, DX, документация и направление развития. Каждая находка содержит ссылку file:line, оценку влияния, трудозатраты и уверенность.

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

Приоритезация. Находки сортируются по leverage (impact ÷ effort, взвешенный по confidence).

Что делает планы исполняемыми

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

• Самодостаточность. Весь контекст инлайнится: точные пути файлов, выдержки текущего кода, конвенции репозитория с примером, проверенные команды. Никаких «как обсуждалось выше».
• Верификационные шлюзы. Каждый шаг завершается командой и ожидаемым выводом. Критерии завершения — машинно-проверяемые. Исполнителю не нужно судить, успешно ли он справился.
• Жёсткие границы. Явные списки того, что вне scope, и условия STOP — «если X, остановись и доложи» — вместо импровизации маленькой модели.

Каждый план также фиксирует git-коммит, против которого написан, чтобы исполнитель мог механически проверить, не устарел ли план.

Замыкание цикла

Планы не выстреливаются в пустоту:

• execute <plan> запускает дешёвого исполнителя в изолированном git worktree, передаёт ему план, затем ревьюит результат как техлид — прогоняет все критерии завершения, проверяет scope, читает diff. Вердикт: approve (мёрж за вами), отправить на доработку (максимум 2 раунда) или заблокировать и уточнить план.
• reconcile обрабатывает накопившееся: верифицирует DONE-планы, расследует BLOCKED и переписывает вокруг препятствия, обновляет устаревшие планы, архивирует независимо исправленные находки.
• --issues публикует планы как GitHub Issues — тот же самодостаточный контент, так что любой агент или человек может взять задачу.

Жёсткие правила

• Никогда не модифицирует исходный код. Записи только в plans/; исполнители работают в одноразовых worktree, мёрж — всегда ваше решение.
• Никогда не запускает мутабельные команды — только чтение, поиск и анализ.
• Никогда не воспроизводит секреты. Только локации и типы учётных данных, всегда рекомендация ротации.
• Если попросить реализовать — откажется и укажет на план (или предложит execute).

Для кого

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

Пример — запуск аудита на shadcn/ui выявил дублирование shadow-config и O(n²) в миграции иконок, с точными ссылками на строки кода и рекомендациями по приоритету.