Precisei executar uma issue com 5 subtasks no backend do Aurora — todas relacionadas, mas cada uma independente o suficiente para ter sua própria PRPull Request (PR) Um pedido formal para incorporar suas mudanças ao código principal. Outros desenvolvedores revisam, comentam e aprovam antes de aceitar. É o controle de qualidade do código.. O tipo de tarefa que, se você faz tudo numa branchBranch Uma cópia paralela do código onde você faz mudanças sem afetar a versão principal. Quando fica pronto, você junta de volta. É como um rascunho que não estraga o documento original. só, vira uma PR monstruosa impossível de revisar. E se faz em branches separadas contra a main, perde o contexto de que são parte de um mesmo esforço.

Fiz isso inteiro com o Claude CodeClaude Code Ferramenta de linha de comando da Anthropic. Você desenvolve software conversando com IA direto no terminal — ela lê seu código, edita arquivos e roda testes.. E a experiência me ensinou algo que agora é padrão no meu workflow: quando a IA executa, você precisa de checkpoints.

O problema: a IA não tem "salvar progresso"

Quando você pede para o Claude Code executar uma tarefa complexa — cinco mudanças sequenciais num backend, por exemplo — várias coisas podem dar errado no meio do caminho. A context windowContext window A "memória de curto prazo" da IA — a quantidade de texto que ela consegue considerar de uma vez. Quando estoura, ela esquece o início da conversa. pode estourar. A IA pode cometer um erro na terceira tarefa que invalida a quarta. Ou simplesmente entregar algo diferente do que você esperava.

Se tudo estava numa branch só, com commitsGit commit Salvar uma "foto" do estado atual do seu projeto. Git é o sistema de controle de versão mais usado no mundo — permite voltar no tempo e colaborar sem pisar no trabalho dos outros. soltos sem revisão, você fica no escuro. Onde exatamente ela parou? O que já foi testado? O que ainda precisa ser feito? A resposta, na maioria das vezes, é: você não sabe.

O problema não é a IA. É a falta de estrutura para acompanhar o que ela fez.

A solução: release branch com PRs sequenciais

A solução é velha conhecida da engenharia de software — só que aplicada num contexto novo. Criei uma release branchRelease branch Uma branch temporária que agrupa várias mudanças antes de ir para produção. Funciona como uma área de preparação — tudo entra ali primeiro, e só depois vai para o código principal. — e cada subtask virou um ciclo completo:

  1. Criar branch a partir da release
  2. Implementar a subtask
  3. Abrir PR contra a release branch
  4. Squash mergeSquash merge Técnica que comprime vários commits em um só na hora de aceitar uma PR. O histórico fica limpo — uma linha por mudança, em vez de dezenas de commits intermediários.
  5. Próxima subtask

No final, uma única PR da release contra a main mostra tudo consolidado.

Por que funciona tão bem com IA

Cada PR mergeada é um checkpoint. Se o contexto estourar, se a IA cometer um erro no meio do caminho — você sabe exatamente onde parou. PR #14 mergeada? Subtask 1.1 feita. PR #15? 1.2 feita. É progresso incremental documentado.

Sem essa estrutura, eu teria um commit gigante ou, pior, perderia o tracking de onde a IA parou e o que já foi feito. Com a release branch, cada mudança tem sua PR com descrição, diffDiff A comparação visual entre duas versões de um arquivo, mostrando exatamente o que mudou — linha por linha, em verde (adicionado) e vermelho (removido). isolado e histórico de merge. Se preciso retomar numa nova sessão, basta olhar o estado da release branch.

A rastreabilidade muda completamente a dinâmica. Em vez de "a IA fez alguma coisa e eu espero que esteja certo", vira "a IA fez a subtask 1.2, tem uma PR revisável, os testes passaram, e está isolada das outras mudanças". Você volta a ter controle.

Prós e contras

Prós:

  • Rastreabilidade real — cada subtask é um checkpoint documentado
  • PRs pequenas e revisáveis — ninguém precisa ler 800 linhas de uma vez
  • RollbackRollback Desfazer uma mudança e voltar ao estado anterior. Como o "Ctrl+Z" do código em produção — se algo der errado, você reverte sem perder tudo. granular — posso reverter uma subtask sem afetar as outras
  • Histórico limpo — a main recebe um único squash merge no final
  • Retomada fácil — uma nova sessão continua de onde a anterior parou

Contras:

  • Overhead de criar branches e PRs para cada subtask — mas com automação é trivial
  • Risco de conflitos entre subtasks se tocarem nos mesmos arquivos — na prática, com subtasks bem definidas, conflitos são raros

Dica: crie um agenteAgente Uma IA que age de forma autônoma — em vez de só responder perguntas, ela executa tarefas sozinha: lê código, cria arquivos, roda testes. Pense como um estagiário digital muito rápido. para não repetir instrução

Se esse workflow faz sentido para o seu contexto, vale criar um agente customizado no Claude Code que codifique essas regras. Em vez de explicar o fluxo toda vez — "cria release branch, abre PR por subtask, faz squash merge" — você escreve uma vez e o agente segue o protocolo.

No Claude Code, basta criar um arquivo .claude/agents/release-manager.md no seu projeto (ou em ~/.claude/agents/ para uso global) descrevendo o fluxo: como nomear branches, quando abrir PRs, qual formato de commit usar, como reportar progresso. O agente passa a ser invocável direto no terminal.

O ponto não é ter o agente perfeito — é não repetir instrução manual toda sessão. Se o fluxo funciona, automatize.

Por que não só arquivos locais?

Dá para resolver esse problema de outras formas. Você pode manter um TODO.md no repositório, usar task lists dentro do próprio Claude Code, ou criar documentação local que rastreia o progresso. Tudo isso funciona — e para projetos solo, pode ser suficiente.

Mas a escolha deliberada de issues e PRs tem uma vantagem que nenhum arquivo local oferece: a documentação é pública e revisável por pares. Uma PR não é só um checkpoint — é um convite para outra pessoa olhar, questionar e aprovar. O diff está ali, o contexto está ali, a motivação está ali. Qualquer colega do time consegue entender o que foi feito sem precisar perguntar.

Arquivos locais morrem com o contexto de quem escreveu. PRs sobrevivem no histórico do projeto. Quando alguém — incluindo você do futuro — precisar entender por que aquela mudança foi feita, a PR conta a história completa. Um TODO.md atualizado pela IA não tem a mesma força probatória.

A lição de fundo

Quanto mais autonomia você dá para a IA, mais estrutura você precisa ao redor. Não é um paradoxo — é pragmatismo. Release branches com PRs sequenciais não são burocracia. São infraestrutura de confiança.

Cada PR mergeada é uma garantia de que aquele pedaço está feito, testado e documentado — independente do que aconteça depois. É isso que permite dar cada vez mais corda para a IA sem perder o controle.

Confiança na IA não vem de fé. Vem de checkpoints.

Se você usa Claude Code (ou qualquer assistente de IA) em tarefas complexas, experimente esse workflow. O princípio vale independente da ferramenta: estruture o trabalho em checkpoints, sempre.