Claude Code opera como um sistema agêntico, não como uma interface de chat com conhecimento de programação. O CLI lê sua base de código, executa comandos, modifica arquivos, gerencia fluxos de trabalho do git, conecta-se a serviços externos via MCP e delega tarefas complexas a subagentes especializados. Tudo flui através de uma interface de linha de comando que se integra à forma como desenvolvedores realmente trabalham.

A diferença entre uso casual e uso eficaz do Claude Code se resume a cinco sistemas centrais. Domine-os e o Claude Code se torna um multiplicador de força:

1. Hierarquia de configuração — controla o comportamento
2. Sistema de permissões — controla operações
3. Sistema de hooks — permite automação determinística
4. Protocolo MCP — estende capacidades
5. Sistema de subagentes — lida com tarefas complexas de múltiplas etapas

Passei meses levando o Claude Code aos seus limites em bases de código de produção, pipelines de CI/CD e implantações empresariais. Este guia destila essa experiência na referência abrangente que eu gostaria que existisse quando comecei. Cada recurso inclui sintaxe real, exemplos de configuração reais e os casos extremos que confundem até usuários experientes.

Como o Claude Code Funciona: O Modelo Mental

Antes de explorar os recursos, entenda como a arquitetura do Claude Code molda tudo o que você faz com ele. O sistema opera em três camadas:

┌─────────────────────────────────────────────────────────┐
│                    CAMADAS DO CLAUDE CODE                │
├─────────────────────────────────────────────────────────┤
│  CAMADA DE EXTENSÃO                                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  Ferramentas externas, automação determinística,        │
│  expertise de domínio, extensões empacotadas            │
├─────────────────────────────────────────────────────────┤
│  CAMADA DE DELEGAÇÃO                                     │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (até 10 em paralelo)      │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Contextos isolados para trabalho focado, retorna       │
│  resumos                                                 │
├─────────────────────────────────────────────────────────┤
│  CAMADA PRINCIPAL                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Contexto da Conversa Principal           │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Sua interação primária; contexto limitado; custa       │
│  dinheiro                                                │
└─────────────────────────────────────────────────────────┘

Camada Principal: Sua conversa principal. Cada mensagem, leitura de arquivo e saída de ferramenta consome contexto de uma janela compartilhada de 200K tokens (1M com premium). Quando o contexto enche, o Claude perde o controle das decisões anteriores e a qualidade degrada. Esta camada custa dinheiro por token.

Camada de Delegação: Subagents são criados com contextos limpos, fazem trabalho focado e retornam resumos. Os resultados da exploração não inflam sua conversa principal—apenas as conclusões retornam. Use subagents Haiku para exploração (barato, rápido) e Sonnet para implementação.

Camada de Extensão: MCP conecta serviços externos (bancos de dados, GitHub, Sentry). Hooks garantem a execução de comandos shell independentemente do comportamento do modelo. Skills codificam expertise de domínio que o Claude aplica automaticamente. Plugins empacotam tudo isso para distribuição.

O insight principal: A maioria dos usuários trabalha inteiramente na Camada Principal, observando o contexto inflar e os custos subirem. Usuários avançados direcionam a exploração e o trabalho especializado para a Camada de Delegação, mantêm a Camada de Extensão configurada para seu fluxo de trabalho e usam a Camada Principal apenas para orquestração e decisões finais.

Índice

1. Como Instalo o Claude Code?
2. Modos de Interação Principais
3. Sistema de Configuração em Detalhes
4. Qual Modelo Devo Escolher?
5. Como Funciona o Sistema de Permissões?
6. Como os Hooks Funcionam?
7. O Que É MCP (Model Context Protocol)?
8. O Que São Subagents?
9. O Que É o Modo Extended Thinking?
10. Estilos de Saída
11. Slash Commands
12. Como as Skills Funcionam?
13. Sistema de Plugins
14. Como a Memória Funciona?
15. Entrada de Imagem e Multimodal
16. Como Funciona a Integração com Git?
17. Como Uso o Claude Code na Minha IDE?
18. Padrões de Uso Avançado
19. O Que É o Claude Code Remote?
20. O Que São Background Agents?
21. Claude in Chrome
22. Claude Code in Slack
23. Quanto Custa o Claude Code?
24. Otimização de Performance
25. Como Depuro Problemas?
26. Implantação Empresarial
27. Referência de Atalhos de Teclado
28. Boas Práticas

Como Instalo o Claude Code?

Requisitos do Sistema

O Claude Code roda em macOS 10.15+, Ubuntu 20.04+/Debian 10+ e Windows 10+ através de WSL ou Git Bash. O sistema requer no mínimo 4 GB de RAM e uma conexão ativa com a internet. A compatibilidade de shell funciona melhor com Bash, Zsh ou Fish.

Para Windows, tanto WSL 1 quanto WSL 2 funcionam. Git Bash também funciona se você preferir Windows nativo. Alpine Linux e outros sistemas baseados em musl requerem pacotes adicionais:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Métodos de Instalação

Instalação nativa (recomendado)

O binário nativo proporciona a experiência mais limpa sem dependência de Node.js:

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

# Homebrew alternative
brew install --cask claude-code

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

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Para instalação de versão específica:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Instalação via NPM (obsoleta)

Nota: A partir da v2.1.15, instalações via npm mostram um aviso de obsolescência. O binário nativo é agora o método de instalação recomendado. Migre com claude install.

Para ambientes legados onde npm ainda é necessário:

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

Nunca use sudo com instalação npm—isso cria problemas de permissão que complicam tudo posteriormente.

Migração de instalação existente

Se você tem uma instalação mais antiga baseada em npm, migre para o binário nativo:

claude install

Opções de Autenticação

O Claude Code suporta três caminhos de autenticação, cada um com diferentes trade-offs:

Claude Console (cobrança via API)

Conecte-se diretamente à API da Anthropic através do platform.claude.com (anteriormente console.anthropic.com). Crie uma conta, configure a cobrança e autentique através da CLI. Isso fornece cobrança baseada em uso com acesso completo à API. Um workspace dedicado “Claude Code” é criado automaticamente—você não pode criar chaves de API para este workspace, mas pode monitorar o uso.

Assinatura Claude Pro ou Max

Use suas credenciais da conta claude.ai. A assinatura cobre tanto a interface web quanto o uso da CLI em um único plano mensal. Isso simplifica a cobrança para usuários individuais que querem custos previsíveis.

Plataformas empresariais

AWS Bedrock, Google Vertex AI e Microsoft Foundry oferecem acesso de nível empresarial com relacionamentos de cobrança de nuvem existentes:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

Para implantações empresariais atrás de proxies ou através de gateways LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Verificação

claude doctor

Isso reporta o tipo de instalação, versão, configuração do sistema e quaisquer problemas detectados.

Atualizações

O Claude Code atualiza automaticamente por padrão, verificando na inicialização e periodicamente durante as sessões. As atualizações são baixadas em segundo plano e aplicadas na próxima execução.

Desabilitar atualizações automáticas:

export DISABLE_AUTOUPDATER=1

Ou em settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Atualização manual:

claude update

Desinstalação

Instalação nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalação nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Limpar configuração (remove todas as configurações):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Modos de interação principais

REPL interativo

Inicie o Claude Code sem argumentos para entrar no loop interativo de leitura-avaliação-impressão (REPL):

cd your-project
claude

O REPL mantém o contexto da conversa entre as interações. Digite suas consultas diretamente, receba respostas e continue até sair com /exit ou Ctrl+D.

Comece com um prompt inicial para direcionar a sessão:

claude "explain the authentication flow in this project"

Dica avançada: O REPL preserva o estado entre eventos de compactação. Quando o contexto cresce demais, o Claude automaticamente resume a conversa mais antiga, preservando decisões-chave e trechos de código. Você pode acionar isso manualmente com /compact ou adicionar instruções personalizadas sobre o que preservar.

Modo não interativo

O modo de impressão (-p) executa uma única consulta e encerra:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Para saída estruturada adequada para análise em scripts:

claude -p "count lines by file type" --output-format json

A saída JSON inclui tudo o que você precisa para automação:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Para processamento em tempo real de saída em streaming:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r '.result // empty'
done

Gerenciamento de sessões

As sessões persistem o histórico da conversa para continuação. Isso é essencial para trabalhos complexos em múltiplas sessões:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Crie sessões reproduzíveis com IDs explícitos:

claude --session-id "feature-auth-$(date +%s)"

Dica avançada: Use IDs de sessão que codifiquem contexto: feature-${branch}-${timestamp} ou bug-JIRA-123. Quando você voltar dias depois, o ID indica sobre o que era a sessão. Visualize as sessões disponíveis dentro do REPL usando /resume.

As sessões são armazenadas como transcrições JSONL. A execução do agente recebe valores únicos de agentId com transcrições armazenadas como agent-{agentId}.jsonl. A retomada preserva o contexto completo das conversas anteriores.

Sessões nomeadas (dez. 2025): Nomeie e gerencie sessões com mais facilidade:

# Name current session
> /rename my-feature-work

# Resume by name or number
> /resume 1                    # Resume first session
> /resume my-feature-work      # Resume by name
claude --resume 3              # Resume from terminal

# Fork with custom session ID
claude --session-id "new-exploration" --resume "base-session" --fork-session

Aprofundamento no sistema de configuração

O Claude Code usa um sistema de configuração em camadas. Entender a hierarquia é essencial porque níveis superiores sobrescrevem os inferiores, e as configurações corporativas não podem ser contornadas de forma alguma.

Hierarquia de configuração

Dica avançada: Use .claude/settings.local.json para preferências pessoais em projetos compartilhados — ele deve estar no .gitignore. Use .claude/settings.json para configurações da equipe que são versionadas no controle de versão.

Referência completa do settings.json

Uma configuração abrangente demonstrando todas as opções principais:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"]
}

Referência de variáveis de ambiente

Autenticação e API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Configuração de modelo:

ANTHROPIC_MODEL=claude-opus-4-5                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5-20251101
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929-v1:0
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length

Configuração de provedores de nuvem:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Controle de comportamento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls

Configuração de ferramentas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Rede e proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

Interface e terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]

Depuração:

ANTHROPIC_LOG=debug                             # Enable API request logging

Qual Modelo Devo Escolher?

Escolher o modelo certo para cada tarefa impacta significativamente tanto o custo quanto a qualidade. O Claude Code oferece troca flexível de modelos em múltiplos níveis.

Modelos Disponíveis

Por que essas diferenças de preço importam: Uma sessão típica de codificação consome 50K-200K tokens de entrada e 10K-50K tokens de saída. Com o Haiku, isso custa $0,10-$0,45 por sessão. Com o Opus, a mesma sessão custa $0,50-$2,25—5x mais. Reserve o Opus para problemas genuinamente difíceis.¹

Quando Usar Cada Modelo

Haiku: Use para subagents fazendo exploração, buscas simples de arquivos, perguntas rápidas. É 10-20x mais barato que o Opus e responde mais rápido. Perfeito para tarefas em segundo plano onde você não precisa de raciocínio profundo.

Sonnet: O cavalo de batalha para desenvolvimento diário. Lida bem com a maioria das tarefas de codificação: implementar funcionalidades, corrigir bugs, escrever testes, revisão de código. Use este como seu padrão.

Opus: Reserve para raciocínio genuinamente complexo: decisões arquiteturais, debugging complicado, compreensão de sistemas complexos, análise de segurança. A diferença de qualidade é real para problemas difíceis, mas o custo também. O Opus 4.5 alcança 80,9% no SWE-bench Verified enquanto reduz o uso de tokens pela metade comparado aos predecessores.⁴⁵ Nota: Usuários com assinatura Pro agora têm acesso ao Opus 4.5 como parte de sua assinatura.²⁰

Opusplan: Um modo híbrido que usa Opus para planejamento (onde a qualidade do raciocínio mais importa) e Sonnet para execução (onde a velocidade importa). Excelente para refatoração complexa onde você quer o melhor plano, mas não precisa de raciocínio nível Opus para cada edição individual.

Trocando de Modelos

Durante a sessão:

> /model opus
> /model sonnet
> /model haiku

Na inicialização:

claude --model opus

Via variável de ambiente:

export ANTHROPIC_MODEL=opus

Em settings.json:

{
  "model": "claude-sonnet-4-5-20250929"
}

Para subagents especificamente:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexto Estendido

Para grandes bases de código ou sessões longas, habilite o contexto de 1M de tokens:

claude --model sonnet[1m]

Ou dentro de uma sessão:

> /model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]

Contexto estendido custa mais por token. Use quando você realmente precisar, não como padrão.

Verificando o Modelo Atual

> /status

Isso mostra o modelo atual, informações da conta, configurações aplicadas e outros estados da sessão.

Frameworks de Decisão

Saber que recursos existem não é suficiente—você precisa saber quando usar cada um. Essas árvores de decisão transformam conhecimento em ação.

Qual Modelo Devo Usar?

INÍCIO → A tarefa é simples? (busca de arquivo, pergunta rápida, formatação)
         │
         ├── SIM → Use Haiku
         │         Custo: ~$0,03/tarefa
         │         Velocidade: Mais rápido
         │
         └── NÃO → Requer raciocínio profundo?
                  (arquitetura, debugging complexo, análise de segurança)
                  │
                  ├── SIM → Use Opus
                  │         Custo: ~$2,00/tarefa
                  │         Qualidade: Mais alta
                  │
                  └── NÃO → Use Sonnet (padrão)
                           Custo: ~$0,75/tarefa
                           Equilíbrio: Melhor no geral

Regra geral: Comece com Sonnet. Desça para Haiku para subagents. Escale para Opus apenas quando a resposta do Sonnet parecer superficial.

Comando vs Skill vs Subagent?

Você quer controle explícito sobre quando ele executa?
│
├── SIM → Use Slash Command
│         Exemplo: /deploy, /test, /security-review
│         Você invoca. Você controla o timing.
│
└── NÃO → A expertise deve ser aplicada automaticamente baseada no contexto?
         │
         ├── SIM → Use Skill
         │         Exemplo: Padrões de segurança, regras de domínio, padrões de código
         │         O Claude reconhece o contexto e aplica a expertise.
         │
         └── NÃO → O trabalho precisa de contexto isolado?
                  │
                  ├── SIM → Use Subagent
                  │         Exemplo: Exploração profunda, análise paralela
                  │         Previne sobrecarga de contexto na conversa principal.
                  │
                  └── NÃO → Apenas faça o prompt diretamente
                           Nem tudo precisa de abstração.

Hook vs Prompt?

A ação DEVE acontecer SEMPRE, independente do julgamento do Claude?
│
├── SIM → Use Hook (determinístico)
│         Exemplos:
│         - Formatar código após cada edição
│         - Registrar todos os comandos bash
│         - Bloquear acesso a arquivos .env
│         O Claude não pode pular, esquecer ou decidir diferente.
│
└── NÃO → Use Prompt (probabilístico)
         Exemplos:
         - "Considere adicionar testes"
         - "Pense nos casos extremos"
         - "Revise por segurança se relevante"
         O Claude decide baseado no contexto.

Quando Usar Extended Thinking?

Este é um problema genuinamente difícil?
│
├── Decisão arquitetural com muitos tradeoffs → SIM, use thinking
├── Debugging complexo com causa raiz incerta → SIM, use thinking
├── Análise de segurança requerendo raciocínio cuidadoso → SIM, use thinking
├── Entendendo base de código desconhecida → SIM, use thinking
│
├── Correção de bug rotineira → NÃO, pule thinking
├── Refatoração simples → NÃO, pule thinking
├── Formatação de código → NÃO, pule thinking
└── Perguntas rápidas → NÃO, pule thinking

Alterne com Tab durante a sessão. Orçamentos de thinking mais altos custam mais—comece com o mínimo e aumente apenas se as respostas parecerem apressadas.

Como o Sistema de Permissões Funciona?

O sistema de permissões do Claude Code fornece controle granular sobre quais operações podem ser executadas. Entendê-lo é essencial tanto para segurança quanto para eficiência do fluxo de trabalho.

Níveis de Permissão

Ferramentas somente leitura (aprovação automática): - Read - Ler conteúdo de arquivos - Glob - Encontrar arquivos por padrão - Grep - Buscar conteúdo em arquivos - WebSearch - Buscar na web - LSP - Inteligência de código (ir para definição, encontrar referências, documentação ao passar o mouse)²⁵

Capacidades da ferramenta LSP (v2.0.74+): A ferramenta LSP fornece inteligência de código similar a uma IDE: - Ir para definição: Pular para onde um símbolo é definido - Encontrar referências: Listar todos os usos de um símbolo na base de código - Documentação ao passar o mouse: Obter informações de tipo e documentação para qualquer símbolo - Funciona com TypeScript, Python, Go, Rust e outras linguagens com suporte a LSP - Requer que o language server esteja disponível (tipicamente instalado com seu toolchain)

Ferramentas de modificação (requerem aprovação): - Edit - Modificar arquivos existentes - Write - Criar novos arquivos - Bash - Executar comandos shell - WebFetch - Buscar conteúdo de URLs - NotebookEdit - Modificar notebooks Jupyter

Na primeira vez que uma ferramenta de modificação é executada, o Claude Code solicita aprovação. As aprovações persistem pela sessão a menos que configurado explicitamente de outra forma.

Modos de Permissão

Modo YOLO (v2.0.68+): Para operação totalmente autônoma, use a flag --dangerously-skip-permissions. Isso diz sim para tudo—edições de arquivo, comandos bash, todas as chamadas de ferramentas. A palavra “dangerous” é intencional. Use em ambientes sandboxed ou quando você confia totalmente na base de código.⁶¹

claude --dangerously-skip-permissions

Defina o modo via CLI:

claude --permission-mode acceptEdits

Alterne durante a sessão:

Shift+Tab  # Cicla entre os modos

Em settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Sintaxe de Regras de Permissão

Regras granulares controlam operações específicas. As regras são avaliadas em ordem: a primeira correspondência vence.

Padrões de comandos Bash:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

O asterisco fornece correspondência de prefixo: Bash(npm run test:*) permite npm run test, npm run test:unit e npm run test:integration.

Limitação importante: Padrões Bash correspondem apenas prefixos, não regex. Um padrão como Bash(curl http:*) não vai corresponder a curl -X GET http://... porque as opções vêm antes da URL. Para bloqueio robusto, negue o comando inteiramente: Bash(curl:*).

Padrões de operações de arquivo:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Sintaxe de caminho: - Caminhos relativos: Edit(src/**) - relativo ao diretório de trabalho - Absoluto do arquivo de configurações: Edit(/build/**) - relativo à localização do arquivo de configurações - Verdadeiramente absoluto: Edit(//tmp/**) - começa com // - Diretório home: Read(~/.zshrc)

Padrões de ferramentas MCP:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Use a sintaxe de curinga mcp__server__* para permitir ou negar todas as ferramentas de um servidor MCP específico.³⁹ Isso é útil para habilitar rapidamente todas as ferramentas de servidores confiáveis ou bloquear servidores inteiros de fontes não confiáveis.

Padrões WebFetch:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Diretórios Adicionais

Estenda o acesso do Claude além do projeto atual:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Isso é essencial para monorepos ou quando o Claude precisa referenciar código em diretórios irmãos.

Modo Sandbox

Habilite isolamento de sistema de arquivos e rede:

> /sandbox

Ou configure nas configurações:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

Quando em sandbox: - Acesso ao sistema de arquivos restrito ao diretório do projeto - Acesso à rede controlado - Certos comandos excluídos das restrições do sandbox - Comandos Bash aprovados automaticamente se autoAllowBashIfSandboxed for true

Dica de especialista: O modo sandbox é excelente para executar o Claude em bases de código não confiáveis. Habilite-o ao explorar projetos desconhecidos ou quando você quiser uma camada extra de proteção. Testes internos da Anthropic descobriram que o sandboxing reduz as solicitações de permissão em 84%.⁴⁵

Como os Hooks Funcionam?

Hooks executam comandos shell determinísticos em pontos específicos do fluxo de trabalho do Claude Code. Diferentemente de solicitar que o Claude execute ações, hooks garantem a execução independentemente do comportamento do modelo. Eles são essenciais para aplicar padrões da equipe e automatizar tarefas repetitivas.

Por que hooks em vez de prompts: Dizer ao Claude “sempre execute o Prettier após editar arquivos” funciona às vezes. Mas o Claude pode esquecer, priorizar velocidade ou decidir que a alteração é “muito pequena.” Hooks garantem a execução—cada Edit ou Write aciona seu formatador, sempre, sem exceções. Para conformidade, segurança e padrões da equipe, determinístico supera probabilístico.⁷

Eventos Disponíveis

Configuração de Hooks

Defina hooks em settings.json ou em um hooks.json dedicado:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

O campo matcher determina quais ferramentas acionam um hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Protocolo de Entrada/Saída de Hooks

Hooks recebem JSON no stdin:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Códigos de saída controlam o comportamento: - 0: Sucesso—a operação prossegue. Stdout é exibido no modo verbose (Ctrl+O). Para UserPromptSubmit e SessionStart, stdout é adicionado ao contexto. - 2: Erro bloqueante—a operação para. Stderr se torna a mensagem de erro enviada de volta ao Claude. - 1, 3, etc.: Erro não bloqueante—a operação continua. Stderr é exibido como aviso no modo verbose.

Para controle avançado, hooks podem retornar JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Hooks PreToolUse com permissão ask (v2.1.0+): Hooks PreToolUse agora podem retornar updatedInput ao usar a decisão de permissão “ask”, permitindo que hooks atuem como middleware enquanto ainda solicitam consentimento do usuário.³⁹

{
  "decision": "ask",
  "message": "Modified command requires approval",
  "updatedInput": {
    "command": "npm test -- --coverage --ci"
  }
}

Hooks PreToolUse com additionalContext (v2.1.9+): Hooks podem injetar contexto no modelo retornando additionalContext. Isso é útil para fornecer informações dinâmicas (documentação de API, schemas de banco de dados, estado do ambiente) que o modelo deve considerar.⁵¹

{
  "decision": "allow",
  "additionalContext": "Note: This database has a 5-second query timeout. Complex joins may need optimization."
}

A string additionalContext é anexada ao contexto do modelo para aquele turno, tornando-a disponível para raciocínio sem modificar permanentemente a conversa.

Exemplos Práticos de Hooks

Auto-formatar arquivos TypeScript após edição:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Registrar todos os comandos bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Bloquear acesso a arquivos sensíveis:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 1
fi
exit 0

Executar testes após alterações no código:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Sistema de notificação personalizado:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Injetar contexto dinâmico nos prompts:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Depuração de Hooks

Ative o modo debug para solucionar problemas com hooks:

claude --debug

Isso registra: - Tempos de execução dos hooks - Dados de entrada/saída - Mensagens de erro e stack traces - Resultados de decisão (allow/reject/ask)

Hooks com Escopo de Componente (v2.1.0+)

Hooks podem ser definidos diretamente em Skills, subagents e slash commands usando frontmatter. Esses hooks têm escopo para o ciclo de vida do componente e só são executados quando aquele componente está ativo.⁴¹

Skill com hooks incorporados:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Eventos suportados: PreToolUse, PostToolUse, Stop

A opção once (apenas para skills e slash commands) garante que o hook seja executado apenas uma vez por sessão—útil para tarefas de limpeza ou finalização.

Estratégia para Sessões de Longa Duração

Para sessões do Claude Code durante a noite ou sem supervisão, configure hooks para manter o Claude no caminho certo sem intervenção manual. O insight principal: use hooks de linting e testes como barreiras de proteção que forçam o Claude a corrigir problemas antes de continuar.⁶⁴

O Padrão “Não Pare Até os Testes Passarem”:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Estratégia para sessões durante a noite:

1. Verificação pré-voo: Use um hook Setup para verificar se o ambiente está pronto
2. Validação contínua: Hooks PostToolUse executam testes após cada alteração
3. Portão de conclusão: Hooks Stop verificam todos os critérios de aceitação antes do Claude declarar “concluído”
4. Notificação: Hooks Stop podem notificá-lo via Slack/Pushover quando o Claude terminar ou ficar travado

Combine com --dangerously-skip-permissions em um container isolado para execuções totalmente autônomas durante a noite. O Claude continuará iterando até os testes passarem ou esgotar suas opções.

O que é MCP (Model Context Protocol)?

MCP estende o Claude Code com acesso a ferramentas externas, bancos de dados, APIs e serviços por meio de um protocolo padronizado. O ecossistema cresceu exponencialmente: o MCP agora tem 100 milhões de downloads mensais e mais de 3.000 servidores indexados no MCP.so (janeiro de 2026), consolidando sua posição como o padrão da indústria para conectar IA a ferramentas e dados.³⁵⁴ Compreender o MCP é essencial para integrar o Claude à sua cadeia de ferramentas existente.

Por que o MCP é importante para desenvolvedores: Sem o MCP, o Claude Code só pode ler arquivos e executar comandos bash. Com o MCP, o Claude pode consultar seu banco de dados de produção, criar tickets no Jira, revisar PRs no GitHub, verificar erros no Sentry e interagir com qualquer API que sua equipe utiliza — tudo a partir de solicitações em linguagem natural. O protocolo padroniza como ferramentas de IA se conectam a serviços externos, prevenindo dependência de fornecedor.

Suporte a MCP remoto (junho de 2025)

O Claude Code agora suporta servidores MCP remotos com autenticação OAuth nativa.²⁸ Conecte-se a ferramentas e fontes de dados sem gerenciar servidores locais — basta autenticar uma vez e o Claude Code cuida da atualização de tokens automaticamente.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

MCP Tool Search (v2.1.7+)

À medida que os servidores MCP cresceram em capacidade (alguns expondo mais de 50 ferramentas), as descrições de ferramentas começaram a consumir contexto excessivo. O MCP Tool Search resolve isso carregando dinamicamente as descrições de ferramentas apenas quando necessário — uma forma de carregamento sob demanda para ferramentas de IA.⁵⁴

Impacto no desempenho: Benchmarks internos mostram melhorias drásticas na precisão: - Opus 4: 49% → 74% em avaliações MCP - Opus 4.5: 79,5% → 88,1% em avaliações MCP - Redução de overhead de tokens: 85%

Como funciona: Quando as descrições de ferramentas MCP excedem 10% da janela de contexto (limite padrão), o Claude Code adia o carregamento das descrições completas até que sejam realmente necessárias. O Claude vê os nomes das ferramentas, mas busca as descrições sob demanda.

Configuração:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Valores: - true - Sempre habilitar a busca de ferramentas - false - Sempre desabilitar (carregar todas as descrições de ferramentas antecipadamente) - auto:N - Habilitar quando as ferramentas excederem N% do contexto (0-100)

Dica avançada: Com o Tool Search habilitado, você pode conectar muito mais servidores MCP sem se preocupar com limites de contexto. A redução de 95% no contexto significa que servidores que antes competiam por contexto agora coexistem sem problemas.

Assistente interativo de configuração MCP

Execute claude mcp add sem argumentos para iniciar uma interface passo a passo para adicionar servidores MCP. O assistente guia você pela seleção do tipo de transporte, autenticação e configuração.¹⁵

Tipos de transporte

HTTP (recomendado para servidores remotos):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (descontinuado, mas funcional):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (servidores locais):

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

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

O Windows requer um wrapper cmd para stdio:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Gerenciamento de escopo

Os servidores MCP existem em três escopos com precedência clara (local sobrepõe projeto, que sobrepõe usuário):

Especifique o escopo durante a instalação:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Formato do arquivo de configuração

O arquivo .mcp.json define os servidores em nível de projeto:

{
  "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}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

As variáveis de ambiente são expandidas usando a sintaxe ${VAR} com valores padrão opcionais: ${VAR:-default}.

Comandos de gerenciamento MCP

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

Autenticação OAuth

Para servidores que exigem OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Usando recursos e prompts MCP

Referenciar recursos:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

Prompts MCP como comandos slash:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Limites de saída

A saída do MCP é limitada para evitar estouro de contexto: - Limite de aviso: 10.000 tokens - Máximo padrão: 25.000 tokens

Aumente se necessário:

export MAX_MCP_OUTPUT_TOKENS=50000

Servidores MCP populares

Padrões práticos de MCP

Fluxo de trabalho GitHub:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Consultas ao banco de dados:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Monitoramento de erros:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

Configuração MCP empresarial

Administradores de sistema podem aplicar políticas MCP via managed-mcp.json:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Localização: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

A lista de bloqueio tem precedência absoluta. Os comandos devem corresponder exatamente, incluindo a ordem dos argumentos.

MCP Apps (janeiro de 2026)

A Anthropic lançou o MCP Apps, uma extensão do Model Context Protocol que permite interfaces interativas de ferramentas diretamente dentro da interface do Claude.⁷⁸ O MCP Apps permite que os usuários visualizem, editem e interajam com conteúdo de serviços externos sem sair do Claude — incluindo Asana, Box, Canva, Figma, Hex, monday.com e Slack. Qualquer servidor MCP pode fornecer uma interface interativa que é renderizada dentro do Claude. Embora o MCP Apps atualmente apareça na interface web do claude.ai, as extensões do protocolo MCP subjacente são relevantes para o ecossistema MCP do Claude Code à medida que os servidores adotam as novas capacidades interativas.

Plataforma de API: Code Execution Tool v2 (janeiro de 2026)

A Anthropic lançou a v2 do Code Execution Tool em beta público, substituindo o sandbox original exclusivo para Python por execução de comandos Bash e manipulação direta de arquivos.⁷⁹ Principais mudanças: - Executar comandos Bash (não apenas Python) em contêineres isolados - Escrever e executar código em qualquer linguagem - Chamada programática de ferramentas (também em beta público): o Claude pode chamar ferramentas de dentro da execução de código, reduzindo latência e uso de tokens em fluxos de trabalho com múltiplas ferramentas

Isso afeta principalmente usuários da API, mas sinaliza a direção para as capacidades de execução em nuvem do Claude Code.

O Que São Subagents?

Subagents são instâncias especializadas do Claude que lidam com tarefas complexas de forma independente. Eles são um dos recursos mais poderosos do Claude Code e um dos menos compreendidos. Dominar subagents expande dramaticamente o que você pode realizar.

Por que subagents existem: A conversa principal do Claude Code tem uma única janela de contexto. Tudo o que você discute, cada arquivo que o Claude lê, cada saída de ferramenta—tudo consome esse contexto. Em sessões longas, o contexto se esgota, o Claude perde o controle de decisões anteriores e o desempenho degrada. Subagents resolvem isso isolando o trabalho: resultados de exploração não inflam sua conversa principal, apenas o resumo retorna. O Claude também pode executar até 10 subagents em paralelo, permitindo trabalho concorrente que seria impossível sequencialmente.²

Como Subagents Funcionam

Quando o Claude encontra uma tarefa que se beneficia de atenção focada—exploração profunda, análise em múltiplas etapas, trabalho especializado—ele pode gerar um subagent. O subagent:

1. Começa com um contexto limpo (sem poluição da conversa principal)
2. Tem acesso a ferramentas especificadas
3. Opera com um modelo específico (frequentemente mais barato/rápido)
4. Retorna resultados para a conversa principal

Essa arquitetura previne overflow de contexto enquanto permite workflows complexos.

Tipos de Subagent Integrados

Explore (rápido, somente leitura): - Modelo: Haiku (ultra-rápido) - Modo: Estritamente somente leitura - Ferramentas: Glob, Grep, Read e comandos bash seguros (ls, git status, git log, git diff, find, cat, head, tail) - Níveis de profundidade: Quick, Medium, Very thorough - Use para: Exploração de codebase, encontrar arquivos, entender estrutura

General-purpose: - Modelo: Sonnet - Modo: Leitura/escrita completa - Ferramentas: Todas as ferramentas disponíveis - Use para: Tarefas complexas de pesquisa + modificação

Plan: - Modelo: Sonnet (ou Opus com opusplan) - Modo: Somente leitura - Ferramentas: Read, Glob, Grep, Bash - Use para: Planejar implementações complexas antes da execução

Acionando Subagents

O Claude automaticamente delega para subagents com base no tipo de tarefa. Você também pode solicitá-los explicitamente:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

Dica de especialista: Para tarefas complexas, solicite explicitamente a delegação para subagent. “Use an explore agent to find…” previne inchaço de contexto na sua conversa principal.

Criando Subagents Personalizados

Defina subagents em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Campos de configuração:

Gerenciando Subagents

> /agents                    # Gerenciamento interativo
> /agents create             # Criar novo subagent
> /agents edit               # Modificar existente
> /agents delete             # Remover subagent
> /agents list               # Ver todos

Executando Agents em Background

Para tarefas de longa duração:

> Run a thorough security review in the background

> /agents  # Check status of running agents

Recupere os resultados depois com o ID do agent.

Padrões Avançados

Subagents encadeados:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Exploração paralela:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Agents retomáveis: Agents podem ser retomados com seu ID para continuar trabalho anterior:

> Resume agent abc123 and continue the analysis

Subagents Assíncronos (Dezembro 2025)

Subagents assíncronos permitem multitarefa e execução paralela para projetos de grande escala:

> Run security review in the background while I continue frontend work
> /tasks                    # Check status of running agents

Agents assíncronos retornam resultados via TaskOutputTool unificado, permitindo workflows eficientes estilo pipeline.

Resiliência a Negação de Permissão (v2.1.0+)

A partir da v2.1.0, subagents continuam trabalhando após negações de permissão em vez de parar completamente. Quando um subagent encontra uma barreira de permissões, ele tenta abordagens alternativas automaticamente. Isso torna workflows autônomos mais resilientes e reduz a necessidade de intervenção humana.⁴⁷

Agent Skills (Dezembro 2025)

Agent Skills são pastas organizadas de instruções, scripts e recursos que agents descobrem e carregam dinamicamente.³¹ Eles fornecem expertise de domínio composável e portátil:

.claude/skills/
├── security-review/
│   ├── skill.md           # Instructions and prompts
│   ├── checklist.md       # Security checklist
│   └── common-vulns.sh    # Detection scripts
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Skills diferem de comandos: comandos são invocados explicitamente, enquanto skills se auto-ativam com base no contexto da tarefa. O Claude Agent SDK (renomeado de Claude Code SDK) fornece a estrutura para construir agents personalizados com suporte a skills.³²

O Que É o Modo Extended Thinking?

Extended thinking dá ao Claude mais tempo para raciocinar através de problemas complexos antes de responder. É particularmente valioso para decisões arquiteturais, depuração de problemas difíceis e tarefas que requerem análise cuidadosa.

Estado Atual (Janeiro 2026)

Extended thinking agora está habilitado por padrão com um orçamento de 31.999 tokens—o orçamento máximo que anteriormente era acionado por “ultrathink”.⁷⁰ Essa mudança foi feita porque extended thinking melhora significativamente o desempenho em tarefas complexas de planejamento e raciocínio.

Importante: Gatilhos em linguagem natural como “think”, “think hard”, “think harder” e “ultrathink” não funcionam mais. Essas palavras-chave agora são interpretadas como instruções regulares de prompt e não alocam tokens de pensamento. O orçamento de pensamento é controlado exclusivamente pela variável de ambiente MAX_THINKING_TOKENS ou via /config.⁷⁰

Modelos Suportados

• Claude Opus 4.5
• Claude Sonnet 4.5
• Claude Haiku 4.5

Controlando Extended Thinking

Alternar rapidamente durante a sessão:

Press Alt+T to toggle thinking on/off

Nota: O toggle de thinking foi alterado de Tab para Alt+T para evitar acionamentos acidentais.³⁹

Via /config: Navegue até /config → Extended Thinking para habilitar/desabilitar ou ajustar orçamento.

Variável de ambiente (permanente):

# Set custom budget (default is 31,999)
export MAX_THINKING_TOKENS=8000
claude

# Double the default for complex tasks
export MAX_THINKING_TOKENS=63999
claude

Desabilitar para economia de custos: Para tarefas mais simples onde raciocínio profundo não é necessário, você pode reduzir custos desabilitando thinking em /config ou diminuindo o orçamento:

export MAX_THINKING_TOKENS=8000  # Reduce from default 31,999

Orçamentos de Token de Pensamento

Consideração de custo: Tokens de pensamento são cobrados como tokens de saída. O orçamento padrão de 31.999 funciona bem para a maioria das tarefas, mas para operações simples você pode economizar custos reduzindo o orçamento ou desabilitando thinking completamente.

Como Funciona

Quando thinking está habilitado, a resposta do Claude inclui raciocínio interno que não é mostrado na saída mas influencia a resposta. O pensamento é criptografado e retornado em um campo signature para verificação.

Em conversas de múltiplos turnos com uso de ferramentas, blocos de pensamento devem ser passados de volta para a API para preservar a continuidade do raciocínio. O Claude Code lida com isso automaticamente.

Quando Considerar Desabilitar/Reduzir

Extended thinking agora é o padrão, mas considere reduzir o orçamento ou desabilitar para: - Edições simples de arquivo - Refatoração rotineira - Perguntas rápidas - Formatação de código - Operações de alto volume onde os custos se acumulam

Comportamento de Cache

O cache de system prompt é preservado quando parâmetros de thinking mudam. O cache de mensagens é invalidado quando o orçamento ou status de habilitação do thinking muda entre turnos.

Estilos de Saída

Estilos de saída personalizam como o Claude apresenta informações—útil para aprendizado, documentação ou preferências específicas da equipe.¹⁹

Estilos Integrados

Definindo Estilo de Saída

> /output-style Explanatory
> /output-style Learning

Ou via configurações:

{
  "outputStyle": "Explanatory"
}

Estilos de Saída Personalizados

Crie em .claude/styles/:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

Invoque com /output-style my-style.

Comandos Slash

Os comandos slash fornecem acesso rápido aos recursos do Claude Code e permitem fluxos de trabalho personalizados. Eles são mais rápidos do que digitar prompts completos para operações comuns.

Referência de Comandos Integrados

Criação de Comandos Personalizados

Crie comandos reutilizáveis em .claude/commands/ (projeto) ou ~/.claude/commands/ (pessoal):

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

Salve como .claude/commands/security-review.md, invoque com /security-review.

Opções de Frontmatter do Comando

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---

Interpolação de Argumentos

Todos os argumentos como string única:

---
description: Fix GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

Uso: /fix-issue 123

Argumentos numerados:

---
description: Create component
argument-hint: [name] [type]
---

Create a new $2 component named $1 in src/components/.

Uso: /create-component Button functional

Execução de Bash Inline

Execute comandos bash dentro de prompts de comando:

---
description: Git status summary
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`
Changed files: !`git status --short`

Summarize the current state of this repository.

Referências de Arquivo

Inclua conteúdos de arquivo nos comandos:

---
description: Compare implementations
---

Compare these files:
@src/v1/handler.ts
@src/v2/handler.ts

Which implementation is more maintainable?

Namespacing de Comandos

Organize comandos em subdiretórios:

.claude/commands/
├── backend/
│   ├── test.md
│   └── deploy.md
├── frontend/
│   ├── test.md
│   └── build.md
└── review.md

Comandos com o mesmo nome mostram seu namespace na ajuda: /test (project:backend) vs /test (project:frontend).

Como Funcionam as Skills?

Skills representam uma abordagem fundamentalmente diferente para estender o Claude Code. Diferente dos comandos slash que você invoca explicitamente, skills são invocadas pelo modelo—o Claude automaticamente descobre e usa com base no contexto. Você incorpora expertise de domínio em uma skill, e o Claude utiliza essa expertise sempre que a situação exigir, sem você precisar lembrar de pedir.

Por que skills mudam tudo: Considere expertise de domínio—as regras de processamento de pagamentos, os requisitos de conformidade, os padrões arquiteturais que sua equipe refinou ao longo dos anos. Sem skills, você ou re-explica esse contexto a cada sessão ou espera que o Claude infira a partir de comentários no código. Com skills, você codifica uma vez. O Claude lê a definição da skill e aplica essa expertise automaticamente sempre que relevante. Seus desenvolvedores júnior recebem orientação de nível sênior sem perguntar. Seus padrões de segurança são aplicados sem precisar lembrar de invocá-los.

Essa distinção é importante. Um comando slash é um atalho que você lembra de usar. Uma skill é conhecimento que o Claude sempre tem disponível. Quando você cria uma skill de revisão de segurança com os padrões específicos de vulnerabilidade e requisitos de conformidade da sua equipe, o Claude aplica essa expertise sempre que encontra código relevante—durante revisões de PR, refatoração ou qualquer tarefa onde segurança importa. Você não invoca /security-review; o Claude reconhece o contexto e aplica a skill automaticamente.

Skills vs Comandos vs Subagents

Entender quando usar cada mecanismo de extensão evita duplicação e maximiza a eficácia:

Use comandos slash quando quiser controle explícito: /deploy, /test, /review PR 456. Você decide quando executá-los.

Use skills quando expertise deve estar automaticamente disponível: padrões de segurança, aplicação de estilo de código, conhecimento específico de domínio. O Claude decide quando aplicá-las.

Use subagents quando tarefas precisam de isolamento: exploração em segundo plano, análise paralela, raciocínio especializado que não deve poluir sua conversa principal.

Estrutura e Localização das Skills

Skills ficam em diretórios dedicados contendo um arquivo SKILL.md obrigatório mais recursos de suporte opcionais:

Skills pessoais (disponíveis em todos os seus projetos):

~/.claude/skills/
├── code-reviewer/
│   ├── SKILL.md
│   ├── SECURITY_PATTERNS.md
│   └── PERFORMANCE_CHECKLIST.md
├── sql-analyst/
│   ├── SKILL.md
│   └── QUERY_PATTERNS.md
└── api-designer/
    └── SKILL.md

Skills de projeto (compartilhadas com a equipe via git):

.claude/skills/
├── domain-expert/
│   ├── SKILL.md
│   ├── BUSINESS_RULES.md
│   └── DATA_MODELS.md
└── deployment/
    ├── SKILL.md
    └── RUNBOOKS.md

Skills de projeto são commitadas no controle de versão. Quando colegas de equipe fazem pull, eles recebem suas skills automaticamente—sem instalação, sem configuração. É assim que você padroniza expertise em uma equipe.

Formato do SKILL.md

Toda skill requer um arquivo SKILL.md com frontmatter YAML:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review or audit code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Analysis

When reviewing code, check for:

### Input Validation
- All user input sanitized before use
- Parameterized queries for database operations
- Output encoding for rendered content

### Authentication & Authorization
- Session tokens properly validated
- Permission checks before sensitive operations
- No hardcoded credentials or API keys

### Data Exposure
- Sensitive data not logged
- PII properly masked in error messages
- API responses don't leak internal details

## Performance Patterns

### Database
- N+1 query detection
- Missing indexes on filtered columns
- Unbounded result sets

### Memory
- Large object lifecycle management
- Stream processing for big files
- Connection pool exhaustion risks

## Formato de Saída da Revisão

Para cada descoberta:
- **Arquivo**: path/to/file.ts:123
- **Severidade**: Crítica | Alta | Média | Baixa
- **Categoria**: Segurança | Performance | Manutenibilidade
- **Problema**: Descrição clara do problema
- **Recomendação**: Correção específica com exemplo de código
- **Justificativa**: Por que isso é importante

Consulte [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) para padrões detalhados de vulnerabilidades.
Consulte [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) para diretrizes de otimização.

Referência do Frontmatter

Substituições de String (v2.1.9+): Skills podem acessar o contexto da sessão usando a substituição ${CLAUDE_SESSION_ID}. Útil para logging, rastreamento ou geração de saídas específicas da sessão.⁵¹

O campo description é crítico. Claude descobre skills combinando suas solicitações com as descrições das skills. Uma descrição vaga significa que Claude não reconhecerá quando usar a skill. Uma descrição específica com condições claras de ativação significa ativação confiável.

Descrição ruim:

description: Helps with code

Descrição eficaz:

description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review, audit, or check code.

A descrição eficaz inclui: - O que a skill faz (revisar código para problemas específicos) - Quando usá-la (examinando mudanças, PRs, análise de qualidade) - Frases de ativação (review, audit, check)

Restrições de Ferramentas

O campo allowed-tools limita o que Claude pode fazer quando uma skill está ativa. Isso é essencial para skills que devem ser somente leitura ou limitadas em escopo:

---
name: security-auditor
description: Audit code for security vulnerabilities without making changes
allowed-tools: Read, Grep, Glob
---

Com esta configuração, Claude pode analisar código mas não pode editar arquivos, executar comandos bash ou fazer modificações. A skill impõe comportamento somente leitura.

Padrões comuns de restrição:

Arquivos de Suporte

Skills podem incluir múltiplos arquivos. Claude lê o SKILL.md principal na ativação, depois acessa arquivos de suporte conforme necessário—divulgação progressiva que gerencia o contexto eficientemente.

Padrão de estrutura:

my-skill/
├── SKILL.md           # Obrigatório: visão geral + referência rápida
├── DETAILED_GUIDE.md  # Documentação detalhada
├── EXAMPLES.md        # Exemplos concretos
├── PATTERNS.md        # Padrões de referência
├── templates/         # Templates reutilizáveis
│   └── component.tsx
└── scripts/           # Utilitários auxiliares
    └── validate.py

Referencie arquivos de suporte a partir do SKILL.md:

Para padrões detalhados de segurança, veja [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md).

Use este template para novos componentes:
@templates/component.tsx

Valide configurações com:
```bash
python scripts/validate.py config.json

**Dica de especialista:** Coloque informações essenciais diretamente no SKILL.md. Reserve arquivos de suporte para material de referência aprofundado. Claude lê o SKILL.md imediatamente, mas só acessa arquivos de suporte quando necessário. Se informações críticas estiverem enterradas em um arquivo de suporte, Claude pode não encontrá-las.

### Exemplo Completo: Skill de Especialista de Domínio

Aqui está uma skill de qualidade de produção para uma aplicação fintech:

**Estrutura de diretórios:**

.claude/skills/payments-domain/ ├── SKILL.md ├── BUSINESS_RULES.md ├── COMPLIANCE.md └── DATA_MODELS.md

**SKILL.md:**
```markdown
---
name: payments-domain
description: Expert knowledge of payment processing domain including transaction flows, compliance requirements, and business rules. Use when working with payment code, transaction handling, refunds, disputes, or financial calculations.
---

# Payments Domain Expertise

## Core Concepts

### Transaction States

PENDING → AUTHORIZED → CAPTURED → SETTLED ↘ VOIDED AUTHORIZED → DECLINED CAPTURED → REFUNDED (partial or full) SETTLED → CHARGEBACK → REPRESENTED

### Money Handling Rules
- ALL monetary values stored as integers (cents, not dollars)
- Currency always explicitly tracked (never assume USD)
- Rounding: HALF_EVEN for calculations, HALF_UP for display
- Never use floating point for money

### Idempotency Requirements
Every payment operation MUST be idempotent:
```typescript
// Required pattern
async function processPayment(idempotencyKey: string, amount: number) {
  const existing = await findByIdempotencyKey(idempotencyKey);
  if (existing) return existing; // Return cached result

  const result = await executePayment(amount);
  await storeWithIdempotencyKey(idempotencyKey, result);
  return result;
}

Quick Reference

Fee Calculations

• Interchange: 1.5% + $0.10 (debit), 2.1% + $0.10 (credit)
• Platform fee: 2.9% + $0.30 (standard), 2.2% + $0.30 (enterprise)
• International: +1% cross-border fee
• Currency conversion: mid-market rate + 1%

Compliance Thresholds

• $3,000: Enhanced due diligence trigger
• $10,000: CTR filing required
• $25,000: Additional verification required

Refund Windows

• Full refund: 120 days from capture
• Partial refund: 180 days from capture
• Chargeback window: 120 days (Visa), 180 days (Mastercard)

Key Files

• src/payments/processor.ts - Core payment logic
• src/payments/refunds.ts - Refund handling
• src/compliance/aml.ts - AML checks
• src/models/transaction.ts - Transaction model

See BUSINESS_RULES.md for detailed business logic. See COMPLIANCE.md for regulatory requirements. See DATA_MODELS.md for schema documentation.

Com esta skill implementada, Claude aplica automaticamente a expertise do domínio de pagamentos quando você trabalha em código de transações, pergunta sobre lógica de reembolsos ou depura fluxos de pagamento. Você não invoca nada—a expertise simplesmente está lá.

### Criando Skills Eficazes

**Comece pela descrição.** Escreva a descrição primeiro, depois construa o conteúdo da skill para corresponder. A descrição determina quando Claude usa a skill, então acerte isso:

1. Declare o que a skill fornece
2. Liste condições específicas de ativação
3. Inclua palavras-chave e frases relevantes

**Mantenha skills focadas.** Uma skill deve cobrir um domínio ou capacidade:

| Bom (focado) | Ruim (muito amplo) |
|--------------|---------------------|
| `security-auditor` | `code-helper` |
| `react-patterns` | `frontend-stuff` |
| `postgres-optimization` | `database-expert` |
| `api-documentation` | `docs-generator` |

Se uma skill tenta cobrir demais, sua descrição fica vaga, e Claude não reconhecerá de forma confiável quando usá-la.

**Use divulgação progressiva.** Coloque as informações mais importantes diretamente no SKILL.md. Referencie arquivos de suporte para profundidade:

```markdown

## Referência Rápida
[Padrões essenciais aqui - Claude vê isso imediatamente]

## Aprofundamento
Para cobertura abrangente, veja [DETAILED_GUIDE.md](DETAILED_GUIDE.md).

Inclua exemplos concretos. Descrições abstratas são menos úteis que padrões concretos:

## Validação de Entrada

### Padrão
```typescript
// Good: Explicit validation with typed errors
const validated = PaymentSchema.safeParse(input);
if (!validated.success) {
  throw new ValidationError(validated.error.issues);
}

// Bad: Implicit coercion
const amount = Number(input.amount); // Silent NaN on invalid input

**Teste com solicitações realistas.** Após criar uma skill, teste se Claude a ativa:

Review this payment processing code for issues

Deve ativar a skill payments-domain

How should I handle refunds?

Deve ativar a skill payments-domain

What’s the weather like?

NÃO deve ativar a skill payments-domain

Se Claude não ativar a skill quando esperado, revise a descrição para incluir as frases de ativação que você está usando.

### Estratégias de Compartilhamento em Equipe

**Compartilhamento baseado em Git (recomendado para skills de projeto):**
```bash
# Adicione a skill ao projeto
mkdir -p .claude/skills/team-standard
# Crie SKILL.md e arquivos de suporte

# Commit
git add .claude/skills/
git commit -m "Add team coding standards skill"
git push

# Colegas de equipe recebem automaticamente
git pull
claude  # Skill agora disponível

Compartilhamento entre projetos via symlinks:

# Crie localização canônica da skill
mkdir -p ~/shared-skills/security-reviewer
# Crie SKILL.md

# Symlink nos projetos
ln -s ~/shared-skills/security-reviewer ~/.claude/skills/security-reviewer
# Agora disponível em todos os seus projetos

Distribuição via plugin: Para distribuição mais ampla, empacote skills em plugins:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

Skills empacotadas em plugins ficam disponíveis quando usuários instalam o plugin.

Depurando Skills

Skill não está ativando:

1. Verifique se a descrição corresponde à sua solicitação: yaml # Se você está dizendo "check this code" mas a descrição diz "review" description: Review OR check code for issues...

2. Verifique a localização do arquivo: ```bash # Pessoal ls ~/.claude/skills/my-skill/SKILL.md

# Projeto ls .claude/skills/my-skill/SKILL.md ```

1. Valide o frontmatter YAML:
2. Primeira linha deve ser exatamente ---
3. Fechamento --- antes do conteúdo markdown
4. Sem tabs no YAML (use espaços)

5. Campo name é minúsculo apenas com hífens

6. Execute em modo debug: bash claude --debug # Observe mensagens de carregamento de skills

Skill ativando inesperadamente:

Restrinja a descrição. Se sua skill ativa quando não deveria, a descrição está muito ampla:

# Muito ampla - ativa em qualquer menção de "code"
description: Help with code

# Específica - ativa apenas para contextos de segurança
description: Audit code for security vulnerabilities including injection attacks, authentication flaws, and data exposure. Use when specifically asked about security, vulnerabilities, or when reviewing code for security issues.

Arquivos de suporte não encontrados:

• Use caminhos relativos a partir da localização do SKILL.md
• Apenas barras normais (mesmo no Windows)
• Verifique se o arquivo realmente existe: ls .claude/skills/my-skill/REFERENCED.md

Quando Criar uma Skill

Crie uma skill quando: - Expertise de domínio deve estar automaticamente disponível - Múltiplos membros da equipe precisam do mesmo conhecimento - Você está repetidamente explicando os mesmos padrões ou regras - Contexto deve ser injetado sem invocação explícita - Conhecimento abrange múltiplos arquivos e precisa de organização

Não crie uma skill quando: - Você quer controle explícito sobre a invocação (use slash command) - A tarefa precisa de contexto separado (use subagent) - É um prompt único (apenas digite) - A “skill” é realmente apenas um único template (use slash command)

Dica de especialista: Se você se pega repetidamente digitando /security-review antes de trabalhar em código de autenticação, converta para uma skill. A expertise deve ser ambiente, não explicitamente invocada. Se você quer invocação explícita, mantenha como um comando.

Sistema de Plugins

Plugins empacotam extensões do Claude Code para distribuição. Um plugin pode incluir comandos personalizados, subagents, skills, hooks e servidores MCP. A Anthropic lançou oficialmente o marketplace de plugins em dezembro de 2025 com 36 plugins selecionados.⁴⁷

Estrutura de Plugin

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required: metadata
├── commands/                     # Slash commands
│   └── hello.md
├── agents/                       # Subagents
│   └── helper.md
├── skills/                       # Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                        # Event handlers
│   └── hooks.json
└── .mcp.json                     # MCP servers

Manifesto do Plugin

plugin.json mínimo:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Gerenciamento de Plugins

> /plugin                              # Interactive interface
> /plugin install name@marketplace     # Install
> /plugin enable name@marketplace      # Enable
> /plugin disable name@marketplace     # Disable
> /plugin uninstall name@marketplace   # Remove
> /plugin marketplace add ./local      # Add local marketplace
> /plugin marketplace list             # View marketplaces

Desenvolvimento Local

Crie um marketplace local para testes:

mkdir dev-marketplace && cd dev-marketplace
mkdir my-plugin
# Create plugin structure

cd ..
claude
> /plugin marketplace add ./dev-marketplace
> /plugin install my-plugin@dev-marketplace

Componentes de Plugin

• Commands: Disponíveis como slash commands (/plugin-command)
• Agents: Aparecem na lista /agents
• Skills: Carregam automaticamente com base na configuração da skill
• Hooks: Mesclados com hooks de usuário/projeto, executados em paralelo
• MCP Servers: Iniciam automaticamente quando o plugin é habilitado

Como Funciona a Memória?

O sistema de memória do Claude Code permite contexto persistente entre sessões. O gerenciamento eficaz de memória é a diferença entre Claude entender seu projeto profundamente e tratar cada sessão como um novo começo.

Hierarquia do CLAUDE.md

Estrutura Eficaz do CLAUDE.md

# Project Context

## Architecture
- Monorepo with packages in /packages
- React frontend in /packages/ui
- Node.js API in /packages/api
- Shared types in /packages/types
- PostgreSQL database via Prisma

## Code Standards
- TypeScript strict mode everywhere
- ESLint + Prettier enforced (pre-commit hooks)
- No default exports
- JSDoc on all public APIs
- Tests required for all new code

## Commands
- `npm test` - Run all tests
- `npm run test:watch` - Watch mode
- `npm run lint` - Check linting
- `npm run lint:fix` - Auto-fix lint issues
- `npm run build` - Production build
- `npm run dev` - Start dev servers
- `npm run db:migrate` - Run migrations
- `npm run db:seed` - Seed database

## Patterns

### API Endpoints
Create in packages/api/src/routes/
Use Zod for request/response validation
All endpoints need OpenAPI documentation

### React Components
Create in packages/ui/src/components/
Use React Query for server state
Prefer composition over inheritance

### Database
Prisma schema in packages/api/prisma/
Always create migration for schema changes
Use transactions for multi-table operations

## Important Notes
- NEVER commit .env files
- API runs on :3000, UI on :3001
- Local DB: postgres://localhost:5432/myapp
- Feature flags in packages/api/src/flags.ts

## Recent Decisions
- 2025-12-01: Migrated to React Query v5
- 2025-11-15: Adopted Zod for all validation
- 2025-11-01: Moved to ESM modules

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

Importação de Arquivos

Referencie outros arquivos dentro do CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Sintaxe de importação: - Relativo: @docs/file.md - Absoluto do projeto: @/absolute/path.md - Diretório home: @~/.claude/file.md - Profundidade máxima: 5 níveis de importações

Diretório de Regras de Memória

Para uma memória mais organizada, use .claude/rules/ para armazenar arquivos de regras categorizados:¹⁸

.claude/rules/
├── testing.md          # Testing conventions
├── security.md         # Security requirements
├── api-patterns.md     # API design patterns
└── deployments.md      # Deployment procedures

As regras carregam automaticamente e fornecem contexto estruturado sem sobrecarregar o CLAUDE.md.

Adição Rápida de Memória

Use o prefixo # para adicionar notas durante uma sessão:

# Always run tests before committing
# The payment module is especially fragile
# Use the new logger from packages/api/src/logger.ts

Você será solicitado a selecionar em qual arquivo de memória armazenar a nota.

Comandos de Gerenciamento de Contexto

Visualizar uso de contexto:

> /context

Mostra uma grade visual da alocação de contexto entre prompt do sistema, conversa, ferramentas e conteúdo de arquivos.

Compactar conversa:

> /compact
> /compact focus on the authentication changes
> /compact preserve test output and error messages

Resume de forma inteligente conversas mais antigas enquanto preserva informações importantes.

Instruções de compactação personalizadas (no CLAUDE.md):

# Summary Instructions
When using compact, focus on:
- Test output and failures
- Code changes made this session
- Architecture decisions

Extended thinking para contexto:

export MAX_THINKING_TOKENS=10000

Mais thinking tokens significa mais capacidade de raciocínio, mas custos mais altos.

Estratégias de Otimização de Contexto

1. Use referências específicas de arquivos em vez de pedir para Claude pesquisar
2. Limpe conversas não relacionadas com /clear entre tarefas
3. Compacte proativamente durante sessões longas
4. Use subagents para isolar trabalho exploratório
5. Divida tarefas complexas em interações focadas
6. Retome sessões para trabalho contínuo em vez de re-explicar

Entrada de Imagens e Multimodal

Claude Code pode analisar imagens—capturas de tela, diagramas, mockups, mensagens de erro, schemas de banco de dados.

Métodos de Entrada

1. Arrastar e soltar: Arraste arquivos de imagem para a janela do Claude Code
2. Colar: Ctrl+V (não Cmd+V no Mac) para colar da área de transferência
3. Referência de caminho: “Analise esta imagem: /path/to/screenshot.png”

Visualizando Imagens Anexadas

Quando Claude referencia uma imagem em sua resposta, links de imagem clicáveis permitem visualização direta:³⁴

[Image #1]   # Click to open in default image viewer
[Image #2]   # Navigate attached screenshots

Isso é útil ao revisar capturas de tela ou depurar problemas visuais—clique na referência para ver exatamente o que Claude analisou.

Casos de Uso

• Depurar problemas de UI: “Aqui está uma captura de tela do bug, o que está causando isso?”
• Implementar designs: “Construa este componente baseado no mockup”
• Analisar diagramas: “Explique este diagrama de arquitetura”
• Schemas de banco de dados: “Crie modelos Prisma correspondentes a este ERD”
• Análise de erros: “O que esta captura de tela de erro significa?”

Dica de especialista: Ao implementar a partir de mockups, inclua múltiplas capturas de tela mostrando diferentes estados (padrão, hover, carregando, erro). Quanto mais contexto visual, melhor a implementação.

Como Funciona a Integração com Git?

Claude Code tem integração profunda com git com protocolos de segurança integrados.

Protocolos de Segurança

• Respeita .gitignore automaticamente
• Não modifica branches sem permissão
• Mostra diffs antes de commits
• Segue as convenções de commit do projeto
• Nunca faz force push sem solicitação explícita
• Verifica autoria antes de fazer amend em commits

Fluxos de Trabalho Comuns

Criar commits:

> commit these changes
> create a commit with a meaningful message

Claude irá: 1. Executar git status e git diff 2. Analisar mudanças 3. Gerar uma mensagem de commit convencional 4. Aguardar aprovação antes de fazer commit

Criar pull requests:

> create a PR for this feature
> summarize the changes and create a PR

Revisar código:

> review the changes in this PR
> what could go wrong with these changes?

Integração com GitHub Actions

Automatize Claude em CI/CD com a action oficial:

Configuração rápida:

> /install-github-app

Arquivo de workflow manual:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for bugs, security issues, and performance problems"
          claude_args: "--max-turns 5"

Para Bedrock (com OIDC):

- name: Configure AWS
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    aws-region: us-west-2

- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0'

Como Usar Claude Code na Minha IDE?

Extensão VS Code

Requisitos: VS Code 1.98.0+

Instalação: Pesquise “Claude Code” no marketplace de Extensões

Recursos: - Painel lateral (ícone Spark) - Plan mode com visualização de diff - Toggle de auto-aceitar edições - Toggle de extended thinking - Anexo de arquivos e colagem de imagens - Histórico de conversas - Múltiplas sessões simultâneas

Nota de Segurança: Uma vulnerabilidade de bypass de autenticação WebSocket (CVE-2025-52882) foi corrigida nas extensões de IDE v1.0.24+. Certifique-se de que sua extensão está atualizada—todas as versões vulneráveis foram removidas das lojas de extensões.³⁸

Configuração de provedor de terceiros (em .claude/settings.json):

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "AWS_PROFILE": "your-profile"
  }
}

Plugin JetBrains

Suportado: IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, DataGrip

Instalação: Settings → Plugins → Pesquisar “Claude Code” → Install → Reiniciar

Atalhos principais: - Cmd+Esc (Mac) / Ctrl+Esc (Windows): Lançamento rápido - Cmd+Option+K (Mac) / Alt+Ctrl+K (Windows): Adicionar referência de arquivo

Recursos: - Visualização de diff no visualizador de diff da IDE - Compartilhamento automático de contexto de seleção - Integração com diagnósticos - Múltiplas sessões

Configuração WSL2: Defina o comando Claude para:

wsl -d Ubuntu -- bash -lic "claude"

Integração com Terminal

Conecte um terminal externo à sua IDE:

> /ide

Claude Code detecta automaticamente VS Code, Cursor, Windsurf e IDEs JetBrains.

Integração com Slack (Dezembro 2025)

Claude Code agora integra diretamente com Slack, permitindo que desenvolvedores deleguem tarefas de codificação a partir de threads de chat.¹⁴

Como funciona: 1. Mencione @Claude em um canal ou thread do Slack 2. Claude analisa a mensagem para determinar se é uma tarefa de codificação 3. Uma sessão do Claude Code inicia automaticamente na infraestrutura da Anthropic 4. Claude coleta contexto de mensagens recentes do canal/thread 5. Atualizações de progresso são postadas de volta na sua thread do Slack 6. Links para revisar mudanças e abrir PRs são fornecidos na conclusão

Casos de uso: - Investigação de bugs a partir de relatórios de bugs postados no Slack - Revisões rápidas de código baseadas em feedback da equipe - Implementações de pequenas funcionalidades a partir de solicitações de recursos

Requisitos: - App Claude instalado via Slack App Marketplace - Plano Slack pago - Acesso ao Claude Code na web

Privacidade: Claude respeita a estrutura de permissões existente do Slack. Ele não pode acessar conversas ou repositórios que você não está autorizado a ver. As conversas não são usadas para treinamento de modelo.

Padrões de uso avançado

Modo headless e CI

Execute o Claude Code em scripts e pipelines de CI:

#!/bin/bash
# Automated code review

result=$(claude -p "Review this code for quality issues" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode plan \
  --disable-slash-commands \
  --max-turns 5)

if echo "$result" | jq -e '.result | test("critical|high severity")' > /dev/null; then
  echo "Issues found:"
  echo "$result" | jq -r '.result'
  exit 1
fi

echo "Review passed"
exit 0

Piping e encadeamento

# Analyze logs
cat production.log | claude -p "summarize errors" > error-summary.md

# Process multiple files
find . -name "*.ts" -exec cat {} \; | claude -p "find security issues"

# Chain with jq
claude -p "generate config" --output-format json | jq -r '.result' > config.json

Tarefas em segundo plano

Execute operações longas sem bloquear o terminal:

> start the build in the background

Ou pressione Ctrl+B durante a execução de um comando.

Gerencie tarefas em segundo plano:

> /bashes                    # List running tasks
> get output from task xyz   # Retrieve output

Sessões paralelas com Git Worktrees

# Create worktrees for parallel work
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix bugfix-123

# Run Claude in each
cd ../project-feature-a && claude --session-id "feature-a"
cd ../project-bugfix && claude --session-id "bugfix-123"

Cada worktree é um diretório de projeto independente com sua própria sessão.

Parsing de saída JSON

result=$(claude -p "analyze this code" --output-format json)

# Extract fields
echo "Result: $(echo $result | jq -r '.result')"
echo "Cost: $(echo $result | jq -r '.total_cost_usd')"
echo "Session: $(echo $result | jq -r '.session_id')"
echo "Duration: $(echo $result | jq -r '.duration_ms')ms"

Gerenciamento programático de sessões

# Named sessions for tracking
claude --session-id "feature-$(git branch --show-current)-$(date +%s)"

# Continue previous work
claude -c "continue implementing the tests"

# Fork for parallel exploration
claude -r "main-session" --fork-session "try alternative approach"

O que é o Claude Code Remote?

O Claude Code Remote conecta a web ao terminal, permitindo que você inicie tarefas na nuvem e continue localmente — ou vice-versa. Esse recurso transforma a forma como você trabalha entre dispositivos.

O conceito central

A interface web em claude.ai/code executa o Claude Code na nuvem. As tarefas são executadas em segundo plano enquanto você está longe do terminal. Quando estiver pronto para continuar, teleporte a sessão para sua máquina local e retome exatamente de onde o Claude parou.

Isso possibilita fluxos de trabalho que antes não eram possíveis: - Inicie uma refatoração complexa pelo celular, deixe executar enquanto você se desloca e finalize na sua estação de trabalho - Enfileire múltiplas tarefas na interface web e revise os resultados quando voltar à sua mesa - Transfira operações de longa duração para a nuvem quando precisar fechar o laptop

O prefixo &

Envie uma tarefa para executar no Claude Code web em segundo plano:

& Build a comprehensive REST API for user management with authentication, CRUD operations, and proper error handling

O prefixo & despacha seu prompt para a nuvem. O Claude trabalha nele de forma assíncrona — você pode fechar o terminal, trocar de dispositivo ou continuar com outro trabalho. A interface web em claude.ai/code mostra suas sessões em execução e concluídas.

A flag --teleport

Traga uma sessão da nuvem para o seu terminal local:

claude --teleport session_abc123

Isso recupera o estado da sessão da web e a retoma localmente. Você obtém o histórico completo da conversa, todos os arquivos que o Claude modificou e pode continuar a interação como se estivesse lá o tempo todo.

O ID da sessão aparece na interface web. Clique em qualquer sessão para ver seu ID e status atual.

Requisitos

O Claude Code Remote está disponível para assinantes Pro, Max, Team (assentos premium) e Enterprise (assentos premium).⁷³ A interface web roda na infraestrutura da Anthropic, executando as mesmas capacidades do Claude Code que você tem localmente — operações com arquivos, comandos bash, integrações MCP — mas em um ambiente de nuvem gerenciado. O acesso para Team e Enterprise foi expandido em janeiro de 2026 — administradores de conta podem ativar o acesso nas configurações do Claude.

App iOS (novembro de 2025): O Claude Code também está disponível no app iOS do Claude, permitindo que você inicie tarefas de programação em movimento e acompanhe o progresso do agente pelo celular.²² Você pode iniciar tarefas enquanto está longe da mesa e depois teleportá-las para o terminal quando estiver pronto para revisar.

Fluxo de trabalho prático

No caminho para o trabalho:

& Review all PRs assigned to me and prepare summaries with recommendations

Na sua mesa:

# Check what completed
# Visit claude.ai/code to see session list

# Pull the session locally to review and act on recommendations
claude --teleport pr-review-session-xyz

Antes de sair do trabalho:

& Run the full test suite, fix any failures, and prepare a summary of what was changed

Na manhã seguinte:

claude --teleport test-fixes-session-abc
# Review what Claude did overnight, make final adjustments

Status atual

O Claude Code Remote está atualmente em research preview. Espere que o recurso evolua à medida que a Anthropic coleta feedback. O fluxo de trabalho principal — execução na nuvem com teleporte local — permite desenvolvimento contínuo com IA: o Claude trabalha enquanto você está longe do teclado, e você retoma exatamente de onde ele parou.

Limitação atual: O teleporte de sessão é atualmente unidirecional — você pode trazer sessões da web para o terminal, mas não pode enviar uma sessão do terminal para a web. Ainda não há como continuar uma sessão local em uma máquina remota (por exemplo, uma instância AWS via SSH).

O que são Background Agents?

Background agents executam enquanto você continua trabalhando — sem precisar esperar a conclusão de tarefas de longa duração.¹⁷

Como funcionam os Background Agents

Em vez de bloquear seu terminal enquanto o Claude executa uma tarefa complexa, os background agents: 1. Executam de forma independente em um processo separado 2. Continuam funcionando mesmo se você fechar o terminal 3. Reportam os resultados quando concluídos via notificação 4. Podem ser monitorados e gerenciados enquanto estão em execução

Iniciando um Background Agent

Usando Ctrl+B: Enquanto o Claude está trabalhando, pressione Ctrl+B para enviar a tarefa atual para o segundo plano. Seu terminal fica disponível imediatamente.

Usando o prefixo &:

& Run all tests and fix any failures
& Refactor the authentication module to use JWT
& Generate comprehensive API documentation

O prefixo & despacha para o Claude Code Remote (execução na nuvem). Para execução local em segundo plano, use Ctrl+B em uma tarefa que já está em execução.

Monitorando tarefas em segundo plano

> /tasks                    # List all running tasks
> /task status abc123       # Check specific task
> /task cancel abc123       # Stop a task
> /task output abc123       # View task output so far

Fluxos de trabalho paralelos com Background Agents

Execute múltiplos agentes simultaneamente:

& Fix all failing tests in src/
& Update documentation for the API module
& Run security scan on the codebase

Cada um executa de forma independente. Monitore o progresso com /tasks e recupere os resultados conforme forem concluídos.

Claude in Chrome (dezembro de 2025)

O Claude Code agora se integra ao seu navegador através da extensão Claude in Chrome, permitindo controle direto do navegador a partir do terminal.²⁴

Configuração

1. Instale a extensão do Chrome em https://claude.ai/chrome
2. Inicie o Claude Code e a integração é detectada automaticamente
3. Use linguagem natural para controlar seu navegador

Capacidades

Automação do navegador a partir do terminal:

> Navigate to github.com and open my repositories
> Fill out this form with the test user data
> Take a screenshot of the current page
> Click the submit button and wait for the page to load

Web scraping e testes:

> Extract all product prices from this e-commerce page
> Run through the signup flow and report any issues
> Check if the mobile menu works correctly

Casos de uso

• Testes E2E: Execute testes de integração diretamente do Claude Code
• Web scraping: Extraia dados de páginas sem escrever código de automação de navegador
• Preenchimento de formulários: Automatize fluxos de trabalho web repetitivos
• Verificação visual: Capture screenshots e analise layouts de páginas

A integração com o Chrome funciona dentro da sua sessão de navegador existente, acessando seu estado de login e cookies — útil para testar fluxos autenticados.

Claude Code no Slack (dezembro de 2025)

A Anthropic lançou o Claude Code no Slack, permitindo que desenvolvedores deleguem tarefas de programação diretamente de threads de chat.²⁶

Como funciona

1. Marque @Claude em qualquer canal ou thread do Slack
2. Descreva a tarefa de programação com contexto
3. O Claude analisa as mensagens do Slack para identificar o repositório
4. Atualizações de progresso aparecem na thread
5. O Claude compartilha links para revisar o trabalho e abrir PRs

Exemplo de fluxo de trabalho

@Claude The login form validation is broken on mobile devices.
Can you fix it? Check the bug report from earlier in this thread.

O Claude irá: 1. Ler a thread para obter contexto 2. Identificar o repositório relevante 3. Clonar e analisar o código-fonte 4. Postar atualizações de progresso 5. Criar um PR com a correção 6. Compartilhar o link do PR para revisão

Benefícios

• Consciência de contexto: O Claude lê o histórico do Slack para relatórios de bugs, solicitações de funcionalidades e discussões
• Visibilidade da equipe: Atualizações de progresso nas threads mantêm todos informados
• Baixa fricção: Sem necessidade de terminal ou IDE — comece direto do chat
• Integração com GitHub: PRs criados automaticamente com descrições adequadas

Requisitos

• Workspace do Slack com a integração do Claude habilitada
• Repositório GitHub conectado
• Permissões adequadas para o Claude criar branches/PRs

Este recurso está atualmente em research preview para usuários Pro, Max, Team e Enterprise.

Quanto Custa o Claude Code?

Entender e controlar custos é essencial para o uso sustentável do Claude Code.

Visualizando Custos

> /cost

Saída:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Planos de Assinatura

Limites de taxa (agosto de 2025): A Anthropic introduziu limites de taxa semanais para assinantes pagos. Assinantes Max podem comprar uso adicional além do limite de taxa nas taxas padrão da API.²¹

Preços de Tokens da API (Janeiro de 2026)⁵⁷

Para usuários cobrados via API, preço por milhão de tokens:

O prompt caching reduz significativamente os custos de entrada repetida: gravações no cache custam 1,25× a base (cache de 5 min) ou 2× (cache de 1 hora), mas leituras do cache custam apenas 0,1×—uma economia de 90%. Para sistemas RAG e assistentes de código com contexto repetido, o caching pode reduzir custos em 88-95%.

A Batch API oferece 50% de desconto com retorno em 24 horas para tarefas não urgentes, como suítes de teste noturnas.

Política de Múltiplas Contas⁵⁹

Você pode ter múltiplas contas Claude? Sim, para casos de uso legítimos. A Anthropic permite explicitamente múltiplas contas quando servem a propósitos distintos.

O que é permitido:

Limites técnicos: - Até 3 contas podem ser verificadas com o mesmo número de telefone - Múltiplas assinaturas pagas do mesmo IP/rede são explicitamente suportadas - Contas são completamente separadas—sem transferência de chat ou projeto entre elas

O que é proibido (conforme a Política de Uso): - Criar contas para evadir banimentos após ser banido - Coordenar atividade maliciosa entre contas para evitar detecção - Usar múltiplas contas para burlar limites de taxa ou créditos do tier gratuito

Nota do mundo real: Em janeiro de 2026, o power user Jeffrey Emanuel (@doodlestein) teve 22 contas Max automaticamente sinalizadas e temporariamente banidas. O funcionário da Anthropic Thariq (@trq212) resolveu em 4 horas após confirmar uso legítimo. Se você está usando Claude Code extensivamente para projetos de trabalho e pessoais em múltiplas contas, é exatamente para isso que o serviço foi projetado—apenas não tente burlar o sistema.

Em caso de dúvida: Entre em contato com o Suporte da Anthropic para confirmar sua configuração específica por escrito.

Fatores de Custo

Exemplos de Custo do Mundo Real

Insight para economia: Usar Haiku para subagents de exploração e Sonnet para implementação tipicamente reduz custos em 40-50% comparado a usar Sonnet para tudo.

Gerenciamento de Custos para Times

TPM/RPM recomendados por tamanho de time:

Taxas Ocultas de Ferramentas

Além do preço por token, algumas ferramentas incorrem em cobranças separadas:¹⁶

Isso se acumula em loops de agente. Um ciclo de debug de 100 iterações com Bash custa ~24.500 tokens de entrada extras apenas em overhead.

Estratégias para Economizar Custos

1. Use Haiku para subagents: A maioria das explorações não precisa de Sonnet
2. Habilite prompt caching: É o padrão, mas verifique se não está desabilitado
3. Defina max turns: claude --max-turns 5 previne conversas descontroladas
4. Use plan mode para exploração: Sem execução = sem operações caras acidentais
5. Compacte proativamente: Contexto menor = menos tokens
6. Limite a saída: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API para trabalho não urgente: 50% de desconto em tokens de entrada e saída

Monitorando Uso

• Claude Console: platform.claude.com (requer role Admin ou Billing)
• Limites de workspace: Defina limites de gastos por workspace
• Bedrock/Vertex: Use monitoramento de custo nativo da cloud
• LiteLLM: Para rastreamento detalhado por usuário com provedores terceiros

Uso de Tokens em Background

Algumas operações consomem tokens em background: - Sumarização de conversa para /resume - Comandos /cost e /status - Auto-compaction

Tipicamente menos de $0,04 por sessão.

Claude Code Analytics API (Team/Enterprise)⁵³

Acesse programaticamente as análises de uso do Claude Code e métricas de produtividade da sua organização via Admin API.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Chave Admin API (sk-ant-admin...) - Plano Team ou Enterprise - Role Admin, Billing ou Developer

Métricas Disponíveis:

Exemplo de Requisição:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Casos de Uso: - Análise de produtividade de desenvolvedores (sessões, commits, PRs) - Métricas de uso de ferramentas (taxas de aceitação/rejeição para Edit, Write, etc.) - Rastreamento e alocação de custos entre times - Justificativa de ROI para ferramentas de codificação com IA

Nota: Os dados aparecem dentro de 1 hora após a conclusão da atividade. Apenas dados com mais de 1 hora são incluídos nas respostas para consistência.

Otimização de Desempenho

Reduzindo Latência

Seleção de modelo: - Haiku: Respostas mais rápidas, menor custo - Sonnet: Bom equilíbrio - Opus: Melhor qualidade, maior latência

Streaming: Todas as respostas fazem streaming por padrão—você vê a saída conforme é gerada.

Prompt caching: Habilitado por padrão. Reduz latência para contexto repetido (system prompts, definições de ferramentas).

Estratégias de Caching

System prompts e definições de ferramentas são cacheados automaticamente: - Duração do cache: 5 minutos (efêmero) - Cache hit: Tokens de entrada reduzidos e resposta mais rápida

Blocos de thinking de turnos anteriores são cacheados em conversas multi-turno.

Desabilite o caching por modelo se necessário:

export DISABLE_PROMPT_CACHING_SONNET=1
export DISABLE_PROMPT_CACHING_OPUS=1
export DISABLE_PROMPT_CACHING_HAIKU=1

Operações Paralelas

Paralelização de subagents: Múltiplos subagents podem executar simultaneamente. Cada um opera independentemente sem poluir o contexto principal.

Bash em background: Comandos de longa duração não bloqueiam a conversa:

> run the full test suite in the background

Git worktrees: Habilitam sessões verdadeiramente paralelas em branches separados.

Otimização de Memória

• Referências específicas de arquivo: @src/auth.ts em vez de “encontre o arquivo de auth”
• Buscas direcionadas: “busque em src/api” não “busque em todo lugar”
• Sessões novas: /clear entre tarefas não relacionadas
• Compactação personalizada: Adicione instruções ao CLAUDE.md sobre o que preservar

Como Depuro Problemas?

Problemas de Instalação

Problemas de path no WSL:

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check
which npm  # Deve começar com /usr não /mnt/c

Conflitos de versão do Node (nvm): Adicione ao ~/.bashrc ou ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Erros de permissão: Use instalação nativa em vez de npm:

curl -fsSL https://claude.ai/install.sh | bash

Problemas de Autenticação

# Reset completo
/logout
rm -rf ~/.config/claude-code/auth.json
claude  # Login novo

Problemas de Desempenho

Alto uso de CPU/memória: - Use /compact para reduzir contexto - Reinicie entre tarefas maiores - Adicione diretórios grandes ao .gitignore - Execute claude doctor

Busca lenta: Instale o ripgrep do sistema:

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Linux
sudo apt install ripgrep

Então:

export USE_BUILTIN_RIPGREP=0

Lento no WSL: - Mova o projeto para o sistema de arquivos Linux (não /mnt/c/) - Use filtros de diretório específicos nas buscas

Problemas de Integração com IDE

JetBrains não detectado (WSL2):

Opção 1 - Windows Firewall:

wsl hostname -I  # Obter IP do WSL
New-NetFirewallRule -DisplayName "Allow WSL2" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16

Opção 2 - Rede espelhada (adicione ao ~/.wslconfig):

[wsl2]
networkingMode=mirrored

Então: wsl --shutdown

Tecla Escape não funciona no JetBrains: Settings → Tools → Terminal → Desmarque “Move focus to the editor with Escape”

Modo Debug

claude --debug                    # Saída completa de debug
ANTHROPIC_LOG=debug claude       # Log de requisições da API
claude doctor                    # Verificação de saúde

Reset de Configuração

# Reset de configurações do usuário
rm ~/.claude.json
rm -rf ~/.claude/

# Reset de configurações do projeto
rm -rf .claude/
rm .mcp.json

Mensagens de Erro Comuns

Implantação Empresarial

Comparação de Provedores Cloud

Implantação de Configurações Gerenciadas

Implante políticas organizacionais por meio de managed-settings.json:

Localização: - macOS: /Library/Application Support/ClaudeCode/managed-settings.json - Linux: /etc/claude-code/managed-settings.json - Windows: C:\Program Files\ClaudeCode\managed-settings.json

Exemplo de política:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)",
      "Read(.env*)",
      "WebFetch"
    ],
    "defaultMode": "default"
  },
  "model": "claude-sonnet-4-5-20250929",
  "disableBypassPermissionsMode": "disable"
}

Os usuários não podem sobrescrever configurações gerenciadas.

CLAUDE.md Empresarial

Implante contexto organizacional:

Localização: - macOS: /Library/Application Support/ClaudeCode/CLAUDE.md - Linux: /etc/claude-code/CLAUDE.md

Conteúdo:

# Company Standards

## Security Requirements
- Never commit secrets or credentials
- All external API calls require security review
- Use parameterized queries for all database access

## Code Standards
- Follow company style guide at @docs/STYLE.md
- All PRs require two approvals
- Test coverage minimum: 80%

## Approved Tools
- npm, yarn, pnpm for package management
- Jest for testing
- ESLint + Prettier for formatting

Estratégia de Implantação

1. Comece pela documentação: Acerte o CLAUDE.md antes de implantar
2. Grupo piloto: Comece com 5 a 10 desenvolvedores
3. Fase de perguntas e respostas: Deixe os pilotos usarem o Claude para exploração de código
4. Desenvolvimento guiado: Avance para correções de bugs pequenas
5. Implantação completa: Distribua com configurações gerenciadas
6. Monitore custos: Acompanhe o uso por equipe

Auditoria e Conformidade

• Transcrições de sessão são armazenadas localmente por padrão
• Use os logs do provedor cloud para auditoria empresarial
• Considere o LiteLLM para rastreamento detalhado de uso
• Configurações gerenciadas garantem a conformidade com políticas

Analytics API (Administrador)

Planos Enterprise e Team têm acesso à Analytics API do Claude Code para rastreamento programático de uso.

Endpoint: GET /v1/organizations/usage_report/claude_code

Autenticação: Requer chave de API Admin (sk-ant-admin...), provisionada no Console pelos administradores da organização.

Métricas disponíveis:

Parâmetros da requisição: - starting_at - Data para agregação diária (AAAA-MM-DD) - Retorna dados por usuário para o dia especificado

Exemplo:

curl -X GET "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-25" \
  -H "x-api-key: sk-ant-admin-..." \
  -H "anthropic-version: 2023-06-01"

Limitações: - Apenas agregados diários (~1h de atraso para consistência) - Para monitoramento em tempo real, use a integração OpenTelemetry - Rastreia apenas uso da API própria (não Bedrock/Vertex)

Custo: Gratuito para organizações com acesso à Admin API.

Referência de Atalhos de Teclado

Controles Gerais

Atalhos personalizáveis (v2.1.18+): Execute /keybindings para personalizar atalhos de teclado. Suporta atalhos específicos por contexto, sequências de acordes (combinações de múltiplas teclas) e personalização completa. Os atalhos são armazenados em ~/.claude/keybindings.json. Consulte a documentação de keybindings para a referência completa de configuração.⁷⁷

Sugestões de prompt (dez. 2025): O Claude agora sugere prompts para acelerar seu fluxo de trabalho. Pressione Tab para aceitar uma sugestão ou Enter para enviar seu próprio prompt.¹³

Entrada Multilinha

Prefixos Rápidos

Desempenho de referência a arquivos (jan. 2026): As menções com @ agora são 3x mais rápidas em repositórios git. O Claude Code também respeita arquivos .ignore e .rgignore ao sugerir complementos de arquivos — útil para excluir artefatos de build ou arquivos gerados das sugestões.³⁵

Modo Vim

Ative com /vim:

Modo normal: - h/j/k/l - Navegação - w/e/b - Movimento por palavra - 0/$ - Início/fim da linha - gg/G - Início/fim do buffer - dd - Excluir linha - cc/C - Alterar linha/até o fim - dw/de/db - Variações de exclusão de palavra - x - Excluir caractere - . - Repetir última edição

Modo de inserção: - i/I - Inserir antes/no início da linha - a/A - Inserir após/no fim da linha - o/O - Abrir linha abaixo/acima - Esc - Retornar ao modo normal

Boas Práticas

Estratégia de Sessão

Use IDs de sessão descritivos:

claude --session-id "feature-$(git branch --show-current)-$(date +%s)"
claude --session-id "bug-JIRA-456"
claude --session-id "spike-new-architecture"

Retome sessões para trabalhos em andamento em vez de reexplicar o contexto.

Design do CLAUDE.md

Mantenha-o escaneável. O Claude lê isso a cada sessão — prosa densa desperdiça contexto.

Foque no que não é óbvio. Documente padrões específicos do projeto, convenções incomuns e decisões. Pule o que o Claude consegue inferir do código.

Atualize continuamente. Adicione notas durante o desenvolvimento com #. Revise e consolide semanalmente.

Inclua referência de comandos. Os comandos que você executa constantemente devem estar documentados.

Comandos Personalizados

Crie comandos para fluxos de trabalho repetitivos:

---
description: Start new feature
allowed-tools: Bash(git:*), Read, Edit
---

1. Create branch: !`git checkout -b feature/$ARGUMENTS`
2. Pull latest main
3. Set up boilerplate
4. Begin implementation

Prompts Eficazes

Seja específico:

# Good
"Add email validation to LoginForm in src/components/LoginForm.tsx"

# Too vague
"Improve the login"

Referencie arquivos diretamente:

"Review @src/auth/middleware.ts for security issues"

Forneça restrições:

"Refactor using the same pattern as @src/repositories/UserRepository.ts"

Use subagents para exploração:

"Have an explore agent find all places where we handle errors"

Controle de Custos

• Use /cost regularmente
• Use Haiku para tarefas simples e subagents
• Defina MAX_THINKING_TOKENS apenas quando necessário
• Use --max-turns para scripts automatizados
• Compacte proativamente em sessões longas

Segurança

• Configure regras de negação em .claude/settings.json para arquivos sensíveis
• Use o modo sandbox para projetos não confiáveis
• Nunca permita Bash(rm -rf:*) ou Bash(sudo:*)
• Use hooks para bloquear acesso a segredos
• Implante configurações gerenciadas para ambientes empresariais

Dicas e Técnicas da Comunidade⁵⁶⁵⁸

A comunidade do Claude Code descobriu padrões poderosos que vão além da documentação oficial. Estas dicas vêm de usuários avançados, incluindo Boris Cherny (criador do Claude Code) e o repositório de mais de 40 dicas.

Use o Modo Plan Antes de Programar

Se você lembrar de apenas uma dica, que seja esta. Quanto mais tempo você dedicar ao planejamento, maior a probabilidade de Claude ter sucesso. Pressione Shift+Tab para alternar para o modo plan antes de iniciar a implementação.

Novidade em janeiro de 2026: Quando você aceita um plano, Claude agora oferece limpar automaticamente seu contexto, dando ao plano uma janela de contexto limpa. Isso melhora significativamente a aderência ao plano—Claude permanece no caminho certo por mais tempo sem o contexto antigo interferindo. As opções incluem: “Sim, limpar contexto e aceitar edições automaticamente” (Shift+Tab), “Sim, e aprovar edições manualmente”, ou “Sim, aceitar edições automaticamente” (sem limpar).

Limpe o Contexto Frequentemente

Use /clear com frequência. Toda vez que você começar algo novo, limpe o chat. Você não precisa do histórico antigo consumindo tokens ou acionando chamadas de compactação caras. Apenas limpe e siga em frente.

Use Imagens e Capturas de Tela

Claude se destaca com entrada visual. No macOS: Cmd+Ctrl+Shift+4 captura a tela para a área de transferência, depois Ctrl+V para colar diretamente no Claude Code. Use isso para compartilhar mockups de UI, mensagens de erro ou referências de design.

Instale o GitHub App para Revisões de PR

Execute /install-github-app e Claude revisará automaticamente seus PRs. Isso é particularmente valioso à medida que o desenvolvimento assistido por IA aumenta o volume de PRs—Claude frequentemente detecta erros de lógica e problemas de segurança que revisores humanos deixam passar.

Operação Autônoma Baseada em Container

Para operação totalmente autônoma, execute Claude Code em um container Docker com tmux como camada de controle. Seu Claude Code local controla a instância em container, que pode executar tarefas de longa duração ou experimentais sem aprovação manual. Se algo der errado, está isolado.

# Conceptual pattern (varies by setup)
# Local Claude Code → tmux → Container Claude Code
# Results pulled back when complete

Modo Docker Sandbox (Início Rápido): Claude Code suporta um sandbox Docker simplificado através do subcomando docker. Isso cria um ambiente isolado para explorar codebases não confiáveis ou executar prompts experimentais com segurança.⁶³

# Run Claude Code in Docker sandbox
docker sandbox run claude

# Or with specific project
docker sandbox run claude /path/to/project

Use o modo sandbox quando: - Explorar codebases desconhecidas ou não confiáveis - Testar prompts experimentais que podem modificar arquivos - Executar sessões autônomas que você quer completamente isoladas - Aprender Claude Code sem risco para seus arquivos reais

Gemini CLI como Fallback

A ferramenta WebFetch do Claude Code não consegue acessar certos sites (como Reddit). Crie uma skill que instrua Claude a usar Gemini CLI como fallback—Gemini tem acesso à web e pode buscar conteúdo de sites que Claude não consegue acessar diretamente.

Padrão Meta-Agent Factory

Em vez de criar agents que executam tarefas, crie um agent que cria outros agents. Isso não é recursão inteligente—é um multiplicador genuíno de produtividade para fluxos de trabalho de automação complexos.

Claude Squad: Gerenciador Multi-Agent

Claude Squad gerencia múltiplas instâncias do Claude Code em paralelo, cada uma em sua própria sessão tmux com worktrees isoladas. Execute vários agents simultaneamente em tarefas diferentes, monitore seu progresso de um único painel e recupere os resultados quando completarem.⁶⁵

# Install
npm install -g @smtg-ai/claude-squad

# Start multiple agents
claude-squad start "Implement auth feature" --worktree auth-feature
claude-squad start "Write API tests" --worktree api-tests
claude-squad start "Update documentation" --worktree docs-update

# Monitor all agents
claude-squad status

Casos de uso: - Paralelizar funcionalidades independentes entre agents - Executar prompts exploratórios sem bloquear sua sessão principal - Escalar codificação autônoma além de uma única janela de contexto

Estatísticas de Produtividade de Usuários Avançados

Boris Cherny demonstrou o potencial do Claude Code: em 30 dias, ele entregou 259 PRs com 497 commits—40.000 linhas adicionadas e 38.000 removidas. Isso mostra o que é possível quando Claude Code está totalmente integrado ao fluxo de trabalho de desenvolvimento.

Pessoas para Seguir

Mantenha-se atualizado com os desenvolvimentos do Claude Code seguindo estas contas:

Equipe Anthropic (Fontes Primárias)

Principais Criadores de Conteúdo

Recursos Principais

• GitHub Releases: anthropics/claude-code/releases - Acompanhe apenas os releases
• Discord: Canais da comunidade Anthropic
• Lista completa: Veja ~/.claude/docs/following-list.md para mais de 20 contas curadas

Boris e a equipe da Anthropic compartilham funcionalidades conforme são lançadas—frequentemente a forma mais rápida de aprender sobre novas capacidades antes da documentação ser atualizada.

Anti-padrões Comuns

Aprender o que NÃO fazer frequentemente fornece mais valor do que as melhores práticas. Estes padrões consistentemente causam problemas:

Anti-padrões de Custo

Anti-padrões de Contexto

Anti-padrões de Fluxo de Trabalho

Anti-padrões de Configuração

Anti-padrões de Prompt

Receitas de Fluxo de Trabalho

Padrões de ponta a ponta para cenários comuns.

Receita 1: Iniciando um Novo Projeto

# 1. Initialize
cd my-project
claude

# 2. Let Claude understand the codebase
> "Explore this codebase and summarize the architecture"

# 3. Set up project configuration
> /init

# 4. Create CLAUDE.md with learned patterns
> "Create CLAUDE.md documenting the patterns you observed"

# 5. Add team commands
> "Create a /test command that runs our test suite"
> "Create a /deploy command for staging deployment"

Receita 2: Fluxo de Desenvolvimento Diário

# 1. Continue yesterday's session
claude -c

# 2. Quick context recap
> "What did we work on yesterday?"

# 3. Check current state
> /status

# 4. Work on feature (Sonnet handles most tasks)
> "Implement the user profile endpoint"

# 5. Proactive context management
> /compact  # Before context exceeds 50%

# 6. Check spending
> /cost

# 7. End session cleanly
> "Summarize what we accomplished today"

Receita 3: Refatoração Complexa

# 1. Use Opus for planning, Sonnet for execution
> /model opusplan

# 2. Plan the refactoring
> "Plan refactoring our authentication from sessions to JWT"

# 3. Review the plan
# (Claude presents approach, you approve or modify)

# 4. Execute with Sonnet
> "Execute the plan"

# 5. Verify nothing broke
> "Have an explore agent verify all auth-related tests pass"

# 6. Review the diff
> !git diff

Receita 4: Automação de Revisão de PR

# In CI/CD (GitHub Actions, etc.)
claude -p "Review this PR for:" \
  --input-file pr_diff.txt \
  --output-format json \
  --permission-mode plan \
  --max-turns 5 << EOF
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing test coverage
Provide findings in JSON format.
EOF

Receita 5: Debugando Problemas em Produção

# 1. Configure Sentry MCP for error access
claude --add-mcp sentry

# 2. Get error context
> "Fetch the last 10 errors from Sentry for the auth service"

# 3. Deep dive with thinking
> Tab  # Enable extended thinking
> "Analyze these errors and identify the root cause"

# 4. Fix and verify
> "Implement a fix and add a regression test"
> !npm test

Guia de Migração

Vindo de outras ferramentas de codificação com IA? Veja como os conceitos se correspondem.

Vindo do GitHub Copilot

O que você ganha: Capacidade verdadeiramente agêntica—Claude Code lê sua base de código, executa testes, cria PRs e delega para subagents. Não são apenas sugestões.

Vindo do Cursor

O que você ganha: Integrações MCP (bancos de dados, GitHub, Sentry), delegação para subagents, hooks para automação e fluxo de trabalho nativo do terminal.

Vindo do ChatGPT / Claude Web

O que você ganha: Tudo. Interfaces web exigem fluxos de trabalho de copiar e colar; Claude Code opera diretamente na sua base de código.

Mudanças-Chave de Mentalidade

1. Pare de copiar código. Claude Code escreve diretamente nos arquivos.
2. Pare de alternar contexto. MCP traz ferramentas externas para a sessão.
3. Delegue agressivamente. Subagents lidam com exploração sem inflar seu contexto.
4. Automatize com hooks. Formatação, linting e logging acontecem automaticamente.
5. Pense em sessões. Continue o trabalho com -c, não conversas do zero.

Principais Conclusões

Para desenvolvedores: - Haiku custa 10-20x menos que Opus—use para subagents e tarefas simples - Use /compact proativamente durante sessões longas para gerenciar o contexto - IDs de sessão codificando contexto (feature-${branch}-${timestamp}) ajudam a navegar de volta ao trabalho anterior - Prefixe prompts comuns com # para adicionar à memória persistente sem digitação extra

Para equipes de DevOps e plataforma: - Modo headless (flag -p) permite integração CI/CD com saída JSON para parsing - Hooks garantem execução independentemente do comportamento do modelo—use para linting, formatação, verificações de segurança - MCP estende capacidades para bancos de dados, GitHub, Sentry e mais de 300 integrações - Tarefas em background (prefixo &) executam no Claude Code Remote para execução assíncrona

Para equipes de segurança: - Regras de permissão são avaliadas com primeira correspondência vence—estruture listas allow/deny cuidadosamente - Modo sandbox isola sistema de arquivos e rede para bases de código não confiáveis - Padrões Bash correspondem apenas prefixos—Bash(curl:*) bloqueia todo curl, não apenas URLs específicas - Configurações gerenciadas enterprise não podem ser sobrescritas por usuários

Para líderes de equipe: - Skills ativam automaticamente baseado no contexto—incorpore expertise de domínio sem invocação explícita - Skills de projeto são commitados no git—colegas de equipe recebem expertise padronizada automaticamente - Rastreamento de custos via /cost mostra detalhamento da sessão; planeje 10k-300k TPM por usuário baseado no tamanho da equipe - Comandos personalizados em .claude/commands/ criam fluxos de trabalho reutilizáveis

Para arquitetos enterprise: - Configurações gerenciadas implantam políticas em toda a organização via /etc/claude-code/managed-settings.json - AWS Bedrock, Google Vertex AI e Microsoft Foundry integram com faturamento cloud existente - Extended thinking (Tab para alternar) melhora raciocínio complexo com custo maior - Comece o piloto com 5-10 desenvolvedores antes da implantação completa

Cartão de Referência Rápida

Imprima isso. Cole no seu monitor.

╔═══════════════════════════════════════════════════════════════╗
║                    CLAUDE CODE QUICK REFERENCE                 ║
╠═══════════════════════════════════════════════════════════════╣
║  MODELS                                                        ║
║    haiku     $1/$5/M     Exploration, simple tasks            ║
║    sonnet    $3/$15/M    Daily coding (default)               ║
║    opus      $5/$25/M    Architecture, hard problems          ║
║    sonnet[1m] $6/$22.50/M Large codebases (1M context)        ║
╠═══════════════════════════════════════════════════════════════╣
║  ESSENTIAL COMMANDS                                            ║
║    /compact        Reduce context (do at 50% capacity)        ║
║    /cost           Check session spending                     ║
║    /model opus     Switch to Opus                             ║
║    /status         Show current state                         ║
║    /init           Set up project config                      ║
║    /mcp            Configure integrations                     ║
╠═══════════════════════════════════════════════════════════════╣
║  KEYBOARD SHORTCUTS                                            ║
║    Tab             Toggle extended thinking                   ║
║    Shift+Tab       Cycle permission modes                     ║
║    Ctrl+C          Interrupt current operation                ║
║    Esc → Esc       Rewind last change                         ║
║    Ctrl+L          Clear screen                               ║
╠═══════════════════════════════════════════════════════════════╣
║  PREFIXES                                                      ║
║    #message        Add to persistent memory                   ║
║    @path/file      Reference file in prompt                   ║
║    !command        Execute bash directly                      ║
║    &task           Send to cloud (async)                      ║
╠═══════════════════════════════════════════════════════════════╣
║  CONFIG FILE HIERARCHY (first found wins)                      ║
║    .claude/settings.local.json    Personal (gitignored)       ║
║    .claude/settings.json          Project (shared)            ║
║    ~/.claude/settings.json        User global                 ║
║    /etc/.../managed-settings.json Enterprise (locked)         ║
║    CLAUDE.md                      Project context             ║
╠═══════════════════════════════════════════════════════════════╣
║  DAILY WORKFLOW                                                ║
║    1. claude -c              Continue session                 ║
║    2. Work on features       Use Sonnet                       ║
║    3. /compact               Before context bloats            ║
║    4. /cost                  Check spending                   ║
║    5. Summarize              Clean exit                       ║
╠═══════════════════════════════════════════════════════════════╣
║  DECISION RULES                                                ║
║    Simple task?        → Haiku                                ║
║    Hard reasoning?     → Opus                                 ║
║    Everything else?    → Sonnet                               ║
║    Must always run?    → Hook (not prompt)                    ║
║    Auto-apply wisdom?  → Skill (not command)                  ║
║    Needs isolation?    → Subagent                             ║
╚═══════════════════════════════════════════════════════════════╝

Changelog

Esta referência é um documento vivo. Atualizações são aplicadas conforme o Claude Code evolui.

Execute /update-cc-guide para escanear e aplicar as últimas atualizações do Claude Code.

Referências