Перевірка 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 тримає експеримент у межах одного репозиторію. project повʼязує plugin із проєктним workflow, і ціна помилки там вища — неважливо, чи зберігається привʼязка в конфігу з репозиторію, чи в стані рівня проєкту поточної версії 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
або прибрати привʼязку на рівні проєкту тим способом, який підтримує ваша версія 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 заново.

Формат може бути зовсім коротким:

Плагін: team-review-kit v0.2.0
Scope: project
Рішення: встановлюємо

Навіщо:
єдиний workflow для issue-analysis і pr-review

Що вміє:
лише skills, без hooks, мережі та credentials

Обмеження:
використовуємо лише для review-задач

Шлях відкату:
вимкнути через менеджер plugins або прибрати привʼязку на рівні проєкту тим способом, який підтримує поточне встановлення

Якщо рішення негативне, його записують майже так само коротко. І в цьому є важливий педагогічний момент: ви вчитеся не просто «встановлювати чи не встановлювати», а пояснювати рішення інженерною мовою. Це особливо корисно для новачків: у команді цінують не лише хороший вибір, а й здатність пояснити його без туману та емоцій.

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