Claude Code: O Guia Completo
Do zero à geração de dashboards com IA. Com hacks, atalhos e a seção de dados que ninguém escreveu ainda.
O Claude Code é a ferramenta de codificação da Anthropic que roda no terminal do seu computador. Diferente do Claude no chat (que você já conhece), ele não espera você colar trechos de código. Ele lê seu projeto inteiro, edita arquivos, roda comandos, e entrega resultados prontos. Funciona como um par de programação que nunca cansa, nunca esquece o contexto, e trabalha enquanto você faz outra coisa.
Essa edição faz algo que não encontrei em nenhum guia em português: cobre o Claude Code do zero absoluto (para quem nunca abriu um terminal) até usos avançados para profissionais de dados (dashboards, SQL, dbt, pipelines). Com hacks, atalhos e limitações reais.
PARTE 1: O BÁSICO (para quem nunca abriu o terminal)
O que é o Claude Code (e como difere do Claude no chat)
Quando você usa o Claude pelo site ou pelo app, está conversando com ele numa janela. Você cola um trecho de código, ele responde. Você cola outro, ele responde. Se quiser que ele edite um arquivo, precisa copiar o conteúdo, colar no chat, pedir a edição, copiar de volta, colar no arquivo. É manual.
O Claude Code elimina esse ping-pong. Ele vive dentro do terminal do seu computador, no mesmo lugar onde seus arquivos estão. Quando você pede “corrija o bug no arquivo app.py”, ele abre o arquivo, lê, edita e salva. Quando você pede “rode os testes”, ele roda. Quando você pede “crie um dashboard com esses dados”, ele cria os arquivos, instala as dependências e te diz como abrir.
A diferença prática: no chat, o Claude vê o que você mostra. No Claude Code, ele vê o projeto inteiro.
Como instalar (3 minutos)
Você não precisa ser desenvolvedor. Precisa de um computador com macOS, Linux ou Windows 11.
No Mac ou Linux, abra o Terminal e cole:
curl -fsSL https://claude.ai/install.sh | bashNo Windows, abra o PowerShell e cole:
irm https://claude.ai/install.ps1 | iexDepois, navegue até a pasta do seu projeto (ou qualquer pasta) e digite:
claudeNa primeira vez, ele abre o navegador para login. Use sua conta do Claude (a mesma do site). Pronto.
Se você já é desenvolvedor e prefere npm: npm install -g @anthropic-ai/claude-code (requer Node.js 18+).
Se estiver o Claude desktop instalado, já estará na guia Code
Quanto custa
O Claude Code vem junto com a assinatura do Claude. Não é um produto separado.
O plano Pro ($20/mês) inclui o Claude Code com o modelo Sonnet 4.6 como padrão e acesso ao Opus 4.7. É o ponto de entrada para a maioria das pessoas.
O plano Max ($100/mês ou $200/mês) multiplica a capacidade por 5x ou 20x. Para quem usa o Claude Code mais de 4 horas por dia, o Pro esgota rápido.
O plano gratuito do Claude não inclui o Claude Code.
Uma pegadinha comum: se você tem uma API key configurada no seu computador, o Claude Code vai usá-la e cobrar por token em vez de usar sua assinatura. Remova a variável ANTHROPIC_API_KEY antes de usar.
Os 5 comandos que você precisa saber
Você não precisa decorar 60 comandos. Comece com 5:
claude — Abre o Claude Code na pasta atual. Tudo começa aqui.
/init — Analisa o projeto e cria um arquivo CLAUDE.md com instruções para o Claude seguir. Rode uma vez por projeto.
/clear — Limpa o contexto da conversa. Use entre tarefas diferentes para evitar que resíduos da tarefa anterior contaminem a próxima.
/compact — Resume o histórico para liberar espaço. Use a cada 30 minutos em sessões longas.
Ctrl+C — Cancela o que o Claude está fazendo. O botão de emergência.
Só isso. O resto você aprende conforme precisa.
PARTE 2: COMO FUNCIONA NO DIA A DIA
Três modos de trabalho
O Claude Code tem três modos. Você alterna entre eles com Shift+Tab:
Default — O Claude pede sua aprovação antes de cada ação. Editou um arquivo? Pede OK. Quer rodar um comando? Pede OK. Seguro, mas lento.
Plan — O Claude lê tudo, analisa, e te entrega um plano detalhado. Não mexe em nada até você aprovar. Use sempre antes de mudanças grandes. É o modo “pense antes de agir”.
Auto — O Claude toma decisões sozinho. Um classificador de IA analisa cada ação e bloqueia apenas as arriscadas (apagar arquivos importantes, mexer em infra compartilhada). Libera o resto sem perguntar. É o modo “faça e me mostra depois”. Disponível em todos os planos pagos desde abril de 2026.
Recomendação: comece no Default. Quando entender o que ele faz e confiar no fluxo, mude para Auto em tarefas que você já domina. Use Plan sempre antes de refatorações que tocam 3+ arquivos.
O arquivo CLAUDE.md (o segredo que pouca gente configura)
Quando você roda /init, o Claude cria um arquivo chamado CLAUDE.md na raiz do projeto. Esse arquivo é lido automaticamente no início de cada sessão. É onde você ensina ao Claude como seu projeto funciona.
Um CLAUDE.md bem escrito transforma a qualidade das respostas. Um mal escrito (ou vazio) gera retrabalho constante.
Estrutura que funciona (mantenha em menos de 150 linhas):
# Nome do Projeto
Descrição em uma frase do que o projeto faz.
## Comandos
- `make dev`: inicia ambiente local
- `dbt build`: compila e testa modelos
- `streamlit run app/main.py`: abre o dashboard
## Estrutura de pastas
- models/staging/ — modelos de staging
- models/marts/ — fatos e dimensões
- app/ — interface Streamlit
## Convenções
- snake_case sempre
- SQL em lowercase
- Staging: stg_[fonte]__[entidade]s.sql
## Regras
- NUNCA commitar .env
- Sempre rodar testes antes de commitQuando o Claude errar um padrão, peça para ele atualizar o próprio CLAUDE.md com a correção. O arquivo vira um documento vivo que melhora a cada sessão.
Passando contexto: o truque do @
Em vez de descrever onde está um arquivo, use @:
@models/staging/stg_orders.sql como otimizar esse modelo?O Claude carrega o conteúdo do arquivo direto no contexto. Funciona com arquivos, pastas e URLs. Economiza tokens porque ele não precisa buscar o arquivo sozinho.
Sessões paralelas e background agents
Desde abril de 2026, o Claude Code roda múltiplas tarefas ao mesmo tempo.
Ctrl+B joga a tarefa atual para background. Você continua conversando no prompt principal enquanto ela roda.
Ctrl+T mostra a lista de tarefas em execução.
Na prática: você pede para o Claude refatorar um módulo (Ctrl+B), enquanto isso pede para ele escrever testes para outro. Dois agentes trabalhando em paralelo, cada um no seu próprio branch isolado (via worktrees do Git).
Worktrees resolvem o problema de dois agentes editarem o mesmo arquivo. Cada sessão paralela ganha seu próprio checkout. Rode com claude --worktree nome-da-feature.
PARTE 3: RECURSOS AVANÇADOS
/ultrareview — code review por frota de agentes
O /ultrareview é o recurso mais ambicioso do Claude Code em 2026. Quando você roda, ele sobe seu diff para uma sandbox na nuvem da Anthropic e dispara 5 a 20 agentes revisores em paralelo. Cada agente procura um tipo de problema. Quando um agente encontra um bug, outro agente tenta reproduzir antes de reportar.
O resultado: você só vê bugs reais, verificados. Não sugestões de estilo.
Diferente do /review (que é local, rápido e pega o óbvio), o /ultrareview pega falhas de lógica, race conditions, problemas de segurança, e edge cases que um lint jamais encontraria.
Custo: 3 rodadas grátis para experimentar. Depois, $5 a $20 por rodada dependendo do tamanho do diff. Tempo: 5 a 20 minutos rodando em background.
Para profissionais de dados: rode antes de mergear mudanças em queries complexas, migrations, ou scripts de ETL que tocam produção. O custo de um bug em produção é muito maior que $20.
Routines — cron jobs com IA
Uma Routine é uma automação salva: prompt + repositório + conectores. Roda na infraestrutura da Anthropic, mesmo com seu laptop fechado. Três tipos de gatilho:
Agendada — horária, diária ou semanal. “Toda segunda às 8h, analise os alertas do fim de semana e classifique por severidade.”
Via API — endpoint HTTP com bearer token. Integra com qualquer sistema que dispara webhooks.
Via GitHub — dispara quando um PR é aberto, um push acontece, ou uma release é criada.
Limites por plano: 5/dia no Pro, 15/dia no Max, 25/dia no Team/Enterprise.
Caso de uso para dados: “Toda sexta às 18h, conecte no Postgres, calcule as métricas semanais, gere um relatório em PDF, e poste no canal do Slack.”
Níveis de esforço
O Claude Code tem 5 níveis de esforço que controlam o quanto o modelo “pensa” antes de responder:
low — respostas rápidas, formatação, lookups simples. Gasta poucos tokens.
medium — tarefas médias, pequenos refactors.
high — análise complexa, debugging. Era o padrão até março 2026.
xhigh — o padrão atual no Opus 4.7. Coding agêntico, refactors multi-arquivo, debugging ambíguo.
max — problemas extremamente difíceis. Consome muitos tokens. Use com parcimônia.
Hack: o Opus 4.7 no nível low entrega qualidade equivalente ao 4.6 no medium. Se está gastando tokens rápido demais, baixe o esforço com /effort em vez de trocar de modelo.
MCP — conectando o Claude Code ao seu banco de dados
MCP (Model Context Protocol) é o protocolo que conecta o Claude Code a fontes externas: Postgres, Snowflake, BigQuery, Jira, Slack, APIs de dados.
Em vez de exportar um CSV, copiar para a pasta e carregar manualmente, você conecta o banco direto:
claude mcp add postgres-prod --transport http https://seu-servidor-mcp.comAgora o Claude Code consulta seu banco ao vivo. “Quais são as 10 tabelas mais acessadas essa semana?” — ele roda a query no banco e te responde.
Para profissionais de dados, os MCPs mais úteis: Postgres, Snowflake, dbt Power User (integrado ao VS Code), e OpenMetadata (lineage e impact analysis).
Hooks — automação a cada ação
Hooks são comandos que disparam automaticamente quando o Claude faz algo. Configurados no arquivo .claude/settings.json.
Exemplo prático: toda vez que o Claude edita um arquivo .sql, rodar sqlfluff para verificar formatação automaticamente. Toda vez que ele faz commit, rodar os testes. Toda vez que ele cria um arquivo Python, rodar black para formatar.
Para profissionais de dados: configure um hook que rode dbt build --select no modelo que acabou de ser editado. Você pede uma mudança, o Claude edita, o hook compila e testa automaticamente.
PARTE 4: CLAUDE CODE PARA PROFISSIONAIS DE DADOS
Tudo acima serve para qualquer profissional. Essa seção é específica para quem trabalha com dados.
Gerando dashboards do zero
Esse é o caso de uso mais impressionante para não-desenvolvedores. Você tem um CSV e quer um dashboard interativo. O fluxo:
Crie uma pasta vazia. Abra o terminal nela. Rode
claude.Prompt:
Crie um dashboard Streamlit em app.py.
Carregue os dados de @dados/vendas.csv com pandas (use @st.cache_data).
Adicione: sidebar com filtros de região e produto,
três KPI cards no topo (receita total, ticket médio, volume),
gráfico de linha de receita por mês (Plotly),
tabela interativa com busca.
Crie requirements.txt e instruções de como rodar.O Claude cria todos os arquivos, instala as dependências, e te diz para rodar
streamlit run app.py.Abra o navegador em localhost:8501. Seu dashboard está lá.
Itere: “adicione um gráfico de barras por categoria” ou “mude as cores para o padrão da empresa: azul #1A56DB e cinza #64748B”. O Claude edita e você recarrega a página.
Para dados vindos de banco (não CSV): conecte via MCP e peça “crie o dashboard a partir da tabela revenue_daily do Postgres”. Ele faz a query e monta tudo.
SQL: geração, otimização e explicação
Conecte o Claude Code ao seu banco via MCP. Depois:
Gerar: “Escreva uma query que retorne receita mensal por região, com comparação MoM e YoY, filtrando apenas clientes ativos.”
Otimizar: “@queries/relatorio_mensal.sql Analise o plano de execução e sugira otimizações. Explique cada mudança.”
Explicar: “Explique essa query para alguém de negócio que não sabe SQL. Foque no que ela calcula, não em como.”
Com as Altimate Skills (open source, instaláveis na pasta .claude/skills/), a otimização de SQL ficou 22% mais rápida em benchmarks. O Claude aprende padrões do seu banco e sugere índices, reescreve subqueries, e identifica full table scans.
dbt: modelos, testes e documentação
O Claude Code funciona bem com projetos dbt. O que ele faz:
Criar modelos: “Crie um modelo staging para a fonte orders do schema raw. Siga a convenção stg_[fonte]__[entidade]s.sql. Adicione testes de not_null e unique na primary key. Gere a documentação no schema.yml.”
Refatorar: “Mova a lógica de negócio do modelo de staging para um modelo intermediário. Staging deve fazer apenas cast, rename e filter de deleted.”
Documentar: “Gere a documentação do schema.yml para todos os modelos da pasta marts/ que ainda não têm descrição.”
Um detalhe que importa: o Claude Code lê o projeto dbt inteiro, incluindo macros, sources e seeds. Ele entende o grafo de dependências. Quando você pede uma mudança num modelo, ele verifica o impacto nos modelos downstream.
Com as dbt Agent Skills (open source, da Altimate), a acurácia em tarefas reais subiu para 53% no benchmark ADE-bench. Não é perfeito — um engenheiro precisa revisar SCD types, materializations e incremental logic. Mas o primeiro rascunho economiza horas.
Scripts de ETL e debug de pipelines
Prompt para um pipeline completo:
Crie um script Python que:
1) Conecte no Postgres (credenciais em .env)
2) Extraia dados da tabela raw_events dos últimos 7 dias
3) Transforme: parse do JSON, normalização de nomes, deduplicação
4) Carregue na tabela clean_events
5) Registre logs em arquivo e envie resumo por Slack webhook
Estruture em funções separadas. Adicione tratamento de erro e retry.Para debug: “O pipeline de ingestão falhou com esse erro: [cole o log]. Analise a causa raiz e proponha um fix.”
O Claude Code lê o log, identifica a causa (timeout, schema change, permissão), e propõe a correção com o código editado. Para profissionais de dados que lidam com falhas de pipeline diariamente, isso encurta o tempo de diagnóstico de horas para minutos.
Data quality automatizada
Configure um hook que rode verificações de qualidade toda vez que o Claude editar um arquivo SQL ou Python:
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": "if echo '$FILE' | grep -q '.sql$'; then sqlfluff lint $FILE; fi"
}]
}]
}
}Vá além: peça ao Claude para gerar testes Great Expectations ou Soda automaticamente a partir do schema e de uma amostra dos dados. “Analise a tabela orders e gere testes de qualidade: range válido para revenue, completude de campos obrigatórios, unicidade de order_id, e integridade referencial com a tabela customers.”
PARTE 5: HACKS E ATALHOS
Os atalhos que economizam tempo
Shift+Tab — Cicla entre Default, Plan e Auto. Use direto em vez de digitar /plan.
Esc, Esc — Volta no tempo (conversa e código). O “Ctrl+Z” do Claude Code.
Ctrl+B — Manda tarefa para background. Continue trabalhando enquanto ela roda.
Ctrl+T — Lista de tarefas em execução.
Alt+T — Liga/desliga Extended Thinking (o Claude mostra o raciocínio).
Alt+P — Troca de modelo rápido (Opus/Sonnet/Haiku).
# no início — Salva na auto-memória sem editar CLAUDE.md. Ex: “# sempre usar pytest, nunca unittest”.
7 hacks que mudam o fluxo
1. Sempre peça um plano primeiro. Antes de codificar, peça: “Liste os passos, arquivos afetados e riscos. Aguarde minha aprovação.” Evita 80% dos retrabalhos.
2. /clear entre tarefas. O erro mais comum é acumular contexto de tarefas anteriores. Limpe antes de começar algo novo.
3. /compact a cada 30 minutos. Em sessões longas, o contexto enche e a qualidade cai. O /compact resume sem perder informação.
4. Use Sonnet para trabalho rotineiro, Opus para arquitetura. O alias “opusplan” faz isso automaticamente: planeja com Opus (mais inteligente), executa com Sonnet (mais barato). Economiza tokens sem perder qualidade.
5. Não micromanage bugs. Cole o erro e diga “fix”. O Claude resolve a maioria sem instrução granular. Se não resolver, aí sim dê contexto adicional.
6. Peça para o Claude atualizar o CLAUDE.md. Quando ele errar um padrão, não corrija manualmente — peça “atualize o CLAUDE.md para evitar esse erro no futuro”. O documento melhora a cada sessão.
7. Use @arquivo em vez de deixar o Claude buscar. Quando você sabe qual arquivo é relevante, aponte com @. Economiza tokens de busca e é mais preciso.
Os 3 erros que todo mundo comete
Rodar o Claude Code na pasta Home. Ele indexa tudo. São milhares de arquivos irrelevantes consumindo contexto. Sempre navegue até a pasta do projeto antes de rodar.
CLAUDE.md vago demais. “Formate o código direitinho” não ajuda. “Use black para Python, sqlfluff para SQL, e conventional commits para mensagens de commit” ajuda.
Deixar a ANTHROPIC_API_KEY no ambiente. Se você está pagando a assinatura Pro/Max, a API key faz o Claude Code cobrar por token em vez de usar o plano. Rode unset ANTHROPIC_API_KEY antes de usar.
PARTE 6: QUANDO USAR O QUÊ
Claude Code vs Claude no chat: Use o chat para perguntas rápidas sem repositório. Use o Claude Code para tudo que envolve editar arquivos, rodar comandos ou trabalhar num projeto.
Claude Code vs Cursor: Cursor é melhor para edição inline diária com autocomplete. Claude Code é melhor para refatorações multi-arquivo, tarefas autônomas longas, e automações em background. O padrão entre desenvolvedores em 2026: usar os dois.
Claude Code vs GitHub Copilot: Copilot é mais barato ($10/mês) e o autocomplete é excelente. Claude Code é mais autônomo e trabalha com projetos inteiros. Copilot para código novo inline. Claude Code para mudanças grandes e arquiteturais.
Para profissionais de dados que não programam diariamente: Claude Code sozinho resolve. Você não precisa de Cursor ou Copilot se seu trabalho principal não é escrever código, mas sim resolver problemas com dados e entregar resultados.
O que o Claude Code não faz
Não substitui um engenheiro. Ele acelera. Ele gera primeiros rascunhos. Ele debuga. Mas decisões de arquitetura, modelagem de dados e lógica de negócio continuam precisando de alguém que entenda o domínio.
O tokenizer novo do Opus 4.7 consome mais. O mesmo input pode gastar até 35% mais tokens que no modelo anterior. Se você está no plano Pro e seus limites esgotam rápido, esse é o motivo. Considere o Max ou reduza o nível de esforço.
O modelo segue instruções de forma mais literal. Prompts vagos que funcionavam antes podem dar resultados piores. Seja específico: em vez de “melhore esse código”, diga “refatore essa função para usar list comprehension em vez de for loop, mantenha os nomes das variáveis”.
/ultrareview e Routines são research preview. Funcionam, mas podem mudar de comportamento, preço ou serem descontinuados. Não construa processos críticos que dependam exclusivamente deles.
Dados sensíveis passam pelos servidores da Anthropic. Para ambientes regulados (saúde, financeiro, governo), use o plano Enterprise com HIPAA e audit logs. Nunca cole credenciais em prompts.
Ponto de partida: instale o Claude Code, navegue até um projeto existente, rode /init, e faça uma pergunta sobre o código. “Explique o que esse projeto faz” já é um ótimo começo. Se não tem projeto, crie uma pasta, jogue um CSV dentro e peça um dashboard Streamlit. Cinco minutos. Sem risco.
Obrigada pela conteudo.Foi de extrema valia.Grata!!