Setup do Claude Code CLI 2026: Guia rápido de 5 minutos

Como configurar o Claude Code? Instale o CLI globalmente com npm install -g @anthropic-ai/claude-code, autentique-se pelo navegador e então crie um arquivo CLAUDE.md na raiz do seu projeto com detalhes da stack e 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 após cada edição. Todo o setup leva menos de cinco minutos. {.answer-block}

Mais de 29.000 desenvolvedores na ServiceNow já usam o Claude Code diariamente¹, e a Allianz implantou a ferramenta em toda a empresa no início de 2026². A curva de adoção da ferramenta reflete um padrão: uma vez que os desenvolvedores experimentam codificação agêntica no próprio terminal, eles não voltam a copiar e colar de janelas de chat. Este guia rápido faz parte da minha série sobre engenharia de IA — guias práticos para desenvolvedores que constroem com Claude. O passo a passo a seguir leva você do zero a uma sessão funcional do Claude Code em cerca de cinco minutos, com configurações reais que você pode continuar usando depois.

TL;DR: Instale o Claude Code via npm install -g @anthropic-ai/claude-code, autentique-se 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 arquivos automaticamente após cada edição. Todo o setup leva menos de cinco minutos e a configuração persiste entre sessões.

Pontos principais

• Desenvolvedores solo: CLAUDE.md e um hook de formatação cobrem 80% do que você precisa. Comece com as permissões padrão e pré-aprove ferramentas conforme constrói confiança.
• Líderes de equipe: Faça commit de .claude/settings.json no seu repositório para que toda a equipe compartilhe as mesmas allowlists de permissões e hooks.
• Engenheiros de segurança: O modelo de permissões em três níveis⁴ (Ask, Allowlisted, --dangerously-skip-permissions) mapeia diretamente para níveis de confiança. O modo Ask exige aprovação explícita para cada escrita e cada comando.

Pré-requisitos

Você precisa de três coisas antes de instalar o Claude Code:

Node.js 18 ou superior. O Claude Code é distribuído como um pacote npm³. Verifique sua versão:

node --version
# v18.0.0 or higher

Se precisar instalar ou atualizar o Node.js, use o nvm ou baixe diretamente de nodejs.org.

Uma conta Anthropic com acesso à API. Crie uma chave de API em console.anthropic.com em Settings > API Keys. O Claude Code cobra por token do seu saldo da API, ou você pode usar o plano de assinatura Max (US$ 100/mês individual, US$ 200/mês para equipes em março de 2026)⁶. Mantenha a chave disponível para a etapa de autenticação.

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 exibe diffs de arquivos e saídas de ferramentas que se beneficiam de espaço horizontal.

Instalação

Instale o Claude Code globalmente via npm:

npm install -g @anthropic-ai/claude-code

Verifique se a instalação foi bem-sucedida:

claude --version

Você deve ver um número de versão impresso no stdout. Se receber um erro “command not found”, o diretório global de binários do npm não está no seu PATH. Execute npm config get prefix e adicione o subdiretório /bin ao PATH do seu shell. No macOS com o Node instalado via Homebrew, o prefixo geralmente é /usr/local, portanto adicione /usr/local/bin se ainda não estiver lá.

Problema comum de instalação: Se você encontrar erros de permissão EACCES durante npm install -g, não use sudo. Em vez disso, configure o npm para usar um diretório gravável pelo usuário⁷:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (~/.zshrc or ~/.bashrc):
export PATH="$HOME/.npm-global/bin:$PATH"

Na primeira execução, o Claude Code abre seu navegador no console da Anthropic para autenticação OAuth. Você faz login, autoriza, e o Claude Code armazena o token localmente em ~/.claude/. Como alternativa, você pode definir a variável de ambiente ANTHROPIC_API_KEY antes de iniciar. De qualquer forma, as credenciais permanecem na sua máquina e autenticam apenas requisições à API.

Primeira sessão

Navegue até qualquer diretório de projeto e execute:

cd ~/Projects/my-app
claude

O Claude Code inicia uma sessão REPL interativa. Na primeira execução em um novo projeto, o Claude faz várias coisas automaticamente:

1. Escaneia a estrutura de diretórios para entender o layout do projeto
2. Lê arquivos de configuração como package.json, pyproject.toml ou Cargo.toml para identificar a stack
3. Procura um arquivo CLAUDE.md na raiz do projeto para instruções específicas do projeto

Teste com um prompt simples para confirmar que tudo funciona:

> Explain the structure of this project

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

O que observar na sua primeira sessão. Preste atenção a duas coisas: as chamadas de ferramentas (mostradas em tempo real antes de cada ação) e os prompts de permissão. As chamadas de ferramentas revelam como o Claude navega pela sua base de código. Você notará que ele lê arquivos nos quais você talvez não tivesse pensado em verificar, o que muitas vezes traz à tona contexto útil. Os prompts de permissão mostram exatamente o que o Claude pretende alterar antes que algo toque o disco. Se uma edição proposta parecer errada, negue-a e forneça esclarecimentos. O Claude ajusta sua abordagem com base no seu feedback dentro da sessão⁸.

Configurando o CLAUDE.md

O CLAUDE.md é o arquivo mais importante para o uso eficaz do Claude Code. Sem ele, o Claude infere sua stack a partir do conteúdo dos arquivos e faz suposições razoáveis. Com ele, o Claude segue suas convenções exatas desde o primeiro prompt. A diferença importa porque o comportamento baseado em inferência sofre desvios: o Claude pode usar CommonJS em um projeto ESM, escolher o test runner errado ou ignorar seu workflow de migração de banco de dados. O CLAUDE.md elimina esse desvio.

Crie o arquivo na raiz do seu projeto:

touch CLAUDE.md

Aqui está um template prático para começar em 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

Para um projeto JavaScript/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 do CLAUDE.md são aquelas que evitam erros repetidos. Se o Claude continuar importando com require() em vez de import, adicione “ESM imports only” aos Code Standards. Se seu comando de teste exigir ativar primeiro um virtualenv, documente essa sequência. O Claude lê o CLAUDE.md no início de cada sessão, portanto cada linha se torna uma instrução persistente que se acumula ao longo de centenas de interações. Exploro os padrões que tornam os arquivos CLAUDE.md eficazes em AGENTS.md Patterns, e o princípio mais amplo de como contexto é arquitetura. A especificação aberta AGENTS.md⁹ segue um padrão similar para outras ferramentas agênticas, mas o CLAUDE.md suporta recursos mais ricos como diretórios de skills e regras.

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

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

O CLAUDE.md no nível do projeto é o que você commita no controle de versão. Os membros da equipe que usam o Claude Code herdam suas convenções automaticamente.

Fundamentos 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 que você escolhe controla um trade-off fundamental: mais autonomia significa sessões mais rápidas, mas menos visibilidade do que está sendo alterado.

Modo Ask (o padrão) exige aprovação antes de cada escrita em arquivo, execução de comando ou ação destrutiva. Você vê exatamente o que o Claude pretende fazer e aprova ou rejeita cada passo. Recomendo começar aqui porque os prompts de aprovação ensinam como o Claude Code funciona. Depois de algumas sessões, você desenvolve intuição sobre quais operações são seguras para pré-aprovar e quais merecem escrutínio todas as vezes.

Permissões em allowlist permitem que você pré-aprove ferramentas e padrões específicos para que o Claude não pergunte todas as vezes. Você configura isso 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 de migração sem perguntar. Ele ainda pergunta antes de escrever arquivos ou executar qualquer outro comando bash. Observe o padrão: operações de leitura e comandos sabidamente seguros entram na allowlist. Operações de escrita permanecem no modo Ask porque você quer revisar o que o Claude escreve antes que isso chegue ao disco.

Pular permissões perigosamente (--dangerously-skip-permissions) desabilita todos os prompts de confirmação. A flag existe exclusivamente para pipelines de CI/CD e workflows automatizados onde nenhum humano está presente para aprovar. Nunca use em sessões interativas em uma base de código que você valoriza.

O sistema de permissões torna o Claude Code seguro para usar em projetos reais. A progressão é deliberada: comece no modo Ask para construir entendimento, coloque na allowlist as operações que se tornam repetitivas e deixe as operações de escrita restritas para que você sempre revise as alterações antes que elas cheguem.

Seu primeiro hook

Hooks são comandos shell que executam 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 post sobre construir skills customizadas cobre o próximo nível de automação. Hooks resolvem um problema fundamental com 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 uma inconsistência de estilo aparece. Hooks fornecem garantias determinísticas onde o modelo fornece garantias probabilísticas. Um hook de formatação executa seu formatador após cada escrita de arquivo, todas as vezes, independentemente do que o modelo decidiu fazer. Aqui está um primeiro hook prático: formatar arquivos automaticamente depois que o Claude os edita.

Crie ou edite .claude/settings.json no seu projeto:

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

O hook PostToolUse⁵ dispara após cada chamada de ferramenta Edit ou Write. O Claude Code define $FILE_PATH como o caminho do arquivo modificado. O Prettier o formata no local, 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 seja suportado⁵.

Outros hooks iniciais práticos que recomendo:

• PreToolUse em 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 stdout dos hooks SessionStart alimenta o contexto do Claude)
• Stop: Executa seu conjunto de testes automaticamente quando o Claude termina uma tarefa

Hooks transformam o Claude Code de uma ferramenta conversacional em um ambiente de desenvolvimento governado. Até mesmo um ou dois hooks bem escolhidos eliminam categorias inteiras de erros.

Quando algo dá errado

Três situações aparecem repetidamente na primeira semana de uso do Claude Code. Conhecê-las de antemão economiza tempo de depuração.

O Claude ignora suas instruções no CLAUDE.md. A causa mais comum: o Claude já leu o arquivo e armazenou em cache o seu entendimento antes de você editá-lo. Execute /clear para resetar o contexto, ou inicie uma nova sessão. O Claude relê o CLAUDE.md no início da sessão, não a cada prompt. Se o Claude ainda ignorar as instruções após uma sessão nova, verifique se um CLAUDE.md de prioridade maior (no nível do usuário em ~/.claude/CLAUDE.md) entra em conflito com o arquivo no nível do projeto.

O Claude faz uma alteração que você não aprovou. Se você colocou um padrão na allowlist de forma muito ampla (por exemplo, Bash(*) em vez de Bash(python -m pytest*)), o Claude pode executar comandos sem perguntar. Restrinja seus padrões de allowlist. A abordagem mais segura: coloque na allowlist apenas operações de leitura e comandos nomeados específicos. Se o Claude já fez uma alteração 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 comprime mensagens anteriores quando a janela de contexto de 200K enche, mas a compressão pode descartar detalhes importantes do início da conversa. Para sessões com mais de 30 minutos, faça commits periódicos das alterações em andamento e inicie uma nova sessão com /clear. O contexto novo relê o CLAUDE.md e começa limpo. Eu faço commit após cada subtarefa concluída, o que me dá tanto um ponto de rollback quanto uma fronteira natural de sessão.

O Claude edita o arquivo errado ou faz alterações desnecessárias. Quando o Claude começa a “melhorar” código que você não pediu para tocar, o problema geralmente é ambiguidade no prompt. Em vez de “limpe o módulo de auth”, diga “em app/auth/handlers.py, renomeie verify_user para verify_user_credentials e atualize todos os chamadores”. 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 outros trabalhos.

Próximos passos

O passo a passo acima cobre o essencial: instalação, sua primeira sessão, configuração do projeto, permissões e um hook inicial. Para uma comparação do Claude Code com outras ferramentas agênticas, veja Claude Code vs Codex. Para a referência completa cobrindo todos os 5 sistemas centrais (hierarquia do CLAUDE.md, o modelo completo de permissões, arquitetura de hooks, slash commands customizados e workflows multi-agentes) leia O Guia Completo do Claude Code.

O guia cobre gerenciamento da janela de contexto, delegação para subagentes, auto-ativação de skills e os padrões que emergem após meses de uso diário do Claude Code. Se este guia rápido foi útil, o guia completo é o próximo passo natural. Para uma referência de consulta rápida de cada comando, flag e atalho, veja o Cheat Sheet do Claude Code.

Referências

FAQ

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

Você precisa de Node.js 18 ou superior (o Claude Code é distribuído como um pacote npm), uma conta Anthropic com acesso à API ou uma assinatura Max, e qualquer emulador de terminal. O Claude Code roda em macOS, Linux e Windows (via WSL ou nativo). Nenhuma dependência adicional, contêineres Docker ou runtimes de linguagem são necessários além do Node.js. O comando de instalação é npm install -g @anthropic-ai/claude-code.

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

CLAUDE.md é um arquivo markdown na raiz do seu projeto que informa ao Claude Code sua stack, convenções de código e comandos comuns. Sem ele, o Claude infere sua configuração a partir do conteúdo dos arquivos e faz suposições razoáveis — mas essas suposições sofrem desvios entre as sessões. Com o CLAUDE.md, o Claude segue suas convenções exatas desde o primeiro prompt, em cada sessão. Ele suporta uma hierarquia de três níveis: nível do usuário (~/.claude/CLAUDE.md), nível do projeto (./CLAUDE.md) e nível do diretório (./src/CLAUDE.md), mesclados em ordem de especificidade.

Quanto custa o Claude Code?

O Claude Code suporta dois modelos de cobrança. O modelo API pay-as-you-go cobra por token às tarifas padrão da API da Anthropic⁶. Uma sessão típica de 30 a 60 minutos custa entre US$ 0,50 e US$ 3,00 dependendo do tamanho da base de código e do volume de geração. Alternativamente, o plano Max da Anthropic⁶ (US$ 100/mês individual, US$ 200/mês para equipes em março de 2026) inclui o uso do Claude Code com limites de taxa mais altos. Você pode monitorar o uso da API em console.anthropic.com.

Posso usar o Claude Code com o VS Code?

Sim. O Claude Code funciona em qualquer terminal, incluindo o terminal integrado do VS Code. Abra o painel do terminal no VS Code, navegue até o diretório do seu projeto e execute claude exatamente como faria em um terminal autônomo. O Claude Code lê e edita arquivos no disco, portanto as alterações aparecem imediatamente nas abas do editor do VS Code. Não há extensão separada do VS Code necessária. Alguns desenvolvedores mantêm uma divisão dedicada do terminal para o Claude Code ao lado de seu editor, o que funciona bem para revisar alterações à medida que elas acontecem.

O Claude Code é seguro para usar em bases de código de produção?

O modo Ask do Claude Code exige aprovação explícita antes de cada escrita em arquivo e cada execução de comando. Nada muda no disco sem sua confirmação. O sistema de permissões, combinado com hooks que podem bloquear operações perigosas como force pushes ou comandos shell destrutivos, torna o Claude Code prático para trabalho em produção. Eu 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 gradualmente colocar na allowlist apenas as operações em que você confia. O controle de versão fornece a rede de segurança final: faça commit antes de iniciar qualquer sessão significativa do Claude Code para que você sempre possa reverter.

Qual é o erro mais comum que novos usuários cometem?

Dar ao Claude contexto demais no prompt em vez de colocá-lo no CLAUDE.md. Novos usuários tendem a colar todos os seus padrões de codificação em cada prompt, o que desperdiça espaço da janela de contexto e produz resultados inconsistentes entre sessões. Mova instruções recorrentes para o CLAUDE.md uma vez, e use prompts para requisições específicas da sessão. O segundo erro mais comum: colocar Bash(*) na allowlist em vez de comandos específicos. Uma allowlist de Bash com curinga permite que o Claude execute qualquer comando shell sem perguntar, o que anula o propósito do sistema de permissões.