Встановлення plugin: scope і lifecycle

1. Встановлення — це вибір радіуса дії, а не кнопка

На словах встановлення plugin звучить майже невинно: натиснули команду, отримали інструмент, пішли далі. Але в реальному workflow це не кнопка, а рішення про радіус дії. Ви відповідаєте не лише на «чи хочу я цей plugin», а й на «де він почне жити і хто його відчує». Саме тут багато хто спотикається: здається, що встановлення — особиста справа, а за пʼять хвилин plugin уже впливає на весь репозиторій і дивує колег.

Корисно тримати в голові просту формулу-камертон: permissions відповідають за те, що плагін може робити, а scope — за те, де і для кого він існує. Сьогодні нас цікавить саме scope. Йдеться про механіку вже вибраного кандидата або експерименту в пісочниці, який ви тримаєте у вузькому scope: саме вміння ставити plugin не виправдовує встановлення першого-ліпшого package.

# Концептуально: точні команди та прапорці можуть відрізнятися у вашій версії Claude Code
/plugin install team-review-kit --scope user     # встановити плагін лише для себе
/plugin list                                     # подивитися список установлених плагінів
/plugin details team-review-kit                  # побачити склад, scope і основні відомості

Важлива тонкість у тому, що «встановлено» і «уже бере участь у поточній сесії» — не завжди одне й те саме. Десь plugin підхопиться відразу, десь знадобиться оновити список plugins, перезапустити сесію або відкрити проєкт заново. Пакет лежить у системі — і пакет підхопило середовище: розрізняйте ці два кроки, інакше народжується «я ж поставив, чому нічого не змінилося?».

2. Scope: де плагін живе і кого він стосується

Коли ви вперше бачите кілька scope підряд, усе це виглядає як трохи бюрократичний набір слів. Але ідея дуже побутова. Уявіть викрутку: її можна покласти до своєї особистої шухляди, залишити на одному робочому столі, прибрати до спільної шафи команди або отримати централізовано від комірника. З плагінами так само — один і той самий team-review-kit у різних scope означає різне коло впливу.

Ось зручна карта, до якої варто повертатися щоразу перед встановленням:

user

local

project

managed

Назви scope між версіями можуть відрізнятися — user десь називається personal — але логіка та сама.

flowchart TD
    A[Потрібно встановити плагін] --> B{Кому він потрібен?}
    B --> C[Лише мені
в усіх проєктах
user]
    B --> D[Лише мені
в одному repo
local]
    B --> E[Усій команді
в цьому repo
project]
    B --> F[Організації централізовано
managed]

Найчастіша плутанина — між user і local: новачкові вони здаються майже однаковими, «в обох випадках це ж лише я». Але різниця суттєва. user — як покласти інструмент у свій рюкзак: носите його по всіх проєктах. local — як залишити інструмент на одному верстаку: у сусідньому репозиторії його вже немає. Тестуєте review-plugin лише для Commerce OS — local розумніше за user.

3. Project scope — це вже не особисте налаштування

З project scope починається доросле життя. До цього ви переважно возилися зі своїм середовищем — «я собі поставив зручну штуку». Але щойно plugin привʼязується до repo, це вже рішення про проєктний workflow, шматок спільної інфраструктури, навіть якщо всередині поки що два безневинні skill-компоненти.

Уявіть, що команда Commerce OS вирішила користуватися єдиним review workflow. Обираючи project scope, ви кажете: plugin стосується цього repo, а не всіх моїх проєктів. Де саме живе привʼязка — у конфігу проєкту чи як стан у менеджера plugins — залежить від реалізації, тому перед розгортанням перевірте довідку й домовтеся, як команда буде його поширювати та вимикати.

Навіть проста фіксація рішення робить життя спокійнішим:

## Plugin baseline

Плагін: team-review-kit
Scope: project
Навіщо: єдиний review workflow для Commerce OS
Кого стосується: тих, хто працює за спільним plugin baseline цього repo
Як вимкнути: тимчасово disable; повністю прибрати project-level привʼязку тим способом, який підтримує поточне встановлення

Зверніть увагу, це не складна документація і не «процес заради процесу», а спосіб не забути, навіщо в проєкту взагалі зʼявився plugin рівня project. Інакше за місяць трапляється класика: половина команди вважає його обовʼязковим стандартом, друга — чиїмось експериментом, а автор уже сам не памʼятає, з чого все почалося.

Практичне правило тут просте: якщо plugin сирий, живе один день і потрібен лише вам — не поспішайте з project. Спочатку доведіть, що він потрібен команді, а не лише автору вчорашнього ентузіазму.

4. Namespace: навіщо плагіну «прізвище»

Історія з namespace дуже схожа на звичайне людське життя. Поки в групі один Діма, можна просто «Діма». Зʼявляється другий — і раптово зʼясовується, що прізвища не бюрократія, а спосіб не плутати людей. З іменами плагінів рівно та сама історія: один review-плагін — імʼя review зручне, зʼявляється другий із подібним змістом — починається легкий організаційний жах.

Уявімо два набори: один для review коду, другий — для review документації. Без namespace це може виглядати так:

Без namespace:
- review
- review

На вигляд усе красиво. На практиці не зрозуміти, який саме review викликався, звідки він прийшов і чому замість перевірки PR ви раптом отримали поради щодо README. З namespace картина стає людяною:

З namespace:
- review-kit:pr-review
- docs-kit:review

Точний формат імені залежить від реалізації, але ідея одна: namespace додає skill або команді «прізвище». Це особливо важливо саме на етапі встановлення. Чому? Тому що конфлікт імен стає помітним не тоді, коли ви пишете plugin, а тоді, коли в одному середовищі починають жити кілька plugin одночасно.

Новачкові namespace здається надмірним: «У нас же поки один plugin». Це логіка приблизно рівня «я поки один Діма, прізвище мені не потрібне». Але такі речі ставляться не на один день. Середовище росте, команди нашаровуються, колеги приносять свої інструменти й артефакти. Якщо закласти namespace від самого початку, потім не доведеться влаштовувати болісну міграцію імен, пояснювати всім, чому старі команди раптом перестали працювати, і ловити конфлікти в дусі «а у мене review робить не те».

Хороший namespace не зобовʼязаний звучати як назва стартапу. Його задача набагато прозаїчніша: бути зрозумілим і стабільним. team-review-kit, commerce-tools, docs-kit працюють краще, ніж абстрактне super-ai-pro. З іменами плагінів узагалі корисно трохи менше поезії й трохи більше інженерного сенсу.

5. Життєвий цикл: install → use → update → uninstall

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

Найкорисніша ментальна модель тут така: install → activate → use → update → disable → uninstall. Навіть якщо інтерфейс обʼєднує якісь кроки, розділяти їх подумки все одно зручно.

install

activate

use

update

disable

uninstall

Концептуально це може виглядати так:

# Концептуально: назви команд і прапорців залежать від версії Claude Code
/plugin update team-review-kit       # оновити плагін
/plugin disable team-review-kit      # тимчасово вимкнути
/plugin enable team-review-kit       # знову увімкнути
/plugin uninstall team-review-kit    # видалити повністю

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

Найменш оцінений крок тут — update. Люди часто ставляться до оновлення як до технічної рутини: «ну вийшла нова версія, поставимо». Але оновлення plugin — це майже новий install. У нової версії може змінитися склад, поведінка, характер підказок, навіть непряме навантаження на контекст. Тому оновлювати plugin «автоматом, бо цифра версії стала більшою» — погана звичка. Набагато здоровіше ставитися до update як до нової версії договору: ви ще раз перевіряєте, що саме прийняли у свій workflow.

6. Практичний розбір: ставимо реальний плагін із claude-plugins-official

До цього моменту ми міркували про install, scope, namespace і lifecycle на синтетичному team-review-kit. Це зручно для пояснення, але в якийсь момент корисно побачити, як той самий цикл виглядає на реальному плагіні з реального marketplace. Так поняття з лекції перетворюється на навичку, яку можна повторити руками.

Marketplace, з якого має сенс почати, — це claude-plugins-official. Це каталог плагінів, який підтримує Anthropic і який доступний у Claude Code за замовчуванням. Якщо ви нічого спеціально не налаштовували, він уже підключений, і вам не потрібно окремо додавати джерело. Це важлива деталь: для більшості користувачів шлях від «хочу спробувати» до «уже встановлено» коротший, ніж здається.

Найперше корисне діяння — подивитися, які marketplace у вас уже активні та які плагіни в них доступні. Концептуально це виглядає так:

# Концептуально: точні назви команд і формат виводу залежать від версії Claude Code
/plugin marketplace list                                      # які marketplace підключені
/plugin marketplace add anthropics/claude-plugins-official    # якщо з якоїсь причини офіційний не активний

У більшості випадків перший із цих кроків вам уже покаже офіційний marketplace у списку. Другий знадобиться лише в нестандартному налаштуванні — наприклад, якщо ви працюєте в середовищі з власним набором джерел.

Далі — встановлення конкретного плагіна. Візьмемо для прикладу code-review: це дуже впізнавана категорія, і у плагіна простий capability surface, який легко перевірити:

# Концептуально: назви та прапорці можуть відрізнятися у вашій версії Claude Code
/plugin install code-review --scope user      # ставимо лише для себе, без впливу на проєкт
/plugin list                                   # бачимо, що плагін зʼявився
/plugin details code-review                    # дивимося, що всередині

Команда details тут особливо цінна. До запуску плагіна в роботу корисно побачити, що саме він приніс із собою: які в нього slash-команди, які спеціалізовані агенти, які hooks, які вимоги до середовища. Це і є та сама поверхня можливостей, про яку ми говорили в попередній лекції. Жодної магії: пакет, його склад, його права.

Після встановлення можна перевірити плагін на реальній задачі. У code-review сценарій простий: перемикаєтесь на гілку з готовим PR і запускаєте команду плагіна:

# На гілці з готовим PR, концептуально
/code-review                  # вивід у термінал
/code-review --comment        # той самий результат, але опублікований як коментар у PR

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

Тепер найважливіше для дисципліни: вміти так само спокійно відкотити зміни. Не «залишили назавжди, бо начебто працює», а пройти весь ланцюжок lifecycle до кінця:

# Концептуально, послідовність відкату
/plugin disable code-review     # тимчасово вимкнули, не видаляючи
/plugin enable code-review      # повернули назад (якщо ще потрібен)
/plugin uninstall code-review   # прибрали із системи повністю

Ці три кроки — не просто «команди про всяк випадок». Це і є той самий повний цикл install → activate → use → disable → uninstall, який ми щойно обговорили на абстрактному рівні. Коли ви хоча б один раз чесно пройшли його на реальному плагіні, далі будь-який наступний установленний пакет стає не «загадковим новим мешканцем системи», а просто черговим елементом зі знайомим ланцюжком станів.

Корисна звичка: після такого практичного прогону зафіксувати собі коротку нотатку. Не процес заради процесу, а маленька страховка від забудькуватості.

## Plugin trial log

Плагін: code-review (claude-plugins-official)
Навіщо пробував: подивитися, як закриває self-review перед PR
Scope: user (лише мій workflow, без впливу на проєкт)
Результат: допоміг упіймати пропущену перевірку null; шум на простих diff
Рішення: залишаю в user scope, переводити в project поки не буду
Як відкотити: /plugin disable, далі /plugin uninstall

Нотатка потрібна не тому, що ви любите бюрократію. Вона потрібна тому, що за два тижні ви не згадаєте, чому цей плагін у вас взагалі встановлено, у якому scope, і що ви тоді про нього вирішили. Маленький log позбавляє від такої амнезії краще за будь-який коментар у чаті.

І останнє зауваження про стійкість до змін версій, яке варто тримати в голові саме для цієї лекції. Команди встановлення, назви прапорців, формат виводу details і list, навіть спосіб підключення marketplace за замовчуванням — усе це може трохи змінюватися від версії до версії. Не запамʼятовуйте конкретну форму команди як заклинання. Запамʼятайте логіку: підʼєднали marketplace, подивилися каталог, обрали плагін за категорією й поверхнею можливостей, встановили в найвужчий scope, використали в безпечному режимі, за потреби тимчасово вимкнули або зовсім видалили. Ця логіка стабільна. Точна форма кожної команди — ні.

7. Невидима ціна: context overhead і зайві плагіни

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

Корисно памʼятати: установленний plugin — це не просто файл десь на диску. Його опис, назви компонентів, а іноді й інструкції з метаданими стають частиною робочого середовища Claude Code. У Claude немає окремої запиленої полиці під назвою «це колись знадобиться». Якщо plugin активний, він збільшує складність загальної картини. Тому встановлення плагіна завжди має ціну, навіть коли він «нічого такого не робить».

Хороша аналогія — рюкзак. Один додатковий предмет майже не відчувається. Але якщо щоразу кидати туди «раптом знадобиться» і ніколи не розбирати вміст, рюкзак стає важчим, а шукати потрібну річ — довше. З plugin відбувається те саме: невикористані розширення рідко ламають усе одразу, але поступово погіршують оглядовість системи.

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

8. Скрізний приклад: team-review-kit у Commerce OS

Тепер зберемо все в одну реальну картину. У вас є Workflow Kit команди, у якому вже живуть два корисні навички: issue-analysis і pr-review. Ви упакували їх у plugin team-review-kit. Далі перед вами не абстрактне, а дуже живе завдання: як саме підʼєднати цей plugin до Commerce OS, щоб він допомагав, а не створював зайву плутанину.

Різні сценарії потребують різного scope:

local

user

project

managed

Уявімо типову історію. Спочатку team-review-kit іде в local scope Commerce OS: пару днів перевіряєте, чи допомагає pr-review перед PR. Потім підключається другий розробник, workflow повторюється — і ось тепер рішення переводите в project scope, фіксуєте в plugin baseline і окремо перевіряєте, як поточна версія Claude Code зберігає такий рівень встановлення і ділиться ним.

У цей момент на install-команду ви вже дивитеся не як на «чарівний рядок із документації», а як на інженерне рішення з трьома питаннями всередині. Де житиме plugin? Хто його відчує? Як я його вимкну або видалю, якщо експеримент не вдасться? Якщо ви вмієте чесно відповідати на них ще до запуску команди — значить, ви перестали «просто ставити плагіни» і почали працювати з ними як із нормальними артефактами команди.