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-роли:

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

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

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

Не смешивай режимы: роль применяется отдельным слоем конфигурации и может
перекрыть прямые параметры. `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).

## Выбор уровня

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

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

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

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

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