From 65c802f8fc3563156c618fbcbdfeaad12a39803e Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 6 Sep 2026 08:48:58 -0400 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=D1=81=D0=BE=D0=B3=D0=BB=D0=B0?= =?UTF-8?q?=D1=81=D0=BE=D0=B2=D0=B0=D0=BD=D0=B0=20=D0=BF=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D0=BA=D0=B0=20=D0=BF=D0=BB=D0=B5?= =?UTF-8?q?=D0=B9=D0=B1=D1=83=D0=BA=D0=B0=20Codex?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - сохранить замысел самостоятельного скилла для Astra-координатора. - Что: - описаны роли, защита контекста и выбор приёмов по задаче. - сохранены отдельный триаж и защита от несходящегося ревью. - Проверка: - выполнен горячий обзор против обсуждения и действующего договора триажа. - проверены локальные ссылки и git diff --cached --check. --- .scratch/codex-subagent-playbook/spec.md | 160 +++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 .scratch/codex-subagent-playbook/spec.md diff --git a/.scratch/codex-subagent-playbook/spec.md b/.scratch/codex-subagent-playbook/spec.md new file mode 100644 index 0000000..9999e33 --- /dev/null +++ b/.scratch/codex-subagent-playbook/spec.md @@ -0,0 +1,160 @@ +# Переработка 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 работа продолжается доступными средствами; + ограничения проведённой проверки названы точно. +- Выбор моделей, глубины рассуждения и передачи истории опирается на + проверенные возможности среды, а не на старые заметки. + +Конкретные настройки моделей и способы запуска уточняются при переработке. +Эта спецификация сохраняет согласованное направление; изменение самого +скилла начинается по отдельному запросу на реализацию.