Manual de Boas Práticas com Claude Code

Por Que o Claude Code Muda Tudo

O Claude Code transforma a IA de uma ferramenta de chat que você visita em uma camada de sistema operacional que roda por todo o seu fluxo de trabalho.

O Que o Claude Code Pode Fazer

📁 Acesso Total ao Sistema de Arquivos

Leia, escreva, crie e organize qualquer arquivo. Sem limites de upload.

Impacto: "Processe 10.000 arquivos em minutos ao invés de horas de upload manual"

⚙️ Execução de Comandos e Ferramentas

Rode comandos de shell, execute scripts, gerencie Git, instale pacotes — tudo através de linguagem natural.

Impacto: "Não-programadores rodando comandos bash sem aprender sintaxe"

🔌 Conexões MCP (200+ Ferramentas)

Conecte-se a GitHub, Notion, Slack, Jira, bancos de dados, APIs.

Impacto: "Uma interface para todo o seu ecossistema de ferramentas"

🤖 Trabalho Multi-Agente Autônomo

Sub-agentes trabalham em paralelo, checkpoints permitem voltar atrás, tarefas em background rodam enquanto você trabalha.

Impacto: "Delegue como se tivesse 5 desenvolvedores juniors"

O Workflow do Claude Code

O Claude Code opera em 4 fases que se repetem:

Pré-requisitos e Planos

Requisitos do Sistema

Planos e Preços

Instalação no Terminal (CLI)

Caminho Recomendado: Usar com Cursor

1. Baixe o Cursor em cursor.com
2. Abra seu projeto no Cursor
3. Abra terminal (View → Terminal)
4. Digite claude e Enter
5. Autentique via browser

macOS / Linux

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

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

Verificação e Primeiro Uso

claude --version
cd ~/seu-projeto
claude

Integração com VS Code

Instalação

1. Extensions (Cmd+Shift+X / Ctrl+Shift+X)
2. Pesquise "Claude Code"
3. Instale a extensão oficial da Anthropic
4. Reinicie se necessário

Onde Encontrar

• Spark icon (canto superior direito)
• Activity Bar (sidebar esquerda)
• Command Palette → "Claude Code"

Checkpoints (Exclusivo)

• Fork conversation — novo branch mantendo mudanças
• Rewind code — reverte mudanças no código
• Fork + Rewind — ambos

Comandos Essenciais e Atalhos

Slash Commands

Atalhos de Teclado

Referências de Arquivo

@filename → @report.csv | @folder/ → @data/ | Tab → Autocomplete

Skills e CLAUDE.md

CLAUDE.md — Memória do Projeto

Responde 3 perguntas: O QUÊ (stack, dirs, arquitetura), POR QUÊ (propósito, decisões), COMO (comandos, gotchas, regras).

# Projeto: Marketing Dashboard
## Commands
- npm run build
- npm test
## Style Guide
- Use TypeScript
- Follow existing patterns
## Important Context
- Main data source: /data/analytics.csv
- Deploy target: vercel

Hierarquia (cascading)

Skills (Automações Reutilizáveis)

# .claude/skills/testing/SKILL.md
---
name: testing patterns
description: Jest testing patterns for React
allowed tools: Read, Grep, Glob
---
# Testing Patterns
Use describe + it + AAA pattern
Use factory mocks

O campo description é CRÍTICO — determina a auto-ativação.

Plan Mode

Como Funciona

1. Ative com /plan ou Shift+Tab
2. Descreva a tarefa
3. Claude analisa arquivos e dependências
4. Apresenta plano passo a passo
5. Você aprova, ajusta ou rejeita

Quando Usar

• Refatorações multi-arquivo
• Features novas complexas
• Codebases desconhecidos
• Aprendizado

> /plan
> Refatorar autenticação para JWT no lugar de cookies de sessão.

Claude responde:
1. Analisar auth/session.py e middleware.py
2. Criar auth/jwt_handler.py
3. Atualizar rotas
4. Modificar testes
5. Atualizar CLAUDE.md

Técnicas de Prompting

Pro Pattern: Checkpoint + Iterate

1. Peça um plano primeiro
2. Revise o plano
3. Execute com checkpoints
4. Rewind se errar (Esc Esc)
5. Itere com feedback específico

Modelos Disponíveis

> /model
> Selecione: claude-sonnet-4-6 ou claude-opus-4-6

Conecte Tudo com MCP

MCP (Model Context Protocol) é USB-C para IA: um protocolo, centenas de conexões.

claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp list

Workflow Combinado

Via pipe (CLI)

claude -p "Rode testes, corrija falhas e explique."
cat error.log | claude -p "Analise e sugira correções."
git diff main..feat/nova | claude -p "Faça code review."

Dicas e Boas Práticas

Para Resultados Melhores

• Sempre comece com CLAUDE.md configurado
• Prompts específicos > vagos
• Use /plan antes de mudanças grandes
• Limite contexto com @-mentions
• Sonnet 80%, Opus 20%
• Revise antes de aprovar
• Use /clear entre tarefas

Erros Comuns

Estrutura de Arquivos do Projeto

your_project/
├─ CLAUDE.md
├─ .claude/
│  ├─ settings.json        # Config compartilhada (Git)
│  ├─ settings.local.json  # Config local (não vai pro Git)
│  ├─ skills/
│  │  ├─ code-review/SKILL.md
│  │  └─ testing/SKILL.md
│  ├─ commands/
│  │  └─ deploy.md         # Vira /deploy
│  └─ agents/
│     └─ security-reviewer.md
├─ arc/
└─ .gitignore

Extended Thinking e Ultrathink

> ultrathink: Analise a arquitetura inteira e proponha refatoração

Auto Memory (MEMORY.md)

O MEMORY.md é gerado automaticamente pelo Claude. Persiste entre sessões por workspace.

/memory  # Ver e editar memórias salvas

Hooks — Automação Determinística

Hooks são callbacks que SEMPRE executam (determinísticos), diferente de skills (probabilísticas).

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "scripts/sec.sh",
        "timeout": 5
      }]
    }]
  }
}

Exit codes: 0 = allow, 2 = block

Permissões e Segurança

{
  "permissions": {
    "allow": ["Read:*", "Bash:git:*", "Write:*:*.md"],
    "deny": ["Read:env:*", "Bash:sudo:*"]
  }
}

Arquitetura de 4 Camadas

• L1 fornece contexto base para todas as camadas
• L2 ativa automaticamente baseado no contexto
• L3 valida antes/depois de cada ação
• L4 opera em paralelo com skills e contexto próprios

Workflow Diário Recomendado

Top 10 Plugins — Guia de Instalação

Custom Commands, Worktrees e /batch

Custom Slash Commands

Crie .claude/commands/deploy.md → vira /deploy automaticamente.

/batch — Execução Paralela

/batch "Migre todos os componentes React de class para hooks"
# Analisa → Cria worktrees → Executa paralelo → Abre PRs

Git Worktrees

• EnterWorktree — trabalha em branch isolado
• ExitWorktree — volta ao principal

Agent SDK e Headless Mode

Agent SDK (Python/TypeScript)

from anthropic import Agent
agent = Agent(model="claude-sonnet-4-6", enable_file_checkpointing=True)
result = agent.run("Analise o projeto e gere testes")

Headless em CI/CD

claude -p "Rode testes e reporte" --json
claude --bare -p "Gere changelog" --json

GitHub @claude Integration

Taguear @claude em issues/PRs do GitHub faz o Claude responder automaticamente.

# Em uma issue:
@claude Implemente esta feature e abra um PR

# Em um PR:
@claude Revise focando em segurança e performance

# Em uma issue de bug:
@claude Investigue e sugira correção

Agent Teams — Agentes Paralelos

Múltiplas instâncias Claude coordenando-se peer-to-peer.

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Case Study

Anthropic usou 16 agentes para construir compilador C em Rust: 100K linhas, $20K API, compila Linux 6.9.

Sandbox Avançado e Docker

Sandbox reduziu permission prompts em 84%. 3 camadas de defesa:

sbx run claude --name my-sandbox -- "Fix login"

Dispatch + Computer Use

Claude controla seu desktop: mouse, clique, navegação. Funciona com Dispatch para tarefas enquanto você está longe.

Combo: Computer Use + Remote Control

# No terminal:
claude remote-control
# Escaneie QR code com app Claude mobile
# Do celular: "Abra VS Code, rode testes e corrija"
# Claude usa Computer Use no seu Mac

Cowork + Scheduled Tasks

3 Tipos de Scheduling

/loop 5m check deploy status
/loop list
/schedule daily security audit at 8am

GitHub Actions (CI/CD)

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Revise este PR focando em segurança"
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

JetBrains IDEs

Plugin para IntelliJ, WebStorm, PyCharm, GoLand, PHPStorm.

Troubleshooting

/doctor  # Diagnóstico automático

Interfaces e Sessions

Gerenciamento de Sessões

claude -n "nome"     # Sessão com nome
/rename              # Renomeia
/color               # Cor do prompt bar
--continue           # Continua última sessão
--resume             # Retoma sessão por ID

Case Studies e ROI

• 60% dos devs usam IA diariamente
• 67% mais PRs merged/dia
• 29M instalações diárias VS Code
• US$ 2.5 bi receita anualizada

Keybindings e Output Styles

// ~/.claude/keybindings.json
{
  "voice:pushToTalk": "meta+k",
  "background": "ctrl+b"
}

🚀 Claude Opus 4.7 — O Novo Flagship

Lançado em 15 de abril de 2026, o Opus 4.7 é o modelo mais capaz da Anthropic para raciocínio complexo e coding agêntico.

Principais Melhorias

• Software engineering avançado — ganhos significativos nas tarefas mais difíceis
• Vision melhorada — análise de imagens mais precisa
• Instruction following — segue instruções com mais rigor
• Long-running agents — trabalho autônomo mais confiável em tarefas de longa duração
• Auto-verificação — pensa se as próprias outputs estão corretas antes de reportar
• Catches logical faults — detecta falhas de lógica durante planejamento

Novos Controles

Preço e Disponibilidade

• Mesmo preço do Opus 4.6: $5 / $25 por MTok
• Tokenizer atualizado
• ⚠️ Tem API breaking changes vs Opus 4.6 — veja o guia de migração

🖥️ Claude Code Desktop App Redesenhado

Lançado em 15 de abril de 2026, o Claude Desktop App foi completamente reconstruído em torno de sessões paralelas.

Nova Sidebar de Sessões

• Todas as sessões ativas e recentes em um só lugar
• Filtros por status, projeto ou ambiente
• Agrupar sessões por projeto
• Gerenciamento visual de múltiplas sessões paralelas

Side Chat Shortcut

Cmd + ;  →  Abre side chat

# Permite fazer uma pergunta em paralelo
# sem poluir o thread principal com contexto extra

Workflow Integrado

Disponibilidade

Rollout para usuários Pro, Max, Team e Enterprise. Atualize o app para a versão mais recente.

⚡ Routines — Automação Sem Sessão Ativa

Lançado em 15 de abril de 2026 em research preview.

Routines são uma nova forma de configurar automações do Claude Code que rodam sem sessão ativa — direto na infraestrutura web da Anthropic.

Como Funciona

Uma routine empacota 3 coisas em uma configuração única:

1. Prompt — a instrução que será executada
2. Repo — o repositório alvo
3. Connectors — ferramentas e integrações relevantes

3 Tipos de Trigger

Diferença para /loop e /schedule

🔒 Claude Mythos Preview + Project Glasswing

Anunciado em 7 de abril de 2026. Claude Mythos Preview é um novo modelo de linguagem general-purpose com capacidade excepcional em tarefas de segurança computacional.

O que Torna o Mythos Especial

• Performance forte em todas as áreas
• Capacidade excepcional em cybersecurity
• Pode descobrir vulnerabilidades em kernels (Linux, outros OSs)
• Constrói exploits funcionais para vulnerabilidades N-Day
• Identifica e explora CVEs complexas

Project Glasswing

Iniciativa da Anthropic usando Mythos Preview para:

• Ajudar a proteger os softwares mais críticos do mundo
• Preparar a indústria para práticas defensivas necessárias
• Estar à frente de atacantes cibernéticos

🎯 Advisor Tool + Claude Managed Agents

Duas novas capacidades beta lançadas na Claude API em abril de 2026.

Advisor Tool (Public Beta)

Um padrão novo: pair de modelo executor + modelo advisor.

• Executor model (mais rápido) — faz o trabalho bruto de geração de tokens
• Advisor model (mais inteligente) — fornece orientação estratégica mid-generation
• Workloads agênticos long-horizon ficam próximos da qualidade "advisor-solo"
• Maioria dos tokens é gerada na taxa do executor (mais barato)

# Beta header:
advisor-tool-2026-03-01

Claude Managed Agents (Public Beta)

Um agent harness totalmente gerenciado pela Anthropic para rodar Claude como agente autônomo.

• Secure sandboxing built-in
• Built-in tools prontos para uso
• Server-sent event streaming nativo
• Você não precisa gerenciar infra de agentes