refactor(skill): плейбук возвращён к оптике тонкого мастера
- Зачем: - субагенты должны сохранять внимание мастера и помогать результату, а не обслуживать обязательный конвейер. - Что: - семиступенчатый процесс заменён эвристиками выбора исполнителя, проверяющего и независимого ревьюера. - права агентов отделены от канала результата, а полная полезная нагрузка выведена из контекста мастера. - добавлены авторитетные договоры промптов, полевые заметки и handoff следующей сессии. - Проверка: - git diff --cached --check. - свежий обзор через writing-great-skills, все принятые находки закрыты.
This commit is contained in:
ddadmin committed
1 parent
7110a075ea
commit
f9ea5b8c44
10 files changed
+344
-290
No files matched your search
@@ -1,169 +1,132 @@
|
||||
---
|
||||
name: codex-subagent-playbook
|
||||
description: Координация одной нетривиальной инженерной задачи через субагентов с сохранением чистого контекста мастера.
|
||||
description: Оптика тонкого мастера для одной нетривиальной задачи: субагенты сохраняют контекст и приносят нужную независимость.
|
||||
---
|
||||
|
||||
# Тонкий мастер
|
||||
|
||||
Ты — координатор. Держи в своём контексте цель, ограничения, решения и
|
||||
индекс находок. Исследование, реализацию, проверки, журналы и полный diff
|
||||
отдавай субагентам. Внешний агент полезен как дополнительная независимая
|
||||
линия, но процесс не должен от него зависеть.
|
||||
Это оптика работы, а не обязательный конвейер. Цель — решить одну
|
||||
нетривиальную задачу, сохранив внимание мастера для цели, ограничений,
|
||||
решений и рисков. Субагенты нужны результату, а не процессу.
|
||||
|
||||
Применяй конвейер к одной нетривиальной задаче. Если работа локальна, вывод
|
||||
короток и ошибка дёшева, сообщи о лишних накладных расходах и сделай её сам.
|
||||
Тонкий мастер не пустой мастер. Он сам принимает решения, делает дешёвые
|
||||
точечные проверки и смотрит ключевые артефакты. Исследование, реализацию или
|
||||
проверку он отдаёт только тогда, когда отдельный контекст даст задаче
|
||||
конкретное преимущество.
|
||||
|
||||
## Договор делегирования
|
||||
## Основная оптика
|
||||
|
||||
- Запускай свежих исполнителей без истории мастера (`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` остаются в истории мастера.
|
||||
- Проси вернуть только итог, доказательства, вопросы-решения и следующий
|
||||
шаг. Полные журналы оставляй в обменном каталоге. В репозиторий клади
|
||||
только долговечные артефакты, предусмотренные его правилами.
|
||||
- Продолжай того же исполнителя для починки его кода. Для независимого
|
||||
ревью запускай свежий тред.
|
||||
- Держи одного владельца рабочего дерева. Пока он пишет, другие агенты не
|
||||
читают это дерево. Параллель разрешай только для неизменяемых входов или
|
||||
отдельных worktree.
|
||||
- До писателя сохрани в `/tmp` машинно читаемую точку отсчёта: статус,
|
||||
полный staged/unstaged diff, а также перечень и хэши неотслеживаемых
|
||||
файлов. После него сравни новое состояние с точкой отсчёта и отчётом. Не
|
||||
удаляй и не откатывай чужие изменения.
|
||||
- Сообщай пользователю короткий статус на границах этапов.
|
||||
- Перед каждым запуском ответь: что этот агент добавит — защиту контекста,
|
||||
свежий взгляд, специализацию, параллельность или отдельную среду проверки?
|
||||
Если ничего, работай сам или продолжи существующий тред.
|
||||
- Держи у мастера короткий индекс: цель, ограничения, принятые решения,
|
||||
риски, вердикты и доказательства, влияющие на следующий шаг. Полные diff,
|
||||
журналы и нарративы ему не нужны.
|
||||
- Исследование с неизвестным или шумным объёмом делегируй до погружения.
|
||||
Одну узкую гипотезу с предсказуемо короткой командой мастер может проверить
|
||||
сам; если ответа нет, продолжение уходит агенту.
|
||||
- Свежий тред даёт независимость от исполнителя, но не разнообразие ошибок.
|
||||
Другое семейство моделей даёт отдельную линию; второй агент того же
|
||||
семейства оправдан только высоким риском или действительно иным фокусом.
|
||||
- Выбирай самый дешёвый надёжный уровень для выбранной работы. Если хост не
|
||||
показывает модель и глубину, считай стоимость незакреплённой и не умножай
|
||||
совместимые роли без явной пользы.
|
||||
- Один исполнитель владеет изменениями исходников. Его же продолжай для
|
||||
исправлений; независимую оценку отдавай свежему треду. Права
|
||||
`workspace-write` сами по себе не делают агента владельцем исходников.
|
||||
|
||||
Если нужные роли ещё не настроены или надо выбрать модели, прочитай
|
||||
[уровни и роли](references/roles.md). Не загружай этот справочник в обычном
|
||||
прогоне с уже настроенными ролями.
|
||||
Внешняя модель полезна как дополнительная линия, когда её родословная и цена
|
||||
оправданы риском. Процесс не должен от неё зависеть.
|
||||
|
||||
## Контекст и обмен
|
||||
|
||||
- Если результат понадобится следующему агенту, полный отчёт запиши в
|
||||
уникальный файл временного обменного каталога. Мастеру верни только итог,
|
||||
счётчики, вопросы-решения и путь. Короткий конечный результат можно вернуть
|
||||
одним сообщением.
|
||||
- Канал результата не связан с правами агента. Ревьюеру можно дать рабочие
|
||||
права для тестов, кэшей, поиска и документации, а запрет менять исходники и
|
||||
постоянное окружение удерживать мандатом и сверкой Git до и после.
|
||||
- Не возвращай один полный отчёт одновременно файлом и сообщением. Не
|
||||
переписывай находки между файлами: передавай исходный путь или собирай новый
|
||||
промпт механической конкатенацией.
|
||||
- Не выводи в контекст мастера полную точку отсчёта, diff, перечень хэшей или
|
||||
сырой журнал. Если дерево грязное или возможны пересечения, порученный
|
||||
агент либо готовый скрипт сохраняет подробности во временный файл и сообщает
|
||||
только состояние, счётчики, пересечение с разрешённым объёмом и путь.
|
||||
- Временные обменные файлы веди на английском. Долговечные документы и текст
|
||||
для пользователя пиши на языке проекта.
|
||||
- Сообщай пользователю короткий статус на действительно значимых границах, а
|
||||
не на каждом служебном переходе. Тайм-аут и `idle` не являются результатом.
|
||||
|
||||
## Когда какой приём полезен
|
||||
|
||||
- **Самодостаточная постановка** нужна, когда исполнитель начинает без истории
|
||||
разговора или проекту важен долговечный след. Для локальной ясной правки
|
||||
достаточно короткого мандата.
|
||||
- **Исследователь** нужен для неизвестного объёма, внешних фактов или шумного
|
||||
обхода репозитория. Его результат — факты и вопросы, не реализация.
|
||||
- **Ревью постановки** окупается при скрытых проектных решениях, дорогой ошибке
|
||||
или критериях, которые можно выполнить формально без нужного результата.
|
||||
- **Исполнитель** нужен, когда отдельный контекст реализации ценнее прямой
|
||||
работы мастера. Он не коммитит и не расширяет объём без решения мастера.
|
||||
- **Проверяющий** нужен для шумных журналов, специальной среды, стенда или
|
||||
независимого подтверждения команд. Не создавай отдельную роль, если те же
|
||||
проверки дёшево и надёжно выполняет исполнитель либо ревьюер.
|
||||
- **Свежий ревьюер** нужен, когда цена пропущенного дефекта выше стоимости
|
||||
обзора. По умолчанию достаточно одного. Вторую линию добавляй ради другого
|
||||
семейства моделей или отдельного класса риска, а не ради числа два.
|
||||
|
||||
## Типичный ход задачи
|
||||
|
||||
Часто полезно уточнить постановку, дать одному исполнителю реализовать её,
|
||||
проверить обязательные свойства и при заметном риске получить свежий обзор.
|
||||
Пропускай, объединяй и меняй порядок этих действий, если так надёжнее и
|
||||
дешевле достигается результат.
|
||||
|
||||
- Перед реализацией разреши продуктовые, архитектурные и относящиеся к
|
||||
границам решения вне мандата исполнителя. Технический способ внутри мандата
|
||||
оставь ему.
|
||||
- Пока исполнитель меняет исходники, не запускай другого владельца тех же
|
||||
файлов. Параллель разрешай для независимых неизменяемых входов, отдельных
|
||||
worktree или команд без общего изменяемого состояния.
|
||||
- Обязательные и доступные сквозные проверки должны пройти до финальной
|
||||
приёмки. Недоступную или падающую проверку нельзя молча превратить в зелёную:
|
||||
риск принимает пользователь либо полномочие, заранее записанное в задаче.
|
||||
- Ревьюеру дай задачу, изменённый объём, проверки и один выбранный фокус. Он
|
||||
исследует и проверяет гипотезы, но не исправляет исходники. Вердикт без
|
||||
находок должен назвать просмотренный объём и выполненные проверки либо
|
||||
проверенные гипотезы.
|
||||
- Находки возвращай тому же исполнителю. Он исправляет или аргументированно
|
||||
отклоняет их через контракт и проверку. Исходный ревьюер при необходимости
|
||||
узко проверяет свои находки; новый соседний дефект не скрывает.
|
||||
- На финале мастер смотрит только решения, остаточные риски, итоговые счётчики
|
||||
и действительно ключевые артефакты. Полный diff и отчёты читают агенты,
|
||||
которым поручена их проверка. Коммит делай только по просьбе пользователя.
|
||||
|
||||
## Нативные договоры
|
||||
|
||||
Если нужны готовые роли или выбор моделей, прочитай
|
||||
[уровни и роли](references/roles.md). Если роли не настроены, не имитируй
|
||||
экономию названиями: честно отметь незакреплённую стоимость.
|
||||
|
||||
Когда выбран конкретный приём, возьми только его договор из
|
||||
[сборки нативных промптов](references/prompt-templates.md). Не загружай все
|
||||
шаблоны заранее и не переписывай их текст в вызов агента.
|
||||
|
||||
При развитии скилла или первом прогоне в новой среде прочитай
|
||||
[полевые заметки](references/field-notes.md) и проверь открытые предположения.
|
||||
|
||||
Точные договоры заданий и результатов бери из нужного раздела
|
||||
[скелетов нативных промптов](references/prompt-templates.md). Это их
|
||||
единственный источник; не переписывай форматы в других файлах.
|
||||
|
||||
## Формат возврата
|
||||
|
||||
Если результат понадобится следующему агенту, полный отчёт сначала запиши в
|
||||
отдельный файл обменного каталога. Финальный ответ ограничь состоянием,
|
||||
счётчиками, коротким индексом и путём. Для параллельных агентов используй
|
||||
разные пути. Не возвращай один полный отчёт одновременно файлом и сообщением.
|
||||
До запуска выбери канал: агент с записью в обменный каталог сохраняет полный
|
||||
отчёт файлом; `read-only`-агент возвращает короткий индекс один раз
|
||||
сообщением. Для длинного переиспользуемого отчёта заранее выбери
|
||||
`workspace-write`, запрети правки исходников и сверь Git до и после.
|
||||
|
||||
## Конвейер
|
||||
|
||||
### 1. Зафиксировать задачу
|
||||
|
||||
Создай или уточни принятый проектом файл-задачу: цель, критерии приёмки,
|
||||
границы, решения, что прочитать и команды проверки. Шумное исследование
|
||||
репозитория отдай быстрому исследователю. Он находит команды, но не запускает
|
||||
полный набор; узкую проверку выполняет только для подтверждения нужного
|
||||
факта. Если задача ссылается на другой скилл, продублируй его ключевые
|
||||
требования текстом: исполнитель может не подхватить скилл автоматически.
|
||||
|
||||
Этап завершён, когда исполнитель может начать без истории разговора и без
|
||||
уточняющих вопросов.
|
||||
|
||||
### 2. Проверить постановку
|
||||
|
||||
Для сложной или дорогой ошибки отдай постановку свежему сильному ревьюеру.
|
||||
Попроси проверить её против реального кода: выполнимость, скрытые решения,
|
||||
пропущенные критерии и способы формально отчитаться без нужного результата.
|
||||
Для особенно дорогой ошибки используй два слепых ревью.
|
||||
|
||||
Внеси в файл-задачу решение по каждой находке: принять, сузить или отклонить
|
||||
с доводом.
|
||||
|
||||
Этап завершён, когда у каждой находки есть записанное решение.
|
||||
|
||||
### 3. Реализовать
|
||||
|
||||
Передай задачу отдельному исполнителю с правом записи. Мандат: следовать
|
||||
файлу-задаче, не делать коммит, не менять соседний объём. Исполнитель
|
||||
запускает только узкие проверки разработки; полный набор остаётся этапу 4.
|
||||
|
||||
Этап завершён, когда отчёт исполнителя соответствует изменённому дереву и
|
||||
все критерии либо выполнены, либо явно помечены как заблокированные.
|
||||
|
||||
### 4. Переварить проверки
|
||||
|
||||
Отдай быстрому проверяющему тесты, линтеры, сборку и объёмные журналы. Пусть
|
||||
он вернёт команды, счётчики, короткую причину каждого сбоя и путь к полному
|
||||
журналу. Исправления возвращай исполнителю этапа 3.
|
||||
|
||||
Этап завершён, когда полный обязательный набор прошёл после последней правки
|
||||
или каждый оставшийся сбой объяснён и принят пользователем.
|
||||
|
||||
### 5. Провести слепое ревью
|
||||
|
||||
Создай один канонический файл ревью на всех слепых ревьюеров. Запусти свежего
|
||||
ревьюера без контекста исполнителя; в `message` передай путь к этому файлу и
|
||||
выбранный канал результата. Для `workspace-write` добавь уникальный путь
|
||||
файла, для `read-only` запроси один короткий индекс сообщением. Для высокого
|
||||
риска запусти двух ревьюеров параллельно с разными фокусами и каналами,
|
||||
которые не конфликтуют.
|
||||
Внешнюю модель подключай дополнительной линией, если она доступна и её
|
||||
стоимость оправдана. Ревьюеры исследуют и проверяют гипотезы, но не
|
||||
исправляют код. Канал результата выбери по правилам раздела «Формат
|
||||
возврата»; точный договор — в скелете слепого ревью.
|
||||
|
||||
Этап завершён, когда все запрошенные вердикты получены, а рабочее дерево не
|
||||
содержит неназванных правок.
|
||||
|
||||
### 6. Закрыть находки
|
||||
|
||||
Продолжи исполнителя этапа 3 и передай пути к исходным индексам без
|
||||
пересказа. Он исправляет находку, сужает исправление или отклоняет её через
|
||||
контракт, код и проверку. Мастер проверяет серьёзные и спорные отклонения,
|
||||
решает вопросы объёма и риска. Исполнитель сохраняет отчёт о решениях
|
||||
файлом; прежнему ревьюеру передай только путь к нему и запрос на узкую
|
||||
проверку собственных находок.
|
||||
|
||||
Этап завершён, когда по каждой находке записано решение и принятые
|
||||
исправления перепроверены.
|
||||
|
||||
### 7. Принять результат
|
||||
|
||||
Используй отчёт этапа 4. Повтори только проверки, которые обесценили более
|
||||
поздние правки. Сам проверь ключевые артефакты и решения, которые нельзя
|
||||
делегировать. Обнови файл-задачу. Коммит делай только по просьбе
|
||||
пользователя. После завершения всех агентов перенеси нужные долговечные
|
||||
артефакты по правилам проекта и удали только обменный каталог этого прогона.
|
||||
|
||||
Этап завершён, когда критерии приёмки закрыты, финальные счётчики известны,
|
||||
неназванных изменений нет, а пользователь получил краткий итог.
|
||||
[полевые заметки](references/field-notes.md) и проверь живые предположения.
|
||||
|
||||
## Сбои координации
|
||||
|
||||
- После запуска жди через `wait_agent` с реалистичным сроком только когда
|
||||
результат блокирует следующий шаг. Тайм-аут, idle и сводка об обновлении
|
||||
не являются результатом; не засоряй историю статусными пингами.
|
||||
- Агент завершился без отчёта: сначала проверь сохранённый файл, затем один
|
||||
раз запроси короткий итог через `followup_task`. После повторной тишины
|
||||
подними свежего агента с файлами задачи и уже собранного индекса.
|
||||
- При блокировке перенеси нужные для продолжения данные в долговечный
|
||||
артефакт по правилам проекта и удали остальной обменный каталог прогона.
|
||||
- Агент вернул длинный рассказ: не тащи его дальше. Попроси повторить ответ по
|
||||
договору возврата.
|
||||
- Два писателя пересеклись: останови их, установи владельца каждой правки и
|
||||
продолжи одним исполнителем от проверенной точки отсчёта.
|
||||
- Находки не становятся слабее по раундам: останови цикл и вынеси пользователю
|
||||
противоречие или неверно выбранную границу задачи.
|
||||
- Агент завершился без ожидаемого файла: один раз запроси короткий итог в том
|
||||
же треде; после повторной тишины продолжи свежим агентом от сохранённых
|
||||
артефактов.
|
||||
- Агент вернул длинный рассказ в сообщение: попроси повторить ответ индексом и
|
||||
путём, не переноси рассказ дальше.
|
||||
- Два исполнителя пересеклись в исходниках: останови их, установи одного
|
||||
владельца и продолжи от проверенного состояния, не откатывая чужие правки.
|
||||
- Находки не становятся слабее по раундам: если аргументы исчерпаны, вынеси
|
||||
пользователю противоречие, риск или неверную границу задачи.
|
||||
- После завершения сохрани только предусмотренные проектом долговечные
|
||||
решения и удали временные артефакты именно этого прогона.
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
# Handoff: плейбук возвращён к оптике тонкого мастера
|
||||
|
||||
Дата: 2026-07-12. Для следующей сессии, которая проверит обновлённый скилл на
|
||||
нетривиальной задаче с кодом, тестами и шумным выводом.
|
||||
|
||||
## Состояние
|
||||
|
||||
Скилл переработан после самоприменения и сравнения с
|
||||
`claude-subagent-playbook`. Текущий источник поведения —
|
||||
[`../SKILL.md`](../SKILL.md); это набор приёмов, а не обязательный конвейер.
|
||||
Нативная механика раскрывается только по выбранной ветке через
|
||||
[`../references/prompt-templates.md`](../references/prompt-templates.md) и
|
||||
[`../references/roles.md`](../references/roles.md).
|
||||
|
||||
Факты двух прогонов и ещё непроверенные предположения дистиллированы в
|
||||
[`../references/field-notes.md`](../references/field-notes.md). Не переносить
|
||||
их обратно в основной файл без нового наблюдаемого сбоя.
|
||||
|
||||
Ключевая граница следующей работы: субагент запускается ради конкретной пользы
|
||||
задаче или контексту мастера. Свежий тред не считается второй независимой
|
||||
родословной. Права агента не определяют канал результата. Полная полезная
|
||||
нагрузка не должна проходить через контекст мастера.
|
||||
|
||||
## Что проверено
|
||||
|
||||
- Один свежий обзор проверил переработку через оптику `writing-great-skills` и
|
||||
исходного Claude-плейбука; все принятые находки закрыты, одно предложение
|
||||
вернуть `read-only` обоснованно отклонено по принятой практике пользователя.
|
||||
- `git diff --check` проходит.
|
||||
- Относительные ссылки и сборка промптов проверялись в ходе итераций; найден и
|
||||
исправлен пропущенный путь отчёта триажа.
|
||||
- Посторонние неотслеживаемые скиллы в объём не входят.
|
||||
|
||||
## Следующая сессия
|
||||
|
||||
1. Выбрать одну подходящую задачу с кодом; не создавать искусственный полный
|
||||
прогон ради проверки скилла.
|
||||
2. До каждого запуска агента записывать ожидаемую отдельную пользу, после —
|
||||
сверить её с фактическим вкладом.
|
||||
3. Измерить только мастерский след: какие полные отчёты или diff всё ещё попали
|
||||
в его контекст, сколько агентов можно было не запускать.
|
||||
4. Проверить живые предположения из `references/field-notes.md`: управляемость
|
||||
ролей и стоимости, `workspace-write`-ревью, сеть и файловый канал.
|
||||
5. Менять скилл только по фактам прогона; дистиллировать поглощённые уроки.
|
||||
|
||||
## Suggested skills
|
||||
|
||||
- `$codex-subagent-playbook` — провести выбранную задачу с новой оптикой.
|
||||
- `$writing-great-skills` — проверить, что новые уроки не вернули каркас,
|
||||
дублирование или осадок.
|
||||
- `$handoff` — заменить эту записку после следующего содержательного прогона.
|
||||
- `$conventional-commits` — зафиксировать следующую доказанную поставку.
|
||||
@@ -1,73 +1,39 @@
|
||||
# Полевые заметки
|
||||
|
||||
Читай этот файл при развитии скилла и при первом прогоне в новой среде. После
|
||||
боевого прогона записывай только факты, которые меняют процесс. Когда урок
|
||||
поглощён `SKILL.md` или `roles.md`, сжимай запись до одной строки со ссылкой.
|
||||
Читай при развитии скилла и первом прогоне в новой среде. Храни здесь только
|
||||
факты, которые меняют выбор приёма, и живые предположения. Поглощённый урок
|
||||
сжимай до одной строки с указателем на действующий договор.
|
||||
|
||||
## Перенесено из исходного плейбука
|
||||
## Наблюдения
|
||||
|
||||
- Разные семейства моделей находили почти непересекающиеся классы ошибок.
|
||||
Это аргумент за внешний обзор, но не обязательная часть конвейера.
|
||||
- Ревьюер без прав на запись хуже проверял гипотезы, когда тестам нужны кэши
|
||||
и временные артефакты. Рабочая защита: точка отсчёта Git, явный мандат не
|
||||
менять исходники и сверка дерева после ревью.
|
||||
- Пустой вердикт сам по себе не доказывает работу ревьюера. Нужны покрытие,
|
||||
выполненные команды или другие наблюдаемые доказательства.
|
||||
- Настройки модели, унаследованные от интерактивной сессии, менялись между
|
||||
запусками. Для управляемой стоимости модель и глубину надо закреплять.
|
||||
- Критичный отчёт фонового агента мог потеряться после его завершения.
|
||||
Надёжнее сообщение плюс файл с индексом.
|
||||
- Ссылка на другой скилл в файле-задаче не проверена как надёжный способ его
|
||||
включить. Ключевые требования надо дублировать текстом.
|
||||
- Прямой запуск внешнего Codex зависел от версии песочницы, AppArmor и сети.
|
||||
Нативный конвейер не должен зависеть от внешнего CLI.
|
||||
- 2026-07-10 — хост скрыл выбор роли и модели; стоимость осталась
|
||||
незакреплённой. Исследователь нашёл блокирующий `.gitignore`, но без нужды
|
||||
запустил полный набор тестов. Вывод поглощён в
|
||||
[основную оптику](../SKILL.md) и [мандаты](roles.md).
|
||||
- 2026-07-10 — главной утечкой контекста была повторная передача отчётов и
|
||||
промптов через мастера. Вывод поглощён в [правила обмена](../SKILL.md) и
|
||||
[сборку промптов](prompt-templates.md).
|
||||
- 2026-07-12 — разные семейства ревьюеров пересеклись в двух темах примерно из
|
||||
восьми и сохранили заметный независимый вклад. Вывод поглощён в
|
||||
[основную оптику](../SKILL.md).
|
||||
- 2026-07-12 — самоприменение поймало сломанную сборку с необязательным
|
||||
`notes.md` и показало, что язык обмена надо задавать явно. Вывод поглощён в
|
||||
[сборку промптов](prompt-templates.md).
|
||||
- 2026-07-12 — тот же прогон выявил регрессии производного скилла: второй
|
||||
ревьюер того же семейства не давал новой родословной; мастер вывел в свой
|
||||
контекст 44 хэша, полный отчёт и почти весь diff; права ревьюера смешались с
|
||||
каналом результата; семь буквальных этапов породили лишние проверки. Вывод
|
||||
поглощён в [основную оптику](../SKILL.md).
|
||||
|
||||
## Проверить боем
|
||||
|
||||
1. Выбирает ли текущий хост пользовательского агента по имени и показывает ли
|
||||
фактически использованную модель после запуска новой сессии с TOML.
|
||||
2. Даёт ли набор быстрых ролей экономию без повторной работы сильной модели.
|
||||
3. Остаётся ли дерево неизменным после ревьюера с `workspace-write`.
|
||||
фактически использованную модель после новой сессии с TOML.
|
||||
2. Даёт ли дешёвая роль экономию без повторной работы сильной модели.
|
||||
3. Остаётся ли дерево неизменным после ревьюера с `workspace-write` и явным
|
||||
мандатом не менять исходники.
|
||||
4. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях.
|
||||
5. Достаточно ли общего договора возврата, чтобы мастер не открывал сырые
|
||||
журналы и полные отчёты.
|
||||
6. Где проходит практический порог между прямой работой и полным конвейером.
|
||||
|
||||
## 2026-07-10 — пробный прогон этапов 1–2
|
||||
|
||||
- Мастер без истории исходного плейбука поднял исследователя и ревьюера,
|
||||
свёл их вывод в самодостаточную постановку и не вынес сырые журналы в
|
||||
итоговый контекст.
|
||||
- Конкретный 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`: файловый канал,
|
||||
один канонический промпт и ожидание только на критическом пути.
|
||||
5. Достаточно ли файлового канала, чтобы мастер не открывал полный отчёт и
|
||||
сырые журналы.
|
||||
6. Когда отдельный проверяющий или вторая линия ревью окупаются лучше
|
||||
объединения совместимой работы.
|
||||
@@ -1,87 +1,88 @@
|
||||
# Скелеты нативных промптов
|
||||
# Сборка нативных промптов
|
||||
|
||||
Читай только тот раздел, который нужен на текущем этапе. Полный текст
|
||||
задания и отчёта живёт в обменном временном каталоге; вызов агента содержит
|
||||
короткую обёртку с абсолютными путями.
|
||||
Открывай только раздел выбранного приёма. Это справочник готовых договоров,
|
||||
а не обязательная последовательность. Постоянный текст живёт в
|
||||
[prompts/](prompts/):
|
||||
|
||||
## Общий договор результата
|
||||
- [result-contract.md](prompts/result-contract.md) — обычный результат;
|
||||
- [review-boilerplate.md](prompts/review-boilerplate.md) — слепое ревью;
|
||||
- [triage-header.md](prompts/triage-header.md) — закрытие находок;
|
||||
- [recheck-header.md](prompts/recheck-header.md) — узкая перепроверка;
|
||||
- [runtime-language.md](prompts/runtime-language.md) — язык временного обмена.
|
||||
|
||||
Полный отчёт, независимо от канала:
|
||||
Текст договора меняй только в его авторитетном файле. Здесь остаются выбор и
|
||||
механика сборки.
|
||||
|
||||
## Канал результата
|
||||
|
||||
Канал выбери по [основной оптике](../SKILL.md). Здесь важна только механика:
|
||||
для файлового канала задай уникальный `REPORT`, для сообщения не создавай
|
||||
вторую копию результата.
|
||||
|
||||
## Обычный исполнитель или исследователь
|
||||
|
||||
Параметрический файл содержит только нужные конкретной задаче поля:
|
||||
|
||||
```text
|
||||
ИТОГ: завершено | есть вопросы | заблокировано
|
||||
ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики
|
||||
РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь
|
||||
НАХОДКИ: SEVERITY файл:строка — суть — как проверить
|
||||
СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет»
|
||||
GOAL: one verifiable goal
|
||||
BOUNDARIES: allowed and forbidden work
|
||||
READ FIRST: paths to contracts and examples
|
||||
CHECKS: commands this agent should run
|
||||
REPORT: path, only when the result will be reused
|
||||
```
|
||||
|
||||
Пустые разделы пропускаются. Сырой вывод и ход рассуждений не включаются.
|
||||
При файловом канале этот договор заполняется в файле, а финальное сообщение
|
||||
содержит только `ИТОГ`, счётчики и `АРТЕФАКТ: абсолютный путь`. При
|
||||
`read-only` договор возвращается один раз сообщением без поля `АРТЕФАКТ`.
|
||||
Добавь общий результат и язык временного обмена:
|
||||
|
||||
## Исполнитель
|
||||
|
||||
Файл задачи должен содержать:
|
||||
|
||||
```text
|
||||
ЦЕЛЬ: одна проверяемая цель
|
||||
КРИТЕРИИ: исчерпывающий список
|
||||
ГРАНИЦЫ: разрешённые и запрещённые изменения
|
||||
СНАЧАЛА ПРОЧИТАТЬ: пути к контрактам и образцам
|
||||
ПРОВЕРКИ: узкие команды разработки
|
||||
ОТЧЁТ: отдельный путь в обменном каталоге
|
||||
```bash
|
||||
cat "$D/params.md" "$P/result-contract.md" "$P/runtime-language.md" \
|
||||
> "$D/prompt.md"
|
||||
```
|
||||
|
||||
Короткий вызов: прочитать файл задачи и выполнить буквально. Агент с записью
|
||||
в обменный каталог сохраняет полный отчёт по заданному пути и финальным
|
||||
сообщением возвращает состояние, счётчики и путь. `read-only`-агент
|
||||
возвращает короткий результат один раз сообщением. Коммит не делать.
|
||||
Самодостаточный файл задачи, критерии и подробное обязательное чтение добавляй
|
||||
только когда они действительно нужны выбранной работе.
|
||||
|
||||
## Слепое ревью
|
||||
## Свежий ревьюер
|
||||
|
||||
Один канонический файл на всех ревьюеров:
|
||||
Общая часть содержит задачу, изменённый объём и известные проверки. Фокус
|
||||
содержит только выбранный для этого ревью класс риска. Для одного ревьюера:
|
||||
|
||||
```text
|
||||
АРТЕФАКТ: задача и изменённый объём
|
||||
ФОКУС: корректность, контракт, краевые случаи, честность тестов
|
||||
МАНДАТ: исследовать и проверять гипотезы, исходники не исправлять
|
||||
ФОРМАТ: severity, файл:строка, сценарий сбоя, доказательство, проверка
|
||||
ВЕРДИКТ: APPROVED | REVISE
|
||||
```bash
|
||||
cat "$D/review-common.md" "$D/review-focus.md" \
|
||||
"$P/review-boilerplate.md" "$P/runtime-language.md" \
|
||||
> "$D/review-prompt.md"
|
||||
```
|
||||
|
||||
Вызов каждого ревьюера добавляет только его фокус и канал результата:
|
||||
|
||||
- `workspace-write`: уникальный путь файла; финальное сообщение — вердикт,
|
||||
счётчики по severity и путь; исходники не менять, Git сверить до и после;
|
||||
- `read-only`: короткий индекс один раз финальным сообщением, без требования
|
||||
записать файл.
|
||||
Если осознанно выбраны несколько линий, каждому ревьюеру дай отдельный файл
|
||||
фокуса и отдельный путь результата. Не создавай вторую линию только ради
|
||||
симметрии или свежего треда того же семейства.
|
||||
|
||||
## Закрытие находок
|
||||
|
||||
Исполнителю передаются пути к исходным индексам ревью и такой короткий
|
||||
мандат:
|
||||
Передай исполнителю исходные индексы без пересказа. Обязательный
|
||||
`triage-params.md` задаёт путь полного отчёта и нужные проверки. `notes.md`
|
||||
добавляй только для новых решений мастера, которых у исполнителя ещё нет:
|
||||
|
||||
```text
|
||||
По каждой находке: исправить, сузить или отклонить через контракт и проверку.
|
||||
Не менять соседний объём. Полный отчёт решений записать по указанному пути.
|
||||
Финальным сообщением вернуть счётчики, проверки и путь.
|
||||
```bash
|
||||
cat "$P/triage-header.md" "$D/triage-params.md" "$D/review-a.md" \
|
||||
> "$D/fix-prompt.md"
|
||||
if [ -f "$D/review-b.md" ]; then
|
||||
cat "$D/review-b.md" >> "$D/fix-prompt.md"
|
||||
fi
|
||||
if [ -f "$D/notes.md" ]; then
|
||||
cat "$D/notes.md" >> "$D/fix-prompt.md"
|
||||
fi
|
||||
cat "$P/runtime-language.md" >> "$D/fix-prompt.md"
|
||||
```
|
||||
|
||||
Не переписывай находки в сообщение или новый файл: исходные индексы уже
|
||||
являются неизменяемым входом.
|
||||
|
||||
## Узкая перепроверка
|
||||
|
||||
Прежнему ревьюеру передаются путь к его исходному индексу и путь к отчёту
|
||||
решений исполнителя:
|
||||
Используй прежний тред ревьюера. Параметры содержат пути к его исходному
|
||||
индексу и отчёту решений, а также проверку, если она нужна:
|
||||
|
||||
```text
|
||||
Проверь только прежние находки и новые правки рядом с ними.
|
||||
По каждой: CLOSED | NOT_CLOSED | REJECTION_VALID | REJECTION_INVALID.
|
||||
Полный повторный обход не выполнять.
|
||||
```bash
|
||||
cat "$P/recheck-header.md" "$D/recheck-params.md" \
|
||||
"$P/runtime-language.md" > "$D/recheck-prompt.md"
|
||||
```
|
||||
|
||||
Финальное сообщение: `ALL_CLOSED` или `ISSUES_REMAIN`, счётчики и путь к
|
||||
файлу перепроверки.
|
||||
Не запускай перепроверку автоматически: она нужна для принятых исправлений,
|
||||
спорного отклонения или дорогой ошибки, а не для закрытия ритуального этапа.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Narrow re-check
|
||||
|
||||
Re-check only your original findings and the changes immediately adjacent to
|
||||
their resolution. Do not perform a full review.
|
||||
|
||||
For every original finding report `CLOSED`, `NOT_CLOSED`, `REJECTION_VALID`,
|
||||
or `REJECTION_INVALID`, with concise evidence. If this narrow work exposes a
|
||||
new adjacent defect, report it in the normal findings format; the scope bound
|
||||
limits exploration, not honest reporting.
|
||||
|
||||
Return the full re-check through the channel named by the caller. For a file
|
||||
channel, write it to the supplied path and return only
|
||||
`RECHECK: ALL_CLOSED | ISSUES_REMAIN`, counters, and `REPORT: <absolute path>`.
|
||||
For a message channel, return the concise finding statuses once.
|
||||
@@ -0,0 +1,14 @@
|
||||
## Result contract
|
||||
|
||||
Write the full result through the channel chosen by the caller:
|
||||
|
||||
- `STATUS: complete | questions | blocked`
|
||||
- `EVIDENCE:` changed files, executed commands, and final counters
|
||||
- `DECISIONS:` only questions for the orchestrator or user
|
||||
- `FINDINGS:` severity, location, essence, and verification method
|
||||
- `NEXT:` one concrete action or `none`
|
||||
|
||||
Omit empty sections. Do not include raw output or a reasoning narrative. For a
|
||||
file channel, put the full result in the named file and return only status,
|
||||
counters, and `REPORT: <absolute path>`. For a message channel, return one
|
||||
concise result without a report path.
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
## Mandate
|
||||
|
||||
- Review and test hypotheses; do not edit source files or persistent
|
||||
environment state.
|
||||
- Use the working permissions needed for checks, caches, temporary artifacts,
|
||||
documentation and primary-source research. The caller verifies Git before
|
||||
and after the review.
|
||||
- Do not run `git add`, `git commit`, or commands that discard changes.
|
||||
- Report only the findings index and verdict through the channel named by the
|
||||
caller.
|
||||
|
||||
## Findings index
|
||||
|
||||
For each finding:
|
||||
|
||||
`SEVERITY(BLOCKER|MAJOR|MINOR|NIT) | file:line or task section | failure scenario | evidence | how to verify`
|
||||
|
||||
If there are no findings, list the reviewed scope and every executed check or
|
||||
tested hypothesis with its outcome. A bare no-findings assertion is invalid.
|
||||
|
||||
Final line: `VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUIRED`
|
||||
@@ -0,0 +1,4 @@
|
||||
## Runtime language
|
||||
|
||||
Write every runtime prompt result, report, findings index, and exchange file in
|
||||
English. Do not infer the output language from the repository or conversation.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Triage blind-review findings
|
||||
|
||||
The review indexes below are immutable input. Process every finding and change
|
||||
nothing outside their scope. For each finding, either:
|
||||
|
||||
- fix it and name the contract or check that proves closure; or
|
||||
- reject it with evidence from the contract and a check, never a bare claim.
|
||||
|
||||
Do not commit or stage changes. Propose accepted rejections and residual risks
|
||||
for the orchestrator to own and record as durable task decisions. The
|
||||
orchestrator cannot silently accept risk; authority must come from the user or
|
||||
already be explicit in the task.
|
||||
|
||||
Write a full resolution report to the path supplied by the caller. Return only
|
||||
status, counters, executed checks, and that path in the final message.
|
||||
@@ -1,7 +1,9 @@
|
||||
# Уровни и роли
|
||||
|
||||
Читай этот файл только при настройке ролей или когда нужная роль недоступна.
|
||||
Сам конвейер описан в `SKILL.md`.
|
||||
[Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен.
|
||||
Этот файл — условные настройки мандата, а не список обязательных участников.
|
||||
Один агент может совмещать совместимую работу; не создавай тред на каждое имя.
|
||||
|
||||
- [Возможности хоста](#возможности-хоста)
|
||||
- [Выбор уровня](#выбор-уровня)
|
||||
@@ -28,7 +30,8 @@
|
||||
конфигурации агента.
|
||||
|
||||
Если способ выбора роли не виден в доступном инструменте, считай стоимость
|
||||
неуправляемой и отметь это в итоговом отчёте.
|
||||
неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу
|
||||
на дополнительные роли без явной пользы.
|
||||
|
||||
Вызов TOML-роли:
|
||||
|
||||
@@ -86,7 +89,7 @@
|
||||
Конкретные названия моделей держи в конфигурации агентов, а не в `SKILL.md`.
|
||||
Так замена модельной линейки не меняет процесс.
|
||||
|
||||
## Роли
|
||||
## Возможные мандаты
|
||||
|
||||
### `fast-worker`
|
||||
|
||||
@@ -128,13 +131,12 @@
|
||||
корректности, безопасности, контракта и тестов. Каждая находка содержит
|
||||
сценарий сбоя, доказательство, влияние и способ проверки.
|
||||
|
||||
Для чистого чтения: `sandbox_mode = "read-only"`. Если ревью требует запуска
|
||||
инструментов, которые пишут кэш или артефакты, использовать
|
||||
`workspace-write`, запретить правки исходников мандатом и сверить Git до и
|
||||
после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и
|
||||
доступ к документации. Непроверенную внешнюю механику отмечать как гипотезу.
|
||||
Для длинного или повторно используемого индекса нужен доступ на запись в
|
||||
обменный каталог; иначе вернуть короткий индекс один раз сообщением.
|
||||
Для полноценного ревью обычно нужен `sandbox_mode = "workspace-write"`: тесты,
|
||||
кэши, временные артефакты и исследование не следует урезать ради запрета
|
||||
правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется
|
||||
до и после. Доступ к сети проверять отдельно: право записи не гарантирует
|
||||
поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу.
|
||||
Канал результата от песочницы не зависит.
|
||||
|
||||
### `verifier`
|
||||
|
||||
@@ -168,6 +170,8 @@ developer_instructions = """
|
||||
|
||||
- Держи глубину `1`: субагенты не создают собственное дерево исполнителей.
|
||||
- Оставляй один слот мастеру.
|
||||
- Параллельно запускай чтение, независимые исследования и слепые ревью.
|
||||
- Параллельно запускай только работу без конфликтующих входов, команд и
|
||||
изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а
|
||||
не ради заполнения свободного слота.
|
||||
- Реализацию и починку одного рабочего дерева выполняй последовательно одним
|
||||
владельцем.
|
||||
Reference in new issue
Block a user