--- name: codex-subagent-playbook description: Оптика тонкого мастера для одной нетривиальной задачи: субагенты сохраняют контекст и приносят нужную независимость. --- # Тонкий мастер Это оптика работы, а не обязательный конвейер. Цель — решить одну нетривиальную задачу, сохранив внимание мастера для цели, ограничений, решений и рисков. Субагенты нужны результату, а не процессу. Тонкий мастер не пустой мастер. Он сам принимает решения, делает дешёвые точечные проверки и смотрит ключевые артефакты. Исследование, реализацию или проверку он отдаёт только тогда, когда отдельный контекст даст задаче конкретное преимущество. ## Основная оптика - Перед каждым запуском ответь: что этот агент добавит — защиту контекста, свежий взгляд, специализацию, параллельность или отдельную среду проверки? Если ничего, работай сам или продолжи существующий тред. - Держи у мастера короткий индекс: цель, ограничения, принятые решения, риски, вердикты и доказательства, влияющие на следующий шаг. Полные diff, журналы и нарративы ему не нужны. - Исследование с неизвестным или шумным объёмом делегируй до погружения. Одну узкую гипотезу с предсказуемо короткой командой мастер может проверить сам; если ответа нет, продолжение уходит агенту. - Свежий тред даёт независимость от исполнителя, но не разнообразие ошибок. Другое семейство моделей даёт отдельную линию; второй агент того же семейства оправдан только высоким риском или действительно иным фокусом. - Выбирай самый дешёвый надёжный уровень для выбранной работы. Если хост не показывает модель и глубину, считай стоимость незакреплённой и не умножай совместимые роли без явной пользы. - Один исполнитель владеет изменениями исходников. Его же продолжай для исправлений; независимую оценку отдавай свежему треду. Права `workspace-write` сами по себе не делают агента владельцем исходников. Внешняя модель полезна как дополнительная линия, когда её родословная и цена оправданы риском. Процесс не должен от неё зависеть. ## Контекст и обмен - Если результат понадобится следующему агенту, полный отчёт запиши в уникальный файл временного обменного каталога. Мастеру верни только итог, счётчики, вопросы-решения и путь. Короткий конечный результат можно вернуть одним сообщением. - Канал результата не связан с правами агента. Ревьюеру можно дать рабочие права для тестов, кэшей, поиска и документации, а запрет менять исходники и постоянное окружение удерживать мандатом и сверкой Git до и после. - Не возвращай один полный отчёт одновременно файлом и сообщением. Не переписывай находки между файлами: передавай исходный путь или собирай новый промпт механической конкатенацией. - Не выводи в контекст мастера полную точку отсчёта, diff, перечень хэшей или сырой журнал. Если дерево грязное или возможны пересечения, порученный агент либо готовый скрипт сохраняет подробности во временный файл и сообщает только состояние, счётчики, пересечение с разрешённым объёмом и путь. - Временные обменные файлы веди на английском. Долговечные документы и текст для пользователя пиши на языке проекта. - Сообщай пользователю короткий статус на действительно значимых границах, а не на каждом служебном переходе. Тайм-аут и `idle` не являются результатом. ## Когда какой приём полезен - **Самодостаточная постановка** нужна, когда исполнитель начинает без истории разговора или проекту важен долговечный след. Для локальной ясной правки достаточно короткого мандата. - **Исследователь** нужен для неизвестного объёма, внешних фактов или шумного обхода репозитория. Его результат — факты и вопросы, не реализация. - **Ревью постановки** окупается при скрытых проектных решениях, дорогой ошибке или критериях, которые можно выполнить формально без нужного результата. - **Исполнитель** нужен, когда отдельный контекст реализации ценнее прямой работы мастера. Он не коммитит и не расширяет объём без решения мастера. - **Проверяющий** нужен для шумных журналов, специальной среды, стенда или независимого подтверждения команд. Не создавай отдельную роль, если те же проверки дёшево и надёжно выполняет исполнитель либо ревьюер. - **Свежий ревьюер** нужен, когда цена пропущенного дефекта выше стоимости обзора. По умолчанию достаточно одного. Вторую линию добавляй ради другого семейства моделей или отдельного класса риска, а не ради числа два. ## Типичный ход задачи Часто полезно уточнить постановку, дать одному исполнителю реализовать её, проверить обязательные свойства и при заметном риске получить свежий обзор. Пропускай, объединяй и меняй порядок этих действий, если так надёжнее и дешевле достигается результат. - Перед реализацией разреши продуктовые, архитектурные и относящиеся к границам решения вне мандата исполнителя. Технический способ внутри мандата оставь ему. - Пока исполнитель меняет исходники, не запускай другого владельца тех же файлов. Параллель разрешай для независимых неизменяемых входов, отдельных worktree или команд без общего изменяемого состояния. - Обязательные и доступные сквозные проверки должны пройти до финальной приёмки. Недоступную или падающую проверку нельзя молча превратить в зелёную: риск принимает пользователь либо полномочие, заранее записанное в задаче. - Ревьюеру дай задачу, изменённый объём, проверки и один выбранный фокус. Он исследует и проверяет гипотезы, но не исправляет исходники. Вердикт без находок должен назвать просмотренный объём и выполненные проверки либо проверенные гипотезы. - Находки возвращай тому же исполнителю. Он исправляет или аргументированно отклоняет их через контракт и проверку. Исходный ревьюер при необходимости узко проверяет свои находки; новый соседний дефект не скрывает. - На финале мастер смотрит только решения, остаточные риски, итоговые счётчики и действительно ключевые артефакты. Полный diff и отчёты читают агенты, которым поручена их проверка. Коммит делай только по просьбе пользователя. ## Нативные договоры Если нужны готовые роли или выбор моделей, прочитай [уровни и роли](references/roles.md). Если роли не настроены, не имитируй экономию названиями: честно отметь незакреплённую стоимость. Когда выбран конкретный приём, возьми только его договор из [сборки нативных промптов](references/prompt-templates.md). Не загружай все шаблоны заранее и не переписывай их текст в вызов агента. При развитии скилла или первом прогоне в новой среде прочитай [полевые заметки](references/field-notes.md) и проверь живые предположения. ## Сбои координации - Агент завершился без ожидаемого файла: один раз запроси короткий итог в том же треде; после повторной тишины продолжи свежим агентом от сохранённых артефактов. - Агент вернул длинный рассказ в сообщение: попроси повторить ответ индексом и путём, не переноси рассказ дальше. - Два исполнителя пересеклись в исходниках: останови их, установи одного владельца и продолжи от проверенного состояния, не откатывая чужие правки. - Находки не становятся слабее по раундам: если аргументы исчерпаны, вынеси пользователю противоречие, риск или неверную границу задачи. - После завершения сохрани только предусмотренные проектом долговечные решения и удали временные артефакты именно этого прогона.