Guia Completo de Claude Code

🚀Instalação e Setup

Claude Code é o CLI agêntico da Anthropic — lê seu código, edita arquivos, roda comandos e integra com git/GitHub/CI. Roda no terminal, tem extensão VS Code, plugin JetBrains e app desktop.

Instalação nativa (recomendada)

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

# 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

# Homebrew (macOS/Linux) - nao auto-atualiza
brew install --cask claude-code

# WinGet (Windows) - nao auto-atualiza
winget install Anthropic.ClaudeCode

Primeiro uso

# Entre em qualquer projeto e rode:
cd ~/meu-projeto
claude

# Na primeira execucao, o CLI pede login via navegador:
# 1) Conta Claude (assinatura Pro, Max ou Team)
# 2) Anthropic Console (API key com billing proprio)
# 3) Amazon Bedrock / Google Vertex AI / Microsoft Foundry (empresas)

Verificando a instalação

claude --version          # ex.: 2.1.59
claude --help             # lista todas as flags
claude doctor             # diagnostico de ambiente
claude config list        # configuracoes ativas

Formas de invocar

Autenticação e modelos

# Trocar de modelo durante a sessao
/model                    # abre seletor
/model claude-opus-4-5    # Opus para tarefas complexas
/model claude-sonnet-4-5  # Sonnet para velocidade

# Ou via flag no arranque
claude --model claude-opus-4-5

# Logout / trocar conta
claude logout
claude login

⌨️Interface e Comandos Básicos

O Claude Code é um REPL — cada linha digitada é uma mensagem para o agente. A interface tem atalhos, slash commands e um modo de escape para shell direto.

Slash commands essenciais

/help              # lista todos os comandos disponiveis
/init              # analisa o repo e gera CLAUDE.md automaticamente
/clear             # limpa a sessao atual (novo contexto)
/compact           # resume a conversa e libera tokens
/model             # troca de modelo (Opus, Sonnet, etc.)
/memory            # abre gestor de CLAUDE.md e auto memory
/review            # revisa a PR atual (skill bundled)
/security-review   # audita mudancas por falhas de seguranca
/permissions       # gerencia allow/deny de ferramentas
/config            # abre editor de configuracoes
/agents            # lista e gerencia subagents
/hooks             # abre editor de hooks
/mcp               # lista servidores MCP e ferramentas
/login /logout     # autenticacao
/status            # mostra sessao, modelo, diretorios
/cost              # custo da sessao atual em tokens/USD
/exit              # encerra o CLI

Atalhos de teclado

• Tab — autocompletar slash commands, skills e @mentions de arquivo
• ↑ / ↓ — navegar no histórico de prompts
• Esc — cancela a resposta em andamento
• Esc Esc (dois toques) — ativa plan mode (planeja antes de editar)
• Ctrl+C — interrompe sem sair
• Ctrl+D — sai do REPL
• Shift+Tab — alterna entre modos (plan / accept-edits / default)
• ! no início — prefixo de bash escape (executa shell direto)
• # no início — grava rapidamente no CLAUDE.md ou auto memory
• @ — menciona arquivo ou diretório (carrega no contexto)

Bash escape e menções

# Prefixo ! - roda o comando no shell do host, sem passar pelo agente
!ls -la
!git status
!pnpm test

# Mencao @ - injeta o conteudo do arquivo/dir no contexto
Revise @src/lib/api.ts e encontre problemas de tipagem.
Baseado em @content/docs/mercado-financeiro, crie um indice.

# # no inicio - grava como memoria (pergunta onde salvar)
# sempre use pnpm, nunca npm, neste projeto

Flags úteis no arranque

claude --model claude-opus-4-5         # modelo especifico
claude --add-dir ../docs ../shared     # diretorios extras
claude --permission-mode plan          # inicia em plan mode
claude --append-system-prompt "..."    # anexa ao system prompt
claude -p "fix the failing tests"      # one-shot nao-interativo
claude -c                              # continua a sessao anterior
claude --resume <session-id>           # retoma sessao especifica
claude --dangerously-skip-permissions  # aceita tudo (use com cautela!)

🛠Ferramentas do Agente

Por baixo dos panos, Claude usa um conjunto de ferramentas (tools) para agir no seu código. Entender quais são e como autorizar cada uma evita surpresas e melhora a previsibilidade.

Ferramentas nativas

Como Claude escolhe a ferramenta

• Procurar arquivo por nome? Glob, não find.
• Procurar conteúdo? Grep, não grep ou rg.
• Ler arquivo? Read, não cat/head/tail.
• Editar? Edit (diff pequeno); Write só para criação ou rewrite total.
• Rodar algo? Bash com comando específico e timeout.

Permission modes

# Modos principais - alternados com Shift+Tab no REPL

# 1) default (ask)
#    Pergunta antes de usar ferramentas que escrevem/executam.
#    Read/Glob/Grep costumam ser allowed por padrao.

# 2) acceptEdits
#    Aceita Edit/Write automaticamente, mas pergunta em Bash.

# 3) plan
#    So investiga (read-only). Nao edita nem roda comandos.
#    Ao final, apresenta um plano para voce aprovar.

# 4) bypassPermissions  (cuidado!)
#    Aceita tudo sem perguntar.
#    Ative so com --dangerously-skip-permissions.

Allowlist / denylist

// .claude/settings.json - regras persistentes de permissao
{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Bash(pnpm lint:*)",
      "Read(//Users/kaique/Developer/**)",
      "Edit(src/**)",
      "WebFetch(domain:docs.anthropic.com)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Write(.env*)",
      "Edit(.env*)"
    ],
    "ask": [
      "Bash(curl *)",
      "Bash(npm publish*)"
    ]
  }
}

🧠CLAUDE.md e Memória

Cada sessão do Claude começa com contexto zero. Dois mecanismos carregam conhecimento entre sessões: CLAUDE.md (você escreve) e auto memory (Claude escreve sobre o projeto).

Hierarquia de CLAUDE.md

# Todos os arquivos abaixo sao CONCATENADOS (nao substituem).
# Ao subir na arvore, Claude le CLAUDE.md em cada diretorio ancestral.

# 1) Managed policy (IT/DevOps da empresa)
/Library/Application Support/ClaudeCode/CLAUDE.md     # macOS
/etc/claude-code/CLAUDE.md                            # Linux/WSL
C:\Program Files\ClaudeCode\CLAUDE.md                 # Windows

# 2) User (pessoal, todos os projetos)
~/.claude/CLAUDE.md

# 3) Project (compartilhado via git)
./CLAUDE.md
./.claude/CLAUDE.md

# 4) Local (pessoal neste projeto; nao commitar)
./CLAUDE.local.md         # adicione ao .gitignore

Exemplo de CLAUDE.md eficaz

# CLAUDE.md

## Stack do projeto
- Next.js 16 + App Router + Fumadocs
- TypeScript strict, Tailwind v4, pnpm 10
- Backend Go em backend/api/ (Gin + MongoDB + Redis)

## Comandos
- Dev: `pnpm dev` (http://localhost:3000)
- Lint: `pnpm lint:fix` (obrigatorio antes de commit)
- Build: `pnpm build` (requer GO_API_URL no .env.local)
- Testes unitarios: `pnpm vitest run` - NUNCA usar Jest
- E2E: `pnpm test`

## Convencoes
- Indentacao 2 espacos, sem tabs
- Links internos: `<Link>` do Next, nunca `<a href>`
- Commits: Conventional Commits em portugues

## Arquivos importantes
- Acesso a API: @src/lib/api.ts
- Config do site: @src/config/site.ts
- Guia de docs: @docs/git-workflow.md

## Proibicoes
- Nao recriar src/models/ nem src/lib/mongodb.ts
- Nao usar Jest - apenas Vitest
- Nao commitar sem rodar pnpm lint:fix antes

Imports com @path

# CLAUDE.md aceita imports recursivos (ate 5 niveis de profundidade)

Projeto: @README.md
Scripts disponiveis: @package.json
Convencoes de git: @docs/git-instructions.md
Preferencias pessoais: @~/.claude/my-prefs.md

# Paths relativos resolvem ao arquivo que contem o import
# (nao ao cwd). Absolutos e ~/ tambem funcionam.

Auto memory

# Claude escreve notas proprias em:
~/.claude/projects/<projeto>/memory/
├── MEMORY.md          # indice (primeiras 200 linhas / 25KB carregadas)
├── debugging.md       # insights de debug
├── patterns.md        # padroes descobertos
└── preferences.md     # preferencias suas que ele notou

# Ativar/desativar
/memory                      # abre painel com toggle
# via settings.json:
{ "autoMemoryEnabled": false }

# Shortcut para adicionar memoria durante a conversa
# basta digitar uma linha comecando com #:
# sempre rode pnpm format antes de commitar

.claude/rules/ — regras modulares

# Para projetos grandes, divida CLAUDE.md em arquivos tematicos
your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── api-design.md

# Rules podem ser path-scoped via frontmatter YAML:
---
paths:
  - "src/api/**/*.ts"
  - "backend/**/*.go"
---

# Estas regras so carregam quando Claude le arquivos no padrao.

🔌Hooks, Skills e MCP

Três formas de estender Claude Code: hooks disparam scripts em eventos do ciclo de vida, skills empacotam workflows reutilizáveis e MCP conecta fontes de dados externas.

Hooks — automação determinística

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint:fix",
            "timeout": 30
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push*)",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-branch.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date)] $CLAUDE_PROMPT\" >> ~/.claude-log"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "say 'Claude terminou'" }
        ]
      }
    ]
  }
}

Eventos de hook

Skills — comandos customizados

# ~/.claude/skills/commit/SKILL.md - pessoal, todos os projetos
# ou .claude/skills/commit/SKILL.md - compartilhado via git

---
name: commit
description: Cria commit com mensagem convencional em portugues
disable-model-invocation: true      # so voce invoca, Claude nao
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) Bash(git diff*)
---

Faca um commit das mudancas atuais:

1. Rode `git status` para ver arquivos modificados
2. Rode `git diff --staged` para revisar o que vai no commit
3. Analise os arquivos e escolha um escopo (feat, fix, refactor, docs, chore)
4. Escreva mensagem em portugues no padrao:
   <tipo>(<escopo>): <descricao curta no imperativo>
5. Execute `git commit -m` com a mensagem gerada
6. Confirme com `git status` apos

Tipos de skill

MCP — Model Context Protocol

# MCP conecta Claude a fontes externas: bancos de dados, APIs, Slack, Jira.
# Instala servidores via CLI:
claude mcp add postgres \
  --command "npx -y @modelcontextprotocol/server-postgres" \
  --env POSTGRES_URL=postgresql://localhost/mydb

claude mcp add github \
  --command "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=$GH_TOKEN

# Listar servidores configurados
claude mcp list

# Gerenciar durante a sessao
/mcp             # mostra servidores e ferramentas disponiveis

# Ou via settings.json:
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": { "MDB_URI": "mongodb://localhost:27017" }
    }
  }
}

⚡Workflow Avançado

Dominando planning mode, subagents, compaction e integração com git, Claude Code deixa de ser "assistente" e vira um multiplicador real de produtividade.

Plan mode (Esc Esc)

# Dois toques em Esc (ou Shift+Tab para alternar) entram em plan mode.
# Claude investiga (Read/Glob/Grep), mas NAO edita nem roda comandos.
# Ao final, mostra um plano detalhado para aprovacao antes de executar.

# Exemplo de fluxo:
> Esc Esc
[plan mode ativo]
> Migre todas as chamadas de axios para fetch nativo.

-> Claude explora src/, lista os 23 arquivos afetados, descreve
  as mudancas, mostra riscos e pede confirmacao.
-> Voce aprova com Enter ou volta ao modo default com Shift+Tab.

# Inicie ja em plan mode:
claude --permission-mode plan

Extended thinking

# Inclua a palavra "think" no prompt para aumentar o orcamento de raciocinio.
# Mais "think" = mais tokens de thinking antes da resposta final.

think            # nivel basico
think hard       # medio
think harder     # alto
ultrathink       # maximo (use em planejamento arquitetural)

# Exemplo:
"ultrathink: desenhe a arquitetura de cache para esta API Go,
 considerando latencia, invalidacao e custo de memoria."

Subagents

# Agents rodam em contexto isolado - nao poluem a conversa principal.
# Ideais para busca paralela, especializacao e tarefas longas.

# .claude/agents/explorer.md
---
name: explorer
description: Especialista em explorar grandes codebases sem editar
tools: Read, Glob, Grep, Bash
model: claude-sonnet-4-5
---

Voce e um agente de exploracao. NUNCA edite arquivos.
Encontre padroes, liste arquivos relevantes, mapeie dependencias
e retorne um sumario estruturado ao agente principal.

# Usar via Task tool (Claude delega automaticamente)
# ou invocar explicitamente:
/agents
# -> selecione explorer -> descreva a tarefa

Compaction — sessões longas

# Quando o contexto enche, Claude compacta automaticamente.
# Ele resume a conversa e descarta detalhes, preservando:
#   - CLAUDE.md (re-injetado do disco)
#   - Skills invocadas recentemente (budget de 25k tokens)
#   - Resumo da conversa anterior
#   - Mensagem atual

# Comandos manuais:
/compact                             # compacta agora com resumo inteligente
/compact focus on the failing tests  # compacta com foco especifico
/clear                               # limpa tudo e comeca fresh (perde contexto!)

# Boa pratica: /compact entre fases de trabalho grande.
# Ex.: depois de terminar um refactor, antes de comecar testes.

Git workflow com skills nativas

# Peca em linguagem natural - Claude conhece git profundamente
"Crie um commit com as mudancas atuais, mensagem em portugues, conventional commits"

"Abra uma PR para main com titulo curto e checklist de testes no corpo"

"Veja os 5 ultimos commits, identifique o que quebrou o lint e reverta apenas aquele"

# Skills bundled uteis:
/review                # revisa PR atual (usa gh pr view)
/security-review       # audita branch por falhas de seguranca
/init                  # gera CLAUDE.md inicial do repo

# Em CI, use a action oficial no GitHub Actions:
# .github/workflows/claude.yml
#   uses: anthropics/claude-code-action@v1

Scheduled tasks e loops

# /loop - repete um prompt em intervalo (dentro da sessao)
/loop 5m /babysit-prs
/loop 30s verifique se o deploy subiu

# /schedule - agenda agents remotos (rodam mesmo com a maquina desligada)
/schedule                         # abre configurador
# Exemplos: "revisao diaria de PRs as 9h", "auditoria semanal de deps"

# Claude Code tambem roda no browser (claude.ai/code) e no app iOS,
# permitindo continuar sessoes do celular com claude --teleport.

Best practices consolidadas

• Comece com /init em cada projeto novo para gerar CLAUDE.md base.
• Use Esc Esc para mudanças grandes — aprovar o plano antes evita retrabalho.
• CLAUDE.md curto e específico bate longo e vago — Claude segue com mais aderência.
• Hooks para o que tem que acontecer sempre (lint, format); skills para o que depende do contexto.
• /compact entre fases de trabalho para manter o contexto limpo.
• Prefira -p (one-shot) em scripts — determinístico e stream-friendly.
• Commits pequenos e seguidos deixam Claude trabalhar em pedaços — mais seguro e reversível.
• Sempre revise diffs antes de aceitar em acceptEdits — IA erra, nós também.