Abri o código do meu playbook de Claude Code

Hoje deixei público o repositório do meu Claude Code Playbook. É um guia prático de configuração do Claude Code, com os princípios que eu sigo, mais uma base instalável que deixa qualquer máquina ou VM configurada do mesmo jeito com um comando. A licença é MIT, e o projeto não tem ligação com a Anthropic.

Se você já usa o Claude Code e quer ir direto para a prática, escrevi um guia passo a passo do autopilot, da instalação até o pull request.

Por que eu fiz isso

Eu queria três coisas de cada projeto com Claude Code, e são elas que organizam o playbook:

• Cada projeto orienta bem o Claude. Contexto enxuto e em camadas, para que toda sessão já comece sabendo construir, testar e entregar o repositório.
• Os agentes continuam trabalhando enquanto houver capacidade. Isolamento, fila de tarefas, verificação sem supervisão e alertas.
• Nada de desperdiçar recursos. Cuidar do contexto, usar o modelo certo para cada trabalho e medir antes de otimizar.

A parte que virou o destaque do README é o autopilot.

O que o autopilot faz

A ideia é descrever o projeto uma vez e receber um pull request verificado. Você roda /autopilot-spec no Claude Code, responde à única entrevista do processo e sai com um SPEC.md com critérios de aceite verificáveis. Depois, autopilot start coloca o Claude para trabalhar em segundo plano, sem perguntas e sem pedidos de permissão, até que cada critério esteja verificado.

As garantias, como o README descreve:

• Espera o reset dos limites de uso. Quando a janela de 5 horas ou a semanal acaba, ele dorme até o reset e continua na mesma sessão.
• Nunca gasta créditos de uso. Ele se recusa a começar, e para no meio, se a sua conta for cobrar créditos pagos além do plano.
• Fica no próprio branch. Nunca faz push para o branch padrão, nunca faz merge, deploy nem gasta dinheiro. Hooks reforçam as regras mais arriscadas, não só o prompt.
• Sobrevive a quedas e travamentos. Retoma a mesma sessão com backoff, mantém a máquina acordada e se marca como bloqueado depois de três execuções sem progresso, em vez de ficar em loop.

No fim, ele escreve o AUTOPILOT_DONE.md, com cada critério e o comando que o comprovou, e abre um pull request com um documento de PR e diagramas Mermaid. Se só uma pessoa puder desbloquear o trabalho, como uma credencial, um serviço pago ou uma decisão de produto, ele escreve o AUTOPILOT_BLOCKED.md e para.

O que ainda não está provado

Prefiro deixar as limitações claras:

• A espera num limite de uso real ainda não foi observada de ponta a ponta, porque não dá para provocar isso sob demanda. Ela depende do CLAUDE_CODE_RETRY_WATCHDOG, documentado pelo Claude Code, com uma leitura do horário de reset como plano B, e os dois caminhos estão cobertos por testes com um stub.
• A checagem de créditos lê o texto de claude -p /usage. Se a Anthropic mudar esse texto, o autopilot falha do jeito seguro: se recusa a rodar em vez de arriscar uso pago.
• Fechar a tampa do notebook ainda faz a maioria dos Macs dormir, mesmo com caffeinate, a não ser que haja um monitor externo ligado.
• Os PRs precisam do gh. Um PR aberto por um servidor MCP do GitHub escapa do hook que exige o documento de PR.

E um aviso sério: o autopilot roda um agente de IA sem supervisão, por horas, executando comandos sem perguntar. Os hooks de proteção bloqueiam uma lista curta de comandos perigosos, mas são a última linha de defesa, não um sandbox. 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.

Por onde começar

O repositório tem o README com os requisitos e nove guias, dos princípios até o autopilot. Relatos de execuções reais são bem-vindos como issues.

Para rodar o autopilot no seu próprio projeto, siga o guia do autopilot: ele mostra cada comando, como uma execução termina e o que configurar antes de uma execução longa.