Генерация handbook

handbook generate --source <repo> --work <workdir> [options]

Это единственная дорогая команда. Всё на этой странице — о том, как тратить на неё меньше и получать от неё больше.

Начните дёшево, затем углубляйте

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

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

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

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

Такой порядок означает, что вы никогда не платите за глубокие карточки поверх скелета, который вот-вот выбросите.

--detail brief против deep

Режим deep оправдан, когда handbook будет использовать агент, потому что именно заметки по функциям превращают страницу этапа в адресную книгу. Режим brief подходит для первого прохода, для очень большого репозитория или когда вам в основном нужна структура.

Режимы можно смешивать: сгенерируйте brief везде, затем перезапустите --phase 2a --detail deep --resume, направив --source на подкаталог, который важнее всего.

--synth-mode oneshot против doctor

oneshot синтезирует скелет за один проход. Быстро, дёшево, обычно разумно.

doctor запускает цикл починки «актор–критик»: предложить не более трёх структурных изменений, рассмотреть их тремя критиками (инженер, архитектор, читатель), проверить выживших механически по реальному графу, применить, переназначить, повторить.

--strategy file против member

file (по умолчанию) — скелет синтезирует LLM; листовой единицей является исходный файл. Масштабируется на большие репозитории. Используйте эту стратегию, если нет причин поступить иначе.

member — skeleton.yaml пишете вы; отдельные функции и методы классифицируются по вашим этапам, а артефакты уровня файлов выводятся из этого.

metadata:
  version: 1
  archetype: HTTP API server
stages:
  - id: stage-1
    title: Request intake
    description: Accepting connections, parsing requests, and routing them.
    parent: null
    children: []
    crosscut: false
  - id: stage-2
    title: Business logic
    description: What the service actually does with a validated request.
    parent: null
    children: []
    crosscut: false
  - id: crosscut-1
    title: Configuration and logging
    description: Cross-cutting infrastructure used by every stage.
    parent: null
    children: []
    crosscut: true

handbook generate --source $REPO --work $WORK --strategy member --skeleton skeleton.yaml

Стратегия member стоит дороже — классифицируется каждая функция, — но даёт более точную прозу, а phase 2c становится бесплатной, потому что организация выводится детерминированно.

Запуск фаз по отдельности

--phase 1        # just the graph (same as `handbook analyze`)
--phase 2a       # just the cards
--phase 2b       # just skeleton + assignment
--phase 2c       # just the grouping
--phase 3        # just narration + registers
--phase 2        # 2a + 2b + 2c
--phase 2c,3     # a comma list

Каждая фаза читает только свои артефакты, лежащие выше по потоку, поэтому это всегда безопасно. Типичные случаи:

Возобновление и кэширование

• --resume пропускает файлы, у которых уже есть полная карточка на запрошенной глубине. Карточки записываются по мере готовности, так что Ctrl-C всегда безопасен.
• --llm-cache кэширует сырые ответы в <work>/phase3/cache с ключом по модели, промпту и опциям. Повторные запуски во время итераций становятся почти бесплатными.
• --refresh игнорирует кэши phase 3. Используйте его, когда вы изменили входные данные промпта, а ключ кэша этого не заметил — например, после ручного редактирования skeleton.yaml.

--refresh отключает --llm-cache для этого запуска — так задумано.

Наблюдение за работой

handbook generate --source $REPO --work $WORK -v

[scan] auto root=/Users/me/code/api
[scan] typescript: 284 files
[2a] batch 12/36 · 96 cards
[2b] 9 stages; 0 files unassigned
[3] narrating stage-4 (2 children)

Использование токенов записывается в run-manifest.json по завершении запуска.

Когда результат неверен

Подробнее в разделе Устранение неполадок.