Куда на самом деле уходят токены, какие ручки действительно что-то меняют и как это выяснить до того, как потратить хоть что-нибудь.

Узнайте до того, как потратить

handbook analyze --source $REPO --work $WORK

{ "files": 412, "functions": 3187, "edgesKept": 9042, "edgesDropped": 611, "filesUnparsed": 3 }

Бесплатно. Именно число files определяет стоимость, потому что phase 2a — самая дорогая фаза — примерно линейна по нему.

Куда уходят токены

Фаза	Доля типичного запуска	Масштабируется с
1 analyze	0%	—
2a карточки	60–80%	число файлов × `--detail`
2b скелет + назначение	10–20%	число файлов, и значительно больше с `--synth-mode doctor`
2c организация	5%	число этапов
3 повествование + регистры	5–15%	число этапов, сильно кэшируется

Если хотите тратить меньше, phase 2a — единственное место, которое имеет значение.

Ручки, по убыванию эффекта

1. `--detail brief` вместо `deep`

В несколько раз дешевле. Brief — это назначение, роль и жизненный цикл; deep добавляет разбор на 120–300 слов плюс заметку на каждую функцию и уменьшает размер пакета с 8 файлов до 1.

handbook generate --source $REPO --work $WORK                       # brief
handbook generate --source $REPO --work $WORK --phase 2a --detail deep --resume  # upgrade later

2. Ограничьте `--source` тем, что вам важно

Граф строится из того, что вы сканируете. Задокументировать один сервис внутри монорепозитория стоит долю от документирования всех сразу:

handbook generate --source $REPO/services/payments --work work/payments

3. `--max-chars-per-file`

handbook generate --source $REPO --work $WORK --max-chars-per-file 20000

Ограничивает, сколько содержимого любого отдельного файла вообще отправляется. Сгенерированные файлы, вендорные бандлы и гигантские операторы switch — чистая стоимость без капли информации. 0 (по умолчанию) означает «без ограничения».

4. `--llm-cache`, пока вы итерируете

handbook generate --source $REPO --work $WORK --llm-cache

Кэширует сырые ответы с ключом по модели, промпту и опциям. Повторный запуск после правки становится почти бесплатным. Добавьте --refresh, когда намеренно хотите игнорировать кэш.

5. `--synth-mode oneshot`, если только не нужен `doctor`

Doctor выполняет несколько раундов предложений плюс по три критика в каждом. Он уместен, когда одношаговый синтез выдал перекошенные или бессмысленные этапы, и он чистые накладные расходы, когда не выдал.

6. Модель подешевле там, где это не важно

Фазы по-разному вознаграждают сильную модель:

Фаза	Чувствительность к модели
2a карточки	Средняя — небольшая модель пишет пригодные назначения
2b скелет	Высокая — это то самое суждение, на котором держится весь handbook
2c организация	Низкая — она всё равно деградирует до детерминированного порядка
3 повествование	Выше средней — это проза, которую читают люди
`plan`	Наивысшая — байт-точные якоря не прощают ошибок

Поскольку фазы запускаются по отдельности, модели можно смешивать:

handbook generate --source $REPO --work $WORK --phase 2a --model cheap-model
handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --model strong-model

Скорость

Стоимость и скорость — разные проблемы. Эти флаги меняют время выполнения, а не расход:

Флаг	По умолчанию	Повышайте, когда
`--llm-concurrency <n>`	`16`	Ваш эндпоинт это выдерживает. Глобальный потолок
`--read-workers <n>`	`12`	Узкое место — phase 2a
`--assign-workers <n>`	`12`	Узкое место — phase 2b
`--organize-workers <n>`	`8`	Узкое место — phase 2c
`--narrate-workers <n>`	`8`	Узкое место — phase 3
`--read-batch-size <n>`	1 deep / 8 brief	Меньше запросов, но крупнее. Следите за усечением

--llm-concurrency ограничивает всё остальное. Подняв --read-workers до 40 при --llm-concurrency 16, вы получите 16.

Ограничения частоты выглядят как сбои

Если в логе видны повторные попытки, сначала понизьте --llm-concurrency, а уже потом повышайте --llm-retries. Упорнее ретраить упор в ограничение частоты — значит потратить те же токены дважды.

Чтение стоимости запуска

<work>/run-manifest.json

{
  "model": "gpt-4o-mini",
  "phases": ["1", "2a", "2b", "2c", "3"],
  "startedAt": "2026-08-08T13:02:11.004Z",
  "finishedAt": "2026-08-08T13:19:44.881Z",
  "usage": { "promptTokens": 1840221, "completionTokens": 214880, "totalTokens": 2055101 }
}

jq '.usage, (.finishedAt, .startedAt)' work/api/run-manifest.json

Он описывает последний успешный запуск. Провалившийся запуск оставляет предыдущий манифест нетронутым; прерванный не пишет ничего.

Разумная лестница

Бесплатно

handbook analyze --source $REPO --work $WORK

Проверьте число файлов, dropped-calls.json и scan-coverage.json. Ненулевой filesUnparsed — это дыра в руководстве, за которое вы вот-вот заплатите. Почините сканирование, прежде чем что-то тратить.

Дёшево — верна ли форма?

handbook generate --source $REPO --work $WORK --llm-cache

Прочитайте phase2/skeleton.yaml. Если этапы неверны, исправьте это, прежде чем углублять прозу.

Почините структуру, если нужно

handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor

Углубите, когда структура верна

handbook generate --source $REPO --work $WORK --phase 2a --detail deep --resume

Больше никогда за это не платите

handbook render ...      # free, deterministic, run in CI
handbook skill ...       # free
handbook validate ...    # free
handbook resync ...      # proportional to the change

Очень большие репозитории

Файлов	Рекомендация
< 200	Сразу `--detail deep --synth-mode doctor`
200–1,000	Сначала brief, затем углубляйте выборочно
1,000–5,000	Brief, `--max-chars-per-file 20000`, и подумайте об отдельном handbook на подсистему
> 5,000	Один handbook на подсистему. Единый handbook на 5 000+ файлов не будет ни дешёвым, ни читаемым

Несколько handbook — это нормально: это просто несколько рабочих каталогов и несколько пакетов SKILL, каждый с более точным описанием, чем было бы у одного гигантского.

Стоимость и производительность