Como dividir uma tarefa grande no Claude Code em entregas que ele fecha até o fim

Pedido gigante quase nunca volta como entrega gigante

Volta como seis arquivos tocados pela metade, um TODO no meio da função e uma sessão que já não lembra direito por que aquilo começou

Fala aí, beleza? Se tu já mandou "refatora o módulo inteiro e migra pro framework novo" e recebeu um pedaço solto de cada coisa, o problema não foi o modelo ficar burro no meio do caminho

O problema é que a demanda não tinha começo, meio e critério de pronto

Uma feature inteira ou uma migração não cabem numa unidade de trabalho só, e quando não cabe, sobra código que ninguém consegue revisar nem commitar com cara de entrega

Esse post é sobre fatiar. Bora? 🙂

O que deixar pronto antes de fatiar o trabalho

Antes de sair quebrando em fase, arruma o terreno

São quatro coisas, e nenhuma delas é fórmula mágica, é só higiene mesmo

• CLAUDE.md do projeto: o /init lê a estrutura do repositório e escreve o CLAUDE.md registrando comandos de build, arquitetura e convenções, e esse arquivo é carregado no começo de toda sessão naquele repo
• Memória automática: além do CLAUDE.md que você escreve, existe a memória que o Claude escreve sozinho a partir das suas correções, e os dois são lidos no início de toda conversa
• Git limpo: cada fatia vai terminar em commit, então começar com working tree suja é pedir pra misturar a entrega com sujeira antiga
• Um check que já roda: suíte de teste, build ou linter, qualquer coisa que diga "pronto" sem você precisar achar que está pronto

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

"Que check?"

A documentação chama de check qualquer sinal legível na conversa: suíte de testes, exit code do build, linter, script que compara a saída com uma fixture, screenshot comparado com o design

E o motivo é direto: o Claude tem desempenho melhor quando existe um alvo claro contra o qual iterar

Sem alvo, ele para quando acha que acabou. Com alvo, ele para quando o alvo diz que acabou 😀

Passo a passo: quebrar a demanda em entregas que fecham

1. Decida se vale planejar:

Nem toda tarefa merece plano

A documentação é clara sobre quando planejar compensa: quando há incerteza sobre a abordagem, quando a mudança toca vários arquivos ou quando o código é desconhecido

E ela também diz quando PULAR o plano: quando o diff cabe numa frase

O erro comum deste passo: abrir modo plano pra trocar uma string, e gastar três turnos de conversa num negócio de dez segundos

2. Entre no modo plano:

Aperta Shift+Tab até a barra de status mostrar o indicador ⏸ plan mode on

Ou já começa a sessão direto nele:

claude --permission-mode plan

No meio da sessão o Shift+Tab cicla nesta ordem: default → acceptEdits → plan

Dentro do modo plano ele lê arquivos e propõe um plano, e não faz nenhuma edição em disco antes de você aprovar

O erro comum deste passo: apertar Shift+Tab uma vez só, parar no acceptEdits e achar que está planejando. Aí ele já está escrevendo em disco enquanto você lê a proposta que não existe

3. Separe exploração de execução:

A recomendação oficial é separar pesquisa e planejamento da implementação, justamente pra não resolver o problema errado com muita eficiência

E, na hora de pedir, ser preciso: citar arquivos, restrições e padrões de exemplo

Isso vale em dobro quando o alvo é código velho que ninguém mais lembra como funciona, tipo quando você vai refatorar um projeto legado que já nasceu antes de você entrar no time

O erro comum deste passo: pedido genérico do tipo "melhora isso aqui", sem apontar arquivo nem restrição. Ele vai melhorar alguma coisa, só que provavelmente não a que você queria

4. Exija a quebra em fases:

Pra mudanças grandes (migração de framework, refatoração ampla, subsistema novo), a documentação recomenda quebrar o trabalho em fases, cada uma com o seu próprio plano

O motivo é bem prático: um plano único cobrindo tudo é grosseiro demais pra revisar

Então a régua é essa: cada plano tem que ser revisável isoladamente

Se você não consegue ler a fase 2 sozinha e dizer "isso aqui está certo", ela ainda não é uma fatia, é um pedaço de intenção

Na prática o pedido fica mais ou menos assim:

Quebre esta migração em fases.
Uma fase por vez, com plano próprio, e cada plano tem que
fazer sentido lido sozinho.
Não comece a implementar: pare no plano da fase 1.

O erro comum deste passo: aceitar o plano único gigante porque ele parece completo. Completo e irrevisável é o pior dos mundos

5. Edite o plano antes de aprovar:

O plano proposto não é lei, é rascunho

Dá pra abrir ele no editor de texto com Ctrl+G e mexer direto antes do Claude seguir

No VS Code ele abre automaticamente como documento Markdown completo, e aí você deixa comentário inline como feedback antes dele começar

O erro comum deste passo: aprovar com uma fase vaga ("ajustar o restante") e tentar consertar depois no meio da conversa. Consertar plano em execução custa muito mais caro que apagar uma linha antes de aprovar

6. Defina o check de cada fatia:

Antes de aprovar, cada fase precisa responder: o que prova que ela acabou?

Escolhe um sinal legível: a suíte de testes passando, o exit code do build, o linter limpo, um script que compara a saída com uma fixture, um screenshot comparado com o design

O erro comum deste passo: critério de pronto subjetivo. "Está funcionando" não é check, é opinião

7. Execute uma fatia por vez e feche com artefato:

Fatia fechada termina em duas coisas escritas

A engenharia da Anthropic conta que, em trabalho longo, a melhor forma de manter o ambiente em estado limpo foi pedir ao modelo que commitasse o progresso no git com mensagens descritivas e escrevesse resumos do avanço num arquivo de progresso

A recomendação é commitar e dar push a cada unidade significativa de trabalho: isso dá histórico recuperável, deixa o progresso visível e evita perder tudo se a sessão terminar no meio

O erro comum deste passo: deixar pra commitar tudo no fim. Sessão longa que morre sem commit não deixa nem entrega nem rastro

A sessão encheu no meio da fatia: o que fazer

O sintoma:

O contexto lota, a resposta começa a perder o fio e ele repete coisa que já tinha resolvido

Calma que a sessão não morre: a compactação automática está ativa por padrão e roda quando se aproxima do limite

A causa:

Quase sempre é fatia larga demais, com a conversa carregando a exploração inteira junto

E tem um detalhe importante: a compactação sozinha não resolve trabalho que atravessa várias janelas de contexto, porque nem sempre passa instruções perfeitamente claras pra sessão seguinte

É exatamente por isso que a recomendação é deixar artefato explícito escrito, e não confiar no resumo

A solução, com o que existe na ferramenta:

• /context mostra o uso atual da janela por categoria, com sugestões de otimização e quais arquivos CLAUDE.md e de memória automática foram carregados. Comece sempre por aqui, antes de chutar
• /compact resume a conversa e segue em frente, e aceita instrução de foco:

/compact focus on the auth bug fix

• Dá pra configurar quão cheia a janela fica antes da compactação automática rodar, informando a contagem de tokens:

/autocompact 500k

• O tamanho da janela de contexto também é configurável, como número simples de 100 a 1000 interpretado em milhares (200 equivale a 200.000 tokens), sempre limitado à janela do próprio modelo. E existem modelos com suporte a janela de 1.000.000 de tokens
• Se a fatia descarrilhou, volta no tempo: /rewind, ou Esc duas vezes com o campo de prompt vazio (se tiver texto no campo, o Esc duplo limpa o texto em vez de abrir o menu)

O menu de rewind lista cada prompt enviado na sessão e te dá quatro ações no ponto escolhido: restaurar código e conversa, restaurar só a conversa, restaurar só o código, ou resumir dali em diante pra liberar contexto

Tome cuidado com dois detalhes:

1. Os checkpoints cobrem só as edições feitas pelo Claude, e não as suas edições nem comandos bash
2. Eles somem junto com as sessões depois de 30 dias, período ajustável em cleanupPeriodDays

A prevenção:

Artefato escrito por fatia

Commit descritivo mais o arquivo de progresso atualizado, sempre

Assim, se a janela encher no meio, a próxima sessão não depende da memória da conversa, ela lê o que ficou registrado

Como fatiar por tipo de demanda

O recorte muda conforme o tipo de trabalho. Se liga nos três casos mais comuns:

Migração de framework e refatoração ampla:

Aqui é o caso literal da documentação: quebra em fases, um plano por fase

Quando a coisa é auditoria de base de código ou migração grande de verdade, existem também os workflows dinâmicos, que orquestram muitos subagentes a partir de um script que o Claude escreve e que pode ser rodado de novo

Rodar de novo é o ponto: migração raramente acerta de primeira

Subsistema novo:

Subsistema novo é onde mais se resolve o problema errado, porque ninguém sabe direito o formato final antes de começar

Então a primeira fase é exploração pura, separada da execução, e cada fase seguinte carrega o seu check

Trabalho de leitura pesada:

Quando a fatia é "entender onde isso é usado no projeto inteiro", jogar tudo na conversa principal é o caminho mais rápido pra estourar a janela

Cada subagente roda em janela de contexto própria e isolada: ele não enxerga o histórico da conversa principal nem os arquivos já lidos, e devolve apenas o resumo do que fez

E, por padrão, um subagente pode criar subagentes próprios até três camadas abaixo da conversa principal

O efeito prático é esse: a leitura pesada acontece longe do seu contexto, e volta só o que interessa

O que aprendi fatiando trabalho longo na prática

O que me empurrou pra esse assunto foi um incômodo bem específico

Em sessão longa o Claude Code chega no limite, compacta o contexto e acaba esquecendo parte do que estava sendo feito, porque só uma seleção do que ele considera importante sobrevive

E o pior é que essa perda não é previsível: às vezes o que importava fica, às vezes não

Na minha experiência o contexto durava pouco antes de compactar, e depois que passei a cuidar disso consegui trabalhar por um período bem maior sem perder o fio da tarefa

O que mudou no meu jeito de pedir, na ordem:

1. Antes de começar a mexer no projeto de demonstração, pedi ao Claude Code que gerasse um arquivo de contexto do projeto, li esse arquivo e SÓ DEPOIS escrevi os prompts. Queria saber o que estava acontecendo no código antes de mandar ele fazer qualquer coisa
2. Não joguei tudo num pedido só: dividi em três prompts sequenciais, em frentes diferentes. Primeiro análise, depois correção de segurança, por último adição de recurso
3. O prompt de correção foi delimitado por escopo E por quantidade: aplicar as três correções de segurança mais críticas identificadas na análise e extrair a lógica de validação dos controllers pra um middleware reutilizável
4. O terceiro prompt, o de funcionalidade nova, foi escrito com os entregáveis item a item: um endpoint de estatísticas retornando totais, percentual e agrupamento, mais uma seção visual no frontend com cards e barra de progresso, e a busca desses dados no carregamento do dashboard

Repara que nenhum desses prompts é vago

"Três correções, as mais críticas da análise" fecha. "Melhora a segurança" não fecha nunca

Rodei mais de um prompt de propósito, pra ter volume real de trabalho na sessão, senão a diferença de consumo nem apareceria. Depois de fechar os três pedidos, fui conferir o estado do contexto pra comparar o que entrou e o que foi economizado

E aqui vai a parte honesta: gerenciamento de contexto resolve durabilidade, não resolve recorte

Ele te dá mais tempo de sessão. Ele NÃO transforma um pedido gigante numa entrega revisável

Quem faz isso é a fatia com critério de pronto

No vídeo abaixo eu mostro esse teste na prática, com um plugin que usei pra segurar a sessão por mais tempo, e a ideia dele é basicamente essa: filtrar o material pesado fora do contexto e devolver só o resumo, e manter um registro do que já foi feito pra recuperar caso o contexto seja compactado

Conclusão

A régua nunca foi o tamanho do pedido

A régua é: essa entrega dá pra revisar e commitar sozinha?

Se dá, é fatia. Se não dá, ainda é intenção, e intenção não fecha até o fim

Recapitulando o caminho: CLAUDE.md e check no lugar, decidir se o plano vale, entrar no modo plano, separar exploração de execução, exigir fases com plano próprio, editar o plano antes de aprovar, definir o check de cada fatia e fechar cada uma com commit descritivo e arquivo de progresso

O próximo passo é concreto e cabe hoje: pega a próxima demanda ampla da sua fila, abre o modo plano, exige a quebra em fases e define o check da primeira fatia ANTES de aprovar qualquer coisa

Faz o teste e me conta se a sessão te entregou algo fechado dessa vez 😀

até o próximo post!