--- 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. Повтори только проверки, которые обесценили более поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя делегировать. Обнови файл-задачу. Коммит делай только по просьбе пользователя. Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны, неназванных изменений нет, а пользователь получил краткий итог. ## Сбои координации - Агент исчез без отчёта: сначала проверь сохранённый файл, затем один раз запроси итог. После повторной тишины подними свежего агента с файлом-задачей и уже собранным индексом. - Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по договору возврата. - Два писателя пересеклись: останови их, установи владельца каждой правки и продолжи одним исполнителем от проверенной точки отсчёта. - Находки не становятся слабее по раундам: останови цикл и вынеси пользователю противоречие или неверно выбранную границу задачи.