feat(agents): добавлен плейбук оркестрации субагентов

- Зачем: - нужен повторяемый процесс делегирования без засорения контекста мастер-модели. - Что: - добавлен явно вызываемый скилл с этапами, договорами возврата и защитой рабочего дерева. - описаны роли, уровни стоимости, полевые заметки и handoff для следующей версии. - Проверка: - quick_validate.py agents/.agents/skills/codex-subagent-playbook. - git diff --cached --check.
2026-07-10 16:46:57 +03:00
1 parent 6e767d13ff
commit 4d074adda6
@@ -0,0 +1,156 @@
+---
+name: codex-subagent-playbook
+description: Координация одной нетривиальной инженерной задачи через субагентов с сохранением чистого контекста мастера.
+---
+
+# Тонкий мастер
+
+Ты — координатор. Держи в своём контексте цель, ограничения, решения и
+индекс находок. Исследование, реализацию, проверки, журналы и полный diff
+отдавай субагентам. Внешний агент полезен как дополнительная независимая
+линия, но процесс не должен от него зависеть.
+
+Применяй конвейер к одной нетривиальной задаче. Если работа локальна, вывод
+короток и ошибка дёшева, сообщи о лишних накладных расходах и сделай её сам.
+
+## Договор делегирования
+
+- Запускай свежих исполнителей без истории мастера (`fork_turns="none"`),
+  когда среда это поддерживает. Передавай путь к самодостаточному
+  файлу-задаче, а не пересказ разговора.
+- Давай каждому субагенту одну роль и проверяемый результат. Выбирай самый
+  дешёвый уровень, который надёжно справится с этой ролью.
+- Проси вернуть только итог, доказательства, вопросы-решения и следующий
+  шаг. Полные журналы оставляй в `/tmp` или в принятом проектом каталоге.
+- Продолжай того же исполнителя для починки его кода. Для независимого
+  ревью запускай свежий тред.
+- Держи одного владельца рабочего дерева. Пока он пишет, другие агенты не
+  читают это дерево. Параллель разрешай только для неизменяемых входов или
+  отдельных worktree.
+- До писателя сохрани в `/tmp` машинно читаемую точку отсчёта: статус,
+  полный staged/unstaged diff, а также перечень и хэши неотслеживаемых
+  файлов. После него сравни новое состояние с точкой отсчёта и отчётом. Не
+  удаляй и не откатывай чужие изменения.
+- Сообщай пользователю короткий статус на границах этапов.
+
+Если нужные роли ещё не настроены или надо выбрать модели, прочитай
+[уровни и роли](references/roles.md). Не загружай этот справочник в обычном
+прогоне с уже настроенными ролями.
+
+При развитии скилла или первом прогоне в новой среде прочитай
+[полевые заметки](references/field-notes.md) и проверь открытые предположения.
+
+## Формат возврата
+
+Каждому субагенту задай этот договор результата:
+
+```text
+ИТОГ: завершено | есть вопросы | заблокировано
+ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики
+РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь
+НАХОДКИ: SEVERITY файл:строка — суть — как проверить
+СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет»
+```
+
+Пустые разделы пропускаются. Сырой вывод и ход рассуждений в ответ не
+включаются.
+
+Для ревьюера замени общий раздел `ИТОГ` на обязательный договор:
+
+```text
+ВЕРДИКТ: APPROVED | REVISE
+ПОКРЫТИЕ: проверенные области, файлы и команды
+ДОКАЗАТЕЛЬСТВА: результаты проверок или воспроизведения
+НАХОДКИ: SEVERITY файл:строка — сценарий сбоя — как проверить
+```
+
+Пустой индекс принимай только с заполненными покрытием и доказательствами.
+Для дорогого ревью попроси также сохранить индекс в `/tmp` и вернуть путь:
+сообщение может потеряться после завершения треда.
+
+## Конвейер
+
+### 1. Зафиксировать задачу
+
+Создай или уточни принятый проектом файл-задачу: цель, критерии приёмки,
+границы, решения, что прочитать и команды проверки. Шумное исследование
+репозитория отдай быстрому исследователю. Он находит команды, но не запускает
+полный набор; узкую проверку выполняет только для подтверждения нужного
+факта. Если задача ссылается на другой скилл, продублируй его ключевые
+требования текстом: исполнитель может не подхватить скилл автоматически.
+
+Этап завершён, когда исполнитель может начать без истории разговора и без
+уточняющих вопросов.
+
+### 2. Проверить постановку
+
+Для сложной или дорогой ошибки отдай постановку свежему сильному ревьюеру.
+Попроси проверить её против реального кода: выполнимость, скрытые решения,
+пропущенные критерии и способы формально отчитаться без нужного результата.
+Для особенно дорогой ошибки используй два слепых ревью.
+
+Внеси в файл-задачу решение по каждой находке: принять, сузить или отклонить
+с доводом.
+
+Этап завершён, когда у каждой находки есть записанное решение.
+
+### 3. Реализовать
+
+Передай задачу отдельному исполнителю с правом записи. Мандат: следовать
+файлу-задаче, не делать коммит, не менять соседний объём. Исполнитель
+запускает только узкие проверки разработки; полный набор остаётся этапу 4.
+
+Этап завершён, когда отчёт исполнителя соответствует изменённому дереву и
+все критерии либо выполнены, либо явно помечены как заблокированные.
+
+### 4. Переварить проверки
+
+Отдай быстрому проверяющему тесты, линтеры, сборку и объёмные журналы. Пусть
+он вернёт команды, счётчики, короткую причину каждого сбоя и путь к полному
+журналу. Исправления возвращай исполнителю этапа 3.
+
+Этап завершён, когда полный обязательный набор прошёл после последней правки
+или каждый оставшийся сбой объяснён и принят пользователем.
+
+### 5. Провести слепое ревью
+
+Запусти свежего ревьюера без контекста исполнителя. Для высокого риска
+запусти двух ревьюеров параллельно с разными фокусами. Внешнюю модель
+подключай дополнительной линией, если она доступна и её стоимость оправдана.
+Ревьюеры исследуют и проверяют гипотезы, но возвращают только индекс находок
+и не исправляют код.
+
+Этап завершён, когда все запрошенные вердикты получены, а рабочее дерево не
+содержит неназванных правок.
+
+### 6. Закрыть находки
+
+Дословно передай общий индекс исполнителю этапа 3. Он исправляет находку,
+сужает исправление или отклоняет её через контракт, код и проверку. Мастер
+проверяет серьёзные и спорные отклонения, решает вопросы объёма и риска.
+Исправления отправляй прежнему ревьюеру на узкую повторную проверку.
+
+Этап завершён, когда по каждой находке записано решение и принятые
+исправления перепроверены.
+
+### 7. Принять результат
+
+Используй отчёт этапа 4. Повтори только проверки, которые обесценили более
+поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя
+делегировать. Обнови файл-задачу. Коммит делай только по просьбе
+пользователя.
+
+Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны,
+неназванных изменений нет, а пользователь получил краткий итог.
+
+## Сбои координации
+
+- Агент исчез без отчёта: сначала проверь сохранённый файл, затем один раз
+  запроси итог. После повторной тишины подними свежего агента с
+  файлом-задачей и уже собранным индексом.
+- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по
+  договору возврата.
+- Два писателя пересеклись: останови их, установи владельца каждой правки и
+  продолжи одним исполнителем от проверенной точки отсчёта.
+- Находки не становятся слабее по раундам: останови цикл и вынеси пользователю
+  противоречие или неверно выбранную границу задачи.