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

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. Comandos slash

Comandos personalizados: Crie .claude/commands/my-command.md (projeto) ou ~/.claude/commands/my-command.md (pessoal) e invoque com /my-command. Os comandos oferecem suporte a frontmatter YAML para descrição, ferramentas permitidas, sobrescrita de modelo e interpolação de argumentos via $ARGUMENTS ou posições $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 keybindings podem ser personalizados via /keybindings (armazenados em ~/.claude/keybindings.json).

5. Arquivos de configuração

Hierarquia de precedência (maior para menor)

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

6. Referência do settings.json

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

Sintaxe de regra de permissão: Tool(pattern:*) faz 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 ver o schema completo de configurações, consulte Configuration Deep Dive 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 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 em toda sessão. Use listas, 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 consome contexto.

Dicas avançadas: - Use o prefixo # no REPL para adicionar coisas à auto-memory sem editar 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

Modo auto (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 cloud, alterações de IAM, envio de dados sensíveis para fora.¹

Circuit breaker: 3 bloqueios consecutivos ou 20 no total em uma sessão pausam de volta 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 prompts para operações somente leitura.

9. Eventos de hooks

| InstructionsLoaded | CLAUDE.md carregado | Não | | ConfigChange | Arquivo de config muda durante a sessão | Sim | | WorktreeCreate | Worktree sendo criado | Sim | | WorktreeRemove | Worktree sendo removido | Não | | PreCompact | Antes da compactação do contexto | Não | | PostCompact | Depois da compactação do contexto | Não | | Elicitation | MCP solicita entrada estruturada | Sim | | ElicitationResult | Usuário responde ao diálogo de MCP | Sim | | StopFailure | Turno termina por erro de API | Não | | PermissionRequest | Diálogo de permissão exibido | Sim | | PermissionDenied | Modo auto nega uma ação (v2.1.88+) | Não | | CwdChanged | Diretório de trabalho muda (v2.1.83+) | Não | | FileChanged | Arquivo observado modificado externamente (v2.1.83+) | Não | | TaskCreated | Nova task criada (v2.1.84+) | Não | | TeammateIdle | Integrante da equipe de agents fica ocioso | Sim | | TaskCompleted | Task marcada como concluída | Sim |

Para ver o protocolo completo de hooks (input/output JSON, matchers, códigos de saída), consulte Hooks Deep Dive 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 matcher:

Códigos de saída:

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

Campos de output / input de hook:

• duration_ms no input de hook PostToolUse / PostToolUseFailure (v2.1.119+) — tempo de execução da tool excluindo prompts de permissão e hooks PreToolUse.
• hookSpecificOutput.updatedToolOutput (v2.1.121+) — substitui o output 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 shell quoting.
• continueOnBlock em hooks PostToolUse (v2.1.139+) — devolve o motivo do bloqueio para Claude e continua o turno.
• subagent_type no input de hook de agent (v2.1.140+) — identifica qual tipo de agent está rodando.

11. Configuração rápida do 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 busca de tools, consulte a seção de MCP no guia completo.

alwaysLoad (v2.1.121+): Tire um servidor confiável da postergação do Tool Search. Todas as suas tools carregam no início da sessão, sem round-trip de ToolSearch:

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

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

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

11.5. Comandos de Plugin CLI

12. Tipos de subagents

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

Custom subagents 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 o Agent View nas versões atuais: uma tela de operações em preview de pesquisa para sessões Claude Code em execução, bloqueadas e concluídas. Use para monitoramento, não como prova de que o trabalho passou pelos critérios de qualidade.⁶

Campos de frontmatter de custom agent:

Exemplo de custom agent (.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 do modelo

Provedores de nuvem

Controle de comportamento

Configuração de ferramentas

Rede e proxy

Para a lista completa, veja Environment Variables 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 reasoning adaptativo (sem orçamentos fixos de thinking). O novo nível de esforço xhigh é o padrão para cargas de trabalho de coding/agentic no Opus 4.7.

Trocar modelos 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. Coding diário sensível a custo vai para Sonnet. Reasoning difícil, arquitetura, loops agentic e análise de segurança vão para Opus. Use opusplan para refatoração complexa (Opus planeja, Sonnet executa).

15. Locais dos principais arquivos

16. Registro de alterações

17. Referências

Este guia de consulta rápida é o complemento de consulta rápida do guia completo de Claude Code CLI. Para passo a passo de configuração, veja o quickstart do Claude Code. Especificamente para projetos iOS e macOS, veja o guia iOS Agent Development, os padrões de integração XcodeBuildMCP e a Apple Ecosystem Series. Última atualização em 13 de maio de 2026.