Por que isto existe

A falha que você já viu

Você pede a um agente de codificação uma mudança que atravessa o sistema. Ele faz grep de um símbolo, encontra um local plausível, edita e reporta sucesso.

Ele deixou passar:

• a constante que de fato controla o comportamento, três diretórios adiante;
• a implementação espelhada no caminho de lote;
• a métrica que conta exatamente aquilo que ele acabou de mudar;
• o teste que assevera o comportamento antigo.

O agente não estava confuso sobre como escrever o código. Estava confuso sobre onde o código está. E não tinha como descobrir, porque as únicas ferramentas de que dispunha eram busca textual e uma janela de contexto pequena demais para conter o repositório.

Por que resumos não resolvem

A resposta óbvia é "resuma a base de código e entregue o resumo ao agente". Isso falha por uma razão específica:

Um resumo responde "o que é isto?". Um agente precisa de "onde isso está?"

Um parágrafo lindamente escrito sobre o subsistema de upload não conta a um agente que o orçamento de retries também vive em worker/queue.py e é lido por metrics/emit.py. Pior: um resumo é prosa plausível — um agente vai alegremente raciocinar em cima dele, sem conseguir distinguir quais frases são fatos estruturais e quais são paráfrase do modelo.

Disso seguem três modos de falha:

1. Não é endereçável. Prosa nomeia conceitos, não caminhos e intervalos de linhas.
2. Não é verificável. Nada nele distingue um fato do parser de um palpite.
3. Apodrece. No momento em que o código muda, o resumo fica silenciosamente errado, e nada nele avisa.

O que o Handbooks faz em vez disso

Ele constrói um índice, não um resumo

A saída responde exatamente uma pergunta: quais arquivos, funções e itens de estado esta mudança precisa tocar?

Cada entrada é um endereço — um caminho, um nome qualificado, um intervalo de linhas — derivado de um parse real. A prosa em volta desses endereços existe para ajudar um humano a ler, e explicitamente não é aquilo sobre o qual um agente deve agir. O pacote SKILL diz isso em sua primeira linha:

Este handbook é um índice de localização da base de código, não uma descrição do código. Use-o para decidir QUAIS arquivos, funções e estados uma mudança precisa tocar — e então leia o código-fonte real.

Ele separa fatos de prosa, por construção

A separação é imposta por fronteira de pacote, não por convenção: o analisador, o renderizador, o empacotador de skill e o patcher não dependem do pacote de LLM em absoluto.

Ele falha visivelmente

Cada escolha de design aqui segue uma regra: quando algo não funciona, diga.

• Um arquivo cuja geração de ficha falhou ainda aparece, com uma descrição vazia. Ele é listado em _coverage.json. Nunca é descartado e nunca é inventado.
• Uma chamada que o analisador não conseguiu resolver vai para dropped-calls.json com sua categoria e o texto bruto. Nunca é adivinhada como uma aresta plausível.
• Um arquivo que o analisador não conseguiu ler, ou só conseguiu parsear em parte, vai para scan-coverage.json com o motivo. Nunca é contado como coberto — um arquivo que ninguém abriu não é "um arquivo sem funções".
• Uma linguagem analisada pelo motor guiado por configuração é nomeada na visão geral, para que "relações de chamada de melhor esforço" não possam ser lidas como "exatas".
• Uma execução do planner que desistiu sai com código diferente de zero, para que nenhum script confunda seu pedido de desculpas com um plano.
• Uma âncora de patch que casa zero vezes, ou duas, recusa. Nunca escolhe uma delas.

Ele se mantém atualizado a custo proporcional

Documentação apodrece porque atualizá-la custa tanto quanto escrevê-la. O resync compara o grafo de chamadas antigo com o novo e regenera apenas o que mudou — fichas dos arquivos tocados, atribuição dos novos, prosa das etapas afetadas. Toque três arquivos, pague por três arquivos.

O cache por hash de conteúdo faz o resto: uma etapa cujas entradas não mudaram não é renarrada.

A economia

A geração é o passo caro, e acontece uma vez. Tudo depois dela — renderizar para markdown, para um site HTML, para o índice de agentes, para llms.txt, empacotar como SKILL, validar esse pacote — é determinístico e gratuito. Você pode rodar essas etapas a cada commit.

Essa separação é o motivo de render e skill serem comandos separados em vez de flags de generate, e de viverem em pacotes que não conseguem alcançar um LLM nem por acidente.

O que isto não é

• Não é uma ferramenta de busca de código. Não substitui o grep nem o seu LSP. Ele diz a um agente para onde apontá-los.
• Não é um agente de codificação autônomo. O planner é somente leitura por construção; não tem ferramenta de escrita. O apply é um executor mecânico sem modelo no circuito. Um humano decide no meio.
• Não substitui a sua própria documentação. Decisões de arquitetura, intenção de produto e convenções do time não são deriváveis de um grafo de chamadas, e o Handbooks não finge o contrário.

A seguir