fix(agents): исправлена оркестрация моделей и контекста

- Зачем:
  - следующая сессия должна управлять стоимостью субагентов без повторной загрузки длинных отчётов в контекст мастера.
- Что:
  - разделены TOML-роли и разовые переопределения модели, уточнены fork и service tier.
  - добавлен файловый обмен, жизненный цикл временного каталога и нативные скелеты промптов.
  - синхронизированы полевые заметки и handoff с проверенной механикой Codex.
- Проверка:
  - quick_validate.py agents/.agents/skills/codex-subagent-playbook.
  - git diff --cached --check.
  - независимое ревью: VERDICT: APPROVED.
This commit is contained in:
Dmitry Dementiev committed 2026-07-10 17:59:15 +03:00
1 parent 0d2fc9af65
commit 60182ab493
5 files changed
+249 -57

No files matched your search

@@ -15,13 +15,26 @@ description: Координация одной нетривиальной инж
## Договор делегирования
- Запускай свежих исполнителей без истории мастера (`fork_turns="none"`),
когда среда это поддерживает. Передавай путь к самодостаточному
файлу-задаче, а не пересказ разговора.
- Запускай свежих исполнителей без истории мастера (`fork_turns="none"`).
Если схема `spawn_agent` открывает `agent_type`, `model` и
`reasoning_effort`, выбери один источник истины: для TOML-роли передай
только `agent_type`; для разового выбора передай `model` и
`reasoning_effort` без роли с закреплённой моделью. Полный fork `all`
несовместим с этими переопределениями; плейбук использует `none` ради
чистого контекста. Передавай путь к самодостаточному файлу-задаче, а не
пересказ разговора.
- Давай каждому субагенту одну роль и проверяемый результат. Выбирай самый
дешёвый уровень, который надёжно справится с этой ролью.
дешёвый уровень, который надёжно справится с этой ролью. Если хост скрыл
параметры модели, пометь стоимость как незакреплённую.
- В начале прогона создай один обменный каталог во временном каталоге ОС с
непредсказуемым именем (`mktemp -d` или аналог) и передай агентам его
абсолютный путь. Индекс держи у мастера; длинные отчёты, журналы и
повторно используемые промпты — файлами. Прочитай полезную нагрузку один
раз, дальше передавай путь: аргументы `spawn_agent`, `send_message` и
`followup_task` остаются в истории мастера.
- Проси вернуть только итог, доказательства, вопросы-решения и следующий
шаг. Полные журналы оставляй в `/tmp` или в принятом проектом каталоге.
шаг. Полные журналы оставляй в обменном каталоге. В репозиторий клади
только долговечные артефакты, предусмотренные его правилами.
- Продолжай того же исполнителя для починки его кода. Для независимого
ревью запускай свежий тред.
- Держи одного владельца рабочего дерева. Пока он пишет, другие агенты не
@@ -40,33 +53,20 @@ description: Координация одной нетривиальной инж
При развитии скилла или первом прогоне в новой среде прочитай
[полевые заметки](references/field-notes.md) и проверь открытые предположения.
Точные договоры заданий и результатов бери из нужного раздела
[скелетов нативных промптов](references/prompt-templates.md). Это их
единственный источник; не переписывай форматы в других файлах.
## Формат возврата
Каждому субагенту задай этот договор результата:
```text
ИТОГ: завершено | есть вопросы | заблокировано
ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики
РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь
НАХОДКИ: SEVERITY файл:строка — суть — как проверить
СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет»
```
Пустые разделы пропускаются. Сырой вывод и ход рассуждений в ответ не
включаются.
Для ревьюера замени общий раздел `ИТОГ` на обязательный договор:
```text
ВЕРДИКТ: APPROVED | REVISE
ПОКРЫТИЕ: проверенные области, файлы и команды
ДОКАЗАТЕЛЬСТВА: результаты проверок или воспроизведения
НАХОДКИ: SEVERITY файл:строка — сценарий сбоя — как проверить
```
Пустой индекс принимай только с заполненными покрытием и доказательствами.
Для дорогого ревью попроси также сохранить индекс в `/tmp` и вернуть путь:
сообщение может потеряться после завершения треда.
Если результат понадобится следующему агенту, полный отчёт сначала запиши в
отдельный файл обменного каталога. Финальный ответ ограничь состоянием,
счётчиками, коротким индексом и путём. Для параллельных агентов используй
разные пути. Не возвращай один полный отчёт одновременно файлом и сообщением.
До запуска выбери канал: агент с записью в обменный каталог сохраняет полный
отчёт файлом; `read-only`-агент возвращает короткий индекс один раз
сообщением. Для длинного переиспользуемого отчёта заранее выбери
`workspace-write`, запрети правки исходников и сверь Git до и после.
## Конвейер
@@ -114,21 +114,28 @@ description: Координация одной нетривиальной инж
### 5. Провести слепое ревью
Запусти свежего ревьюера без контекста исполнителя. Для высокого риска
запусти двух ревьюеров параллельно с разными фокусами. Внешнюю модель
подключай дополнительной линией, если она доступна и её стоимость оправдана.
Ревьюеры исследуют и проверяют гипотезы, но возвращают только индекс находок
и не исправляют код.
Создай один канонический файл ревью на всех слепых ревьюеров. Запусти свежего
ревьюера без контекста исполнителя; в `message` передай путь к этому файлу и
выбранный канал результата. Для `workspace-write` добавь уникальный путь
файла, для `read-only` запроси один короткий индекс сообщением. Для высокого
риска запусти двух ревьюеров параллельно с разными фокусами и каналами,
которые не конфликтуют.
Внешнюю модель подключай дополнительной линией, если она доступна и её
стоимость оправдана. Ревьюеры исследуют и проверяют гипотезы, но не
исправляют код. Канал результата выбери по правилам раздела «Формат
возврата»; точный договор — в скелете слепого ревью.
Этап завершён, когда все запрошенные вердикты получены, а рабочее дерево не
содержит неназванных правок.
### 6. Закрыть находки
Дословно передай общий индекс исполнителю этапа 3. Он исправляет находку,
сужает исправление или отклоняет её через контракт, код и проверку. Мастер
проверяет серьёзные и спорные отклонения, решает вопросы объёма и риска.
Исправления отправляй прежнему ревьюеру на узкую повторную проверку.
Продолжи исполнителя этапа 3 и передай пути к исходным индексам без
пересказа. Он исправляет находку, сужает исправление или отклоняет её через
контракт, код и проверку. Мастер проверяет серьёзные и спорные отклонения,
решает вопросы объёма и риска. Исполнитель сохраняет отчёт о решениях
файлом; прежнему ревьюеру передай только путь к нему и запрос на узкую
проверку собственных находок.
Этап завершён, когда по каждой находке записано решение и принятые
исправления перепроверены.
@@ -138,16 +145,22 @@ description: Координация одной нетривиальной инж
Используй отчёт этапа 4. Повтори только проверки, которые обесценили более
поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя
делегировать. Обнови файл-задачу. Коммит делай только по просьбе
пользователя.
пользователя. После завершения всех агентов перенеси нужные долговечные
артефакты по правилам проекта и удали только обменный каталог этого прогона.
Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны,
неназванных изменений нет, а пользователь получил краткий итог.
## Сбои координации
- Агент исчез без отчёта: сначала проверь сохранённый файл, затем один раз
запроси итог. После повторной тишины подними свежего агента с
файлом-задачей и уже собранным индексом.
- После запуска жди через `wait_agent` с реалистичным сроком только когда
результат блокирует следующий шаг. Тайм-аут, idle и сводка об обновлении
не являются результатом; не засоряй историю статусными пингами.
- Агент завершился без отчёта: сначала проверь сохранённый файл, затем один
раз запроси короткий итог через `followup_task`. После повторной тишины
подними свежего агента с файлами задачи и уже собранного индекса.
- При блокировке перенеси нужные для продолжения данные в долговечный
артефакт по правилам проекта и удали остальной обменный каталог прогона.
- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по
договору возврата.
- Два писателя пересеклись: останови их, установи владельца каждой правки и