Tool capability preflight для MCP

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.

Самые важные строки здесь — не про технику, а про дисциплину: disallowed actions, verification и kill switch. Многие команды охотно описывают, что инструмент умеет, и почти не описывают, чего ему нельзя, — а потом удивляются write-capable integration там, где всем нужен read-only.

Практическое правило здесь простое: по умолчанию tool получает read-only роль. Session permissions говорят «технически возможно»; workflow boundary должен быть уже: «в этой задаче делаем только вот это».

И ещё одна важная мысль. Exact names команд, 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

Pain: не копируем issue и комментарии вручную в сессию.
Allowed: read issue, read comments, search by label.
Forbidden: comment, close, reassign, change labels.
Credentials: read-only token из env.
Verification: claims из issue сверяем с кодом и tests.
Kill switch: отключаем project scope config и перезапускаем сессию.

Фрагмент короткий, но он уже решает половину проблем. Теперь под такой preflight уже можно формулировать задачу Claude:

Прочитай issue COM-142 через tracker.
Разрешено только чтение issue и комментариев.
Не меняй статус, labels и 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» тему не закрыть. Сравним три сценария.

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 намекает на третье, а код: «Коллеги, у меня тут вообще четвёртая история». В этот момент важно не назначать победителя по принципу «внешний убедительнее». Лучше смотреть на источники трезво:

Эта таблица снимает соблазн искать «единственный source of truth» на все случаи жизни — универсального источника здесь нет. Когда источники спорят, правильная реакция — не выбрать любимый, а превратить конфликт в проверяемую гипотезу.

Хороший ход — остановить edits и попросить Claude сделать именно расследование:

Есть конфликт между внешним источником и codebase.
Не вноси изменений.
Покажи, какие claims подтверждаются кодом, какие только issue/docs,
и предложи минимальную проверку, которая снимет конфликт.

Это очень сильная привычка. Сначала фиксируете, в чём именно расхождение, потом — минимальную проверку: локальный reproduce, 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 держите короткую политику:

### Внешние инструменты: позиция по умолчанию

Default mode: read-only first.
Project scope: only after written preflight.
Conflict rule: tool claims are hypotheses until verified in code/tests.
Kill switch: every tool must have one-step disable path.

Это не бюрократия ради бюрократии, а способ превратить индивидуальную осторожность в командную норму: новый разработчик видит не только integrations, но и подход команды.

Scope. Ещё один практический момент — scope. Tool сырой, неочевидный или нужен только вам для эксперимента — держите на личном или локальном уровне. Project scope — общая ответственность: только integrations с понятным сценарием, verification path и owner.

Kill switch. Отдельно стоит уважать kill switch. Интеграцию нельзя быстро отключить — она не готова к реальной жизни. Где-то это отключение project-scoped config, где-то отзыв токена, где-то временный возврат на local scope. Механика зависит от версии Claude Code и инфраструктуры, но принцип один: у команды должен быть короткий путь назад. Без него automation выглядит смело только до первого инцидента.

Когда вы соберёте ответы на все десять вопросов preflight в одном месте — у вас на руках не «ещё один подключённый server», а полный контур: названа боль, сужены capabilities, выписаны disallowed actions, зафиксированы credentials и объём context, назначен способ verification и есть kill switch. Именно этот контур, а не сам факт подключения, отличает управляемую интеграцию от рычага без правил. Дальше, в следующей лекции, тот же каркас мы прогоним через шесть разных внешних сигналов — и увидим, что меняется только сигнал и проверка на конце, а логика остаётся одна.