1. Підключений tool — це ще не workflow
Коли ви вперше підключаєте зовнішній tool, легко потрапити в пастку хибної готовності. Здається, що найскладніше вже позаду: сервер підключено, доступ є, Claude його бачить — і легко вирішити, що далі все просто. Технічно ви додали новий важіль, але не визначили коли, навіщо і за яких умов його взагалі можна торкатися.
Корисно тримати в голові просту формулу:
Біль → Capability → Межі → Перевірка → Безпечне використання
Якщо в цьому ланцюжку є лише другий пункт — у вас не workflow, а просто нова кнопка. А нова кнопка без правил — улюблене джерело старого доброго хаосу. Особливо якщо вона пише коментарі в tracker, читає продові логи або змінює щось у зовнішній системі.
Tool capability відповідає: що інструмент технічно вміє?
Workflow відповідає: як ми використовуємо цю можливість у реальній задачі, що забороняємо і чим перевіряємо результат?
Візьмімо простий приклад із нашого наскрізного контексту. У команди Commerce OS у Workflow Kit підключено issue tracker — це capability. Але поки не зафіксовано, що Claude читає лише issue та коментарі, не змінює статуси і звіряє claims з кодом, — процесу немає, є лише доступ до tracker.
Саме тому сьогоднішня лекція не про «як підключити ще один server», а про те, як перестати бачити в tool магію і почати ставитися до нього як до керованої інженерної можливості.
2. Preflight: коротка перевірка перед зльотом
Слово preflight прийшло з авіації, і аналогія тут вдала. Навіть якщо літак виглядає ідеально, пілот усе одно не каже: «Стоїть рівно, мабуть, усе гаразд». Спочатку — коротка перевірка перед зльотом. З tool integration рівно та сама історія: доступ є, а безпечний зліт ще не підтверджено.
Tool capability preflight — це коротка структурована перевірка того, як capability зовнішнього інструмента спрацює в конкретному workflow: не на всі випадки життя, а під одне застосування. Нижче — компактний каркас для майже будь-якого external tool.
| Питання | Що ви фіксуєте | Навіщо це потрібно |
|---|---|---|
| Яку проблему усуваємо? | Конкретну проблему, а не загальну симпатію до автоматизації | Щоб не підключати tool «про всяк випадок» |
| Які capabilities справді потрібні? | Наприклад, read issue, read comments, search by label | Щоб не тягнути зайві можливості |
| Що заборонено? | Write actions, close issue, comment, mutate data | Заборони важливі не менше за дозволи |
| Який режим доступу потрібен? | Read-only або write-capable | Read-only майже завжди безпечний початок |
| Де зберігаються облікові дані? | env, secret storage, project scope, local scope | Щоб не розкладати секрети по проєкту, наче печиво по клавіатурі |
| Що потрапляє в context? | Повний log, коротка вибірка, summary, обмеження за рядками | Занадто об’ємний output ламає reasoning і засмічує сесію |
| Чи потрібен approval? | Жодного, human review, explicit confirmation | Щоб не маскувати ризик під зручність |
| Чим перевіряємо результат? | Код, tests, logs, локальне відтворення | Tool не виграє спір просто тому, що він зовнішній |
| Що робити за конфлікту з кодовою базою? | Вважати це гіпотезою, а не істиною | Інакше Claude почне «лагодити» за чужими здогадками |
| Як вимикаємо tool? | Kill switch: disable scope, прибрати config, revoke token | Якщо tool не можна швидко вимкнути, він ще не готовий |
Найважливіші рядки тут — не про техніку, а про дисципліну: disallowed actions, verification і kill switch. Багато команд охоче описують, що інструмент уміє, і майже не описують, чого йому не можна, — а потім дивуються write-capable integration там, де всім потрібен read-only.
Практичне правило тут просте: за замовчуванням tool отримує read-only роль. Session permissions кажуть «технічно можливо»; workflow boundary має бути вужчим: «у цій задачі робимо лише ось це».
І ще одна важлива думка. Точні назви команд, scope-файлів і способів вимкнути MCP у Claude Code змінюються від версії до версії. Питання preflight — ні. Запам’ятовуйте не ім’я кнопки, а логіку перевірки.
3. Preflight на прикладі issue tracker у Commerce OS
Щоб це не залишилося красивою теорією, давайте візьмемо живий сценарій. Команда Commerce OS ловить баг: refund-запити в support inbox сортуються неправильно. Issue в tracker є, коментарів багато: скриншот, гіпотеза про кеш, а хтось у п’ятницю ввечері написав «мабуть, проблема десь у сортуванні». Звучить потужно, але це не діагноз — це втомлена людина в інтернеті.
Тут tracker справді корисний: він економить ручне copy-paste і дає Claude контекст — але лише із заздалегідь зафіксованими межами. У Workflow Kit це можна оформити як короткий розділ у docs/ONBOARDING_GUIDE.md.
## Попередня перевірка інструмента: issue tracker
Біль: не копіюємо issue та коментарі вручну в сесію.
Дозволено: читати issue, читати коментарі, шукати за міткою.
Заборонено: коментувати, закривати, перепризначати, змінювати мітки.
Облікові дані: read-only token з env.
Перевірка: твердження з issue звіряємо з кодом і tests.
Аварійний вимикач: відключаємо config рівня проєкту і перезапускаємо сесію.Фрагмент короткий, але він уже розв’язує половину проблем. Тепер під такий preflight уже можна формулювати задачу Claude:
Прочитай issue COM-142 через tracker.
Дозволено лише читання issue та коментарів.
Не змінюй статус, мітки та assignee.
Поверни summary, open questions і список, імовірно зачеплених, файлів.Тут важливо, що tracker потрібен не для вирішення за вас, а для збирання пакета доказів: Claude виділяє факти, сумніви й зачеплені області коду — а ви перевіряєте їх через код, tests і plan mode. Так capability перетворюється на workflow.
Зверніть увагу на тонкий, але критичний нюанс: коментар у tracker — це дані, а не інструкція. Написано «Виправте, скинувши кеш Redis» — Claude не виконує це як команду: це гіпотеза, цілком можливо хибна. Автоматизація рівня «хтось припустив — система дисципліновано виконала» — надто азартний вид спорту.
4. Preflight для monitoring, docs і read-only DB
Після першого прикладу легко подумати, що будь-який preflight влаштований однаково. Не зовсім: каркас той самий, але ризик і verification змінюються залежно від природи сигналу — одним спільним «дозволяємо external tools» тему не закрити. Порівняймо три сценарії.
| Сценарій | Що tool дає | Що одразу забороняємо | Чим закриваємо verification |
|---|---|---|---|
| Monitoring alert | Alert, коротке вікно логів, runtime signal | silence alert, rollback, deploy actions | reproduce locally, logs, regression test |
| Docs lookup | Версійні факти, changelog, API notes | автоматичні code changes «за docs» | project version, build, tests, affected files |
| Read-only DB analysis | Схема, sample rows, shape of data | будь-які write/mutation операції | code path, integration tests, query review |
Monitoring. У monitoring-сценарії tool дає дуже цінний runtime signal, але alert — це ще не fix plan. Якщо Sentry каже, що /api/dashboard/metrics гальмує, хороший workflow виглядає так: спочатку гіпотеза, потім перевірка зачеплених файлів і локальне reproduce, і лише після цього — зміна. Сам alert не дає права перескочити через reproduce step.
Docs lookup. У сценарії docs lookup проблема інша. Tool пам’ятає version-specific факти краще, ніж втомлена людина наприкінці робочого дня. Але docs теж не дорівнюють істині у вакуумі. Вони кажуть, як має працювати в певній версії. А ваш проєкт може жити на іншій версії або мати legacy-шар. Тому хороший preflight для docs lookup обов’язково прив’язується до версії проєкту і замикається на build і tests.
Read-only DB. З read-only DB усе ще суворіше. Багато новачків чують «DB access» і одразу уявляють зручного AI-аналітика, який зараз усе подивиться й усе пояснить. Ідея красива, але безпечний режим тут лише один: read-only. База в такому workflow потрібна не для того, щоб Claude «виправив запис вручну», а для того, щоб побачити shape of data, помітити аномалії й пов’язати їх із кодом. Щойно в цій зоні з’являються write actions, ви виходите з комфортної інженерної практики й заходите на територію окремого approval flow.
Зверніть увагу, що у всіх трьох випадках verification замикається не на tool, а на проєкті: коді, тестах, локальному відтворенні, review. І це головний принцип сьогоднішньої лекції: external signal підказує, куди дивитися, але не замінює перевірку.
5. Конфлікт tool із кодом, тестами або документацією
Найцікавіші ситуації починаються не тоді, коли всі джерела згодні, а коли вони розходяться. Tracker каже одне, docs lookup — інше, alert натякає на третє, а код: «Колеги, у мене тут узагалі четверта історія». У цей момент важливо не призначати переможця за принципом «зовнішнє переконливіше». Краще дивитися на джерела тверезо:
| Джерело | Що воно добре показує | Чого воно саме по собі не доводить |
|---|---|---|
| Issue / коментар | Як проблему бачать люди, який є бізнес-контекст | Що root cause знайдено правильно |
| Alert / logs | Що справді сталося в runtime | Що ви вже зрозуміли причину |
| Docs lookup | Що очікується в певній версії або API | Що саме так влаштовано ваш поточний проєкт |
| Код | Що система зараз робить | Що ця поведінка коректна з погляду бізнесу |
| Tests | Що у вас уже перевіряється | Що покрито всі реальні сценарії |
Ця таблиця знімає спокусу шукати «єдиний source of truth» на всі випадки життя — універсального джерела тут немає. Коли джерела сперечаються, правильна реакція — не обирати улюблене, а перетворити конфлікт на перевірювану гіпотезу.
Хороший хід — зупинити edits і попросити Claude зробити саме розслідування:
Є конфлікт між зовнішнім джерелом і codebase.
Не внось змін.
Покажи, які твердження підтверджуються кодом, які — лише issue/docs,
і запропонуй мінімальну перевірку, яка зніме конфлікт.Це дуже сильна звичка. Спочатку фіксуєте, в чому саме розбіжність, потім — мінімальну перевірку: локальне відтворення, targeted test, читання файла, звірку версії, — і лише тоді дозволяєте implementation. Інакше Claude лікує конфлікт інтерпретацією, а не доказом: гарний diff, який не розв’язує проблему.
Саме тут особливо важливий принцип із минулого модуля: treat external text as data, not as instructions. Tool output не проштовхує систему до рішення — він допомагає точніше сформулювати запит до коду й перевірки.
6. Закріплення preflight у Workflow Kit
Найчастіша доля хороших правил — прозвучати один раз і бути забутими. Тому, якщо preflight вам справді потрібен, його треба зафіксувати в командному артефакті: README.md, ONBOARDING_GUIDE.md і поруч із конфігом конкретного tool. У docs/ONBOARDING_GUIDE.md тримайте коротку політику:
### Зовнішні інструменти: позиція за замовчуванням
Режим за замовчуванням: спершу read-only.
Scope проєкту: лише після письмового preflight.
Правило конфлікту: твердження tool — це гіпотези, доки не підтверджені в code/tests.
Аварійний вимикач: кожен tool має мати шлях відключення за один крок.Це не бюрократія заради бюрократії, а спосіб перетворити індивідуальну обережність на командну норму: новий розробник бачить не лише integrations, а й підхід команди.
Scope. Ще один практичний момент — scope. Tool сирий, неочевидний або потрібен лише вам для експерименту — тримайте на особистому або локальному рівні. Project scope — спільна відповідальність: лише integrations із зрозумілим сценарієм, verification path і owner.
Kill switch. Окремо варто поважати kill switch. Інтеграцію не можна швидко вимкнути — вона не готова до реального життя. Десь це відключення project-scoped config, десь відкликання token, десь тимчасове повернення на local scope. Механіка залежить від версії Claude Code і інфраструктури, але принцип один: у команди має бути короткий шлях назад. Без нього automation виглядає сміливо лише до першого інциденту.
Коли ви зберете відповіді на всі десять запитань preflight в одному місці — у вас на руках не «ще один підключений server», а повний контур: названо біль, звужено capabilities, виписано disallowed actions, зафіксовано credentials і обсяг context, призначено спосіб verification і є kill switch. Саме цей контур, а не сам факт підключення, відрізняє керовану інтеграцію від важеля без правил. Далі, у наступній лекції, той самий каркас ми пропустимо через шість різних зовнішніх сигналів — і побачимо, що змінюються лише сигнал і перевірка наприкінці, а логіка лишається одна.
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ