Subagents: тихое расследование

1. Большое расследование засоряет основную сессию

Компактный пакет улик — код, команду, вывод, trace, скриншот — вы уже умеете приносить. Этого хватает на локальный вопрос. Но как только надо пройтись по нескольким модулям и вернуться с коротким проверяемым выводом, всплывает другая проблема: расследование захламляет основную сессию.

Расследование почти всегда шире, чем правка одного метода. Claude читает много файлов, держит гипотезы, сравнивает тесты, копит куски логов. Это нормально. Плохо то, что дальше: основная сессия тащит весь этот багаж с собой, даже когда вам нужен только итог.

Пример. В Commerce OS вы разбираете refund flow. Claude читает OrderController, RefundService, OrderService, клиент платёжного провайдера, пару конфигов, тесты и старый лог с ошибкой. На этапе поиска всё полезно. Но потом вы хотите просто дописать строку в API_MAP.md — а сессия всё ещё «помнит» весь промежуточный шум, включая отброшенные гипотезы.

Решение — subagent. Тяжёлое чтение уходит в отдельное окно контекста. Назад возвращается не мусор, а выжимка: что нашли, где, что не проверили, что дальше.

Основная сессия
  └─ ставит задачу investigation
       └─ subagent читает много файлов и логов
            └─ возвращает только summary + evidence
                 └─ основная сессия принимает решение

2. Subagent — это отдельное окно контекста

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

Модель простая. Основная сессия формулирует вопрос. Subagent проводит исследование. Основная сессия получает короткий результат и на его основе обновляет артефакты и решает дальше. Subagent — не замена сессии, а её «комната для шума».

Небольшая таблица помогает это зафиксировать:

Очень важно и то, чем subagent сегодня не является. Мы не конфигурируем кастомных агентов, не настраиваем разрешения, не собираем multi-agent pipeline и не строим «армию исследователей». Пока это просто паттерн — вынести тяжёлое расследование из основной сессии.

3. Subagent нужен, когда читать надо много, а вернуть мало

Новый приём тянет применять везде. Удержитесь. Subagents полезны не тем, что звучат красиво, а тем, что уменьшают context pollution.

Один файл, одна строчка в тесте, известный заранее обработчик — subagent тут лишний посредник. А вот просканировать все routes, найти все точки вызова Stripe, собрать тесты вокруг refund flow, обойти большой модуль и вернуть только summary — его работа.

Посмотрите на это так:

Вопрос к себе один: «Мне нужно, чтобы Claude много прочитал, но мало вернул?» Если да — subagent почти наверняка полезен. Если нужен длинный интерактивный разговор по ходу чтения — оставайтесь в основной сессии. Subagent любит чёткие рамки и короткий проверяемый результат.

4. Ставьте задачу как мини-версию task spec

Бесполезное investigation почти всегда от размытой постановки, а не от плохого Claude. С subagent это видно особенно хорошо. Скажете «посмотри, что тут с платежами» — он честно посмотрит, подумает и вернёт туман. Поэтому subagent task оформляется как маленький task spec.

Рабочий шаблон очень простой:

Цель: что именно нужно выяснить.
Область поиска: где можно смотреть, а где не нужно.
Верни: какой формат ответа ожидается.
Не делай: что запрещено или не требуется.

Вот хороший пример для Commerce OS:

Исследуй, где в Commerce OS проходят refund-операции.
Смотри только controllers, services, payment client, configs и tests.
Верни короткое summary, file:line ссылки, связанные тесты и open questions.
Не меняй файлы и не присылай длинные куски кода.

Заметьте, здесь нет магии. Вы не пишете «будь лучшим аналитиком на свете». Вы задаёте цель, границы и формат ответа. Это всё та же инженерная дисциплина из предыдущих модулей, только на более мелком уровне.

Ещё один пример — уже под задачу из текущего модуля, где вы поддерживаете API_MAP.md:

Найди все точки, где проект общается со Stripe.
Проверь build file, client code, config keys, env vars и integration tests.
Верни только подтверждённые места с file:line ссылками.
Если что-то похоже на гипотезу, пометь это явно.

Такой запрос особенно хорош тем, что сразу заставляет subagent разделять факт и предположение. А это сильно экономит вам время на проверке.

5. Хороший ответ — это output contract

Subagent полезен, только если назад приходит рабочий результат, а не «литературное расследование на шесть экранов». Для этого нужен output contract. Не пугайтесь громкого слова: это просто заранее оговорённый формат ответа.

Хороший ответ почти всегда содержит пять вещей:

summary — суть в двух строках;

evidence — file:line ссылки для проверки;

assumptions — где subagent догадался, а не увидел;

open questions — что не смог подтвердить;

next steps — что логично делать основной сессии дальше.

Summary: refund flow входит через `OrderController`, дальше идёт в
`RefundService`, а внешний вызов уходит через `StripeClient`.

Доказательства:
- `src/orders/OrderController.java:41-67`
- `src/refunds/RefundService.java:18-73`
- `src/payments/StripeClient.java:88-123`
- `src/test/.../RefundServiceTest.java:22-64`

Предположения:
- webhook-обработка, вероятно, есть, но не подтверждена.

Открытые вопросы:
- не найден тест на проверку подписи webhook.

Следующие шаги:
- проверить webhook handler и обновить `API_MAP.md`.

Ответ короткий и проверяемый. Плохой — наоборот: двадцать file paths без контекста, огромные цитаты кода, неявные догадки, «всё вроде находится тут». Правило простое: subagent должен сжимать исследование, а не дублировать его. Иначе вы поменяли место хранения шума, а не убрали его.

6. Subagent помогает заполнить API_MAP.md

Свяжем это с Commerce OS. В API_MAP.md уже зафиксированы первые маршруты и интеграции. Теперь надо дополнить раздел внешних интеграций — описать платёжного провайдера и точки refund flow. Целиком в основной сессии это утопит её в деталях, поэтому работаете через subagent.

Основная сессия ставит задачу: «Найди все подтверждённые точки интеграции со Stripe: dependency, client, config keys, места вызова checkout/refund, связанные tests. Верни короткую выжимку с evidence и open questions». Subagent уходит читать код, сессия держит только цель — обновить артефакт.

Возвращается, допустим, такое:

Summary: Stripe подключён как внешний payment provider; checkout и refund
идут через один client class.

Доказательства:
- `build.gradle:34`
- `src/payments/StripeClient.java:14-145`
- `src/orders/OrderService.java:132-154`
- `src/refunds/RefundService.java:87-104`
- `src/main/resources/application.yml:54-61`

Открытые вопросы:
- webhook signature validation не подтверждена тестом.

Из такой выжимки удобно обновлять API_MAP.md, troubleshooting note или черновик документации, не перетаскивая назад весь сырой поиск. Но в API_MAP.md это не копируется вслепую: основная сессия проверяет два-три опорных места, чтобы убедиться, что выводы не фантазия, и только потом обновляет артефакт.

Фрагмент API_MAP.md может стать таким:

## Внешние интеграции

- Stripe payment provider
  - dependency: `build.gradle:34`
  - client: `src/payments/StripeClient.java:14-145`
  - checkout call: `src/orders/OrderService.java:132-154`
  - refund call: `src/refunds/RefundService.java:87-104`
  - config: `src/main/resources/application.yml:54-61`
  - open question: webhook signature validation not verified

Тут сходятся предыдущие лекции. Из лекции 1 — формат карты. Из лекции 2 — привычка опираться на evidence. Из сегодняшней — способ добыть evidence, не утопив основную сессию. Новые приёмы не живут отдельно, а достраивают знакомый workflow.

7. Возвращаем выводы в основную сессию

Финиш — место, где легко всё испортить. Subagent отработал хорошо, а основная сессия тащит назад весь сырой материал или начинает спорить с ним на эмоциях. Спасает простой порядок.

Сначала сессия принимает только summary и evidence. Потом выборочно проверяет два-три опорных места — те ссылки, на которых держится вывод. Потом обновляет артефакт: API_MAP.md, investigation note или docs draft. И только затем, если нужно, ставит следующий вопрос.

Основная сессия
   ↓ формулирует mini task spec
Subagent
   ↓ приносит summary + citations
Вы
   ↓ проверяете опорные места
Артефакт
   ↓ обновляется через diff

Subagent не снимает с вас ответственность. Он не решает за разработчика — он сокращает стоимость исследования. Владелец результата по-прежнему вы: какие выводы войдут в API_MAP.md, какие останутся open questions, а какие уйдут в корзину как неподтверждённые, решаете вы.

В этом весь подход. Subagent не делает сессию умнее. Он не даёт ей захламиться — а чистая сессия работает лучше.