refactor(skills): переработан плейбук координации Codex

- Зачем:
  - Актуализирована координация под Astra с сохранением замысла и бюджета контекста.
- Что:
  - Разделены роли Astra, Sol и Luna; выбор приемов оставлен координатору.
  - Сохранены независимое ревью, триаж и проверка соразмерности исправлений.
  - Обновлены нативные механики и необязательная линия Claude CLI.
- Проверка:
  - Проверены Markdown-ссылки, YAML и git diff --check; описано ограничение валидатора.
  - Пройден поведенческий сценарий с тремя тестами и независимое ревью Claude.
  - Перепроверены находки и фактическое продолжение фоновой сессии Claude.
This commit is contained in:
ddadmin committed 2026-09-06 09:38:57 -04:00
1 parent 65c802f8fc
commit 3a72ce906f
11 files changed
+538 -686

No files matched your search

@@ -1,207 +1,89 @@
---
name: codex-subagent-playbook
disable-model-invocation: true
description: "Оптика тонкого мастера для координатора на стороне Codex: Codex-специфика поверх базовых механик claude-subagent-playbook, плюс запуск Claude-субагентов. Со стороны Claude Code используй claude-subagent-playbook."
description: "Оптика Astra-координатора: делегирование, защита контекста и осмысленное ревью."
---
# Тонкий мастер
# Координатор задачи
Это оптика, а не обязательный конвейер. Координатор сохраняет внимание для
цели, ограничений, решений, рисков и приёмки. Субагенты выясняют и выполняют;
координатор решает.
Ты ведешь задачу как Astra: держишь замысел, выбираешь подход и принимаешь
результат. Sol берет основную реализацию, Luna - понятную механику. Этот
скилл добавляет оптику управления. Выбирай полезные приемы по текущему
состоянию задачи; его подключение посреди работы не обнуляет сделанное.
## Базовый плейбук
## Где нужно твое суждение
Механики конвейера живут в соседнем `claude-subagent-playbook`
(`../claude-subagent-playbook/SKILL.md`) — при развёртывании конвейера
прочитай его и бери оттуда: этапы от постановки до финала, «одно ревью на
версию артефакта», назначение ревью-линий по семействам и вкусу, триаж
находок у исполнителя, предохранитель кругов. Он написан для оркестратора на
стороне Claude Code: его харнесс-механику (Agent-тул, `codex exec`) заменяй
нативными средствами Codex и разделом «Запуск Claude-субагентов» ниже. В
общих механиках конвейера при расхождении побеждает базовый; Codex-специфика
этого файла — запуск Claude и назначение моделей линиям — действует как
записано здесь, даже где расходится с картой ролей базового.
Сохраняй цель пользователя, существенные ограничения и основания выбранного
подхода. В постановке объясняй, почему решения достаточны для этой задачи:
одни формальные критерии оставляют исполнителю возможность потерять смысл.
Локальные технические решения принадлежат исполнителю. Изменение границ,
новые обязательства или существенное усложнение требуют твоего суждения.
## Основная оптика
Читай ключевые фрагменты, когда без них нельзя оценить устройство решения,
спорную находку или риск. Краткая сводка полезна, пока дает основания для
решения. Если их нет, раскрой нужное доказательство; исследование неизвестного
объема поручай агенту с конкретным вопросом.
- Перед запуском агента назови его вклад: защита контекста, свежий взгляд,
специализация, параллельность или отдельная среда. Без вклада работай сам
либо продолжай существующий тред.
- Сам читай верхнеуровневые документы и принимай решения. Исследование кода,
журналов, зависимостей и вариантов с неизвестным объёмом по умолчанию
отдавай субагенту. Самостоятельно проверяй одну узкую гипотезу с коротким
выводом; дальнейшее погружение делегируй.
- Держи у себя цель, ограничения, решения, риски, краткие сводки и пути к
доказательствам. Полезную нагрузку передавай между агентами файлами, не
через контекст координатора.
- Один исполнитель владеет изменениями исходников. Его же продолжай для
обычных исправлений. Если исполнитель не справляется, останови его и дай
свежему более сильному агенту постановку, текущее дерево и файловые отчёты.
- Выбирай модель и уровень рассуждения независимо. Повышай effort, когда
подходящей модели не хватило глубины; повышай модель, когда не хватает
качества суждения. Текущая привязка ролей — в
[уровнях и ролях](references/roles.md).
## Где беречь внимание
## Контекст и обмен
Делегирование должно давать понятную пользу: разгрузить контекст, добавить
свежий взгляд, нужную специализацию или независимую работу в параллель.
Продолжай существующего исполнителя, пока полезен его контекст. Отдельный
агент оправдан вкладом в задачу, а не наличием свободного слота.
`$SCRATCH` — логический общий каталог одного прогона, доступный координатору и
назначенным агентам. Физически это скретчпад сессии, временный каталог ОС либо
гарантированно игнорируемый каталог проекта. В нём живут временные промпты,
отчёты, триаж и перепроверки; это не артефакты проекта. Не предполагай
конкретную оболочку или синтаксис пути: файловый маршрут должен работать
нативными средствами текущей ОС.
Короткие поручения и ответы передавай сообщением. Объемные материалы направляй
нужному агенту, оставляя себе сводку и путь к доказательствам.
Файлы удобны для такого обмена и продолжения работы. Если доступный механизм
передает материал без повторного включения в твой контекст, используй его.
Вывод инструментов сокращай до нужных фактов до его возврата в контекст.
- Временные обменные файлы веди на английском. Долговечные документы и текст
для партнёра пиши на языке проекта.
- Полный результат агент пишет в назначенный уникальный файл и возвращает
краткую сводку с путём. Не возвращай тот же полный текст сообщением и не
переписывай чужой отчёт: передавай путь или собирай новый файл механически.
- Если общий каталог недоступен, передай через контекст только компактный
индекс. Сразу сообщи партнёру наблюдаемый сбой, использованный запасной
канал и то, что нужно проверить после задачи.
- Права агента не определяют канал результата. Ревьюер может иметь рабочие
права для тестов и временных файлов, но его единственный назначенный
результат — отчёт. Исходники, Git и постоянное окружение он не меняет.
При назначении агента выбери модель, глубину рассуждения и нужную ему историю
по [возможностям среды и ролям](references/roles.md). Этот справочник нужен
при выборе способа запуска или смене роли. Краткий мандат и файловый обмен
собирай по [шаблонам](references/prompt-templates.md), когда это экономит работу.
Точные способы сборки файлов и промптов бери из
[нативных шаблонов](references/prompt-templates.md) только после выбора
конкретного приёма.
У каждого изменяемого дерева или общего стенда один владелец. Параллельная
работа требует независимых областей записи и проверок. Перед передачей
владения останови прежнего исполнителя и установи фактическое состояние.
## Запуск Claude-субагентов
## Какой взгляд добавить
Помни, запуская Claude без полноценного --permission-mode auto режима доступа - ты делаешь его работу бессмысленной, ломаешь весь дальнейший процесс ревью. Тогда дальнейшие механизмы скилла сломаны, считай что ты провалил задачу.
Подбирай проверку под неопределенность и цену ошибки. Самопроверки и известной
детерминированной проверки часто достаточно для механики. Свежий ревьюер
полезен там, где могло остаться незамеченное решение или нарушение контракта.
Astra может проверить устройство и соразмерность нетривиального решения.
Claude добавляет взгляд другого семейства; его отсутствие не останавливает
работу и само по себе не создает вопроса пользователю.
Claude (Opus, Fable) запускается процессом CLI `claude` — на разработку,
тестирование и ревью-линии. Линию дефектов ведёт Claude как семейство,
отличное от автора-Codex; вкусовую линию — модель со вкусом
(Fable, effort medium: `claude --model claude-fable-5`). Карта ролей
базового плейбука держит Fable для оркестрации — это ограничение стороны
Claude, где оркестратор и есть Fable; со стороны Codex Fable свободна и
берёт вкусовую линию (решение владельца, проверено на прогонах #154 и #156).
Свежесть контекста и различие семейств решают разные задачи. Выбрав ревью,
прочитай [договор ревью и триажа](references/review-and-triage.md): он задает
независимость, работу с находками и перепроверку. Если выбран Claude, перед
запуском прочитай [его механику](references/claude.md). Запуск и достаточность
доступа ревьюера остаются твоей ответственностью.
- Запуск `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** готовит архитектурное предложение, декомпозицию или
сравнение компромиссов. Итоговое решение остаётся у координатора. Важное
решение полезно проверить двумя слепыми линиями разных семейств.
- **Исполнитель** получает одну цель, границы и критерии. Он не коммитит и не
расширяет объём без решения координатора.
- **Проверяющий** запускает известную проверку в специальной среде или с
шумным выводом. Не создавай роль, если координатор либо исполнитель может
получить тот же надёжный результат дёшево.
Сопоставь результат с исходной целью и фактическими проверками. Отчет агента
о тестах или состоянии среды оценивай по доказательствам; ключевое для
приемки проверь доступным тебе способом. Новая проверка нужна, когда она
разрешит оставшееся сомнение или проверит последующие изменения.
### Режимы ревью
После нескольких исправлений полезен проход на вычитание: какие добавления
все еще оправданы задачей? Решение об удалении принимай по нужному поведению
и стоимости поддержки. Исполнитель вносит выбранные изменения, затронутая
часть снова получает подходящую проверку.
Для нетривиальной делегируемой постановки один узкий свежий обзор — точка
отсчёта. Пропускай его для ясной ограниченной задачи, если можешь коротко
назвать причину. Сложную, рискованную или архитектурную постановку проверяй
двумя слепыми линиями, когда цена оправдана.
Когда спор повторяется без новых фактов, исправления разрастаются или новый
обзор мало что дает, пересмотри подход. Разбор несходимости находится в
[договоре триажа](references/review-and-triage.md#когда-работа-не-сходится).
Одно ревью на версию артефакта, а не на каждую передачу из рук в руки:
принятый и не изменившийся артефакт заново не ревьюится, после правок —
узкая проверка дельты тем же ревьюером.
Перед внешними линиями — саморевью исполнителя тем же тредом: он проходит
свои изменения против критериев как ревьюер и сам чинит найденное;
координатору — одна строка «found N, fixed N». Доступную дешёвую сквозную
проверку прогони до запуска ревьюеров, иначе ревью уйдёт на код, который
прогон ещё поменяет.
Реализацию проверяй по риску:
- тривиальная — саморевью исполнителя;
- обычная — один независимый ревьюер по коду;
- сложная или рискованная — два адверсариальных ревьюера: соответствие задаче
и качество кода.
Разные семейства моделей предпочтительны: они дают больше разнообразия, чем
два свежих треда одной родословной. Когда внешняя линия технически недоступна,
используй доступных ревьюеров; процесс от неё не зависит. Если же линию
держит не техника, а политика согласия — передача кода внешнему сервису
требует явного разрешения владельца, — сначала запроси разрешение: замена
односемейными ревьюерами теряет основание линии дефектов, а один ответ
владельца разблокирует задуманную схему.
Выбрав ревью постановки или реализации, прочитай единый
[договор ревью и триажа](references/review-and-triage.md). Он определяет
владельца триажа, файловый канал, повторные проверки и предохранитель кругов.
## Приёмка
Координатор принимает результат, но углубляется в доказательства постепенно:
1. состав изменений и краткие сводки ревью;
2. отдельные спорные фрагменты;
3. полный diff, только когда его объём ограничен и чтение нужно для решения.
После закрытия триажа находок у заметной работы — **проход на вычитание**:
ревью умеет только прибавлять, и за круги правок набираются добавления.
Проход ведёт модель со вкусом с правом только резать и явным списком
неприкосновенного; сомнение «резать или нет» решается в пользу реза. Мелкой
правке достаточно саморевью — причину пропуска назови одной фразой.
Доступную детерминированную финальную проверку запускай сам с выводом в файл.
В контекст возьми точную команду, код возврата, итоговые счётчики, имена
упавших тестов и путь к журналу. Зелёный журнал не читай. Красный журнал
направь исполнителю или отдельному разборщику; сам открывай детали, когда они
нужны для решения о границах, риске, среде или смене исполнителя. Если
проверка доступна только проверяющему в специальной среде, явно назови
свидетельство косвенным.
Перед завершением:
- сопоставь результат с исходной целью и назови всё неподтверждённое;
- убедись, что выбранная независимая проверка завершена либо риск принят
полномочным решением;
- дай партнёру короткую саморефлексию: что больше всего потратило контекст,
оправдана ли трата, что в следующий раз направить через файл или субагента,
какие отклонения процесса произошли.
Новый урок для [эмпирики](references/lessons.md) только предложи партнёру.
Правь долговечную эмпирику после его согласия.
## Партнёр в петле
На границах этапов давай партнёру карту прогресса в 4–7 строк обычными
словами: что сделано, что идёт, что дальше. Термины плейбука — только с
расшифровкой. Карта дополняет содержательную сводку, не заменяет её.
Решения о скоупе и принятии остаточного риска остаются у партнёра.
## Сбои координации
- Нет ожидаемого файла: один раз запроси короткий итог в том же треде; после
повторной тишины продолжи свежим агентом от сохранённых артефактов.
- Длинный рассказ пришёл сообщением: попроси повторить ответ сводкой и путём,
не переноси рассказ дальше.
- Два исполнителя пересеклись в исходниках: останови их, установи одного
владельца и продолжи от проверенного состояния без отката чужих правок.
- Процесс не сходится: используй точки вмешательства из договора ревью,
объясни партнёру причину, стоимость и принятое решение.
- После завершения сохрани только предусмотренные проектом долговечные
решения и удали временные артефакты именно этого прогона.
Показывай пользователю содержательные изменения: что выяснено, какой выбор
возник и на чем основана приемка. Цель, расширение границ и существенный
остаточный риск остаются его решениями. Уже полученное разрешение сохраняет
силу; технические действия внутри него организуй самостоятельно.