dotfiles/.scratch/codex-subagent-playbook/spec.md

# Переработка codex-subagent-playbook

## Задача

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

Текущий скилл вырос из Claude-плейбука, развивался отдельно и позднее получил
ссылку на него как на базовый. В нём смешались прежние ограничения среды,
повторяющиеся правила и разные шкалы ревью. По опыту пользователя, Sol
склонен выполнять формальные требования, принимать замечания ревью за истину
и усложнять решение после нескольких кругов исправлений. Проход на вычитание
появился как защита от этого поведения.

## Принятый подход

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

У выбранного приёма есть ясный договор. Например, независимое ревью требует
свежего контекста, а триаж — явного исхода каждой находки. Эти свойства
сохраняют смысл приёма. Правила владения изменениями защищают совместную
работу агентов. Остальные рекомендации оставляют место суждению координатора.

### Роли и внимание координатора

| Участник | Назначение |
|---|---|
| Astra | Замысел, подход, границы, технический вкус, разрешение спорных вопросов и приёмка |
| Sol | Основная реализация, техническое исследование, проверка и исправление подтверждённых дефектов |
| Luna | Понятная механика, пакетные операции и известные проверки с объёмным выводом |
| Claude | Преимущественно независимое ревью другим семейством моделей для поиска слепых зон GPT |

Это распределение ответственности, а не обязательный список участников.
Sol свободен в локальных технических решениях. Вопрос, который существенно
меняет устройство решения, границы или добавляет обязательства, возвращается
координатору с вариантами, последствиями и рекомендацией.

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

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

### Ревью и отдельный триаж

Claude полезен различием обучения и самостоятельным взглядом на код. Его
доступность не гарантирована: основной процесс работает средствами Codex,
а отсутствие Claude само по себе не требует согласования. Выбор конкретной
модели опирается на результаты прогонов; прежняя оценка Opus не становится
постоянной гарантией качества.

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

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

У каждой находки есть явный исход: исправлена, отклонена, вынесена за границы
или требует решения. Исправления перепроверяются, отклонения подкрепляются
доводами. Вынесенный вопрос остаётся открытым до решения его владельца.
Сохраняется связь между исходной находкой, её разбором и перепроверкой.

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

Ревью — набор проверяемых утверждений. При разборе важны фактическая верность,
применимость сценария к проекту и соразмерность исправления. Предложенный
ревьюером способ починки тоже оценивается; исполнитель может выбрать более
подходящий. Аргументированное отклонение нормально, квота отклонений не нужна.
Например, требование усилить безопасность должно опираться на применимый
сценарий и конкретную границу доверия. Само упоминание безопасности не делает
предложение обязательным.

Проход на вычитание сохраняется как приём против накопления лишнего после
реализации и ревью. Координатор оценивает, какие добавления по-прежнему
оправданы задачей. Выбранные удаления сохраняют нужное поведение, изменившаяся
часть получает подходящую проверку. Универсальное правило «при сомнении режь»
уступает оценке конкретного решения.

### Среда и устройство скилла

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

Новый скилл опирается на доступные средства выбора модели, глубины рассуждения
и передачи истории. Июльские утверждения об ограничениях требуют проверки.
Описание параметра инструментом и его фактическое применение различаются;
проверенные возможности и оставшиеся предположения должны быть различимы.

Структуру определяет [writing-for-agents](../../agents/.agents/skills/writing-for-agents/SKILL.md):
общая оптика находится в основном тексте, механика отдельных приёмов — по
ссылкам с ясными условиями чтения. Один смысл имеет одно авторитетное место.
Конкретные настройки среды отделены от устойчивых принципов. Границы
обязательной работы сформулированы проверяемо, без лишних ритуалов.

## Границы и альтернативы

Полная переработка самостоятельного Codex-скилла предпочтительнее точечной
починки надстройки: надстройка сохраняет чтение двух расходящихся инструкций.
Claude-плейбук служит источником проверенных приёмов; его полное чтение
перестаёт быть предпосылкой применения нового скилла.

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

## Как оценить результат переработки

Поведение нового скилла нужно проверить на характерных ситуациях:

- При подключении посреди работы координатор выбирает нужные приёмы,
  сохраняя силу уже выполненной работы и проверок.
- Механическая задача не порождает лишних участников и этапов; нетривиальное
  решение получает достаточное внимание Astra и обоснованное ревью.
- Большой отчёт попадает нужному агенту, а координатор получает основания
  для решения без повторного чтения полного материала.
- Ошибочная или неуместная находка получает обоснованный исход; настоящая
  проблема исправляется и проверяется. Все находки учтены отдельно.
- Повторяющийся спор без новых доказательств вызывает пересмотр подхода,
  а не автоматический запуск ещё одного общего ревью.
- Исправление, которое добавляет существенную сложность, получает оценку
  уместности до внесения; проход на вычитание сохраняет нужное поведение.
- При недоступности Claude работа продолжается доступными средствами;
  ограничения проведённой проверки названы точно.
- Выбор моделей, глубины рассуждения и передачи истории опирается на
  проверенные возможности среды, а не на старые заметки.

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