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

Уровни и роли

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

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

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

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

• Управляемая стоимость. Хост видит агентов из ~/.codex/agents или .codex/agents и позволяет выбрать агента по имени. Вызывай именованную роль; модель и глубину рассуждений закрепляй в её TOML-файле. Не наследуй плавающие настройки мастер-сессии для роли с известным бюджетом.
• Неуправляемая стоимость. Интерфейс запуска принимает только задачу и имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана дешёвая или сильная модель. task_name — идентификатор треда, а не выбор конфигурации агента.

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

Выбор уровня

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

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

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