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

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

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

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

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

- Перед запуском агента назови его вклад: защита контекста, свежий взгляд,
  специализация, параллельность или отдельная среда. Без вклада работай сам
  либо продолжай существующий тред.
- Сам читай верхнеуровневые документы и принимай решения. Исследование кода,
  журналов, зависимостей и вариантов с неизвестным объёмом по умолчанию
  отдавай субагенту. Самостоятельно проверяй одну узкую гипотезу с коротким
  выводом; дальнейшее погружение делегируй.
- Держи у себя цель, ограничения, решения, риски, краткие сводки и пути к
  доказательствам. Полезную нагрузку передавай между агентами файлами, не
  через контекст координатора.
- Один исполнитель владеет изменениями исходников. Его же продолжай для
  обычных исправлений. Если исполнитель не справляется, останови его и дай
  свежему более сильному агенту постановку, текущее дерево и файловые отчёты.
- Выбирай модель и уровень рассуждения независимо. Повышай effort, когда
  подходящей модели не хватило глубины; повышай модель, когда не хватает
  качества суждения. Текущая привязка ролей — в
  [уровнях и ролях](references/roles.md).

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

`$SCRATCH` — логический общий каталог одного прогона, доступный координатору и
назначенным агентам. Физически это скретчпад сессии, временный каталог ОС либо
гарантированно игнорируемый каталог проекта. В нём живут временные промпты,
отчёты, триаж и перепроверки; это не артефакты проекта. Не предполагай
конкретную оболочку или синтаксис пути: файловый маршрут должен работать
нативными средствами текущей ОС.

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

Точные способы сборки файлов и промптов бери из
[нативных шаблонов](references/prompt-templates.md) только после выбора
конкретного приёма.

## Выбор приёма

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

### Режимы ревью

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

Реализацию проверяй по риску:

- тривиальная — саморевью исполнителя;
- обычная — один независимый ревьюер по коду;
- сложная или рискованная — два адверсариальных ревьюера: соответствие задаче
  и качество кода.

Разные семейства моделей предпочтительны: они дают больше разнообразия, чем
два свежих треда одной родословной. Когда внешняя линия технически недоступна,
используй доступных ревьюеров; процесс от неё не зависит.

Выбрав ревью постановки или реализации, прочитай единый
[договор ревью и триажа](references/review-and-triage.md). Он определяет
владельца триажа, файловый канал, повторные проверки и предохранитель кругов.

## Приёмка

Координатор принимает результат, но углубляется в доказательства постепенно:

1. состав изменений и краткие сводки ревью;
2. отдельные спорные фрагменты;
3. полный diff, только когда его объём ограничен и чтение нужно для решения.

Доступную детерминированную финальную проверку запускай сам с выводом в файл.
Команды нового сценария проверь на живом объекте до полного прогона; сложные
вставки собирай файлами, не экранированием.
В контекст возьми точную команду, код возврата, итоговые счётчики, имена
упавших тестов и путь к журналу. Зелёный журнал не читай. Красный журнал
направь исполнителю или отдельному разборщику; сам открывай детали, когда они
нужны для решения о границах, риске, среде или смене исполнителя. Если
проверка доступна только проверяющему в специальной среде, явно назови
свидетельство косвенным.

Перед завершением:

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

Новый урок для [эмпирики](references/lessons.md) только предложи партнёру.
Правь долговечную эмпирику после его согласия.

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

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