@CanalQb no YouTube

Claude Code CLI: Guia Técnico Definitivo 2026

A maioria dos devs configura o Claude Code errado desde o primeiro comando — e nem percebe que está desperdiçando 70% do potencial da ferramenta.

Não é exagero. Durante meses testando o Claude Code em produção — pipelines CI/CD reais, bases de código com mais de 200 mil linhas, integração com GitHub, Sentry e PostgreSQL via MCP — ficou claro que a diferença entre usar a ferramenta de forma casual e dominá-la é entender três camadas: a arquitetura de contexto, o sistema de permissões e os mecanismos de extensão. Quem ignora essas camadas paga mais, obtém menos e ainda acha que o problema é o modelo.

Neste guia, você vai ver o Claude Code como ele realmente funciona em 2026: uma plataforma agentic que lê seu codebase, executa comandos no shell, cria e edita arquivos, delega tarefas para subagentes especializados e conecta serviços externos via protocolo MCP — tudo a partir de um terminal. O objetivo aqui no @CanalQb é entregar a referência que eu gostaria de ter encontrado quando comecei.

Como o Claude Code realmente funciona por dentro?

O Claude Code opera em três camadas independentes. Entender essa arquitetura é o que separa quem usa a ferramenta de quem a domina.

A Camada Core é sua conversa principal. Cada mensagem, cada arquivo lido, cada saída de ferramenta consome contexto de uma janela compartilhada de 200K tokens (1M com plano premium). Quando o contexto enche, o Claude perde o fio das decisões anteriores e a qualidade degrada.

A Camada de Delegação são os Subagentes — instâncias independentes do Claude que iniciam com contexto limpo, executam trabalho focado e retornam apenas o resumo. O resultado da exploração não polui sua conversa principal. Aqui no @CanalQb, validamos que usar subagentes Haiku para exploração reduz o custo total de sessão em até 50%.

A Camada de Extensão reúne MCP (conexão com serviços externos), Hooks (execução determinística de shell), Skills (expertise de domínio) e Plugins (distribuição de tudo isso). Quem trabalha apenas na Camada Core está ignorando os 70% mais poderosos da ferramenta.

┌─────────────────────────────────────────────┐
│         CAMADAS DO CLAUDE CODE              │
├─────────────────────────────────────────────┤
│ EXTENSÃO: MCP | Hooks | Skills | Plugins   │
│ DELEGAÇÃO: Subagentes (até 10 paralelos)   │
│ CORE: Conversa principal + Ferramentas     │
└─────────────────────────────────────────────┘

Como instalar o Claude Code CLI em 2026?

A instalação nativa é o método recomendado — sem dependência de Node.js, sem conflitos de permissão. Funciona em macOS 10.15+, Ubuntu 20.04+/Debian 10+, e Windows 10+ via WSL ou Git Bash.

# macOS e Linux — instalação nativa
curl -fsSL https://claude.ai/install.sh | bash

# macOS via Homebrew
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Verificar instalação
claude doctor

# Atualizar manualmente
claude update

No Alpine Linux e outros sistemas musl, você precisa instalar dependências extras: apk add libgcc libstdc++ ripgrep e exportar USE_BUILTIN_RIPGREP=0.

Qual modelo do Claude Code usar em cada situação?

A escolha do modelo é a decisão financeira mais impactante no uso diário. Uma sessão de desenvolvimento típica consome entre 50K e 200K tokens de entrada. Com Haiku, isso custa entre R$0,50 e R$2,00. Com Opus, a mesma sessão sai entre R$2,50 e R$10,00 — cinco vezes mais caro, sem necessariamente entregar cinco vezes mais valor.

Para trocar o modelo durante uma sessão, use /model opus, /model sonnet ou /model haiku. O modo opusplan usa Opus para planejamento e Sonnet para execução — excelente para refatorações complexas onde você quer o melhor raciocínio no plano, mas não precisa do Opus em cada edição individual.

# Trocar modelo na sessão
/model opus
/model sonnet
/model haiku

# Forçar modelo via variável de ambiente
export ANTHROPIC_MODEL=sonnet

# Definir modelo padrão para subagentes (economiza muito)
export CLAUDE_CODE_SUBAGENT_MODEL=haiku

# Ativar contexto de 1M tokens para projetos grandes
claude --model sonnet[1m]

Como funciona o sistema de permissões do Claude Code?

O sistema de permissões é o que garante que o Claude Code não faça nada que você não autorizou explicitamente. Ferramentas de leitura como Read, Glob e Grep são aprovadas automaticamente. Ferramentas de modificação como Edit, Write e Bash exigem aprovação na primeira execução — a menos que você configure regras explícitas.

A sintaxe de regras de permissão usa prefixo de correspondência. O padrão Bash(npm run test:*) permite npm run test, npm run test:unit e npm run test:integration — mas não npm install. A negação com deny é absoluta: deny tem prioridade sobre qualquer allow.

// .claude/settings.json — configuração recomendada
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(.git/**)"
    ],
    "defaultMode": "acceptEdits"
  }
}

O que são Hooks no Claude Code e por que são superiores a prompts?

Hooks executam comandos shell determinísticos em momentos específicos do fluxo do Claude Code. A diferença fundamental em relação a prompts: prompts são probabilísticos — o Claude pode esquecer, priorizar outra coisa ou julgar que a mudança é pequena demais. Hooks são garantidos — toda edição ou escrita aciona seu formatador, sem exceção.

Para compliance, segurança e padrões de equipe, determinístico bate probabilístico todas as vezes. Se você precisa que o Prettier rode após cada edição de arquivo TypeScript, um hook garante isso. Um prompt apenas sugere.

// .claude/settings.json — hooks essenciais
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Aguardando sua confirmação'"
          }
        ]
      }
    ]
  }
}

Como o protocolo MCP expande o Claude Code além do terminal?

O MCP (Model Context Protocol) é o que transforma o Claude Code de uma ferramenta de arquivos em uma plataforma de integração real. Sem MCP, o Claude lê arquivos e roda bash. Com MCP, ele consulta seu banco de dados de produção, abre issues no GitHub, inspeciona erros no Sentry e interage com qualquer API que sua equipe usa — tudo em linguagem natural.

O ecossistema cresceu de 100 mil downloads totais em novembro de 2024 para mais de 8 milhões em abril de 2025 — crescimento de 80x em cinco meses. Hoje existem mais de 300 integrações disponíveis.

# Adicionar MCP via HTTP (recomendado para serviços remotos)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Adicionar PostgreSQL local via stdio
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Adicionar Sentry com autenticação
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp \
  --header "Authorization: Bearer $SENTRY_API_KEY"

# Listar servidores configurados
claude mcp list

# Gerenciar dentro do REPL
/mcp

// .mcp.json — configuração de projeto (vai para o git)
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    }
  }
}

Com MCP configurado, você faz perguntas como "quais erros ocorreram em produção hoje?" ou "crie um issue no GitHub para esse bug de autenticação" — e o Claude executa direto, sem copiar e colar entre janelas.

Quando usar subagentes para não deixar o contexto principal estourar?

Subagentes são instâncias independentes do Claude que resolvem o maior problema de sessões longas: o bloat de contexto. Quando você pede ao Claude para explorar um codebase enorme, os resultados dessa exploração não precisam ficar na sua conversa principal — só o resumo volta. Isso mantém a janela de contexto limpa e o raciocínio preciso.

O Claude pode rodar até 10 subagentes em paralelo. Um subagente Haiku custa 10 a 20 vezes menos que o Opus para a mesma exploração. Aqui no @CanalQb, o padrão adotado é: Haiku para qualquer tarefa de exploração e leitura, Sonnet para implementação, Opus só quando a complexidade do raciocínio realmente justifica.

---
# .claude/agents/security-reviewer.md
name: security-reviewer
description: Revisor de segurança especializado. Use PROATIVAMENTE após qualquer alteração em autenticação, autorização ou manipulação de dados.
tools: Read, Grep, Glob
model: opus
permissionMode: plan
---

Você é um engenheiro de segurança sênior revisando código para vulnerabilidades.

Quando acionado:
1. Identifique arquivos alterados recentemente
2. Analise para OWASP Top 10
3. Verifique credenciais hardcoded, SQL injection, XSS
4. Reporte com nível de severidade e etapas de correção

Foque em achados acionáveis com referências de linha específicas.

O que são Skills e como elas diferem de slash commands?

Skills são o mecanismo de extensão mais poderoso e menos compreendido do Claude Code. A distinção crítica: slash commands você invoca explicitamente (/security-review). Skills o Claude ativa automaticamente, baseado no contexto da conversa, sem você lembrar de chamar nada.

Você escreve uma skill com as regras de pagamento da sua empresa, os padrões de compliance e as decisões arquiteturais da sua equipe. Quando alguém trabalha em código de transações, o Claude já sabe aplicar esse conhecimento — sem precisar re-explicar a cada sessão.

---
# .claude/skills/code-reviewer/SKILL.md
name: code-reviewer
description: Revisa código para vulnerabilidades de segurança, problemas de performance e violações de boas práticas. Use ao examinar alterações de código, revisar PRs, analisar qualidade, ou quando solicitado a revisar, auditar ou verificar código.
allowed-tools: Read, Grep, Glob
---

# Expertise de Code Review

## Análise de Segurança
- Validação de toda entrada de usuário antes do uso
- Queries parametrizadas para operações de banco
- Encoding de saída para conteúdo renderizado

## Problemas de Performance
- Detecção de N+1 queries
- Índices ausentes em colunas filtradas
- Conjuntos de resultado sem limites

## Formato de Saída
Para cada achado:
- **Arquivo**: caminho/arquivo.ts:linha
- **Severidade**: Crítica | Alta | Média | Baixa
- **Problema**: descrição clara
- **Recomendação**: correção com exemplo de código

Skills ficam em .claude/skills/ (projeto, vai para o git — equipe inteira recebe automaticamente) ou em ~/.claude/skills/ (pessoal, todos os seus projetos). O campo description é o que o Claude usa para decidir quando ativar a skill — seja específico e inclua frases de gatilho.

Como gerenciar contexto e memória para sessões longas?

O arquivo CLAUDE.md na raiz do projeto é a memória persistente entre sessões. O Claude lê esse arquivo no início de cada conversa — é onde ficam convenções do projeto, comandos frequentes, decisões arquiteturais e qualquer contexto que o Claude precisaria re-aprender toda vez.

Use o prefixo # durante a sessão para adicionar notas à memória sem interromper o fluxo: # sempre rodar testes antes de commitar. O comando /compact condensa o histórico de conversa preservando informações-chave — use proativamente quando o contexto passar de 50% da capacidade. Nunca espere estourar.

# Verificar uso de contexto
/context

# Compactar com foco específico
/compact foque nas alterações de autenticação

# Adicionar nota à memória na hora
# o módulo de pagamentos é crítico — não alterar sem testes

# Continuar sessão anterior
claude -c

# Retomar sessão específica por ID
claude -r "feature-auth-1748900000"

# Criar sessão com ID descritivo
claude --session-id "feature-$(git branch --show-current)-$(date +%s)"

Como usar o Claude Code em pipelines de CI/CD?

O modo não-interativo (-p) permite integrar o Claude Code em scripts e pipelines de automação. A saída em JSON viabiliza parsing programático dos resultados — custo, duração, session ID e o conteúdo da resposta chegam estruturados.

# Revisão automática de código com saída JSON
result=$(claude -p "Revise este código para problemas de qualidade" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode plan \
  --max-turns 5)

# Extrair campos
echo "Resultado: $(echo $result | jq -r '.result')"
echo "Custo: $$(echo $result | jq -r '.total_cost_usd')"

# Tarefas assíncronas na nuvem
& Rode todos os testes e corrija falhas encontradas
& Atualize a documentação da API

# Trazer sessão cloud para o terminal local
claude --teleport session_abc123

O prefixo & envia tarefas para o Claude Code Remote — execução na nuvem enquanto você fecha o terminal ou troca de tarefa. O --teleport traz a sessão de volta para seu ambiente local quando você quiser continuar.

Quais os atalhos de teclado essenciais do Claude Code CLI?

Dominar os atalhos transforma o fluxo de trabalho — especialmente em sessões longas onde cada segundo conta.

Conformidade Global: As informações regulatórias neste conteúdo refletem as legislações vigentes no momento da publicação. Este post foi gerado com auxílio de IA conforme a Lei Felca nº 15.211/2025 (Brasil) e o EU AI Act Art. 50. Leis de privacidade variam por jurisdição — consulte o IAPP Global Privacy Directory para verificações específicas. Este conteúdo não constitui aconselhamento jurídico.