diff --git a/agents/.agents/skills/codex-subagent-playbook/SKILL.md b/agents/.agents/skills/codex-subagent-playbook/SKILL.md index 67703a5..a350760 100644 --- a/agents/.agents/skills/codex-subagent-playbook/SKILL.md +++ b/agents/.agents/skills/codex-subagent-playbook/SKILL.md @@ -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`. После повторной тишины + подними свежего агента с файлами задачи и уже собранного индекса. +- При блокировке перенеси нужные для продолжения данные в долговечный + артефакт по правилам проекта и удали остальной обменный каталог прогона. - Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по договору возврата. - Два писателя пересеклись: останови их, установи владельца каждой правки и diff --git a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md index b101d53..6538bc1 100644 --- a/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md +++ b/agents/.agents/skills/codex-subagent-playbook/handoffs/20260710-1643-first-version.md @@ -11,12 +11,15 @@ Codex и проверит полный конвейер на боевой зад - выбор ролей и уровней — [`../references/roles.md`](../references/roles.md); - перенесённые уроки и открытые проверки — [`../references/field-notes.md`](../references/field-notes.md); +- точные договоры нативных агентов — + [`../references/prompt-templates.md`](../references/prompt-templates.md); - явный вызов скилла — [`../agents/openai.yaml`](../agents/openai.yaml). -Нативные TOML-роли ещё не созданы. В текущем интерфейсе `spawn_agent` роль, -модель и глубина рассуждений не выбираются явно, поэтому первый пробный -прогон использовал роли только как мандаты в промпте и честно пометил -стоимость как неуправляемую. +Нативные TOML-роли ещё не созданы. В интерфейсе пробной tool-backed сессии +хост скрыл поля `agent_type`, `model`, `reasoning_effort` и `service_tier`, +поэтому прогон использовал роли только как мандаты в промпте и честно +пометил стоимость как неуправляемую. Это не общее ограничение Codex: +нативная схема поддерживает все четыре поля. ## Принятые решения @@ -27,9 +30,20 @@ Codex и проверит полный конвейер на боевой зад `policy.allow_implicit_invocation: false` в `openai.yaml`. - Модели закрепляются в файлах ролей, а не в `SKILL.md`, чтобы процесс не зависел от смены модельной линейки. +- Для TOML-роли передаётся `agent_type`; для разового выбора — `model` и + `reasoning_effort` без роли с закреплённой моделью. Плейбук использует + `fork_turns="none"` ради чистого контекста; полный fork `all` наследует + модель мастера. - Один агент владеет рабочим деревом. До записи сохраняется точка отсчёта, включая хэши неотслеживаемых файлов. -- Критичный отчёт ревьюера возвращается сообщением и сохраняется в `/tmp`. +- Полный отчёт ревьюера сохраняется файлом; сообщение содержит только + вердикт, счётчики и путь. `read-only`-ревьюер возвращает короткий индекс + один раз сообщением. +- На прогон создаётся один обменный временный каталог. Полные отчёты и + повторно используемые промпты передаются между агентами путями; мастер не + вставляет их повторно в tool-call. +- После завершения или сохранения блокирующего handoff обменный каталог + этого прогона удаляется. - Нативный конвейер не зависит от вложенного запуска `codex exec`. ## Что проверено @@ -58,9 +72,15 @@ Codex и проверит полный конвейер на боевой зад проверить смысловые договоры ролей, повторную установку, стороннюю роль и конфликт совпадающего имени. 6. Проверить обнаружение ролей установленным Codex CLI в отдельном - `CODEX_HOME`. Синтаксический разбор TOML не доказывает поддержку схемы. + `CODEX_HOME`. Затем начать новую сессию и проверить, что её схема + `spawn_agent` открывает `agent_type`, `model`, `reasoning_effort` и + `service_tier`. + Синтаксический разбор TOML не доказывает поддержку схемы. 7. Прогнать этапы 3–7 на подходящей задаче, обновить полевые заметки только подтверждёнными фактами и убрать поглощённый осадок. +8. Измерить, сколько длинных отчётов реально попало в контекст мастера. + Цель — каждый полный артефакт читается не более одного раза и больше не + пересказывается между агентами. ## Известные ловушки @@ -71,8 +91,15 @@ Codex и проверит полный конвейер на боевой зад от сохранённой точки отсчёта, не очищать и не включать их в коммиты. - `task_name` нативного `spawn_agent` — имя треда, а не доказанный выбор пользовательской конфигурации агента. +- Полный fork `all` несовместим с другой ролью, моделью и глубиной. Плейбук + использует `none` для свежего контекста; ограниченный fork числом + технически допускает переопределения. +- Некоторые tool-backed хосты скрывают поля управления моделью, хотя Codex + их поддерживает. Проверять фактическую схему в начале сессии. - Права `workspace-write` не гарантируют сеть. Проверку документации и поиск отмечать как непроверенные, если сеть недоступна. +- Длинный текст в `spawn_agent`, `send_message` или `followup_task` остаётся + в истории мастера. Передавать путь к файлу и короткий вопрос. ## Suggested skills diff --git a/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md b/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md index 3f81b90..478a633 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/field-notes.md @@ -25,7 +25,7 @@ ## Проверить боем 1. Выбирает ли текущий хост пользовательского агента по имени и показывает ли - фактически использованную модель. + фактически использованную модель после запуска новой сессии с TOML. 2. Даёт ли набор быстрых ролей экономию без повторной работы сильной модели. 3. Остаётся ли дерево неизменным после ревьюера с `workspace-write`. 4. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях. @@ -38,10 +38,36 @@ - Мастер без истории исходного плейбука поднял исследователя и ревьюера, свёл их вывод в самодостаточную постановку и не вынес сырые журналы в итоговый контекст. -- Доступный `spawn_agent` не позволил закрепить пользовательскую роль, - модель или стоимость. Роли были только мандатами в промпте; мастер честно - отметил неуправляемую стоимость. +- Конкретный tool-backed хост скрыл из схемы `spawn_agent` поля `agent_type`, + `model`, `reasoning_effort` и `service_tier`. Это ограничение той сессии, + а не Codex в целом: актуальная нативная схема поддерживает все четыре поля. + Роли в прогоне были только мандатами в промпте; мастер верно отметил + стоимость той сессии как неуправляемую. - Исследователь обнаружил блокирующее правило `.gitignore` для будущих TOML, которое мастер без шумного обхода репозитория мог пропустить. - Исследователь без необходимости запустил полный набор тестов. Ограничение «карта команд, а не полный прогон» поглощено в `SKILL.md` и `roles.md`. + +## 2026-07-10 — проверка документации и исходного кода Codex + +- Нативный `spawn_agent` принимает `agent_type`, `model`, + `reasoning_effort` и `service_tier`. +- Полный fork `all` наследует модель мастера и отклоняет роль, модель и + глубину. Плейбук выбирает `none` ради чистого контекста; ограниченный fork + числом технически совместим с переопределениями. +- Хост может намеренно скрыть эти поля из видимой схемы. В такой сессии + мастер не может гарантировать стоимость через нативный вызов. +- TOML-роли остаются правильным способом закрепить модель и глубину. После + их установки нужна новая сессия и проверка фактической схемы инструмента. +- `service_tier` не блокируется полным fork, но задаётся только по явному + запросу. + +## 2026-07-10 — ретро утечки контекста прародителя + +- Главная утечка была не в работе агентов, а в повторной передаче одного + текста через мастера: отчёт, новый промпт, повторная проверка и tool-call. +- Нативный Codex не наследует буквально поведение Claude `SendMessage`, но + длинные аргументы `spawn_agent`, `send_message` и `followup_task` всё равно + остаются в истории мастера. +- Лечение поглощено в `SKILL.md` и `prompt-templates.md`: файловый канал, + один канонический промпт и ожидание только на критическом пути. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md b/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md new file mode 100644 index 0000000..da3c567 --- /dev/null +++ b/agents/.agents/skills/codex-subagent-playbook/references/prompt-templates.md @@ -0,0 +1,87 @@ +# Скелеты нативных промптов + +Читай только тот раздел, который нужен на текущем этапе. Полный текст +задания и отчёта живёт в обменном временном каталоге; вызов агента содержит +короткую обёртку с абсолютными путями. + +## Общий договор результата + +Полный отчёт, независимо от канала: + +```text +ИТОГ: завершено | есть вопросы | заблокировано +ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики +РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь +НАХОДКИ: SEVERITY файл:строка — суть — как проверить +СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет» +``` + +Пустые разделы пропускаются. Сырой вывод и ход рассуждений не включаются. +При файловом канале этот договор заполняется в файле, а финальное сообщение +содержит только `ИТОГ`, счётчики и `АРТЕФАКТ: абсолютный путь`. При +`read-only` договор возвращается один раз сообщением без поля `АРТЕФАКТ`. + +## Исполнитель + +Файл задачи должен содержать: + +```text +ЦЕЛЬ: одна проверяемая цель +КРИТЕРИИ: исчерпывающий список +ГРАНИЦЫ: разрешённые и запрещённые изменения +СНАЧАЛА ПРОЧИТАТЬ: пути к контрактам и образцам +ПРОВЕРКИ: узкие команды разработки +ОТЧЁТ: отдельный путь в обменном каталоге +``` + +Короткий вызов: прочитать файл задачи и выполнить буквально. Агент с записью +в обменный каталог сохраняет полный отчёт по заданному пути и финальным +сообщением возвращает состояние, счётчики и путь. `read-only`-агент +возвращает короткий результат один раз сообщением. Коммит не делать. + +## Слепое ревью + +Один канонический файл на всех ревьюеров: + +```text +АРТЕФАКТ: задача и изменённый объём +ФОКУС: корректность, контракт, краевые случаи, честность тестов +МАНДАТ: исследовать и проверять гипотезы, исходники не исправлять +ФОРМАТ: severity, файл:строка, сценарий сбоя, доказательство, проверка +ВЕРДИКТ: APPROVED | REVISE +``` + +Вызов каждого ревьюера добавляет только его фокус и канал результата: + +- `workspace-write`: уникальный путь файла; финальное сообщение — вердикт, + счётчики по severity и путь; исходники не менять, Git сверить до и после; +- `read-only`: короткий индекс один раз финальным сообщением, без требования + записать файл. + +## Закрытие находок + +Исполнителю передаются пути к исходным индексам ревью и такой короткий +мандат: + +```text +По каждой находке: исправить, сузить или отклонить через контракт и проверку. +Не менять соседний объём. Полный отчёт решений записать по указанному пути. +Финальным сообщением вернуть счётчики, проверки и путь. +``` + +Не переписывай находки в сообщение или новый файл: исходные индексы уже +являются неизменяемым входом. + +## Узкая перепроверка + +Прежнему ревьюеру передаются путь к его исходному индексу и путь к отчёту +решений исполнителя: + +```text +Проверь только прежние находки и новые правки рядом с ними. +По каждой: CLOSED | NOT_CLOSED | REJECTION_VALID | REJECTION_INVALID. +Полный повторный обход не выполнять. +``` + +Финальное сообщение: `ALL_CLOSED` или `ISSUES_REMAIN`, счётчики и путь к +файлу перепроверки. diff --git a/agents/.agents/skills/codex-subagent-playbook/references/roles.md b/agents/.agents/skills/codex-subagent-playbook/references/roles.md index ff427c7..8ad15af 100644 --- a/agents/.agents/skills/codex-subagent-playbook/references/roles.md +++ b/agents/.agents/skills/codex-subagent-playbook/references/roles.md @@ -15,9 +15,13 @@ и его конфигурацию. - **Управляемая стоимость.** Хост видит агентов из `~/.codex/agents` или - `.codex/agents` и позволяет выбрать агента по имени. Вызывай именованную - роль; модель и глубину рассуждений закрепляй в её TOML-файле. Не наследуй - плавающие настройки мастер-сессии для роли с известным бюджетом. + `.codex/agents` и схема `spawn_agent` открывает `agent_type`, `model` и + `reasoning_effort`. Для TOML-роли передавай `agent_type`, а модель и + глубину бери из её файла. Для разового выбора передавай `model` и + `reasoning_effort` без пользовательской роли с закреплённой моделью. + Плейбук использует `fork_turns="none"` ради чистого контекста. Технически + ограниченный fork числом тоже допускает переопределения; только полный + fork `all` наследует модель мастера и отклоняет их. - **Неуправляемая стоимость.** Интерфейс запуска принимает только задачу и имя треда. Передавай роль мандатом в промпте, но не утверждай, что выбрана дешёвая или сильная модель. `task_name` — идентификатор треда, а не выбор @@ -26,6 +30,38 @@ Если способ выбора роли не виден в доступном инструменте, считай стоимость неуправляемой и отметь это в итоговом отчёте. +Вызов 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). + ## Выбор уровня | Уровень | Для чего | Настройка | @@ -97,6 +133,8 @@ `workspace-write`, запретить правки исходников мандатом и сверить Git до и после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и доступ к документации. Непроверенную внешнюю механику отмечать как гипотезу. +Для длинного или повторно используемого индекса нужен доступ на запись в +обменный каталог; иначе вернуть короткий индекс один раз сообщением. ### `verifier` @@ -123,7 +161,8 @@ developer_instructions = """ ``` Не подменяй выбор роли совпадением `task_name` с её именем: это работает -только при явной гарантии хоста. +только при явной гарантии хоста. После добавления или изменения TOML начни +новую сессию и проверь, что имя роли появилось в описании `agent_type`. ## Пределы параллельности