Como Usar o Claude Code: Planeje, Escreva Prompts e Mantenha o Controle

Quase todo mundo conhece o Claude no chat: você cola código, copia a resposta de volta e torce para encaixar. O Claude Code é diferente. Ele roda dentro do seu projeto, lê os arquivos, edita, executa os testes e faz o commit, pedindo permissão pelo caminho. Isso o torna mais útil que um chatbot para software de verdade, e mais fácil de usar mal. Este guia mostra como usar o Claude Code direito: instalação, primeira sessão, planejar antes de ele escrever, prompts que ele consegue executar, a configuração que o mantém nos trilhos e os limites a conhecer antes de lhe entregar o código.

O que é o Claude Code (e o que não é)

É a ferramenta de programação agêntica da Anthropic. "Agêntica" quer dizer que ele não só sugere código: trabalha em ciclo, escolhe o próximo passo, usa ferramentas e confere o resultado até concluir a tarefa. Na prática, ele pesquisa o repositório, lê e edita arquivos, roda comandos de shell como os testes ou o linter, usa o git e se conecta a ferramentas externas. A ideia por trás desse ciclo está no nosso guia sobre o que são agentes de IA.

Ele roda em vários lugares, todos com o mesmo motor, e as configurações do projeto valem em todos:

• O terminal: a versão completa, foco deste guia.
• VS Code e IDEs da JetBrains: extensões com diffs no editor e a opção de compartilhar a seleção atual.
• O app de desktop: a aba Code do app do Claude, com revisão visual de diffs e várias sessões lado a lado.
• Os apps web e mobile: em claude.ai/code, para tarefas longas em repositórios que você não tem localmente.

O que ele não é: um autocompletar que termina a sua linha, nem substituto para saber o que o seu código deve fazer. Lembra mais um colega rápido e incansável recém-chegado: lê tudo depressa, mas só sabe o que está no repositório e o que você conta. Para respostas, explicações ou uma segunda opinião sobre um trecho, o chat comum do nosso guia de como usar o Claude é mais simples.

Como instalar o Claude Code e iniciar uma sessão

Você precisa de um plano pago do Claude (Pro, Max, Ultra, Team ou Enterprise), de uma conta no Claude Console com créditos de API ou de acesso por um provedor de nuvem compatível, como o Amazon Bedrock. O plano gratuito não o inclui.

O instalador recomendado é um só comando. No macOS, Linux ou WSL, abra um terminal e rode curl -fsSL https://claude.ai/install.sh | bash. No PowerShell do Windows, use irm https://claude.ai/install.ps1 | iex. Homebrew (brew install --cask claude-code) e WinGet (winget install Anthropic.ClaudeCode) também funcionam, mas, ao contrário do instalador nativo, não se atualizam sozinhos. No Windows nativo, instale também o Git for Windows para o Claude Code poder usar um shell Bash.

Depois:

1. Abra um terminal novo e rode claude --version para confirmar a instalação. Se o comando não existir, a pasta de instalação ainda não está no PATH.
2. Entre numa pasta de projeto com cd e digite claude.
3. Faça login quando pedido. Ele abre o navegador; as credenciais ficam salvas, então é uma vez só.
4. Digite /help para ver os comandos disponíveis. Um / sozinho lista comandos e skills enquanto você digita.

Prefere evitar o terminal? Use a extensão do VS Code ou a aba Code do app de desktop. Tudo o que segue vale lá também, com botões no lugar de alguns atalhos.

Primeira sessão: explore e depois faça uma mudança pequena

Não comece com "crie uma funcionalidade". Deixe o Claude Code ler o projeto e contar o que encontrou. Você vê como ele raciocina e pega mal-entendidos antes das edições. Perguntas simples servem: "o que este projeto faz?", "onde fica o ponto de entrada principal?" ou "explique a estrutura de pastas". Num código desconhecido, peça um tour completo:

Depois faça uma mudança pequena e segura: um erro de digitação no README, um teste que falta ou uma mensagem de erro mais clara. Observe. Cada edição aparece como diff e, conforme o modo de permissão da sessão, ele pergunta antes de aplicar ou aplica e avisa. Selecione Yes se a mudança parecer certa; se não, diga o que está errado.

O git também funciona em conversa: "quais arquivos eu alterei?", "crie uma branch chamada fix/login-timeout" ou "faça commit das minhas mudanças com uma mensagem descritiva". Trabalhe numa branch desde o início, para descartar qualquer experimento facilmente.

Primeiro o plano, depois o código

Para algo maior que uma correção pequena, o melhor hábito é separar pensar de digitar. No modo de planejamento (Plan mode), o Claude Code lê e explora, mas não edita o código-fonte até você aprovar um plano escrito. Pressione Shift+Tab para chegar a ele (a linha de status mostra "plan mode on") ou comece um único prompt com /plan.

Um bom prompt de planejamento descreve o resultado, as restrições e como saber que funciona:

Com o plano pronto, o Claude Code oferece aprovar e seguir, aprovar revisando cada edição ou continuar planejando. Leia com atenção: é a hora mais barata para pegar uma suposição errada, como editar um arquivo gerado ou ignorar uma chamada em outro ponto do código. Ctrl+G abre o plano no seu editor para alterá-lo antes de aprovar.

Como escrever prompts que o Claude Code consegue executar

O Claude Code lê o repositório, mas não a sua mente nem a sua tela. O conselho oficial: conte o que ele não descobre sozinho. Diga o arquivo, descreva o sintoma e como é o "corrigido". "Corrija o bug" o manda caçar; "corrija o bug do login em que o usuário vê uma tela em branco após errar a senha" o põe direto no trabalho.

Formas de passar contexto diretamente:

• Referencie arquivos com @: digitar @ seguido de um caminho, como @src/auth/session.ts, inclui esse arquivo na mensagem.
• Cole o erro real: o stack trace completo ou a saída do teste vale mais que uma paráfrase.
• Cole capturas de tela: úteis para bugs de layout ou um design a reproduzir.
• Divida trabalhos grandes em etapas numeradas: crie a tabela, depois o endpoint, depois a página que o usa.

Para bugs, esta estrutura funciona bem:

A última linha importa. Pressionado a fazer um teste passar, qualquer modelo de programação pode ser tentado a editar o teste ou esconder o erro. Avisar antes evita isso. Nossos prompts de IA para programação têm mais templates para revisões, refatorações e documentação, e o gerador de prompts para Claude transforma um pedido vago num prompt estruturado assim.

CLAUDE.md, permissões e desfazer: mantendo o controle

O CLAUDE.md é um arquivo Markdown simples na raiz do projeto, lido pelo Claude Code no início de cada sessão. Rode /init e ele gera um rascunho a partir do código; o seu trabalho é sobretudo apagar linhas. Mantenha-o curto (a documentação sugere menos de 200 linhas) com só o que o Claude não deduz do código: os comandos exatos de build e teste, as convenções da equipe, o passo de deploy que só existe na cabeça de alguém, as pastas proibidas. Se o repositório já tem um AGENTS.md para outros agentes, o Claude Code pode lê-lo no lugar. Escrever essas instruções lembra muito escrever um system prompt; nosso gerador de system prompt ajuda a estruturá-las.

Os modos de permissão definem o que roda sem perguntar. Shift+Tab alterna entre eles:

• Manual: o Claude lê à vontade, mas pergunta antes de editar ou rodar comandos.
• Accept edits (aceitar edições): edições e comandos comuns de arquivo na pasta do projeto seguem direto; os demais ainda perguntam.
• Plan (planejamento): exploração e um plano escrito, sem editar o código-fonte.
• Auto, onde houver: tudo roda, e um modelo classificador separado revisa antes as ações arriscadas.

A documentação é clara em dois pontos. Primeiro, o CLAUDE.md é orientação, e o Claude pode achar que uma linha não se aplica. O que deve acontecer sempre vira uma regra de negação (deny rule; por exemplo, bloquear a leitura de arquivos .env) ou um hook, um script que o Claude Code roda em pontos fixos, como antes de cada edição ou quando o Claude tenta terminar. Segundo, nunca use o modo que ignora todas as permissões fora de um contêiner descartável ou máquina virtual.

Se ele errar o rumo, pressione Esc para pará-lo no meio da ação e redirecionar. Pressione Esc duas vezes com o prompt vazio, ou digite /rewind, para voltar o código, a conversa ou ambos a um ponto anterior. Esses checkpoints só cobrem arquivos editados pelas ferramentas do próprio Claude, não por comandos de shell, então continue fazendo commits no git.

Sessões longas, custos e automação

Cada mensagem reenvia a conversa até ali, então sessões longas gastam mais cota do plano ou orçamento de API. A maioria dos modelos atuais do Claude tem janela de contexto de um milhão de tokens, e o Claude Code compacta o histórico antigo sozinho, então raramente falta espaço. O problema é pagar por histórico inútil e se distrair com ele. O que ajuda:

• /clear entre tarefas sem relação: não custa nada. /clear [NOME] também nomeia a sessão que você deixa, para voltar a ela.
• /compact com um foco: /compact mantenha as mudanças na API e os comandos de teste resume o resto.
• /usage e /context: mostram para onde foi o uso e o que enche a janela de contexto.
• Retome em vez de explicar de novo: claude -c continua a última sessão naquela pasta; /rename mais claude --resume [NOME] retoma um trabalho nomeado dias depois.

Dominado o básico, o Claude Code vai muito além do chat. claude -p "[TAREFA]" roda um único prompt e sai, o que permite enviar logs por pipe ou chamá-lo de scripts e CI; há integrações prontas para GitHub Actions e GitLab. Servidores MCP o conectam a ferramentas como gerenciadores de issues, bancos de dados e arquivos de design. As skills empacotam procedimentos repetíveis, como um checklist de release, que o Claude só carrega quando precisa, e os subagentes cuidam de tarefas paralelas sem poluir a conversa principal.

O que o Claude Code não consegue fazer

• Saber o que não está escrito: regras de negócio, o porquê de um código estranho ou um deploy que ninguém documentou. Fora do repositório, do CLAUDE.md ou do prompt, o Claude chuta.
• Garantir código correto: ele pode escrever código plausível que passa em testes fracos e ainda falha em casos extremos, segurança ou desempenho. Revise os diffs como o pull request de um colega, sobretudo em autenticação, pagamentos ou exclusão de dados.
• Fazer você entender o próprio sistema: deixá-lo escrever tudo sem ler é vibe coding, bom para protótipos e arriscado para o que você vai manter.
• Resistir sozinho a instruções maliciosas: páginas web, issues, dependências ou arquivos lidos podem conter texto feito para manipulá-lo. Pedidos de permissão, regras de negação e o sandbox (/sandbox) existem em parte para isso; veja nosso guia sobre injeção de prompt.
• Sair de graça: exige plano pago ou créditos de API, e sessões pesadas esgotam rápido os limites do plano. Confira os preços atuais antes de colocá-lo no fluxo de uma equipe.
• Ficar igual por muito tempo: funcionalidades, comandos e padrões mudam com frequência. Se um comando deste guia agir diferente, valem a documentação oficial e o /help.

Bem usado, o Claude Code assume as partes lentas da programação: se orientar num código desconhecido, escrever os testes que você pularia, caçar um bug por seis arquivos. O padrão é sempre o mesmo. Explore primeiro, planeje antes de editar, dê uma verificação para ele rodar, mantenha o CLAUDE.md curto e verdadeiro e revise o que ele entrega. Você continua sendo o engenheiro; ele digita.

Referências

• Anthropic — Visão geral do Claude Code (documentação oficial)
• Anthropic — Boas práticas para Claude Code
• Wikipedia — Claude