docs(skill): принцип «мастер решает», готовые boilerplate-промпты, ревизия
- Зачем:
- ретро прогона 2026-07-12 (задача 20, clickstream-demo): контекст
оркестратора съедали инлайн-диагнозы, переписывание boilerplate и
кириллица в обменных файлах.
- Что:
- SKILL.md: принцип «мастер решает — субагенты выясняют» со стоп-краном
«сам — максимум один заход», обменные файлы на английском, сквозная
проверка до ревьюеров, будильник одной строкой.
- references/prompts/: готовые английские boilerplate-файлы (мандат
ревью, триаж, перепроверка) — подшиваются cat'ом, контекст мастера
не проходят; prompt-templates перестроен под сборку.
- codex-exec: модель gpt-5.6-sol, лестница эффорта, ловушка «&»;
sandbox-справочник переименован в codex-sandbox-apparmor.md;
lessons дистиллирован, добавлена запись прогона 2026-07-12.
- закрыты 14 находок слепого Fable-ревью скилла (согласованность,
единый источник $SCRATCH, скелет ревью постановки).
- Проверка:
- все внутренние ссылки резолвятся; слепое ревью: APPROVED_WITH_MINORS,
восстановление структуры подтверждено без потерь.
This commit is contained in:
1 parent
60182ab493
commit
7110a075ea
9 files changed
+357
-410
No files matched your search
@@ -20,35 +20,42 @@ description: >-
|
||||
|
||||
**Не разворачивай конвейер на мелочь.** Косметика, пара часов работы, один
|
||||
файл — сделай сам: накладные расходы процесса многократно превысят цену
|
||||
работы (эмпирика: на полировку ноутбука чуть не завели несколько issue —
|
||||
пользователь остановил). Очередь зависимых issue с автономным прогоном —
|
||||
работы. Очередь зависимых issue с автономным прогоном —
|
||||
это `/coordinator-loop`, не этот плейбук.
|
||||
|
||||
## Роли
|
||||
|
||||
- **Оркестратор (ты)** — план, постановка, синтез, коммит. Работай по
|
||||
**индексу** (правило `/coordinator-loop`): в твой контекст входят вердикты
|
||||
и находки `файл:строка`, а не diff, не полные логи и не нарратив. Шумные
|
||||
команды — через файл-лог, в контекст только сводку. **Индекс — у тебя,
|
||||
полезная нагрузка — файлами между агентами**: вердикты, отчёты и промпты
|
||||
живут в `$SCRATCH` (обменный temp-каталог прогона с полуслучайным
|
||||
префиксом — скретчпад сессии или `mktemp -d`; детали — в
|
||||
[references/prompt-templates.md](references/prompt-templates.md)), ты
|
||||
читаешь их один раз и дальше передаёшь путями и конкатенацией (`cat`), а
|
||||
не переписываешь Write'ом — каждое переписывание дублирует контент в
|
||||
твоём контексте (ретро 2026-07-10: находки ревью проходили через
|
||||
оркестратора до шести раз). SendMessage возвращает эхом
|
||||
весь текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос),
|
||||
- **Оркестратор (ты)** — план, постановка, синтез, коммит. Принцип:
|
||||
**мастер решает — субагенты выясняют**; твой контекст — самый дорогой
|
||||
ресурс, в него входят решения, вердикты и находки `файл:строка` — не
|
||||
diff, не полные логи, не нарратив. Работу с неизвестным заранее объёмом
|
||||
вывода (диагноз падения, исследование гипотезы, серия экспериментов,
|
||||
чтение логов) отдавай субагенту **до её начала**: изнутри она всегда
|
||||
выглядит «ещё на один шаг». Стоп-кран: **сам — максимум один заход**
|
||||
(одна команда с коротким выводом по единственной гипотезе); не
|
||||
подтвердилось — делегируй. Механику (правки файлов по готовым решениям,
|
||||
скрипты, вёрстку) — `fast-worker`'у: твоё в них только короткий список
|
||||
решений. **Индекс — у тебя, полезная нагрузка — файлами между
|
||||
агентами**: вердикты, отчёты и промпты живут в `$SCRATCH` (обменный
|
||||
temp-каталог прогона — скретчпад сессии или `mktemp -d`; детали — в
|
||||
[references/prompt-templates.md](references/prompt-templates.md)) и
|
||||
ведутся **на английском** — проект их не хранит, а кириллица в 1,5–2
|
||||
раза дороже по токенам; русский — только тому, что уходит в репозиторий
|
||||
и пользователю. Читай их один раз, дальше передавай путями и
|
||||
конкатенацией (`cat`), не переписывай Write'ом — каждое переписывание
|
||||
дублирует контент в твоём контексте. SendMessage возвращает эхом весь
|
||||
текст сообщения — teammate'у шли короткое (вердикт, путь, вопрос),
|
||||
длинное — файлом, который он прочтёт сам.
|
||||
- **Codex** — реализация кода. У пользователя лимиты Codex больше, код он
|
||||
пишет в целом лучше, но верхнеуровнево планирует хуже — поэтому
|
||||
декомпозиция и постановка остаются у тебя. Механика вызова —
|
||||
[references/codex-exec.md](references/codex-exec.md).
|
||||
- **Ревьюеры** — два, **разных родословных**, слепые друг к другу:
|
||||
Claude-субагент (`adversarial-reviewer`; нет в среде — скептический
|
||||
`general-purpose`) и Codex **свежим тредом**, не тем, что писал код.
|
||||
Разные родословные ловят непересекающиеся классы находок (пересечение в
|
||||
прогонах — стабильно ~ноль). Обоим — руки: тесты, гипотезы, поиск,
|
||||
Claude-субагент (`adversarial-reviewer`; нет в среде — `deep-reasoner`
|
||||
или скептический `general-purpose`) и Codex **свежим тредом**, не тем,
|
||||
что писал код.
|
||||
Разные родословные ловят разные классы находок (пересечение в прогонах —
|
||||
от нуля до пары тем). Обоим — руки: тесты, гипотезы, поиск,
|
||||
документация, первоисточники; запрет менять исходники и окружение —
|
||||
**мандатом в промпте, не урезанием песочницы** (рецепт и подстраховка —
|
||||
[references/codex-exec.md](references/codex-exec.md)).
|
||||
@@ -71,8 +78,8 @@ description: >-
|
||||
контекста; всё нужное — в файле: цель, критерии приёмки чекбоксами,
|
||||
границы («что трогать нельзя»), «сначала прочитать» (спека, ADR, README с
|
||||
командами), команды проверки. Формат и место — по конвенции репозитория
|
||||
(например, `.scratch/<feature>/issues/`; репозиторий настроен под скиллы
|
||||
Мэтта Покока — постановка через `/to-tickets` в сконфигурированный трекер:
|
||||
(например, `.scratch/<feature>/issues/`; если репозиторий настроен под
|
||||
скиллы Мэтта Покока — постановка через `/to-tickets` в его трекер:
|
||||
тикеты-срезы с рёбрами блокировок вместо ad-hoc файла, конвенции — в
|
||||
`docs/agents/`, настройка — `/setup-matt-pocock-skills`). Не хватает
|
||||
фактуры по внешним библиотекам/API — сначала `/research` и Context7 MCP,
|
||||
@@ -83,17 +90,16 @@ description: >-
|
||||
не задав тебе ни одного вопроса.
|
||||
2. **Свежий взгляд на постановку — до реализации.** Адверсарный ревьюер без
|
||||
твоего контекста проверяет задачу против кода: фактические ошибки, скрытые
|
||||
решения-«однострочники», недостающие критерии. Окупается: ловит блокеры,
|
||||
которые исполнитель молча реализовал бы (эмпирика: «русские названия из
|
||||
`name_ru`» — а в данных `name_ru` английский). Постановка крупная или
|
||||
решения-«однострочники», недостающие критерии. Окупается каждый прогон:
|
||||
ловит блокеры, которые исполнитель молча реализовал бы. Постановка
|
||||
крупная или
|
||||
цена ошибки высока — сделай ревью двойным и слепым, как для кода: вторая
|
||||
линия — Codex свежим тредом с явной рамкой «ревьюируй постановку, не
|
||||
реализацию; детали реализации — только если постановка молча предрешает
|
||||
решение» (без рамки зарывается в детали). Родословные и тут ловят разное:
|
||||
Codex — уровень требований (недостающие критерии, наблюдаемость,
|
||||
«формально отчитаться можно»), Клод — механику кода (нереализуемые
|
||||
формулировки, мёртвые стабы; эмпирика 2026-07-10: пересечение — 2 темы
|
||||
из ~15). Этап закрыт, когда каждая
|
||||
формулировки, мёртвые стабы). Этап закрыт, когда каждая
|
||||
находка внесена в задачу **решением** или письменно отклонена — «пусть
|
||||
решит исполнитель» решением не считается.
|
||||
3. **Реализация Кодексом.** Промпт: «задача самодостаточна, следуй буквально,
|
||||
@@ -103,7 +109,11 @@ description: >-
|
||||
[references/codex-exec.md](references/codex-exec.md).
|
||||
Один писатель в дереве: пока Codex пишет — никто больше (казус с
|
||||
форвардером — в [references/lessons.md](references/lessons.md)). Готово,
|
||||
когда Codex вернул отчёт, а в дереве нет правок, которых он не называл.
|
||||
когда Codex вернул отчёт, в дереве нет правок, которых он не называл,
|
||||
и дешёвая сквозная проверка (если она есть в репо) зелёная: гонял её
|
||||
исполнитель по промпту, а если ему она недоступна (docker, стенд) — ты,
|
||||
**до запуска ревьюеров**: иначе ревью уйдёт на код, который сквозной
|
||||
прогон ещё поменяет.
|
||||
4. **Два слепых ревью параллельно.** Промпт — **один канонический файл в
|
||||
`$SCRATCH` на оба ревью** (скелет и обёртки вызова —
|
||||
[references/prompt-templates.md](references/prompt-templates.md)): Codex
|
||||
@@ -111,15 +121,13 @@ description: >-
|
||||
«прочитай файл X и выполни; индекс — в файл Y» (не дублируй текст
|
||||
промпта в параметре — это второй полный экземпляр в твоём контексте).
|
||||
Содержание: путь к задаче-файлу + фокус (математика/краевые случаи,
|
||||
соответствие критериям, честность тестов, артефакты). Друг про друга не
|
||||
знают, твои выводы им не пересказывай. Обоим поощряй безопасные
|
||||
эмпирические проверки (воспроизвести краевой случай вне репо, сходить в
|
||||
документацию) — вердикт заметно твёрже; менять исходники и окружение
|
||||
нельзя. Вердикты — файлами с **разными путями**: у Codex это его
|
||||
`-o`-отчёт, Клод-ревьюеру обёртка разрешает запись файла вердикта в
|
||||
`$SCRATCH` (вне репо — мандату не противоречит), финальным актом —
|
||||
SendMessage только со строкой VERDICT, счётчиками и путём: его
|
||||
idle-уведомления не содержат результата, не жди из них ничего. После
|
||||
соответствие критериям, честность тестов, артефакты); мандат и
|
||||
поощрение эмпирических проверок уже в готовом boilerplate. Друг про
|
||||
друга не знают, твои выводы им не пересказывай. Вердикты — файлами с
|
||||
**разными путями**: у Codex это его `-o`-отчёт, Клод-ревьюеру путь и
|
||||
финальный акт (SendMessage только со строкой VERDICT, счётчиками и
|
||||
путём) задаёт готовая обёртка из шаблонов; его idle-уведомления
|
||||
результата не содержат, не жди из них ничего. После
|
||||
ревью сверь дерево (`git status`). Клод-ревьюеру можно поручить смотреть
|
||||
артефакты (картинки из ноутбука). Этап закрыт, когда оба вердикта у тебя
|
||||
индексами и дерево нетронуто; вердикт без единой находки засчитывай
|
||||
@@ -131,9 +139,10 @@ description: >-
|
||||
кода): перешли Codex индекс находок **дословно**, он чинит или
|
||||
**аргументированно отклоняет** — через контракт и тест, не голословно;
|
||||
промпт починки — «закрой перечисленное, больше ничего не меняй».
|
||||
«Дословно» — это конкатенация: `cat шапка.md вердикт-A.md вердикт-B.md >
|
||||
fix-prompt.md` Bash'ем; Write'ом ты бы переписал те же находки в контекст
|
||||
ещё раз. Свои замечания к триажу — только шапкой. Ты судишь уровнем
|
||||
«Дословно» — это конкатенация: `cat triage-header.md вердикт-A.md
|
||||
вердикт-B.md > fix-prompt.md` Bash'ем (шапка готова в
|
||||
`references/prompts/`); Write'ом ты бы переписал те же находки в
|
||||
контекст ещё раз. Свои замечания к триажу — только шапкой. Ты судишь уровнем
|
||||
задачи: принять риск / вне скоупа. Повторная проверка — узкая (см.
|
||||
«Свежесть»); её промпт не пересказывает резолюции — ссылается на файл
|
||||
отчёта исполнителя. Этап закрыт, когда по каждой находке обоих ревью есть
|
||||
@@ -153,9 +162,10 @@ description: >-
|
||||
(механика — [references/codex-exec.md](references/codex-exec.md)).
|
||||
Подстраховка от молчаливой смерти агента — ScheduleWakeup сроком дольше
|
||||
ожидаемой длительности: по пробуждению смотри логи сам, по приходу
|
||||
результата таймер снимай. Idle-уведомления teammate-субагентов — шум, а не
|
||||
событие: не докладывай о них пользователю и не действуй по ним, если
|
||||
результат уже получен (ретро 2026-07-10: ~7 пустых ходов на idle-пингах).
|
||||
результата таймер снимай; промпт будильника — одна короткая строка,
|
||||
план не пересказывай (он живёт в разговоре). Idle-уведомления
|
||||
teammate-субагентов — шум, а не событие: не докладывай о них пользователю
|
||||
и не действуй по ним, если результат уже получен.
|
||||
|
||||
## Соседние скиллы
|
||||
|
||||
@@ -176,9 +186,10 @@ description: >-
|
||||
- [references/codex-exec.md](references/codex-exec.md) — прямой `codex exec`:
|
||||
сквозные правила (шум в файлы, thread_id, resume по id, проверка отписки),
|
||||
ветки исполнитель/ревьюер/триаж, раннер для переваривания шума.
|
||||
- [references/prompt-templates.md](references/prompt-templates.md) — скелеты
|
||||
четырёх промптов конвейера (задача/ревью/триаж/перепроверка): пиши только
|
||||
параметрический блок на задачу, boilerplate не переписывай.
|
||||
- [references/prompt-templates.md](references/prompt-templates.md) — сборка
|
||||
промптов: готовые boilerplate-файлы в `references/prompts/` подшиваются
|
||||
`cat`'ом из каталога скилла, Write'ом пишутся только параметрические
|
||||
блоки.
|
||||
- [references/lessons.md](references/lessons.md) — датированная эмпирика
|
||||
прогонов: что поймал каждый этап, казусы, цифры.
|
||||
- [references/claude-agents.md](references/claude-agents.md) — определения
|
||||
|
||||
Reference in new issue
Block a user