Проверка plugin: что ставить и почему

1. Plugin — это чемодан, а не заметка

Когда разработчик впервые видит plugin, у него часто возникает очень мирная мысль: «Ну это же просто подсказки для Claude, что тут может пойти не так?» Много чего. Plugin почти никогда не бывает просто текстом. Это чемодан с инструментами: снаружи подписано красиво, а внутри может лежать аккуратная отвёртка — или бензопила. Установка — не жест симпатии, а решение пустить в свой рабочий процесс новый пакет возможностей.

В прошлой лекции я разбирал механику: install, update, scope, жизненный цикл. Но она не отвечает на главный вопрос — нужно ли ставить этот пакет вообще. До реального install нужен отдельный фильтр: откуда пакет взялся, что приносит в среду, как сочетается с проектом, что делать при откате.

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

Эта схема полезна ещё и тем, что не зависит от версии Claude Code. Команды менеджера plugins, имена файлов с метаданными, набор полей могут меняться. Логика — нет: сначала источник, потом границы возможностей, потом жизнь после установки.

flowchart TD
    A[Нужен новый plugin] --> B[Проверить источник и автора]
    B --> C[Проверить возможности и права]
    C --> D[Проверить совместимость с проектом]
    D --> E[Проверить обновление и путь отката]
    E --> F{Риск оправдан?}
    F -- Да --> G[Устанавливаем в нужный scope]
    F -- Нет --> H[Не устанавливаем]

Если держать эту схему в голове, становится проще не влюбляться в plugin по обложке. А история эта очень частая: красивый README, пара звёздочек, слово automation — и рука уже тянется к install. Инженерный подход, увы, скучнее: сначала читаем, потом думаем, потом ставим.

2. Кто за это отвечает завтра утром

На этом шаге легко свалиться в одну из двух крайностей. Первая — доверять всем подряд: «раз лежит в marketplace, значит кто-то уже проверил». Вторая — не доверять никому, будто каждый plugin метит украсть ваш ноутбук и кота. Обе бесполезны. Нужна не наивность и не страх, а спокойная проверка происхождения.

Самый простой вопрос звучит так: если этот plugin сломается завтра утром, вы понимаете, кто за него отвечает? Для внутреннего plugin ответ конкретен: репозиторий, владелец из tooling-команды, канал поддержки. Для внешнего — хочется видеть хотя бы репозиторий, автора, лицензию, историю релизов, признаки живого проекта. «Архив неизвестно чей, README на полстраницы, последний коммит полтора года назад» — ещё не красный флаг, но очень уверенный жёлтый.

Вот минимум метаданных, на которые я смотрю первым делом. Не финальный снимок review-kit, а тот минимум, что вообще должен быть у внятного кандидата.

{
  "name": "team-review-kit",
  "version": "0.1.0",
  "author": "internal-tooling-team",
  "license": "MIT",
  "namespace": "review-kit"
}

Даже такой небольшой фрагмент уже даёт несколько сигналов: имя, версия, автор, лицензия, namespace. Качество это ещё не доказывает — но перед вами оформленный артефакт, а не «папка с чем-то полезным на моей машине».

Здесь полезно запомнить одну простую формулу: известный автор снижает риск происхождения, но не отменяет проверку самого plugin. Иногда думают так: «Автор уважаемый, можно больше ничего не читать» — нет. Даже у известного автора plugin может тащить hooks, shell-скрипты, сетевые вызовы и широкие права. Имя на обложке — повод читать внимательнее, а не переставать читать.

Для внутреннего plugin логика та же, и тут ждёт новая ловушка: команды часто считают внутренний пакет безопасным по умолчанию. На практике внутреннее документировано хуже внешнего. Пишет один человек «на коленке», README откладывает на потом, changelog не заводит — а через месяц уходит в отпуск. И у команды стоит полезная, но загадочная коробка без инструкции.

3. Capability surface: не что обещает, а что может

Это самая важная часть review, потому что именно здесь заканчиваются красивые описания и начинается реальная поверхность возможностей. Термин capability surface запоминается просто: суммарный набор действий, на которые plugin способен в вашем проекте. Не то, что он обещает, а то, что он может сделать, если вы его установите. Два skill-компонента как структурированные подсказки без автодействий — один риск. Hooks, shell-скрипты, доступ к внешним данным, сетевые запросы, требования к токенам — совсем другой разговор. Поэтому читаю не только README, но и список компонентов.

Для практической проверки удобно держать перед глазами такую таблицу:

Хороший безопасный README обычно не прячет capability surface, а честно делает его коротким и понятным. Например:

## Сводка capability

Плагин добавляет два skills: issue-analysis и pr-review.
Автоматических hooks нет.
Сетевых запросов нет.
Токены и внешние credentials не требуются.
Shell-скрипты не используются.

Такой фрагмент хорош не тем, что выглядит скромно, а тем, что после него вы уже знаете границы. Два skill — и всё. Скрытого второго этажа нет.

А вот концептуально тревожный пример выглядит так:

{
  "name": "generic-automation-suite",
  "permissions": ["shell", "network", "write"],
  "requiresCredentials": true,
  "hooks": 4
}

Даже если этот фрагмент условный, он заставляет задать правильные вопросы. Зачем plugin для review workflow нужен shell? Почему network? Какие операции записи? Почему hooks целых четыре? Частая ошибка здесь очень человеческая: «наверное, это всё для удобства». Инженерный ответ звучит иначе: если вашему сценарию нужен review diff, а plugin просит половину кухни целиком, это не удобство, а несоответствие принципу least privilege.

Ещё один момент, про который легко забыть при слове «безобидный»: даже skill-only plugin грузит контекст своим описанием, namespace и командами — ту самую невидимую цену мы разбирали в прошлой лекции. Поэтому «нужен ли он вообще» — часть capability surface, а не отдельная придирка.

4. Хороший plugin — и всё равно не ваш

Представьте, что вы нашли действительно аккуратный plugin: автор понятен, возможности безопасны, README написан не кровью. И всё равно его можно не ставить — он должен подойти именно вашему проекту, команде и среде. Это и есть проверка совместимости, не только технической, но и операционной.

Самый очевидный вопрос здесь — scope. user рискует вашим личным набором инструментов (в некоторых интерфейсах уровень зовётся personal). local держит эксперимент в границах одного repo. project связывает plugin с проектным workflow, и цена ошибки там выше — неважно, хранится ли привязка в конфиге из repo или в состоянии уровня проекта текущей версии Claude Code. Для экспериментов почти всегда разумнее начинать с user или local. К project переходите, когда ясно: этот workflow нужен команде и понятно, как его раскатывать.

Вторая важная часть — namespace и пересечения имён. Допустим, у вас уже есть review plugin, и новый тоже приносит skill pr-review. Без namespace получается прекрасная лотерея: кто сработает, как отобразится, что увидит команда. Здоровее так:

review-kit:issue-analysis
review-kit:pr-review

Сразу видно, откуда пришёл компонент, и меньше риск конфликтов. В командах это особенно полезно, потому что через два месяца никто уже не помнит, кто добавил очередной review.

Но совместимость — это не только имена. Очень частый практический вопрос: на какую оболочку и среду рассчитан plugin? Скрипты на bash, а половина команды в PowerShell — проблема уже есть, хотя plugin сам по себе «хороший». То же со структурой репозитория, ожидаемыми командами, соглашениями по каталогам. Plugin, идеальный в одном mono-repo, в другом бесполезен или раздражает.

Отдельно стоит проверять дублирование. Иногда plugin ничего не ломает, а просто не нужен: дублирует существующий skill, повторяет установленный workflow, добавляет вторую команду для той же задачи. Тоже несовместимость, только организационная. Слишком много почти одинаковых инструментов — прямой путь к вопросу «а какой правильный?», после которого не пользуются никаким.

5. Где дверь, если что-то пойдёт не так

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

Первая вещь, которую хочется видеть, — версия и changelog. Даже 0.1.0 лучше, чем «актуальная папка на сегодня»: можно говорить конкретно — «у нас 0.2.0, в 0.3.0 появились hooks, пока не обновляем». Здесь версия важна не сама по себе, а как язык разговора об обновлении и откате: без неё «у меня работает, а у тебя нет» не разложить на причины.

Вторая вещь — понятный путь update и отката. Обновление нельзя воспринимать как нейтральную техническую мелочь: новая версия добавит возможности, изменит поведение, расширит права, начнёт конфликтовать с workflow. Поэтому update стоит мысленно считать почти новым install. Changelog туманный, изменения — «many improvements»? Не радуйтесь, читайте внимательнее.

Хороший README обычно заранее объясняет, как жить с plugin после установки:

## Обновление

Перед update проверьте release notes.
Если новая версия меняет hooks, permissions или список credentials,
обновляйте только после повторного review.

## Отключение

Плагин можно отключить через менеджер plugins
или убрать project-level привязку тем способом, который поддерживает ваша версия Claude Code.

Третья вещь — владелец. У plugin должен быть человек или команда, кому можно задать вопрос. Иначе получается грустный артефакт-сирота: все пользуются, никто не отвечает, обновлять страшно, удалять ещё страшнее. Внутри команды это особенно комично: полезный plugin стоит, а автор — «кажется, Паша, который теперь на другом проекте». Технически работает, организационно в зоне риска.

6. Ставим или отказываемся

Чтобы не оставлять всё на уровне красивых принципов, давайте сравним два воображаемых, но очень жизненных варианта. Первый — team-review-kit, команда хочет его для issue analysis и PR review. Второй — generic-automation-suite, который выглядит эффектно, но вызывает вопросы.

В первом случае решение довольно спокойное: набор возможностей ограничен задачей, поддержка понятна, project scope оправдан. Даже если вы новичок, здесь легко сформулировать решение без магии:

Решение: устанавливаем в project scope.

Причина: plugin закрывает командный workflow issue-analysis и pr-review.
Capability surface ограничен двумя skills, токены не нужны, namespace не конфликтует.
Есть понятный owner, версия и путь отключения.

Во втором случае отказ — не перестраховка, а нормальный инженерный вердикт. Вы не обязаны давать слабо документированному plugin с hooks, shell, сетью и широкими credentials шанс «просто посмотреть на практике». Иногда лучший эксперимент — тот, который так и не начался.

Решение: не устанавливаем.

Причина: plugin требует больше возможностей, чем нужно для нашего review workflow.
Есть hooks, shell-скрипты и сетевой доступ без достаточной документации.
Путь отключения и последствия update не описаны.

Обратите внимание, что в обоих случаях язык спокойный. Без «ужасный» и «идеальный». Только соответствие задаче, границы возможностей, качество сопровождения.

7. Запишите решение, пока оно не стало легендой

Когда решение не зафиксировано, оно очень быстро превращается в легенду: через месяц уже никто не помнит, почему plugin стоит, кто одобрил, на каких условиях. Поэтому полезно сделать маленькую заметку — в README команды, tooling-документе или хотя бы в описании pull request. Не для красоты, а чтобы следующий человек не проходил весь review заново.

Формат может быть совсем коротким:

Plugin: team-review-kit v0.2.0
Scope: project
Решение: устанавливаем

Зачем:
единый workflow для issue-analysis и pr-review

Что умеет:
только skills, без hooks, сети и credentials

Ограничения:
используем только для review-задач

Путь отката:
отключить через менеджер plugins или убрать project-level привязку тем способом, который поддерживает текущая установка

Если решение отрицательное, его записывают почти так же коротко. И в этом есть важный педагогический момент: вы учитесь не просто «ставить или не ставить», а объяснять решение инженерным языком. Это особенно полезно для новичков: в команде ценят не только хороший выбор, но и способность объяснить его без тумана и эмоций.

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