Generar un handbook

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

Este es el único comando costoso. Todo lo que hay en esta página trata de gastar menos en él y de sacarle más provecho.

Empieza barato y luego mejora

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

Hacerlo en este orden significa que nunca pagas por fichas deep encima de un esqueleto que estás a punto de descartar.

--detail brief vs deep

Deep vale la pena cuando un agente va a usar el handbook, porque las notas por función son lo que convierte la página de una etapa en un directorio de direcciones. Brief es lo adecuado para una primera pasada, para un repositorio muy grande, o cuando lo que más te interesa es la estructura.

Puedes mezclar: genera en brief en todas partes y luego vuelve a ejecutar --phase 2a --detail deep --resume tras apuntar --source al subdirectorio que más te importa.

--synth-mode oneshot vs doctor

oneshot sintetiza un esqueleto en una sola pasada. Rápido, barato y, por lo general, razonable.

doctor ejecuta un bucle de reparación actor–crítico: proponer como máximo tres cambios estructurales, revisarlos con tres críticos (ingeniero, arquitecto, lector), validar los supervivientes mecánicamente contra el grafo real, aplicar, reasignar, repetir.

--strategy file vs member

file (por defecto) — el LLM sintetiza el esqueleto; un archivo fuente es la unidad hoja. Escala a repositorios grandes. Úsalo salvo que tengas una razón para no hacerlo.

member — tú redactas skeleton.yaml; las funciones y métodos individuales se clasifican en tus etapas, y los artefactos a nivel de archivo se derivan de eso.

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 cuesta más — se clasifica cada función — pero produce una prosa más precisa, y la phase 2c sale gratis porque la organización se deriva de forma determinista.

Ejecutar fases por separado

--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 lee solo sus artefactos aguas arriba, así que esto siempre es seguro. Los casos comunes:

Reanudar y caché

• --resume omite los archivos que ya tienen una ficha completa en la profundidad solicitada. Las fichas se escriben a medida que se completan, así que Ctrl-C siempre es seguro.
• --llm-cache guarda en caché las respuestas crudas bajo <work>/phase3/cache, indexadas por modelo, prompt y opciones. Las re-ejecuciones mientras iteras se vuelven casi gratuitas.
• --refresh ignora las cachés de la phase 3. Úsalo cuando cambiaste las entradas del prompt pero la clave de caché no se dio cuenta — por ejemplo, tras editar skeleton.yaml a mano.

--refresh desactiva --llm-cache para esa ejecución, por diseño.

Ver cómo trabaja

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)

El uso de tokens queda en run-manifest.json cuando la ejecución termina.

Cuando el resultado es incorrecto

Más en Solución de problemas.