⚙️ Instalação & Setup

Node.js v18+ (ou Bun), terminal com suporte a cores e acesso à internet para autenticação inicial.

Sem o ambiente certo, a instalação falha silenciosamente. Checar antes economiza 30 min de depuração.

Node.js LTS, verificar com node -v, npm v9+ ou Bun v1+, suporte a macOS/Linux/WSL2.

Um único comando instala o Claude Code globalmente: npm install -g @anthropic-ai/claude-code.

Instalação global torna o comando claude disponível em qualquer diretório do sistema.

Flag -g (global), permissões de pasta npm, alternativa via Bun: bun install -g.

Rodar claude --version e claude --help para confirmar que o binário está no PATH.

Detecta erros de PATH antes de perder tempo na autenticação. "command not found" tem solução simples.

PATH do sistema, which claude, output esperado com número de versão.

Claude Code lança atualizações frequentes com novos modelos e features. O mesmo comando de instalação com npm update -g atualiza.

Versões antigas não suportam modelos novos. Atualização leva 30 segundos e traz melhorias significativas.

npm update -g @anthropic-ai/claude-code, verificar changelog no GitHub, breaking changes raros.

Claude Code roda nativamente em macOS e Linux. No Windows, use WSL2 (Windows Subsystem for Linux) para melhor compatibilidade.

Cada OS tem gotchas de permissão e PATH diferentes. Conhecer as diferenças evita horas de frustração.

WSL2 no Windows, Homebrew no macOS para Node.js, distros Linux recomendadas (Ubuntu 22+).

Os 5 erros mais frequentes: EACCES (permissão npm), command not found (PATH), ENOENT (Node versão antiga), network timeout, e conflito de versão.

Erros de instalação bloqueiam 30% dos iniciantes. Ter o diagnóstico em mente resolve em minutos.

sudo npm install -g (solução EACCES), nvm para múltiplas versões Node, verificar npm cache com npm cache clean --force.

Digitar claude no terminal abre o REPL interativo. Na primeira execução, redireciona para autenticação.

Entender o fluxo de primeiro boot evita confusão com os prompts de login e términal interativo.

REPL (Read-Eval-Print Loop), terminal interativo, fluxo de onboarding automático.

O Claude Code autentica via browser OAuth com sua conta Anthropic ou via API key. Credenciais ficam em ~/.claude/.

Escolher entre conta vs API key determina billing, limites e modelo disponível.

OAuth2 browser flow, pasta ~/.claude/, token de sessão, reautenticação quando expira.

API key = pague por uso (tokens). Claude Max = assinatura mensal com limite generoso. Para uso pesado, assinatura costuma valer mais.

Escolha errada pode gerar custos surpresa ou limitar projetos que precisam de muitas chamadas diárias.

Token pricing, rate limits, Claude Pro vs Max, variável de ambiente ANTHROPIC_API_KEY.

O prompt > aceita linguagem natural, comandos slash (/help, /clear) e referências a arquivos com @.

Dominar os atalhos do REPL multiplica produtividade — sem precisar reescrever contexto a cada mensagem.

Comandos /help, /clear, /status, referência a arquivos com @, multiline com Enter vs Shift+Enter.

Pedir ao Claude para criar um arquivo, ler um projeto, explicar código existente — as primeiras tarefas práticas.

Colocar a mão na massa imediatamente consolida o aprendizado e desmistifica o uso da ferramenta.

Prompt de task, confirmação de ação, diferença entre leitura (segura) e escrita (requer permissão).

Sair com Ctrl+C ou /exit. Retomar o contexto anterior com claude --resume ou abrindo o mesmo diretório.

Sessões longas são normais em projetos reais. Saber retomar sem perder contexto é essencial.

Contexto persistido no diretório, .claude/ local, claude --resume, histórico de conversas.

Arquivo JSON que controla permissões, ferramentas, hooks e comportamentos do Claude Code. Localizado em ~/.claude/settings.json (global) ou .claude/settings.json (projeto).

Sem conhecer settings.json você aceita todos os defaults — e recebe prompts de permissão para cada ação trivial.

Hierarquia user > project, chave permissions, tools, merge vs override.

Cada ferramenta pode ser configurada com allow (executar sem perguntar), ask (pedir confirmação) ou deny (bloquear).

Permissões erradas travam o workflow ou expõem operações destrutivas. O balanço certo é produtivo e seguro.

Chave allow lista glob patterns, escopo por ferramenta (Bash, Read, Write, Edit), override por projeto.

Regras gerais: leitura é segura (allow), escrita dentro do projeto é ok, comandos de sistema externos precisam de atenção, delete/drop requer ask.

Liberar tudo (allow *) é perigoso em máquinas de produção. Liberar pouco demais inutiliza a ferramenta.

Principle of least privilege, glob src/** para limitar escopo, deny para comandos destruidores.

Modos pré-definidos: default (pede confirmação em tudo), --dangerously-skip-permissions (sem confirmação — apenas dev local), modo headless para CI/CD.

Em pipelines automatizados você precisa de modo não-interativo. Em produção, nunca use dangerously-skip.

Flag --print para saída não-interativa, variáveis de ambiente para CI, claude --no-tty.

Arquivo Markdown que o Claude lê automaticamente a cada sessão. É o "briefing" do projeto — contexto, convenções, comandos especiais.

Sem CLAUDE.md você repete o contexto toda sessão. Com ele, o Claude já sabe o stack, estilo e regras do projeto.

Posição ./CLAUDE.md ou ~/.claude/CLAUDE.md, seções recomendadas, limite de tokens do contexto.

Settings globais (~/.claude/settings.json) se aplicam a todos os projetos. Settings de projeto (.claude/settings.json) sobrescrevem para aquele repo.

Configurar corretamente a hierarquia evita conflitos entre projetos pessoais e profissionais.

Merge de objetos JSON, precedência project > user, versionar .claude/settings.json no git do projeto.

Model Context Protocol (MCP) é um padrão aberto para conectar Claude a ferramentas externas: bancos de dados, APIs, filesystems, serviços cloud.

Com MCP o Claude deixa de ser um chatbot e vira um agente que acessa dados reais do seu ambiente.

Servidor MCP, cliente Claude Code, JSON-RPC, ferramentas expostas via MCP, repositório oficial de servidores.

Adicionar um servidor MCP ao settings.json na chave mcpServers. O Claude inicializa e expõe as ferramentas automaticamente.

Conectar um MCP leva 2 minutos. Sem este conhecimento você usa apenas as ferramentas nativas do Claude.

Chave mcpServers no JSON, command e args, verificar com /mcp no REPL.

Servidores MCP disponíveis: filesystem, GitHub, PostgreSQL, Slack, Google Drive, Puppeteer (browser), SQLite e dezenas mais.

Cada MCP expande drasticamente o que o Claude pode fazer. GitHub MCP + Claude = revisão de código automatizada.

Repositório modelcontextprotocol/servers, MCPs oficiais vs comunitários, segurança de servidores de terceiros.

Abrir o Claude Code em um diretório existente ou criar um projeto do zero com estrutura de arquivos, CLAUDE.md e settings iniciais.

Começar um projeto corretamente (com CLAUDE.md e settings) garante consistência durante todo o desenvolvimento.

cd meu-projeto && claude, estrutura recomendada de diretório, /init para gerar CLAUDE.md automático.

Criar projeto, escrever CLAUDE.md, fazer uma tarefa real (ex: criar API REST), revisar mudanças, commitar — tudo com Claude guiando.

Ver o ciclo completo (intenção → código → revisão → commit) solidifica o modelo mental de uso do Claude Code.

Loop de desenvolvimento, diff visual, confirmação de mudanças, integração com git, output de tarefas complexas.

Com instalação, auth, settings e MCP configurados, você está pronto para explorar Skills (T3), Automação (T4) e Projetos reais (T5).

O setup é a base. Tudo que vem depois depende de ter o ambiente bem configurado.

Skills personalizadas, hooks de automação, worktrees, projetos multi-arquivo, CI/CD com Claude.