Extension taxonomy: мапа розширень

1. Коли prompt переростає сам себе

На початку роботи з Claude Code зазвичай достатньо звичайного prompt, CLAUDE.md і акуратної сесії — це нормальний і, більше того, правильний старт. Але з часом зʼявляється дивний ефект: працювати гірше ви не стали, просто дедалі частіше повторюєте одне й те саме. Кожну issue у Commerce OS розбираєте однаково: план, перевірка scope, TASK_SPEC.md, verification. Ті самі обмеження вручну.

І в цей момент проблема вже не в моделі й не у вашій памʼяті. Workflow дозрів до окремого артефакта.

Уявіть типову ситуацію в Commerce OS. Вам регулярно прилітають задачі на кшталт «неправильне сортування refund-запитів», «дублювання в пагінації замовлень», «повільний endpoint для dashboard-метрик». Для кожної — один ритуал: читаєте issue, фіксуєте ціль, scope, non-goals, спосіб перевірки, ризики. Ось як виглядає цей симптом у мініатюрі:

Прочитай issue.
Виділи ціль, scope, non-goals, критерії приймання та план перевірки.
Не змінюй код.
Спочатку покажи кандидати на affected files і ризики.

Один раз — це prompt. Два-три рази на тиждень — кандидат у reusable workflow. Тут і потрібна extension taxonomy — мапа механізмів розширення. Вона потрібна не заради красивих слів, а щоб перестати лікувати різні проблеми одним молотком. Молоток — річ добра. Але не тоді, коли ним лікують Wi‑Fi.

Дуже важливо зафіксувати головну думку цієї лекції. Базовий workflow нікуди не зникає: Task spec, контекст, evidence, Git, diff, review лишаються вашим шляхом. Розширення не замінюють дисципліну — вони роблять її повторюваною, переносною та менш виснажливою.

2. Одна мапа замість зоопарку можливостей

Коли вперше заходите в тему розширень, легко відчути себе людиною, яку завели в величезний будівельний магазин без списку покупок. Усе наче корисне, але незрозуміло, навіщо саме це потрібно просто зараз. Рятує не розсип термінів, а одна мапа: який механізм на яке запитання відповідає. Тримайте її перед очима весь цей блок курсу.

Точні назви, поля конфігів і команди в Claude Code змінюються від версії до версії — але самі категорії та завдання, які вони розвʼязують, залишаються стабільними.

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

flowchart TD
    A[Зʼявився workflow-біль] --> B{Це разове завдання?}
    B -- Так --> P[prompt]
    B -- Ні --> C{Це постійне правило?}
    C -- Так --> D{Для всього проєкту?}
    D -- Так --> CM[CLAUDE.md]
    D -- Ні --> R[rule]
    C -- Ні --> E{Це повторювана процедура?}
    E -- Так --> S[skill]
    E -- Ні --> F{Потрібні зовнішні дані?}
    F -- Так --> M[MCP]
    F -- Ні --> G{Потрібне автоматичне спрацьовування на подію?}
    G -- Так --> H[hook]
    G -- Ні --> I{Потрібен окремий контекст дослідження?}
    I -- Так --> SA[subagent]
    I -- Ні --> J{Потрібно роздати рішення команді?}
    J -- Так --> PL[plugin]

Тут важливо бачити не тільки «що обрати», а й «чого не обирати». Якщо проблема в тому, що Claude забуває команду запуску проєкту, це не привід заводити skill або plugin. Якщо правило стосується лише каталогу payments/, не треба роздувати весь CLAUDE.md. Якщо потрібні дані вже є в кодовій базі, MCP буде зайвим. Дуже часто найкращий інженерний вибір — взагалі не додавати новий шар.

І так, для новачків це особливо важливо. Коли відкриваєте тему розширень, руки самі тягнуться зробити красиво: rules, skills, agents, hooks, MCP, plugin, а якщо зовсім увійти у смак — ще обкладинку для README і трохи драматичної музики. Але хороший workflow росте поступово. Інакше замість корисного набору інструментів ви отримаєте маленький зоопарк, у якому ніхто не розуміє, хто за що відповідає.

3. prompt, CLAUDE.md і rule: типова плутанина

Саме тут найчастіше виникає плутанина. Здається, ніби prompt, CLAUDE.md і rule відрізняються лише місцем, де лежить текст. Насправді різниця між ними не географічна, а інженерна: у них різний строк життя, різний scope і різна причина появи. Якщо це не розрізняти, дуже швидко виходить або роздутий CLAUDE.md, або десять локальних правил замість однієї нормальної проєктної інструкції.

Зручно порівняти їх напряму:

Подивіться на такий фрагмент CLAUDE.md для Commerce OS:

## Команди проєкту
- backend: ./gradlew test
- frontend: npm run test

## Загальні правила
- Спочатку показуй план для нетривіальних змін.
- Не змінюй public API без явного узгодження.

Це хороший кандидат для CLAUDE.md, тому що правило стосується всього проєкту. Неважливо, працюєте ви з catalog/, orders/ чи support/, — загальна дисципліна однакова.

А тепер інший випадок:

# Правило для payments/**

- Перед змінами спочатку покажи план.
- Не змінюй refund logic без доказів регресії.
- Не чіпай суміжні файли «заодно».

Це вже не загальне правило проєкту. Воно потрібне лише в чутливій зоні. Якщо таке правило покласти в загальний CLAUDE.md, воно почне шуміти всюди, навіть там, де не потрібно. А якщо, навпаки, правило для всього проєкту сховати в локальний rule, його просто не побачать у потрібний момент.

Prompt тут живе зовсім за іншими законами. Він гарний, коли завдання одиничне й контекст сильно залежить від поточного запитання. Наприклад, ви хочете один раз попросити:

Перевір, чому /api/orders іноді повертає дублікати.
Спочатку збери evidence і список файлів, яких це стосується.
Код поки не змінюй.

Це не проєктне правило і не повторювана процедура на щодень. Це конкретний запит під конкретну ситуацію.

Якщо зовсім просто, prompt — це поточна репліка, CLAUDE.md — загальний статут проєкту, а rule — локальна табличка на дверях конкретної кімнати. У кожної з цих речей своя робота. Спроба замінити одну іншою майже завжди закінчується тим, що інструкції або забуваються, або починають занадто голосно звучати там, де не потрібні.

4. skill, subagent, MCP, hook, plugin

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

Ось як ця мапа зазвичай виглядає в структурі Workflow Kit:

workflow-kit/
├── .claude/
│   ├── CLAUDE.md
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   ├── hooks/
│   └── mcp/
└── README.md

Ця структура важлива не тому, що «так красиво». Вона показує, що Workflow Kit — це окремий інженерний шар, а не таємна комірчина всередині Commerce OS. Commerce OS — продуктний код. Workflow Kit — надбудова, яка допомагає з ним працювати.

Почнімо зі skill. Це механізм для повторюваної процедури. Якщо ви багато разів проходите один і той самий workflow — наприклад, перетворюєте issue на TASK_SPEC.md, — отже, перед вами вже не «вдалий prompt», а майже готовий skill. У нього є тригер, вхід, обмеження й очікуваний результат. Skill відповідає не на запитання «що мені сказати моделі», а на запитання «як відтворювано провести процедуру».

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

MCP відповідає на зовсім інше запитання: як дати Claude доступ до зовнішніх даних або дій. Це історія про issue tracker, моніторинг, документацію, базу даних, дії в браузері. Дуже важлива межа тут така: якщо інформація вже є в репозиторії, MCP не потрібен. Не потрібно тягнути зовнішній протокол заради того, що спокійно читається з коду та конфігів. MCP — це міст назовні, а не новий спосіб прочитати локальний файл.

Hook — це реакція на подію. Не правило, не процедура і не зовнішнє джерело даних. У hook інший характер: що має статися автоматично, коли спрацьовує певна подія. Наприклад, після редагування варто прогнати форматування. Або перед небезпечною дією заблокувати шлях. З hook дуже легко перестаратися. Якщо skill — це «зроби процедуру повторюваною», то hook — це «зроби реакцію автоматичною». А автоматизація без акуратних меж дуже швидко перетворюється на невелику, але набридливу катастрофу.

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

5. Вибір механізму без ворожіння та зайвого ентузіазму

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

Нижче — кілька типових ситуацій із зв’язки Commerce OS + Workflow Kit:

Зверніть увагу, чого в таблиці немає. Немає «важлива річ — отже plugin». Немає «хочеться автоматизації — отже hook». Немає «звучить солідно — підключимо MCP». Дуже часто правильна відповідь виглядає скромно: розвʼязується через CLAUDE.md — не заводьте rule; вистачає rule — не робіть plugin; повторюваність не доведена — не поспішайте зі skill.

Такі рішення корисно фіксувати письмово — наприклад, у README Workflow Kit або поруч з артефактом. Ось короткий формат, який справді допомагає:

# Чому зʼявився rule для payments/**

Проблема: Claude пропонував занадто широкі зміни поруч із refund logic.
Рішення: окремий scoped rule лише для payments/**.
Чому не CLAUDE.md: обмеження не стосується інших модулів проєкту.

Це здається дрібницею — але саме такі нотатки перетворюють «набір файлів у .claude/» на зрозумілу інженерну систему. Через місяць уже не згадати, чому правило живе саме тут. А коротке обґрунтування знижує шанси на хаос і священні війни в дусі «давайте перенесемо все в одне місце».

Коли у вас перед очима є ця мапа, Claude Code перестає бути коробкою із загадковими фічами. Ви бачите набір відповідей на workflow-запитання: де вистачить звичайного prompt, де потрібен стабільний CLAUDE.md, де допоможе локальний rule, а де краще взагалі нічого не додавати. З цього й починається доросла робота з розширеннями: не «що б ще увімкнути», а «яку конкретну біль я зараз розвʼязую».