Тикет «не работает оплата» раньше означал для меня маленький квест: открыть 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 и субагенты уже сейчас работают как взрослый инструмент.
Не идеальный. Не универсальный. Но вполне настоящий.