From 86bba06f09f2c57599e71a6805e54425e52989a8 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 14 Jun 2026 21:39:46 +0300 Subject: [PATCH] =?UTF-8?q?docs(handoff):=20handoff=20coordinator-loop=20?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D0=BD=D0=B5=D1=81=D1=91=D0=BD=20=D0=B2?= =?UTF-8?q?=20=D0=BD=D0=B0=D0=B2=D1=8B=D0=BA=20(=D1=83=D0=BA=D0=B0=D0=B7?= =?UTF-8?q?=D0=B0=D1=82=D0=B5=D0=BB=D1=8C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - авторитетная версия должна жить у навыка (dotfiles), рядом с handoff-побратимом; здесь — чтобы не плодить расходящиеся копии. - Что: - полное содержимое заменено коротким указателем на dotfiles-версию. - Проверка: - открыть .scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md Co-Authored-By: Claude Opus 4.8 (1M context) --- ...-06-14-coordinator-loop-context-economy.md | 187 +----------------- 1 file changed, 10 insertions(+), 177 deletions(-) diff --git a/.scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md b/.scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md index dc0b792..96884ee 100644 --- a/.scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md +++ b/.scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md @@ -1,183 +1,16 @@ -# Handoff: экономия контекста в coordinator-loop +# Handoff: экономия контекста в coordinator-loop (указатель) Дата: 2026-06-14 MSK -Статус: рабочая договорённость по итогам сессии проектирования, в `SKILL.md` ещё не внесена. -## Зачем этот handoff +Полная, авторитетная версия этого handoff перенесена **внутрь навыка**, рядом с +handoff про наблюдаемость: -Сохранить выводы сессии, пока они свежие. Разбирались, почему навык `coordinator-loop` -(координатор + субагенты) при длинной цепочке задач переполняет контекст координатора и -дорого стоит по токенам. Это снимок для продолжения в новой сессии, а не готовая -спецификация: часть решений принята, часть осталась открытой — так и записано. +`~/dotfiles/agents/.agents/skills/coordinator-loop/handoffs/2026-06-14-coordinator-loop-context-economy.md` -Навык живёт в dotfiles: `~/.claude/skills/coordinator-loop/` (`SKILL.md`, `README.md`, -`references/rationale.md`). +Почему там: handoff про доработку навыка `coordinator-loop`, и сам навык, и его +handoff-побратим (`2026-06-14-observability-design.md`) живут в dotfiles. Чтобы будущая +сессия по доработке навыка нашла всё в одном месте, авторитетная версия лежит у навыка. -## Что болит - -Прогон Codex по двум фичам (`feature-data-generator`, 8 задач, и -`generator-model-time-startup-history`, 6 задач) вёлся как `/coordinator-loop`. У -координатора дважды заканчивался контекст (по разу на прогон), и работа съела почти весь -5-часовой лимит подписки (по логам — около 3 ч 45 мин на втором прогоне). - -## Диагностика - -Главный метод и главный урок: **логи — истина, самоотчёт модели — нет.** Codex на прямой -вопрос искренне назвал виновником многословные отчёты субагентов, пересекающие границу. Логи -это опровергли. Модель не видит свой токен-счёт и сочиняет правдоподобную, но неверную -картину. Спасло то, что полезли в логи (`~/.codex/logs_2.sqlite`, `~/.codex/sessions/`), а -не поверили рассказу. Анализ делал отдельный субагент на дешёвой модели, чтобы не забивать -контекст разбором. - -### Два разных пожара (мы их сначала склеивали) - -**Пожар A — контекст координатора.** Горел не от отчётов на границе (они были компактны: -в среднем 2,6 КБ, максимум 7,3 КБ, полных diff и логов тестов в них не было). Горел от того, -что происходило **внутри сессии самого координатора**: - -- координатор **сам читал полные diff'ы**, чтобы проверить находки, — 19 diff'ов крупнее - 10 КБ, суммарно 413 КБ, независимо от сводок воркеров; -- сессия ревьюера-апрувера раздулась до 947 КБ за 21 ход, и 42 из 44 ожиданий `wait_agent` - завершились таймаутом (опрос по кругу при том, что push-уведомления приходили). - -Пик контекста: 199 307 токенов из окна 258 400 (77 %), одна компактизация. - -**Пожар B — 5-часовой лимит** (отдельная от контекст-окна вещь, это суммарный расход -токенов): - -- **103 прогона полного тест-сета** (каждый ~40 КБ вывода, до 16 877 токенов за один) — - главный потребитель; -- `/goal`-петли воркеров по ~400K токенов на задачу (задачи 05 и 06); -- 13 Docker-сборок и накладные расходы опроса. - -### Гипотезы и вердикты - -| # | Гипотеза | Вердикт | Доказательство | -|---|---|---|---| -| H1 | контекст рос из-за отчётов субагентов | **опровергнута** | средний отчёт 2,6 КБ, max 7,3 КБ; diff и логи в них не входили | -| H2 | координатор перечитывал то, что воркер уже сообщил | **подтверждена** | 19 полных diff в сессии координатора, 413 КБ | -| H3 | компактизация теряла важное и его восстанавливали | частично | после компактизации координатор перечитывал статусы issue и git-историю | -| H4 | полный режим ревью применялся избыточно | частично, переосмыслена | дело не в самом ревью, а в polling-overhead: 42/44 таймаута, сессия 947 КБ | -| H5 | лимит съели `/goal` и тест-прогоны | частично | 103 полных ретеста — главное; `/goal` был только на 05–06 | - -### Что Codex дал верно, несмотря на промах с локацией - -Его интроспекция угадала **форму** балласта (материал, который должен был сжиматься после -своего момента) и продиктовала точные компактные форматы. Ключевой ответ про классификацию -находок: отчёта субагента **хватало для маршрутизации** (blocker / риск / docs-мелочь / -ложная тревога), но для финального решения «чинить или нет» по межмодульному инварианту он -**всё равно лез в код** — отчёт был индексом и аргументацией, а не заменой чтения. Отсюда -вывод: лучший отчёт — это индекс (находка, `файл:строка`, минимальный путь воспроизведения, -какой критерий нарушен, что проверить в коде), а не нарратив. - -Про `wait_agent`: таймауты стояли 10/15/3 минуты, push-уведомления (``) -приходили, но Codex им не доверял и ждал заново — отсюда лишний опрос. Сам прописал лечение: -на уведомление сразу обрабатывать результат, а не запускать `wait_agent` повторно. - -## Prior art: obra:superpowers `subagent-driven-development` - -Нашли, что чужой навык глубоко проработан и стоит на той же идее: оркестратор не делает работу -сам, держит контекст чистым, субагенты — «свежий контекст». По части ядра мы переизобретали -его. - -**Берём оттуда:** - -- **Ревьюер читает код сам и не верит докладу** — это жёсткое правило убивает Пожар A по - построению (координатор перестаёт быть верификатором). -- **Модель по роли** (минимально достаточная: дешёвая — на механику, сильная — на архитектуру - и ревью). Поправка под нас: наш implementer «толстый» (`/goal`), ему нужна сильная модель; - дешёвая выигрывает на субагенте-верификаторе простых находок, docs-проверках и диагностике. -- **Статус-контракт воркера** `DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT` — - протокол эскалации, которого у нас нет. -- **Качественная стадия ревью** (хорош ли код, межмодульные инварианты). - -**Не берём (сознательно другой выбор):** - -- У superpowers **толстый план** (~2000 строк, почти реализация) + тонкий механический - implementer. У нас **тонкий issue** (acceptance criteria) + толстый `/goal`, который сам - додумывает реализацию и самопроверяется. Для учебного репозитория наш путь лучше: issue - читаемы менти, реальное решение живёт в петле, нет огромного плана. -- Их **спек-стадия ревью** у нас по большей части избыточна: «выполнили ли спеку» уже - проверяет петля `/goal`. - -Вывод: `coordinator-loop` остаётся отдельным навыком (своя идентичность — цепочка issue из -`/to-issues`, гейт-классификация находок, владение коммитом). Заимствуем механику делегирования, -а не план-центричную философию. - -## Решения сессии - -**Принято (дёшево, метрически обосновано):** - -1. Координатор **не читает diff ради проверки находки** — чтение кода уходит ревьюеру-субагенту - (он читает код сам и возвращает только вердикт). Чинит Пожар A (413 КБ). -2. **Доверять push, не крутить `wait_agent` по кругу**: пришло `` — - сразу обрабатывать; один разумный статус-таймер вместо polling-цикла. Возможно, самый - дешёвый одиночный выигрыш (сток 947 КБ почти случайный, не дизайн). - -**Намеренная цена — НЕ трогать:** - -- `/goal`-петля (~400K токенов/задача) — сознательный обмен на качество решения; -- независимое межмодульное ревью на пороге риска; -- декомпозиция «тонкий issue + толстый `/goal`». - -**Кандидаты-фиксы (не приняты, проверить на прогоне):** - -- точечные тесты в петле, полный тест-сет — только на гейте (риск пропустить межмодульный - регресс в середине петли ловит гейт + межмодульный ревьюер); -- отчёты в формате индекса, а не нарратива; -- демоушн закрытых issue в компактную durable-форму (`summary`), чтобы компактизация её не - уничтожала; -- файловый канал в общем дереве для обмена находками (оркестрация по ссылке, а не payload - через контекст); -- модель по роли. - -## Связь с handoff про наблюдаемость - -Есть параллельный handoff `2026-06-14-observability-design.md` (в dotfiles, в каталоге навыка), -где уже спроектирован файловый канал `coordinator-runs/` (live-логи + `summary.md`, чтение по -требованию, координатор не ведёт лог сам). Это **тот же** файловый канал, что нужен нашему -кандидату-фиксу. **Свести в один дизайн, не строить две файловые системы.** Оба не реализованы — -слить легко. - -## Открытые вопросы (с моей рекомендацией, но не закрыты) - -1. **Объём первого захода.** A — полная переделка сразу; B — внести только два дёшевых правила, - остальное пометить «проверить на следующем прогоне». Рекомендация: **B** (держит навык от - разрастания). -2. **Кто верифицирует находку** — автор-воркер со своим знанием кода и проверяемым обоснованием, - или свежий ревьюер? Склонялись к автору на знании + независимый на пороге риска. Не закрыто. -3. **Слить ли два handoff** (этот и про наблюдаемость) в один дизайн до правки `SKILL.md`? - Рекомендация: да. -4. **Кросс-хост.** Файловый канал отчасти оправдан тем, что host-agnostic (Codex и Claude Code). - Если на деле только Codex — обоснование слабее. Уточнить требование. - -## Числа-ориентиры для следующего прогона - -Чтобы измерить, помогли ли фиксы, а не поверить на слово: - -- пик контекста координатора: было 77 % окна (199K/258K) — должно заметно упасть; -- собственные diff-чтения координатора: было 413 КБ — должно стремиться к нулю; -- сессия ожиданий/опроса: было 947 КБ при 42/44 таймаутах — push обрабатывается, цикла нет; -- прогоны полного тест-сета: было 103 — точечные в петле, полный только на гейте. - -## Что ещё не сделано - -- Решения не внесены в `SKILL.md`. -- Кандидаты-фиксы не приняты и не проверены на реальном прогоне. -- Два handoff не сведены. -- Не решён объём первого захода (вопрос 1 выше). - -## Рекомендуемые следующие шаги - -1. Решить объём первого захода (A vs B). -2. Свести этот handoff с handoff про наблюдаемость в один дизайн. -3. Внести минимум в `SKILL.md` (два принятых правила), сверяясь с superpowers как prior art. -4. На ближайшем реальном прогоне замерить числа-ориентиры выше; по факту резать или добавлять. -5. Опционально — лёгкая дивергенция/конвергенция через `brainstorm-with-docs`, если решение - захочется поискать шире. Возможно, и не понадобится. - -## Suggested skills - -- `write-a-skill` — при переносе правил в `SKILL.md`, чтобы не раздувать основной файл. -- `brainstorm-with-docs` — если делать полноценный заход с дивергенцией/конвергенцией. -- `conventional-commits` — для коммитов изменений в навыке. +Здесь оставлен только указатель: диагностика, на которой стоит handoff, снята с прогона +именно этого репозитория (фичи `feature-data-generator` и +`generator-model-time-startup-history` под `/coordinator-loop`).