ddadmin
7110a075ea
- Зачем:
- ретро прогона 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,
восстановление структуры подтверждено без потерь.
148 lines
12 KiB
Markdown
148 lines
12 KiB
Markdown
# Codex через прямой `codex exec`: рецепты и ловушки
|
||
|
||
Проверено 2026-07-09 (codex-cli 0.142.5, Windows + Git Bash) и 2026-07-12
|
||
(0.144.1, WSL2 Ubuntu: exec/resume/`-o`/фоновый Bash — весь конвейер);
|
||
линукс-эмпирика 07-06/07-07 шла через companion-обёртку и отражена в уроках
|
||
ниже.
|
||
Прямой CLI надёжнее обёртки: её фоновая машина глючит (молчаливая подмена
|
||
анализа Кодекса своим — issue #158, ломает слепое ревью; зависшие статусы),
|
||
и её `--write`-запуски режет классификатор авторежима. Далее `$D` =
|
||
подпапка задачи в обменном каталоге прогона (определение и конвенция —
|
||
[prompt-templates.md](prompt-templates.md)).
|
||
|
||
## Сквозные правила (любая ветка)
|
||
|
||
- **Промпт — файлом, шум — в файлы.** Промпт подавай через stdin (`-`);
|
||
stdout/stderr — редиректами в `$SCRATCH`. В контекст оркестратора
|
||
читается ровно один файл — финальный отчёт из `-o`. Промпт **собирай
|
||
конкатенацией, а не переписывай**: скелеты — в
|
||
[prompt-templates.md](prompt-templates.md), Write'ом пиши только
|
||
параметрический блок задачи; чужой контент (вердикты ревью, отчёты) в
|
||
промпт попадает через `cat a.md b.md > prompt.md` — дословно и без
|
||
повторного прохода через твой контекст (ретро 2026-07-10: переписывание
|
||
гоняло находки через оркестратора до шести раз).
|
||
- **Модель и глубину рассуждения задавай явно** (`-m`,
|
||
`-c 'model_reasoning_effort="..."'`): дефолты берутся из
|
||
`~/.codex/config.toml` и плавают за последней интерактивной сессией
|
||
пользователя — из конфига не наследовать, при расхождении с правилом —
|
||
спроси пользователя. Боевая модель — **`gpt-5.6-sol`** (решение
|
||
пользователя 2026-07-12), она хороша и для анализа/ревью, не только для
|
||
кода. Эффорт по сложности: `high` — реализация, ревью, диагноз; `medium`
|
||
— механика и **узкие починки по готовому диагнозу** (resume-триаж, где
|
||
рецепт уже расписан); `xhigh` — не дефолтить: расход удваивается, а
|
||
выигрыш мал — только по явному запросу пользователя. Оверрайды проверены
|
||
под `--strict-config`.
|
||
- **Запуск — собственным фоновым Bash оркестратора** (`run_in_background`):
|
||
фоновый процесс детачится, живёт сквозь ходы и будит оркестратора по
|
||
выходу. Потолок 10 минут — только у фронтграундного Bash; фоновому таймаут
|
||
не нужен, `timeout NNN` вокруг codex не ставь. **`&` внутрь команды не
|
||
добавляй** — фон даёт харнесс; с `&` уведомление придёт от обёртки при
|
||
живом codex (эмпирика 2026-07-12). Спасение осиротевшего процесса:
|
||
ожидатель `while kill -0 <pid>; do sleep 10; done` под
|
||
`run_in_background` будит по его реальному выходу.
|
||
- **thread_id — в первой строке stdout-JSONL** (`{"type":"thread.started",...}`).
|
||
Забирай сразу после старта: это страховка — если процесс умер или его
|
||
прибил хост, тред жив: `codex exec resume <id> «дай финальный отчёт»`.
|
||
- **resume — только по явному id.** Безадресный resume цепляет последний тред
|
||
сессии — при параллельных тредах подхватит чужой (например, ревью-тред
|
||
вместо треда реализации).
|
||
- **Вердикт без находок — проверь лог: работа или отписка.** Дёшево:
|
||
`grep -c '"command_execution"' stdout.jsonl` (счётчик выполненных команд)
|
||
или промежуточные сообщения —
|
||
`jq -r 'select(.item.type=="agent_message") | .item.text' stdout.jsonl`.
|
||
Одна строка APPROVED при пустом счётчике — отписка, перезапускай.
|
||
- **Кросс-платформенно.** Рецепты — POSIX под Git Bash (эмпирика 2026-07-09:
|
||
`codex`, `jq`, редиректы под Windows работают). `$SCRATCH` задавай
|
||
forward-slash-путём (`/c/Users/...`), не `C:\...`; пути в аргументах
|
||
кавычь; в выводах под Windows возможны `\r`.
|
||
- **Linux: sandbox может молча сломаться обновлением Codex.** CLI 0.144.1
|
||
сменил backend на bwrap+userns; Ubuntu 24.04 с
|
||
`apparmor_restrict_unprivileged_userns=1` глушит любые команды до запуска
|
||
(`bwrap: loopback: Failed RTM_NEWADDR`). Сигнатура: web_search работает,
|
||
а `pwd` в sandbox — нет. Обход без sudo `use_legacy_landlock=true` чинит
|
||
только read-only (write-режим с ним паникует); полный фикс — AppArmor-
|
||
профиль. Диагностика и рецепты —
|
||
[codex-sandbox-apparmor.md](codex-sandbox-apparmor.md).
|
||
Фикс целиком под sudo — сам не применяй: дай пользователю готовые команды
|
||
из файла рецептов (`!`-префикс в чат), после применения профиля напомни
|
||
убрать `use_legacy_landlock`. Перед первым прогоном конвейера на новой
|
||
Linux-машине прогони диагностику из файла рецептов превентивно.
|
||
- **Блок классификатора — решение пользователя.** Если запуск не прошёл
|
||
permission-гейт, дай пользователю готовую команду с префиксом `!` в чат
|
||
или попроси сменить режим разрешений. Сработавший путь — прямой exec;
|
||
companion с `--write` блокируется и напрямую, и через раннера.
|
||
|
||
## Ветка «исполнитель» (пишет код)
|
||
|
||
```bash
|
||
cat "$D/task-prompt.md" | codex exec --json --strict-config \
|
||
-s workspace-write -m gpt-5.6-sol \
|
||
-c 'model_reasoning_effort="high"' \
|
||
-c 'approval_policy="on-request"' -c 'approvals_reviewer="auto_review"' \
|
||
-o "$D/task-result.md" - \
|
||
> "$D/task-stdout.jsonl" 2> "$D/task-stderr.txt"
|
||
```
|
||
|
||
- `--strict-config` — обязателен: опечатка в `-c`-ключе упадёт громко, а не
|
||
проглотится молча (важно для `approvals_reviewer` — в `--help` он не
|
||
документирован, но strict-config его принимает; связка с
|
||
`approval_policy="on-request"` отработала боевой прогон 2026-07-09).
|
||
- Право записи + авто-ревьюер аппрувов. Скоуп ограничивай промптом («коммит
|
||
не делай», границы из файла задачи), не песочницей — жёсткий read-only
|
||
лишает исполнителя тестов и поиска.
|
||
- Промпт: путь к файлу задачи; мандат — в этапе 3 SKILL.md.
|
||
- До старта сними baseline `git status --porcelain`; после — сверь отчёт
|
||
Кодекса с деревом: правок, которых он не называл, быть не должно.
|
||
|
||
## Ветка «ревьюер» (свежий тред, мандат промптом)
|
||
|
||
Тот же вызов, что у исполнителя — запись + авто-аппрув, — но **свежим
|
||
тредом**, не тем, что писал код. Read-only-песочницей ревьюера не режь: она
|
||
отнимает у него руки — тесты, проверку гипотез, поиск, документацию,
|
||
первоисточники. Защита — мандат в промпте, готовым файлом
|
||
[prompts/review-boilerplate.md](prompts/review-boilerplate.md) (сборка —
|
||
[prompt-templates.md](prompt-templates.md)); Codex держит его надёжно
|
||
(практика пользователя, 2026-07-10). Дешёвая подстраховка:
|
||
`git status --porcelain` до ревью и сверка после — дерево должно остаться
|
||
нетронутым. Кавеат: сеть под workspace-write по умолчанию закрыта; что
|
||
поиск/документация проходят эскалацией через авто-аппрув — рабочая
|
||
гипотеза, боем не обкатана (см.
|
||
[../handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md](../handoffs/20260710-codex-revyuer-write-i-sliyanie-handoffov.md)).
|
||
|
||
`-o`-файл вердикта — и есть обменный артефакт: на триаже он уходит в
|
||
fix-промпт конкатенацией, читай его один раз для синтеза и не пересказывай.
|
||
|
||
## Ветка «триаж/починка» (тем же тредом, что писал код)
|
||
|
||
```bash
|
||
cat "$D/fix-prompt.md" | codex exec resume --json <thread-id> \
|
||
-o "$D/fix-result.md" - \
|
||
> "$D/fix-stdout.jsonl" 2> "$D/fix-stderr.txt"
|
||
```
|
||
|
||
- `resume` не принимает `-s`/`-C` — песочница и CWD наследуются от исходного
|
||
треда (write-тред остаётся write); модель наследуется, но переопределяется
|
||
`-m` при нужде.
|
||
- Промпт — индекс находок **дословно** + «закрой перечисленное, больше
|
||
ничего не меняй; отклонение — только аргументированно».
|
||
|
||
## Раннер-субагент: когда результат надо переварить
|
||
|
||
Для запуска раннер не нужен (см. сквозные правила) — он нужен, когда сырой
|
||
результат шумный и его стоит провалидировать или сжать до индекса, прежде
|
||
чем показывать оркестратору. Тогда раннеру (`fast-worker`; нет в
|
||
репозитории — `general-purpose`) отдай
|
||
**готовую команду** и правила разбора — не постановку задачи: тонкий агент,
|
||
получив постановку, реализует её сам (казус форвардера, lessons 2026-07-06).
|
||
Свой 10-минутный потолок на синхронный Bash раннер обходит отслеживаемым
|
||
ожиданием: команда запускается его собственным фоновым Bash, а ждёт он
|
||
процессом-ожидателем (`until grep -q '<маркер>' лог; do sleep 30; done` под
|
||
`run_in_background`) — харнесс переинвоцирует его по выходу процесса.
|
||
«Жду уведомления» без отслеживаемого процесса не будит никогда, а голый
|
||
поллер вне `run_in_background` умирает при смене хода (эмпирика
|
||
2026-07-07) — живучесть даёт именно фоновый запуск.
|
||
|
||
Companion-плагин (`codex-companion.mjs` в кэше плагинов) — только для
|
||
ручного интерактива (`status`, `result <job-id>`); конвейер ходит прямым
|
||
exec.
|