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; use --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 meio de $ARGUMENTS ou dos 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 meio de /keybindings (armazenados em ~/.claude/keybindings.json).

5. Arquivos de configuração

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

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

6. Referência do settings.json

Principais configurações, com tipos e exemplos. Coloque-as em qualquer arquivo de configuração 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
  },
  "cleanupPeriodDays": 30,
  "respectGitignore": true,
  "showTurnDuration": true,
  "language": "en",
  "autoMemoryDirectory": ".claude/memory",
  "plansDirectory": ".claude/plans"
}

Sintaxe das regras de permissão: Tool(pattern:*) faz a 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 somente a <cwd>/dir — e não mais a qualquer dir/ em qualquer nível da árvore; use Edit(**/src/**) para corresponder 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 conferir o esquema completo das configurações, consulte o Aprofundamento sobre 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:

AGENTS.md (v2.1.277+): em um projeto sem CLAUDE.md, Claude Code lê AGENTS.md como alternativa – altere esse comportamento em “Project instructions” no /config (ainda não disponível no Bedrock/Vertex/Foundry).

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 o conteúdo fácil de consultar. Textos corridos e densos desperdiçam tokens de contexto em todas as sessões. 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, portanto, cada palavra consome contexto.

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

8. Modos de permissão

O Auto Mode (v2.1.85+) é o modo de permissão padrão para novas sessões nos planos Pro, Max e Team desde 14 de agosto de 2026 (um defaultMode definido por você continua válido até que você aceite a solicitação de troca exibida uma única vez; disableAutoMode desativa esse modo em toda a organização). Ele é o substituto recomendado para --dangerously-skip-permissions. Ações somente leitura e edições de arquivos são aprovadas automaticamente; desde a v2.1.281, quando a análise do classificador passou a ser executada no servidor, comandos shell somente leitura e executados em sandbox também aguardam essa análise e são bloqueados quando sinalizados. As regras personalizadas de allow/deny são resolvidas primeiro. Todo o restante é enviado ao classificador de segurança. Bloqueados automaticamente por padrão: curl | bash, force-push para a main, deploys em produção, exclusões em massa na nuvem, alterações de IAM e envio de dados confidenciais para serviços externos.¹

Disjuntor: após 3 bloqueios consecutivos ou 20 no total durante uma sessão, o modo volta a solicitar confirmação manual.

rm perigoso em modos autônomos (v2.1.281): no modo auto e com --dangerously-skip-permissions, a solicitação de confirmação de um rm perigoso aguarda 2 minutos e depois nega o comando com uma sugestão de reescrita, permitindo que a sessão continue. Um rm recursivo cujo destino consiste apenas na saída de uma substituição de comando, como rm -rf "$(pwd)", agora solicita confirmação mesmo com uma regra allow do Bash.

# 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 no PowerShell (v2.1.119+): os comandos da ferramenta PowerShell são aprovados automaticamente pelo modo de permissão da mesma forma que os comandos do Bash. Regras allow como PowerShell(Get-*:*) dispensam solicitações de confirmação em operações somente leitura. Use a v2.1.149 ou mais recente em workflows que usam bastante o PowerShell; ela corrige desvios de permissão do comando cd integrado, a correspondência de regras allow com prefixos e curingas e o rastreamento obsoleto de variáveis de diretório.

9. Eventos de hooks

| InstructionsLoaded | CLAUDE.md é carregado | Não | | ConfigChange | O arquivo de configuração é alterado durante a sessão | Sim | | DirectoryAdded | /add-dir ou SDK register_repo_root adiciona um diretório de trabalho durante a sessão (v2.1.219+) | Não | | WorktreeCreate | Durante a criação de um worktree | Sim | | WorktreeRemove | Durante a remoção de um worktree | Não | | PreCompact | Antes da compactação do contexto | Não | | PostCompact | Após a compactação do contexto | Não | | Elicitation | MCP solicita uma entrada estruturada | Sim | | ElicitationResult | O usuário responde à caixa de diálogo de MCP | Sim | | StopFailure | O turno termina devido a um erro de API | Não | | PermissionRequest | A caixa de diálogo de permissão é exibida | Sim | | PermissionDenied | O modo automático nega uma ação (v2.1.88+) | Não | | CwdChanged | O diretório de trabalho é alterado (v2.1.83+) | Não | | FileChanged | Um arquivo monitorado é modificado externamente (v2.1.83+) | Não | | TaskCreated | Uma nova tarefa é criada (v2.1.84+) | Não | | TeammateIdle | Um membro da equipe de agentes fica ocioso | Sim | | TaskCompleted | Uma tarefa é marcada como concluída | Sim |

Para conhecer o protocolo completo de hooks (JSON de entrada/saída, matchers e códigos de saída), consulte o guia detalhado sobre 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 solicitações de permissão e 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 a partir de um hook UserPromptSubmit.
• args: string[] em hooks de comando (v2.1.139+) — passa argv estruturado sem uso de 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 de hooks de agentes (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 do terminal para notificações, títulos de janelas e sinais sonoros.

11. Configuração rápida de 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"
      }
    }
  }
}

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

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

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

Novas tentativas automáticas (v2.1.121+): Servidores MCP que apresentarem erro durante a inicialização terão até 3 novas tentativas antes de serem marcados como desconectados.

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

11.5. Comandos de CLI para plugins

12. Tipos de subagents

Claude delega tarefas automaticamente a 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.⁴

claude agents abre a Agent View nas versões atuais: uma tela de operações em versão preliminar para pesquisa que mostra sessões Claude Code em execução, bloqueadas e concluídas. claude agents --cwd <path> restringe 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 maneira 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 compatibilidade com /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 da Agent View; a v2.1.147 adiciona sessões em segundo plano fixadas, que permanecem ativas quando ociosas e são reiniciadas no mesmo lugar para receber atualizações. Use a 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 ver 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 setembro 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 5.5: $0.40-$1.80.

Modelo padrão no Claude Code (por plano): Opus em todos os planos desde a v2.1.280 (22 de setembro de 2026) – Pro e Team Standard migraram do Sonnet para o Opus, assim como Max, Team Premium e Enterprise – e o modelo Opus padrão é o Opus 5.5 (claude-opus-5-5), para o qual o alias opus agora aponta. A divisão da v2.1.251 (Opus 5 nos planos premium, Sonnet 5 no Pro/Team Standard) e o Sonnet 5 como padrão em todos os planos na v2.1.197 ficaram no passado. Os administradores podem definir um padrão para toda a organização, exibido como “Padrão da organização” em /model (v2.1.196+). A Claude Platform na AWS, o Amazon Bedrock e a Agent Platform do Google Cloud também usam o Opus 5.5 como padrão; o Microsoft Foundry é a única exceção (o padrão é o Sonnet 4.5 e é o único lugar onde opus aponta para o Opus 4.6) – fixe um modelo específico por meio de ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL.

Opus 5.5, Sonnet 5, Opus 5, Opus 4.8, Fable 5 e Fable 5.1 usam apenas raciocínio adaptativo (sem orçamentos fixos de thinking), com /effort xhigh para os trabalhos de programação e tarefas agênticas mais difíceis. O padrão de effort é high em todos eles, exceto no Opus 5.5, cujo padrão é medium – e, desde a v2.1.280, um nível de effort salvo antes de /effort passar a ser específico de cada modelo não é mais aplicado a modelos recém-lançados, como o Opus 5.5; portanto, ele começa com o próprio padrão até que você escolha outro. O thinking não pode ser desativado no Opus 5.5 nem nos modelos Fable (MAX_THINKING_TOKENS=0 não tem efeito neles). Mudanças incompatíveis do Opus 5 em relação ao Opus 4.8: o thinking fica ativado por padrão nas solicitações que omitem o campo thinking, e thinking: {type: "disabled"} com effort xhigh ou max retorna um erro 400.

O Fast mode (/fast) é compatível com Opus 5.5, Opus 5 e Opus 4.8, sendo o Opus 5.5 o padrão desde a v2.1.280 – $8 / $40 por MTok no Opus 5.5, $10 / $50 no Opus 5 e 4.8 (2× o preço-base em cada caso) para obter 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 voltar à velocidade padrão. Disponível em versão preliminar para pesquisa, apenas no API da Claude e em assinaturas (não no Bedrock/Vertex/Foundry nem na Claude Platform na AWS); alternar entre velocidades invalida o cache do prompt. Desde a v2.1.271, o Fast mode também funciona em sessões remotas do Claude Code (runners na nuvem e auto-hospedados): a configuração de Fast mode do host ou /fast digitado na sessão é aplicada quando permitido pela sua organização.

Alterne entre modelos durante uma sessão:

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

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

15. Principais locais de arquivos

16. Changelog

17. Referências

Esta folha de consulta rápida complementa o guia completo do Claude Code CLI. Para ver instruções de configuração passo a passo, consulte o guia de início rápido do Claude Code. Especificamente para projetos 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.