Guia rápido do Claude Code: comandos, configurações e atalhos

Cada flag do CLI, comando de barra, atalho de teclado, chave de configuração, evento de hook e variável de ambiente em um só lugar. Para explicações detalhadas, veja o guia completo do Claude Code. Para configuração inicial, veja o quickstart.

1. Instalação

Três métodos de instalação, em ordem de preferência.

# Native binary (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew (macOS)
brew install --cask claude-code

# NPM (deprecated — migrate with `claude install`)
npm install -g @anthropic-ai/claude-code

Instale uma versão específica:

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

Verifique a instalação:

claude doctor
claude --version

Autentique:

claude auth login       # Log in or switch accounts
claude auth status      # Check current auth state
claude auth logout      # Clear stored credentials

2. Flags de CLI

3. Slash Commands

Comandos personalizados: Crie .claude/commands/my-command.md (projeto) ou ~/.claude/commands/my-command.md (pessoal) e invoque com /my-command. Os comandos aceitam frontmatter YAML para descrição, ferramentas permitidas, substituição de modelo e interpolação de argumentos via $ARGUMENTS ou posicionais $1, $2.

---
description: Fix a GitHub issue
allowed-tools: Read, Edit, Bash(git:*)
model: opus
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

Uso: /fix-issue 123

4. Atalhos de teclado

Controles gerais

Prefixos rápidos

Entrada multilinha

Os atalhos de teclado podem ser personalizados via /keybindings (armazenado em ~/.claude/keybindings.json).

5. Arquivos de configuração

Hierarquia de precedência (da maior para a menor)

A primeira correspondência vence. Configurações Enterprise não podem ser contornadas.

6. Referência de Settings.json

Principais configurações com tipos e exemplos. Coloque em qualquer arquivo de configurações da hierarquia acima.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Glob", "Grep", "Bash(npm run:*)", "Bash(git:*)", "Edit(src/**)"],
    "deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(sudo:*)"],
    "ask": ["WebFetch", "Bash(docker:*)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared-lib"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {},
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "respectGitignore": true,
  "showTurnDuration": true,
  "language": "en",
  "autoMemoryDirectory": ".claude/memory",
  "plansDirectory": ".claude/plans"
}

Sintaxe de regras de permissão: Tool(pattern:*) fornece correspondência por prefixo. Bash(npm run test:*) permite npm run test, npm run test:unit etc. Padrões de arquivo usam sintaxe glob: Edit(src/**).

Novas chaves (v2.1.118+):

Para o schema completo de configurações, consulte Análise detalhada de configuração no guia completo.

7. Referência rápida do CLAUDE.md

CLAUDE.md é o arquivo de instruções do seu projeto. Claude o lê no início de cada sessão.

Onde ele fica:

O que incluir:

# Project Name

## Stack
- Backend: FastAPI, Python 3.11+
- Frontend: HTMX + Alpine.js + Bootstrap 5

## Commands
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `python -m pytest -v`
- Lint: `ruff check .`

## Conventions
- Conventional commits: feat:, fix:, docs:, refactor:
- Never force push to main
- Always activate venv before Python commands

## Key Files
- app/main.py — FastAPI app and routes
- app/models.py — SQLAlchemy models

Mantenha fácil de escanear. Prosa densa desperdiça tokens de contexto a cada sessão. Use listas com marcadores, tabelas e blocos de código curtos. Evite parágrafos longos — Claude lê CLAUDE.md no início de cada sessão, então cada palavra custa contexto.

Dicas avançadas: - Use o prefixo # no REPL para adicionar itens à memória automática sem editar o CLAUDE.md: # Always use TypeScript strict mode - O CLAUDE.md em subdiretórios é carregado quando Claude lê arquivos nesse diretório - Regras compartilhadas pela equipe ficam em .claude/rules/*.md para organização modular

8. Modos de permissão

Auto Mode (v2.1.85+) é o substituto recomendado para --dangerously-skip-permissions. Somente leitura e edições de arquivo são aprovadas automaticamente. Regras personalizadas de allow/deny são resolvidas primeiro. Todo o resto vai para o classificador de segurança. Bloqueado automaticamente por padrão: curl | bash, force-push para main, deploys em produção, exclusões em massa na nuvem, alterações de IAM, envio de dados confidenciais externamente.¹

Disjuntor: 3 bloqueios consecutivos ou 20 no total em uma sessão pausam e voltam para solicitações manuais.

# Enable at startup
claude --enable-auto-mode

# Cycle during session
Shift+Tab    # default -> acceptEdits -> auto -> plan

Aprovação automática do PowerShell (v2.1.119+): comandos da tool PowerShell são aprovados automaticamente no modo de permissão da mesma forma que comandos Bash. Regras de allow como PowerShell(Get-*:*) ignoram solicitações para operações somente leitura. Use v2.1.149+ em workflows com muito PowerShell; ela corrige bypasses de permissão do cd integrado, correspondência de regras de allow por prefixo/wildcard e rastreamento de variável de diretório desatualizada.

9. Eventos de hooks

| InstructionsLoaded | CLAUDE.md carregado | Não | | ConfigChange | Arquivo de configuração muda no meio da sessão | Sim | | WorktreeCreate | Worktree sendo criado | Sim | | WorktreeRemove | Worktree sendo removido | Não | | PreCompact | Antes da compactação de contexto | Não | | PostCompact | Depois da compactação de contexto | Não | | Elicitation | MCP solicita entrada estruturada | Sim | | ElicitationResult | Usuário responde ao diálogo de MCP | Sim | | StopFailure | Turno termina devido a erro de API | Não | | PermissionRequest | Diálogo de permissão exibido | Sim | | PermissionDenied | Auto mode nega uma ação (v2.1.88+) | Não | | CwdChanged | Diretório de trabalho muda (v2.1.83+) | Não | | FileChanged | Arquivo monitorado modificado externamente (v2.1.83+) | Não | | TaskCreated | Nova tarefa criada (v2.1.84+) | Não | | TeammateIdle | Membro da equipe de agentes fica ocioso | Sim | | TaskCompleted | Tarefa marcada como concluída | Sim |

Para o protocolo completo de hooks (JSON de entrada/saída, matchers, códigos de saída), consulte Análise detalhada de hooks no guia completo.

10. Configuração de hooks

Hooks ficam em settings.json ou em um hooks.json dedicado. Exemplo mínimo:

{
  "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"
          }
        ]
      }
    ]
  }
}

Sintaxe de matchers:

Códigos de saída:

Hooks assíncronos rodam em segundo plano sem bloquear: adicione "async": true ao objeto do hook.²

Saída / campos de entrada de hook:

• duration_ms na entrada de hook PostToolUse / PostToolUseFailure (v2.1.119+) — tempo de execução da tool excluindo solicitações de permissão e hooks PreToolUse.
• hookSpecificOutput.updatedToolOutput (v2.1.121+) — substitui a saída da tool para qualquer tool (v2.1.118 introduziu isso apenas para MCP; v2.1.121 estende para todas as tools).
• hookSpecificOutput.sessionTitle (v2.1.96+) — define o título da sessão a partir de um hook UserPromptSubmit.
• args: string[] em hooks de comando (v2.1.139+) — passa argv estruturado sem quoting de shell.
• continueOnBlock em hooks PostToolUse (v2.1.139+) — envia o motivo do bloqueio de volta para Claude e continua o turno.
• subagent_type na entrada de hook de agente (v2.1.140+) — identifica qual tipo de agente está em execução.
• terminalSequence na saída JSON do hook (v2.1.141+) — emite sequências de controle de terminal para notificações, títulos de janela e sinos.

11. Configuração rápida de MCP

Adicione um servidor MCP com um comando:

# Remote HTTP server (recommended)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Remote with auth header
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

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

Controle de escopo:

claude mcp add --scope project ...   # Team-shared (.mcp.json)
claude mcp add --scope user ...      # Personal (~/.claude.json)

Exemplo de .mcp.json do 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": "postgresql://user:pass@localhost/db"
      }
    }
  }
}

MCP agora tem 100 milhões de downloads mensais e mais de 3.000 servidores indexados.³ Para tipos de transporte, elicitation e configuração de tool search, veja a seção de MCP no guia completo.

alwaysLoad (v2.1.121+): Exclui um servidor confiável do adiamento do Tool Search. Todas as ferramentas dele são carregadas no início da sessão, sem ida e volta de ToolSearch:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

Nova tentativa automática (v2.1.121+): servidores MCP que geram erro durante a inicialização tentam novamente até 3 vezes antes de serem marcados como desconectados.

mcp_authenticate redirectUri de SDK (v2.1.121+): obrigatório para concluir OAuth em esquemas de URI personalizados — aplicativos desktop e fluxos de conectores do claude.ai.

11.5. Comandos CLI de plugins

12. Tipos de subagent

Claude delega automaticamente para subagents. Você também pode solicitá-los explicitamente:

> Use the explore agent to find all auth-related files
> Have a subagent analyze the database schema

Subagents personalizados são definidos em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal) como arquivos markdown com frontmatter YAML. Até 10 subagents podem rodar em paralelo.⁴

claude agents abre a Agent View nas versões atuais: uma tela operacional em research-preview para sessões Claude Code em execução, bloqueadas e concluídas. claude agents --cwd <path> limita a visualização a um diretório (v2.1.141+), a v2.1.142 adiciona flags de despacho para sessões em segundo plano, e a v2.1.143 aplica essas flags de forma consistente ao dashboard e às sessões em segundo plano: --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort e --dangerously-skip-permissions. A v2.1.144 adiciona suporte a /resume para sessões em segundo plano e as marca com bg; a v2.1.145 adiciona claude agents --json, contagens de abas aguardando entrada e correções no painel de resposta da Agent View; a v2.1.147 adiciona sessões em segundo plano fixadas, que continuam ativas quando ociosas e reiniciam no mesmo lugar para atualizações. Use a Agent View para monitoramento, não como prova de que o trabalho passou pelos gates de qualidade.⁶

Campos de frontmatter de agente personalizado:

Exemplo de agente personalizado (.claude/agents/security-reviewer.md):

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

You are a senior security engineer. Analyze for OWASP Top 10 vulnerabilities,
secrets, hardcoded credentials, and SQL injection. Report findings with severity
levels and remediation steps.

13. Variáveis de ambiente

Autenticação e API

Configuração de modelo

Provedores de cloud

Controle de comportamento

Configuração de ferramentas

Rede e proxy

Para a lista completa, veja Variáveis de ambiente no guia completo.

14. Referência de custos

Preço por 1 milhão de tokens (em abril de 2026).⁵

Uma sessão típica consome 50K-200K tokens de entrada e 10K-50K tokens de saída. Sessão com Haiku: $0.10-$0.45. Sessão com Opus: $0.50-$2.25.

Modelo padrão por plano (Claude Code em 16 de abril de 2026):

• Max, Team Premium → Opus 4.7
• Pro, Team Standard, Enterprise, Anthropic API → Sonnet 4.6 (Enterprise + API mudam para Opus 4.7 em 23 de abril de 2026)
• Bedrock, Vertex, Foundry → Sonnet 4.5 (fixe uma versão mais nova via ANTHROPIC_DEFAULT_OPUS_MODEL)

Opus 4.7 exige Claude Code v2.1.111 ou posterior. Ele usa apenas raciocínio adaptativo (sem orçamentos fixos de thinking). O novo nível de esforço xhigh é o padrão para workloads de codificação/agênticos no Opus 4.7.

Troque de modelo durante uma sessão:

/model opus       # Switch to Opus (resolves to 4.7 on API, 4.6 on Bedrock/Vertex/Foundry)
/model sonnet     # Switch to Sonnet 4.6
/model haiku      # Switch to Haiku 4.5
/effort xhigh     # Opus 4.7 only — recommended for coding/agentic

Regra de decisão: Exploração simples vai para Haiku. Codificação diária sensível a custo vai para Sonnet. Raciocínio difícil, arquitetura, loops agênticos e análise de segurança vão para Opus. Use opusplan para refatorações complexas (Opus planeja, Sonnet executa).

15. Principais locais de arquivos

16. Changelog

17. Referências

Esta cheat sheet é a companheira de consulta rápida do guia completo do Claude Code CLI. Para tutoriais de configuração, veja o quickstart do Claude Code. Especificamente para projetos iOS e macOS, veja o guia de desenvolvimento de agentes para iOS, os padrões de integração do XcodeBuildMCP e a Apple Ecosystem Series. Última atualização em 24 de maio de 2026.