Boas práticas do Claude Code: hábitos que dão melhores resultados
13 min de leitura
Quando uma sessão do Claude Code dá errado, a causa quase sempre é uma de duas. O Claude construiu algo diferente do que você tinha em mente, ou disse "pronto" quando o trabalho não estava pronto. Nenhuma das duas é fraqueza da ferramenta. As duas vêm de informação que o Claude não tinha.
Diga ao Claude o que ele não consegue ver e dê a ele um jeito de conferir o próprio trabalho.
Os hábitos abaixo são os que mais importam, na ordem em que você vai usá-los. Eles partem do princípio de que você já instalou o Claude Code e rodou uma sessão. Se não, comece com Claude Code para iniciantes.
Como roda uma boa sessão
O Claude Code trabalha em um ciclo: reúne contexto, age e verifica o resultado. Você também está nesse ciclo. Pode interromper a qualquer momento para corrigir a rota. Cada hábito deste guia melhora uma parte do ciclo.
Hábito 1: diga ao Claude só o que ele não consegue ver
O Claude começa toda tarefa lendo o seu código, e faz isso bem. Ele descobre a estrutura de pastas, o framework de testes e o jeito como os componentes existentes são feitos, em geral mais rápido do que você explicaria. Isso significa que quase tudo o que você tem vontade de escrever ele já sabe.
O que ele não consegue achar é informação que nunca esteve no repositório: uma decisão tomada numa reunião, um processo de deploy que mora na cabeça de uma pessoa, a variável de ambiente de que seus testes de integração precisam. Faça duas perguntas antes de acrescentar uma linha a um prompt ou ao CLAUDE.md:
- O Claude acharia isso lendo o código?
- Ele realmente iria procurar?
Se as duas respostas forem sim, deixe de fora. Listas longas de fatos óbvios enterram o único fato que importa. O próximo guia, CLAUDE.md explicado, mostra onde ficam os fatos duradouros.
Hábito 2: escreva um prompt específico
Um prompt específico funciona pelo mesmo motivo: dá ao Claude informação que ele não tem. Cite o arquivo ou a área, descreva o sintoma e diga como é o "corrigido". Se você prefere uma entre duas abordagens razoáveis, diga qual, porque o Claude não consegue ler isso no código.
| Em vez de | Tente |
|---|---|
fix the login bug | users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it |
add a calendar widget | follow the pattern in HotDogWidget.php and build a calendar widget that lets you pick a month and page between years. no new libraries |
clean up this file | split utils.ts into one file per concern. keep every export name the same so no import breaks |
Os prompts melhores dizem o lugar, a prova e os limites. Não são mais longos por vaidade. Cada trecho acrescentado elimina um palpite.
O checkout falha para usuários com cartão vencido. O código relevante está em src/payments/. Investigue primeiro e me diga o que encontrou. Não altere nada até eu mandar.
”Repare na delegação nesse prompt. Você dá contexto e direção, e deixa o Claude descobrir quais arquivos ler e quais comandos rodar.
Palavras mágicas não existem
Frases como "pense passo a passo" ou "seja minucioso" são texto comum de prompt, não interruptores. O quanto o Claude pensa é definido pelo nível de esforço, que você muda nas configurações do modelo, e não pela redação.
Hábito 3: entregue a coisa em vez de descrevê-la
Se você já tem o que o Claude precisa, entregue direto. Digitar a descrição de um erro é mais lento e menos preciso do que o próprio erro.
- 1
Referencie um arquivo com @
Digite
@e o caminho, como@src/auth/session.ts, para colocar o conteúdo desse arquivo na sua mensagem. - 2
Cole uma imagem
Cole uma captura de tela do design que você quer ou do erro que você vê. O Claude lê imagens.
- 3
Envie a saída de um comando
Mande a saída direto do seu shell, por exemplo
cat error.log | claude -p "what's going on here".
Hábito 4: deixe o Claude entrevistar você quando não tiver certeza
Você não precisa fechar o plano inteiro antes de escrever o prompt. Quando a ideia ainda está nebulosa, peça ao Claude que faça perguntas até conseguir escrever a especificação:
Quero adicionar limite de requisições à API pública, mas ainda não pensei direito. Me entreviste até conseguir escrever a especificação e depois escreva-a em SPEC.md.
”O Claude volta com perguntas sobre as partes que você ainda não definiu: por usuário ou por chave, o que acontece com as requisições acima do limite, o que fica fora do escopo. Quando as respostas fecham, ele escreve o SPEC.md. Inicie uma sessão nova para construir a partir desse arquivo, de modo que a construção comece com um contexto limpo e uma definição escrita de "pronto".
Para qualquer coisa com risco real, acrescente a etapa de plano do guia de permissões. Modos de permissão e modo plan do Claude Code, explicados mostra como fazer o Claude explorar e propor antes de editar.
Hábito 5: dê ao Claude uma verificação para rodar
Este é o hábito de maior efeito. O Claude para quando o trabalho parece pronto. Se ele não tem nada para rodar que diga se o trabalho está mesmo pronto, "parece pronto" é tudo o que ele tem. Na prática você vira a suíte de testes, e cada erro espera você notar.
Dê a ele algo que volte como passou ou falhou, e o Claude fecha o ciclo sozinho: faz a mudança, roda a verificação, lê a falha, corrige e roda a verificação de novo.
A verificação pode ser quase qualquer coisa cujo resultado o Claude consiga ler:
- um arquivo de teste
- o código de saída de um build
- um linter ou uma checagem de tipos
- um script que compara a saída com um exemplo salvo
- uma captura de tela do navegador ao lado do mockup
Se o seu projeto já tem uma, a linha mais útil do seu CLAUDE.md é o comando que a roda. O quanto a verificação é rígida fica por sua conta:
| Nível | Como | Bom para |
|---|---|---|
| No prompt | run the auth tests after, and keep going until they pass | Qualquer tarefa, sem preparação |
| Como meta | /goal all tests in tests/auth pass and lint is clean define uma condição que um modelo separado confere a cada turno | Execuções longas sem ninguém olhando |
| Como hook Stop | Um script que roda quando o Claude tenta terminar e o manda de volta ao trabalho se falhar | Uma regra que sempre deve valer |
| Por um revisor novo | /code-review confere o diff num subagente novo que nunca viu a sua conversa | Uma segunda opinião |
A verificação para começar
Adicione o comando de teste exato ao CLAUDE.md e termine seus prompts com "rode e me mostre a saída". Só isso resolve a maioria dos problemas de "ele disse que tinha terminado".
Hábito 6: peça evidência, não garantias
"Todos os testes passam" sozinho diz muito pouco. Peça ao Claude que mostre o comando que rodou e a saída, ou a captura de tela. Ler a saída é mais rápido do que rodar a verificação você mesmo e, numa sessão que você não acompanhou, é a única prova que você tem.
Quando o Claude disser que terminou, você também pode rodar /verify, que faz o Claude montar e executar o app e olhar o resultado. Isso pega o tipo de problema que testes e checagens de tipos deixam passar, como uma página que tecnicamente carrega mas está visivelmente quebrada.
Dentro do Claude Tutorial
Conferir o trabalho faz parte da habilidade
Saber o que verificar e pedir provas vale para todo tipo de trabalho com o Claude, e o app pratica isso com tarefas reais, não só de código.
Hábito 7: observe o primeiro minuto e corrija cedo
Nenhuma configuração substitui acompanhar o começo de uma tarefa e intervir quando o Claude vai para onde você não queria. Decore estes controles:
Escpara o Claude no meio de uma ação e mantém tudo até aquele ponto, então você redireciona sem perder trabalho.- Digitar e apertar Enter enquanto o Claude trabalha coloca uma correção na fila. O Claude a lê assim que as chamadas de ferramenta em andamento terminam e se ajusta.
/rewind, ouEscduas vezes num prompt vazio, abre um menu em que você volta o código, a conversa ou os dois a um ponto anterior. Isso torna pouco arriscado tentar primeiro a abordagem mais ousada./btwfaz uma pergunta rápida paralela sem acrescentá-la ao histórico da conversa.
O rewind cobre arquivos que o Claude editou, não tudo
Arquivos alterados só por um comando de shell não são restaurados, nem bancos de dados ou deploys. O rewind funciona junto com o git. Não o substitui.
Hábito 8: depois de duas correções que falharam, recomece
Se você corrigiu a mesma coisa duas vezes e continua errado, uma terceira correção se soma a uma conversa que já contém duas tentativas fracassadas para o Claude reler. Rode /clear e escreva um único prompt novo que inclua o que você aprendeu.
Parece perder progresso. Quase sempre funciona melhor. Usar /clear entre tarefas sem relação também é um bom hábito por si só, porque um contexto focado dá respostas melhores e custa menos.
Para trabalhos que se estendem por vários dias, dê um nome à sessão com /rename oauth-migration e retome-a depois com claude --resume oauth-migration. O claude --continue retoma a mais recente.
Hábito 9: mantenha as regras curtas e tire as regras duras da prosa
Tudo o que você diz ao Claude num prompt ou no CLAUDE.md é um pedido que o modelo lê e em geral segue. Um hook, uma regra de negação (deny) ou uma configuração gerenciada é diferente: o Claude Code a aplica sempre, não importa o que o modelo decida.
Use o primeiro tipo para quase tudo, porque o Claude é bom em julgar quando uma orientação se aplica. Use o segundo para as poucas regras que não podem ter exceção, como "nunca edite o cliente gerado" ou "sempre rode o formatador depois de criar um arquivo".
Um sinal que vale notar
Se você continua reforçando uma linha do CLAUDE.md e o Claude ainda a deixa passar, a linha pertence a um hook. O inverso também vale: se você criou hooks para coisas que são só preferências, apague-os.
Se a sua sessão ficar longa, confira o /context para ver o que está ocupando espaço. O Claude compacta a conversa automaticamente, e um resumo pode perder instruções detalhadas do começo. Regras permanentes pertencem ao CLAUDE.md, que é lido de novo do disco depois do /compact. Você também pode orientar o resumo: /compact focus on the API changes.
Conselhos que você pode parar de seguir
Algumas dicas antigas eram gambiarras para coisas que os modelos anteriores não faziam. Os modelos atuais alcançaram isso, e as gambiarras agora custam mais do que dão.
| Conselho antigo | Por que você pode largá-lo |
|---|---|
| Gerencie a janela de contexto agressivamente | A maioria dos modelos atuais tem uma janela enorme e a compactação é automática. Usar /clear entre tarefas ainda vale a pena. |
| Ponha IMPORTANT ou CAIXA ALTA nas regras | O texto simples é seguido, e a ênfase faz o Claude aplicar a regra em excesso. Uma regra que não pode ceder é um hook. |
| Diga "pense muito" ou "seja minucioso" | O esforço é o controle de verdade. Essas frases só dão um empurrão dentro dele. |
| Diga ao Claude para continuar e não ser preguiçoso | Os modelos seguem em frente numa tarefa combinada. Dar ao Claude uma verificação para passar é outra coisa, e ainda vale a pena. |
| Descreva sua arquitetura no CLAUDE.md | O Claude lê o repositório. Escreva só o que ele não consegue achar. |
| Use um subagente para obter uma resposta melhor | Delegar a mesma tarefa não a melhora. Um revisor novo ajuda porque não viu o seu raciocínio, e isso é outra coisa. |
Perguntas frequentes
Como obtenho melhores resultados com o Claude Code?
Dê a ele informação que ele não consegue ver, escreva prompts específicos, entregue arquivos e erros em vez de descrevê-los e dê uma verificação que passa ou falha. Depois corrija cedo com Esc e rode /clear quando as correções não estiverem funcionando.
Por que o Claude Code diz que terminou quando não terminou?
Ele para quando o trabalho parece pronto. Se nada que ele possa rodar provar o contrário, "parece pronto" é tudo o que ele tem. Dê a ele um teste, build ou linter para rodar e peça que mostre a saída.
Devo usar o modo plan sempre?
Não. Use quando a mudança toca muitos arquivos, quando você ainda não entende o código ou quando um erro sairia caro. Para uma mudança de uma frase, peça direto.
Quando devo usar o /clear?
Entre tarefas sem relação e depois de duas correções que falharam para o mesmo problema. Comece o prompt novo com o que você aprendeu.
Qual é a diferença entre o CLAUDE.md e um hook?
O CLAUDE.md são instruções que o Claude lê e em geral segue. Um hook é um script que o Claude Code executa num ponto fixo, então acontece independentemente do que o modelo decida. Use um hook para uma regra sem exceções.
Como retomo a sessão do Claude Code de ontem?
Rode claude --continue para a conversa mais recente, ou claude --resume para escolher uma. Se você deu um nome à sessão com /rename, use claude --resume <nome>.
Seu checklist de hábitos
Seu prompt diz o lugar, o sintoma ou objetivo e como é o "pronto"
O Claude tem um comando que pode rodar e que volta como passou ou falhou, e você pediu para ver a saída
Você observou o primeiro minuto e conhece
Esc,/rewinde/clearO CLAUDE.md guarda só o que o Claude não acha no código, e as regras que nunca podem ceder são hooks
Você lê o diff antes de fazer o commit, como faria com o pull request de um colega
Continue lendo
- Claude Code para iniciantes: instale, entre e faça sua primeira tarefa para configurar e rodar sua primeira sessão.
- CLAUDE.md explicado: ensine o seu projeto ao Claude Code uma vez só para o arquivo que leva suas regras de uma sessão a outra.
- Modos de permissão e modo plan do Claude Code, explicados para escolher quanto o Claude pode fazer sem perguntar.
- O que fazer quando o Claude não faz o que você pediu para o mesmo problema no app de chat.
- Como fazer mudanças em vários arquivos com o Claude Code para esses hábitos aplicados a uma mudança em muitos arquivos.