Dmitry Dementiev
4d074adda6
- Зачем: - нужен повторяемый процесс делегирования без засорения контекста мастер-модели. - Что: - добавлен явно вызываемый скилл с этапами, договорами возврата и защитой рабочего дерева. - описаны роли, уровни стоимости, полевые заметки и handoff для следующей версии. - Проверка: - quick_validate.py agents/.agents/skills/codex-subagent-playbook. - git diff --cached --check.
135 lines
8.4 KiB
Markdown
135 lines
8.4 KiB
Markdown
# Уровни и роли
|
|
|
|
Читай этот файл только при настройке ролей или когда нужная роль недоступна.
|
|
Сам конвейер описан в `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`.
|
|
Минимальный шаблон:
|
|
|
|
```toml
|
|
name = "role-name"
|
|
description = "Когда координатору выбирать эту роль."
|
|
model = "<актуальная модель нужного уровня>"
|
|
model_reasoning_effort = "medium"
|
|
sandbox_mode = "read-only"
|
|
developer_instructions = """
|
|
Одна узкая роль и её договор результата.
|
|
"""
|
|
```
|
|
|
|
Не подменяй выбор роли совпадением `task_name` с её именем: это работает
|
|
только при явной гарантии хоста.
|
|
|
|
## Пределы параллельности
|
|
|
|
- Держи глубину `1`: субагенты не создают собственное дерево исполнителей.
|
|
- Оставляй один слот мастеру.
|
|
- Параллельно запускай чтение, независимые исследования и слепые ревью.
|
|
- Реализацию и починку одного рабочего дерева выполняй последовательно одним
|
|
владельцем.
|