# Handoff: эксперимент с координатором субагентов

Дата: 2026-06-11
Ветка: `feature/data-generator`
Жанр: одноразовый handoff по [ADR-0003](../../docs/adr/0003-handoffs-in-scratch.md).

## Зачем нужен этот handoff

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

Этот документ фиксирует текущее понимание процесса перед запуском, чтобы не
потерять договорённости в новой сессии.

## Текущий рабочий контекст

Активная линия работы — переработка steady-stream генератора кликстрима.
Задачи лежат в `.scratch/feature-data-generator/issues/`.

Уже выполнены и ожидают человеческой приёмки:

- `01-minimal-connected-visit.md`
- `02-visit-page-path-and-monotonic-time.md`
- `02-5-generator-service-cleanup.md`
- `03-tick-stream-with-active-visits.md`
- `04-user-population-and-returns.md`

Оставшаяся последовательность:

1. `05-intensity-and-flow-calibration.md`
2. `06-state-v2-and-restart.md`
3. `07-service-integration-and-docs.md`

Задачи зависимы и, вероятно, меняют близкие файлы генератора, поэтому запускать
их надо строго последовательно, не параллельно.

В рабочем дереве на момент обсуждения была незакоммиченная правка только в
`.scratch/feature-data-generator/issues/06-state-v2-and-restart.md`: добавлен
комментарий, что задачу 06 нельзя начинать до завершения предыдущих срезов,
особенно задачи 05.

## Договорённая схема эксперимента

Верхнеуровневый агент не включает для себя `/goal`. Его роль — координатор и
gatekeeper, а не непосредственный исполнитель.

Для каждой задачи:

1. Координатор запускает нового worker-субагента на ровно один issue.
2. Задание субагенту формулируется в стиле `/goal`:
   - реализовать конкретный файл задачи;
   - работать по методике `/tdd`;
   - не реализовывать следующие задачи;
   - не коммитить;
   - не откатывать чужие изменения;
   - в конце отчитаться по изменённым файлам, тестам, проверкам и рискам.
3. После реализации тот же субагент делает саморевью в отдельной роли:
   - остановиться;
   - проверить результат против acceptance criteria, спеки и тестов;
   - искать ошибки, лишний объём, хрупкость и нарушение учебной читаемости;
   - сначала выдать находки с важностью, не исправляя их сразу.
4. Координатор решает, какие замечания достаточно важные.
5. Тот же субагент исправляет только одобренные важные замечания.
6. Координатор проверяет верхнеуровневые вещи:
   - границы задачи;
   - список изменённых файлов;
   - честность отметок acceptance criteria;
   - тесты;
   - `git status`;
   - отсутствие смешивания нескольких задач.
7. Коммит делает координатор, не субагент.
8. Координатор закрывает агента и переходит к следующему issue новым
   worker-субагентом.

Для сложных переходов, особенно после задачи 05 перед задачей 06, можно добавить
отдельного reviewer-субагента. Это не обязательный шаг на каждую задачу, а
контрольная мера, если есть риск, что саморевью исполнителя недостаточно.

## Роль координатора

Координатор не должен пытаться заново глубоко реализовывать или полностью
повторять работу субагента. Его польза — в управлении процессом:

- держать порядок задач;
- ограничивать область изменений;
- читать отчёты и принимать решения;
- запускать исправления только по существенным замечаниям;
- делать финальный обзор diff на уровне границ и рисков;
- выполнять проверки и коммитить.

Главный риск верхнеуровневого `/goal`: он может заставить координатора
оптимизировать работу под закрытие большой цели, а не под аккуратное управление
этапами. Поэтому для координатора `/goal` не использовать.

## Почему саморевью тем же субагентом допустимо

Пользователь отмечает, что на практике субагенты хорошо делают “ревью свежим
взглядом” внутри уже накопленного подробного контекста задачи. Это может быть
полезнее, чем полностью внешний поверхностный обзор координатора, которому не
хватит деталей реализации.

Ожидаемая модель:

- субагент глубоко понимает сделанную задачу и проверяет её на несостыковки;
- координатор не доверяет этому слепо, но оценивает адекватность выводов и
  границы изменений;
- для особо рискованных мест можно подключить отдельного проверяющего агента.

## Suggested skills

- `tdd` — должен использовать worker-субагент при реализации каждой задачи.
- `conventional-commits` — использовать координатору перед созданием каждого
  коммита.
- `claude-team-review` — опционально после задачи 05 или перед задачей 06, если
  нужен дополнительный независимый взгляд на модель.
- `handoff` — после эксперимента зафиксировать рефлексию: что получилось, что
  не получилось, какие правила стоит оставить.

## Возможная первая команда субагенту

```text
/goal Реализовать .scratch/feature-data-generator/issues/05-intensity-and-flow-calibration.md с использованием /tdd.

Работай только в границах этой задачи. Не реализовывай задачи 06-07.
Не коммить. Не откатывай чужие изменения.

Сначала прочитай сам issue и источники решений, указанные в нём. Работай
вертикальными TDD-срезами: один тест на наблюдаемое поведение -> минимальная
реализация -> зелёная проверка -> следующий тест.

В конце остановись и отчитайся:
- какие файлы изменены;
- какие тесты добавлены или изменены;
- какие проверки запускались и с каким результатом;
- какие acceptance criteria закрыты;
- какие риски или спорные места остались.
```

После этого координатор должен попросить того же субагента выполнить саморевью
результата, не исправляя замечания до отдельного решения координатора.