Tool integration: шесть сценариев

1. Tool полезен, когда сокращает путь к проверке

Когда внешний tool уже прошёл preflight — разрешения сужены, лишние write actions закрыты, verification и kill switch понятны, — вопрос уже не в самом подключении. Внешний инструмент ценен не потому, что подключён, а потому, что сокращает путь от внешнего сигнала до проверенного инженерного действия.

Issue, monitoring alert, данные из read-only базы, дизайн, документация и browser check кажутся шестью разными мирами. На деле каркас один и тот же: tool остаётся capability, workflow начинается там, где signal превращается в гипотезу, план и проверку. Иначе выходит знакомая офисная картина: вам переслали письмо, вы переслали его Claude, Claude переслал вам уверенное мнение, а код как был не проверен, так и остался.

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

Обратите внимание на середину схемы. Гипотеза и план между «получили сигнал» и «сделали diff» — это защита от момента, когда сервис подкинул гору контекста, а вы приняли его за готовый диагноз. Ни один источник не даёт права перепрыгнуть шаг «понять, что происходит в коде».

Чтобы не терять нить, удобно держать рядом маленькую workflow-заметку — возле TASK_SPEC.md или секцией внутри него:

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

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

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

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

Такой фрагмент выглядит скромно, но делает важную вещь: связывает внешний источник и ваш рабочий цикл. Не «MCP подключён», а «сигнал превращён в задачу, план и проверку». Вот с этого начинается взрослая работа.

2. Issue-to-PR: трекер помогает думать

Самый понятный сценарий — работа с issue tracker. Здесь preflight уже зафиксировал границы: tracker — read-only источник задачи, а claims из комментариев остаются данными, пока их не подтвердили код и tests. Ценность интеграции в том, что жалоба быстрее превращается в TASK_SPEC.md. В Workflow Kit у нас есть read-only интеграция вроде .claude/mcp/issue-tracker.json — доступ к карточке, комментариям, меткам, скриншотам, ссылкам на обсуждения. Дальше обычная инженерия: issue → TASK_SPEC.md, discovery по коду, маленький план, и только тогда 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: алерт — сирена, не диагноз

С monitoring работает тот же каркас, только сигнал здесь живёт в runtime. Preflight заранее фиксирует read-only posture: tool покажет alert и ограниченное окно логов. Поэтому alert нужен не как fix plan, а как старт triage.

Если перескочить через reproduce step, получится классический patch loop: Claude чинит симптом, вылезает новый, потом ещё один, и через двадцать минут у вас три изменения в unrelated-файлах и ни одного ответа на «что было корневой причиной».

Здесь очень помогает EVIDENCE_LOG.md — он превращает alert из эмоционального раздражителя в инженерный журнал наблюдений.

# EVIDENCE_LOG.md

Сигнал: рост ошибок 500 на /api/orders/{id}/refund
Окно логов: 10:12–10:18
Гипотеза: таймаут при повторной проверке статуса возврата
Проверка: воспроизвести локально запрос с тем же сценарием
Подтверждение: падает регрессионный тест RefundTimeoutTest

Обратите внимание: alert здесь не сказал «исправь сервис возвратов» — он только задал направление. И особенно важно удерживать границу автономности: tool не глушит alert, не откатывает релиз, не выполняет произвольные команды на проде и не объявляет баг закрытым потому, что график «вроде стал лучше». Это уже автопилот в зоне, где цена ошибки слишком велика.

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

4. Read-only БД: смотрим смело, лечим через код

С read-only БД preflight уже сделал за нас главный выбор: смотреть можно, лечить руками нельзя — и это сразу снимает самую опасную иллюзию. База показывает форму проблемы, но не объясняет её причину.

Допустим, в Commerce OS вы видите странные дубли заявок на возврат. Read-only запрос подтвердит, что дубли есть и в каком объёме — и спор «нам показалось» сменяется разговором по фактам.

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

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

Именно поэтому read-only DB analysis всегда должен замыкаться на код и проверку. Очень удобно связывать результат с API_MAP.md или найденным endpoint: увидели дубли — через карту API и discovery нашли путь /api/orders/{id}/refund — проверили сервис — добавили regression test.

Есть и ещё одна причина держаться за read-only как за default. База данных любит правду, но не любит импульсивные UPDATE и DELETE, особенно «просто чтобы быстро проверить гипотезу». Правило одинаково в учебном и рабочем baseline: изменения данных идут через код, миграции, тестовые сценарии и human approval. Не потому, что красивее на бумаге, а потому, что так дешевле платить за ошибки.

5. Design-to-code: макет — это контекст, а не приказ

До сих пор внешние tools разбирали то, что уже случилось в проекте: жалобу из issue, runtime-сигнал из 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 остаются очень умными предположениями. Умное предположение, конечно, лучше глупого — но до verified engineering action оно всё ещё не дотягивает.

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

Если смотреть на issue tracker, monitoring, базу, дизайн, документацию и browser по отдельности, кажется, будто это шесть разных миров. На деле каркас один и тот же — меняется только внешний сигнал и тип проверки на конце. Это хорошая новость: достаточно узнавать один и тот же workflow в разной одежде.

Ниже — компактная карта, которую полезно буквально держать под рукой, когда вы проектируете 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

Если упростить до одной фразы, то сегодняшняя лекция вот о чём: внешний tool не делает работу за вас, он делает ваш следующий шаг точнее. А вы вместе с Claude Code превращаете эту точность в нормальный инженерный цикл: понять, спланировать, изменить, проверить и зафиксировать в артефакте репозитория.

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

1

Задача

Claude code, 14 уровень, 1 лекция

Недоступна

Issue-to-PR: превратите жалобу из трекера в инженерную постановку

Issue-to-PR: превратите жалобу из трекера в инженерную постановку

Открыть

1

Задача

Claude code, 14 уровень, 1 лекция

Недоступна

Использование docs lookup как части engineering workflow

Использование docs lookup как части engineering workflow

Открыть