Інтеграція інструментів: шість сценаріїв

1. Інструмент корисний, коли скорочує шлях до перевірки

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

Issue, alert моніторингу, дані з БД лише для читання, дизайн, документація та перевірка в браузері здаються шістьма різними світами. Насправді каркас один і той самий: інструмент залишається можливістю, а робочий процес починається там, де сигнал перетворюється на гіпотезу, план і перевірку. Інакше виходить знайома офісна картина: вам переслали лист, ви переслали його Claude, Claude переслав вам упевнене судження, а код як був не перевірений, так і лишився.

flowchart TD
    A[Зовнішній сигнал] --> B[Гіпотеза]
    B --> C[План]
    C --> D[Невелика зміна]
    D --> E[Перевірка]
    E --> F[Артефакт у репозиторії]

Зверніть увагу на середину схеми. Гіпотеза й план між «отримали сигнал» та «зробили diff» — це захист від моменту, коли сервіс підкинув гору контексту, а ви сприйняли її як готовий діагноз. Жодне джерело не дає права перескочити крок «зрозуміти, що відбувається в коді».

Щоб не втрачати нитку, зручно тримати поруч невелику робочу нотатку — біля TASK_SPEC.md або в його секції:

## Зовнішній сигнал
Issue COM-142: дублікати в списку повернень

## Гіпотеза
Проблема в сортуванні на рівні сервісу, а не в SQL-запиті

## Перевірка
Тест сортування + ручна перевірка inbox

## Артефакт
TASK_SPEC.md + PR_DESCRIPTION.md

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

2. Issue-to-PR: трекер допомагає мислити

Найзрозуміліший сценарій — робота з issue tracker. Тут попередня перевірка вже зафіксувала межі: tracker — джерело задачі лише для читання, а твердження з коментарів залишаються даними, доки їх не підтвердять код і tests. Цінність інтеграції в тому, що скарга швидше перетворюється на TASK_SPEC.md. У Workflow Kit у нас є інтеграція лише для читання на кшталт .claude/mcp/issue-tracker.json — доступ до картки, коментарів, міток, скриншотів, посилань на обговорення. Далі звичайна інженерія: issue → TASK_SPEC.md, дослідження коду, маленький план, і лише тоді diff.

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

# TASK_SPEC.md

Завдання: виправити порядок заявок на повернення в inbox підтримки
Джерело: issue COM-142
Scope: модуль support inbox і пов’язаний тест сортування
Не змінювати: API списку заявок і схему БД
Перевірка: тест сортування + ручна перевірка в UI
Ризик: не зачепити звичайні тікети без повернення

Тепер Claude працює за структурою, а не за емоцією «критично». Дуже корисно задавати Claude вузькі рамки: не «розбери issue», а «прочитай issue, пов’яжи його з кодом, запропонуй affected files, підготуй чорновик TASK_SPEC.md і вкажи, яких фактів бракує».

Хороший issue-to-PR workflow тримається на ланцюжку: discovery, diff, tests, PR_DESCRIPTION.md. Випаде з нього хоч один крок — і інтеграція знову перетвориться на красиве пересилання контексту.

3. Monitoring triage: alert — сирена, не діагноз

Із моніторингом працює та сама схема, тільки сигнал тут живе в середовищі виконання. Попередня перевірка заздалегідь фіксує режим лише для читання: інструмент покаже alert і обмежене вікно логів. Тому alert потрібен не як план виправлення, а як старт тріажу.

Якщо перескочити через крок відтворення, вийде класичний patch loop: Claude виправляє симптом, з’являється новий, потім ще один, і через двадцять хвилин у вас три зміни в unrelated-файлах і жодної відповіді на запитання «що було кореневою причиною».

Тут дуже допомагає EVIDENCE_LOG.md — він перетворює alert з емоційного подразника на інженерний журнал спостережень.

# EVIDENCE_LOG.md

Сигнал: зростання помилок 500 на /api/orders/{id}/refund
Вікно логів: 10:12–10:18
Гіпотеза: таймаут під час повторної перевірки статусу повернення
Перевірка: відтворити локально запит із тим самим сценарієм
Підтвердження: падає регресійний тест RefundTimeoutTest

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

Якщо сказати зовсім просто, monitoring workflow звучить так: alert → hypothesis → reproduce → fix → regression check. Поки немає reproduce і regression check, інтеграція не замикається — є лише тривожний дзвінок і чужа впевненість. А впевненість без відтворення майже декоративна.

4. Read-only БД: дивимося сміливо, лікуємо через код

Із БД лише для читання попередня перевірка вже зробила за нас головний вибір: дивитися можна, лікувати руками — ні, і це одразу знімає найнебезпечнішу ілюзію. База показує форму проблеми, але не пояснює її причину.

Припустімо, у Commerce OS ви бачите дивні дублікати заявок на повернення. Read-only запит підтвердить, що дублікати є і в якому вони обсязі, — і суперечка «нам здалося» змінюється розмовою по фактах.

SELECT order_id, COUNT(*) AS cnt
FROM refund_requests
GROUP BY order_id
HAVING COUNT(*) > 1;

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

Саме тому аналіз БД лише для читання завжди має замика́тися на код і перевірку. Дуже зручно пов’язувати результат з API_MAP.md або знайденою кінцевою точкою: побачили дублікати — через карту API і дослідження знайшли шлях /api/orders/{id}/refund — перевірили сервіс — додали regression test.

Є ще одна причина триматися за режим лише для читання як за default. База даних любить правду, але не любить імпульсивні UPDATE і DELETE, особливо «просто щоб швидко перевірити гіпотезу». Правило однакове в навчальному й робочому базовому сценарії: зміни даних ідуть через код, міграції, тестові сценарії та підтвердження людиною. Не тому, що так гарніше на папері, а тому, що так дешевше платити за помилки.

5. Design-to-code: макет — це контекст, а не наказ

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

Дизайн-інтеграції та скриншоти часто викликають у новачків дивну суміш захвату й паніки. Захват — «Claude побачить макет і все зверстає». Паніка — макет майже завжди акуратніший за поточний екран, і рука тягнеться «заодно трохи переробити все». Оце «заодно» і перетворює маленьке UI-завдання на раптовий ремонт половини інтерфейсу.

Правильний design-to-code workflow починається не з генерації компонентів, а зі зіставлення дизайну з реальним кодом. Макет, скриншот, коментар дизайнера — це зовнішній сигнал: інтерфейс має виглядати інакше.

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

## UI-завдання

Екран: картка тікета в support inbox
Змінити: зробити кнопку "Повернення" візуально помітнішою
Не змінювати: поведінку форми, API та логіку надсилання
Перевірка: скриншот до/після + ручний прохід у браузері

Після цього Claude допоможе знайти компонент і запропонувати мінімальну зміну. Зверніть увагу: дизайн тут — reference, а не автогенератор архітектури. Ваших компонентів, обмежень верстки, правил теми й історії багів він не знає; це знає кодова база і TASK_SPEC.md.

Корисно ставитися до design-to-code як до перекладу з однієї мови на іншу: макет говорить мовою інтерфейсу, репозиторій — мовою компонентів і обмежень. Claude може бути перекладачем між ними, але не диктатором, який оголошує війну коду лише тому, що дизайнер змінив відступ із 12 пікселів на 16. Іноді це справді важлива зміна — але зрозуміти це можна всередині workflow, а не за красою макета.

6. Docs lookup і browser checks разом

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

Docs lookup особливо корисний там, де ви не хочете покладатися на пам’ять Claude: на фіксованому стеку потрібен точний синтаксис конфігурації. Замість гадань за минулим проєктом Claude дістає вузький факт, а ви застосовуєте його до файлу й перевіряєте локальним збиранням.

Але документація сама по собі задачу не закриває. Browser workflow тут виконує роль фінального заземлення: не «вірю, що компонент виглядає правильно», а відтворюю сценарій, роблю скриншот і перевіряю, що інтерфейс не зламав сусідні елементи.

## Перевірка в браузері

Сторінка: /admin/support
Сценарій: відкрити тікет і натиснути "Повернення"
Очікування: кнопка помітна, форма відкривається, верстка не стрибає
Факт: сценарій проходить, зсуву layout не спостерігається

Зверніть увагу, як гарно замикається цикл, і лише тоді ви кажете «зміна прийнята». Без browser check design-to-code та docs lookup лишаються дуже розумними припущеннями. Розумне припущення, звісно, краще за дурне — але до перевіреної інженерної дії воно все ще не дотягує.

7. Один каркас для шести сценаріїв

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

Нижче — компактна карта, яку корисно буквально тримати під рукою, коли ви проєктуєте tool integration у Workflow Kit.

TASK_SPEC.md

PR_DESCRIPTION.md

EVIDENCE_LOG.md

EVIDENCE_LOG.md

API_MAP.md

TASK_SPEC.md

TASK_SPEC.md

EVIDENCE_LOG.md

Якщо спростити до однієї фрази, то сьогоднішня лекція ось про що: зовнішній інструмент не робить роботу за вас, він робить ваш наступний крок точнішим. А ви разом із Claude Code перетворюєте цю точність на нормальний інженерний цикл: зрозуміти, спланувати, змінити, перевірити й зафіксувати в артефакті репозиторію.

Саме тому й не потрібно тримати в голові шість різних «інтеграцій». Достатньо вміти впізнавати один каркас у різному одязі: issue, alert, рядки з бази, макет, сторінка документації, поведінка в браузері — на вході різні, а маршрут до артефакту в репозиторії один. Освоїли його на трекері — майже безкоштовно отримуєте monitoring, базу, дизайн, документацію й браузер. Далі в курсі цей самий маршрут ми переносимо всередину Claude Code: там, де дія повторюється від сесії до сесії, її підхоплюють hooks.