Como usar o Claude Code: guia para iniciantes

Para usar o Claude Code, instale-o com um comando, rode claude dentro de uma pasta de projeto, faça login com sua conta do Claude no navegador e então descreva o que quer em linguagem natural. O Claude lê o código de que precisa, propõe edições e comandos e pergunta antes de fazer qualquer coisa que você não tenha permitido.

Esse é o ciclo inteiro. O resto deste guia cobre o que faz ele funcionar bem: um arquivo CLAUDE.md, os modos de permissão, alguns slash commands, o plan mode e alguns hábitos que te mantêm dentro dos limites de uso.

O que é o Claude Code

O Claude Code é o agente de código da Anthropic. Ele roda no seu terminal (e também no VS Code, no JetBrains, num app desktop e na web), trabalha nos arquivos da pasta onde você o inicia e pode rodar comandos de shell como seus testes, linters e git. Diferente de uma janela de chat, ele não precisa que você cole código. Ele vai lá e lê o que precisa.

Passo 1: instale o Claude Code

O instalador nativo é o jeito recomendado. Ele se atualiza sozinho em segundo plano.

Instalações por Homebrew e WinGet não se atualizam sozinhas, então atualize de vez em quando pelo seu gerenciador de pacotes. Confira se funcionou:

claude --version

Passo 2: faça login

Vá até uma pasta de projeto e inicie:

cd your-project
claude

Na primeira vez, o Claude Code abre o navegador para o login. Você pode usar:

• uma assinatura Claude Pro, Max, Team ou Enterprise, que é a escolha mais comum;
• uma conta do Claude Console, cobrada por token a partir de créditos pré-pagos;
• um provedor de nuvem: Amazon Bedrock, Google Cloud ou Microsoft Foundry.

Seu login fica salvo, então você só faz isso uma vez. Se tiver mais de uma conta, /login alterna entre elas.

Passo 3: sua primeira tarefa

Comece com algo pequeno e real, não “crie um app para mim”. Boas primeiras tarefas:

• “Explique como a autenticação funciona neste projeto.”
• “Rode os testes e me diga por que o que falha está falhando.”
• “Adicione validação de entrada ao formulário de cadastro, com um teste.”

Digite e pressione Enter. O Claude lê arquivos e depois propõe mudanças ou comandos. Dependendo do modo de permissão, ele pergunta antes ou segue em frente, e mostra cada edição como um diff. Leia os diffs. Quem entrega o código continua sendo você.

Você também pode começar já com uma tarefa:

claude "find where we parse dates and list the formats we accept"

Outras formas úteis de começar:

Passo 4: escreva um CLAUDE.md

Toda sessão começa com uma janela de contexto nova. O CLAUDE.md é como o Claude se lembra do seu projeto: um arquivo Markdown que ele lê no início de cada sessão.

Rode isto numa sessão:

/init

O Claude percorre o codebase e escreve um primeiro CLAUDE.md com os comandos de build, os comandos de teste e as convenções que encontrou. Se já existir um CLAUDE.md, ele sugere melhorias. Depois, edite você mesmo. Boas coisas para colocar:

• como fazer build, rodar e testar (pnpm test, não “rode os testes”)
• convenções que não são óbvias pelo código
• coisas a evitar (“nunca edite arquivos gerados em src/gen/”)
• onde ficam as partes importantes

Mantenha-o curto; a Anthropic sugere ficar abaixo de umas 200 linhas por arquivo. Arquivos longos gastam contexto e são seguidos com menos confiabilidade. Você pode dividir o conteúdo com imports @path/to/file.

Há alguns lugares onde um CLAUDE.md pode ficar:

Se o seu repositório já tem um AGENTS.md para outros agentes, versões recentes do Claude Code o leem quando não há CLAUDE.md, e você pode importá-lo de um CLAUDE.md com @AGENTS.md.

Passo 5: entenda as permissões

O Claude Code pergunta antes de fazer qualquer coisa arriscada. A frequência depende do modo de permissão. Pressione Shift+Tab para alternar entre eles; o modo atual aparece na parte de baixo da tela.

Versões recentes começam em auto mode por padrão; as mais antigas começam em Manual. No auto mode, um segundo modelo revisa cada ação e bloqueia o que parece arriscado ou fora da tarefa, mas isso não é uma garantia, então fique de olho no que ele faz.

Para um controle mais fino, /permissions deixa você adicionar regras de allow, ask e deny, como “sempre permitir npm test” ou “sempre perguntar antes de git push”. No macOS, Linux e WSL2, /sandbox roda os comandos de Bash dentro de um sandbox.

Existe também --dangerously-skip-permissions, que nunca pergunta. A própria documentação da Anthropic diz para usar só dentro de um contêiner ou máquina virtual. Não use na sua máquina principal enquanto está aprendendo.

Passo 6: os slash commands que valem a pena conhecer

Digite / numa sessão para ver todos os comandos. Estes são os que você mais vai usar:

/rewind é o que os iniciantes esquecem. Se o Claude seguir pelo caminho errado, volte para antes de ele começar em vez de discutir até ele voltar.

Passo 7: use o plan mode para qualquer coisa maior

Para mudanças que tocam mais de um ou dois arquivos, peça um plano primeiro. Pressione Shift+Tab até ver o plan mode, ou digite:

/plan add rate limiting to the public API

No plan mode, o Claude lê o código, faz perguntas para esclarecer e escreve um plano, mas não edita seu código. Você lê o plano, contesta as partes de que não gosta e aprova quando estiver certo. Aí ele passa a editar e segue o plano.

Isso custa alguns minutos e poupa muito retrabalho. Você também pode iniciar uma sessão em plan mode com claude --permission-mode plan.

Bons hábitos de prompt

O Claude Code segue bem instruções claras. A maioria dos resultados ruins vem de instruções vagas.

• Diga como verificar o trabalho. “Adicione o endpoint e faça pnpm test api passar” é melhor que “adicione o endpoint”.
• Aponte arquivos. Cite o arquivo ou a função pelo nome, ou digite @ para referenciar um arquivo.
• Uma tarefa por conversa. Use /clear quando mudar para algo sem relação.
• Dê exemplos. “Siga o padrão de users.service.ts” vale mais que um parágrafo de descrição.
• Peça uma explicação primeiro quando não conhece o código: “Como X funciona? Não mude nada ainda.”
• Interrompa cedo. Pressione Esc para pará-lo se ele for para o lado errado e corrija.
• Coloque correções repetidas no CLAUDE.md. Se você disse duas vezes, escreva.

Limites e como ficar dentro deles

Os planos de assinatura têm limites de uso: uma janela móvel de 5 horas e um limite semanal, e os planos maiores dão mais. Conversas longas gastam mais, porque cada mensagem carrega todo o contexto junto.

• Veja como você está com /usage.
• Use /clear entre tarefas sem relação.
• Use /compact em sessões longas, opcionalmente dizendo o que manter: /compact keep the API decisions.
• Use /context para ver o que está ocupando espaço, como arquivos grandes ou muitas ferramentas de MCP.
• Escolha um modelo mais leve para trabalho simples com /model.

Mais sobre isso em limites de uso do Claude Code e como reduzir o uso de tokens do Claude Code.

Quando um terminal não basta

Quando você pegar o jeito, vai querer um segundo Claude trabalhando enquanto o primeiro roda os testes. Dois agentes na mesma pasta pisam nos arquivos um do outro, então cada um precisa da própria git worktree. É aí que um único terminal fica desconfortável.

O AgentVera é um app desktop para macOS, Windows e Linux que roda o Claude Code (e outros agentes de CLI) em terminais reais, lado a lado. Ele usa o login do Claude Code que você já tem.

• Workspace: uma grade de agentes por projeto, de 1×1 a 5×4. Cada agente tem o próprio nome, modelo, esforço e Role and instructions, e volta para a própria conversa depois de reabrir o app.
• Worktrees: no painel Git, crie uma worktree e inicie um agente nela com um clique, assim agentes em paralelo nunca compartilham arquivos.
• Permissões por agente: no diálogo New agent, escolha Ask, Auto ou Full access. Auto usa o auto mode do próprio Claude Code.
• Checkpoints e replay: os últimos 60 turnos de cada agente ficam guardados, e você pode reproduzir uma sessão.
• Contexto num relance: cada painel mostra o tamanho do contexto ao vivo, e o auto-compact entra em ação antes de a janela encher.

Tudo isso está no plano gratuito. A aprovação automática, que deixa passar leituras e testes seguros mas ainda pergunta antes de coisas como git push ou rm, está no Pro e no Team.

Quando chegar lá, leia como rodar vários agentes do Claude Code e baixe o AgentVera de graça.

Deixe a cola de comandos do Claude Code aberta enquanto aprende e, se você trabalha no VS Code, veja a configuração da extensão para VS Code.

Conclusão

Instale, rode claude, faça login e comece com uma tarefa pequena e real. Rode /init e mantenha seu CLAUDE.md curto. Use Shift+Tab para escolher quanto o Claude pode fazer, o plan mode para qualquer coisa maior, /rewind quando der errado e /clear e /compact para ficar dentro dos limites. Isso cobre a maior parte do que você precisa nas primeiras semanas.