Claude Code: o que é, para que serve e os 5 mal-entendidos de quem nunca usou

Fala aí, beleza? Se você chegou aqui pesquisando o que é o Claude Code, provavelmente já ouviu três descrições diferentes e nenhuma delas bate 😅

A mais comum é chamar ele de autocomplete turbinado

A segunda é tratar como um chat que cospe código pra você colar no arquivo

E a terceira é o extremo oposto: um robô que programa sozinho enquanto você dorme

Neste post eu apresento a ferramenta pelo avesso: primeiro o que ela NÃO é, depois o que ela faz de fato dentro do seu projeto

Bora?

Para que serve o Claude Code no dia a dia de um projeto

Definição seca primeiro: Claude Code é uma ferramenta de codificação agêntica (agentic coding tool) da Anthropic, que lê o codebase, edita arquivos, executa comandos e se integra às ferramentas de desenvolvimento

"Agêntica" soa palavra de marketing, né? Então traduz assim: em vez de te entregar um texto pra você aplicar na mão, ele mesmo aplica, dentro do modo de permissão que você deixou ativo

A própria documentação do Claude Code cita tarefas bem pé no chão:

• escrever testes para código que está sem cobertura
• corrigir erros de lint
• resolver conflitos de merge
• atualizar dependências
• gerar release notes

E dá pra pedir um pull request em linguagem natural, no estilo "create a pr for my changes", sem você montar o fluxo passo a passo

O detalhe que muda tudo: ele atua em múltiplos arquivos e ferramentas, entendendo o projeto inteiro, não um arquivinho isolado que você colou na caixa de texto

E como ele aprende o jeito do seu projeto?

Existe um arquivo chamado CLAUDE.md, que fica na raiz do repositório e é lido no início de toda sessão

É ali que entram padrões de código, decisões de arquitetura e bibliotecas preferidas do time

Se você conhece aqueles arquivos de config que todo projeto tem na raiz, a lógica é a mesma: o projeto se apresenta antes do trabalho começar

Claude Code x autocomplete da IDE x chat de código: a diferença na prática

Antes dos mal-entendidos, deixa eu colocar os três lado a lado, porque quase toda confusão nasce de misturar essas categorias

Olhando assim fica óbvio, né? Mas na cabeça de quem nunca usou, os três viram "IA que escreve código" e é aí que a expectativa quebra

Mal-entendido 1: achar que é só um autocomplete mais esperto

Sintoma: a pessoa instala, abre o projeto e fica esperando aparecer sugestão cinza no fim da linha enquanto digita

Causa: a comparação mental com as ferramentas de completar código no editor, que foi o primeiro contato de quase todo mundo com IA na programação

Realidade: ele lê a base de código, edita arquivos e executa comandos, atuando em vários arquivos ao mesmo tempo

Não é uma sugestão de linha, é uma tarefa executada

Como não cair nessa: descreva a TAREFA, não o trecho

Em vez de esperar uma sugestão, você fala o que precisa acontecer no projeto

E se bater aquele frio na barriga de deixar ele sair editando, roda /plan antes: o modo plano libera leitura e exploração e bloqueia edição até você aprovar o plano

Mal-entendido 2: tratar como um chat que devolve trecho solto para você colar

Sintoma: pedir o código, olhar a resposta, selecionar, copiar e colar no arquivo na mão

Aí quando não dá certo, apaga tudo e pede de novo 🙃

Causa: hábito puro de conversa de chat, onde a saída sempre foi texto pra você transportar

Realidade: ele edita os arquivos do projeto e roda comandos direto

E tem rede de segurança: cada prompt que inicia um turno cria um checkpoint, e você pode restaurar a conversa, o código ou os dois para um ponto anterior

Como não cair nessa: aprove as edições dentro do fluxo da ferramenta e, quando o caminho não te agradar, volte por checkpoint em vez de sair desfazendo na unha

É a diferença entre dirigir o carro e empurrar o carro…

Mal-entendido 3: pensar que ele existe só dentro do terminal

Sintoma: o cara olha um print de CLI, pensa "não sou de terminal" e desiste antes de tentar

Causa: a maioria dos vídeos e das capturas de tela mostra a linha de comando, então o terminal virou a cara do produto

Realidade: as superfícies são terminal (CLI), extensões de IDE (VS Code e JetBrains), app desktop e navegador

A ferramenta é a mesma, o lugar onde você fala com ela é que muda

Como não cair nessa: escolha a superfície que combina com o seu fluxo ANTES de decidir que a ferramenta não é pra você

Se você vive dentro da IDE, comece pela IDE e pronto

Mal-entendido 4: acreditar que ele mexe no que quiser sem nenhum limite

Sintoma: medo de apontar um agente pro repositório do trabalho, aquele friozinho de imaginar os rm -rf da vida rodando sozinhos

Causa: a fama generalizada de IA que apaga arquivo e depois pede desculpa

Realidade: existe um modelo de permissões, e ele é o coração da coisa

No modo manual, o Claude para e pede permissão explícita antes de editar arquivo, rodar comando de shell ou acessar a rede

No modo plano, acionado por /plan, ele lê e explora à vontade, escreve o plano e não toca no código-fonte até você aprovar (a barra de status mostra o aviso de plan mode on)

E existe o modo automático, em que ele age sem os prompts de permissão a cada passo, com um classificador checando cada tool call antes de executar, bloqueando ação irreversível, destrutiva ou de exfiltração de dados

Ou seja: quem decide o quanto de corda ele tem é você, escolhendo o modo

Como não cair nessa: comece no modo mais restrito, veja como ele se comporta no SEU projeto e só depois solte a corda

Guardrails (limites) existem pra ser usados, não pra ser pulados no primeiro dia

Mal-entendido 5: confiar no relatório de sucesso e dispensar a revisão humana

Sintoma: ler "pronto, corrigi e está funcionando", dar um sorriso e mandar o commit

Causa: resposta segura e bem escrita em linguagem natural SOA como verificação, mas afirmação não é prova

Realidade: a própria documentação de boas práticas orienta pedir evidência em vez de aceitar a afirmação de sucesso: a saída do teste, o comando que foi rodado e o retorno dele, ou um screenshot do resultado

Como não cair nessa: termine toda tarefa com um "me mostra a evidência"

Se a evidência não fecha, você volta por checkpoint e refaz o caminho, sem drama

Esse aqui é campeão na lista de erros de quem começa no Claude Code, justamente porque parece produtividade e é o contrário

A revisão continua sendo sua, beleza? Ele age, você julga

E o preço? Claude Code não é de graça nem ilimitado

Esse ponto não é bem um mal-entendido de conceito, é de expectativa, mas pega tanta gente que merece seção própria

A confusão: instalar animado e descobrir que não dá pra usar no plano gratuito, porque a cabeça mistura duas coisas diferentes: o chat com a ferramenta de código, e a assinatura com a API

O que vale de fato: o acesso vem pelo plano Claude Pro (US$ 20/mês, preço nos EUA, sem impostos aplicáveis), pelo Max 5x (US$ 100/mês), pelo Max 20x (US$ 200/mês), por um assento premium Team ou Enterprise, ou por uma conta do Claude Console (API)

E atenção nesse ponto: uma assinatura paga do Claude não inclui o uso da API pelo Console, que é cobrado separadamente

Outra coisa que pega muita gente de surpresa: o trabalho no terminal e os chats consomem o mesmo pool de uso

O limite por sessão reseta a cada 5 horas, e os planos Max também têm limite semanal

Como se planejar: na hora de escolher o nível, conte o uso do terminal DENTRO do mesmo plano, não como um extra que aparece do nada

O teste da skill Caveman: o que ele mostra sobre o Claude Code ser um agente

Esse papo de limite compartilhado me levou a testar uma skill chamada Caveman, que promete encurtar a saída do modelo

E o resultado do teste explica melhor o conceito de agente do que qualquer definição bonitinha

No vídeo eu mostro que ela mexe SÓ na saída: o prompt continua exatamente o mesmo, o que muda é a forma como o modelo responde

Instalei as skills direto pelo terminal, sem nem precisar abrir o Claude Code, e na hora de escolher onde instalar comentei que vale deixar disponível de forma global, não só naquele projeto

Escolhi copiar os arquivos para todos os agentes, mas seguir por symlink também funcionaria

Depois troquei o nível de resumo no meio da própria sessão, chamando a skill com o modo que eu queria, sem reiniciar nada

Pra comparar de forma justa, pedi sempre a MESMA explicação (como funciona uma função recursiva em JavaScript) em cada nível

No modo mais leve a explicação continuou compreensível, só um pouco mais sucinta que o normal

No mais agressivo a resposta virou fragmento quase telegráfico, e eu disse na hora: esse nível eu usaria pro modelo programar, não pra pedir explicação

Testei até um modo que responde em chinês: o código continuou legível, mas a explicação ficou incompreensível pra quem não lê chinês haha

E uma coisa foi ficando visível: quanto mais agressivo o resumo, mais rápidas as respostas apareciam

Aí rodei um projeto de verdade com a skill ativa, um app de notas com criação, edição, exclusão, cards na home e dark mode

O projeto foi criado sem erros a partir do prompt inicial, e os comentários do agente rodando em background ficaram curtíssimos, que era o Caveman trabalhando ali na frente

Agora a parte honesta: tentei medir o consumo dentro da própria ferramenta e não consegui fechar a comparação que eu queria, então deixei como dever de casa

E tem o contraponto, que é importante: quanto mais econômico o modo, menos dá pra conversar com o modelo e tirar dúvida

O que isso prova sobre o conceito? Que o Claude Code é um agente que você CONFIGURA, não um chat que você consulta

A mesma instrução, com a configuração diferente, produz um comportamento diferente

E já que o assunto é skill, vale dar uma olhada nas skills que você instalou e nunca usou, porque elas continuam ali influenciando a sessão

No vídeo acima você vê o teste rodando ao vivo, nível por nível, e o app de notas sendo criado com a skill ativa

O que você precisa para começar a usar o Claude Code

Checklist curto, só o verificável:

1. Um acesso pago: plano Claude Pro ou Max, assento premium Team ou Enterprise, ou conta do Claude Console (API). O erro comum aqui é achar que o plano gratuito serve, ou supor que a assinatura cobre a API (não cobre, a cobrança é separada)
2. Sistema compatível: macOS 13.0 ou superior, ou Windows 10 versão 1809 ou superior. No Windows nativo, o Git for Windows é recomendado pro Claude Code usar a ferramenta Bash. O erro comum é pular esse detalhe e estranhar depois
3. Instalação nativa no macOS, Linux ou WSL:

curl -fsSL https://claude.ai/install.sh | bash

4. Instalação nativa no Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

5. Decidir o caminho da instalação com consciência: além do instalador nativo, dá pra instalar por Homebrew, WinGet e gerenciadores de pacote do Linux. O erro comum deste passo é escolher um desses e esquecer que eles exigem atualização manual por padrão, enquanto a instalação nativa se atualiza sozinha em background

Claude Code não é mágica nem autocomplete: é um agente que você conduz

Se eu tivesse que amarrar os cinco mal-entendidos em uma frase só, seria essa: ele lê o projeto, propõe, age dentro do modo de permissão que você escolheu e precisa da sua revisão

Tira qualquer uma dessas quatro partes e a expectativa quebra de novo

Próximo passo concreto, na ordem:

1. instala pelo caminho nativo
2. cria um CLAUDE.md na raiz do repositório com os padrões do projeto, as decisões de arquitetura e as bibliotecas preferidas
3. roda a primeira tarefa em /plan, lê o plano com calma e só depois aprova
4. no fim, pede evidência: a saída do teste, o comando rodado e o retorno

Fez isso? Então você já usou a ferramenta do jeito que ela foi desenhada, e não como um autocomplete frustrado 😀

Depois que o básico estiver rodando, existe uma camada seguinte pra explorar: MCP, pra conectar ferramentas e fontes externas, e subagentes trabalhando em partes diferentes de uma mesma tarefa

Mas isso é papo pra outro post… até o próximo!