Gerando um handbook

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

Este é o único comando caro. Tudo nesta página trata de gastar menos com ele e obter mais dele.

Comece barato, depois faça upgrade

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

Seguir essa ordem significa que você nunca paga por fichas profundas em cima de um esqueleto que está prestes a descartar.

--detail brief vs deep

deep vale a pena quando um agente vai usar o handbook, porque as notas por função são o que transforma a página de uma etapa em um catálogo de endereços. brief é a escolha certa para uma primeira passada, para um repositório muito grande, ou quando você quer principalmente a estrutura.

Você pode misturar: gere com brief em tudo e depois reexecute --phase 2a --detail deep --resume apontando --source para o subdiretório que mais lhe interessa.

--synth-mode oneshot vs doctor

oneshot sintetiza um esqueleto em uma única passada. Rápido, barato, geralmente razoável.

doctor executa um loop de reparo ator–crítico: propõe no máximo três mudanças estruturais, revisa-as com três críticos (engenheiro, arquiteto, leitor), valida as sobreviventes mecanicamente contra o grafo real, aplica, reatribui, repete.

--strategy file vs member

file (padrão) — o LLM sintetiza o esqueleto; um arquivo-fonte é a unidade folha. Escala para repositórios grandes. Use esta a menos que tenha um motivo para não usar.

member — você escreve o skeleton.yaml; funções e métodos individuais são classificados nas suas etapas, e os artefatos em nível de arquivo são derivados disso.

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 custa mais — cada função é classificada — mas produz uma prosa mais precisa, e a phase 2c se torna gratuita porque a organização é derivada de forma determinística.

Executando fases separadamente

--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

Cada fase lê apenas seus artefatos upstream, portanto isso é sempre seguro. Os casos comuns:

Retomando e cache

• --resume pula arquivos que já têm uma ficha completa na profundidade solicitada. As fichas são gravadas à medida que ficam prontas, então Ctrl-C é sempre seguro.
• --llm-cache guarda as respostas brutas em <work>/phase3/cache, com chave por modelo, prompt e opções. Reexecuções enquanto você itera se tornam quase gratuitas.
• --refresh ignora os caches da phase 3. Use-o quando você mudou as entradas do prompt mas a chave do cache não percebeu — por exemplo, depois de editar o skeleton.yaml à mão.

--refresh desativa --llm-cache naquela execução, por design.

Observando o trabalho

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)

O uso de tokens é registrado em run-manifest.json quando a execução termina.

Quando o resultado está errado

Mais em Solução de problemas.