Dmitry Dementiev
60182ab493
- Зачем: - следующая сессия должна управлять стоимостью субагентов без повторной загрузки длинных отчётов в контекст мастера. - Что: - разделены TOML-роли и разовые переопределения модели, уточнены fork и service tier. - добавлен файловый обмен, жизненный цикл временного каталога и нативные скелеты промптов. - синхронизированы полевые заметки и handoff с проверенной механикой Codex. - Проверка: - quick_validate.py agents/.agents/skills/codex-subagent-playbook. - git diff --cached --check. - независимое ревью: VERDICT: APPROVED.
111 lines
8.9 KiB
Markdown
111 lines
8.9 KiB
Markdown
# Handoff: первая версия Codex Subagent Playbook
|
||
|
||
Дата: 2026-07-10. Для следующей сессии, которая добавит настоящие роли
|
||
Codex и проверит полный конвейер на боевой задаче.
|
||
|
||
## Состояние
|
||
|
||
Первая версия скилла готова и формально валидна:
|
||
|
||
- процесс тонкого мастера — [`../SKILL.md`](../SKILL.md);
|
||
- выбор ролей и уровней — [`../references/roles.md`](../references/roles.md);
|
||
- перенесённые уроки и открытые проверки —
|
||
[`../references/field-notes.md`](../references/field-notes.md);
|
||
- точные договоры нативных агентов —
|
||
[`../references/prompt-templates.md`](../references/prompt-templates.md);
|
||
- явный вызов скилла — [`../agents/openai.yaml`](../agents/openai.yaml).
|
||
|
||
Нативные TOML-роли ещё не созданы. В интерфейсе пробной tool-backed сессии
|
||
хост скрыл поля `agent_type`, `model`, `reasoning_effort` и `service_tier`,
|
||
поэтому прогон использовал роли только как мандаты в промпте и честно
|
||
пометил стоимость как неуправляемую. Это не общее ограничение Codex:
|
||
нативная схема поддерживает все четыре поля.
|
||
|
||
## Принятые решения
|
||
|
||
- Главная цель — сохранить контекст мастер-модели для требований, решений и
|
||
синтеза. Внешняя модель остаётся необязательной дополнительной линией.
|
||
- Скилл запускается только явно. Текущий валидатор не принимает
|
||
`disable-model-invocation`; используется
|
||
`policy.allow_implicit_invocation: false` в `openai.yaml`.
|
||
- Модели закрепляются в файлах ролей, а не в `SKILL.md`, чтобы процесс не
|
||
зависел от смены модельной линейки.
|
||
- Для TOML-роли передаётся `agent_type`; для разового выбора — `model` и
|
||
`reasoning_effort` без роли с закреплённой моделью. Плейбук использует
|
||
`fork_turns="none"` ради чистого контекста; полный fork `all` наследует
|
||
модель мастера.
|
||
- Один агент владеет рабочим деревом. До записи сохраняется точка отсчёта,
|
||
включая хэши неотслеживаемых файлов.
|
||
- Полный отчёт ревьюера сохраняется файлом; сообщение содержит только
|
||
вердикт, счётчики и путь. `read-only`-ревьюер возвращает короткий индекс
|
||
один раз сообщением.
|
||
- На прогон создаётся один обменный временный каталог. Полные отчёты и
|
||
повторно используемые промпты передаются между агентами путями; мастер не
|
||
вставляет их повторно в tool-call.
|
||
- После завершения или сохранения блокирующего handoff обменный каталог
|
||
этого прогона удаляется.
|
||
- Нативный конвейер не зависит от вложенного запуска `codex exec`.
|
||
|
||
## Что проверено
|
||
|
||
- `quick_validate.py` завершился с `Skill is valid!`.
|
||
- Независимое ревью закрыло договор ревьюера, точку отсчёта, выбор стоимости
|
||
и устранение лишних повторных прогонов.
|
||
- Безопасный пробный прогон этапов 1–2 поднял исследователя и ревьюера,
|
||
сформировал самодостаточную постановку и не вынес сырые журналы в итог
|
||
мастера. Файлы проекта не менялись.
|
||
- Прогон выявил лишний полный запуск тестов исследователем; ограничение роли
|
||
уже внесено в процесс и справочник.
|
||
|
||
## Следующая сессия
|
||
|
||
1. Решить, входят ли Windows/chezmoi в первую поставку ролей. Пробная
|
||
постановка ограничила первую поставку Linux/WSL.
|
||
2. Выбрать модели для быстрого, рабочего и глубокого уровней. Локально
|
||
подтверждена только `gpt-5.6-sol`; не считать это готовой таблицей ролей.
|
||
3. Создать шесть ролей: `fast-worker`, `explorer`, `worker`,
|
||
`deep-reasoner`, `reviewer`, `verifier`.
|
||
4. Разместить Linux/WSL-источник в `codex/.codex/agents/` и узко открыть
|
||
нужные TOML в `.gitignore`. Сейчас родительское правило игнорирует весь
|
||
каталог.
|
||
5. Расширить `tests/test_install.sh`: разобрать TOML через `tomllib`,
|
||
проверить смысловые договоры ролей, повторную установку, стороннюю роль и
|
||
конфликт совпадающего имени.
|
||
6. Проверить обнаружение ролей установленным Codex CLI в отдельном
|
||
`CODEX_HOME`. Затем начать новую сессию и проверить, что её схема
|
||
`spawn_agent` открывает `agent_type`, `model`, `reasoning_effort` и
|
||
`service_tier`.
|
||
Синтаксический разбор TOML не доказывает поддержку схемы.
|
||
7. Прогнать этапы 3–7 на подходящей задаче, обновить полевые заметки только
|
||
подтверждёнными фактами и убрать поглощённый осадок.
|
||
8. Измерить, сколько длинных отчётов реально попало в контекст мастера.
|
||
Цель — каждый полный артефакт читается не более одного раза и больше не
|
||
пересказывается между агентами.
|
||
|
||
## Известные ловушки
|
||
|
||
- Простое исключение `!codex/.codex/agents/*.toml` может не сработать, пока
|
||
не раскрыты игнорируемые родительские каталоги. Нужны положительные и
|
||
отрицательные проверки `git check-ignore`.
|
||
- Текущее рабочее дерево dotfiles содержит посторонние изменения. Работать
|
||
от сохранённой точки отсчёта, не очищать и не включать их в коммиты.
|
||
- `task_name` нативного `spawn_agent` — имя треда, а не доказанный выбор
|
||
пользовательской конфигурации агента.
|
||
- Полный fork `all` несовместим с другой ролью, моделью и глубиной. Плейбук
|
||
использует `none` для свежего контекста; ограниченный fork числом
|
||
технически допускает переопределения.
|
||
- Некоторые tool-backed хосты скрывают поля управления моделью, хотя Codex
|
||
их поддерживает. Проверять фактическую схему в начале сессии.
|
||
- Права `workspace-write` не гарантируют сеть. Проверку документации и поиск
|
||
отмечать как непроверенные, если сеть недоступна.
|
||
- Длинный текст в `spawn_agent`, `send_message` или `followup_task` остаётся
|
||
в истории мастера. Передавать путь к файлу и короткий вопрос.
|
||
|
||
## Suggested skills
|
||
|
||
- `$writing-great-skills` — удерживать плотность и предсказуемость скилла.
|
||
- `$skill-creator` — валидировать структуру и проводить пробные прогоны.
|
||
- `$tdd` — сначала закрепить установку и договоры ролей тестами.
|
||
- `$claude-team-review` — независимое ревью после появления TOML и тестов.
|
||
- `$conventional-commits` — зафиксировать следующую завершённую поставку.
|