Как я собрал AI-оркестратор расследования продовых инцидентов на SKILL.md, субагентах и API

Тикет «не работает оплата» раньше означал для меня маленький квест: открыть Sentry, Kibana, Grafana, базу, Jira — и через десять минут поймать себя на мысли, что уже не помнишь, зачем открыл четвёртую вкладку.

Я хотел автоматизировать это обычным кодом — написать сервис, завернуть API, сделать кнопку. В итоге написал markdown. И это до сих пор меня немного раздражает.

Потому что в задачах вроде «сходи в три системы, собери улики, принеси черновой вывод» SKILL.md дал лучший ROI, чем PHP-скрипт. Не потому что markdown магический — просто цена ошибки здесь умеренная, а цена ручной рутины раздражающе высокая.

Честно: это не про «AI заменил on-call». Это про полуавтоматический черновик расследования. Иногда очень полезный. Иногда тупящий. Иногда уверенный в ерунде. Но достаточно полезный, чтобы я продолжил этим пользоваться.

Что получилось на практике

Появился AI-оркестратор расследования: по короткому описанию проблемы он решает, куда идти — в логи, Sentry, базу, Jira или APM — и собирает первый отчёт. В проекте он называется research-billing, но в статье я буду называть его расследовательским оркестратором.

Раньше:

  • 15–20 минут
  • 5 вкладок
  • много копипаста между системами

С оркестратором:

  • 3–5 минут до первого чернового отчёта
  • полезный черновик — в 13–14 из 20 случаев
  • в 6–7 случаях всё равно дожимаю руками

Чаще проваливается, когда проблема в логике кода, а не в данных. Это заметно дешевле потерянного времени, но не zero-cost. И да, это не бенчмарк — я не замерял всё аккуратно. Но даже грубых цифр хватило, чтобы понять: схема окупает себя в реальной рутине.

Три вещи, которые я сначала свалил в одну кучу

Я смешал три сущности:

  • SKILL.md — workflow-инструкция: когда вызываться, что делать, какой формат ответа нужен
  • subagents — параллельные исполнители с собственным context window
  • MCP — способ дать агенту инструменты и внешние интеграции

Расклад такой: MCP не заменяет SKILL.md. MCP даёт агенту руки. Skill задаёт порядок, ограничения и критерий полезного результата.

Важно: SKILL.md уже не выглядит локальным хаком. Anthropic оформил этот подход как open standard Agent Skills, а OpenAI указывает, что skills в ChatGPT, Codex и API следуют тому же формату.

Что я собрал

В Laravel-проекте у меня папка .claude/skills/ с набором skills:

  • research-billing — оркестратор расследования
  • db-billing — production БД, только чтение и готовые SQL-шаблоны
  • kibana-billing — ELK и поисковые шаблоны по x-request-id, invoice_id, exception class
  • sentry-billing — issues, events и стектрейсы
  • jira-billing — тикеты и комментарии
  • newrelic-billing и grafana-billing — метрики и аномалии
  • billing-parallel-review — тот же паттерн, но для code review

research-billing — диспетчер. Он получает текст вроде «заказ 87291 не оплачивается, 404», вытаскивает идентификаторы, выбирает маршрут, определяет временной диапазон и запускает первую волну расследования.

Он не «умеет всё сам». Он — диспетчер: разбирает вход, не забывает источники, ждёт ответов и склеивает вывод.

Архитектура в файлах

В репо нет папки .claude/agents/. Субагенты — inline prompts для Agent tool. Структура:

Почему это удобно:

  • маршрутизация и правила запуска — в одном месте
  • знания по источникам не размазаны по одному гигантскому prompt’у
  • project-specific эвристики — рядом с интеграцией, а не в голове
  • тот же паттерн можно применить к другим задачам

Это легче поддерживать, чем монолитный CLAUDE.md.

Кусок оркестратора research-billing

Самый полезный элемент — диспетчер. Он умнее, чем «если 404 — сходи в три места». Он задаёт:

  • эвристику выбора
  • порядок волн
  • стратегию временного окна
  • формат выхода

Контракт между агентами

Самое плохое, что может сделать субагент — принести «умный абзац» вместо структурированного результата. Поэтому у меня не один JSON-контракт, а серия жёстких markdown-шаблонов по ролям.

Это банально, но работает. Синтезатору не нужно угадывать, где факт, где вывод, а где фантазия. Он видит секции и собирает отчёт поверх них.

Я заставил субагентов:

  • отделять сырые улики от интерпретации
  • приносить факты в форме, которую можно склеить без повторного анализа

Кейс, после которого я понял, что штука реально полезная

Тикет: «Клиент жалуется, страница оплаты отдаёт 404».

Запускаю оркестратор с описанием.

Skill вытаскивает 87291 как entity_id, 404 — как симптом, и запускает три линии расследования:

  • DB Investigator находит запись: статус expired, ссылка создана 5 дней назад, TTL — 72 часа
  • Log Investigator в Elasticsearch находит пачку 404 по /pay/expired-slug. Slug в запросах не совпадает с текущим — клиент ходит по старой ссылке
  • Error Investigator в Sentry: ошибок уровня error нет, но есть warning про истёкшую ссылку

Главный агент собирает вывод: баг не в коде, а в том, что клиент открыл старый URL. Это не «сломалась система», а «мы отдаём слишком жестокий 404, где нужна человеческая страница с объяснением».

Раньше — 15–20 минут и пять переходов. Сейчас — несколько минут до первого внятного черновика. Не до истины. А до черновика. И в этом вся магия.

Хороший выход — структурированный отчёт, который можно читать, обсуждать, пересылать или докручивать руками. Свободный поток слов — нет.

Ещё одна находка: агент по умолчанию хочет обвинить внешний сервис — «банк не ответил», «сломались credentials». Реальная эвристика жёстче:

  • сначала проверь целостность данных инвойса
  • потом уже обвиняй внешнюю интеграцию

В skill’е это стало правилом: если payment_type_option_id = NULL, проблема не в банке, а в том, что код падает на paymentTypeOption->type, уходит в catch и маскируется под 404.

То же с кодовым расследованием: если 404, полезно смотреть не только catch, но и тело try. Мелочь, но именно такие project-specific правила превращают skill из демки в рабочий инструмент.

Какие формулировки реально сделали это стабильным

Агент любит понимать «параллельно» как «ну да, как-нибудь потом». Вот где неточные формулировки ломали схему:

Слабая формулировка Что реально сработало
«Запусти всё параллельно» CRITICAL: launch all subagents in one message, not sequentially
«Если данных хватит, сделай вывод» STOP CONDITION: wait for all spawned agents before synthesis
«Посмотри логи по ошибке» If matches > 50, return first 10 and count the rest
«Поищи за последнее время» explicit date -> ±2h; default -> 30d; if invoice found -> center logs around created_at ±1h
«Копни глубже» run second wave only on specific triggers; maximum 2 waves
«Проверь банк / credentials» first inspect invoice data integrity and NULL FK before blaming external integrations
«Покажи релевантные issues» Never filter out critical issues
«Сделай краткий отчёт» Format: problem -> evidence -> conclusion -> recommendation

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

По сути — это не prompt engineering, а мини-SOP для вероятностной системы.

Вот кусок реального skill’а

Чтобы не выглядело как эзотерика — упрощённый фрагмент одного из скиллов.

Skill — это не код интеграции, а текстовый playbook поверх API. Он не даёт агенту забыть шаги и каждый раз «изобретать» критерий полезного ответа.

Почему не PHP-скрипт, не MCP и не просто большой system prompt

Три частых вопроса:

Почему не обычный код?
Потому что ценность не в вызове API, а в неоднозначной glue-логике: вытащить ID из текста, выбрать маршрут, распараллелить источники, собрать черновой вывод.

Почему не MCP?
MCP и skills решают разные задачи. MCP — «какие инструменты доступны». Skill — «как действовать в этом сценарии».

Почему не CLAUDE.md или system prompt?
Глобальные инструкции грузятся всегда, даже когда не нужны. Skill поднимается по требованию. Чем больше always-on контекста, тем выше риск, что агент начнёт следовать не тем правилам.

Всё это выглядит так:

  • CLAUDE.md — общие правила репозитория
  • SKILL.md — конкретный workflow
  • MCP — подключение инструментов
  • subagents — параллельное выполнение

Когда я разложил это по полочкам, система перестала казаться магией — стала нормальной инженерной конструкцией. Вероятностной, да. Но инженерной.

Где AI-оркестрация начинает буксовать

Теперь плохая новость. Всё это хрупко.

Skill — это промпт. Промпт — вероятностная штука. Один сценарий может в понедельник отработать идеально, а в среду — решить, что в Sentry идти не обязательно.

Дебажить — сомнительное удовольствие. Нет stacktrace. Нет «почему я так решил». Только вывод и ощущение, что на шаге 4 агент пошёл не туда.

Три типовых фейла:

Фейл 1: проблема в кодовой логике, а не в данных.
Логи чистые, база в порядке, Sentry молчит, а корень — в условии на 20 строк. Оркестратор почти всегда недоразбирает: перед ним операционные источники, а не reasoning по коду.

Фейл 2: источники противоречат друг другу.
Например, логи обновились, а Sentry — нет. Или в Jira описан старый симптом, а пользователь воспроизводит новый. Если не заставить синтезатор отмечать противоречия, он выберет одну версию и подаст её как истину.

Фейл 3: вход грязный.
В тикете два ID, старый slug, кусок текста из прошлого кейса и «всё упало». Ошибка начинается на маршрутизации: агент бежит не туда и тратит контекст впустую.

Есть ещё эффект роста.

Сначала SKILL.md маленький и прекрасный. Потом туда добавляют edge case, лимит на логи, special case для Jira, запрет фильтровать critical, строгий шаблон синтеза. И внезапно — markdown-монстр, который сам требует сопровождения.

Я сформулировал трезвый критерий: подход теряет смысл, если:

  • SKILL.md лезет за 300–500 строк
  • в нём хаков больше, чем полезных инструкций
  • ошибка начинает стоить дорого
  • сценарий нужно выполнять детерминированно, а не «обычно неплохо»

Тогда проблема не в «мало промпта». Проблема в том, что сценарий перестал быть хорошим кандидатом для skill-based orchestration.

И это полезнее признать вовремя, чем усиливать markdown словами CRITICAL, MUST, NEVER, ALWAYS и делать вид, что вероятностная система стала программой.

В 2026 полезная автоматизация — это не «сразу писать сервис», а «собрать для агента workflow, дать инструменты и заставить приносить структурированный результат».

Это удобно: за вечер можно собрать штуку, которая реально экономит время.

И тревожно: сложность никуда не исчезает. Она переезжает в markdown, frontmatter, оговорки, stop conditions и контракты между агентами.

Для меня SKILL.md + subagents + API — это не «недокод» и не заглушка. Это отдельный тип инженерной автоматизации. Он подходит, когда:

  • нужно собрать факты из нескольких источников
  • цена ошибки умеренная
  • первый полезный черновик ценнее идеальной детерминированности

И плохо работает, когда:

  • нужен гарантированный сценарий
  • ошибка дорогая
  • workflow уже не даёт выигрыша от вероятностной оркестрации

У меня в проекте два режима:

  • несколько узких skills как «умные шпаргалки» по API
  • два оркестратора, которые временами умничают, временами тупят, но покупают несколько спокойных минут на каждом расследовании

И вот главный вывод: в AI-автоматизации ценность появляется не там, где «убрали человека», а где радикально сократили путь от симптома к первому внятному объяснению.

Если нужно быстро собрать сигналы, сопоставить факты и выдать черновой вывод — skills и субагенты уже сейчас работают как взрослый инструмент.

Не идеальный. Не универсальный. Но вполне настоящий.

Читать оригинал