Os quatro trabalhos mais comuns: Explorar código, consertar bugs, refatorar, testar
📚 Navegação da Série: O artigo anterior 15 Como fazer perguntas e dar instruções ensinou você "como falar" — dividindo necessidades vagas em instruções precisas. Este artigo muda a perspectiva: 80% do trabalho diário se resume a essas quatro categorias, e para cada uma eu darei um modelo de instrução que você pode simplesmente copiar e preencher as lacunas para usar.
Amigos, hoje vamos falar de coisas práticas.
Pense bem, o que você realmente faz todos os dias olhando para o código? Resumindo, são quatro coisas que se repetem: assumir um projeto que você não entende, consertar um bug estranho, refatorar uma pilha de código bagunçado e adicionar testes a uma função. Claro que existem outras necessidades, mas essas quatro juntas tomam a maior parte do nosso tempo diário.
O artigo anterior falou sobre "habilidades de comunicação" gerais, mas este abordará cenários específicos — cada um desses quatro trabalhos tem um padrão de ação, e as fórmulas são fixas. Usando o Claude Code por um tempo, você acaba consolidando quatro modelos, salva no seu bloco de notas e, ao deparar com a situação, basta pegar e preencher os espaços.
Dito de outra forma: As habilidades gerais são a energia interior (o chi), esses quatro modelos são os golpes de artes marciais. Você já treinou a energia interior, hoje vou te dar os golpes.
Após ler este artigo, você terá:
- Um modelo de instrução copiável para cada uma das quatro tarefas frequentes (explorar / consertar bug / refatorar / escrever testes)
- O motivo central por trás de "por que escrever assim" para cada categoria, não apenas decorar modelos
- Um cartão de referência rápida para os quatro tipos de tarefas, para salvar e consultar sempre que precisar
- Um guia prático completo (passo a passo para consertar um bug real) com os resultados esperados
01 Primeiro passo: Quatro trabalhos, quatro ferramentas
Antes de colocar a mão na massa, você precisa separar a "personalidade" desses quatro trabalhos. Eles exigem abordagens completamente diferentes do Claude, usar o método errado diminui muito o efeito.
Analogia: Quatro ferramentas na caixa, conheça a função de cada uma. A chave de fenda aperta parafusos, a chave de boca aperta porcas; usar uma chave de boca num parafuso será incômodo. Explorar, consertar bugs, refatorar e escrever testes são quatro ferramentas diferentes — a questão principal não é "saber usar o Claude", mas "qual ferramenta puxar da caixa" para aquele trabalho.
A principal diferença entre elas está numa única dimensão: esse trabalho altera ou não o seu código?
| Trabalho | Altera o código? | O que o Claude faz de principal | No que você deve ficar de olho |
|---|---|---|---|
| Explorar repositório | Não (somente leitura) | Lê arquivos e te explica | Se ele explica corretamente |
| Consertar bug | Sim | Acha a causa raiz + Altera | Achou a raiz? E o teste de regressão? |
| Refatorar | Sim (mas sem mudar comportamento) | Reescrita equivalente | O comportamento continuou o mesmo? |
| Escrever teste | Adiciona arquivo | Gera testes + Cobre os extremos | Cobriu todos os edge cases (casos extremos)? |
Viu só? Explorar tem zero risco (só lê, não escreve), então você pode perguntar sem medo; consertar bugs e refatorar envolvem o bisturi, então você deve fazê-lo explicar primeiro e agir depois; escrever testes fica no meio, ele cria um arquivo novo sem tocar no seu código antigo, mas você precisa ver se ele não teve preguiça e testou só o "caminho feliz".
Lembre-se da lógica dessa tabela, as próximas quatro seções mostrarão como empunhar cada uma dessas ferramentas.
💡 Resumo em uma frase: Diferencie a personalidade das quatro tarefas por "altera o código ou não" — Exploração é risco zero, então pergunte livremente; para trabalhos que usam o bisturi, peça-lhe para explicar antes de alterar.
02 Explorar um código desconhecido: Do grande para o pequeno, em três camadas
Vamos começar com o cenário mais frequente: você assume um projeto totalmente desconhecido e a primeira coisa a fazer é compreendê-lo.
Como a gente fazia isso antes? Abria a pasta, ficava tonto olhando para dezenas de diretórios, clicava em um por um, e depois de duas horas continuava sem entender muito. Agora não precisa mais — o Claude Code trata o diretório atual como a área de trabalho, ele pode ler o projeto inteiro sozinho, você só precisa perguntar.
Analogia: Chegar em uma empresa nova. Você não mergulha no código-fonte de um módulo logo de cara, primeiro você pergunta aos veteranos em três níveis. Nível um: "O que a empresa toda faz e qual a arquitetura geral?"; Nível dois: "Onde fica o código responsável pelo pagamento?"; Nível três: "Num pedido, como o código vai desde a criação até a cobrança?". Do grande para o pequeno, do macro para a linha, esse é o ritmo padrão de exploração.
De acordo com as demonstrações da documentação oficial, essas três camadas correspondem a três tipos de perguntas:
Me dê uma visão geral deste repositório, me conte sobre seu padrão principal de arquiteturaOnde ficam os arquivos responsáveis pela autenticação de usuários? Como esses arquivos trabalham juntos?Rastreie o fluxo de login, do frontend até o banco de dados, mostrando o caminhoUm hábito seguro é que as duas primeiras camadas devem ser perguntadas no Plan Mode (Modo de Planejamento) — ou seja, antes de começar, pressione Shift+Tab duas vezes para mudar para o modo plan (a primeira cai em acceptEdits, a segunda no plan). Por quê? Porque na fase de exploração, queremos apenas que ele leia e explique, não queremos que ele se empolgue e comece a alterar arquivos. No Plan Mode, ele não mexerá no seu código-fonte, não importa o quanto você pergunte.
Por exemplo, se você assumir um projeto legado em Go com 30.000 linhas, no primeiro dia você pode fazer isso: comece com uma "visão geral" para entender os serviços; depois localize gradualmente com "onde fica o código responsável por X"; por fim, escolha uma rota principal "rastreie como essa requisição viaja". Em meio dia você acha o caminho das pedras, antes não levaria menos de dois ou três dias.
Aqui está o modelo de exploração, basta preencher os espaços:
Acabei de assumir este projeto, me ajude a entendê-lo rapidamente. Em três passos:
1. Me dê uma visão geral da arquitetura, explicando os módulos principais e suas responsabilidades
2. Onde estão os arquivos responsáveis por [a feature que te interessa, ex: "pagamento de pedido"]
3. Rastreie o caminho de execução completo de [um fluxo principal, ex: "da criação ao pagamento de um pedido"]
Explique de uma maneira que um novato entenda, e não altere nenhum código por enquanto.💡 Resumo em uma frase: O ritmo da exploração é único — da grande arquitetura ao arquivo e depois à cadeia de execução, em três camadas, é mais seguro perguntar as duas primeiras no Plan Mode.
03 Consertar bug: Colar erro → Achar causa raiz → Alterar → Adicionar teste de regressão
Consertar bugs é o outro trabalho super frequente, e também onde é mais fácil cometer erros.
Por quê? Porque o erro mais comum dos novatos é: colar o erro e dizer "conserta pra mim", e então o Claude dá uma solução que "faz o erro sumir". Atenção: "erro sumir" não é igual a "problema resolvido" — muitas vezes ele apenas mascarou o sintoma, a causa raiz continua lá e vai explodir de novo mais tarde de outro jeito.
Analogia: Ir ao médico porque está doendo. Você não chega e diz "me dá um remédio para a dor", você explica "onde dói, quando começou, qual movimento dói mais", para que o médico faça o diagnóstico primeiro e depois dê a receita. Consertar um bug é exatamente igual — faça-o encontrar a raiz primeiro, não peça a ele para só "dar o analgésico" às pressas.
Uma regra inquebrável enfatizada nas melhores práticas oficiais, que você deveria colar na parede:
Conserte e verifique se o build passa. Resolva a causa raiz, não suprima o erro.
Portanto, o fluxo correto para consertar bugs tem quatro passos, nenhum pode faltar:
- Colar o erro + Passos para reproduzir: O erro completo, stack trace e "o que eu fiz para dispará-lo"
- Pedir a ele para achar a causa raiz: Diga para ele não mudar nada ainda, apenas explicar "por que falhou"
- Dar a correção: Se a raiz estiver certa, deixe-o alterar o código
- Adicionar teste de regressão: Adicione um teste que reproduza esse bug, para garantir que o erro não volte no futuro
O quarto passo é o que os iniciantes mais esquecem, mas é de longe o passo mais valioso. A abordagem oficial é muito inteligente: peça ao Claude para "escrever um teste que falha e reproduza o problema, depois conserte" — assim, quando consertado, o teste ficará verde, o que é o mesmo que colocar um cadeado no bug; se alguém mais tarde mudar aquela linha sem querer, o teste gritará na mesma hora.
Muitas pessoas já sofreram com isso. Por exemplo, consertaram um bug de parser de datas, o Claude mudou, o erro sumiu e commitaram. Duas semanas depois, outro colega estava refatorando e mudou a linha de volta, o mesmo bug ressuscitou ali mesmo — porque como não tinha teste, ninguém sabia que aquela linha não podia ser mexida. Portanto, consertar qualquer bug deve sempre incluir o quarto passo.
Aqui vai o modelo para consertar bugs:
Encontrei um bug.
Mensagem de erro: [Cole o erro e o stack trace completos]
Passos para reproduzir: [O que eu fiz para disparar, acontece às vezes ou sempre?]
Por favor:
1. Primeiro localize a causa raiz, explicando o motivo do erro. Não mude código ainda.
2. Forneça uma solução para resolver a causa raiz, não apenas mascarar o erro.
3. Após alterar, adicione um teste de regressão que reproduza este bug e rode para confirmar que passa.💡 Resumo em uma frase: Quatro passos para bugs — colar erro e reprodução, achar causa raiz, alterar, adicionar teste de regressão; sem o teste de regressão (o cadeado), o mesmo bug voltará mais cedo ou mais tarde.
04 Refatorar: Explicar o estado atual → Definir meta → Pequenos passos → Testar antes e depois
Refatorar é o trabalho de maior risco, porque mexe em "código que não está quebrado".
Ao consertar um bug, há um padrão claro de "consertado" — o erro sumiu e o teste está verde. Na refatoração não, o objetivo é "o código ficar mais limpo, mas o comportamento não pode mudar nem uma vírgula". Se o comportamento mudar, você introduziu um bug sob o pretexto de refatorar, este é o pior tipo de bug, porque ninguém testará ativamente um código "que só foi reorganizado".
Analogia: Reformar uma casa ocupada, mas os moradores não podem sair. Você precisa garantir água, luz e que eles possam morar, enquanto pinta as paredes e arruma a fiação. A refatoração é essa "reforma com os moradores dentro" — a funcionalidade (vida dos moradores) deve ficar intocada do começo ao fim.
Por isso a estratégia segura para refatorar são quatro passos, centrados em "usar testes para travar o comportamento":
- Faça-o explicar o estado atual: Entenda o que o código faz agora e os comportamentos ocultos
- Defina a meta da refatoração: Você quer "dividir funções", "usar sintaxe moderna" ou "remover duplicação"? Seja específico
- Pequenos passos: A documentação recomenda explicitamente "refatorar em pequenos incrementos testáveis", não o deixe reescrever tudo de uma vez
- Testes passam antes e depois: Antes de refatorar, rode os testes para criar uma linha de base, depois de alterar, rode de novo, os resultados das duas devem ser idênticos
O quarto passo é o oxigênio da refatoração. Se o código atual não tem testes, o primeiro passo da refatoração não é mudar o código, é adicionar testes — use o teste como um "snapshot" (foto) do comportamento atual; após a refatoração, verifique contra o snapshot, se não mudar, deu certo. Isso está alinhado com as práticas oficiais: dê ao Claude um jeito de verificar seu próprio trabalho, senão "parece certo" é o único sinal, e refatorações que "parecem certas" são as que mais escondem minas terrestres.
Uma regra rígida que vale a pena seguir: Nunca deixe o Claude refatorar diretamente um código sem cobertura de testes. Imagine deixar ele refatorar rapidamente uma função utilitária sem testes e ele "otimizar" tirando um branch extremo que parecia código morto, mas tratava uma entrada raríssima. Aí explode no servidor de produção. Sempre adicione testes antes de mexer; é mais lento, mas nunca vai quebrar as coisas.
Aqui está o modelo de refatoração:
Eu quero refatorar o [nome do arquivo / função].
Meta da refatoração: [Seja específico, como "dividir em funções menores", "usar sintaxe moderna", "eliminar duplicação"]
Requisitos:
1. Primeiro, explique o comportamento atual deste código, incluindo casos extremos (edge cases) que podem passar despercebidos.
2. Se ele ainda não tiver testes, adicione testes que cubram o comportamento atual antes.
3. Refatore em pequenos passos, mantendo o comportamento externo idêntico.
4. Rode testes antes e depois da refatoração e confirme que os resultados são consistentes.💡 Resumo em uma frase: O oxigênio da refatoração é "o comportamento não pode mudar" — fale sobre o estado atual, defina a meta, dê passos curtos e trave o comportamento com testes rodando antes e depois; se não houver testes, crie-os antes de encostar no código.
05 Escrever testes: O foco é forçá-lo a cobrir casos extremos
O último tipo de trabalho: adicionar testes ao código.
Escrever testes é algo que o Claude faz muito bem na verdade — ele vai olhar seus arquivos de teste existentes e seguir o framework e estilo de asserção que você já usa, alinhando o estilo automaticamente, sem que você precise ensinar. Mas há um problema que você deve saber: se você não for específico, ele por padrão testará apenas os "caminhos felizes" (situações normais).
O que significa testar o caminho normal? Para uma função de divisão, ele pode testar "6 dividido por 2 igual a 3" — está certo, mas e dividido por 0? Se passar número negativo? E null? Esses "casos extremos" (edge cases) são os locais onde os bugs realmente ocorrem, e são o que os testes deveriam focar em cobrir.
Analogia: Contratar alguém para testar a qualidade de um produto, você não pode pedir a ele para testar apenas a "operação normal". O teste valioso é tentar as entradas "bizarras" — vazias, muito grandes, negativas, caracteres zoados. O que falha são sempre os limites, não o fluxo principal. O núcleo de escrever testes é forçar o Claude a testar esses limites.
Portanto, o segredo do modelo de testes resume-se a uma frase: exija explicitamente que ele cubra os casos extremos (edge cases). A boa dica das práticas oficiais é muito parecida — diga a ele claramente "qual função testar, quais cenários testar e se deve usar mock":
Escreva testes para foo.py, cobrindo os casos extremos de usuário desconectado. Evite usar mocks.
Veja a diferença entre duas formas de perguntar:
| ❌ Pergunta Vaga | ✅ Pergunta Precisa |
|---|---|
| "Escreve um teste pra essa função" | "Escreva testes para a função divide, focando em cobrir divisão por 0, números negativos e entrada não numérica como edge cases." |
| Ele testa o caminho feliz, a cobertura é alta mas inútil | Ele testa todos os pontos onde a função explodiria |
E um pequeno truque: use @ para apontar o arquivo para ele diretamente (escrevendo @src/utils/math.py), ele vai ler o arquivo todo antes de agir, isso é bem mais preciso do que descrever "aquela função divide naquele arquivo math". A dica do uso do @ abordada anteriormente brilha muito aqui.
Aqui vai o modelo para escrever testes:
Escreva testes para a [função] no @[caminho_do_arquivo].
Requisitos:
1. Use o framework e o estilo de testes existentes no projeto.
2. Foque em cobrir casos extremos (edge cases): [liste o que conseguir pensar, ex: "entrada vazia, zero, negativo, muito grande, tipo errado"].
3. Pense também se esqueci de algum outro caso extremo e inclua-os nos testes.
4. Após terminar, rode os testes e, se houver falhas, corrija até passar.O ponto 3 é um truque adicional — peça que ele ativamente busque o que você esqueceu. A documentação oficial também diz que o Claude pode analisar caminhos de código para encontrar limites esquecidos. Ao escrever testes você deve colocar esta frase, frequentemente ele acha combinações de entradas que você jamais imaginaria, sendo muito mais completo que uma pessoa tentando listar tudo sozinha.
💡 Resumo em uma frase: Não diga apenas "escreva testes" — obrigue-o explicitamente a cobrir casos extremos (vazio, zero, negativos, erros de tipo), e deixe que ele procure o que você esqueceu; o caminho normal acaba sendo o menos importante.
06 Prática: Usar um bug real para passar pelo processo
Só ver o modelo e não usá-lo é inútil. Vamos praticar "consertar um bug" — é o que mais tem passos; rodar esse te dará fluência para os outros três. Deixei um bug real pronto aqui para você.
Passo 1: Crie um projeto de brinquedo com o bug (Mac / Linux)
mkdir bug-demo
cd bug-demo
echo 'def average(numbers):
return sum(numbers) / len(numbers)' > calc.pyUsuários Windows: digite mkdir e cd, crie o calc.py no Bloco de Notas e cole as duas linhas de Python acima.
Essa função average calcula a média e parece normal — mas passar uma lista vazia causará uma divisão por 0. Este é o bug que iremos consertar.
Resultado Esperado: Há um calc.py na pasta bug-demo, contendo as duas linhas.
Passo 2: Inicie o Claude Code
claudeResultado Esperado: Surge a tela de boas-vindas com o input na parte de baixo.
Passo 3: Aplique o modelo de consertar bug, cole o erro
Digite na entrada (é o modelo da seção 03 preenchido):
Encontrei um bug.
Mensagem de erro: Ao chamar average([]), dá ZeroDivisionError: division by zero
Passos para reproduzir: É 100% reproduzível se passar uma lista vazia para a função average no calc.py
Por favor:
1. Primeiro localize a causa raiz, explicando o motivo do erro. Não mude código ainda.
2. Forneça uma solução para resolver a causa raiz, não apenas mascarar o erro.
3. Após alterar, adicione um teste de regressão que reproduza este bug e rode para confirmar que passa.Resultado Esperado: O Claude primeiro vai te contar a causa raiz — se a lista é vazia, len(numbers) é 0, causando divisão por 0; em seguida vai propor um diff (como retornar 0, ou lançar um erro mais claro), e esperar sua aprovação; após a aprovação, ele também criará um novo arquivo de teste (como test_calc.py), com um teste específico para a lista vazia.
Passo 4: Aprove as alterações e observe o teste rodar
Se o diff estiver bom, escolha "Concordo / Yes". O Claude rodará o teste que acabou de criar.
Resultado Esperado: Ver no terminal algo como:
test_calc.py::test_average_empty_list PASSED
test_calc.py::test_average_normal PASSEDTeste todo verde = O bug foi morto, e um cadeado foi colocado nele — se alguém reverter essa linha amanhã, o teste fica vermelho e avisa na hora.
Passo 5: Saia e confirme que o arquivo mudou
Saia do Claude (digite exit ou pressione Ctrl+D), volte ao terminal e olhe:
cat calc.py(Windows PowerShell use type calc.py)
Resultado Esperado: Em calc.py, a função average já deve ter um tratamento para lista vazia, e você terá um arquivo de teste na mesma pasta. Corresponde ao diff que você aprovou = Processo concluído. Parabéns!
⚠️ Aviso: Se no passo 3 o Claude não tentar escrever testes, é provável que você omitiu o ponto 3 do modelo. Não corte aquela frase — O cadeado do teste de regressão é o que separa novatos dos veteranos.
💡 Resumo em uma frase: Rodamos todo o processo de bug na prática — colocamos um bug real, usamos o modelo para fazê-lo achar a raiz e consertar, e o vimos rodar o teste verde. Dominando esse, você sabe lidar com as outras três tarefas também.
07 Conclusão
Este artigo separou 80% do seu trabalho diário em quatro categorias, fornecendo uma estratégia fixa e um modelo copiável para cada:
| Tarefa | Essência do Modelo em uma Frase | Ponto mais Crítico |
|---|---|---|
| Explorar repositório | "Arquitetura → Onde está o código do X → Rastrear um fluxo" | Perguntar em três níveis (macro ao micro), os dois primeiros no Plan Mode |
| Consertar bug | "Colar erro e reprodução → Achar raiz → Alterar → Adicionar Teste" | Resolva a causa, não sintomas; nunca corte o teste de regressão |
| Refatorar | "Estado atual → Meta → Passos curtos → Testar antes e depois" | Comportamento não pode mudar, se não houver teste, adicione primeiro |
| Escrever teste | "Testes, focando em vazio/zero/negativo/erros de tipo" | Force-o a testar edge cases e peça que ele encontre mais limites para testar |
O que você deve saber agora: Para qualquer tarefa dessas, não fique confuso olhando para a tela piscando — simplesmente chame o modelo correspondente, preencha-o, saiba o que mandar o Claude fazer primeiro e fique de olho nas armadilhas. Esses quatro modelos são a fundação do seu trabalho diário com a ferramenta; com o tempo você verá que trabalhos maiores são sempre combinações lógicas dessas quatro tarefas básicas.
Esses quatro modelos suportarão testes constantes no dia a dia — Por mais sofisticada que seja a tarefa, ela acabará caindo em uma dessas abordagens.
No próximo artigo 17 "Imagens e Multimodal" — Até agora, estávamos "digitando instruções", mas tem coisa difícil de explicar por texto: um print de erro, um layout do Figma, um diagrama do banco de dados. O próximo artigo ensinará como alimentar imagens diretamente para o Claude, para que ele possa trabalhar olhando a imagem. Já pensou que se jogasse para ele aquele print com o erro cabuloso do terminal você teria salvo um bom tempo?