Dmitry Dementiev
d7c5a56675
- Зачем: - перед запуском задачи 05 нужно отделить координационные договорённости от будущих изменений генератора. - Что: - добавлен handoff с правилами эксперимента координатора и субагентов. - уточнён порядок возврата к задаче состояния версии 2 после калибровки потока. - Проверка: - git diff -- .scratch/feature-data-generator/issues/06-state-v2-and-restart.md .scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md.
143 lines
9.2 KiB
Markdown
143 lines
9.2 KiB
Markdown
# 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 закрыты;
|
||
- какие риски или спорные места остались.
|
||
```
|
||
|
||
После этого координатор должен попросить того же субагента выполнить саморевью
|
||
результата, не исправляя замечания до отдельного решения координатора.
|