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

Уровни и роли

Читай этот файл только при настройке ролей или когда нужная роль недоступна. Сам конвейер описан в SKILL.md.

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

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

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

• Управляемая стоимость. Хост видит агентов из ~/.codex/agents или .codex/agents и схема spawn_agent открывает agent_type, model и reasoning_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.

Выбор уровня

Уровень	Для чего	Настройка
Быстрый	Поиск, чтение журналов, тесты, пакетная механика	Быстрая дешёвая модель, low или medium
Рабочий	Обычная реализация по ясной постановке	Сильная модель для кода, medium или high
Глубокий	Архитектура, сложная диагностика, ревью высокого риска	Самая сильная доступная модель, high или выше

Начинай с самого дешёвого подходящего уровня. Повышай уровень, когда агент не может проверить предположение, дважды возвращает слабый результат или задача требует решения с высокой ценой ошибки. Не повышай уровень ради объёма механической работы: дели её на независимые части.

• low/medium: детерминированная механика, поиск и известные проверки.
• medium/high: реализация по ясному контракту, несколько связанных файлов, нет необратимых решений.
• high: публичный контракт, безопасность, целостность данных, конкуренция, миграция или неоднозначная архитектура.
• xhigh и выше: необратимый дорогой выбор либо повторное противоречие сильных агентов. Это исключение, а не обычный режим ревью.

Конкретные названия моделей держи в конфигурации агентов, а не в 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 = "read-only". Если ревью требует запуска инструментов, которые пишут кэш или артефакты, использовать workspace-write, запретить правки исходников мандатом и сверить 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: субагенты не создают собственное дерево исполнителей.
• Оставляй один слот мастеру.
• Параллельно запускай чтение, независимые исследования и слепые ревью.
• Реализацию и починку одного рабочего дерева выполняй последовательно одним владельцем.