clickstream-ch-kafka-superset-demo/docs/research/2026-06-11-subagent-coordinator-experiment.md

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

Status: Research
Дата: 2026-06-11

## Зачем проводили эксперимент

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

- выдаёт одному worker-субагенту один локальный issue;
- требует от worker-а работать через `/goal` и `/tdd`;
- получает отчёт;
- просит того же worker-а сделать саморевью;
- классифицирует находки;
- запускает исправления только по важным пунктам;
- при необходимости подключает отдельного reviewer-субагента;
- сам выполняет финальную проверку, разделяет коммиты и принимает решение о
  переходе к следующей задаче.

Цель эксперимента была не только закрыть задачи генератора, но и понять, можно
ли из такого процесса сделать повторяемый агентный навык.

## Контекст

Эксперимент проводился в ветке `feature/data-generator` на последних трёх
срезах переработки steady-stream генератора:

1. `.scratch/feature-data-generator/issues/05-intensity-and-flow-calibration.md`
2. `.scratch/feature-data-generator/issues/06-state-v2-and-restart.md`
3. `.scratch/feature-data-generator/issues/07-service-integration-and-docs.md`

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

Итоговые рабочие коммиты:

- `8f1e997 feat(generator): откалиброван поток steady-stream генератора`
- `640050e feat(generator): добавлено состояние версии 2 для рестартов`
- `6c4e0f4 feat(generator): подключена новая модель к steady-stream сервису`

Отдельные docs-коммиты фиксировали ход и выводы эксперимента.

## Начальная гипотеза

Ожидалось, что полезное разделение ролей такое:

- **Координатор** держит порядок, границы задач, проверки, коммиты и решение,
  какие замечания действительно надо чинить.
- **Worker-субагент** глубоко погружается в один issue и реализует его через
  короткие TDD-срезы.
- **Саморевью worker-а** полезно, потому что у него уже есть подробный контекст
  реализации.
- **Отдельный reviewer-субагент** нужен не всегда, а на рискованных переходах
  или после больших исправлений.

Верхнеуровневому координатору решили не включать `/goal`: это могло бы сместить
поведение в сторону «закрыть большую цель любой ценой», тогда как задача
координатора — управлять этапами и останавливаться на контрольных точках.

## Словарь ролей

- **Координатор** — верхнеуровневый агент в текущей сессии. Он не пишет основную
  реализацию, а управляет порядком работ, проверяет границы, классифицирует
  замечания, запускает дополнительные проверки и делает коммиты.
- **Worker** — субагент-исполнитель. Он получает один issue, работает в общем
  рабочем дереве, меняет файлы, запускает тесты, но не коммитит.
- **Саморевью worker-а** — отдельная фаза после реализации. Worker временно
  меняет роль с исполнителя на проверяющего свою работу, но сначала только
  выдаёт находки, не исправляя их.
- **Reviewer** — отдельный субагент для независимой проверки. По умолчанию он
  работает только на чтение: анализирует diff, issue, спеки и тесты, но не
  редактирует файлы.
- **Находка** — гипотеза о проблеме, а не автоматическое требование правки.
  Решение принимает координатор.

Важная техническая деталь: все агенты работают с одним рабочим деревом. Поэтому
координатор обязан регулярно проверять `git status --short` и явно отделять
рабочие изменения задачи от процессных заметок, handoff-файлов и чужих правок.

## Протокол, который сложился в эксперименте

Рабочий цикл на задачу:

1. Проверить чистоту дерева и, если нужно, отделить процессные правки отдельным
   docs-коммитом.
2. Запустить нового worker-субагента на один issue.
3. В задании worker-у указать:
   - `/goal`-образную цель;
   - `/tdd` как методику;
   - границы задачи;
   - запрет на коммит;
   - запрет на откат чужих изменений;
   - требование финального отчёта: файлы, тесты, проверки, критерии, риски,
     `git status --short`.
4. После реализации запросить у того же worker-а саморевью без правок.
5. Классифицировать находки.
6. Вернуть worker-у только одобренные правки.
7. Запустить локальные проверки координатора.
8. На сложных местах запустить отдельного reviewer-а.
9. Снова классифицировать находки reviewer-а.
10. При больших исправлениях выполнить второй reviewer-круг.
11. Коммит делает координатор.
12. Старый worker закрывается; следующая задача стартует в новом worker-е.

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

## Классификация reviewer-находок

Reviewer не является источником истины. Его выводы работают как гипотезы,
которые координатор обязан проверить и классифицировать:

- `чинить до коммита` — реальный дефект, нарушение acceptance criteria или
  слабое доказательство ключевого поведения;
- `записать как риск` — важно помнить, но не блокирует текущий коммит;
- `ложная тревога` — reviewer неверно понял код, тест или границы задачи;
- `вне скоупа` — может быть полезно позже, но не относится к текущему issue.

Это оказалось критически важным. Без фильтрации reviewer легко превращается в
источник расползания задачи.

## Наблюдения по задаче 05

Задача 05 была самой дорогой по обратной связи: калибровка статистической
модели требует длинных симуляций и не даёт быстрый «один инвариант — один
результат».

Worker долго работал без промежуточного отчёта. Координатор сначала поставил
мягкий статус-чек, затем прервал агента ради статуса. Это не сломало работу, но
показало: для задач со статистическими тестами стоит заранее закладывать
контрольные точки.

Саморевью worker-а нашло реальные проблемы:

- `docker-compose.yml` оставлял старую интенсивность `GEN_LAMBDA_BASE_PER_MIN=200`;
- тест межсессионной паузы был слишком широким;
- в тестовой конфигурации оставались старые числа;
- README мог быть двусмысленным про `GEN_MIN/MAX_EVENTS_PER_TICK`.

Координаторская проверка добавила отдельную ценность: был найден конфликт между
новым `GEN_LAMBDA_BASE_PER_MIN=30` и старым нижним пределом
`GEN_MIN_EVENTS_PER_TICK=5`. При тике 5 секунд это давало минимум 60 событий в
минуту и ломало критерий интенсивности.

Вывод: саморевью хорошо ловит локальные несостыковки реализации, но координатор
нужен для проверки связей между дефолтами, обычным запуском, документацией и
acceptance criteria.

## Наблюдения по задаче 06

Задача 06 показала, зачем нужен отдельный reviewer-субагент между задачами.
Саморевью worker-а и отдельный reviewer независимо нашли две существенные
проблемы:

- битое state v2 с валидным состоянием ГПСЧ могло пройти `from_dict_safe`, а
  затем уронить сервис уже в `restore_state`;
- снимок активных визитов сохранялся полными batch-словарями и на верхних
  лимитах получался порядка мегабайт, хотя спека говорила о компактном
  состоянии.

Координатор проверил обе гипотезы локально:

- `restore_state` действительно падал на битой вложенной структуре;
- оценка JSON-снимка при 200 активных визитах и популяции 300 дала около 4.7 MB.

Обе находки были классифицированы как `чинить до коммита`.

После исправления компактного состояния понадобился второй reviewer-круг. Он
нашёл новый дефект уже в исправленной версии: формально похожий v2-state с
`population=[]` или строковым `pending_visit_births` проходил первичную
загрузку, но затем оставлял поток без пользователей или ронял следующий тик.

Координатор подтвердил это локальной проверкой и вернул worker-у как
обязательный пункт второго круга. Затем координатор дополнительно нашёл
парный случай: пользователь с `active_click_id`, но без соответствующего
`active_visit`.

Вывод: если исправление по reviewer-находке меняет дизайн, нужен повторный
reviewer-круг. Иначе можно закрыть старый дефект и внести новый рядом.

## Наблюдения по задаче 07

Задача 07 показала другую пользу reviewer-а: проверку силы доказательства, а не
только поиск падений.

Worker добавил сервисный тест с мок-публикацией. Он доказывал, что сервисный
тик публикует связанные сообщения во все четыре топика, но внешний reviewer
заметил: один опубликованный event ещё слабо доказывает уход от старой плоской
модели. Для acceptance criteria было важнее доказать невырожденную модель:
один визит должен дать несколько событий с одним `click_id`.

Координатор классифицировал это как `чинить до коммита`. Тест был усилен:
сервисный контур теперь делает несколько тиков и проверяет несколько событий
одного визита с общим `click_id`, разными `event_id` и согласованными
location/device/geo.

Reviewer также поймал документационные неточности:

- README слишком широко говорил, что переменные из таблицы проброшены через
  compose, хотя `KAFKA_BOOTSTRAP_SERVERS` и `GEN_DATA_DIR` должны оставаться
  безопасными внутренними значениями контейнера;
- `docs/OPERATIONS.md` отставал от новых параметров и метрик.

Вывод: финальная интеграционная задача требует reviewer-а не только по коду, но
и по доказательности тестов и честности документации.

## Что сработало

- Один worker на один issue хорошо удерживает контекст и границы.
- `/goal`-образное задание worker-у работает как хороший контракт даже тогда,
  когда координатор сам не находится в goal-режиме.
- Саморевью того же worker-а полезно, если явно запретить правки на первом
  шаге и попросить сначала выдать находки.
- Отдельный reviewer полезен на границах задач и после больших исправлений.
- Координаторская классификация находок обязательна.
- Коммиты должен делать координатор: это последняя точка контроля состава diff.
- Процессные наблюдения лучше фиксировать отдельно от рабочих коммитов.

## Что не стоит автоматизировать слепо

- Не стоит всегда запускать reviewer-а после каждой мелкой правки. Это дорого и
  может раздувать задачу.
- Не стоит принимать все reviewer-находки как правду.
- Не стоит давать координатору верхнеуровневый `/goal` на всю цепочку, если от
  него требуется управленческая осторожность, а не слепое достижение цели.
- Не стоит смешивать handoff-наблюдения с рабочими коммитами задач.
- Не стоит требовать реальный Kafka-стек для каждого шага, если acceptance
  criteria допускают мок-публикацию. Но надо явно фиксировать, что именно не
  проверялось.

## Ограничения эксперимента

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

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

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

## Инварианты будущего скилла

Если на базе эксперимента делать скилл, в него стоит перенести не конкретные
команды из этого репозитория, а следующие обязательные правила:

- **Один worker — один bounded issue.** Цепочка задач ведётся координатором, а
  не одним долгоживущим исполнителем.
- **Reviewer по умолчанию read-only.** Он выдаёт находки, но не правит файлы.
- **Исправления идут только после классификации.** Даже хорошие reviewer-находки
  сначала проходят фильтр координатора.
- **Коммит делает координатор.** Это защищает границы задачи и состав diff.
- **Большое исправление требует повторной проверки.** Если правка меняет дизайн
  или формат данных, результат самой правки надо ревьюить заново.
- **Рабочее дерево — общий ресурс.** Каждый цикл должен начинаться и
  заканчиваться явной проверкой статуса.
- **Документация и тесты являются частью доказательства.** Reviewer должен
  проверять не только падения, но и силу тестов, честность README/операционных
  документов и соответствие acceptance criteria.

## Эвристики для будущего скилла

Если делать скилл на базе эксперимента, в нём стоит закрепить такие правила:

1. **Начинать с чистого дерева.** Если есть процессные или чужие правки,
   отделить их до запуска worker-а.
2. **Давать worker-у один issue.** Не просить закрывать цепочку задач в одном
   агенте.
3. **Формулировать task prompt как контракт.** В нём должны быть цель, границы,
   методика, запрет на коммит, запрет на откат чужого и формат отчёта.
4. **Требовать саморевью без правок.** Исправления только после решения
   координатора.
5. **Классифицировать находки.** Минимальный набор: чинить до коммита, риск,
   ложная тревога, вне скоупа.
6. **Запускать отдельного reviewer-а на рискованных точках.** Особенно:
   state/serialization, сервисная интеграция, документация, изменения формата
   данных, статистические модели.
7. **Повторять reviewer-круг после больших исправлений.** Если исправление
   изменило дизайн, оно само нуждается в ревью.
8. **Координатор делает собственный sanity-check.** Не полный реимплемент, а
   проверка связей: дефолты, compose, документация, acceptance criteria,
   `git status`, тесты.
9. **Коммитить только координатору.** Worker не должен фиксировать изменения.
10. **Закрывать агентов.** Завершённые subagents надо закрывать, чтобы не
    держать лишний контекст и лимиты.

## Возможный скелет скилла

1. Прочитать issue и зависимости.
2. Проверить рабочее дерево.
3. Запустить worker.
4. Дождаться отчёта или запросить статус, если работа слишком долго молчит.
5. Запустить self-review того же worker-а.
6. Классифицировать находки.
7. Вернуть worker-у только выбранные правки.
8. Запустить проверки координатора.
9. Если задача рискованная, запустить reviewer-а.
10. Классифицировать reviewer-находки.
11. При больших исправлениях повторить reviewer-круг.
12. Сделать коммит.
13. Обновить исследовательскую заметку или итоговый лог, если эксперимент ещё
    идёт.

Этот скелет должен быть параметризуемым. Например, для простой задачи можно
ограничиться worker + саморевью + проверки координатора. Для state/serialization,
интеграции сервиса, документации или статистической модели нужен reviewer.

## Оставшиеся вопросы

- Как заранее понять, когда нужен отдельный reviewer, а когда достаточно
  саморевью?
- Стоит ли задавать worker-у обязательные промежуточные отчёты для статистики и
  долгих тестов?
- Нужно ли явно ограничивать бюджет worker-а или число reviewer-кругов?
- Как лучше формализовать критерий «большое исправление требует второго
  reviewer-а»?
- Должен ли будущий скилл сам создавать research log, или это должен быть
  отдельный режим?

## Предварительная рекомендация

Эксперимент стоит считать успешным. Процесс дал не только рабочий результат, но
и поймал дефекты, которые легко могли пройти обычный одиночный поток:

- конфликт дефолтов интенсивности;
- падение на битом state v2;
- слишком большой state v2;
- неполная валидация компактного state;
- слабый интеграционный тест, не доказывавший уход от старой плоской модели.

Для будущего скилла ядро должно быть не «запусти много агентов», а
**координационный цикл с классификацией находок и контролем границ**.

Главная формула процесса:

```text
worker реализует -> worker сам себя ревьюит -> координатор фильтрует ->
worker чинит выбранное -> reviewer проверяет риск -> координатор фильтрует ->
при большом исправлении повторить reviewer -> координатор коммитит
```

## Внешнее ревью другой моделью (отложенный заход, 2026-06-14)

Отложенное ревью результата петли (его наметил handoff
`2026-06-11-generator-time-adr-and-pending-review.md`) выполнено. Ревью провела
**модель другой родословной** — та, что вела дизайн, ADR и спеки, а не линия
Кодекс, писавшая код. Это и есть проверка центральной гипотезы эксперимента:
какой класс дефектов автономная петля систематически не видит без внешнего
взгляда.

Основа проверки: перечитаны ADR-0004/0005 и обе спеки; код прочитан помодульно;
марковская модель путей прогнана симуляцией на 300 тыс. визитов; прогнан весь
набор тестов (113 passed); происхождение обёртки `try→fresh` прослежено по git.

### Прогноз по находке A не оправдался — петля её поймала

Handoff предсказывал, что петля пропустит ссылочную целостность при
`restore_state` («слепые зоны одной линии Кодекс скоррелированы»). На деле:

- висячая ссылка визит→пользователь ловится валидатором формы (`state.py:88`);
- висячая ссылка пользователь→словарь (неизвестный `seed_click_id`) валидатору
  формы недоступна, но петля **в коммите задачи 06** (`640050e`) добавила обёртку
  `try→fresh` вокруг `restore_state` в сервисе **и** написала регрессионный тест
  `test_invalid_restored_v2_state_starts_fresh` (профиль с `missing-click-id`).
  Это совпадает с разделом «Наблюдения по задаче 06»: и саморевью worker-а, и
  отдельный reviewer независимо нашли «битый v2 проходит `from_dict_safe`, но
  роняет `restore_state`».

Вывод: многоролевой цикл (worker + саморевью + отдельный reviewer) **поймал**
ровно тот класс дефекта, который ставился как главный индикатор эксперимента.
Прогноз о скоррелированной слепоте по этому пункту ошибочен.

### Что внешний взгляд всё же добавил

Дефекты, дожившие до внешнего ревью, оказались **не точечными, а сквозными** —
их не пинит ни один тест, и каждый по отдельности «проходит»:

- **Расхождение живого и восстановленного путей.** Живой визит берёт
  браузер/локацию из *случайной* сид-сессии и `event_id` = `_new_uuid`
  (`generation.py`), восстановленный — из сид-сессии *профиля* и `event_id` =
  `uuid5` (`runtime.py`). У визита, пережившего рестарт, атрибуты «доезжающих»
  событий меняются на середине. Инвариант «один визит — однородный контекст»
  нарушается на стыке двух путей, который ни один тест не сводит вместе.
- **Форма распределения длины визита.** Среднее (10.7) и конверсия в
  `/confirmation` (27%) на цели, воронка монотонна — это тесты проверяют и
  подтверждают. Но *форма* дальше от сида: спайк 16% на длине 2 (форс минимума в
  2 события убирает визиты-отказы из одного события, которые сид допускает),
  ~6.6% визитов срезаются о потолок 30, медиана 8 сидит на нижней границе
  тестовой полосы 8–12. Тесты пинят средние и пороги, но не форму распределения.

### Уточнённая гипотеза

Главный индикатор A был *локальным* дефектом — падение в одной точке на битом
входе; того же семейства, что и прочие находки задачи 06 (раздутый снимок,
неполная валидация). Такие вещи дисциплинированный многоролевой цикл ловит
хорошо. А выжили до внешнего ревью свойства **межмодульные** (инвариант поверх
двух путей кода) и **распределительные** (форма, а не среднее) — ровно там, где
слабы и ревью внутри одной линии, и покритериальные тесты.

Отсюда уточнение к открытому вопросу «когда нужен отдельный reviewer»: ценнее
всего reviewer **другой родословной**, и именно там, где (а) свойство тянется
через несколько модулей/путей, либо (б) корректность распределительная (форма),
а не одно утверждение. Для точечных дефектов на входе хватает саморевью и
отдельного reviewer той же линии.

### Побочно подтвердилось

Разделение двух линий сработало: ADR-0005 (модельные часы ×K) остался решением
на бумаге, код петли честно держался реал-тайм-модели, нечаянного переплетения
линий нет. Процессное решение «не мешать брейншторм времени с петлёй 06/07»
выдержало.

## Связанные артефакты

- `.scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md` —
  исходный одноразовый handoff и рабочий журнал наблюдений.
- `.scratch/feature-data-generator/issues/05-intensity-and-flow-calibration.md`
- `.scratch/feature-data-generator/issues/06-state-v2-and-restart.md`
- `.scratch/feature-data-generator/issues/07-service-integration-and-docs.md`
- `docs/adr/0003-handoffs-in-scratch.md`
- `docs/adr/0002-specs-as-durable-design-docs.md`