Plano de feature nova
Imagine assim: Voce vai construir um comodo novo na casa. Sem planta, o encanamento pode nao chegar la. Com planta, tudo se conecta. Para features novas, o plano e o que garante que a nova funcionalidade encaixa na arquitetura existente.
Uma feature nova e onde plan mode mais brilha. O prompt ideal inclui: o que a feature faz, quais componentes ela toca, quais padroes o projeto ja segue e como validar que funciona. Quanto mais contexto voce der, mais preciso o plano sai.
O segredo e ser especifico sobre as constraints: "siga o pattern do auth middleware existente", "use o mesmo estilo de testes de user.test.ts", "nao crie novos arquivos de config". Constraints claras geram planos que se encaixam no projeto em vez de inventar arquitetura nova.
Em 1 frase: para features novas, de contexto das constraints e padroes existentes; o plano se encaixa sozinho.
Plano de refactor
Imagine assim: Voce quer trocar o piso da casa sem derrubar as paredes. Precisa saber a ordem: tira os moveis, tira o piso velho, coloca o novo, devolve os moveis. Com refactor e igual: a ordem dos passos e tudo.
Refactors sao perigosos sem plano porque afetam codigo existente que funciona. O prompt ideal pede ao Claude para mapear primeiro todas as dependencias do codigo que sera refatorado. Quem chama essa funcao? Quem importa esse modulo? Quais testes cobrem?
A tecnica mais segura e o refactor incremental: pedir um plano que muda uma coisa de cada vez, rodando testes entre cada passo. Se um passo quebra algo, voce sabe exatamente onde voltar. O plano deve incluir um "passo zero" de snapshot (commit ou stash) antes de comecar.
Em 1 frase: refactors pedem plano incremental com testes entre cada passo e snapshot antes de comecar.
Plano de bug fix
Imagine assim: Um detetive nao comeca prendendo suspeitos. Ele investiga, coleta provas, monta a teoria e so depois age. Bug fix e investigacao: reproduzir, diagnosticar, corrigir, validar.
O erro mais comum em bug fix e pular direto para a correcao sem entender a causa raiz. O plano ideal comeca com: (1) reproduzir o bug, (2) identificar a causa, (3) propor a correcao, (4) adicionar teste de regressao. Pedir isso explicitamente no prompt garante que o Claude nao pule etapas.
Dica: inclua no prompt a mensagem de erro exata, o comportamento esperado vs o real, e quais hipoteses voce ja descartou. Isso economiza rounds de ida e volta e faz o plano comecar do ponto certo.
Em 1 frase: bug fix = reproduzir, diagnosticar, corrigir, testar. Nessa ordem, sempre.
Cada tipo de plano tem sua estrutura, mas todos convergem para o mesmo padrao: contexto, constraints e passos.
Exemplo resolvido: plano de bug fix
Bug: "pagina de checkout trava quando usuario tem cupom expirado".
Passo 1: Reproduzir — abrir checkout com cupom expirado, confirmar o travamento.
Passo 2: Diagnosticar — o erro esta em coupon.validate() que retorna undefined em vez de error.
Passo 3: Corrigir — adicionar guard clause em coupon.validate() para cupons expirados.
Passo 4: Testar — adicionar test case para cupom expirado em checkout.test.ts.
Indo mais fundo (opcional): quando decompor vs quando manter monolitico?
Se a tarefa tem dependencias lineares (A antes de B antes de C), mantenha num unico plano sequencial. Se tem partes independentes que podem rodar em paralelo, decomponha em sub-planos. A regra: decomponha quando as partes podem falhar independentemente.
Decomposicao de tarefas
Imagine assim: Comer um boi inteiro e impossivel. Cortar em bifes e facil. Decomposicao e cortar a tarefa grande em pedacos que cabem numa mordida.
Quando a tarefa e grande demais para um plano so, decomponha em sub-tarefas independentes. Cada sub-tarefa deve ser verificavel: voce consegue dizer "isso aqui funciona" ou "isso aqui nao funciona" sem depender das outras.
A regra pratica: se um passo do plano tem mais de 3 sub-passos, ele provavelmente precisa ser decomposto. Peca ao Claude: "quebre o passo 3 em sub-tarefas atomicas". Atomico = uma unica mudanca com um unico criterio de sucesso.
Em 1 frase: decomponha ate cada passo ter um unico criterio de sucesso verificavel.
Mapeando dependencias
Imagine assim: Voce nao pode colocar o telhado antes das paredes. Dependencias sao a ordem natural das coisas: o que precisa existir antes do que.
Um plano sem dependencias mapeadas e uma lista de compras, nao um plano. O Claude precisa saber: quais passos dependem de outros, quais podem rodar em paralelo e quais sao blockers. Peca explicitamente: "mapeie as dependencias entre os passos".
Visualize como um grafo: se o passo C depende de A e B, entao A e B podem ser feitos em qualquer ordem (ou em paralelo), mas C so comeca depois dos dois. Isso e especialmente util quando voce vai combinar plan mode com loop mode no modulo 2.5.
Em 1 frase: sem dependencias mapeadas, o plano e so uma lista; com elas, e um caminho critico.
Estimativa de esforco
Imagine assim: Um orcamento de obra nao precisa ser exato, mas precisa existir. Se o pedreiro diz "uns 3 dias" e ja tem 10 dias, algo deu errado. Com tokens e tempo e igual.
Antes de aprovar o plano, estime: quantos tokens ele vai consumir, quanto tempo vai levar e quantas iteracoes provavelmente serao necessarias. Nao precisa ser preciso. A ordem de grandeza ja ajuda: "isso e 5 minutos ou 2 horas?".
Heuristicas uteis: cada arquivo editado consome ~2-5k tokens de contexto. Um loop de testes tipicamente precisa de 3-7 iteracoes. Se o plano tem mais de 10 passos, considere quebrá-lo em dois planos separados. Se a estimativa assusta, simplifique o plano.
Em 1 frase: estime tokens, tempo e iteracoes antes de aprovar. Se assusta, simplifique.
# Feature nova "Plan: adicione endpoint POST /api/invoices que cria fatura. Siga o pattern de /api/orders. Inclua validacao de input, testes e migration de DB." # Refactor "Plan: refatore o modulo de notificacoes para usar o pattern Observer. Mantenha a interface publica igual. Rode testes entre cada passo." # Bug fix "Plan: o upload falha para arquivos >5MB. Erro: 'PayloadTooLargeError'. Reproduza, identifique a causa, corrija e adicione teste de regressao."
Qual e a tecnica mais segura para planejar um refactor?
Resumo do Modulo
Proximo modulo:
2-3 — Loop Mode — Automacao Iterativa: como o Claude executa em loop autonomo.