docs(research): зафиксирован эксперимент с координатором субагентов
- Зачем: - выводы агентного эксперимента нужны как durable-основа для будущего скилла, а не как одноразовый handoff. - Что: - добавлена research note с гипотезой, протоколом, наблюдениями и ограничениями эксперимента. - зафиксированы роли координатора, worker-а и reviewer-а, классификация находок и инварианты будущего скилла. - Проверка: - ручная перечитка docs/research/2026-06-11-subagent-coordinator-experiment.md.
This commit is contained in:
Dmitry Dementiev
@@ -0,0 +1,360 @@
|
|||||||
|
# Эксперимент с координатором субагентов
|
||||||
|
|
||||||
|
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 -> координатор коммитит
|
||||||
|
```
|
||||||
|
|
||||||
|
## Связанные артефакты
|
||||||
|
|
||||||
|
- `.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`
|
||||||
Reference in New Issue
Block a user