Entra una base de código. Salen dos handbooks: uno que lee tu equipo, otro con el que se orienta tu agente.
Tu agente de código hace grep de un símbolo, encuentra tres de los siete lugares que importan y entrega media modificación. Eso no es un fallo de razonamiento: es un fallo de enrutamiento. Handbooks le da el mapa.
# pipeline completo, sin red, sin clave de API, ~30 s
pnpm install && pnpm build
pnpm demoProyecto de ejemplo incluido, LLM simulado incluido. Cero tokens gastados.
Siete comandos, un solo bucle
Los pasos verde azulado son deterministas: sin LLM, sin red, se vuelven a ejecutar gratis en CI. Los pasos ámbar hablan con tu endpoint y cachean lo que aprenden.
- 1
analyzeSIN LLMParsea cada archivo en un grafo de llamadas tipado.
- 2
generateLLMFichas, etapas, prosa, estado entre etapas.
- 3
renderSIN LLMMarkdown, HTML, índice para agentes, llms.txt.
- 4
skillSIN LLMLo empaqueta para tu agente de código.
- 5
planLLMLocaliza un cambio en ediciones exactas al byte.
- 6
applySIN LLMParche todo o nada, con rollback.
- 7
resyncLLMAdelanta el handbook. Sin reconstruirlo.
- Cómo funciona cada fase →
Por qué puedes confiar en lo que lees
Los hechos vienen de un parser
tree-sitter construye el grafo de llamadas: funciones, aristas resueltas, llamadas de frontera y las llamadas que no pudo resolver — puestas en cuarentena, nunca adivinadas. Esta capa nunca toca un LLM, así que es idéntica en cada ejecución.
La prosa va encima, y lo dice
Un LLM escribe para qué sirve un archivo y cómo se articula un subsistema, siempre anclado al grafo. Donde falla, la estructura se publica igualmente con una descripción vacía. Una frase ausente es mejor que una inventada.
Hecho para enrutar, no para leer
La salida responde «¿qué archivos, funciones y estado tiene que tocar este cambio?» — incluidos los dispersos y poco obvios que una búsqueda de texto no ve. Después el planner lee el código fuente real en cada dirección.
Aplicar es aburrido a propósito
Las anclas deben coincidir exactas al byte y una sola vez. Todo se verifica antes de escribir nada. Cada archivo tocado se respalda con su hash previo al parche, para que el rollback pueda demostrar qué está restaurando.
Se mantiene al día de forma incremental
Resync compara el grafo viejo con el nuevo y regenera solo lo que cambió de verdad. Toca tres archivos, paga por tres archivos. La documentación deja de pudrirse porque actualizarla dejó de ser caro.
Y divulga sus propios límites
Los lenguajes que lee el analizador guiado por configuración se nombran en la visión general, para que «relaciones de llamada best-effort» nunca pueda leerse como «exactas».
Fidelidad del análisis →Una ejecución. Seis formatos.
La generación es la parte cara y ocurre una vez. Todo lo de abajo es un re-render determinista que puedes ejecutar en cada commit.
Handbooks en Markdown
visión general · índice · una página por etapa · tabla de registros de estado
Sitio HTML multipágina
TOC fijo, migas de pan, selector de tema — funciona sobre file://
Una página autocontenida
un único .html que puedes enviar por correo o adjuntar a un ticket
Índice localizador para agentes
deber · conceptos de entrada · estado · ejemplares · co-cambios
llms.txt + llms-full.txt
la convención llms.txt, más todo el handbook aplanado
Paquete SKILL de agente
SKILL.md + references/ + un hash de contenido por archivo
Empieza por el comando gratuito
handbook analyze nunca necesita una clave de API. Ejecútalo sobre tu repo, mira los recuentos de archivos y funciones, y decide si el resto merece un solo token.