Claude Code: o que é e como começar a usar

Um desenvolvedor abre o terminal numa pasta que nunca viu, digita claude e pede: "explique como este projeto sobe em produção". Alguns minutos depois chega uma resposta que cita os arquivos certos. Esse é o primeiro contato típico com o Claude Code, e ele costuma impressionar.

O segundo contato tende a ser outro. A mesma pessoa pede uma mudança pequena. O agente edita quatro arquivos, tenta rodar um script de teste que não existe e anuncia que terminou.

Nada quebrou de forma visível, e nada foi conferido. A diferença entre as duas sessões está no que o repositório informa ao agente.

O Claude Code rende quando o repositório explica a si mesmo: um CLAUDE.md curto, testes que rodam e comandos de build escritos em algum lugar. Sem isso, o agente adivinha, e adivinha com confiança.

O que é o Claude Code e onde ele roda

A documentação oficial descreve a ferramenta como um agente de programação que lê a base de código, edita arquivos, roda comandos e se conecta às ferramentas de desenvolvimento. Você descreve a tarefa em texto, e ele trabalha dentro do projeto com acesso ao que está no disco.

No chat comum, você cola um trecho de código e recebe outro de volta. Aqui, o agente procura os arquivos sozinho, decide o que ler, propõe um plano e executa. Por isso o modo de trabalho muda em relação ao vibe coding, em que a pessoa aceita o resultado sem olhar o código. Com um agente que mexe no disco, revisar o diff faz parte da tarefa.

Hoje ele aparece em cinco lugares. O terminal tem a versão mais completa. Há uma extensão para VS Code, que também instala no Cursor, e um plugin para IDEs JetBrains, que depende do programa de linha de comando instalado à parte. O app desktop roda em macOS e Windows, tem versão beta para Ubuntu e Debian e exige assinatura paga. A versão web fica em claude.ai/code e dispensa instalação.

Todas usam o mesmo motor, então o CLAUDE.md e as configurações do repositório valem em qualquer uma.

Como instalar e abrir a primeira sessão

A documentação recomenda o instalador nativo. No macOS, no Linux e no WSL, o comando é este:

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

No Windows, pelo PowerShell:

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

Também existem pacotes no Homebrew (brew install --cask claude-code) e no WinGet (winget install Anthropic.ClaudeCode). A instalação nativa se atualiza sozinha em segundo plano; as do Homebrew e do WinGet, não. O pacote npm segue disponível e pede Node.js 22 ou mais recente.

Os requisitos de sistema são modestos: macOS 13 ou superior, Windows 10 1809 ou superior, Ubuntu 20.04, Debian 10 ou Alpine 3.19 em diante, 4 GB de RAM e conexão com a internet.

Depois de instalar o Claude Code, abra um terminal novo e confira com claude --version. Para começar, entre na pasta do projeto e digite claude. No primeiro uso, o programa pede login pelo navegador.

Para usar, o Claude Code exige conta Pro, Max, Team, Enterprise ou do Console. O plano gratuito do claude.ai não dá acesso. Empresas também podem usá-lo pela Amazon Bedrock, pela plataforma de agentes do Google Cloud ou pelo Microsoft Foundry.

CLAUDE.md: a memória que você escreve

Cada sessão começa com a janela de contexto vazia. O agente não lembra da conversa de ontem nem do comando de teste que você explicou na semana passada. O CLAUDE.md resolve isso. É um arquivo Markdown na raiz do projeto que o agente lê no início de toda sessão.

O jeito mais rápido de criar o primeiro é rodar /init dentro da sessão. O agente analisa o código e gera um arquivo com comandos de build, instruções de teste e convenções que encontrou. Se o arquivo já existe, ele sugere melhorias em vez de sobrescrever. Quando o repositório já tem um AGENTS.md para outros agentes, a ferramenta consegue ler esse arquivo no lugar do CLAUDE.md.

A documentação sobre memória orienta o conteúdo. Entram os comandos que o agente não adivinha, as regras de estilo que fogem do padrão, o jeito de rodar os testes e as decisões de arquitetura. Ficam de fora a descrição arquivo por arquivo, o tutorial longo e a informação que muda toda semana. A meta é ficar abaixo de 200 linhas por arquivo, porque arquivo longo consome contexto e reduz a aderência às regras.

O CLAUDE.md é contexto, e o agente pode deixar de seguir uma regra. Para algo que precisa acontecer sempre, como rodar o lint antes de cada commit, a documentação indica os hooks. Eles executam comandos em momentos fixos do fluxo, independentemente do que o modelo decidir.

O guia de boas práticas da Anthropic afirma que o agente para quando o trabalho parece pronto. Sem uma verificação que ele consiga rodar, "parecer pronto" é o único sinal disponível. Um teste, um build ou um script que compara saídas fecha esse ciclo sem depender de você.

Modos de permissão: quem aprova o quê

O agente pede autorização antes de agir, e quanto ele pede depende do modo de permissão. No terminal, você troca de modo com Shift+Tab. A página de modos de permissão lista seis:

• default (Manual): só leitura roda sem pedir; edição e comando passam por você.
• acceptEdits: edições de arquivo e comandos comuns de pasta, como mkdir e mv, passam direto.
• plan: o agente lê e propõe um plano, sem editar nada até você aprovar.
• auto: um segundo modelo, o classificador, revisa as ações no seu lugar e bloqueia o que parece arriscado.
• dontAsk: roda só o que foi pré-aprovado e nega o resto. Serve para CI e scripts.
• bypassPermissions: tudo roda sem pergunta, e a documentação restringe o uso a contêineres e máquinas virtuais isoladas.

A partir da versão 2.1.283, o modo auto é o ponto de partida das sessões interativas no terminal e no VS Code. Quem prefere aprovar cada passo precisa escolher o Manual.

Para um repositório desconhecido, o modo plan é o mais didático. Você vê o que o agente entendeu antes que ele toque em qualquer arquivo. Regras por ferramenta somam-se ao modo, e uma regra de negação vale em todos eles, inclusive no bypassPermissions.

Subagentes, skills e MCP sem mistério

Três recursos aparecem em quase todo tutorial e confundem quem está chegando.

Subagentes são assistentes que rodam com contexto e ferramentas próprios. O agente principal delega uma investigação, o subagente lê dezenas de arquivos e devolve só o resumo. A conversa principal fica limpa para a implementação. O critério para separar tarefas está em subagentes: quando vale dividir o trabalho.

Skills são pastas com um arquivo SKILL.md que ensinam um procedimento, como revisar um pull request ou publicar em homologação. Elas carregam sob demanda, enquanto o CLAUDE.md entra em toda sessão. Por isso a documentação sugere mover para skills as instruções que só valem em parte do trabalho. O conceito geral está em Agent Skills.

MCP é o protocolo aberto que liga o agente a fontes externas, como um documento no Google Drive, um ticket no Jira ou uma conversa no Slack. Cada servidor instalado entra com credencial real, então trate a instalação como dependência de software. O básico do padrão está em o que é MCP.

Quanto custa usar o Claude Code

A cobrança segue dois caminhos. Quem usa assinatura Pro, Max, Team ou Enterprise consome do limite do plano, e os preços ficam em claude.com/pricing. Quem entra com conta do Console ou por provedor de nuvem paga por token consumido.

A página de custos traz uma referência para empresas. Em implantações corporativas, o custo médio fica em torno de US$ 13 por desenvolvedor por dia ativo e entre US$ 150 e US$ 250 por mês. Para 90% dos usuários, o gasto fica abaixo de US$ 30 por dia ativo. A própria documentação recomenda começar com um grupo piloto pequeno antes de abrir para todos.

Nos planos Team e Enterprise, o uso de cada pessoa sai de uma cota por assento. Ela se renova numa janela de cinco horas e numa janela semanal, e é compartilhada com o chat e o Cowork.

O que mais pesa é o contexto, porque cada pedido carrega a conversa inteira. Quando o gasto sai do esperado, a documentação aponta duas causas usuais: sessões longas que nunca foram limpas e o Opus deixado como modelo padrão para tudo.

Onde aprender e o roteiro da primeira sessão

A documentação oficial é o ponto de partida, e o guia de boas práticas merece leitura antes da primeira semana. Para quem prefere aula, a Claude Academy oferece cursos gratuitos e no próprio ritmo, entre eles o Claude Code 101 e o Claude Code in Action. O primeiro tem 12 lições e vai do primeiro prompt ao CLAUDE.md, subagentes, skills e hooks. A comparação entre os cursos do catálogo está em cursos gratuitos de IA da Anthropic.

Para a primeira sessão, este roteiro funciona:

1. Escolha um repositório que você conhece. Assim você percebe quando o agente erra.
2. Rode /init e leia o CLAUDE.md gerado. Corrija o que estiver errado e acrescente o comando de teste, se ele não apareceu.
3. Entre no modo plan e faça perguntas. Como o projeto sobe, onde fica a autenticação, o que roda no build. Compare as respostas com o que você sabe.
4. Peça uma mudança pequena com critério de aceite. Por exemplo: "adicione validação de e-mail no cadastro, escreva o teste e rode a suíte". O teste permite ao agente saber se acertou.
5. Leia o diff antes de aceitar. Se algo saiu do escopo, peça para desfazer. Esc duas vezes ou /rewind voltam a um ponto anterior.
6. Faça o commit você mesmo na primeira semana. Depois, se fizer sentido, deixe o agente escrever a mensagem.
7. Rode /clear antes da próxima tarefa. Contexto de outra tarefa atrapalha e encarece cada mensagem.

O guia de boas práticas descreve um erro recorrente: o agente entrega uma implementação plausível que não trata os casos de borda. A correção indicada é sempre fornecer uma verificação, seja teste, script ou captura de tela. A regra que fecha a seção é curta: se você não consegue verificar, não publique.