Fluxo Prompt-para-PR com Claude Code: Diffs Pequenos

Por que Prompt-para-PR vence prompts grandes e de uma só vez

Prompts grandes de uma só vez frequentemente levam a mudanças grandes e confusas: dezenas de arquivos alterados, refatores não relacionados e código que você não teve tempo de entender. Mesmo que o resultado seja tecnicamente correto, a revisão parece arriscada porque é difícil ver o que mudou e por quê.

Diffs pequenos resolvem isso. Quando cada mudança é limitada e focada, você consegue ler em minutos, pegar erros cedo e evitar quebrar coisas que não pretendia tocar. Revisores confiam mais em PRs pequenos, então merges acontecem mais rápido e com menos idas e vindas.

Prompt-para-PR é um loop simples:

• Peça uma mudança pequena com limites claros.
• Verifique o diff e confirme que bate com a intenção.
• Rode suas verificações habituais (testes, lint, build).
• Se algo falhar, re-prompt com o erro e contexto exatos.
• Repita até estar pronto para mesclar.

Essa cadência transforma falhas em feedback rápido em vez de uma surpresa no fim. Se você pedir ao Claude Code para ajustar uma regra de validação, mantenha somente essa regra. Se um teste falhar, cole a saída que falhou e peça a menor correção que faça o teste passar, não uma reescrita do módulo inteiro.

Uma coisa não muda: você continua responsável pelo código final. Trate o modelo como um par de programação local que digita rápido, não como um piloto automático. Você decide o que entra, o que fica de fora e quando é seguro abrir o PR.

Prepare seu repositório e sua configuração de pareamento local

Comece a partir de uma base limpa. Se sua branch estiver atrás ou os testes já estiverem falhando, toda sugestão vira chute. Puxe as últimas alterações, rebase ou faça merge conforme a preferência do time e garanta que o estado atual esteja saudável antes de pedir qualquer coisa.

Uma configuração de “programador em par local” significa que o Claude Code edita arquivos no seu repo enquanto você mantém o controle do objetivo, das guardrails e de cada diff. O modelo não conhece seu código a menos que você mostre, então seja explícito sobre arquivos, restrições e comportamento esperado.

Antes do primeiro prompt, decida onde as verificações irão rodar. Se você consegue rodar testes localmente, terá feedback em minutos, o que mantém iterações pequenas. Se algumas verificações só rodam em CI (certas regras de lint, suítes longas, etapas de build), decida quando vai depender do CI para não ficar esperando após cada mudança pequena.

Um pré-voo simples:

• Atualize sua branch e confirme que a app compila ou inicia.
• Rode as verificações rápidas localmente (lint, testes unitários, checagem de tipos).
• Anote quais verificações são só em CI e quanto tempo costumam levar.
• Confirme que você consegue reproduzir o problema ou ver claramente a funcionalidade faltante.
• Garanta que você consegue desfazer mudanças facilmente (status limpo, commits pequenos).

Mantenha um bloco de notas pequeno aberto enquanto trabalha. Anote restrições como “sem mudanças na API”, “manter compatibilidade retroativa”, “tocar apenas o módulo X”, além de decisões que tomar. Quando um teste falhar, cole a mensagem exata de falha ali também. Esse bloco vira a melhor entrada para seu próximo prompt e evita que a sessão se disperse.

Escreva prompts que conduzam naturalmente a diffs pequenos

Diffs pequenos começam com um prompt propositalmente estreito. A rota mais rápida para código mergeável é uma mudança que você consegue revisar em um minuto, não um refactor que leva uma hora para entender.

Um bom prompt nomeia um objetivo, uma área do código e um resultado esperado. Se você não consegue apontar onde a mudança deve acontecer (um arquivo, pasta ou módulo), o modelo vai chutar e o diff se espalhará.

Um formato de prompt que mantém a mudança enxuta:

• Objetivo: o único comportamento que você quer alterar.
• Localização: o(s) arquivo(s) ou componente(s) a serem tocados.
• Restrições: o que não pode mudar.
• Aceitação: o que significa “pronto”.
• Tamanho do diff: solicite explicitamente a menor mudança que funcione.

Limites são a arma secreta. Em vez de “conserte o bug de login”, diga o que deve permanecer igual: “Não mude a forma da API”, “Não renomeie funções públicas”, “Sem edições só de formatação”, “Evitar novas dependências.” Isso indica ao seu par onde não ser criativo.

Quando a mudança ainda estiver incerta, peça um plano antes do código. Um plano curto força o trabalho em passos e te dá a chance de aprovar um primeiro movimento pequeno.

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

Se você trabalha num time, acrescente restrições de revisão também: “Mantenha abaixo de ~30 linhas alteradas” ou “Um arquivo apenas, a menos que seja absolutamente necessário.” Isso torna o diff mais fácil de ler e deixa os prompts de acompanhamento mais precisos quando algo falha.

Escolha a unidade certa de trabalho para cada iteração

Mantenha cada loop focado em uma pequena mudança testável. Se você consegue descrever o objetivo em uma frase e prever quais arquivos irão mudar, é o tamanho certo.

Boas unidades de trabalho incluem: consertar um bug em um caminho específico (com um repro e uma proteção), ajustar um único teste para um comportamento, fazer um refactor que preserve comportamento (renomear, extrair função, remover duplicação) ou melhorar uma mensagem de erro ou regra de validação.

Defina um limite de tempo para cada loop. Dez a vinte minutos geralmente são suficientes para escrever um prompt claro, aplicar o diff e rodar uma verificação rápida. Se você ainda estiver explorando após 20 minutos, diminua a unidade ou mude só para investigação (anotações, logging, teste que falha) e pare por ali.

Defina “pronto” antes de começar:

• A mudança fica dentro dos arquivos e do comportamento pretendidos.
• Uma verificação prova que funciona (teste, lint ou um passo simples de execução).
• Sem novos avisos ou mudanças de formatação barulhentas.
• O diff é fácil de explicar em duas frases.

Quando o escopo começar a crescer, pare cedo. Se você se pegar dizendo “já que estamos aqui,” você acabou de achar a próxima iteração. Capture-a como follow-up, commit o diff pequeno atual e siga em frente.

Revise o diff antes de rodar verificações

Antes de rodar testes ou builds, leia o diff como um revisor faria. É aqui que o fluxo ou se mantém limpo ou escorrega silenciosamente para “por que tocou esse arquivo?”.

Comece pedindo ao Claude Code para resumir o que mudou em linguagem simples: arquivos tocados, mudança de comportamento e o que não foi alterado. Se ele não conseguir explicar claramente, o diff provavelmente está fazendo demais.

Depois revise você mesmo. Faça uma leitura superficial para checar escopo, depois leia buscando intenção. Você procura deriva: formatação não relacionada, refatores extras, renomeação de símbolos ou mudanças que não foram pedidas.

Uma checagem rápida prévia:

• Os arquivos alterados batem com o que você pediu?
• Há edições casuais (troca de espaços, refatores não relacionados)?
• Introduziu novo comportamento que você não solicitou?
• Há nova dependência ou mudança de config que precise de uma razão real?
• Um revisor conseguiria entender sem ler cinco outros arquivos?

Se o diff estiver maior do que o esperado, não tente testar pra consertar. Refaire e re-prompt por um passo menor. Por exemplo: “Apenas adicione um teste que reproduza o bug. Sem refatores.” Diffs pequenos mantêm falhas mais fáceis de interpretar e tornam o próximo prompt mais preciso.

Rode verificações após cada pequena mudança

Diffs pequenos só valem se você os verificar imediatamente. O objetivo é um loop apertado: mude pouco, verifique pouco, pegue erros enquanto o contexto está fresco.

Comece pela verificação mais rápida que consiga dizer “isto está quebrado”. Se você mudou formatação ou imports, rode lint ou formatação primeiro. Se alterou lógica de negócio, rode os menores testes unitários que cobrem o arquivo ou pacote. Se editou tipos ou configuração de build, faça uma compilação rápida.

Uma ordem prática:

• Lint ou formatação.
• Testes unitários direcionados para a área alterada.
• Build ou checagem de tipos para confirmar que tudo ainda se encaixa.
• Suites mais lentas (integração, e2e) depois que o básico passar.

Quando algo falhar, capture duas coisas antes de consertar qualquer coisa: o comando exato que rodou e a saída completa do erro (copie como está). Esse registro mantém o próximo prompt específico e evita ciclos “ainda falha”.

Mantenha o escopo apertado. Se lint e testes falharem, conserte o lint primeiro, rode de novo e então trate os testes. Não misture “limpezas rápidas” com a correção de um crash no mesmo passo.

Re-prompt com as falhas até as verificações ficarem verdes

Quando verificações falham, trate a saída de erro como seu próximo prompt. O loop mais rápido é: cole o erro, peça um diagnóstico, aplique a menor correção, rode de novo.

Cole falhas literalmente, incluindo o comando e o stack trace completo. Peça a causa mais provável primeiro, não um menu de opções. Claude Code se sai melhor quando pode ancorar em números de linha e mensagens exatas em vez de chutar.

Acrescente uma frase sobre o que você já tentou para não receber soluções repetidas. Repita restrições importantes (“Não mude APIs públicas”, “Mantenha o comportamento atual, apenas conserte o crash”). Então peça o menor patch que faça a verificação passar.

Um bom prompt de falha inclui:

• A saída que falhou exatamente (verbatim).
• O(s) arquivo(s) e linhas envolvidas.
• O que você mudou no último diff.
• O que já tentou.
• Um pedido pela menor correção que faça a verificação passar.

Se a correção proposta mudar comportamento, peça um teste que comprove o novo comportamento. Se um handler agora retorna 400 em vez de 500, solicite um teste focado que falhe no código antigo e passe com a correção. Isso mantém o trabalho honesto e torna o PR mais confiável.

Pare quando as verificações estiverem verdes e o diff ainda parecer uma só ideia. Se o modelo começar a melhorar código não relacionado, re-prompt com: “Apenas trate o teste que falhou. Sem limpeza.”

Faça o PR fácil de revisar e mesclar

Um PR é aprovado mais rápido quando é óbvio o que mudou, por que mudou e como provar que funciona. Com esse fluxo, o PR deve ler como uma história curta: passos pequenos, razões claras.

Mantenha commits alinhados com suas iterações. Se você pediu uma mudança de comportamento, faça esse commit. Se depois consertou um teste, faça o próximo commit. Revisores conseguem seguir o caminho e confiar que você não enfiou mudanças extras.

Escreva mensagens de commit para intenção, não nomes de arquivo. “Corrige redirecionamento de login quando a sessão expira” é melhor que “Atualiza middleware auth.” Quando a mensagem nomeia o resultado para o usuário, revisores gastam menos tempo adivinhando.

Evite misturar refatores com mudanças de comportamento no mesmo commit. Se quiser renomear variáveis ou mover helpers, faça separadamente (ou pule por agora). Ruído atrasa revisão.

Na descrição do PR, seja curto e concreto:

• O que mudou (1–2 frases).
• Por que mudou (o bug ou requisito).
• Como testar (passos exatos, incluindo flags ou dados necessários).
• O que você não mudou (para ajustar expectativas).
• Qualquer risco ou nota de rollback.

Exemplo: uma página de billing quebrava por um customer nulo. Commit 1 adiciona uma proteção e mostra um estado de erro claro. Commit 2 adiciona um teste para o caso nulo. A descrição do PR diz: “Abra Billing, carregue um cliente sem profile, confirme que a página mostra o novo estado vazio.” Esse tipo de PR que revisores aprovam rápido.

Armadilhas comuns que te deixam lento

Essa cadência quebra quando o escopo se expande silenciosamente. Um prompt que começa “conserte este teste que falha” vira “melhore o tratamento de erros no módulo inteiro” e, de repente, você revisa um diff grande com intenção obscura. Mantenha apertado: um objetivo, um conjunto de mudanças, um conjunto de verificações.

Outro freio é aceitar refatores bonitinhos só porque parecem melhores. Renomes, movimentação de arquivos e mudanças de estilo criam ruído na revisão e dificultam ver a verdadeira mudança de comportamento.

Armadilhas comuns:

• Deixar o modelo tocar arquivos não relacionados “já que está aqui”.
• Remediar sintomas (checagens nulas extras) em vez da causa raiz apontada pelo teste.
• Colar só as últimas linhas de logs, escondendo o erro inicial.
• Pular a rápida varredura do diff antes de rodar verificações.
• Re-promptar com “ainda falha” sem o comando e saída exatos.

Um exemplo concreto: um teste falha com “expected 400, got 500.” Se você colar só o final do stack trace, normalmente recebe sugestões genéricas de try/catch. Se colar a saída completa do teste, pode ver o problema real: uma validação faltando. Isso leva a um diff pequeno e focado.

Antes de commitar, leia o diff como um revisor. Pergunte: cada linha serve ao pedido e eu consigo explicar em uma frase? Se não, reverta as mudanças extras e re-prompt por um pedido mais estreito.

Exemplo: correção de bug até PR mergeável em alguns loops

Um usuário relata: “A página de configurações às vezes volta para os padrões depois de salvar.” Você puxa main, roda testes e vê uma falha. Ou não há testes, apenas um repro claro.

Trate como um loop: um pedido pequeno, um diff pequeno, então verificações.

Primeiro, dê ao Claude Code o menor contexto útil: saída de teste que falhou (ou passos para reproduzir), caminho do arquivo suspeito e o objetivo (“mantenha comportamento igual exceto consertar o reset”). Peça diagnóstico e um patch mínimo, não um refactor.

Então trabalhe em loops curtos:

1. Loop 1 (patch mínimo): Aplique a menor mudança que plausivelmente corrige o bug. Mantenha apertado: uma condição de proteção, uma checagem nula faltando, um valor padrão errado ou uma lista de dependência incorreta.

Rode verificações depois de revisar o diff.

2. Loop 2 (alimente com a falha exata): Se testes falharem, copie a saída que falhou de volta ao Claude Code. Inclua nome do arquivo, número de linha e a mensagem de asserção. Pergunte: “Qual a menor mudança para corrigir essa falha sem ampliar o escopo?”

Se as verificações passarem mas você teme regressões, acrescente cobertura.

3. Loop 3 (ajuste de teste ou novo teste): Adicione um teste que falhe sem o patch e passe com ele. Foque no bug. Rode verificações de novo.

Finalize com uma descrição de PR pequena: qual era o bug, por que aconteceu e o que mudou. Adicione uma nota para o revisor tipo “toca apenas o arquivo X” ou “adicionou um teste para o caso de reset” para que a revisão pareça segura.

Checklist rápido antes de abrir o PR

Bem antes de abrir o pull request, faça uma última passada para garantir que o trabalho seja fácil de revisar e seguro para mesclar.

• O diff corresponde ao objetivo original e é pequeno o suficiente para entender em poucos minutos.
• Você rodou as verificações relevantes (testes, lint, typecheck, build) e passaram. Se o time usa CI, confirme que o mesmo conjunto rodará lá.
• A mudança tem a cobertura adequada: um teste para o bug/feature quando prático, ou uma razão clara para não ter teste.
• A descrição do PR é específica: o que mudou, por que mudou e passos exatos para verificar.
• Não há edições casuais: formatação não relacionada, renomes de estilo ou refatores desnecessários.

Um exemplo rápido: se você consertou um bug de login e também reformatou 20 arquivos, desfaça o commit de formatação. Seu revisor deve focar no conserto do login, não se perguntar o que mais mudou.

Se algum item falhar, faça mais um pequeno loop: gere um diff minúsculo, rode verificações e atualize as notas do PR. Esse último loop costuma poupar horas de vai-e-volta.

Próximos passos: torne essa cadência um hábito

Consistência transforma uma boa sessão em um fluxo confiável. Escolha um loop padrão e rode do mesmo jeito sempre. Após uma semana, você notará prompts mais curtos e diffs mais fáceis de revisar.

Uma rotina simples:

• Escolha um resultado minúsculo (um bug, um caso de borda, uma função).
• Peça um diff pequeno e uma explicação breve do que mudou.
• Leia o diff como revisor, então rode verificações localmente.
• Re-prompt com a saída exata do erro e nomes de arquivos.
• Pare no momento em que as verificações estiverem verdes e a mudança estiver clara.

Um template pessoal de prompt ajuda a se disciplinar: “Mude apenas o necessário. Toque no máximo 2 arquivos. Mantenha comportamento público igual a menos que eu diga o contrário. Diga o comando para rodar e o que significa sucesso.”

Se você está construindo dentro do Koder.ai, pode usar o mesmo loop na interface de chat. O modo de planejamento é útil para escopar o menor pedaço mergeável (entradas, saídas e critérios de aceitação), e snapshots e rollback ajudam a recuperar rápido quando um experimento sai do controle.

Quando a mudança estiver estável, exporte o código-fonte para rodar suas ferramentas locais habituais, CI e revisão por colegas no repositório normal. Faça deploy quando precisar de validação no mundo real, por exemplo para checar um fluxo ponta a ponta.

Adote o loop como padrão. Prompts pequenos, diffs pequenos, verificações frequentes e correções rápidas culminam em PRs que dão sono no melhor sentido: seguros, simples e facilmente aprováveis.