refactor(skills): переработан плейбук координации Codex
- Зачем: - Актуализирована координация под Astra с сохранением замысла и бюджета контекста. - Что: - Разделены роли Astra, Sol и Luna; выбор приемов оставлен координатору. - Сохранены независимое ревью, триаж и проверка соразмерности исправлений. - Обновлены нативные механики и необязательная линия Claude CLI. - Проверка: - Проверены Markdown-ссылки, YAML и git diff --check; описано ограничение валидатора. - Пройден поведенческий сценарий с тремя тестами и независимое ревью Claude. - Перепроверены находки и фактическое продолжение фоновой сессии Claude.
This commit is contained in:
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 строк обычными
|
||||
словами: что сделано, что идёт, что дальше. Термины плейбука — только с
|
||||
расшифровкой. Карта дополняет содержательную сводку, не заменяет её.
|
||||
Решения о скоупе и принятии остаточного риска остаются у партнёра.
|
||||
|
||||
## Сбои координации
|
||||
|
||||
- Нет ожидаемого файла: один раз запроси короткий итог в том же треде; после
|
||||
повторной тишины продолжи свежим агентом от сохранённых артефактов.
|
||||
- Длинный рассказ пришёл сообщением: попроси повторить ответ сводкой и путём,
|
||||
не переноси рассказ дальше.
|
||||
- Два исполнителя пересеклись в исходниках: останови их, установи одного
|
||||
владельца и продолжи от проверенного состояния без отката чужих правок.
|
||||
- Процесс не сходится: используй точки вмешательства из договора ревью,
|
||||
объясни партнёру причину, стоимость и принятое решение.
|
||||
- После завершения сохрани только предусмотренные проектом долговечные
|
||||
решения и удали временные артефакты именно этого прогона.
|
||||
Показывай пользователю содержательные изменения: что выяснено, какой выбор
|
||||
возник и на чем основана приемка. Цель, расширение границ и существенный
|
||||
остаточный риск остаются его решениями. Уже полученное разрешение сохраняет
|
||||
силу; технические действия внутри него организуй самостоятельно.
|
||||
Reference in new issue
Block a user