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:

  1. Setup inicial (10 min)

  2. Autenticação (15 min)

  3. Layout do dashboard (10 min)

  4. Mock de dados (5 min)

  5. Gráfico 1 (15 min)

  6. Gráfico 2 (15 min)

  7. 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:

  1. Bug: Aceita emails inválidos como test@ ou @example.com

  2. Edge case: Não valida tamanho máximo (pode causar DoS)

  3. 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.md no 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ã)

  1. Antes de pedir código: Use /plan para features complexas

  2. Ao pedir código: Forneça contexto estruturado

  3. Após receber código: Sempre peça revisão crítica

  4. Ao terminar: Use /review para 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:

  1. Usei /plan para arquitetura (1h)

  2. Criei .instructions.md com padrões GraphQL (30 min)

  3. Pedi revisão crítica em cada resolver (15 min extras)

  4. Usei /test para 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

Keep reading