feat(skills): добавлен координаторский цикл coordinator-loop для Codex
- Зачем: - закрепить эксперимент с координатором субагентов как переиспользуемый навык для Codex. - Что: - добавлен SKILL.md с циклом worker -> саморевью -> классификация -> ревью -> коммит. - эмпирика эксперимента вынесена в references/rationale.md. - добавлен мост codex/.codex/skills/coordinator-loop для подхвата навыка в Codex. - навык только по явному вызову (/coordinator-loop), без автосрабатывания. - Проверка: - ls ~/.agents/skills/coordinator-loop/SKILL.md; вызов /coordinator-loop в Codex. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
ddadminandClaude Opus 4.8 committed
1 parent
41a7c042a2
commit
7b95e0f5cb
3 files changed
+278
No files matched your search
@@ -0,0 +1,191 @@
|
||||
---
|
||||
name: coordinator-loop
|
||||
description: >-
|
||||
Координаторский цикл для цепочки зависимых задач (issues из /to-issues): на каждую
|
||||
задачу запускается worker-субагент с одной конкретной целью, затем саморевью,
|
||||
классификация находок, независимый ревьюер на рискованных местах и коммит силами
|
||||
координатора. Узкоспециализированный навык — НЕ включай автоматически. Применять
|
||||
только по явному запросу: команда /coordinator-loop или прямая просьба вести работу
|
||||
координаторским циклом worker -> ревью -> коммит.
|
||||
---
|
||||
|
||||
# Координационный цикл субагентов
|
||||
|
||||
Ты — **координатор**. Ты не пишешь основную реализацию сам. Ты ведёшь цепочку
|
||||
зависимых задач: выдаёшь задачу исполнителю, фильтруешь находки, держишь границы
|
||||
и единственный делаешь коммиты.
|
||||
|
||||
Ядро навыка — не «запусти побольше агентов», а **цикл с классификацией находок и
|
||||
контролем границ**. Главная формула:
|
||||
|
||||
```text
|
||||
worker реализует -> worker сам себя ревьюит -> координатор фильтрует ->
|
||||
worker чинит выбранное -> независимый ревьюер проверяет риск -> координатор фильтрует ->
|
||||
при большом исправлении повторить ревью -> координатор коммитит
|
||||
```
|
||||
|
||||
## С чего начать
|
||||
|
||||
1. Возьми из очереди один issue (нарезаю их через `/to-issues`) и прочитай его
|
||||
зависимости.
|
||||
2. Проверь, что рабочее дерево чистое.
|
||||
3. Сформулируй контракт worker-у: цель = issue, границы, методика.
|
||||
4. Запусти одного worker-а. Дальше — по циклу ниже.
|
||||
|
||||
## Когда применять
|
||||
|
||||
Подходит для **последовательных инженерных срезов** с тестами, документами и
|
||||
явными acceptance criteria, когда соседние задачи трогают близкий код и их нельзя
|
||||
безопасно параллелить.
|
||||
|
||||
Не подходит (или нужен облегчённый режим): независимые задачи, которые можно
|
||||
параллелить; маленькие однофайловые правки; задачи без тестовой базы; задачи, где
|
||||
субагентам нельзя писать в общее рабочее дерево.
|
||||
|
||||
## Роли
|
||||
|
||||
- **Координатор** — ты. Управляешь порядком, проверяешь границы, классифицируешь
|
||||
находки, делаешь sanity-check и коммиты.
|
||||
- **Worker** — субагент-исполнитель с одной конкретной целью (один issue). Работает
|
||||
в общем дереве, меняет файлы, гоняет тесты, **но не коммитит**.
|
||||
- **Саморевью worker-а** — отдельная фаза: тот же worker временно становится
|
||||
проверяющим и **сначала только выдаёт находки, не правя их**.
|
||||
- **Независимый ревьюер** — отдельный субагент со **свежим контекстом**. Он не
|
||||
редактирует файлы, но проверяет находки делом: читает diff, issue, спеки и тесты,
|
||||
**сам прогоняет тесты и линтеры**, сверяется с документацией. Ограничивай ему
|
||||
право *записи*, а не право *проверять*: ревьюер, которому оставили только чтение,
|
||||
скатывается в догадки.
|
||||
- **Находка** — гипотеза о проблеме, а не автоматическое требование правки.
|
||||
Решение принимаешь ты.
|
||||
|
||||
Все агенты работают с **одним рабочим деревом**. Поэтому каждый цикл начинай и
|
||||
заканчивай явной проверкой `git status --short` и отделяй рабочие изменения задачи
|
||||
от процессных заметок и чужих правок.
|
||||
|
||||
## Цикл на одну задачу
|
||||
|
||||
1. **Прочитай issue и его зависимости.** На них строятся цель, границы и порядок.
|
||||
Если предыдущие задачи цепочки не закрыты — не начинай.
|
||||
2. **Чистое дерево.** Проверь `git status --short`. Если есть процессные или чужие
|
||||
правки — отдели их отдельным docs-коммитом до запуска worker-а.
|
||||
3. **Запусти одного worker-а на этот issue.** Дай задание как контракт (см. ниже).
|
||||
4. **Дождись отчёта.** Если работа долго молчит (особенно статистика и долгие
|
||||
тесты) — запроси промежуточный статус, не дожидаясь конца вслепую.
|
||||
5. **Саморевью без правок.** Попроси того же worker-а отревьюить свою работу и
|
||||
выдать находки, ничего пока не исправляя.
|
||||
6. **Классифицируй находки** (см. ниже).
|
||||
7. **Верни worker-у только одобренное** для исправления.
|
||||
8. **Свой sanity-check.** Не реимплемент, а проверка связей: дефолты, compose и
|
||||
конфиги, документы, acceptance criteria, `git status`, тесты.
|
||||
9. **На рискованном месте — независимый ревьюер** в свежем субагенте (см.
|
||||
«Когда звать ревьюера»).
|
||||
10. **Классифицируй находки ревьюера.**
|
||||
11. **Большое исправление — повторный круг ревью.** Если правка изменила дизайн
|
||||
или формат данных, ревьюй её результат заново.
|
||||
12. **Коммит делаешь ты.** Это последняя точка контроля состава diff.
|
||||
13. **Закрой субагентов.** Следующая задача стартует в новом worker-е.
|
||||
|
||||
## Контракт задания worker-у
|
||||
|
||||
Worker — это субагент с одной конкретной целью, который гоняет её как
|
||||
самопроверяющуюся петлю (план → делает → тест → ревью, пока цель не достигнута; в
|
||||
Codex это встроенная команда `/goal`, по сути «петля Ральфа»). Цель берётся из
|
||||
одного issue (issues удобно нарезать через `/to-issues`).
|
||||
|
||||
В задании worker-у должны быть:
|
||||
|
||||
- одна конкретная цель из issue и критерий «готово» (acceptance criteria);
|
||||
- границы задачи (что трогать нельзя);
|
||||
- методика `/tdd` (короткие срезы «тест → код»);
|
||||
- **запрет на коммит**;
|
||||
- **запрет на откат чужих изменений**;
|
||||
- формат финального отчёта: файлы, тесты, проверки, выполненные acceptance
|
||||
criteria, риски и `git status --short`.
|
||||
|
||||
Цель worker-а — **одна** (один issue = одна петля). Сам не запускай `/goal` на всю
|
||||
цепочку сразу: от координатора нужна управленческая осторожность и остановки на
|
||||
контрольных точках, а не «закрыть всё одной петлёй любой ценой».
|
||||
|
||||
## Классификация находок
|
||||
|
||||
Ревьюер и саморевью — не источник истины. Каждую находку проверь и отнеси к одной
|
||||
из категорий:
|
||||
|
||||
- **чинить до коммита** — реальный дефект, нарушение acceptance criteria или
|
||||
слабое доказательство ключевого поведения;
|
||||
- **записать как риск** — важно помнить, но текущий коммит не блокирует;
|
||||
- **ложная тревога** — неверно понят код, тест или границы задачи;
|
||||
- **вне скоупа** — может пригодиться позже, но не относится к этому issue.
|
||||
|
||||
Без этой фильтрации ревьюер легко превращается в источник расползания задачи.
|
||||
|
||||
## Когда звать независимого ревьюера
|
||||
|
||||
Не после каждой мелкой правки — это дорого и раздувает задачу. Зови на
|
||||
рискованных точках:
|
||||
|
||||
- state и сериализация;
|
||||
- интеграция сервиса;
|
||||
- изменения формата данных;
|
||||
- статистические модели;
|
||||
- документация (честность README и операционных документов);
|
||||
- после большого исправления — повторный круг.
|
||||
|
||||
Ревьюер проверяет не только падения, но и **силу доказательства**: достаточно ли
|
||||
тест доказывает нужное поведение, а не просто «что-то прошло».
|
||||
|
||||
## Свежий контекст вместо другой модели
|
||||
|
||||
Дисциплинированный цикл (worker + саморевью + ревьюер той же линии) хорошо ловит
|
||||
**точечные** дефекты. Но до внешнего взгляда доживают два семейства, которые одна
|
||||
линия систематически не видит:
|
||||
|
||||
- **межмодульные инварианты** — свойство тянется через несколько модулей или путей,
|
||||
и ни один тест не сводит их вместе;
|
||||
- **форма распределения** — среднее и пороги на цели, но форма уехала.
|
||||
|
||||
В идеале их закрывает ревьюер **другой родословной** (другая модель). Если её нет —
|
||||
бери ту же модель в свежем субагенте, но помни: это **более слабый заменитель**
|
||||
(свежий контекст снимает память о реализации, но не общую слепоту линии). Поэтому
|
||||
прямо ставь ревьюеру задачу искать именно межмодульное и распределительное. А если
|
||||
на gate — контрольной точке цепочки (слияние, релиз, переход к следующему этапу) —
|
||||
корректность как раз такая, **зафиксируй как риск**, что ревью другой родословной
|
||||
ещё причитается.
|
||||
|
||||
## Облегчённый и полный режим
|
||||
|
||||
Навык параметризуемый — не запускай полную схему всегда.
|
||||
|
||||
- **Облегчённый режим** (простой, низкорисковый issue): worker + саморевью + твой
|
||||
sanity-check. Без отдельного ревьюера.
|
||||
- **Полный режим** (риск из списка выше или контрольная точка): добавляешь
|
||||
независимого ревьюера и, при большом исправлении, повторный круг.
|
||||
|
||||
Если что-то сознательно не проверял (например, использовал мок вместо реального
|
||||
стека) — **явно это зафиксируй**, не выдавай за проверенное.
|
||||
|
||||
## Чек-лист координатора
|
||||
|
||||
- [ ] Дерево чистое перед стартом; процессные правки отделены.
|
||||
- [ ] Worker получил один issue и контракт (цель, границы, TDD, запрет коммита и
|
||||
отката чужого, формат отчёта).
|
||||
- [ ] Саморевью сделано без правок; находки классифицированы.
|
||||
- [ ] Свой sanity-check связей пройден.
|
||||
- [ ] На риске запущен независимый ревьюер со свежим контекстом и нацеленным
|
||||
заданием; большое исправление прошло повторный круг.
|
||||
- [ ] Незакрытое ревью другой родословной зафиксировано как риск.
|
||||
- [ ] Коммит сделан координатором, diff узкий и в границах задачи.
|
||||
- [ ] Субагенты закрыты; `git status` чист на выходе.
|
||||
|
||||
## Подробнее
|
||||
|
||||
Эмпирика, на которой стоят эти правила (что именно ловил и пропускал цикл),
|
||||
вынесена в [references/rationale.md](references/rationale.md).
|
||||
|
||||
## Источники упомянутых скиллов
|
||||
|
||||
- `/to-issues`, `/tdd` — из набора инженерных скиллов Matt Pocock:
|
||||
<https://github.com/mattpocock/skills>.
|
||||
- `/goal` — встроенная команда Codex CLI.
|
||||
- `/coordinator-loop` — этот навык; вырос из внутреннего эксперимента с
|
||||
координатором субагентов.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Почему цикл устроен именно так
|
||||
|
||||
Это эмпирика, на которой стоят правила в `SKILL.md`. Читать не обязательно перед
|
||||
каждым запуском — нужна, когда хочешь понять, какому классу дефектов какой шаг
|
||||
противостоит, или решить спорный случай.
|
||||
|
||||
Источник — эксперимент на цепочке из трёх зависимых задач генератора кликстрима
|
||||
(калибровка интенсивности, state версии 2 и рестарт, интеграция сервиса). Задачи
|
||||
меняли близкий код, поэтому шли строго последовательно, по одному worker-у на
|
||||
issue. Выводы — хороший сигнал для класса «последовательные инженерные срезы с
|
||||
тестами и acceptance criteria», но не универсальная истина: один репозиторий, один
|
||||
домен, три задачи.
|
||||
|
||||
## Что какой шаг ловит
|
||||
|
||||
- **Саморевью worker-а** хорошо ловит локальные несостыковки своей же реализации:
|
||||
забытый старый дефолт, слишком широкий тест, устаревшие числа в конфиге,
|
||||
двусмысленный README. У worker-а уже есть подробный контекст, поэтому он дёшево
|
||||
находит такие вещи — но только если запретить ему править на первом шаге и
|
||||
попросить сначала выдать находки.
|
||||
- **Sanity-check координатора** добавляет то, что саморевью структурно не видит:
|
||||
связи между дефолтами, обычным запуском, документами и acceptance criteria.
|
||||
Пример из эксперимента: новый базовый поток конфликтовал со старым нижним
|
||||
пределом числа событий на тик — каждая настройка по отдельности «корректна», а
|
||||
вместе ломали критерий интенсивности.
|
||||
- **Отдельный ревьюер** ловит то, что не видит ни worker, ни его саморевью:
|
||||
падение на битом сохранённом состоянии, которое проходит первичную загрузку;
|
||||
слишком большой снимок состояния (мегабайты вместо компактного); слабый
|
||||
интеграционный тест, который формально проходит, но не доказывает уход от
|
||||
старой плоской модели.
|
||||
- **Повторный круг ревью после большого исправления.** Когда правка по находке
|
||||
меняет дизайн или формат данных, она сама нуждается в ревью. В эксперименте
|
||||
переделка компактного состояния закрыла старый дефект и тут же внесла рядом
|
||||
новый — его поймал именно второй круг.
|
||||
|
||||
## Центральная находка про родословную
|
||||
|
||||
Главную гипотезу эксперимента проверяло отложенное ревью **моделью другой
|
||||
родословной** — той, что вела дизайн и спеки, а не той, что писала код.
|
||||
|
||||
Прогноз, что цикл пропустит ссылочную целостность при восстановлении состояния, **не
|
||||
оправдался**: этот точечный дефект цикл поймал сам (саморевью и отдельный ревьюер
|
||||
независимо нашли «битое состояние проходит загрузку, но роняет восстановление», и в
|
||||
коммит легли обёртка и регрессионный тест).
|
||||
|
||||
А до внешнего взгляда дожили дефекты **не точечные, а сквозные**:
|
||||
|
||||
- **Расхождение живого и восстановленного путей.** Живой визит и восстановленный
|
||||
после рестарта брали атрибуты из разных источников и по-разному генерировали
|
||||
идентификаторы событий. Инвариант «один визит — однородный контекст» нарушался на
|
||||
стыке двух путей, который ни один тест не сводил вместе.
|
||||
- **Форма распределения длины визита.** Среднее и конверсия — на цели, воронка
|
||||
монотонна (тесты это подтверждали), но форма уехала от эталона: спайк на коротких
|
||||
визитах, заметная доля срезов о верхний потолок, медиана у нижней границы тестовой
|
||||
полосы. Тесты пинили средние и пороги, но не форму.
|
||||
|
||||
Отсюда уточнение: ценнее всего ревьюер **другой родословной**, и именно там, где
|
||||
свойство (а) тянется через несколько модулей или путей, либо (б) корректность
|
||||
распределительная (форма, а не одно среднее). Для точечных дефектов на входе
|
||||
хватает саморевью и отдельного ревьюера той же линии.
|
||||
|
||||
Поэтому в `SKILL.md` независимый ревьюер по умолчанию — свежий субагент той же
|
||||
модели, но с честной оговоркой: свежий контекст снимает память о реализации, а не
|
||||
общую слепоту линии. Эти два семейства (межмодульное и распределительное) ему надо
|
||||
давать как явную цель, а незакрытое кросс-линейное ревью на gate — фиксировать как
|
||||
риск.
|
||||
|
||||
## Чего не делать слепо
|
||||
|
||||
- Не запускать ревьюера после каждой мелкой правки — дорого и раздувает задачу.
|
||||
- Не принимать все находки за правду — каждую классифицировать.
|
||||
- Не давать координатору верхнеуровневый `/goal` на всю цепочку — нужна
|
||||
управленческая осторожность, а не достижение цели любой ценой.
|
||||
- Не смешивать процессные и handoff-заметки с рабочими коммитами задач.
|
||||
- Не требовать реальный внешний стек на каждом шаге, если acceptance criteria
|
||||
допускают мок, — но явно фиксировать, что именно осталось непроверенным.
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
Эксперимент оставил нерешённым:
|
||||
|
||||
- как заранее понять, что задаче нужен отдельный ревьюер, а не только саморевью;
|
||||
- стоит ли заранее обязывать worker-а к промежуточным отчётам на статистике и
|
||||
долгих тестах;
|
||||
- нужно ли явно ограничивать бюджет worker-а и число кругов ревью;
|
||||
- как формализовать порог «большое исправление требует второго круга».
|
||||
+1
@@ -0,0 +1 @@
|
||||
../../../agents/.agents/skills/coordinator-loop
|
||||
Reference in new issue
Block a user