Renderizando as saídas
Markdown, um site HTML, uma página autocontida, o índice localizador para agentes e llms.txt — tudo determinístico, tudo gratuito de reexecutar.
handbook render --work <workdir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]Sem LLM. Sem rede. Determinístico. O mesmo modelo na entrada, arquivos idênticos byte a byte na saída — então isto pertence ao CI, a cada commit.
As cinco saídas
Sempre gravado.
<out>/
overview.md system prose + a mermaid stage map + "see also" links
index.md every stage, nested by depth, a paragraph each
<stage-id>.md one page per content-bearing stage
register.md the cross-stage state table (only when registers exist)A página de uma etapa traz o resumo da etapa, links para as subetapas e, em seguida, seus arquivos — agrupados e ordenados conforme a phase 2c decidiu, cada um renderizado como uma ficha de arquivo: propósito, papel, ciclo de vida, fatos de chamadas e notas por função nas fichas profundas.
Dois comportamentos que vale a pena conhecer:
- Páginas obsoletas são removidas. Os ids das etapas mudam entre gerações; cada renderização remove primeiro as páginas da renderização anterior, de modo que uma etapa renomeada não deixa nenhuma página fantasma para o empacotador de skill recolher.
- A seção de registradores por etapa é idempotente — anexada sob um marcador, apenas quando o marcador está ausente. Re-renderizar nunca acumula duplicatas.
Vinculando ao seu código-fonte
handbook render --work $WORK --source-base-url https://github.com/me/repo/blob/mainCada caminho de arquivo no handbook se torna um link para o arquivo real. Aponte para uma
tag ou um SHA de commit em vez de main se quiser que o handbook referencie o código a
partir do qual foi gerado.
Sem essa flag a saída não contém nenhuma URL externa, que é o padrão certo para uma base de código privada.
Títulos e idiomas
handbook render --work $WORK --title "Payments Service — Engineering Handbook"O idioma da narração é fixado no momento da geração (--narrate-lang) e armazenado em
phase3/narration.json. O renderizador o lê de lá — cada rótulo, título e cabeçalho de
tabela é localizado para corresponder. A estrutura é idêntica nos dois idiomas, então
ferramentas que leem a saída não precisam saber qual deles é.
Re-renderizar como hábito
Renderizar é gratuito e determinístico, então conecte-o ao CI:
- run: handbook render --work work/api --title "API Handbook" --html --agent-site --llms-txt
- run: handbook skill --handbook work/api/handbook --out skills/api --name api \
--work work/api --source . --agent-dir work/api/handbook/agent
- run: handbook validate --skill skills/api --source .Veja Integração com CI.
Publicando o site HTML
A saída é um diretório estático com links relativos e sem assets externos, então qualquer hospedagem estática funciona:
# GitHub Pages
cp -R work/api/handbook/html/* docs-site/ && git add docs-site
# Netlify / Vercel / S3 / nginx
npx serve work/api/handbook/htmlSirva o llms.txt na raiz do site para que agentes possam encontrá-lo.
Gerando um handbook
Escolhendo detalhe, modo de síntese e estratégia; executando fases separadamente; retomando; e o que fazer quando o resultado está errado.
Empacotando para o seu agente
Transforme um handbook renderizado em um pacote SKILL com detecção de deriva e conecte-o a um agente de codificação.