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-se:

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

Subcomando adicionado na v2.1.212: claude auto-mode reset redefine o estado do auto-mode pelo terminal; passe --yes para ignorar a solicitação de confirmação.⁷

3. Slash commands

Comandos personalizados: crie .claude/commands/my-command.md (projeto) ou ~/.claude/commands/my-command.md (pessoal) e execute com /my-command. Os comandos aceitam frontmatter YAML para descrição, ferramentas permitidas, substituição do modelo e interpolação de argumentos por $ARGUMENTS ou pelos parâmetros 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 em várias linhas

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

5. Arquivos de configuração

Hierarquia de precedência (da mais alta para a mais baixa)

A primeira correspondência prevalece. As configurações empresariais não podem ser ignoradas.

6. Referência do Settings.json

Principais configurações, com tipos e exemplos. Coloque-as 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 das regras de permissão: Tool(pattern:*) oferece correspondência por prefixo. Bash(npm run test:*) permite npm run test, npm run test:unit etc. Os padrões de arquivo usam a sintaxe glob: Edit(src/**). Desde a v2.1.214, uma regra allow dir/** de segmento único corresponde apenas a <cwd>/dir — e não mais a qualquer dir/ na árvore; use Edit(**/src/**) para correspondência em qualquer profundidade. As regras deny/ask mantêm a correspondência em qualquer profundidade, e as condições if: dos hooks recebem o mesmo escopo do cwd.

Novas chaves (v2.1.118+):

Para conhecer o schema completo das configurações, consulte o Guia detalhado 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 faz a leitura dele no início de cada sessão.

Onde 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

Facilite a leitura rápida. Textos densos desperdiçam tokens de contexto em todas as sessões. Use listas, tabelas e blocos de código curtos. Evite parágrafos longos — Claude lê o CLAUDE.md no início de cada sessão, então cada palavra consome 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 de um subdiretório é carregado quando Claude lê arquivos nesse diretório - Coloque regras compartilhadas pela equipe em .claude/rules/*.md para manter uma organização modular

8. Modos de permissão

O Auto Mode (v2.1.85+) é o substituto recomendado para --dangerously-skip-permissions. Operações somente leitura e edições de arquivos são aprovadas automaticamente. As regras personalizadas de permissão e negação são processadas primeiro. Todo o restante é enviado ao classificador de segurança. Ações bloqueadas automaticamente por padrão: curl | bash, force-push para a branch principal, deploys em produção, exclusões em massa na nuvem, alterações de IAM e envio externo de dados confidenciais.¹

Disjuntor: 3 bloqueios consecutivos ou 20 no total durante uma sessão fazem o sistema voltar às solicitações de confirmação manuais.

# Enable at startup (--enable-auto-mode was removed in v2.1.111)
claude --permission-mode auto

# Cycle during session
Shift+Tab    # Manual (aka default) -> acceptEdits -> auto -> plan

Aprovação automática do PowerShell (v2.1.119+): os comandos da ferramenta PowerShell são aprovados automaticamente no modo de permissão da mesma forma que os comandos Bash. Regras de permissão como PowerShell(Get-*:*) dispensam solicitações de confirmação para operações somente leitura. Use a v2.1.149 ou posterior em workflows que utilizam bastante o PowerShell; ela corrige falhas nas permissões do comando integrado cd, na correspondência de regras de permissão por prefixo/curinga e no rastreamento de variáveis de diretório desatualizadas.

9. Eventos de hooks

| InstructionsLoaded | Quando o CLAUDE.md é carregado | Não | | ConfigChange | Quando o arquivo de configuração muda durante a sessão | Sim | | DirectoryAdded | Quando /add-dir ou o register_repo_root de SDK adiciona um diretório de trabalho durante a sessão (v2.1.219+) | Não | | WorktreeCreate | Quando um worktree está sendo criado | Sim | | WorktreeRemove | Quando um worktree está sendo removido | Não | | PreCompact | Antes da compactação do contexto | Não | | PostCompact | Depois da compactação do contexto | Não | | Elicitation | Quando MCP solicita uma entrada estruturada | Sim | | ElicitationResult | Quando o usuário responde à caixa de diálogo de MCP | Sim | | StopFailure | Quando o turno termina devido a um erro de API | Não | | PermissionRequest | Quando a caixa de diálogo de permissão é exibida | Sim | | PermissionDenied | Quando o Auto Mode nega uma ação (v2.1.88+) | Não | | CwdChanged | Quando o diretório de trabalho muda (v2.1.83+) | Não | | FileChanged | Quando um arquivo monitorado é modificado externamente (v2.1.83+) | Não | | TaskCreated | Quando uma nova tarefa é criada (v2.1.84+) | Não | | TeammateIdle | Quando um membro da equipe de agents fica ocioso | Sim | | TaskCompleted | Quando uma tarefa é marcada como concluída | Sim |

Para conhecer o protocolo completo dos hooks (JSON de entrada/saída, matchers e códigos de saída), consulte o Guia detalhado de hooks no guia completo.

10. Configuração de hooks

Os 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 dos matchers:

Códigos de saída:

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

Campos de entrada/saída dos hooks:

• duration_ms na entrada dos hooks PostToolUse / PostToolUseFailure (v2.1.119+) — tempo de execução da ferramenta, excluindo as solicitações de permissão e os hooks PreToolUse.
• hookSpecificOutput.updatedToolOutput (v2.1.121+) — substitui a saída de qualquer ferramenta (a v2.1.118 introduziu esse recurso apenas para MCP; a v2.1.121 o estende para todas as ferramentas).
• hookSpecificOutput.sessionTitle (v2.1.96+) — define o título da sessão por meio de um hook UserPromptSubmit.
• args: string[] em hooks de comando (v2.1.139+) — passa um argv estruturado sem aspas do 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 do hook do agent (v2.1.140+) — identifica qual tipo de agent está em execução.
• terminalSequence na saída JSON do hook (v2.1.141+) — emite sequências de controle do terminal para notificações, títulos de janelas e alertas sonoros.

11. Configuração rápida do MCP

Adicione um servidor MCP com um único 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"
      }
    }
  }
}

O MCP agora registra 100 milhões de downloads mensais e mais de 3.000 servidores indexados.³ Para saber mais sobre tipos de transporte, elicitation e configuração de busca de ferramentas, consulte a seção sobre MCP no guia completo.

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

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

Nova tentativa automática (v2.1.121+): Servidores MCP que apresentam erro durante a inicialização têm até 3 novas tentativas antes de serem marcados como desconectados.

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

11.5. Comandos CLI de plugins

12. Tipos de subagents

O Claude delega tarefas automaticamente aos 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 ser executados em paralelo.⁴

Nas versões atuais, claude agents abre o Agent View: uma tela operacional em fase de prévia para pesquisa que exibe sessões Claude Code em execução, bloqueadas e concluídas. claude agents --cwd <path> restringe a visualização a uma pasta (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 painel 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 identifica com bg; a v2.1.145 adiciona claude agents --json, contagens de abas aguardando entrada e correções no painel de resposta do Agent View; a v2.1.147 adiciona sessões em segundo plano fixadas, que permanecem ativas quando ociosas e reiniciam no mesmo lugar para receber atualizações. Use o Agent View para monitoramento, não como prova de que o trabalho passou pelos critérios de qualidade.⁶

Campos do frontmatter de agentes personalizados:

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 modelos

Provedores de nuvem

Controle de comportamento

Configuração de ferramentas

Rede e proxy

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

14. Referência de custos

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

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

Modelo padrão no Claude Code (desde a v2.1.197, 30 de junho de 2026): Sonnet 5 para todas as novas sessões — contexto nativo de 1M, preços promocionais de $2/$10 até 31 de agosto — com o Opus acessível por meio de um único /model opus (desde a v2.1.219, esse alias seleciona o Opus 5). Os administradores podem definir um padrão para toda a organização, exibido como “Padrão da organização” em /model (v2.1.196+); no Bedrock/Vertex/Foundry, fixe um modelo específico por meio de ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL.

Sonnet 5, Opus 5, Opus 4.8 e Fable 5 usam somente raciocínio adaptativo (sem orçamentos fixos de raciocínio). effort usa high por padrão em todos eles, com /effort xhigh para os trabalhos de programação e agentes mais difíceis. Mudanças incompatíveis do Opus 5 em relação ao Opus 4.8: o raciocínio é ativado por padrão nas requisições que omitem o campo thinking, e thinking: {type: "disabled"} com o nível de esforço xhigh ou max retorna um erro 400.

O modo rápido (/fast) aplica-se somente ao Opus 5 e ao Opus 4.8 desde a v2.1.219 — $10 / $50 por MTok (2× o preço-base) para até 2,5× mais tokens de saída por segundo. O Opus 4.7 foi removido: claude-opus-4-7 + speed: "fast" agora gera um erro em vez de retornar à velocidade padrão. Prévia de pesquisa, somente para Claude API (não disponível no Bedrock/Vertex/Foundry); alternar entre velocidades invalida o cache de prompts.

Alterne entre modelos durante uma sessão:

/model opus       # Switch to Opus 5 (v2.1.219+)
/model sonnet     # Switch to Sonnet 5 (the default)
/model haiku      # Switch to Haiku 4.5
/model fable      # Switch to Fable 5 (tier above Opus)
/effort xhigh     # Recommended for the hardest coding/agentic work

Regra de decisão: use o Haiku para explorações simples. Use o Sonnet para programação cotidiana com foco em custos. Use o Opus para raciocínio complexo, arquitetura, loops de agentes e análise de segurança. Use opusplan para refatorações complexas (o Opus planeja, o Sonnet executa).

15. Localização dos principais arquivos

16. Histórico de alterações

17. Referências

Esta folha de consulta rápida complementa o guia completo do Claude Code CLI. Para instruções passo a passo de configuração, consulte o guia de início rápido do Claude Code. Para projetos específicos de iOS e macOS, consulte o guia de desenvolvimento de agentes para iOS, os padrões de integração do XcodeBuildMCP e a série sobre o ecossistema Apple. Última atualização em 17 de julho de 2026.