diff --git a/.scratch/feature-data-generator/issues/06-state-v2-and-restart.md b/.scratch/feature-data-generator/issues/06-state-v2-and-restart.md index c649e28..4b412c6 100644 --- a/.scratch/feature-data-generator/issues/06-state-v2-and-restart.md +++ b/.scratch/feature-data-generator/issues/06-state-v2-and-restart.md @@ -34,3 +34,9 @@ Status: ready-for-agent ## Comments +2026-06-11: задачу нельзя считать самостоятельной к реализации, пока не закрыты +предыдущие срезы генератора: 02 (путь визита и монотонное время), 03 (тики и +активные визиты), 04 (популяция и возвраты), 05 (интенсивность и калибровка). +Преждевременный кодовый задел state v2 был откатан, чтобы он не попал в коммиты +следующих задач. Возвращаться к этой задаче нужно после реализации зависимостей +и заново проверять все acceptance criteria на актуальной модели генератора. diff --git a/.scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md b/.scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md new file mode 100644 index 0000000..55c975d --- /dev/null +++ b/.scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md @@ -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 закрыты; +- какие риски или спорные места остались. +``` + +После этого координатор должен попросить того же субагента выполнить саморевью +результата, не исправляя замечания до отдельного решения координатора.