refactor(skills): переработан плейбук координации Codex
- Зачем: - Актуализирована координация под Astra с сохранением замысла и бюджета контекста. - Что: - Разделены роли Astra, Sol и Luna; выбор приемов оставлен координатору. - Сохранены независимое ревью, триаж и проверка соразмерности исправлений. - Обновлены нативные механики и необязательная линия Claude CLI. - Проверка: - Проверены Markdown-ссылки, YAML и git diff --check; описано ограничение валидатора. - Пройден поведенческий сценарий с тремя тестами и независимое ревью Claude. - Перепроверены находки и фактическое продолжение фоновой сессии Claude.
This commit is contained in:
ddadmin committed
1 parent
65c802f8fc
commit
3a72ce906f
11 files changed
+538
-686
No files matched your search
@@ -1,212 +1,55 @@
|
||||
# Уровни и роли
|
||||
# Роли и возможности среды
|
||||
|
||||
Маршрутизация моделей обновлена 2026-07-13. Имена и уровни здесь — датированная
|
||||
настройка среды; логика [основной оптики](../SKILL.md) остаётся относительной.
|
||||
Читай этот файл при выборе агента, модели, глубины рассуждения или способа
|
||||
передачи истории. Сначала посмотри на схему доступного инструмента: она
|
||||
описывает текущую среду точнее датированных заметок.
|
||||
|
||||
Читай этот файл только при настройке ролей или когда нужная роль недоступна.
|
||||
[Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен.
|
||||
Этот файл — условные настройки мандата, а не список обязательных участников.
|
||||
Один агент может совмещать совместимую работу; не создавай тред на каждое имя.
|
||||
## Распределение ответственности
|
||||
|
||||
- [Возможности хоста](#возможности-хоста)
|
||||
- [Выбор уровня](#выбор-уровня)
|
||||
- [Текущая маршрутизация](#текущая-маршрутизация)
|
||||
- [Возможные мандаты](#возможные-мандаты)
|
||||
- [Файл пользовательского агента](#файл-пользовательского-агента)
|
||||
- [Пределы параллельности](#пределы-параллельности)
|
||||
- **Astra** держит замысел, выбирает устройство решения, разрешает спорные
|
||||
вопросы и принимает результат. Свежая Astra полезна для отдельной проверки
|
||||
формы и соразмерности, когда цена такого взгляда оправдана.
|
||||
- **Sol** обычно реализует задачу, исследует техническую неопределенность,
|
||||
проверяет код и исправляет подтвержденные дефекты.
|
||||
- **Luna** удобна для ясной механики, пакетных операций и известных проверок
|
||||
с объемным выводом.
|
||||
|
||||
## Возможности хоста
|
||||
Эти назначения служат отправной точкой. Состав собирай под задачу; один агент
|
||||
может совмещать совместимую работу. Выбор определяется вкладом в задачу и
|
||||
качеством доступных моделей. Название роли вторично.
|
||||
|
||||
Сначала установи, позволяет ли текущий хост выбрать пользовательского агента
|
||||
и его конфигурацию.
|
||||
## Модель и глубина
|
||||
|
||||
- **Управляемая стоимость.** Хост видит агентов из `~/.codex/agents` или
|
||||
`.codex/agents` и схема `spawn_agent` открывает `agent_type`, `model` и
|
||||
`reasoning_effort` (про фактическое применение effort — кавеат в
|
||||
[выборе уровня](#выбор-уровня)). Для TOML-роли передавай `agent_type`, а
|
||||
модель и глубину бери из её файла. Для разового выбора передавай `model` и
|
||||
`reasoning_effort` без пользовательской роли с закреплённой моделью.
|
||||
Плейбук использует `fork_turns="none"` ради чистого контекста. Технически
|
||||
ограниченный fork числом тоже допускает переопределения; только полный
|
||||
fork `all` наследует модель координатора и отклоняет их.
|
||||
- **Неуправляемая стоимость.** Интерфейс запуска принимает только задачу и
|
||||
имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана
|
||||
дешёвая или сильная модель. `task_name` — идентификатор треда, а не выбор
|
||||
конфигурации агента.
|
||||
Модель и глубину рассуждения выбирай независимо, если среда открывает обе
|
||||
ручки. Для ограниченной работы разумная отправная точка - `medium`. Для
|
||||
необратимого решения, высокой цены тихой ошибки или существенной
|
||||
неопределенности - `high` либо более сильная доступная настройка. Это примеры:
|
||||
повышай глубину, когда не хватило поиска и рассуждения, а модель - когда не
|
||||
хватило качества суждения.
|
||||
|
||||
Если способ выбора роли не виден в доступном инструменте, считай стоимость
|
||||
неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу
|
||||
на дополнительные роли без явной пользы.
|
||||
Не обещай, что запрошенная модель или глубина фактически применились, если
|
||||
инструмент подтверждает лишь принятие параметра. Опирайся на метаданные запуска,
|
||||
когда они доступны; иначе называй настройку запрошенной.
|
||||
|
||||
Вызов TOML-роли:
|
||||
## Текущая схема Codex
|
||||
|
||||
```json
|
||||
{
|
||||
"task_name": "explore_code",
|
||||
"message": "Исследуй код и верни выжимку по договору роли.",
|
||||
"fork_turns": "none",
|
||||
"agent_type": "explorer"
|
||||
}
|
||||
```
|
||||
На момент обновления доступный `spawn_agent` принимает `model`,
|
||||
`reasoning_effort` и `fork_turns`. Значение `fork_turns` может быть `none`,
|
||||
`all` или положительным числом строкой.
|
||||
|
||||
Разовый выбор модели без TOML-роли с закреплёнными настройками:
|
||||
- `none` дает свежий контекст. Используй его для независимого исходного ревью
|
||||
и для роли, которой достаточно самодостаточного краткого задания.
|
||||
- Положительное число передает ограниченный хвост истории. Это полезно, когда
|
||||
без ближайшего контекста поручение раздуется, а вся история не нужна.
|
||||
- `all` передает полную историю и наследует модель и глубину координатора.
|
||||
В этом режиме явные переопределения модели и глубины отклоняются.
|
||||
|
||||
```json
|
||||
{
|
||||
"task_name": "explore_code",
|
||||
"message": "Исследуй код и верни выжимку по договору результата.",
|
||||
"fork_turns": "none",
|
||||
"model": "<быстрая модель>",
|
||||
"reasoning_effort": "medium"
|
||||
}
|
||||
```
|
||||
Для явного выбора модели или глубины используй `none` либо ограниченную
|
||||
историю. Продолжение через `followup_task` сохраняет полезный контекст уже
|
||||
созданного агента; короткое уточнение работающему агенту передается сообщением.
|
||||
Новый свежий обзор запускается отдельным агентом с `none`.
|
||||
|
||||
Не смешивай режимы: роль применяется отдельным слоем конфигурации и может
|
||||
перекрыть прямые параметры. `service_tier` передавай только по явному запросу;
|
||||
он технически совместим и с полным fork. Если TOML-роль закрепляет
|
||||
`service_tier`, значение роли перекрывает аргумент вызова; для гарантированного
|
||||
разового tier используй роль без закреплённого tier.
|
||||
|
||||
Основание: [официальная документация о субагентах](https://learn.chatgpt.com/docs/agent-configuration/subagents)
|
||||
и [актуальная схема `spawn_agent`](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/multi_agents_spec.rs).
|
||||
|
||||
## Выбор уровня
|
||||
|
||||
| Уровень | Для чего | Настройка |
|
||||
|---|---|---|
|
||||
| Быстрый | Поиск, журналы, известные проверки, ограниченная механика | Дешёвая подходящая модель, обычно `medium` |
|
||||
| Рабочий | Обычная реализация и проверка по задаче | Подходящая ролевая модель, `medium` |
|
||||
| Глубокий | Архитектура, сложная реализация, ревью кода | Сильная модель, `high` |
|
||||
| Исключительный | Необратимое решение или несходимость сильных агентов | Самая сильная модель, `max` |
|
||||
|
||||
Критерий выбора — цена *тихой* ошибки этапа, не сложность работы: где
|
||||
пропущенный дефект никто ниже по конвейеру не поймает (постановка, слепое
|
||||
ревью, диагноз), ставь глубокий уровень; где за результатом стоит приёмка
|
||||
координатора и ошибка громкая (узкая перепроверка, механика), хватает
|
||||
рабочего. Таблица «для чего» — иллюстрация этого критерия, не замена.
|
||||
Экономию уровня считай по конвейеру целиком: дешёвый этап, породивший
|
||||
длинный триаж находок, выходит дороже дорогого.
|
||||
|
||||
Модель задаёт потолок способности, effort — глубину работы этой модели.
|
||||
Повышай effort, когда подходящей модели не хватило поиска или рассуждения.
|
||||
Повышай модель, когда не хватает качества решения. После двух слабых
|
||||
результатов замени исполнителя свежим более сильным агентом вместо переноса
|
||||
его неудачного контекста. От уверенной выдумки внешних фактов (форматы
|
||||
артефактов, версии) не страхует никакой уровень — такие факты проверяй
|
||||
реальным запросом или фикстурой из первоисточника.
|
||||
Кавеат (2026-07-23): текущий хост принимает `reasoning_effort` субагента,
|
||||
но фактически не применяет — рабочая ручка сейчас только модель;
|
||||
перепроверяй после обновлений хоста.
|
||||
|
||||
`xhigh` не является автоматической ступенью: текущая эмпирика показывает
|
||||
малый прирост относительно `high` при заметной цене. Выбирай его вручную для
|
||||
узкой задачи. `max` заметно сильнее и дороже; используй по явному триггеру и
|
||||
объясняй партнёру причину.
|
||||
|
||||
## Текущая маршрутизация
|
||||
|
||||
Это начальная рабочая таблица, а не рейтинг моделей. Проверяй её на прогонах и
|
||||
меняй после согласования эмпирики с партнёром.
|
||||
|
||||
| Роль | Модель и effort |
|
||||
|---|---|
|
||||
| Простая ограниченная реализация, `fast-worker`, известная проверка | Luna `medium` |
|
||||
| Узкий обзор постановки, проверка реализации по задаче | Terra `medium` |
|
||||
| Обычная нетривиальная реализация | Sol `medium` |
|
||||
| Сложная или рискованная реализация | Sol `high` |
|
||||
| `deep-reasoner`: архитектурное предложение, декомпозиция, компромиссы | Sol `high` |
|
||||
| Ревью кода | Sol `high` |
|
||||
| Необратимое решение, спор сильных агентов, повторная несходимость | Sol `max` |
|
||||
|
||||
Официальное назначение текущих уровней семейства — в
|
||||
[каталоге моделей OpenAI](https://developers.openai.com/api/docs/models).
|
||||
Конкретные имена держи здесь и в конфигурации агентов, а не в `SKILL.md`.
|
||||
|
||||
## Возможные мандаты
|
||||
|
||||
### `fast-worker`
|
||||
|
||||
Уровень: быстрый. Читает шумный ввод, запускает проверки, выполняет простые
|
||||
пакетные операции. Возвращает только выжимку и пути к полным журналам.
|
||||
|
||||
Обычно: `sandbox_mode = "workspace-write"`, потому что тесты и инструменты
|
||||
создают временные файлы. В инструкциях ограничить изменения явно названной
|
||||
механикой.
|
||||
|
||||
### `explorer`
|
||||
|
||||
Уровень: быстрый. Строит карту кода, находит точки входа, контракты и команды
|
||||
проверки. Не запускает полный набор тестов и не проектирует решение, пока
|
||||
координатор прямо не попросит. Узкую команду запускает только для проверки факта,
|
||||
без которого карта ненадёжна.
|
||||
|
||||
Обычно: `sandbox_mode = "read-only"`.
|
||||
|
||||
### `worker`
|
||||
|
||||
Уровень: рабочий или глубокий по сложности задачи. Единственный владелец
|
||||
реализации. Читает самодостаточный файл-задачу, меняет код и проверяет свою
|
||||
часть. Не делает коммит.
|
||||
|
||||
Обычно: `sandbox_mode = "workspace-write"`.
|
||||
|
||||
### `deep-reasoner`
|
||||
|
||||
Уровень: глубокий. Принимает одно сложное решение: архитектура, алгоритм,
|
||||
диагноз, противоречие требований. Возвращает предложение, ключевые доводы и
|
||||
непроверенные предположения; итоговое решение принимает координатор.
|
||||
|
||||
Обычно: `sandbox_mode = "read-only"`.
|
||||
|
||||
### `reviewer`
|
||||
|
||||
Уровень: глубокий. Свежий тред без истории исполнителя. Ищет ошибки
|
||||
корректности, безопасности, контракта и тестов. Каждая находка содержит
|
||||
сценарий сбоя, доказательство, влияние и способ проверки.
|
||||
|
||||
Для полноценного ревью обычно нужен `sandbox_mode = "workspace-write"`: тесты,
|
||||
кэши, временные артефакты и исследование не следует урезать ради запрета
|
||||
правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется
|
||||
до и после. Доступ к сети проверять отдельно: право записи не гарантирует
|
||||
поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу.
|
||||
Канал результата от песочницы не зависит. При выбранном ревью используй
|
||||
[единый договор](review-and-triage.md): назначенный файл отчёта — единственный
|
||||
результат наблюдателя; временные кэши допустимы, исходники и Git неизменны.
|
||||
|
||||
### `verifier`
|
||||
|
||||
Уровень: быстрый. Запускает уже известные команды приёмки, разбирает сбои и
|
||||
возвращает счётчики. Не ищет новые требования и не исправляет продуктовый
|
||||
код.
|
||||
|
||||
Обычно: `sandbox_mode = "workspace-write"`.
|
||||
|
||||
## Файл пользовательского агента
|
||||
|
||||
Роли Codex хранятся в `~/.codex/agents/*.toml` или `.codex/agents/*.toml`.
|
||||
Минимальный шаблон:
|
||||
|
||||
```toml
|
||||
name = "role-name"
|
||||
description = "Когда координатору выбирать эту роль."
|
||||
model = "<актуальная модель нужного уровня>"
|
||||
model_reasoning_effort = "medium"
|
||||
sandbox_mode = "read-only"
|
||||
developer_instructions = """
|
||||
Одна узкая роль и её договор результата.
|
||||
"""
|
||||
```
|
||||
|
||||
Не подменяй выбор роли совпадением `task_name` с её именем: это работает
|
||||
только при явной гарантии хоста. После добавления или изменения TOML начни
|
||||
новую сессию и проверь, что имя роли появилось в описании `agent_type`.
|
||||
|
||||
## Пределы параллельности
|
||||
|
||||
- Держи глубину `1`: субагенты не создают собственное дерево исполнителей.
|
||||
- Оставляй один слот координатору.
|
||||
- Параллельно запускай только работу без конфликтующих входов, команд и
|
||||
изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а
|
||||
не ради заполнения свободного слота.
|
||||
- Реализацию и починку одного рабочего дерева выполняй последовательно одним
|
||||
владельцем.
|
||||
Эти сведения описывают текущий интерфейс координации. После изменения схемы
|
||||
заново проверь доступные поля. Файлы локальных
|
||||
ролей, установка моделей и внешняя настройка среды в работу этого скилла не
|
||||
входят. Владение общим состоянием задает [основная оптика](../SKILL.md).
|
||||
Reference in new issue
Block a user