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 — що логічно робити основній сесії далі.

Підсумок: 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 іде читати код, сесія тримає лише мету — оновити артефакт.

Повертається, припустімо, таке:

Підсумок: 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 не робить сесію розумнішою. Він не дає їй захаращуватися — а чиста сесія працює краще.