docs(delegation): бюджет пишется в промпт сабагента, а не держится в голове #3077

Merged

lekss361 merged 1 commit from docs/delegation-agent-budget into main

2026-08-24 16:02:01 +00:00

lekss361 commented

2026-08-24 15:59:49 +00:00

Owner

Что случилось

Прогон разведки 2026-08-24 упёрся в три отказа подряд, и все три — следствие одного пробела в каноне.

агент	что должен был	что делал	итог
`repo-hygiene`	список веток с неотправленной работой	диффал SQL-миграции, разбирал `_next` в Caddyfile	157 ходов, результата нет
`mera-b2c`	этапы запуска из документов в корне	читал `estimator.py`	178 ходов
`mera-b2c`	отдать items по схеме	собрал 17 739 байт в один вызов	`InputValidationError`, работа потеряна целиком

Почему канон не сработал

delegation.md уже содержал и «~≤20 tool-calls», и «границы: что НЕ делать». Но всё это записано как ориентир для оркестратора. Агент этих строк не видит: лимит, оставшийся в голове вызывающего, не ограничивает никого. Промпты были написаны без потолка — при формально соблюдённом правиле.

Отсюда главная правка: бюджет обязан быть текстом внутри промпта. Потолок вызовов и времени, список запрещённого, и правило деградации «бюджет кончается → отдай что есть, допиши в notes что не успел». Последнее важно отдельно: агент без него молча продолжает копать, потому что альтернативы «сдаться частично» ему никто не предложил.

Потолок размера ответа — отдельный пункт, не следствие токенов

Эмпирика #2203-эпохи в файле уже была («агент на 186k tok / 33 calls упал на StructuredOutput»), но записана как история про токены. Отказ другой: payload больше ~10k символов не парсится как JSON, дальше повтор, дальше потеря всей работы. Токенов при этом может быть немного.

Практическое следствие, вынесенное явно: схему надо проектировать под краткость. Поле detail с описанием «2-5 предложений» — это приглашение к отказу, если items может быть десяток.

Новая секция «Целость результата workflow»

Второй класс проблем, вскрытый тем же прогоном: завершившийся прогон не значит успешный. В одном из прогонов 5 агентов из 10 умерли на обрыве соединения; parallel() вернул на их месте null, стадия синтеза отработала на выживших и выдала уверенный текст с числами и ссылками на file:line. Числа при выборочной проверке оказались верными — но проверять пришлось руками, и без этой проверки вердикт был бы неотличим от выдуманного.

В секции: чтение <failures> и journal.jsonl, восстановление через resumeFromRunId (готовые агенты реплеятся из кэша, правило префикса при правке промпта), диагностика зависшего агента по возрасту записи в agent-*.jsonl и типу последнего события, и отличие «завис» от «обрыв соединения, лечится сам».

Плюс грабля Windows: перезапись скрипта workflow через python даёт CRLF, и запуск отбивается на script contains control characters — при том, что синтаксис файла валиден.

Границы

Только .claude/rules/delegation.md, +10 строк, кода не касается. Те же правила добавлены в личный ~/.claude/CLAUDE.md (вне репо) — чтобы действовали и в других окнах, и в других проектах.

Test plan

Правила применены на живом прогоне: два промпта переписаны с потолком 25 вызовов, запретом читать исходники и лимитом ответа ≤6000 символов
Восстановление через TaskStop + resumeFromRunId проверено — 5 готовых разведчиков вернулись из кэша, перезапустились только два изменённых
Проверка на следующем фан-ауте: ни один агент не превышает потолок, ни один не падает на StructuredOutput

## Что случилось Прогон разведки 2026-08-24 упёрся в три отказа подряд, и все три — следствие одного пробела в каноне. | агент | что должен был | что делал | итог | |---|---|---|---| | `repo-hygiene` | список веток с неотправленной работой | диффал SQL-миграции, разбирал `_next` в Caddyfile | 157 ходов, результата нет | | `mera-b2c` | этапы запуска из документов в корне | читал `estimator.py` | 178 ходов | | `mera-b2c` | отдать items по схеме | собрал 17 739 байт в один вызов | `InputValidationError`, работа потеряна целиком | ## Почему канон не сработал `delegation.md` уже содержал и «~≤20 tool-calls», и «границы: что НЕ делать». Но всё это записано как **ориентир для оркестратора**. Агент этих строк не видит: лимит, оставшийся в голове вызывающего, не ограничивает никого. Промпты были написаны без потолка — при формально соблюдённом правиле. Отсюда главная правка: **бюджет обязан быть текстом внутри промпта.** Потолок вызовов и времени, список запрещённого, и правило деградации «бюджет кончается → отдай что есть, допиши в notes что не успел». Последнее важно отдельно: агент без него молча продолжает копать, потому что альтернативы «сдаться частично» ему никто не предложил. ## Потолок размера ответа — отдельный пункт, не следствие токенов Эмпирика #2203-эпохи в файле уже была («агент на 186k tok / 33 calls упал на StructuredOutput»), но записана как история про токены. Отказ другой: payload больше ~10k символов **не парсится как JSON**, дальше повтор, дальше потеря всей работы. Токенов при этом может быть немного. Практическое следствие, вынесенное явно: схему надо проектировать под краткость. Поле `detail` с описанием «2-5 предложений» — это приглашение к отказу, если items может быть десяток. ## Новая секция «Целость результата workflow» Второй класс проблем, вскрытый тем же прогоном: **завершившийся прогон не значит успешный.** В одном из прогонов 5 агентов из 10 умерли на обрыве соединения; `parallel()` вернул на их месте `null`, стадия синтеза отработала на выживших и выдала уверенный текст с числами и ссылками на `file:line`. Числа при выборочной проверке оказались верными — но проверять пришлось руками, и без этой проверки вердикт был бы неотличим от выдуманного. В секции: чтение `<failures>` и `journal.jsonl`, восстановление через `resumeFromRunId` (готовые агенты реплеятся из кэша, правило префикса при правке промпта), диагностика зависшего агента по возрасту записи в `agent-*.jsonl` и типу последнего события, и отличие «завис» от «обрыв соединения, лечится сам». Плюс грабля Windows: перезапись скрипта workflow через python даёт CRLF, и запуск отбивается на `script contains control characters` — при том, что синтаксис файла валиден. ## Границы Только `.claude/rules/delegation.md`, +10 строк, кода не касается. Те же правила добавлены в личный `~/.claude/CLAUDE.md` (вне репо) — чтобы действовали и в других окнах, и в других проектах. ## Test plan - [x] Правила применены на живом прогоне: два промпта переписаны с потолком 25 вызовов, запретом читать исходники и лимитом ответа ≤6000 символов - [x] Восстановление через `TaskStop` + `resumeFromRunId` проверено — 5 готовых разведчиков вернулись из кэша, перезапустились только два изменённых - [ ] Проверка на следующем фан-ауте: ни один агент не превышает потолок, ни один не падает на `StructuredOutput`

lekss361 added 1 commit 2026-08-24 15:59:49 +00:00

docs(delegation): бюджет пишется в промпт сабагента, а не держится в голове

CI Trade-In / changes (pull_request) Successful in 10s

Details

CI Trade-In / backend-tests (pull_request) Has been skipped

Details

CI Trade-In / browser-tests (pull_request) Has been skipped

Details

CI / changes (pull_request) Successful in 12s

Details

CI Trade-In / frontend-checks (pull_request) Has been skipped

Details

CI / backend-tests (pull_request) Has been skipped

Details

CI / frontend-tests (pull_request) Has been skipped

Details

CI / openapi-codegen-check (pull_request) Has been skipped

Details

98aad7b985

Два разведчика без потолка ушли на 157 и 178 ходов вместо инвентаризации:
один вместо списка веток диффал SQL-миграции и разбирал Caddyfile. Третий
собрал 17 739 байт в один StructuredOutput, получил InputValidationError и
потерял всю работу целиком.

Канон уже говорил «~≤20 tool-calls» и «границы: что НЕ делать» — но как
ориентир для оркестратора. Агент этого не видит: лимит, оставшийся в голове
вызывающего, не ограничивает никого. Отсюда правка — бюджет обязан быть
текстом внутри промпта, вместе со списком запрещённого и правилом деградации
«отдай что есть, допиши в notes что не успел».

Отдельным пунктом — потолок РАЗМЕРА структурированного ответа. Он не следует
из лимита токенов: payload больше ~10k символов не парсится, повтор, и работа
теряется. Схему надо проектировать под краткость, длинные detail-поля
провоцируют ровно этот отказ.

Новая секция «Целость результата workflow»: завершившийся прогон не значит
успешный — упавшие агенты возвращают null, parallel() их молча проглатывает,
а синтез всё равно пишет уверенный текст с числами. Плюс восстановление через
resumeFromRunId, диагностика зависшего агента по возрасту записи в
agent-*.jsonl, и грабля Windows: перезапись скрипта через python даёт CRLF,
запуск отбивается на control characters.