Fala Gafanhoto! Adriano Viana aqui.
Se você está por aqui, provavelmente já usa o Claude Code (ou quer começar). Mas deixa eu te contar: você está usando apenas 30% do potencial da ferramenta.
Não porque você é ruim. Mas porque ninguém te ensinou direito.
Passei os últimos 6 meses testando Claude Code em projetos reais. Identifiquei 5 erros que TODO MUNDO comete (eu incluído no começo).
Hoje você vai aprender a corrigir todos eles.
Tempo de leitura: 10 minutos
Impacto: Economizar 10-15h/semana
Vamos lá.
🎯 O Problema
Você usa o Claude Code diariamente.
Mas sempre esbarra nos mesmos problemas:
Código genérico que precisa ser reescrito
Contexto que "evapora" no meio do trabalho
Features que levam 3x mais tempo que deveriam
Bugs que aparecem do nada
Sensação de estar "lutando" com a ferramenta
Resultado: você perde 2-3 horas por dia ajustando código que deveria estar pronto.
O problema não é o Claude Code. É como você está usando.
Aqui estão os 5 erros e as soluções:
❌ ERRO 1: Pedir Tudo de Uma Vez
O que você faz (errado):
"Crie um app completo com:
- Sistema de login
- Dashboard com gráficos
- API REST
- Testes unitários
- Deploy na Vercel"
Por que não funciona:
Claude Code tenta fazer tudo. Resultado:
Perde o contexto
Código genérico
Arquitetura ruim
Você passa 3h ajustando
✅ Solução: Use Plan Mode ANTES de pedir código
Prompt correto:
/plan
"Preciso de um app com login e dashboard.
Requisitos:
- Next.js 14 (App Router)
- Autenticação simples (email/senha)
- Dashboard com 3 gráficos
- Dados mockados inicialmente
Sugira a melhor arquitetura e divida em etapas executáveis."
O que acontece:
Claude divide em 5-7 tarefas pequenas:
Setup inicial (10 min)
Autenticação (15 min)
Layout do dashboard (10 min)
Mock de dados (5 min)
Gráfico 1 (15 min)
Gráfico 2 (15 min)
Gráfico 3 (15 min)
Você aprova o plano. Aí ele executa.
Resultado:
Contexto preservado
Código 10x melhor
Você controla o processo
Economia: 40% do tempo
❌ ERRO 2: Não Dar Contexto Suficiente
O que você faz (errado):
"Conserta esse bug"
Por que não funciona:
Claude vai adivinhar. E adivinhar errado.
Você perde 20 minutos explicando o óbvio.
✅ Solução: Contexto estruturado
Prompt correto:
Contexto do projeto:
- Stack: Next.js 14, TypeScript, Prisma, PostgreSQL
- Problema: Usuário não consegue fazer login após reset de senha
- Comportamento atual: Loading infinito na tela de login
- Comportamento esperado: Redirecionar para /dashboard
- Já tentei: Resetar cache, limpar cookies, restart do servidor
Logs relevantes:
[Cole stack trace ou erro do console]
Analise a causa raiz e sugira correção.
O que acontece:
Claude analisa com contexto completo:
Identifica problema em segundos
Sugere correção cirúrgica
Explica o porquê do bug
Resultado:
Bug resolvido em 2 minutos (vs 20 minutos adivinhando).
Economia: 90% do tempo de debugging
❌ ERRO 3: Ignorar os Arquivos de Configuração
O que você faz (errado):
Deixa Claude Code sem instruções personalizadas.
Por que não funciona:
Claude gera código no estilo dele. Não no SEU estilo.
Resultado:
Código inconsistente
Revisão manual leva horas
Time reclama do padrão
✅ Solução: Crie .claude/instructions.md
Arquivo de configuração:
# Instruções do Projeto
## Stack
- React 18 + TypeScript Strict
- Tailwind CSS (sem CSS-in-JS)
- Testes com Vitest
- Prisma ORM
## Regras de Código
- Usar composition em vez de classes
- Funções: máximo 20 linhas
- Componentes: máximo 150 linhas
- Comentários: apenas em lógica complexa
- Sempre tipos explícitos (nunca any)
## Estrutura de Pastas
src/
components/ # Componentes reutilizáveis
features/ # Features isoladas
hooks/ # Custom hooks
lib/ # Utilitários
types/ # TypeScript types
## Convenções
- Nomenclatura: camelCase para funções, PascalCase para componentes
- Imports: ordem alfabética, React primeiro
- Props: sempre tipar com interface (não type)
## Restrições
- NÃO usar: CSS-in-JS, Redux, class components
- SEMPRE usar: Zod para validação, React Query para fetching
O que acontece:
Claude lê isso automaticamente.
Agora ele gera código que parece que VOCÊ escreveu.
Exemplo real:
Antes (sem instructions.md):
// Código genérico
function fetchUsers() {
const [data, setData] = useState([]);
useEffect(() => {
fetch('/api/users').then(r => r.json()).then(setData);
}, []);
return data;
}
Depois (com instructions.md):
// Código no seu padrão
import { useQuery } from '@tanstack/react-query';
import { api } from '@/lib/axios';
import type { User } from '@/types';
export const useUsers = () => {
return useQuery<User[], Error>({
queryKey: ['users'],
queryFn: async () => {
const { data } = await api.get<User[]>('/users');
return data;
},
staleTime: 1000 * 60 * 5,
});
};
✅ React Query (padrão do projeto)
✅ Tipos explícitos
✅ Estrutura de imports correta
✅ Cache configurado
Zero ajustes necessários.
Resultado:
Economia: 2h/dia de ajustes de código
❌ ERRO 4: Aceitar a Primeira Resposta
O que você faz (errado):
Claude gera código. Você copia. Pronto.
Por que não funciona:
Código genérico tem:
Bugs ocultos
Edge cases não cobertos
Problemas de performance
Vulnerabilidades de segurança
Você descobre isso em produção.
✅ Solução: Sempre peça revisão crítica
Prompt de revisão:
"Revise o código que você acabou de gerar.
Seja HONESTO. Não me bajule.
Identifique:
1. Bugs potenciais ou edge cases não cobertos
2. Oportunidades de otimização de performance
3. Problemas de segurança (SQL injection, XSS, etc)
4. Código duplicado que pode ser abstraído
5. Testes necessários
Para cada problema, explique o risco e sugira correção."
Exemplo real:
Pedi código de validação de email. Claude gerou:
function validateEmail(email: string) {
return /\S+@\S+\.\S+/.test(email);
}
Pedi revisão crítica. Claude respondeu:
"Este código tem 3 problemas:
Bug: Aceita emails inválidos como
test@ou@example.comEdge case: Não valida tamanho máximo (pode causar DoS)
Segurança: Não sanitiza input (pode ter caracteres maliciosos)
Aqui está a versão corrigida:"
import { z } from 'zod';
const emailSchema = z
.string()
.email('Email inválido')
.max(255, 'Email muito longo')
.toLowerCase()
.trim();
export function validateEmail(email: string): boolean {
try {
emailSchema.parse(email);
return true;
} catch {
return false;
}
}
✅ Validação robusta (Zod)
✅ Limite de tamanho
✅ Sanitização automática
✅ Type-safe
Resultado:
Isso me salvou de 3 bugs críticos em produção só nesta semana.
Economia: Centenas de horas de debugging + reputação preservada
❌ ERRO 5: Não Usar Comandos Customizados
O que você faz (errado):
Repete os mesmos prompts todo dia:
"Revise este código"
"Adicione testes para isso"
"Explique esta função"
Perde 10 minutos por dia copiando prompts.
✅ Solução: Crie slash commands
Crie .claude/commands/review.md:
Revise o código selecionado seguindo este checklist:
## 1. Legibilidade
- Nomes descritivos?
- Lógica clara?
- Comentários necessários?
## 2. Performance
- Operações desnecessárias?
- Loops otimizáveis?
- Memória bem gerenciada?
## 3. Segurança
- SQL injection possível?
- XSS vulnerável?
- Inputs validados?
- Secrets expostos?
## 4. Testabilidade
- Funções puras?
- Dependências injetáveis?
- Mocks possíveis?
## 5. Manutenibilidade
- Responsabilidade única?
- Acoplamento baixo?
- Código duplicado?
Para cada problema encontrado:
- Explique o risco
- Mostre exemplo de correção
- Sugira teste para cobrir
Como usar:
Seleciona código → digita /review → Enter
Claude faz revisão completa automática.
Comandos úteis para criar:
.claude/commands/test.md:
Gere testes completos para o código selecionado.
- Framework: Vitest
- Coverage: 100% das funções
- Inclua: happy path, edge cases, error handling
- Use: mocks para dependências externas
.claude/commands/explain.md:
Explique o código selecionado como se eu tivesse 5 anos.
- Use analogias do mundo real
- Desenhe diagramas ASCII se ajudar
- Identifique as 3 partes mais importantes
- Sugira melhorias se houver
.claude/commands/refactor.md:
Refatore o código selecionado seguindo:
- SOLID principles
- Clean Code practices
- Remover duplicação
- Melhorar nomes
- Extrair funções grandes
Explique cada mudança e o porquê.
Resultado:
Economia: 2h/semana de prompts repetitivos
🚀 Recapitulação: Aplique Hoje
Aqui está seu plano de ação:
Setup inicial (30 minutos)
[ ] Crie
.claude/instructions.mdno seu projeto principal[ ] Adicione stack, regras e estrutura de pastas
[ ] Crie 3 comandos:
/review,/test,/explain[ ] Teste com um arquivo existente
Nova rotina (a partir de amanhã)
Antes de pedir código: Use
/planpara features complexasAo pedir código: Forneça contexto estruturado
Após receber código: Sempre peça revisão crítica
Ao terminar: Use
/reviewpara validação final
Checklist mental:
Antes de cada prompt, pergunte:
[ ] Dei contexto suficiente?
[ ] Pedi revisão crítica?
[ ] Tenho .instructions.md atualizado?
[ ] Existe comando customizado para isso?
💡 Caso de Uso Real
Projeto: Migração de API REST para GraphQL
Antes de aplicar essas técnicas:
Tempo estimado: 2 semanas
Código genérico, precisou 40h de ajustes
12 bugs encontrados em testes
Time frustrado com qualidade
Depois de aplicar:
Usei
/planpara arquitetura (1h)Criei
.instructions.mdcom padrões GraphQL (30 min)Pedi revisão crítica em cada resolver (15 min extras)
Usei
/testpara coverage automático
Resultado:
Tempo real: 1 semana
Código no padrão do time (zero ajustes)
2 bugs encontrados (vs 12)
Time impressionado com qualidade
Economia: 40 horas + reputação melhorada
🔗 Recursos Adicionais
💬 Sua Vez
Agora quero ouvir de você:
Qual desses 5 erros você mais comete?
Responda este email me contando. Leio e respondo TODOS.
Se tiver alguma dúvida sobre como aplicar qualquer uma dessas técnicas, é só perguntar.
Gostou desta edição?
📤 Encaminhe para um colega que precisa disso
🐦 Compartilhe no X marcando @adrianoviana
🚀 Subscreva no canal do youtube
⭐ Responda com feedback (ajuda MUITO!)
Até semana que vem!
Abraço,
Adriano Viana
