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

---
name: codex-subagent-playbook
disable-model-invocation: true
description: "Оптика тонкого мастера для координатора на стороне Codex: Codex-специфика поверх базовых механик claude-subagent-playbook, плюс запуск Claude-субагентов. Со стороны Claude Code используй claude-subagent-playbook."
---

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

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

## Базовый плейбук

Механики конвейера живут в соседнем `claude-subagent-playbook`
(`../claude-subagent-playbook/SKILL.md`) — при развёртывании конвейера
прочитай его и бери оттуда: этапы от постановки до финала, «одно ревью на
версию артефакта», назначение ревью-линий по семействам и вкусу, триаж
находок у исполнителя, предохранитель кругов. Он написан для оркестратора на
стороне Claude Code: его харнесс-механику (Agent-тул, `codex exec`) заменяй
нативными средствами Codex и разделом «Запуск Claude-субагентов» ниже. В
общих механиках конвейера при расхождении побеждает базовый; Codex-специфика
этого файла — запуск Claude и назначение моделей линиям — действует как
записано здесь, даже где расходится с картой ролей базового.

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

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

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

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

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

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

## Запуск Claude-субагентов

Claude (Opus, Fable) запускается процессом CLI `claude` — на разработку,
тестирование и ревью-линии. Линию дефектов ведёт Claude как семейство,
отличное от автора-Codex; вкусовую линию — модель со вкусом
(Fable, effort medium: `claude --model claude-fable-5`). Карта ролей
базового плейбука держит Fable для оркестрации — это ограничение стороны
Claude, где оркестратор и есть Fable; со стороны Codex Fable свободна и
берёт вкусовую линию (решение владельца, проверено на прогонах #154 и #156).

- Запуск `claude` передаёт diff и фрагменты кода внешнему сервису Anthropic.
  Если твоя политика требует на это явного разрешения владельца, запроси его
  **до начала реализации**, одним вопросом на весь прогон: вопрос в момент
  ревью останавливает конвейер на самом дорогом участке.
- Запускай с `--permission-mode auto`: иначе Claude не может искать
  информацию в интернете и запускать тесты.
- Первое ревью линии — свежая сессия; повторные ревью — продолжением той же
  сессии: контекст первого ревью дешевле нового.
- Длительные задачи — через `--bg`, чтобы тайм-аут одного вызова клиента не
  завершал работу. Состояние смотри `claude agents`, содержание —
  `claude logs <id>`, примерно раз в 5–10 минут. Это частота наблюдения, а не
  лимит времени: процесс жив и в журнале есть прогресс — оставь работать,
  Claude может выполнять задачу значительно дольше. `--max-turns` — не ручка
  ограничения времени.
- Тайм-аут отдельного запроса — не потеря сессии: продолжай через
  `--resume <session-id>`, это быстрее и дешевле, чем начинать заново.
- Прямолинейные суждения бери агентом `craftsman`, сложные решения и
  высокоответственные ревью — `deep-reasoner`; карта «роль → модель и
  ступень» — в базовом плейбуке, `references/claude-agents.md`.

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

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

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

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

Одно ревью на версию артефакта, а не на каждую передачу из рук в руки:
принятый и не изменившийся артефакт заново не ревьюится, после правок —
узкая проверка дельты тем же ревьюером.

Перед внешними линиями — саморевью исполнителя тем же тредом: он проходит
свои изменения против критериев как ревьюер и сам чинит найденное;
координатору — одна строка «found N, fixed N». Доступную дешёвую сквозную
проверку прогони до запуска ревьюеров, иначе ревью уйдёт на код, который
прогон ещё поменяет.

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

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

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

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

## Приёмка

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

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

После закрытия триажа находок у заметной работы — **проход на вычитание**:
ревью умеет только прибавлять, и за круги правок набираются добавления.
Проход ведёт модель со вкусом с правом только резать и явным списком
неприкосновенного; сомнение «резать или нет» решается в пользу реза. Мелкой
правке достаточно саморевью — причину пропуска назови одной фразой.

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

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

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

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

## Партнёр в петле

На границах этапов давай партнёру карту прогресса в 4–7 строк обычными
словами: что сделано, что идёт, что дальше. Термины плейбука — только с
расшифровкой. Карта дополняет содержательную сводку, не заменяет её.
Решения о скоупе и принятии остаточного риска остаются у партнёра.

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

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