docs(generator): зафиксирован процесс эксперимента с субагентами
- Зачем: - перед запуском задачи 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.
This commit is contained in:
Dmitry Dementiev
@@ -0,0 +1,142 @@
|
||||
# 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 закрыты;
|
||||
- какие риски или спорные места остались.
|
||||
```
|
||||
|
||||
После этого координатор должен попросить того же субагента выполнить саморевью
|
||||
результата, не исправляя замечания до отдельного решения координатора.
|
||||
Reference in New Issue
Block a user