Guia do autopilot: do SPEC.md ao pull request com o Claude Code

Este guia é para quem já usa o Claude Code e quer rodar o autopilot do Claude Code Playbook num projeto de verdade. O autopilot pega um SPEC.md com critérios de aceite e trabalha sozinho, sem perguntas, até que todos estejam verificados e haja um pull request aberto. Os comandos abaixo são os mesmos do README e do guia 9 do repositório.

O que você precisa

Plano: uma assinatura Claude Pro, Max ou Team logada no Claude Code. O autopilot se recusa a rodar com cobrança por chave de API, em planos Enterprise cobrados por uso ou com créditos de uso ligados, porque nesses casos todo token é pago. A variável AUTOPILOT_ALLOW_CREDITS=1 desliga essa trava, por sua conta.
Claude Code: v2.1.259 ou mais recente, por causa da opção --permission-prompts none. A partir da v2.1.305 ele também confere se um limite foi liberado antes da hora.
Permissões: modo auto, ou AUTOPILOT_PERMISSION_MODE=dontAsk se a sua organização desativa o modo auto. O /goal precisa de uma pasta marcada como confiável e de hooks ativados.
Sistema: macOS ou Linux (o WSL2 funciona), com bash, git e jq. Para o pull request no fim, o gh precisa estar logado.

Instalação

Clone o repositório e instale só a parte do autopilot:

git clone https://github.com/filipejesse/claude-code-playbook ~/claude-code-playbook
cd ~/claude-code-playbook
./install.sh --dry-run
./install.sh --autopilot-only

O --dry-run mostra o que a instalação completa mudaria, sem aplicar nada. O --autopilot-only instala apenas o que o autopilot usa: o comando autopilot, o /autopilot-spec, o /open-pr, o agente verifier, os hooks de proteção e de documento de PR e as regras de permissão. Se quiser o playbook inteiro, rode ./install.sh sem opção. Tudo se desfaz com ./install.sh --uninstall.

O spec com /autopilot-spec

Abra o Claude Code na pasta do projeto, que pode estar vazia, e descreva o que você quer construir. O exemplo do guia 9:

mkdir ~/Repos/my-app && cd ~/Repos/my-app && claude
> /autopilot-spec a personal finance tracker that imports bank CSVs and shows monthly charts

Essa entrevista é a única vez em que o Claude pergunta alguma coisa. Depois dela, ele escreve o SPEC.md, com os critérios de aceite e um comando de verificação, monta a estrutura do repositório e faz commit.

Vale gastar tempo aqui. Cada critério precisa ser verificável por um comando, porque é assim que o Claude vai provar que terminou. “A página fica bonita” não dá para checar; “o teste de acessibilidade passa nas duas páginas” dá. Se um critério do rascunho for vago, troque por algo que um comando consiga confirmar.

Rodar, acompanhar e parar

autopilot start
autopilot log
autopilot status
autopilot stop

O autopilot start roda em segundo plano e continua mesmo se você fechar o terminal. O autopilot log acompanha o que ele está fazendo. O autopilot status mostra o estado, o branch, os commits e o PROGRESS.md. O autopilot stop para a execução, e um autopilot start depois retoma a mesma sessão.

O ciclo do autopilot. A linha tracejada é a saída quando só uma pessoa pode desbloquear o trabalho.

Por baixo dos panos, o runner usa o /goal do Claude Code: depois de cada turno, um avaliador separado confere a condição, e o Claude continua até ela ser cumprida. A condição exige cada critério do SPEC.md verificado e o AUTOPILOT_DONE.md escrito. Quando precisa decidir algo, o Claude escolhe, registra a escolha no DECISIONS.md e segue. Para atravessar limites de uso, a variável CLAUDE_CODE_RETRY_WATCHDOG=1 faz a requisição esperar o horário de reset, tanto na janela de 5 horas quanto na semanal. Se o processo cair, o runner retoma a mesma sessão com espera crescente, de 1 a 15 minutos, e três execuções seguidas sem nenhuma mudança no repositório marcam o trabalho como bloqueado.

Como uma execução termina

São dois finais possíveis:

AUTOPILOT_DONE.md: cada critério, o comando que o comprovou e a URL do pull request.
AUTOPILOT_BLOCKED.md: quando só uma pessoa pode desbloquear o trabalho, como uma credencial, um serviço pago ou uma decisão de produto que o spec não resolve.

O trabalho fica num branch autopilot/<date>. Se o repositório tem um remote no GitHub, o Claude abre um PR com o documento de PR, que traz um diagrama de sequência em Mermaid e outros diagramas. A revisão e o merge são seus: o Claude nunca faz merge.

Antes de uma execução longa

Créditos de uso. Com créditos ligados, o limite do plano não para as requisições: elas continuam em créditos pagos. No Pro e no Max, desligue em claude.ai/settings/usage. No Team e no Enterprise, só um Owner consegue.
Janela semanal. Uma execução longa pode consumir boa parte da cota semanal, que o seu trabalho interativo também usa. Comece projetos grandes quando puder abrir mão dela, ou defina AUTOPILOT_MODEL=sonnet.
Isolamento. Faça as primeiras execuções numa VM, num container ou numa conta de usuário descartável, num repositório que você possa jogar fora. Os hooks bloqueiam uma lista curta de comandos perigosos, mas são a última linha de defesa, não um sandbox. O modo bypassPermissions só faz sentido dentro de uma VM ou container descartável.
Notebook. Deixe na tomada. O autopilot mantém a máquina acordada com caffeinate no macOS ou systemd-inhibit no Linux, mas fechar a tampa ainda faz a maioria dos Macs dormir, a não ser que haja um monitor externo ligado.

Um exemplo real: este blog

A infraestrutura e o design deste blog foram construídos em execuções do autopilot:

Pronto para o Cloudflare Pages. Foram 16 critérios, entre eles cabeçalhos de segurança com CSP, uma página 404 bilíngue, redirect na borda e um workflow de CI. A verificação final passou em 23 testes unitários, 107 checagens sobre o build e 114 testes end-to-end, e o check de CI do PR ficou verde. No caminho, o Claude percebeu que um padrão no .gitignore escondia uma pasta de testes que nunca tinha chegado ao repositório, recriou os testes e registrou o motivo no DECISIONS.md.
A identidade visual “Hi, I’m Filipe!”. Foram 17 critérios, de tokens de cor com contraste medido até foco de teclado e movimento reduzido. Fechou com 48 testes unitários, 123 checagens sobre o build, 141 testes end-to-end e 20 screenshots revisados, com 6 críticas datadas e o que mudou depois de cada uma. As duas terminaram do mesmo jeito: um AUTOPILOT_DONE.md com a evidência de cada critério e um PR esperando a minha revisão.

Depois veio o deploy automático no merge: um job de CI que, depois que a verificação passa num push para a main, publica no Cloudflare Pages exatamente o dist/ que foi testado. O merge, e com ele o deploy, continua comigo.

Para fechar

Se você chegou direto aqui, o anúncio do playbook explica por que ele existe e quais limitações do autopilot ainda estão em aberto. Para relatos de execuções ou correções, abra uma issue no repositório.