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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если нужны готовые роли или выбор моделей, прочитай
[уровни и роли](references/roles.md). Если роли не настроены, не имитируй
экономию названиями: честно отметь незакреплённую стоимость.

Когда выбран конкретный приём, возьми только его договор из
[сборки нативных промптов](references/prompt-templates.md). Не загружай все
шаблоны заранее и не переписывай их текст в вызов агента.

При развитии скилла или первом прогоне в новой среде прочитай
[полевые заметки](references/field-notes.md) и проверь живые предположения.

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

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