Tu primer handbook real

Este es el ciclo completo sobre un repositorio real. Está escrito para seguirse en orden, y coloca a propósito las comprobaciones gratuitas antes que las caras.

alias handbook="node $(pwd)/packages/cli/dist/main.js"
export REPO=~/code/myrepo
export WORK=work/myrepo

Paso 1 — Mira antes de saltar

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

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

Esto es gratis y es tu prueba de humo. Sin LLM, sin clave, sin tokens.

Corrige cualquiera de los puntos anteriores ahora. Cada problema aquí se convierte en un problema más caro después.

Paso 2 — Genera el handbook

Este es el paso que cuesta tokens. En un repositorio mediano, espera minutos.

Empieza barato:

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

Eso equivale a --detail brief y --synth-mode oneshot: una ficha corta por archivo y un esqueleto de una sola pasada. Es la forma más rápida de ver si la forma del handbook es la correcta.

Mira $WORK/phase2/skeleton.yaml. ¿La lista de etapas se parece a tu sistema? Si sí, sube de nivel:

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

--phase 2a --resume profundiza solo las fichas, saltándose los archivos que ya tienen una completa. Conservas el esqueleto que ya validaste.

Si el esqueleto está mal, vuelve a ejecutar 2b con el bucle actor–crítico en su lugar:

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

Paso 3 — Renderízalo

handbook render --work $WORK --title "MyRepo Handbook" \
    --html --html-single --agent-site --llms-txt

Sin LLM. Ejecútalo tan a menudo como quieras — en CI, en cada commit.

Añade --source-base-url https://github.com/me/myrepo/blob/main para convertir cada ruta de archivo del handbook en un enlace al archivo real. Sin él, la salida no contiene ninguna URL externa, lo que importa en una base de código privada.

Abre $WORK/handbook/html/overview.html y léelo. Este es el momento de juzgar si el handbook vale algo.

Paso 4 — Empaquétalo para tu agente

handbook skill --handbook $WORK/handbook --out skills/myrepo \
    --name myrepo --project "MyRepo" \
    --work $WORK --source $REPO \
    --agent-dir $WORK/handbook/agent

--work + --source juntos producen coverage.json: un hash de contenido por archivo. Eso es lo que hace que la deriva del handbook sea detectable en lugar de silenciosamente errónea más adelante.

--agent-dir incluye el índice para agentes y sus tablas de hechos, y le da al protocolo de enrutamiento de la SKILL sus recetas de grep — de modo que el agente puede convertir el nombre de un símbolo en path:startLine-endLine con un solo comando, en lugar de leer prosa y adivinar.

Paso 5 — Valídalo

handbook validate --skill skills/myrepo --source $REPO

Comprueba la estructura, el contrato del frontmatter, la consistencia índice ↔ página de etapa, y vuelve a hashear tu código fuente para informar de las páginas que se han quedado atrás. Sale con código 2 en caso de fallo, así que este es el comando que debes poner en CI.

Paso 6 — Planifica un cambio real

handbook plan --source $REPO --handbook skills/myrepo/references \
    --request "Retry failed uploads three times before giving up" \
    --out plan.md

Un bucle de agente de solo lectura: lista, lee y hace grep — no tiene ninguna herramienta de escritura — enruta con el handbook, verifica contra el código fuente real y escribe plan.md.

Lee el plan. Léelo de verdad. Termina con un bloque de declaraciones legible por máquina:

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

Paso 7 — Aplícalo, con un camino de vuelta

handbook apply --source $REPO --plan plan.md --dry-run   # verify only, never writes
handbook apply --source $REPO --plan plan.md             # for real

El dry run no es opcional en espíritu. Resuelve cada ancla contra el contenido actual de los archivos y te dice exactamente qué ediciones aterrizarían.

Aplicar imprime el directorio de la copia de seguridad. Cópialo a algún sitio antes de necesitarlo:

handbook rollback --backup $REPO/.handbook-patches/2026-08-08T14-05-11-204Z

El rollback (la reversión) rechaza cualquier archivo que cambió después del parche, a menos que pases --force — porque restaurarlo destruiría silenciosamente ese trabajo. Consulta Aplicar cambios para las cuatro reglas de seguridad.

Paso 8 — Haz avanzar el handbook

El código se movió. No regeneres — haz un resync.

Un caso es un directorio que tú montas:

cases/upload-retry/
  edited/       copy of the repo after the change   (required)
  plan.md       the plan from step 6                (optional — sharpens scope)
  change.diff   unified diff of the change          (optional — widens scope)

mkdir -p cases/upload-retry
cp -R $REPO cases/upload-retry/edited
cp plan.md cases/upload-retry/
handbook resync --case cases/upload-retry --work $WORK

Resync vuelve a analizar el árbol editado, hace diff del grafo viejo contra el nuevo y regenera solo lo que cambió. Las salidas ya renderizadas bajo $WORK/handbook se refrescan automáticamente.

¿No tienes un endpoint a mano? --no-llm refresca los hechos estructurales y marca la prosa como obsoleta, en lugar de fingir que está al día.

Si tu repositorio es muy grande

Más en Coste y rendimiento.

A continuación