Dmitriy Dementiev
70b18b9e9a
- Зачем: - shell-зависимые примеры и конвейерные формулировки сужали применимость оптики. - Что: - сборка подсказок описана платформенно-нейтральным порядком файлов. - граница ревью и маршрут актуальных отчётов оставлены гибкими. - исправлены входная формулировка и локальная навигация по ролям. - Проверка: - quick_validate.py, git diff --check, Markdown-ссылки и узкая перепроверка агентом.
11 KiB
name, description
| name | description |
|---|---|
| codex-subagent-playbook | Оптика тонкого мастера для одной нетривиальной задачи: как выбирать делегирование, независимую проверку и файловый обмен, сохраняя контекст координатора для решений. |
Тонкий мастер
Это оптика, а не обязательный конвейер. Координатор сохраняет внимание для цели, ограничений, решений, рисков и приёмки. Субагенты выясняют и выполняют; координатор решает.
Основная оптика
- Перед запуском агента назови его вклад: защита контекста, свежий взгляд, специализация, параллельность или отдельная среда. Без вклада работай сам либо продолжай существующий тред.
- Сам читай верхнеуровневые документы и принимай решения. Исследование кода, журналов, зависимостей и вариантов с неизвестным объёмом по умолчанию отдавай субагенту. Самостоятельно проверяй одну узкую гипотезу с коротким выводом; дальнейшее погружение делегируй.
- Держи у себя цель, ограничения, решения, риски, краткие сводки и пути к доказательствам. Полезную нагрузку передавай между агентами файлами, не через контекст координатора.
- Один исполнитель владеет изменениями исходников. Его же продолжай для обычных исправлений. Если исполнитель не справляется, останови его и дай свежему более сильному агенту постановку, текущее дерево и файловые отчёты.
- Выбирай модель и уровень рассуждения независимо. Повышай effort, когда подходящей модели не хватило глубины; повышай модель, когда не хватает качества суждения. Текущая привязка ролей — в уровнях и ролях.
Контекст и обмен
$SCRATCH — логический общий каталог одного прогона, доступный координатору и
назначенным агентам. Физически это скретчпад сессии, временный каталог ОС либо
гарантированно игнорируемый каталог проекта. В нём живут временные промпты,
отчёты, триаж и перепроверки; это не артефакты проекта. Не предполагай
конкретную оболочку или синтаксис пути: файловый маршрут должен работать
нативными средствами текущей ОС.
- Временные обменные файлы веди на английском. Долговечные документы и текст для партнёра пиши на языке проекта.
- Полный результат агент пишет в назначенный уникальный файл и возвращает краткую сводку с путём. Не возвращай тот же полный текст сообщением и не переписывай чужой отчёт: передавай путь или собирай новый файл механически.
- Если общий каталог недоступен, передай через контекст только компактный индекс. Сразу сообщи партнёру наблюдаемый сбой, использованный запасной канал и то, что нужно проверить после задачи.
- Права агента не определяют канал результата. Ревьюер может иметь рабочие права для тестов и временных файлов, но его единственный назначенный результат — отчёт. Исходники, Git и постоянное окружение он не меняет.
Точные способы сборки файлов и промптов бери из нативных шаблонов только после выбора конкретного приёма.
Выбор приёма
- Самодостаточная постановка нужна исполнителю без истории разговора и там, где проекту нужен долговечный след. Для ясной локальной правки хватит короткого мандата.
- Исследователь собирает факты неизвестного объёма. Он возвращает записку решений и пути к доказательствам, а не реализацию.
- Deep-reasoner готовит архитектурное предложение, декомпозицию или сравнение компромиссов. Итоговое решение остаётся у координатора. Важное решение полезно проверить двумя слепыми линиями разных семейств.
- Исполнитель получает одну цель, границы и критерии. Он не коммитит и не расширяет объём без решения координатора.
- Проверяющий запускает известную проверку в специальной среде или с шумным выводом. Не создавай роль, если координатор либо исполнитель может получить тот же надёжный результат дёшево.
Режимы ревью
Для нетривиальной делегируемой постановки один узкий свежий обзор — точка отсчёта. Пропускай его для ясной ограниченной задачи, если можешь коротко назвать причину. Сложную, рискованную или архитектурную постановку проверяй двумя слепыми линиями, когда цена оправдана.
Реализацию проверяй по риску:
- тривиальная — саморевью исполнителя;
- обычная — один независимый ревьюер по коду;
- сложная или рискованная — два адверсариальных ревьюера: соответствие задаче и качество кода.
Разные семейства моделей предпочтительны: они дают больше разнообразия, чем два свежих треда одной родословной. Когда внешняя линия технически недоступна, используй доступных ревьюеров; процесс от неё не зависит.
Выбрав ревью постановки или реализации, прочитай единый договор ревью и триажа. Он определяет владельца триажа, файловый канал, повторные проверки и предохранитель кругов.
Приёмка
Координатор принимает результат, но углубляется в доказательства постепенно:
- состав изменений и краткие сводки ревью;
- отдельные спорные фрагменты;
- полный diff, только когда его объём ограничен и чтение нужно для решения.
Доступную детерминированную финальную проверку запускай сам с выводом в файл. В контекст возьми точную команду, код возврата, итоговые счётчики, имена упавших тестов и путь к журналу. Зелёный журнал не читай. Красный журнал направь исполнителю или отдельному разборщику; сам открывай детали, когда они нужны для решения о границах, риске, среде или смене исполнителя. Если проверка доступна только проверяющему в специальной среде, явно назови свидетельство косвенным.
Перед завершением:
- сопоставь результат с исходной целью и назови всё неподтверждённое;
- убедись, что выбранная независимая проверка завершена либо риск принят полномочным решением;
- дай партнёру короткую саморефлексию: что больше всего потратило контекст, оправдана ли трата, что в следующий раз направить через файл или субагента, какие отклонения процесса произошли.
Новый урок для эмпирики только предложи партнёру. Правь долговечную эмпирику после его согласия.
Сбои координации
- Нет ожидаемого файла: один раз запроси короткий итог в том же треде; после повторной тишины продолжи свежим агентом от сохранённых артефактов.
- Длинный рассказ пришёл сообщением: попроси повторить ответ сводкой и путём, не переноси рассказ дальше.
- Два исполнителя пересеклись в исходниках: останови их, установи одного владельца и продолжи от проверенного состояния без отката чужих правок.
- Процесс не сходится: используй точки вмешательства из договора ревью, объясни партнёру причину, стоимость и принятое решение.
- После завершения сохрани только предусмотренные проектом долговечные решения и удали временные артефакты именно этого прогона.