¿Qué es Handbooks?

Un código base entra. Salen dos manuales.

Handbooks escribe el mismo mapa de tu código dos veces, porque tiene dos lectores muy distintos:

Debajo están los mismos hechos — un grafo de llamadas construido por el parser — así que los dos nunca pueden contradecirse. Uno optimiza narrativa y navegación; el otro, enrutamiento y detección de obsolescencia.

El problema, dicho llanamente

Tienes un repositorio. Es demasiado grande para tenerlo en la cabeza, y demasiado grande para que quepa en una ventana de contexto.

Pídele a un agente de código «reintenta las subidas fallidas tres veces» y parcheará con toda confianza la única función de subida que encontró — y se le escaparán la constante de la política de reintentos, la implementación espejo en el worker de lotes, la métrica que cuenta los intentos y el test que asevera el comportamiento antiguo.

Eso no es un fallo de razonamiento. Es un fallo de enrutamiento. El agente nunca vio un mapa.

Pruébalo antes de seguir leyendo

Nada de lo que hay más abajo importa si no se ejecuta. Esto tarda unos treinta segundos, gasta cero tokens y no necesita clave de API:

git clone <this repo> && cd handbooks
pnpm install && pnpm build
pnpm demo

pnpm demo ejecuta la cadena de herramientas completa contra un proyecto de ejemplo incluido, usando un servidor mock de LLM también incluido. Cuando termina tendrás en disco un handbook renderizado, un sitio HTML, un índice localizador para agentes y un paquete SKILL validado.

Las tres ideas sobre las que está construido

1. Los hechos vienen de un parser, no de un modelo

Handbooks parsea cada archivo fuente con tree-sitter y construye un grafo de llamadas tipado: funciones, métodos, aristas de llamada resueltas a través de self/atributos/parámetros/imports, llamadas que salen de tu código y llamadas que no pudo resolver — puestas en cuarentena en su propio archivo, nunca adivinadas.

Los archivos que no pudo leer ni parsear en absoluto quedan en cuarentena igual: un hueco que puedes enumerar, nunca uno que desaparece en silencio.

Esta capa nunca toca un LLM. Ejecútala dos veces y obtendrás el mismo grafo dos veces.

2. La prosa se superpone a los hechos, y va etiquetada

Un LLM escribe la parte legible por humanos: para qué sirve un archivo, cómo se articula un subsistema, qué estado fluye por qué etapas. Siempre está anclada al grafo y, cuando falla, la estructura se publica igualmente — con una descripción vacía.

Una frase ausente es mejor que una inventada.

3. El mapa está hecho para enrutar, no para leer

La salida no es un resumen de tu código. Es un índice que responde «¿qué archivos, funciones y estado tiene que tocar este cambio?» — incluidos los dispersos y poco obvios. El planner usa después ese índice, lee el código fuente real en cada dirección que encontró y emite un plan de edición lo bastante exacto al byte como para aplicarse mecánicamente.

Lo que te da una ejecución

Para quién es esto

Lo que te cuesta

• Node.js ≥ 20.11 y pnpm. Esa es toda la instalación. Sin compilación nativa, sin Python, sin node-gyp — los parsers son WebAssembly.
• Un endpoint compatible con OpenAI para las fases con LLM. OpenAI alojado, Azure, vLLM, Ollama, LiteLLM, un proxy interno — cualquier cosa que hable /v1/chat/completions. Puede ser un modelo corriendo en tu propia máquina.
• Absolutamente nada para handbook analyze, que es el comando que deberías ejecutar primero.

Adónde ir ahora