Instale o Claude Code CLI: guia de configuração em 5 minutos (2026)

Como configurar o Claude Code? Instale a CLI com o instalador nativo, curl -fsSL https://claude.ai/install.sh | bash, autentique pelo navegador e crie um arquivo CLAUDE.md na raiz do projeto com os detalhes da sua stack e as convenções de código. Configure as permissões em .claude/settings.json e adicione um hook de formatação para corrigir o estilo automaticamente depois de cada edição. Toda a configuração leva menos de cinco minutos. {.answer-block}

A ServiceNow liberou o Claude Code para mais de 29.000 funcionários¹, e a Allianz anunciou uma parceria que deixou o Claude disponível para todos os seus colaboradores no início de 2026². A curva de adoção da ferramenta revela um padrão: depois que a pessoa experimenta programação agêntica no próprio terminal, ela não volta a copiar e colar de janelas de chat. O passo a passo abaixo leva você do zero a uma sessão funcional do Claude Code em cerca de cinco minutos, com uma configuração real que continua útil depois.

Resumo: instale o Claude Code com o instalador nativo (curl -fsSL https://claude.ai/install.sh | bash), autentique pelo navegador, crie um arquivo CLAUDE.md com o contexto do seu projeto e configure as permissões em .claude/settings.json. Adicione um hook do Prettier para formatar os arquivos automaticamente depois de cada edição. Tudo isso leva menos de cinco minutos e a configuração permanece entre as sessões.

Principais conclusões

• Pessoas desenvolvedoras solo: o CLAUDE.md e um hook de formatação cobrem 80% do que você precisa. Comece com as permissões padrão e vá pré-aprovando ferramentas conforme a confiança aumenta.
• Líderes de equipe: versione o .claude/settings.json no repositório para que a equipe inteira use as mesmas listas de permissões e os mesmos hooks.
• Pessoas de segurança: o modelo de permissões⁴ (Ask/Manual, listas de permissões, o classificador do modo auto, --dangerously-skip-permissions) corresponde diretamente a níveis de confiança. O modo Ask exige aprovação explícita para cada escrita e cada comando; porém, desde 14 de agosto de 2026, as sessões Pro, Max e Team começam no modo auto: fixe "defaultMode": "manual" se o seu modelo de ameaças exigir uma pessoa em cada aprovação.

Pré-requisitos

Você precisa de duas coisas antes de instalar o Claude Code:

Uma conta Anthropic. O Claude Code exige uma conta Pro, Max, Team, Enterprise ou Console; o plano gratuito do Claude.ai não inclui acesso³. Os planos por assinatura já contemplam o uso do Claude Code (Max 5x por US$ 100/mês ou Max 20x por US$ 200/mês, ambos individuais, em meados de 2026)⁶, ou você pode pagar por token usando uma chave de API do console.anthropic.com. A autenticação acontece no navegador depois da instalação, então ainda não há nada para copiar.

Um terminal. O Claude Code roda em qualquer emulador de terminal: Terminal.app, iTerm2, Windows Terminal, Alacritty ou o terminal integrado do VS Code. Recomendo um terminal com pelo menos 120 colunas de largura, já que o Claude Code mostra diffs de arquivos e saídas de ferramentas que se beneficiam do espaço horizontal.

O Node.js não é necessário para a instalação recomendada. Ele só importa se você escolher a alternativa via npm descrita abaixo, que exige Node.js 22 ou superior desde a v2.1.198.

Instalação

Instale o Claude Code com o instalador nativo, recomendado pela Anthropic³:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

No Windows, execute irm https://claude.ai/install.ps1 | iex no PowerShell. O instalador coloca o binário em ~/.local/bin/claude, e as instalações nativas se atualizam sozinhas em segundo plano, então você fica em dia sem upgrades manuais.

Confirme que a instalação deu certo:

claude --version

Um número de versão deve aparecer na saída padrão. Se você receber o erro “command not found”, é porque ~/.local/bin não está no seu PATH. Adicione o caminho ao perfil do shell e recarregue:

# Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Para um diagnóstico mais completo da instalação e da configuração, execute claude doctor: ele verifica o binário, o PATH e o estado das atualizações automáticas, além de apontar instalações conflitantes, como uma cópia global do npm esquecida ao lado da nativa.

Instalações alternativas. O Homebrew funciona bem se você prefere casks gerenciados: brew install --cask claude-code (atualize com brew upgrade --cask claude-code ou defina CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1, disponível desde a v2.1.129, para atualizações em segundo plano pelo gerenciador de pacotes). O pacote npm ainda funciona, mas é legado, descontinuado desde a v2.1.15: npm install -g @anthropic-ai/claude-code (Node.js 22+, nunca com sudo⁷), e por baixo dos panos ele instala o mesmo binário nativo. Se você começou pelo npm e quer migrar para a configuração recomendada, instale a versão nativa e remova a cópia do npm com npm uninstall -g @anthropic-ai/claude-code para evitar conflitos de versão.

Na primeira execução, o Claude Code abre o navegador para a autenticação OAuth. Você faz login, autoriza, e o Claude Code guarda o estado de autenticação de execução localmente em ~/.claude.json. Como alternativa, defina a variável de ambiente ANTHROPIC_API_KEY antes de iniciar. Nos dois casos, as credenciais ficam na sua máquina e autenticam apenas requisições de API.

Primeira sessão

Vá até qualquer diretório de projeto e execute:

cd ~/Projects/my-app
claude

O Claude Code inicia uma sessão REPL interativa, carregando o seu CLAUDE.md e as configurações logo na abertura. No primeiro prompt em um projeto novo, o Claude explora o que precisa:

1. Varre a estrutura de diretórios para entender a organização do projeto
2. Lê arquivos de configuração como package.json, pyproject.toml ou Cargo.toml para identificar a stack técnica
3. Aplica as instruções do seu CLAUDE.md da raiz do projeto, já carregadas na abertura

Faça um teste simples para confirmar que está tudo funcionando:

> Explain the structure of this project

O Claude lê seus arquivos, sintetiza a arquitetura e responde no terminal. Você vê as chamadas de ferramentas em tempo real (cada arquivo lido, cada comando executado) e um pedido de permissão antes de qualquer operação de escrita.

O que observar na sua primeira sessão. Preste atenção em duas coisas: as chamadas de ferramentas, exibidas em tempo real antes de cada ação, e os pedidos de permissão. As chamadas de ferramentas revelam como o Claude navega pela sua base de código. Você vai notar que ele lê arquivos que talvez nem passassem pela sua cabeça, o que muitas vezes traz um contexto útil à tona. Os pedidos de permissão mostram exatamente o que o Claude pretende mudar antes que qualquer coisa toque o disco. Se uma edição proposta parecer errada, recuse e explique melhor o que você quer. O Claude ajusta a abordagem com base no seu retorno dentro da mesma sessão⁸.

Como configurar o CLAUDE.md

O CLAUDE.md é, de longe, o arquivo mais importante para usar o Claude Code com eficácia. Sem ele, o Claude deduz sua stack pelo conteúdo dos arquivos e faz suposições razoáveis. Com ele, o Claude segue exatamente as suas convenções desde o primeiro prompt. A diferença importa porque comportamento baseado em dedução tende a derivar: o Claude pode usar CommonJS em um projeto ESM, escolher o test runner errado ou ignorar o seu fluxo de migração de banco de dados. O CLAUDE.md elimina essa deriva.

Crie o arquivo na raiz do projeto:

touch CLAUDE.md

Este é um modelo inicial prático para um projeto Python:

# My App

## Project Context
FastAPI backend with HTMX frontend. PostgreSQL database.

## Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0 (async)
- Frontend: HTMX + Alpine.js, Jinja2 templates
- Database: PostgreSQL 16, Alembic migrations
- Testing: pytest with pytest-asyncio

## Code Standards
- Type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async database operations only (no sync SQLAlchemy)

## Commands
- `source venv/bin/activate` before any Python command
- `uvicorn app.main:app --reload` starts the dev server
- `python -m pytest -v` runs the test suite
- `alembic upgrade head` applies database migrations

Em um projeto JavaScript ou TypeScript, a estrutura é parecida:

# My App

## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit, Playwright for e2e

## Code Standards
- ESM imports only (no require())
- All API endpoints need input validation with Zod
- Tests required for new endpoints before merging

## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the test suite
- `npx prisma migrate dev` runs database migrations

As seções mais valiosas de um CLAUDE.md são as que evitam erros repetidos. Se o Claude insiste em importar com require() em vez de import, acrescente “ESM imports only” em Code Standards. Se o seu comando de teste exige ativar um virtualenv antes, documente essa sequência. O Claude lê o CLAUDE.md no começo de cada sessão, então cada linha vira uma instrução persistente cujo efeito se acumula ao longo de centenas de interações. Exploro os padrões que tornam os arquivos CLAUDE.md eficazes em Padrões do AGENTS.md e no princípio mais amplo de que contexto é arquitetura. A especificação aberta AGENTS.md⁹ segue um padrão parecido para outras ferramentas agênticas, mas o CLAUDE.md dá suporte a recursos mais ricos, como skills e diretórios de regras.

A hierarquia importa. Você pode colocar um CLAUDE.md em três lugares, e o Claude mescla tudo por ordem de especificidade:

1. ~/.claude/CLAUDE.md: instruções globais para todos os projetos (suas preferências pessoais de código)
2. ./CLAUDE.md: instruções no nível do projeto (versionadas no repositório, compartilhadas com a equipe)
3. ./src/CLAUDE.md: instruções no nível do diretório (restritas a um módulo de monorepo ou subsistema)

O CLAUDE.md de projeto é o que você versiona no controle de código. Quem usa Claude Code na equipe herda suas convenções automaticamente.

Noções básicas de permissões

O Claude Code opera em três níveis de permissão⁴ que determinam quanta autonomia o agente tem. O nível escolhido controla um trade-off fundamental: mais autonomia significa sessões mais rápidas, mas menos visibilidade sobre o que muda.

O modo Ask (chamado de “Manual” na CLI desde a v2.1.200) exige aprovação antes de cada escrita de arquivo, cada execução de comando e cada ação destrutiva. Você vê exatamente o que o Claude pretende fazer e aprova ou rejeita cada passo. Note que o padrão mudou em 14 de agosto de 2026: as sessões Pro, Max e Team agora começam no modo auto, no qual um classificador de segurança revisa cada ação em vez de perguntar a você; pressione Shift+Tab para voltar ao Manual ou fixe o comportamento com "defaultMode": "manual" nas configurações. Continuo recomendando começar no Manual, porque os pedidos de aprovação ensinam como o Claude Code funciona. Depois de algumas sessões, você desenvolve intuição sobre quais operações dá para pré-aprovar com segurança e quais merecem análise toda vez.

As listas de permissões deixam você pré-aprovar ferramentas e padrões específicos para o Claude não perguntar toda hora. A configuração fica no .claude/settings.json do seu projeto:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(python -m pytest:*)",
      "Bash(alembic upgrade head)"
    ]
  }
}

A configuração acima permite que o Claude leia arquivos, pesquise na base de código e execute seus comandos de teste e migração sem perguntar. Ele continua perguntando antes de escrever arquivos ou de rodar qualquer outro comando bash. Repare no padrão: operações de leitura e comandos reconhecidamente seguros entram na lista de permissões. As operações de escrita ficam no modo Ask, porque você quer revisar o que o Claude escreve antes de chegar ao disco.

Pular permissões de forma perigosa (--dangerously-skip-permissions) desativa os pedidos de confirmação; comandos de remoção catastrófica continuam pedindo confirmação, uma rede de proteção presente desde a v2.1.126. Essa flag existe exclusivamente para pipelines de CI/CD e fluxos automatizados em que não há ninguém para aprovar. Nunca use em sessões interativas numa base de código com a qual você se importa.

O sistema de permissões torna o Claude Code seguro em projetos reais. A progressão é deliberada: comece no modo Ask para construir entendimento, coloque na lista de permissões as operações que viram rotina e mantenha as escritas sob controle, para sempre revisar as mudanças antes que elas entrem.

Seu primeiro hook

Hooks são comandos de shell executados em pontos específicos do ciclo de vida do Claude Code⁵. Escrevi um tutorial completo de hooks que constrói cinco hooks de produção do zero, e meu texto sobre criar skills personalizadas trata do nível seguinte de automação. Os hooks resolvem um problema de fundo das ferramentas baseadas em LLM: o modelo segue suas regras de formatação na maior parte do tempo, mas “na maior parte do tempo” significa que a cada dez edições de arquivo aparece uma inconsistência de estilo. Os hooks oferecem garantias determinísticas onde o modelo só oferece probabilidade. Um hook de formatação roda o seu formatador depois de cada escrita de arquivo, sempre, independentemente do que o modelo decidiu fazer. Aqui vai um primeiro hook prático: formatação automática dos arquivos depois que o Claude os edita.

Crie ou edite o .claude/settings.json do seu projeto:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

O hook PostToolUse⁵ dispara depois de cada chamada das ferramentas Edit ou Write. O Claude Code define $FILE_PATH com o caminho do arquivo modificado. O Prettier formata o arquivo no lugar, e || true garante que um código de saída diferente de zero não bloqueie o Claude caso o Prettier não esteja instalado ou o tipo de arquivo não tenha suporte⁵.

Outros hooks iniciais práticos que eu recomendo:

• PreToolUse no Bash: bloqueia comandos perigosos como rm -rf / ou git push --force
• SessionStart: injeta a data atual, o branch git ativo ou variáveis de ambiente no contexto (a saída padrão dos hooks SessionStart alimenta o contexto do Claude)
• Stop: roda sua suíte de testes automaticamente quando o Claude termina uma tarefa

Os hooks transformam o Claude Code de ferramenta conversacional em ambiente de desenvolvimento com regras. Mesmo um ou dois hooks bem escolhidos eliminam categorias inteiras de erro.

Quando algo dá errado

Quatro situações aparecem com frequência na primeira semana de uso do Claude Code. Conhecê-las de antemão poupa tempo de depuração.

O Claude ignora as instruções do seu CLAUDE.md. A causa mais comum: o Claude já leu o arquivo e guardou em cache o entendimento dele antes de você editar. Rode /clear para zerar o contexto ou inicie uma sessão nova. O Claude relê o CLAUDE.md no início da sessão, não a cada prompt. Se ele continuar ignorando as instruções depois de uma sessão limpa, verifique se um CLAUDE.md de prioridade mais alta, o do nível de usuário em ~/.claude/CLAUDE.md, está em conflito com o arquivo do projeto.

O Claude faz uma mudança que você não aprovou. Se você liberou um padrão amplo demais, uma regra genérica de Bash em vez de um prefixo estreito como Bash(python -m pytest:*), o Claude consegue rodar comandos sem perguntar. Restrinja os padrões da sua lista de permissões. A abordagem mais segura: liberar apenas operações de leitura e comandos nomeados especificamente. Se o Claude já fez uma mudança indesejada, git diff mostra exatamente o que mudou e git checkout -- <file> reverte.

A janela de contexto enche durante uma sessão longa. O Claude Code compacta as mensagens mais antigas conforme a janela de contexto enche (os modelos padrão têm janelas de 1 milhão de tokens em meados de 2026, então esse limite demora bem mais para chegar do que antigamente), mas a compactação pode descartar detalhes importantes do começo da conversa. Em sessões de mais de 30 minutos, faça commit das mudanças que funcionam de tempos em tempos e comece uma sessão nova com /clear. O contexto novo relê o CLAUDE.md e parte do zero. Eu faço commit depois de cada subtarefa concluída, o que me dá ao mesmo tempo um ponto de retorno e um limite natural de sessão.

O Claude edita o arquivo errado ou faz mudanças desnecessárias. Quando o Claude começa a “melhorar” um código que você não pediu para tocar, o problema costuma ser a ambiguidade do prompt. Em vez de “limpe o módulo de autenticação”, diga: “em app/auth/handlers.py, renomeie verify_user para verify_user_credentials e atualize todas as chamadas”. Especificidade reduz efeitos colaterais indesejados. Se o Claude já fez edições indesejadas, git diff mostra exatamente o que mudou e git checkout -- <file> reverte arquivos individuais sem perder o resto do trabalho.

Próximos passos

O passo a passo acima cobre o essencial: instalação, primeira sessão, configuração do projeto, permissões e um hook inicial. Para comparar o Claude Code com outras ferramentas agênticas, veja Claude Code vs Codex. Para a referência completa dos 5 sistemas centrais (hierarquia do CLAUDE.md, modelo de permissões completo, arquitetura de hooks, comandos slash personalizados e fluxos multiagente), leia O guia completo do Claude Code.

O guia trata do gerenciamento da janela de contexto, da delegação para subagentes, da ativação automática de skills e dos padrões que surgem depois de meses de uso diário do Claude Code. Se este início rápido foi útil, o guia completo é o próximo passo natural. Para uma consulta rápida de cada comando, flag e atalho, veja o resumo de referência do Claude Code.

Se o seu projeto é um app para iOS ou macOS, o guia de desenvolvimento iOS com agentes cobre os padrões do Claude Code específicos da Apple: a integração com o XcodeBuildMCP para builds e simuladores, os hooks para desenvolvimento Apple que protegem o .pbxproj de edições do agente e a Série Ecossistema Apple, que percorre App Intents, servidores MCP, Foundation Models e a conexão entre agente e plataforma no nível do framework.

Referências

FAQ

Quais são os requisitos para instalar o Claude Code?

Você precisa de uma conta Anthropic (Pro, Max, Team, Enterprise ou Console; o plano gratuito não inclui o Claude Code) e de qualquer emulador de terminal. O Claude Code roda em macOS 13+, Linux e Windows, tanto nativo quanto via WSL. A instalação recomendada é a do instalador nativo, curl -fsSL https://claude.ai/install.sh | bash, que não precisa de Node.js, nem de Docker, nem de outros runtimes. O Node.js 22+ só é exigido se você optar pela alternativa via npm (npm install -g @anthropic-ai/claude-code).

O que é o CLAUDE.md e por que eu preciso dele?

O CLAUDE.md é um arquivo markdown na raiz do projeto que informa ao Claude Code a sua stack, as convenções de código e os comandos mais usados. Sem ele, o Claude deduz sua configuração pelo conteúdo dos arquivos e faz suposições razoáveis, mas essas suposições derivam de uma sessão para outra. Com o CLAUDE.md, o Claude segue exatamente as suas convenções desde o primeiro prompt, em toda sessão. Ele aceita uma hierarquia de três níveis: usuário (~/.claude/CLAUDE.md), projeto (./CLAUDE.md) e diretório (./src/CLAUDE.md), mesclados por ordem de especificidade.

Quanto custa o Claude Code?

O Claude Code aceita dois modelos de cobrança. O modelo de API pago conforme o uso cobra por token nas tarifas padrão da API da Anthropic⁶. Uma sessão típica de 30 a 60 minutos custa de US$ 0,50 a US$ 3,00, dependendo do tamanho da base de código e do volume gerado. Como alternativa, os planos Max⁶ da Anthropic (Max 5x por US$ 100/mês, Max 20x por US$ 200/mês, ambos individuais, em meados de 2026) incluem o uso do Claude Code com limites de uso mais altos. Você acompanha o consumo de API em console.anthropic.com.

Dá para usar o Claude Code com o VS Code?

Dá sim. O Claude Code funciona em qualquer terminal, inclusive no terminal integrado do VS Code. Abra o painel do terminal no VS Code, vá até o diretório do projeto e execute claude exatamente como faria em um terminal separado. O Claude Code lê e edita arquivos no disco, então as mudanças aparecem na hora nas abas do editor do VS Code. Nenhuma extensão é necessária para esse fluxo, embora exista também uma extensão dedicada para o VS Code, caso você prefira um painel integrado. Algumas pessoas mantêm um split de terminal dedicado ao Claude Code ao lado do editor, o que funciona bem para revisar as mudanças conforme elas acontecem.

É seguro usar o Claude Code em bases de código de produção?

O modo Ask do Claude Code exige aprovação explícita antes de cada escrita de arquivo e cada execução de comando. Nada muda no disco sem a sua confirmação. O sistema de permissões, combinado com hooks capazes de bloquear operações perigosas como push forçado ou comandos de shell destrutivos, deixa o Claude Code viável para trabalho em produção. Uso o Claude Code diariamente em projetos que atendem usuários reais. A chave é começar no modo Ask, entender o que cada chamada de ferramenta faz antes de aprová-la e liberar aos poucos apenas as operações em que você confia. O controle de versão é a rede de proteção final: faça commit antes de qualquer sessão relevante do Claude Code para poder reverter sempre.

Qual é o erro mais comum de quem está começando?

Dar contexto demais ao Claude no prompt em vez de colocá-lo no CLAUDE.md. Quem está começando tende a colar todos os padrões de código em cada prompt, o que desperdiça espaço da janela de contexto e produz resultados inconsistentes entre sessões. Mova as instruções recorrentes para o CLAUDE.md de uma vez e use os prompts para pedidos específicos daquela sessão. O segundo erro mais comum: liberar Bash(*) em vez de comandos específicos. Uma liberação de Bash com curinga deixa o Claude executar qualquer comando de shell sem perguntar, o que anula o propósito do sistema de permissões.