dotfiles/agents/.agents/skills/codex-subagent-playbook/SKILL.md

---

name: codex-subagent-playbook description: Оптика тонкого мастера для одной нетривиальной задачи: субагенты сохраняют контекст и приносят нужную независимость.

Тонкий мастер

Это оптика работы, а не обязательный конвейер. Цель — решить одну нетривиальную задачу, сохранив внимание мастера для цели, ограничений, решений и рисков. Субагенты нужны результату, а не процессу.

Тонкий мастер не пустой мастер. Он сам принимает решения, делает дешёвые точечные проверки и смотрит ключевые артефакты. Исследование, реализацию или проверку он отдаёт только тогда, когда отдельный контекст даст задаче конкретное преимущество.

Основная оптика

• Перед каждым запуском ответь: что этот агент добавит — защиту контекста, свежий взгляд, специализацию, параллельность или отдельную среду проверки? Если ничего, работай сам или продолжи существующий тред.
• Держи у мастера короткий индекс: цель, ограничения, принятые решения, риски, вердикты и доказательства, влияющие на следующий шаг. Полные diff, журналы и нарративы ему не нужны.
• Исследование с неизвестным или шумным объёмом делегируй до погружения. Одну узкую гипотезу с предсказуемо короткой командой мастер может проверить сам; если ответа нет, продолжение уходит агенту.
• Свежий тред даёт независимость от исполнителя, но не разнообразие ошибок. Другое семейство моделей даёт отдельную линию; второй агент того же семейства оправдан только высоким риском или действительно иным фокусом.
• Выбирай самый дешёвый надёжный уровень для выбранной работы. Если хост не показывает модель и глубину, считай стоимость незакреплённой и не умножай совместимые роли без явной пользы.
• Один исполнитель владеет изменениями исходников. Его же продолжай для исправлений; независимую оценку отдавай свежему треду. Права workspace-write сами по себе не делают агента владельцем исходников.

Внешняя модель полезна как дополнительная линия, когда её родословная и цена оправданы риском. Процесс не должен от неё зависеть.

Контекст и обмен

• Если результат понадобится следующему агенту, полный отчёт запиши в уникальный файл временного обменного каталога. Мастеру верни только итог, счётчики, вопросы-решения и путь. Короткий конечный результат можно вернуть одним сообщением.
• Канал результата не связан с правами агента. Ревьюеру можно дать рабочие права для тестов, кэшей, поиска и документации, а запрет менять исходники и постоянное окружение удерживать мандатом и сверкой Git до и после.
• Не возвращай один полный отчёт одновременно файлом и сообщением. Не переписывай находки между файлами: передавай исходный путь или собирай новый промпт механической конкатенацией.
• Не выводи в контекст мастера полную точку отсчёта, diff, перечень хэшей или сырой журнал. Если дерево грязное или возможны пересечения, порученный агент либо готовый скрипт сохраняет подробности во временный файл и сообщает только состояние, счётчики, пересечение с разрешённым объёмом и путь.
• Временные обменные файлы веди на английском. Долговечные документы и текст для пользователя пиши на языке проекта.
• Сообщай пользователю короткий статус на действительно значимых границах, а не на каждом служебном переходе. Тайм-аут и idle не являются результатом.

Когда какой приём полезен

• Самодостаточная постановка нужна, когда исполнитель начинает без истории разговора или проекту важен долговечный след. Для локальной ясной правки достаточно короткого мандата.
• Исследователь нужен для неизвестного объёма, внешних фактов или шумного обхода репозитория. Его результат — факты и вопросы, не реализация.
• Ревью постановки окупается при скрытых проектных решениях, дорогой ошибке или критериях, которые можно выполнить формально без нужного результата.
• Исполнитель нужен, когда отдельный контекст реализации ценнее прямой работы мастера. Он не коммитит и не расширяет объём без решения мастера.
• Проверяющий нужен для шумных журналов, специальной среды, стенда или независимого подтверждения команд. Не создавай отдельную роль, если те же проверки дёшево и надёжно выполняет исполнитель либо ревьюер.
• Свежий ревьюер нужен, когда цена пропущенного дефекта выше стоимости обзора. По умолчанию достаточно одного. Вторую линию добавляй ради другого семейства моделей или отдельного класса риска, а не ради числа два.

Типичный ход задачи

Часто полезно уточнить постановку, дать одному исполнителю реализовать её, проверить обязательные свойства и при заметном риске получить свежий обзор. Пропускай, объединяй и меняй порядок этих действий, если так надёжнее и дешевле достигается результат.

• Перед реализацией разреши продуктовые, архитектурные и относящиеся к границам решения вне мандата исполнителя. Технический способ внутри мандата оставь ему.
• Пока исполнитель меняет исходники, не запускай другого владельца тех же файлов. Параллель разрешай для независимых неизменяемых входов, отдельных worktree или команд без общего изменяемого состояния.
• Обязательные и доступные сквозные проверки должны пройти до финальной приёмки. Недоступную или падающую проверку нельзя молча превратить в зелёную: риск принимает пользователь либо полномочие, заранее записанное в задаче.
• Ревьюеру дай задачу, изменённый объём, проверки и один выбранный фокус. Он исследует и проверяет гипотезы, но не исправляет исходники. Вердикт без находок должен назвать просмотренный объём и выполненные проверки либо проверенные гипотезы.
• Находки возвращай тому же исполнителю. Он исправляет или аргументированно отклоняет их через контракт и проверку. Исходный ревьюер при необходимости узко проверяет свои находки; новый соседний дефект не скрывает.
• На финале мастер смотрит только решения, остаточные риски, итоговые счётчики и действительно ключевые артефакты. Полный diff и отчёты читают агенты, которым поручена их проверка. Коммит делай только по просьбе пользователя.

Нативные договоры

Если нужны готовые роли или выбор моделей, прочитай уровни и роли. Если роли не настроены, не имитируй экономию названиями: честно отметь незакреплённую стоимость.

Когда выбран конкретный приём, возьми только его договор из сборки нативных промптов. Не загружай все шаблоны заранее и не переписывай их текст в вызов агента.

При развитии скилла или первом прогоне в новой среде прочитай полевые заметки и проверь живые предположения.

Сбои координации

• Агент завершился без ожидаемого файла: один раз запроси короткий итог в том же треде; после повторной тишины продолжи свежим агентом от сохранённых артефактов.
• Агент вернул длинный рассказ в сообщение: попроси повторить ответ индексом и путём, не переноси рассказ дальше.
• Два исполнителя пересеклись в исходниках: останови их, установи одного владельца и продолжи от проверенного состояния, не откатывая чужие правки.
• Находки не становятся слабее по раундам: если аргументы исчерпаны, вынеси пользователю противоречие, риск или неверную границу задачи.
• После завершения сохрани только предусмотренные проектом долговечные решения и удали временные артефакты именно этого прогона.