🔨 Claude Code na Prática

O comando claude inicia o Claude Code interativo no diretório atual. Você pode passar arquivos como argumento ou usar flags para modo não-interativo.

Saber iniciar corretamente garante que o CC carregue o contexto certo do projeto e os arquivos CLAUDE.md relevantes desde o primeiro momento.

claude (interativo), claude arquivo.py (com contexto), claude -p "prompt" (non-interactive).

A qualidade das instruções determina a qualidade do resultado. Instruções vagas geram código genérico; instruções específicas geram soluções exatas.

Dominar a arte de dar instruções é o maior diferencial entre usar CC superficialmente e extrair 100% do seu potencial em tarefas complexas.

Especifique linguagem, framework, convenções. Mencione arquivos relevantes. Descreva o comportamento esperado, não apenas o que fazer.

Comandos especiais prefixados com / que controlam o comportamento do Claude Code durante a sessão.

Os slash commands são atalhos de produtividade. /compact salva contexto, /clear reinicia sem sair, /model troca o modelo na hora.

/help (lista tudo), /compact (comprime histórico), /clear (limpa conversa), /config (configurações), /exit (sai), /model (troca modelo).

Por padrão, o CC pede confirmação antes de executar comandos de terminal. Com --dangerously-skip-permissions, todas as ações são executadas sem confirmação.

Para automações e scripts CI/CD, skip-permissions é essencial. Para uso interativo, o modo padrão protege contra erros acidentais.

Modo padrão: pergunta antes. Skip-permissions: executa tudo. Use skip apenas em ambientes controlados ou containers isolados.

Claude Code pode ler, editar e criar arquivos diretamente no seu sistema de arquivos, sem precisar copiar e colar conteúdo manualmente.

Interagir com arquivos via linguagem natural elimina o atrito de abrir editores, selecionar código e colar de volta. O CC faz tudo em um fluxo contínuo.

"Leia o arquivo X", "Edite a função Y em arquivo Z", "Crie um novo arquivo W com conteúdo...". CC confirma antes de salvar no modo padrão.

Claude Code pode executar qualquer comando git: criar commits com mensagens descritivas, mostrar diffs, criar branches e até resolver conflitos de merge.

CC escreve mensagens de commit mais descritivas que a maioria dos devs, porque ele entende o que mudou. Isso melhora o histórico do projeto automaticamente.

"Faça commit com mensagem descritiva", "Mostre o diff", "Crie branch feature/login", "Resolva conflitos em arquivo.py".

Um arquivo Markdown que o Claude Code lê automaticamente ao iniciar. Funciona como instruções permanentes para o projeto: stack, convenções, comandos e regras.

Sem CLAUDE.md você repete o contexto a cada sessão. Com ele, o CC já sabe o que é o projeto antes de você digitar a primeira mensagem.

Carregado automaticamente, persiste entre sessões, pode ser global (~/.claude/CLAUDE.md) ou por projeto (.claude/CLAUDE.md).

Existem dois níveis: global (~/.claude/CLAUDE.md) aplicado em todos os projetos, e local (.claude/CLAUDE.md) específico para o repositório atual.

O global define suas preferências pessoais (tom, idioma, estilo). O local define o projeto: stack, comandos npm/make, estrutura de pastas.

Global: preferências universais. Local: contexto do projeto. Ambos são carregados juntos — o local complementa o global.

O conteúdo ideal inclui: linguagem e versão, frameworks usados, convenções de código, comandos para rodar o projeto e coisas para evitar.

Um CLAUDE.md bem preenchido transforma o CC num dev sênior do time — ele já conhece as regras sem precisar perguntar.

Seções recomendadas: Stack, Convenções, Comandos, Não fazer. Seja direto — CC lê como instruções, não como documentação.

Um CLAUDE.md completo para uma API REST em Python com FastAPI — inclui stack, convenções, comandos make e restrições claras.

Ver um exemplo real é mais valioso que qualquer descrição abstrata. Com este template você pode adaptar para qualquer projeto em minutos.

Estrutura: # Projeto → ## Stack → ## Convenções → ## Comandos → ## Não fazer. Seções curtas, diretas e acionáveis.

Você pode criar CLAUDE.md dentro de subpastas do projeto. Quando o CC trabalha naquela pasta, carrega o contexto específico daquele módulo.

Em projetos grandes com frontend/backend/infra separados, sub-CLAUDE.md permite instruções específicas por camada sem poluir o contexto global.

Hierarquia: global → projeto → subpasta. Cada nível adiciona contexto ao anterior. Ideal para monorepos e projetos multi-stack.

CLAUDE.md consome espaço da janela de contexto a cada sessão. Um arquivo muito longo desperdiça tokens em informações que raramente são usadas.

Manter CLAUDE.md abaixo de ~2000 tokens (≈1500 palavras) equilibra contexto rico com eficiência — sobra mais espaço para o código real.

Regra: se você não usa uma informação toda semana, não coloque. Prefira sub-CLAUDE.md por módulo a um arquivo enorme no root.

O fluxo completo de criar um script do zero: descrever requisitos, revisar o código gerado, iterar com ajustes e validar o resultado final.

Criar scripts é uma das tarefas mais frequentes. Dominar o fluxo correto — com prompt estruturado e iteração — reduz o tempo de 1h para 10 minutos.

Descreva inputs/outputs esperados, peça testes junto, revise antes de executar. Itere com "altere X para Y" em vez de reescrever o prompt.

O processo de pedir ao CC para analisar código existente, identificar problemas e propor/executar refatorações com explicação de cada mudança.

Refatoração mal planejada quebra funcionalidades. Pedir análise antes garante que o CC entenda as dependências antes de fazer mudanças.

Fluxo: "Analise este arquivo" → revisar análise → "Refatore conforme discutido" → validar. Nunca pule a etapa de análise.

O fluxo de resolver bugs usando CC: colar o erro completo, fornecer o trecho de código relevante e iterar até a solução funcionar.

CC é excelente em debugging porque reconhece padrões de erro de todas as linguagens. Fornecer contexto adequado aumenta a taxa de acerto na primeira tentativa.

Inclua: mensagem de erro completa, stack trace, trecho de código, o que você já tentou. Quanto mais contexto, mais rápida a solução.

Pedir ao CC para gerar testes unitários para código existente: ele analisa as funções, identifica casos de teste relevantes e escreve o arquivo de testes completo.

Gerar testes manualmente é tedioso. CC faz em segundos e muitas vezes inclui edge cases que o dev não pensaria. Resultado: cobertura maior com menos esforço.

"Gere testes pytest para todas as funções públicas de utils.py". Peça casos felizes, edge cases e cenários de erro separadamente para mais cobertura.

CC pode adicionar docstrings a todas as funções, gerar README completo do projeto e adicionar comentários explicativos em código complexo.

Documentação é sempre a última prioridade — e a primeira a ser cobrada. Com CC, documentar um projeto inteiro leva minutos, não horas.

Especifique o formato: Google Style, NumPy, etc. Peça README com seções: Instalação, Uso, Contribuição. CC segue o padrão do CLAUDE.md.

CC pode trabalhar com vários arquivos ao mesmo tempo: renomear uma função em 5 arquivos, ajustar imports, mover código entre módulos mantendo consistência.

Refatorações que cruzam arquivos são as mais propensas a erros humanos. CC rastreia todas as referências e faz as mudanças de forma consistente.

Use /add-dir para adicionar diretórios ao contexto. Peça para CC listar os arquivos afetados antes de executar mudanças em múltiplos arquivos.

A janela de contexto é a quantidade máxima de tokens (texto) que o modelo processa por vez. Inclui todo o histórico da conversa + arquivos abertos + resposta gerada.

Quando a janela enche, o modelo começa a "esquecer" partes da conversa. Entender os limites permite planejar sessões de trabalho eficientes.

Claude Sonnet 4.6: ~200K tokens de contexto. Cada mensagem + resposta consome espaço. CLAUDE.md é carregado a cada sessão e consome contexto.

Quando o contexto se aproxima do limite, o CC começa a "esquecer" conversas antigas — ele não as vê mais. Isso causa respostas inconsistentes com decisões tomadas antes.

Reconhecer os sinais cedo evita desperdício de tempo — você percebe que o CC "esqueceu" algo importante e age antes de ir longe demais no caminho errado.

Sinais: CC contradiz decisões anteriores, "recria" variáveis já definidas, pergunta coisas já respondidas. Hora de usar /compact ou nova sessão.

O comando /compact pede ao CC para criar um resumo compacto do histórico da conversa, substituindo as mensagens longas por um sumário eficiente.

/compact libera contexto mantendo as decisões e descobertas importantes. Permite continuar sessões longas sem perder o fio da meada.

Use proativamente — não espere o contexto encher. Idealmente a cada 10-15 mensagens em sessões de trabalho intenso.

Configuração no settings.json que define quando o CC deve compactar automaticamente o contexto — o número representa o percentual de uso da janela.

Com autoCompact em 75, o CC compacta sozinho quando o contexto chega a 75% — você nunca mais precisará lembrar de fazer /compact manualmente.

Valor recomendado: 75 (equilibra antecipação e espaço). Valores baixos (50) compactam cedo demais; altos (90) deixam o contexto quase cheio.

CLAUDE.md é carregado no início de cada sessão, funcionando como âncora de contexto. Mesmo após /compact, as informações do CLAUDE.md permanecem disponíveis.

Usar CLAUDE.md como repositório das decisões críticas do projeto garante que essas informações sobrevivam a compactações e reinícios de sessão.

Após decisões importantes, atualize o CLAUDE.md: "Adicione ao CLAUDE.md que decidimos usar PostgreSQL em vez de SQLite". Isso persiste para sempre.

Para projetos grandes, a estratégia de dividir o trabalho em sessões por feature/componente é mais eficiente do que tentar fazer tudo em uma sessão única.

Sessões focadas têm melhor qualidade que sessões longas com contexto degradado. Uma nova sessão começa com o CLAUDE.md completo e contexto limpo.

Estratégia: 1 sessão por feature. Antes de encerrar, atualize o CLAUDE.md com decisões tomadas. Nova sessão: contexto limpo, memória persistida no CLAUDE.md.