O que é o Handbooks?
Um código-fonte entra, dois manuais saem — um site de documentação narrado que o seu time lê e um índice de localização com que o seu agente de código se orienta. Do mesmo mapa parseado, sempre em dia com o código.
Um código-fonte entra. Saem dois manuais.
O Handbooks escreve o mesmo mapa do seu código duas vezes, porque tem dois leitores muito diferentes:
📖 O manual para humanos
Um site de documentação narrado etapa por etapa — busca, tema, links profundos — gerado do seu código e aberto direto de file://. Este você lê.
🤖 O manual para a IA
Um índice de localização em formato de máquina: tabelas de roteamento arquivo→etapa, fatos de chamadas por função, llms.txt e um pacote SKILL instalável. Este o seu agente de código lê.
Por baixo estão os mesmos fatos — um grafo de chamadas construído pelo parser — então os dois nunca podem discordar. Um otimiza narrativa e navegação; o outro, roteamento e detecção de desatualização.
O problema, dito com clareza
Você tem um repositório. Ele é grande demais para caber na sua cabeça — e grande demais para caber em uma janela de contexto.
Peça a um agente de codificação para "tentar novamente três vezes os uploads que falharem" e ele vai, cheio de confiança, corrigir a única função de upload que encontrou — e deixar passar a constante da política de retry, a implementação espelhada no worker de lote, a métrica que conta as tentativas e o teste que assevera o comportamento antigo.
Isso não é uma falha de raciocínio. É uma falha de roteamento. O agente nunca viu um mapa.
A versão em uma frase
O Handbooks lê seu código com um parser de verdade, constrói um mapa dele, entrega esse mapa ao agente como um índice de localização — não um resumo — e mantém o mapa atualizado conforme o código muda.
Experimente antes de continuar lendo
Nada do que vem abaixo importa se não rodar. Isto leva cerca de trinta segundos, gasta zero tokens e não precisa de chave de API:
git clone <this repo> && cd handbooks
pnpm install && pnpm build
pnpm demopnpm demo executa a cadeia de ferramentas inteira contra um projeto de exemplo
embutido, usando um servidor de LLM simulado também embutido. Ao terminar, você terá em
disco um handbook renderizado, um site HTML, um índice localizador para agentes e um
pacote SKILL validado.
As três ideias em que ele se apoia
1. Fatos vêm de um parser, não de um modelo
O Handbooks analisa cada arquivo-fonte com tree-sitter e
constrói um grafo de chamadas tipado: funções, métodos, arestas de chamada resolvidas via
self/atributos/parâmetros/imports, chamadas que saem do seu código e chamadas que ele
não conseguiu resolver — postas em quarentena em um arquivo próprio, nunca adivinhadas.
Os arquivos que ele não conseguiu ler nem analisar ficam em quarentena do mesmo jeito — uma lacuna que você pode enumerar, nunca uma que some em silêncio.
Essa camada nunca toca um LLM. Rode duas vezes, obtenha o mesmo grafo duas vezes.
2. A prosa é aplicada por cima dos fatos, e rotulada
Um LLM escreve a parte legível por humanos: para que serve um arquivo, como um subsistema se encaixa, qual estado flui por quais etapas. Ela está sempre ancorada no grafo e, onde falha, a estrutura ainda é entregue — com uma descrição vazia.
Uma frase ausente é melhor do que uma frase inventada.
3. O mapa é feito para rotear, não para ler
A saída não é um resumo do seu código. É um índice que responde "quais arquivos, funções e estados esta mudança precisa tocar?" — inclusive os espalhados e nada óbvios. O planner então usa esse índice, lê o código-fonte real em cada endereço que encontrou e emite um plano de edição exato ao byte, aplicável mecanicamente.
O que uma execução produz
| Saída | Para quem |
|---|---|
| Handbooks em markdown — visão geral, índice de etapas, uma página por etapa, tabela de registradores de estado | humanos |
Site HTML multipágina — sumário fixo, breadcrumbs, alternância de tema, funciona via file:// | humanos |
| Uma página HTML autocontida que você pode mandar por e-mail | humanos |
Índice para agentes — símbolo → path:line-line, tabelas de arquivos e chamadas, receitas de grep | agentes |
llms.txt + llms-full.txt | agentes |
| Um pacote SKILL com um hash de conteúdo por arquivo, tornando a deriva detectável | agentes |
Para quem é isto
| Você é… | Você ganha… |
|---|---|
| Um engenheiro que acabou de herdar um serviço de 200 mil linhas | Um passo a passo etapa por etapa que dá para ler de verdade, mais um site HTML para compartilhar |
| Alguém rodando um agente de codificação em um repositório grande | Um pacote SKILL que impede o agente de adivinhar onde as coisas ficam |
| Um líder de equipe integrando pessoas novas | Documentação que se regenera em vez de apodrecer |
| Alguém mantendo um monorepo poliglota | Uma única passada sobre 18 linguagens, com a fidelidade da análise divulgada por linguagem |
O que isso custa para você
- Node.js ≥ 20.11 e pnpm. A instalação é só isso. Sem compilação nativa, sem
Python, sem
node-gyp— os parsers são WebAssembly. - Um endpoint compatível com OpenAI para as fases que usam LLM. OpenAI hospedado,
Azure, vLLM, Ollama, LiteLLM, um proxy interno — qualquer coisa que fale
/v1/chat/completions. Pode ser um modelo rodando na sua própria máquina. - Absolutamente nada para
handbook analyze, que é o comando que você deve rodar primeiro.
Meu código sai do prédio?
A Phase 1 é inteiramente local. As Phases 2 e 3 enviam o conteúdo dos arquivos para o endpoint que você
configurou — que pode ser localhost. Nada mais sai, e --max-chars-per-file limita quanto de qualquer
arquivo individual chega a ser enviado. Veja o modelo de confiança.
Para onde ir agora
Por que isto existe
O problema do roteamento, e por que resumir uma base de código não o resolve.
Como a geração funciona
Cinco fases, o que cada uma custa e o que degrada quando uma falha.
Configuração
Flags, variáveis de ambiente, cascatas de .env e handbook.config.yaml — um único registro.
Solução de problemas
As coisas que realmente dão errado, e o que fazer a respeito.