Seu primeiro handbook de verdade

Este é o ciclo completo em um repositório real. Foi escrito para ser seguido em ordem, e coloca de propósito as verificações gratuitas antes das caras.

alias handbook="node $(pwd)/packages/cli/dist/main.js"
export REPO=~/code/myrepo
export WORK=work/myrepo

Passo 1 — Olhe antes de pular

handbook analyze --source $REPO --work $WORK

{
  "language": "multi",
  "files": 412,
  "functions": 3187,
  "edgesKept": 9042,
  "edgesDropped": 611,
  "filesUnparsed": 3
}

Isto é gratuito e é o seu teste de fumaça. Sem LLM, sem chave, sem tokens.

Corrija qualquer um dos pontos acima agora. Cada problema aqui vira um problema mais caro depois.

Passo 2 — Gere o handbook

Este é o passo que custa tokens. Em um repositório de porte médio, espere minutos.

Comece barato:

handbook generate --source $REPO --work $WORK

Isso equivale a --detail brief e --synth-mode oneshot: uma ficha curta por arquivo e um esqueleto de passada única. É a forma mais rápida de ver se a forma do handbook está certa.

Olhe $WORK/phase2/skeleton.yaml. A lista de etapas se parece com o seu sistema? Se sim, refine:

handbook generate --source $REPO --work $WORK \
    --phase 2a --detail deep --resume

--phase 2a --resume aprofunda apenas as fichas, pulando arquivos que já têm uma ficha completa. Você mantém o esqueleto que já validou.

Se o esqueleto estiver errado, reexecute a 2b com o laço ator–crítico:

handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor

Passo 3 — Renderize

handbook render --work $WORK --title "MyRepo Handbook" \
    --html --html-single --agent-site --llms-txt

Sem LLM. Rode quantas vezes quiser — em CI, a cada commit.

Adicione --source-base-url https://github.com/me/myrepo/blob/main para transformar cada caminho de arquivo do handbook em um link para o arquivo real. Sem isso, a saída não contém nenhuma URL externa, o que importa em uma base de código privada.

Abra $WORK/handbook/html/overview.html e leia. Este é o momento de julgar se o handbook ficou bom.

Passo 4 — Empacote para o seu agente

handbook skill --handbook $WORK/handbook --out skills/myrepo \
    --name myrepo --project "MyRepo" \
    --work $WORK --source $REPO \
    --agent-dir $WORK/handbook/agent

--work + --source juntos produzem o coverage.json: um hash de conteúdo por arquivo. É isso que torna a deriva do handbook detectável, em vez de silenciosamente errada mais tarde.

--agent-dir inclui o índice para agentes e suas tabelas de fatos, e dá ao protocolo de roteamento da SKILL as suas receitas de grep — assim o agente transforma o nome de um símbolo em path:startLine-endLine com um comando, em vez de ler prosa e adivinhar.

Passo 5 — Valide

handbook validate --skill skills/myrepo --source $REPO

Verifica a estrutura, o contrato do frontmatter, a consistência índice ↔ páginas de etapa, e refaz o hash do seu código-fonte para apontar páginas que ficaram para trás. Sai com código 2 em caso de falha, então este é o comando para colocar no CI.

Passo 6 — Planeje uma mudança real

handbook plan --source $REPO --handbook skills/myrepo/references \
    --request "Retry failed uploads three times before giving up" \
    --out plan.md

Um laço de agente somente leitura: ele lista, lê e faz grep — não tem ferramenta de escrita alguma —, roteia com o handbook, verifica contra o código-fonte real e escreve o plan.md.

Leia o plano. Leia de verdade. Ele termina com um bloco de declarações legível por máquina:

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

Passo 7 — Aplique, com um caminho de volta

handbook apply --source $REPO --plan plan.md --dry-run   # verify only, never writes
handbook apply --source $REPO --plan plan.md             # for real

O dry run não é opcional em espírito. Ele resolve cada âncora contra o conteúdo atual dos arquivos e diz exatamente quais edições seriam aplicadas.

A aplicação imprime o diretório de backup. Copie-o para algum lugar antes de precisar dele:

handbook rollback --backup $REPO/.handbook-patches/2026-08-08T14-05-11-204Z

O rollback recusa qualquer arquivo que mudou depois do patch, a menos que você passe --force — porque restaurá-lo destruiria silenciosamente esse trabalho. Veja Aplicando mudanças para as quatro regras de segurança.

Passo 8 — Avance o handbook junto

O código mudou. Não regenere — faça resync.

Um caso é um diretório que você monta:

cases/upload-retry/
  edited/       copy of the repo after the change   (required)
  plan.md       the plan from step 6                (optional — sharpens scope)
  change.diff   unified diff of the change          (optional — widens scope)

mkdir -p cases/upload-retry
cp -R $REPO cases/upload-retry/edited
cp plan.md cases/upload-retry/
handbook resync --case cases/upload-retry --work $WORK

O resync reanalisa a árvore editada, compara o grafo antigo com o novo e regenera apenas o que mudou. Saídas já renderizadas sob $WORK/handbook são atualizadas automaticamente.

Sem endpoint à mão? --no-llm atualiza os fatos estruturais e marca a prosa como desatualizada, em vez de fingir que ela está em dia.

Se o seu repositório for muito grande

Mais em Custo e desempenho.

A seguir