dotfiles/agents/.agents/skills/codex-subagent-playbook/references/roles.md

Уровни и роли

Маршрутизация моделей обновлена 2026-07-13. Имена и уровни здесь — датированная настройка среды; логика основной оптики остаётся относительной.

Читай этот файл только при настройке ролей или когда нужная роль недоступна. Основная оптика описывает, когда отдельный агент вообще нужен. Этот файл — условные настройки мандата, а не список обязательных участников. Один агент может совмещать совместимую работу; не создавай тред на каждое имя.

• Возможности хоста
• Выбор уровня
• Текущая маршрутизация
• Возможные мандаты
• Файл пользовательского агента
• Пределы параллельности

Возможности хоста

Сначала установи, позволяет ли текущий хост выбрать пользовательского агента и его конфигурацию.

• Управляемая стоимость. Хост видит агентов из ~/.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 — идентификатор треда, а не выбор конфигурации агента.

Если способ выбора роли не виден в доступном инструменте, считай стоимость неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу на дополнительные роли без явной пользы.

Вызов TOML-роли:

{
  "task_name": "explore_code",
  "message": "Исследуй код и верни выжимку по договору роли.",
  "fork_turns": "none",
  "agent_type": "explorer"
}

Разовый выбор модели без TOML-роли с закреплёнными настройками:

{
  "task_name": "explore_code",
  "message": "Исследуй код и верни выжимку по договору результата.",
  "fork_turns": "none",
  "model": "<быстрая модель>",
  "reasoning_effort": "medium"
}

Не смешивай режимы: роль применяется отдельным слоем конфигурации и может перекрыть прямые параметры. service_tier передавай только по явному запросу; он технически совместим и с полным fork. Если TOML-роль закрепляет service_tier, значение роли перекрывает аргумент вызова; для гарантированного разового tier используй роль без закреплённого tier.

Основание: официальная документация о субагентах и актуальная схема spawn_agent.

Выбор уровня

Уровень	Для чего	Настройка
Быстрый	Поиск, журналы, известные проверки, ограниченная механика	Дешёвая подходящая модель, обычно 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. Конкретные имена держи здесь и в конфигурации агентов, а не в 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 сверяется до и после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу. Канал результата от песочницы не зависит. При выбранном ревью используй единый договор: назначенный файл отчёта — единственный результат наблюдателя; временные кэши допустимы, исходники и Git неизменны.

verifier

Уровень: быстрый. Запускает уже известные команды приёмки, разбирает сбои и возвращает счётчики. Не ищет новые требования и не исправляет продуктовый код.

Обычно: sandbox_mode = "workspace-write".

Файл пользовательского агента

Роли Codex хранятся в ~/.codex/agents/*.toml или .codex/agents/*.toml. Минимальный шаблон:

name = "role-name"
description = "Когда координатору выбирать эту роль."
model = "<актуальная модель нужного уровня>"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Одна узкая роль и её договор результата.
"""

Не подменяй выбор роли совпадением task_name с её именем: это работает только при явной гарантии хоста. После добавления или изменения TOML начни новую сессию и проверь, что имя роли появилось в описании agent_type.

Пределы параллельности

• Держи глубину 1: субагенты не создают собственное дерево исполнителей.
• Оставляй один слот координатору.
• Параллельно запускай только работу без конфликтующих входов, команд и изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а не ради заполнения свободного слота.
• Реализацию и починку одного рабочего дерева выполняй последовательно одним владельцем.