DEV Community: Diego de Sousa Brandão

Série: Claude Code CLI: guia técnico — Parte 3: remoto, limites e boas práticas

Diego de Sousa Brandão — Wed, 14 Oct 2026 12:27:40 +0000

Versão do conteúdo: outubro de 2026
Fontes: exclusivamente a documentação oficial da Anthropic (code.claude.com/docs e support.claude.com). A lista completa está em Fontes oficiais.
Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e a referência oficial do CLI. O claude --help não lista todas as flags.

📑 Índice da série

🧠 O que é o Claude Code CLI (Parte 1)
📦 Instalação e autenticação (Parte 1)
🚪 Comandos de entrada (Parte 1)
⌨️ Atalhos de teclado e prefixos (Parte 1)
⚡ Slash commands essenciais (Parte 1)
🔐 Modos de permissão (Parte 1)
📄 Memória: CLAUDE.md e auto memory (Parte 1)
⚖️ Configuração: settings.json (Parte 1)
🪝 Hooks (Parte 2)
👥 Subagents (Parte 2)
🧩 Skills, comandos e plugins (Parte 2)
🔌 MCP no terminal (Parte 2)
⏪ Checkpoints e gestão de contexto (Parte 2)
🤖 Modo não interativo (-p) e CI (Parte 2)
🔀 Sessões em paralelo (Parte 2)
⏰ Automação agendada (Parte 2)
📱 Trabalho remoto e entre dispositivos
✅ O que só o CLI faz
❌ O que o CLI não faz
🤫 Recursos pouco conhecidos
🏆 Fluxo de trabalho recomendado
⚠️ Cuidados e limitações
📚 Fontes oficiais

17. 📱 Trabalho remoto e entre dispositivos

Remote Control: controlar a sessão local de outro aparelho

claude --remote-control   # ou --rc: sessão interativa com Remote Control ligado
claude remote-control     # modo servidor

Dentro de uma sessão: /remote-control ou /rc.
A sessão continua rodando na sua máquina; você acompanha e responde pelo navegador ou pelo app mobile.
Exige Pro, Max, Team ou Enterprise com login no claude.ai. Não funciona com API key nem com Bedrock, Agent Platform ou Foundry. Em Team e Enterprise, um Owner precisa habilitar.
Para ligar em toda sessão: /config → Enable Remote Control for all sessions.

Sessões na nuvem (claude.ai/code)

claude --cloud "corrija o teste flaky em auth.spec.ts"  # cria sessão na nuvem
claude --teleport                                       # puxa uma sessão da nuvem para o terminal

--remote é um apelido antigo (deprecated) de --cloud.
Dentro da sessão, /teleport (ou /tp) também puxa uma sessão da nuvem.
O teleport exige git limpo, o mesmo repositório, a branch publicada e a mesma conta do claude.ai.
Sem remoto no GitHub, --cloud envia um bundle do git (até 100 MB, sem arquivos não rastreados).
--teleport é diferente de --resume: este último só lê o histórico local.
/autofix-pr cria uma sessão na nuvem que acompanha o PR atual e corrige falhas.

Outros dispositivos

Mobile: app Claude para iOS e Android; sessões na nuvem e Remote Control aparecem na aba Code. /mobile mostra um QR code para baixar o app.
Desktop: claude --desktop abre o app desktop na pasta atual (macOS e Windows x64, v2.1.285+). Combine com --continue ou --resume <id> para levar a sessão.
Slack: com Pro, Max, Team ou Enterprise, Claude Code on the web habilitado e GitHub conectado. Funciona em canais, não em DMs. Em Team e Enterprise, essa versão está sendo substituída pelo Claude Tag.

18. ✅ O que só o CLI faz

Comparando com o app desktop, as IDEs, a web e o mobile:

Scripting e modo -p: o desktop é só interativo. Pipelines, --output-format e CI dependem do CLI.
Agent SDK: a página de plataformas o classifica, junto com scripting, como recurso só do CLI. Os pacotes oficiais são em Python e TypeScript.
Agent teams: disponíveis no CLI, não no desktop.
--allowedTools / --disallowedTools por sessão: o desktop não tem equivalente.
Comandos de diálogo como /permissions: no desktop, respondem que não estão disponíveis.
Vim mode (/config → Editor mode, ou "editorMode": "vim") e /terminal-setup.
Mover trabalho entre terminal e nuvem: claude --cloud e claude --teleport.
Provedores terceiros (Bedrock, Agent Platform, Foundry): suportados no CLI e nas IDEs que rodam o CLI. O desktop usa a API da Anthropic por padrão.

Subagents, hooks, skills, CLAUDE.md, plugins, MCP, checkpoints e sandbox não são exclusivos do CLI: funcionam em todas as superfícies e provedores.

19. ❌ O que o CLI não faz

Revisão visual de diff, preview do app e computer use: recursos do app desktop.
Diffs inline no editor: recurso das extensões de VS Code e JetBrains.
Rodar sem a sua máquina: uma sessão do CLI depende do seu computador. Para continuar com tudo desligado, use sessões na nuvem (--cloud) ou rotinas (/schedule).
Sandbox no Windows nativo: só no macOS, Linux e WSL 2.
Sandbox para tudo: o sandbox cobre comandos de shell. Ferramentas de arquivo, servidores MCP e hooks rodam fora dele.
Desfazer efeitos de Bash: checkpoints não cobrem rm, mv, deploys ou chamadas de API.
Ferramentas no /btw: a pergunta paralela não usa ferramentas.
Fast mode em Bedrock, Agent Platform ou Foundry: não disponível.

Recursos que exigem login no claude.ai (não funcionam com API key do Console nem provedores terceiros): sessões na nuvem, Claude Code no mobile, integração com Slack, app desktop, rotinas, /ultrareview, Remote Control e computer use.

20. 🤫 Recursos pouco conhecidos

Recurso	O que faz
`/statusline <descrição>`	Gera um script de status line a partir de linguagem natural. Roda localmente, sem gastar tokens
`/output-style`	Troca o estilo de resposta: Proactive, Concise, Explanatory, Learning ou estilos próprios em `.claude/output-styles/`
`/keybindings`	Abre `~/.claude/keybindings.json` para remapear atalhos, sem reiniciar
`/terminal-setup`	Configura `Shift+Enter` para quebra de linha (VS Code, Cursor, Alacritty, Zed e outros)
`/sandbox`	Liga o sandbox de comandos de shell (Seatbelt no macOS; `bubblewrap` e `socat` no Linux/WSL 2)
`--add-dir` / `/add-dir`	Dá acesso a pastas fora do projeto (ex.: `claude --add-dir ../lib`)
`/copy [N]`	Copia a N-ésima resposta mais recente; `w` no seletor grava em arquivo (útil por SSH)
`/export [arquivo]`	Exporta a conversa como texto
`claude --from-pr 123`	Abre o seletor de sessões ligadas a um PR
`/insights`	Gera um relatório HTML de uso em `~/.claude/usage-data/report.html`
`/recap`	Resume a sessão em uma linha
`/goal <condição>`	Mantém o Claude trabalhando entre turnos até a condição ser atendida
`ultrathink` no prompt	Pede raciocínio mais profundo só naquele turno, sem mudar o `/effort`
`--safe-mode`	Inicia com todas as personalizações desligadas, para depurar
`/powerup`	Lições interativas sobre recursos do Claude Code
`/team-onboarding`	Gera um guia para o time a partir de 30 dias de uso

Mais detalhes úteis:

Sugestões de prompt: Tab ou → aceita. Desligue com promptSuggestionEnabled: false.
Notificações: por padrão só no Ghostty, Kitty e iTerm2. Nos outros terminais, use "preferredNotifChannel": "terminal_bell".
Imagens: cole com Ctrl+V ou arraste para o prompt.

21. 🏆 Fluxo de trabalho recomendado

Baseado na página oficial de boas práticas:

Explore, planeje, implemente, faça commit. Entre no plan mode (Shift+Tab ou claude --permission-mode plan), deixe o Claude ler o código e propor um plano. Use Ctrl+G para editar o plano no seu editor antes de implementar.
Pule o plano em mudanças pequenas. Se dá para descrever o diff em uma frase, não precisa de plano.
Dê ao Claude um jeito de verificar. Testes, build, linter ou screenshot comparado ao design. Sem verificação, ele para quando o trabalho parece pronto.
Faça a verificação decidir quando parar. Use /goal para uma condição da sessão, um hook Stop para um portão determinístico, ou um subagent revisor.
Seja específico. Diga o arquivo, o cenário, o padrão existente a seguir e como fica o "corrigido".
Mantenha um CLAUDE.md enxuto. Comece com /init. Para cada linha, pergunte: "se eu tirar isso, o Claude erra?".
Corrija cedo. Esc para no meio; Esc Esc ou /rewind volta atrás. Depois de duas correções sem sucesso, rode /clear e escreva um prompt melhor.
Use /clear entre tarefas sem relação e subagents para investigações longas.
Entreviste antes de features grandes. Peça ao Claude para te entrevistar, gere um SPEC.md e implemente numa sessão nova.
Escritor e revisor. Uma sessão implementa, outra (com contexto limpo) revisa o diff.
Migrações grandes: /batch, ou um loop de claude -p com --allowedTools e --permission-mode dontAsk.

Padrões de falha a evitar: sessão "pia de cozinha" (tudo misturado), correções em série, CLAUDE.md inchado, confiar sem verificar, investigação sem escopo.

22. ⚠️ Cuidados e limitações

Segurança

No modo default, o Claude só escreve na pasta inicial e nas subpastas, e pede confirmação antes de ler fora dela.
curl e wget não são aprovados automaticamente.
A documentação admite que nenhum sistema é imune a todos os ataques. Prompt injection é um risco real, principalmente com conteúdo da web e servidores MCP.
A Anthropic não audita servidores MCP. Configuração versionada no repositório é responsabilidade do time.
No Windows, evite WebDAV e caminhos \\*: eles podem contornar o sistema de permissões.

`bypassPermissions` e auto mode

bypassPermissions não protege contra prompt injection nem ações indesejadas. Use só em container ou VM isolada.
No Linux e no macOS, a flag é recusada quando roda como root ou com sudo. Administradores podem bloqueá-la com permissions.disableBypassPermissionsMode: "disable".
O classificador do auto mode bloqueia ações irreversíveis, destrutivas ou fora do ambiente. Por padrão, confia só no diretório de trabalho e nos remotes configurados do repositório.
Depois de 3 bloqueios seguidos ou 20 no total, o auto mode pausa e volta a pedir permissão.
Redefinir listas como soft_deny sem "$defaults" remove as proteções internas, incluindo os bloqueios de force-push e de deploy em produção.
Para limites rígidos, use permissions.deny, não o classificador.

Dev containers

Recomendados para isolamento, mas um container não impede que um projeto malicioso leia o que está dentro dele, inclusive as credenciais em ~/.claude.
Não monte segredos do host (como ~/.ssh ou credenciais de nuvem) e restrinja a saída de rede com allowlist.

IDEs

No JetBrains em acceptEdits, o Claude pode alterar arquivos de configuração que a IDE executa sozinha, contornando a confirmação de Bash.

Dados

Planos de consumidor (Free, Pro, Max): os dados podem ser usados para treino se a opção estiver ligada (retenção de 5 anos); com a opção desligada, retenção de 30 dias.
Planos comerciais (Team, Enterprise, API): sem treino por padrão; retenção padrão de 30 dias. Zero Data Retention para contas qualificadas.
As transcrições locais ficam em texto puro em ~/.claude/projects/ por 30 dias (cleanupPeriodDays).
/feedback envia a conversa inteira, incluindo código, e ela é guardada por 5 anos.
Telemetria: desligue com DISABLE_TELEMETRY ou CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.

Custo

Média em empresas: cerca de US$ 13 por desenvolvedor por dia ativo e US$ 150 a 250 por mês; 90% dos usuários ficam abaixo de US$ 30 por dia ativo.
O que encarece: contexto longo, perda de cache, tarefas agendadas e subagents. Agent teams consomem cerca de 7 vezes mais tokens que uma sessão comum quando os teammates rodam em plan mode.
Para gastar menos: /clear entre tarefas, /compact com foco, CLAUDE.md abaixo de 200 linhas, Sonnet para a maior parte do trabalho e Opus para o difícil, model: haiku em subagents simples, ferramentas de CLI em vez de MCP quando possível.
Acompanhe com /usage.

23. 📚 Fontes oficiais

Todas em code.claude.com/docs, consultadas em outubro de 2026.

Visão geral e instalação

Uso no terminal

Permissões, memória e configuração

Extensões

Contexto, automação e paralelismo

Remoto e outras superfícies

Boas práticas, segurança e custo

Fim da série. Parte 1: fundamentos e configuração. Parte 2: extensões, MCP e automação.

Série: Claude Code CLI: guia técnico — Parte 2: extensões, MCP e automação

Diego de Sousa Brandão — Wed, 14 Oct 2026 12:24:51 +0000

Versão do conteúdo: outubro de 2026
Fontes: exclusivamente a documentação oficial da Anthropic (code.claude.com/docs e support.claude.com). A lista completa está em Fontes oficiais (Parte 3).
Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e a referência oficial do CLI. O claude --help não lista todas as flags.

📑 Índice da série

🧠 O que é o Claude Code CLI (Parte 1)
📦 Instalação e autenticação (Parte 1)
🚪 Comandos de entrada (Parte 1)
⌨️ Atalhos de teclado e prefixos (Parte 1)
⚡ Slash commands essenciais (Parte 1)
🔐 Modos de permissão (Parte 1)
📄 Memória: CLAUDE.md e auto memory (Parte 1)
⚖️ Configuração: settings.json (Parte 1)
🪝 Hooks
👥 Subagents
🧩 Skills, comandos e plugins
🔌 MCP no terminal
⏪ Checkpoints e gestão de contexto
🤖 Modo não interativo (-p) e CI
🔀 Sessões em paralelo
⏰ Automação agendada
📱 Trabalho remoto e entre dispositivos (Parte 3)
✅ O que só o CLI faz (Parte 3)
❌ O que o CLI não faz (Parte 3)
🤫 Recursos pouco conhecidos (Parte 3)
🏆 Fluxo de trabalho recomendado (Parte 3)
⚠️ Cuidados e limitações (Parte 3)
📚 Fontes oficiais (Parte 3)

9. 🪝 Hooks

O que é: um comando seu (ou uma chamada HTTP, ferramenta MCP, prompt ou agente) que roda em pontos fixos do ciclo de vida da sessão. Ele não depende de o Claude decidir executá-lo. Hooks dos tipos prompt e agent usam um modelo para avaliar a situação, então não são determinísticos como command e http.

Para que serve: formatar código depois de cada edição, bloquear comandos perigosos, registrar todo comando executado, notificar o time, carregar contexto no início da sessão.

Eventos mais usados

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, PreCompact, PostCompact. A documentação lista 33 eventos no total.

Exemplo: formatar após cada edição

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run format" }
        ]
      }
    ]
  }
}

Códigos de saída

Código	Efeito
`0`	Sucesso. Sem saída, o hook não tem decisão: a ação passa pelo fluxo normal de permissões (silêncio não aprova). Com JSON na saída, o hook pode decidir, por exemplo negar
`2`	Erro bloqueante em eventos que podem bloquear. Em `PreToolUse`, bloqueia a ferramenta e devolve o stderr ao Claude como motivo
Outros	Erro não bloqueante; a ação segue e aparece um aviso

Tipos de handler: command, http, mcp_tool, prompt e agent (este é experimental).

Exemplo: bloquear `rm -rf` com `if` e decisão em JSON

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh  (chmod +x; exige jq)
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # sem decisão; segue o fluxo normal de permissões
fi

O matcher restringe ao Bash e o if restringe a subcomandos rm *; só quando os dois casam o script é executado. Sem matcher, ou com "*", o grupo dispara em toda ocorrência do evento.

Onde definir hooks

Local	Escopo
`~/.claude/settings.json`	Todos os seus projetos
`.claude/settings.json`	O projeto, versionado no git
`.claude/settings.local.json`	O projeto, só para você
Settings gerenciado (managed)	A organização inteira
`hooks/hooks.json` de um plugin	Enquanto o plugin estiver ativo
Frontmatter de skill	Resto da sessão, depois que a skill é chamada
Frontmatter de subagent	Enquanto o subagent roda

Hooks de níveis diferentes se somam: user, project e local acrescentam hooks sem remover os gerenciados. disableAllHooks não desliga hooks gerenciados.
allowManagedHooksOnly (managed) bloqueia hooks de user, project, local e plugins.
Hooks de settings, managed e plugins também rodam dentro de subagents; a entrada traz agent_id e agent_type.
Sessões na nuvem não leem o ~/.claude/settings.json, então hooks de usuário não rodam lá.

Dicas:

/hooks mostra os hooks configurados (só leitura).
O matcher aceita texto exato ou regex. O campo if filtra usando a mesma sintaxe das regras de permissão.
Timeout padrão: 600 s para command, http e mcp_tool; 30 s para prompt; 60 s para agent. Alguns eventos têm limites próprios, menores.
Na maioria dos eventos, se o hook falhar ou estourar o tempo, a ação segue. Para bloquear nesse caso, use "onFailure": "block" em hooks command ou http (v2.1.295+; sem efeito em Stop, SubagentStop, TaskCompleted e TeammateIdle).
Para reinjetar instruções depois de uma compactação, use um hook SessionStart com matcher compact.

Hook não fura deny: um PreToolUse que devolve "allow" não libera uma ação bloqueada por regra deny. Para limites rígidos, use o sistema de permissões.

10. 👥 Subagents

O que é: um assistente especializado que roda na sua própria janela de contexto, com prompt de sistema, ferramentas e permissões próprios. Ele devolve só um resumo, então logs e resultados de busca extensos não poluem a conversa principal.

Subagents nativos:

Explore: busca rápida, só leitura.
Plan: pesquisa no plan mode, só leitura.
general-purpose: tarefas complexas, com todas as ferramentas.
claude: catch-all para o que não se encaixa nos outros.
statusline-setup e claude-code-guide: configuração da status line e dúvidas sobre o próprio Claude Code.

Criar o seu

Arquivo em .claude/agents/ (projeto) ou ~/.claude/agents/ (todos os projetos):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Give specific, actionable feedback.

Só name e description são obrigatórios.

tools: allowlist de ferramentas. Se omitido, o subagent herda todas.
disallowedTools: lista de ferramentas bloqueadas.
Outros campos: model, permissionMode, skills, mcpServers, hooks, memory, isolation: worktree, maxTurns, background, effort, color, initialPrompt, omitClaudeMd.

Como invocar

Automático: o Claude delega com base na description.
Explícito: cite o subagent no prompt ou mencione com @.
Sessão inteira: claude --agent code-reviewer.
Definição temporária, só para a sessão:

claude --agents '{"debugger": {"description": "Debugs errors", "prompt": "You are an expert debugger."}}'

Recursos extras:

/subtask <tarefa> cria um fork que herda a conversa inteira e reporta o resultado de volta na conversa. Para copiar a conversa para uma sessão em segundo plano, use /fork.
Ctrl+B manda um subagent em execução para segundo plano.
Subagents num modelo mais barato (como model: haiku para tarefas simples) reduzem custo.
Para um subagent só de leitura, defina tools com ferramentas de leitura (como no exemplo acima). Apenas remover Edit/Write com disallowedTools não basta: ele mantém Bash e ferramentas MCP.

11. 🧩 Skills, comandos e plugins

Skills

O que é: um arquivo SKILL.md com instruções (e arquivos de apoio opcionais) que ensina um procedimento. O Claude carrega a skill quando ela é relevante, ou você chama com /nome.

Local	Escopo
`~/.claude/skills/<nome>/SKILL.md`	Você, em todos os projetos
`.claude/skills/<nome>/SKILL.md`	O time, via git
`<plugin>/skills/<nome>/SKILL.md`	Chamada como `/plugin-name:skill-name`

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target

disable-model-invocation: true: só você pode chamar (ideal para deploy).
user-invocable: false: some do menu / e só o Claude pode chamar.
$ARGUMENTS recebe todos os argumentos; $0 é o primeiro, $1 o segundo (índice começa em zero).
Arquivos em .claude/commands/ continuam funcionando e também viram /nome; a skill acrescenta arquivos de apoio e controle de invocação.
/skills lista as skills; /skill-doctor (v2.1.252+) mostra o custo de contexto e o uso de cada uma.

Custo de contexto: a descrição de cada skill fica sempre no contexto (description + when_to_use são truncados em 1.536 caracteres na listagem). O conteúdo completo só carrega quando a skill é usada.

Skills que já vêm prontas: /code-review, /batch, /debug, /loop, /claude-api, /verify, /run, /simplify, /fewer-permission-prompts, entre outras.

Plugins

O que é: um diretório que empacota skills, agentes, hooks, servidores MCP e servidores LSP para instalar como uma unidade.

/plugin abre o menu, com as abas Discover, Installed, Marketplaces, Errors e Stats. A aba Discover lista os plugins dos seus marketplaces.
Ao abrir um plugin, os detalhes mostram uma estimativa de custo de contexto (Context cost) e o que ele vai instalar. Marketplaces locais ou próprios podem não fornecer esses dados.
O marketplace oficial da Anthropic (claude-plugins-official) é adicionado na primeira sessão interativa no terminal, salvo bloqueio por política gerenciada.
Pelo shell: claude plugin install <plugin>@<marketplace> (instala no escopo de usuário, a menos que você passe --scope).
Escopos de instalação: usuário, projeto (via .claude/settings.json) ou local.
A aba Installed agrupa plugins sem uso recente (Not used recently), para você desativar o que não usa.
Sessões na nuvem (claude.ai/code) não carregam os plugins das suas configurações locais.

Atenção: um plugin ativo entra em todas as sessões, consome contexto e roda com as suas permissões. Revise antes de instalar.

12. 🔌 MCP no terminal

O MCP (Model Context Protocol) é um padrão aberto para conectar ferramentas de IA a fontes de dados externas.

Adicionar servidores

# Remoto via HTTP (recomendado para servidores remotos)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remoto com cabeçalho de autenticação
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local via stdio: tudo depois de "--" vai para o comando do servidor
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Escopos

Escopo	Onde fica	Quem vê
`local` (padrão)	`~/.claude.json`, na entrada do projeto	Só você, neste projeto
`project`	`.mcp.json` na raiz do repositório	O time, via git
`user`	`~/.claude.json`	Você, em todos os projetos

Escolha com -s ou --scope, por exemplo claude mcp add --transport http shared-server --scope project https://example.com/mcp.

Se o mesmo nome existir em mais de um lugar, vale a entrada inteira da fonte de maior precedência (os campos não se misturam): local → project → user → plugin → connectors do claude.ai. Servidores fornecidos pela organização via managedMcpServers (v2.1.259+) ficam acima de todos.

`.mcp.json` (compartilhado com o time)

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" }
    }
  }
}

${VAR} e ${VAR:-padrão} são expandidos em command, args, env, url e headers. Assim o segredo fica no ambiente, não no git.
Variáveis de credencial ficam vazias quando usadas em url e headers de servidores remotos. Exemplos: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY e NPM_TOKEN. Use nomes próprios, como API_KEY.
Servidores de escopo project pedem aprovação nas sessões interativas. Para refazer essas escolhas: claude mcp reset-project-choices.

Gerenciar

claude mcp list                     # lista servidores
claude mcp get <nome>               # detalhes de um servidor
claude mcp remove <nome>            # remove
claude mcp add-json <nome> '<json>' # adiciona a partir de JSON
claude mcp add-from-claude-desktop  # importa do Claude Desktop (macOS e WSL)
claude mcp serve                    # expõe o próprio Claude Code como servidor MCP
claude mcp login <nome>             # faz o login OAuth sem abrir o painel /mcp
claude mcp logout <nome>            # apaga as credenciais OAuth salvas

Dentro da sessão, /mcp mostra o status, faz login OAuth pelo navegador e liga ou desliga servidores por projeto. /mcp reconnect all reconecta todos os servidores com falha (v2.1.284+).

Limites e nomes

A saída de uma ferramenta MCP gera aviso acima de 10.000 tokens e tem limite padrão de 25.000, ajustável com MAX_MCP_OUTPUT_TOKENS.
MCP_TIMEOUT controla o timeout de inicialização (ex.: MCP_TIMEOUT=10000 claude, 10 s); MCP_TOOL_TIMEOUT, o de cada ferramenta. O campo timeout (em ms) no .mcp.json sobrepõe esse valor por servidor.
Os schemas das ferramentas MCP são carregados sob demanda (tool search) por padrão, para economizar contexto.
Ferramentas MCP seguem o padrão mcp__<servidor>__<ferramenta>; as de plugin, mcp__plugin_<plugin>_<servidor>__<ferramenta>. Use o nome completo em regras de permissão, tools de subagent e matchers de hook.

Segurança: a Anthropic não audita nem gerencia servidores MCP. Instale só os que você confia; um servidor que lê conteúdo da internet expõe você a prompt injection.

13. ⏪ Checkpoints e gestão de contexto

Checkpoints

O Claude Code cria um checkpoint automaticamente antes de cada prompt. Ele guarda as edições feitas pelas ferramentas de edição de arquivo do Claude.

Abrir: /rewind (apelidos /checkpoint e /undo) ou Esc Esc com o campo vazio.
Opções do menu: restaurar código e conversa, só a conversa, só o código, resumir a partir daqui, resumir até aqui. As opções de resumo comprimem o contexto sem mexer nos arquivos.
Retenção: os 100 checkpoints mais recentes de cada sessão. Os snapshots são apagados cerca de 30 dias depois, conforme cleanupPeriodDays.
Checkpoints sobrevivem a --resume e --continue.

O que o checkpoint NÃO desfaz:

Efeitos de comandos Bash (rm, mv, cp etc.).
Edições feitas por subagents.
Mudanças feitas fora do Claude Code ou por outras sessões.
Arquivos com symlink ou hard link.
Ações remotas: banco de dados, APIs, deploys.

Checkpoint não substitui o git. Faça commits.

Gestão de contexto

Comando	O que faz
`/context`	Mostra o uso do contexto em grade colorida, com sugestões
`/compact [instruções]`	Resume a conversa, com foco opcional (ex.: `/compact foque nas mudanças da API`)
`/clear`	Começa uma conversa nova, com contexto vazio (apelidos `/reset` e `/new`)
`/btw <pergunta>`	Pergunta paralela que não entra no histórico
`/autocompact 500k`	Define a partir de quantos tokens a compactação automática dispara (`auto` volta ao padrão)

Janela de contexto: 200 mil tokens no padrão. Modelos com janela nativa de 1 milhão (como Fable 5.1, Sonnet 5 em diante, Haiku 5.5 e Opus 4.7 em diante) usam 1M por padrão.
Compactação automática vem ligada. Ela descarta primeiro saídas antigas de ferramentas e depois resume. Instruções detalhadas do início podem se perder.
Para controlar o que sobrevive à compactação, adicione uma seção "Compact Instructions" no CLAUDE.md.
CLAUDE_CODE_DISABLE_1M_CONTEXT=1 desliga a janela de 1M.

Como economizar contexto:

Regras permanentes vão no CLAUDE.md, não na conversa.
Investigações longas vão para subagents: só o resumo volta.
Skills carregam o conteúdo só quando usadas.
Use /clear entre tarefas sem relação.

14. 🤖 Modo não interativo (`-p`) e CI

claude -p "explique este erro" --output-format json
git diff | claude -p "revise este diff" --allowedTools "Read" "Grep"

Flags principais

Flag	O que faz
`--output-format`	Formato da saída: `text` (padrão), `json` ou `stream-json`. `json` traz `result`, `session_id` e `total_cost_usd`. `stream-json` exige `--verbose`
`--input-format`	Formato da entrada: `text` ou `stream-json`
`--json-schema '<schema>'`	Força saída estruturada (com `--output-format json`, vem em `structured_output`)
`--max-turns <n>`	Limita o número de turnos; sem limite por padrão
`--max-budget-usd <valor>`	Para quando o gasto estimado atingir o teto (só no modo `-p`)
`--allowedTools` / `--disallowedTools`	Libera ou bloqueia ferramentas com a sintaxe de regras, uma regra por argumento entre aspas: `"Bash(git diff *)" "Read"`
`--tools`	Restringe quais ferramentas nativas existem na sessão (ex.: `"Bash,Edit,Read"`)
`--permission-mode`	Modo de permissão da execução (`dontAsk` é o mais seguro para CI)
`--permission-prompts none`	Nega pedidos de permissão em vez de esperar (v2.1.259+)
`--append-system-prompt`	Acrescenta instruções ao prompt de sistema; `--system-prompt` substitui
`--bare`	Pula hooks, skills, plugins, MCP, auto memory e CLAUDE.md; inicia mais rápido
`-c` / `-r <id>`	Continua ou retoma uma sessão também no modo `-p`

Código de saída: 0 em sucesso, diferente de zero em falha. SIGTERM encerra com 143; prefira SIGINT para fechar o turno de forma limpa.
A documentação avisa que --bare deve virar o padrão do -p numa versão futura.

Autenticação em CI

No modo -p, ANTHROPIC_API_KEY é sempre usada quando presente.
Com assinatura: gere o token com claude setup-token e use CLAUDE_CODE_OAUTH_TOKEN.
Com --bare, o OAuth é ignorado: use ANTHROPIC_API_KEY ou apiKeyHelper.

GitHub Actions

Configuração rápida: rode /install-github-app dentro do Claude Code. Exige repositório no github.com, gh autenticado e acesso de admin.
Action oficial: anthropics/claude-code-action@v1, com o segredo ANTHROPIC_API_KEY ou CLAUDE_CODE_OAUTH_TOKEN.
Sem prompt, responde a menções @claude em issues e PRs. Com prompt, roda automaticamente.
claude_args repassa flags do CLI (ex.: --max-turns, --model).
Quem dispara precisa ter permissão de escrita no repositório.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: {% raw %}${{ secrets.ANTHROPIC_API_KEY }}{% endraw %}
    claude_args: "--max-turns 5"

GitLab CI/CD

Integração em beta, mantida pela GitLab. O job instala o Claude Code com o instalador nativo e roda claude -p com a variável mascarada ANTHROPIC_API_KEY.

Agent SDK

O modo -p é a interface de linha de comando do Agent SDK. Para saída estruturada, callbacks de aprovação e controle fino, use os pacotes oficiais em Python ou TypeScript.

15. 🔀 Sessões em paralelo

Git worktrees

claude --worktree feature-auth   # ou: claude -w feature-auth
claude -w "#1234"                # cria a partir de um PR (aspas por causa do #)

Cria <repo>/.claude/worktrees/<nome> numa branch nova worktree-<nome>. Sem nome, o Claude gera um.
Coloque .claude/worktrees/ no .gitignore.
.worktreeinclude (sintaxe de gitignore) copia arquivos ignorados, como .env, para o worktree novo.
worktree.baseRef: "fresh" (padrão, parte da branch principal) ou "head" (parte do HEAD atual).
Ao sair de uma sessão sem nome e sem alterações, o worktree é removido. Nos demais casos, o Claude pergunta antes. Execuções -p não limpam: use git worktree remove.
--tmux junto com --worktree abre o worktree numa sessão tmux.
Subagents com isolation: worktree trabalham num worktree próprio.

`/batch`

/batch <instrução> pesquisa o código, divide o trabalho em 5 a 30 unidades independentes e mostra o plano. Depois da aprovação, roda um subagent em segundo plano por unidade, cada um no seu worktree, com testes.

/batch migre src/ de JavaScript para TypeScript

Sessões em segundo plano

claude --bg "tarefa" inicia uma sessão em segundo plano (não combina com -p).
/background (ou /bg) desanexa a sessão atual; /fork copia a conversa para uma nova sessão em segundo plano.
claude agents abre o painel (agent view, em research preview). ← com o campo vazio desanexa; Enter ou → anexa.
Pelo shell: claude attach, claude logs, claude stop, claude rm, claude respawn.
As sessões rodam na sua máquina; uma sessão ociosa e desanexada encerra o processo depois de cerca de uma hora.

Agent teams (experimental)

Desligado por padrão. Ative com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Um líder coordena vários "teammates" que trabalham em paralelo e conversam entre si.
Não funciona no modo -p. Um time por sessão, sem times aninhados.
Comece com 3 a 5 teammates. O consumo de tokens é bem maior que o de uma sessão única.

16. ⏰ Automação agendada

`/loop`: repetição dentro da sessão

/loop 5m verifique se o deploy terminou
/loop verifique o CI a cada 2 horas

Unidades: s, m, h, d. A granularidade real é de 1 minuto (segundos são arredondados para cima).
Sem intervalo, o Claude escolhe o ritmo entre 1 minuto e 1 hora. Sem prompt, usa .claude/loop.md ou ~/.claude/loop.md, se existir.
Só dispara com o Claude Code aberto e ocioso. Tarefas recorrentes expiram em 7 dias; máximo de 50 por sessão.
Esc para um loop de ritmo automático. CLAUDE_CODE_DISABLE_CRON=1 desliga o recurso.

`/schedule`: rotinas na nuvem

Rotinas rodam na infraestrutura da Anthropic e continuam com o notebook fechado. Planos Pro, Max, Team e Enterprise; em research preview.
Crie com /schedule no CLI ou em claude.ai/code/routines.
Gatilhos: agenda (intervalo mínimo de 1 hora), chamada de API (HTTP POST com token) e eventos do GitHub.
Limites por hora: 100 execuções agendadas por conta; 30 execuções por rotina, somando "Run now", chamadas de API e reexecuções avulsas; 100 chamadas de API por conta.

Qual usar

Opção	Onde roda	Intervalo mínimo	Precisa da máquina ligada?
`/loop`	Na sessão aberta	1 minuto	Sim, com a sessão aberta
Tarefa agendada do app desktop	Na sua máquina	1 minuto	Sim
`/schedule` (rotina)	Nuvem da Anthropic	1 hora	Não
GitHub Actions com `schedule`	Runner do GitHub	Conforme o cron do GitHub	Não

Continua na Parte 3: trabalho remoto, o que só o CLI faz, o que ele não faz, recursos pouco conhecidos, fluxo recomendado, cuidados e fontes oficiais.

⌨️ Série: Claude Code CLI: guia técnico — Parte 1: fundamentos e configuração

Diego de Sousa Brandão — Wed, 14 Oct 2026 11:27:44 +0000

Versão do conteúdo: outubro de 2026
Fontes: exclusivamente a documentação oficial da Anthropic (code.claude.com/docs e support.claude.com). A lista completa está em Fontes oficiais (Parte 3).
Aviso: o Claude Code é atualizado com frequência. Antes de usar este material como referência, confira as mudanças com /release-notes e a referência oficial do CLI. O claude --help não lista todas as flags.

📑 Índice da série

🧠 O que é o Claude Code CLI
📦 Instalação e autenticação
🚪 Comandos de entrada
⌨️ Atalhos de teclado e prefixos
⚡ Slash commands essenciais
🔐 Modos de permissão
📄 Memória: CLAUDE.md e auto memory
⚖️ Configuração: settings.json
🪝 Hooks (Parte 2)
👥 Subagents (Parte 2)
🧩 Skills, comandos e plugins (Parte 2)
🔌 MCP no terminal (Parte 2)
⏪ Checkpoints e gestão de contexto (Parte 2)
🤖 Modo não interativo (-p) e CI (Parte 2)
🔀 Sessões em paralelo (Parte 2)
⏰ Automação agendada (Parte 2)
📱 Trabalho remoto e entre dispositivos (Parte 3)
✅ O que só o CLI faz (Parte 3)
❌ O que o CLI não faz (Parte 3)
🤫 Recursos pouco conhecidos (Parte 3)
🏆 Fluxo de trabalho recomendado (Parte 3)
⚠️ Cuidados e limitações (Parte 3)
📚 Fontes oficiais (Parte 3)

1. 🧠 O que é o Claude Code CLI

O Claude Code é uma ferramenta de programação agêntica da Anthropic. Ela lê o seu código, edita arquivos, executa comandos e se integra às suas ferramentas de desenvolvimento. O CLI é a versão de terminal: você roda claude dentro de uma pasta de projeto e conversa com um agente que trabalha nesse projeto.

Não é um autocomplete. Segundo a documentação, o agente trabalha num ciclo de três fases, que se repete até a tarefa terminar:

🔍 Reúne contexto: lê e busca no repositório.
✏️ Age: edita arquivos, roda testes, build e git.
✅ Verifica: confere o resultado e volta ao início se algo falhou.

Planejar antes de mexer no código não é uma fase do ciclo. É um modo de permissão (plan), que você ativa quando quer (veja a seção 6).

O que ele faz, segundo a documentação oficial:

Escreve testes, corrige erros de lint, resolve conflitos de merge, atualiza dependências e escreve release notes.
Implementa features e corrige bugs a partir de uma descrição em linguagem natural ou de uma mensagem de erro.
Trabalha direto com git: faz stage, escreve mensagens de commit, cria branches e abre pull requests.
Conecta-se a ferramentas externas via MCP (Google Drive, Jira, Slack ou ferramentas internas).
Funciona em pipelines Unix, scripts e CI.

Onde o mesmo motor roda: terminal (CLI), VS Code/Cursor, JetBrains, aba Code do app desktop, web (claude.ai/code), app mobile e Slack. Arquivos CLAUDE.md, settings e servidores MCP do repositório são compartilhados entre as superfícies locais (CLI, IDEs e desktop).

A página oficial de plataformas descreve o CLI como a superfície mais completa para trabalho no terminal e diz que scripting e o Agent SDK só existem nele.

2. 📦 Instalação e autenticação

Requisitos

Sistema operacional: macOS 13.0+, Windows 10 1809+ ou Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Hardware: 4 GB+ de RAM, processador x64 ou ARM64
Conta: Pro, Max, Team, Enterprise ou Console. O plano Free do claude.ai não inclui Claude Code.
Alternativa: provedores terceiros (Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry)

Windows: o Bash tool usa o Git for Windows; sem ele, o Claude Code recorre à ferramenta de PowerShell. O sandbox não funciona no Windows nativo; só no WSL 2.
Alpine e distros com musl: instale bash, curl, libgcc, libstdc++ e ripgrep, e defina USE_BUILTIN_RIPGREP=0.

Instalar

# macOS, Linux, WSL — instalador nativo (recomendado)
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

# Alternativas
brew install --cask claude-code          # Homebrew (canal stable)
brew install --cask claude-code@latest   # Homebrew (canal latest)
winget install Anthropic.ClaudeCode      # WinGet
npm install -g @anthropic-ai/claude-code # npm (Node.js 22+; nunca use sudo)

Também há repositórios assinados para apt, dnf e apk (Debian, Ubuntu, Fedora, RHEL, Alpine).

npm com Node antigo: a instalação conclui, mas mostra o aviso EBADENGINE. Use Node.js 22 ou superior.

Verificar

claude --version   # imprime a versão, ex.: 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

Os binários publicados vêm com um manifest.json assinado e checksums SHA256, verificáveis com a chave GPG divulgada na documentação.

Atualizações

Método de instalação	Atualiza sozinho?	Como atualizar
Instalador nativo	✅ Sim, em segundo plano	`claude update` para forçar
Homebrew	❌ Não, por padrão	`brew upgrade claude-code`
WinGet	❌ Não, por padrão	`winget upgrade Anthropic.ClaudeCode`
apt / dnf / apk	❌ Não	Pelo gerenciador do sistema
npm	✅ Sim, se o diretório global do npm for gravável	`npm install -g @anthropic-ai/claude-code@latest` (evite `npm update -g`)

O canal de atualização (latest ou stable) é definido pelo setting autoUpdatesChannel, ou em /config. O padrão é latest. O stable costuma estar cerca de uma semana atrás e pula versões com regressões graves.
Homebrew e WinGet passam a se atualizar sozinhos com CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1.
O setting minimumVersion define uma versão mínima, para que trocar para stable não faça downgrade.

Login

claude                      # primeira execução: login pelo navegador
claude auth login           # login explícito (--console para cobrança via API)
claude auth status          # status em JSON; código de saída 0 = logado, 1 = não
claude setup-token          # gera um token OAuth de longa duração para CI e scripts

claude setup-token exige assinatura Claude e abre o navegador uma vez para autorizar. O token vale um ano, é impresso no terminal e não fica salvo. Use-o na variável CLAUDE_CODE_OAUTH_TOKEN. Ele autentica só as chamadas ao modelo: não serve para Remote Control nem para connectors do claude.ai, e é ignorado com --bare.

Pegadinha de autenticação: uma ANTHROPIC_API_KEY que você aprovou tem prioridade sobre a assinatura. Confira o que está em uso com /status e rode unset ANTHROPIC_API_KEY para voltar à assinatura.

3. 🚪 Comandos de entrada

Comando	O que faz
`claude`	Abre uma sessão interativa
`claude "pergunta"`	Abre a sessão já com um prompt inicial
`claude -p "pergunta"`	Roda sem interface, imprime o resultado e sai
`claude -c`	Continua a conversa mais recente desta pasta
`claude -r "<sessão>"`	Retoma uma sessão por ID ou nome
`claude -n "nome"`	Dá nome à sessão (aparece em `/resume` e no título do terminal)
`claude -w nome`	Abre a sessão num git worktree isolado (seção 15, na Parte 2)
`claude --bg "tarefa"`	Inicia uma sessão em segundo plano (seção 15, na Parte 2)
`claude update`	Atualiza para a versão mais recente
`claude mcp`	Gerencia servidores MCP
`claude plugin`	Gerencia plugins
`claude agents`	Abre o painel de sessões em segundo plano (exige terminal interativo)

Para processar conteúdo recebido por pipe:

cat arquivo | claude -p "pergunta"

4. ⌨️ Atalhos de teclado e prefixos

Atalhos principais

Atalho	O que faz
`Esc`	Interrompe o Claude ou fecha um diálogo
`Esc` `Esc`	Com o campo vazio, abre o menu de rewind; com texto, limpa o campo e guarda o rascunho no histórico
`Shift+Tab`	Alterna o modo de permissão
`Ctrl+C`	Interrompe ou limpa o campo; com o Claude ocioso, o segundo toque sai
`Ctrl+D`	Sai da sessão: o primeiro toque mostra um aviso e o segundo, em até 800 ms, sai. Com texto no campo, apaga o próximo caractere
`Ctrl+B`	Manda comandos Bash e agentes em execução para segundo plano (no tmux, aperte duas vezes)
`Ctrl+R`	Busca reversa no histórico de comandos
`Ctrl+G`	Abre o prompt no seu editor de texto padrão
`Ctrl+O`	Liga e desliga o visualizador de transcrição
`Ctrl+S`	Guarda ou recupera o rascunho do prompt
`Ctrl+T`	Mostra ou oculta a lista de tarefas do Claude
`Ctrl+V`	Cola imagem da área de transferência (`Cmd+V` no iTerm2; `Alt+V` no Windows/WSL)
`Ctrl+X` `Ctrl+K`	Para todos os subagents em segundo plano e desliga as respostas automáticas a artifacts (aperte duas vezes em até 3 s)
`Option+P` / `Alt+P`	Troca o modelo
`Option+T` / `Alt+T`	Liga e desliga o pensamento estendido (sem efeito no Opus 5.5 e nos modelos Fable)
`Option+O` / `Alt+O`	Liga e desliga o fast mode
`?` (campo vazio)	Mostra o painel de atalhos

macOS: alguns atalhos com Option (como Option+P) exigem configurar Option como Meta no terminal. Option+T funciona sem essa configuração.

Mensagens na fila: dá para digitar enquanto o Claude trabalha. Enter coloca a mensagem na fila; Esc interrompe mas preserva a fila; Ctrl+Enter envia a fila na hora (v2.1.275+).

Prefixos no início da linha

Prefixo	Efeito
`/`	Comando ou skill
`!`	Shell mode: roda o comando direto, a saída entra na conversa e o Claude responde a ela
`@`	Menciona um arquivo (uma pasta mostra a listagem de arquivos, não o conteúdo)

Exemplo de shell mode:

! npm test

O teste roda e o Claude explica as falhas sem você precisar de um segundo prompt.

Atenção: comandos com ! rodam fora do sandbox na maioria das sessões, mesmo com o sandbox ligado. Para o Claude não responder à saída, defina respondToBashCommands como false.

5. ⚡ Slash commands essenciais

Digite / para ver a lista completa e filtrar.

Categoria	Comandos	Para quê
🏗️ Setup	`/init`, `/memory`, `/permissions`, `/config`, `/doctor`	Gerar CLAUDE.md, editar memória e regras, diagnosticar
🧠 Contexto	`/context`, `/compact`, `/clear`, `/rewind`, `/btw`	Ver, resumir e limpar o contexto; voltar no tempo; fazer pergunta paralela
🎛️ Modelo e consumo	`/model`, `/effort`, `/fast`, `/usage`	Trocar o modelo, o nível de esforço e o modo rápido; ver o consumo
🔍 Revisão	`/diff`, `/code-review`, `/security-review`, `/simplify`, `/ultrareview`	Revisar mudanças, buscar bugs e falhas de segurança
🗂️ Sessões	`/resume`, `/branch`, `/fork`, `/rename`, `/export`	Retomar, ramificar, copiar e exportar conversas
🚀 Escala	`/batch`, `/background`, `/loop`, `/schedule`, `/remote-control`	Paralelismo, segundo plano, recorrência, nuvem, controle remoto

Destaques:

/init analisa o repositório e gera um CLAUDE.md inicial com comandos de build, testes e convenções. Se o arquivo já existir, sugere melhorias em vez de sobrescrever.
/effort aceita low, medium, high, xhigh, max ou auto, além de status e ultracode.
/simplify revisa o código alterado com quatro agentes em paralelo. Não procura bugs de corretude; para isso, use /code-review.
/ultrareview faz uma revisão profunda, com vários agentes, num sandbox na nuvem. Pro e Max têm 3 execuções grátis; depois, exige créditos de uso.
/usage mostra o custo da sessão, os limites do plano e estatísticas de uso. /cost e /stats são apelidos.
/btw faz uma pergunta paralela que não entra no histórico. Ele vê a conversa inteira, mas não usa ferramentas.
/branch cria uma ramificação da conversa e muda para ela; a original continua disponível em /resume. /fork copia a conversa para uma nova sessão em segundo plano e mantém você na atual.
/background (apelido /bg) desanexa a sessão atual para rodar em segundo plano e libera o terminal.
/doctor vai além do diagnóstico: aponta skills, servidores MCP e plugins sem uso, hooks lentos, e pode pré-aprovar comandos de leitura que você nega com frequência.

6. 🔐 Modos de permissão

Modo	O que roda sem perguntar	Indicado para
`auto` ⚡	Leituras e edições no diretório de trabalho seguem direto; as demais ações passam por um classificador de segurança	Tarefas longas, menos interrupções
`default` (Manual)	Só leituras	Trabalho sensível
`acceptEdits`	Leituras, edições e comandos comuns de arquivo (`mkdir`, `touch`, `mv`, `cp`)	Iterar no código que você está revisando
`plan` 🗺️	Leituras (mais comandos aprovados pelo classificador, quando o auto mode está disponível)	Explorar e planejar antes de mudar
`dontAsk`	Leituras e ferramentas pré-aprovadas; o resto é negado	CI e scripts travados
`bypassPermissions` ⚠️	Tudo	Apenas containers e VMs isoladas

Como trocar de modo:

Durante a sessão: Shift+Tab. A partir de auto, o primeiro toque vai para default, e o ciclo segue default → acceptEdits → plan. Modos opcionais, como bypassPermissions, entram depois de plan.
Ao iniciar: claude --permission-mode plan. manual é apelido de default.
Plan mode num único prompt: comece o prompt com /plan.
Como padrão: permissions.defaultMode no settings.json.
dontAsk não entra no ciclo do Shift+Tab; ative com --permission-mode dontAsk.

Pouca gente sabe: desde a v2.1.283, auto é o modo inicial das sessões interativas no terminal e no VS Code. Regras deny bloqueiam em qualquer modo, inclusive bypassPermissions. Já as regras allow não têm efeito em bypassPermissions.

Limites que valem conhecer:

permissions.defaultMode com auto ou bypassPermissions é ignorado em settings de projeto (.claude/settings.json) e local. Defina no settings de usuário, no managed, ou passe --permission-mode.
permissions.disableAutoMode: "disable" remove o auto mode.
Caminhos protegidos não têm escrita aprovada automaticamente; a exceção principal é bypassPermissions. Regras allow não liberam escrita neles. A lista inclui, entre outros, .git, .gitmodules, .config/git, .vscode, .idea, .husky, .devcontainer, .claude, .bashrc, .bash_profile, .zshrc, .gitconfig, .npmrc, .yarnrc, .mcp.json e .claude.json.
A primeira leitura fora dos diretórios de trabalho pede confirmação, a menos que permissions.blockReadsOutsideWorkingDirectories esteja desligado.

7. 📄 Memória: CLAUDE.md e auto memory

O Claude Code tem dois sistemas de memória, e os dois são carregados como contexto, não como configuração obrigatória.

	`CLAUDE.md`	Auto memory
Quem escreve	Você	O Claude
Conteúdo	Instruções e regras	Aprendizados e padrões
Escopo	Projeto, usuário ou organização	Por repositório, compartilhado entre worktrees
Carregamento	Toda sessão	Toda sessão (primeiras 200 linhas ou 25 KB)

A auto memory fica em ~/.claude/projects/<projeto>/memory/, com um índice MEMORY.md; o limite de 200 linhas ou 25 KB vale para esse índice. Liga e desliga com o setting autoMemoryEnabled ou em /memory.

Onde fica o CLAUDE.md

Local	Escopo
`~/.claude/CLAUDE.md`	Você, em todos os projetos
`./CLAUDE.md` ou `./.claude/CLAUDE.md`	O time, versionado no git
`./CLAUDE.local.md`	Só você, neste projeto (coloque no `.gitignore`)
`./subpasta/CLAUDE.md`	Carrega sob demanda, quando o Claude trabalha ali
Caminho gerenciado (managed)	A organização inteira

AGENTS.md: se não houver CLAUDE.md, .claude/CLAUDE.md nem CLAUDE.local.md no diretório de trabalho ou acima dele, o Claude Code lê o AGENTS.md no lugar (v2.1.277+).

Exemplo

# Projeto
- Build: ./gradlew build
- Testes: ./gradlew test
- Nunca editar arquivos em /generated
- Convenções de API: @docs/api-conventions.md

Boas práticas da documentação oficial:

Mantenha cada arquivo abaixo de ~200 linhas. Arquivos longos consomem contexto e reduzem a aderência.
Escreva instruções verificáveis: "use indentação de 2 espaços" em vez de "formate bem".
@caminho/arquivo importa outro arquivo, com profundidade máxima de 4 níveis.
Adicione uma linha quando o Claude cometer o mesmo erro pela segunda vez.
Para regras que valem só em parte do código, use .claude/rules/ com escopo por caminho (paths). Regras em ~/.claude/rules/ valem em todos os projetos.
Em monorepos, claudeMdExcludes ignora arquivos CLAUDE.md de pastas acima que não interessam.

Comandos úteis:

/memory: edita os CLAUDE.md, liga ou desliga a auto memory e abre a pasta do que o Claude anotou.
/doctor prompt-audit (v2.1.283+): procura instruções desatualizadas, contraditórias ou que citam arquivos inexistentes, no CLAUDE.md e nas skills.
/context: mostra quais arquivos de memória foram carregados.

Pegadinha: CLAUDE.md é contexto, não regra obrigatória. Para impedir uma ação de verdade, use regras deny de permissão ou hooks.

8. ⚖️ Configuração: settings.json

Precedência, do mais forte para o mais fraco

Nível	Arquivo	Quem afeta
1. Managed	`managed-settings.json`, MDM ou console do claude.ai	A organização
2. Linha de comando	`claude --settings`	Esta sessão
3. Projeto local	`.claude/settings.local.json`	Você, neste projeto
4. Projeto compartilhado	`.claude/settings.json`	Todo o time
5. Usuário	`~/.claude/settings.json`	Você, em todos os projetos

Em geral, o nível mais alto vence. Mas listas como permissions.allow e permissions.deny se somam entre os níveis, em vez de uma substituir a outra.

Exemplo: liberar lint e testes, bloquear `.env`

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Detalhes que fazem diferença:

O arquivo é JSON estrito: comentário ou vírgula sobrando gera erro de configuração.
Ordem de avaliação: deny, depois ask, depois allow. Um deny amplo vence um allow mais específico.
O espaço antes do * importa: Bash(git diff *) casa com git diff e argumentos; sem o espaço, casaria também com git diff-index.
.claudeignore não tem efeito. Para esconder arquivos, use regras Read(...) em deny.
Prefere não editar JSON? /permissions abre um menu, e /fewer-permission-prompts analisa seu uso e propõe uma allowlist.
Para saber de onde veio cada valor, /status mostra as fontes de configuração, e claude doctor aponta entradas descartadas.

Continua na Parte 2: hooks, subagents, skills, plugins, MCP, checkpoints, modo -p e CI, sessões em paralelo e automação agendada.

Custo de tokens em LLMs: onde pesa e como evitar desperdício

Diego de Sousa Brandão — Mon, 21 Sep 2026 16:02:55 +0000

Resumo executivo

Em agentes de código o input domina o volume e o custo; em respostas pontuais e com raciocínio o output pesa mais por token. O desperdício evitável vem de contexto acumulado, modelo e esforço acima do necessário, cache quebrado e modos caros ligados sem necessidade, não da indentação.

Preço por token. O output custa 5x a 6x o input em todos os modelos de topo: Claude Opus 5 US$5/25, GPT-5.6 Sol US$4/20 (promoção), Gemini 3.1 Pro US$2/12, e US$10/50 no Fable 5.1 e no GPT-6 Astra.
Volume em agentes. Agentes gastam ~1.000x mais tokens que chat, com o input puxando o custo (arXiv 2604.22750). Num trace de PR da Sonar, 98% dos ~156 milhões de tokens foram leituras de cache e o output foi 0,19%.
Raciocínio. Thinking tokens são cobrados como output, vêm ligados por padrão e podem chegar a dezenas de milhares por requisição. O esforço é a maior alavanca.
Tokenizer. O do Claude a partir do 4.7 gera ~30% mais tokens que o anterior (Anthropic) e 1,4x a 1,7x mais que o do GPT em texto e código (Playcode). Compare custo por tarefa, não preço por token.
Cache e modos. A leitura de cache custa 10% do input (2,5% no Fable 5.1) e reescrever custa 12,5x mais (50x no Fable 5.1). Fast e Priority custam 1,8x a 2x, e o Batch corta 50%.
Erros de uso mais bem documentados. Sessão longa sem limpar, modelo caro como padrão, esforço alto sem necessidade, cache invalidado, leituras largas e agentes paralelos esquecidos.
Arquivos de contexto. CLAUDE.md, AGENTS.md e GEMINI.md entram em toda sessão e os agentes seguem o que eles dizem. No estudo da ETH Zurich, arquivos gerados por LLM elevaram o custo por tarefa em 20% a 23% sem ganho significativo de acerto. O custo vem do comportamento induzido, não do tamanho do texto.
Estratégias com ganho medido. Mascarar observações antigas (~50% menos custo, JetBrains), estabilizar o prefixo do cache (acerto de 7% para 84% e 59% a 70% de economia num agente em produção), carregar ferramentas sob demanda (de ~77 mil para ~8,7 mil tokens, Anthropic) e cortar instruções de teste de arquivos gerados (−16% a −21% de custo). Os números vêm de contextos diferentes e não se somam.
Formatação. Indentação, espaços e quebras de linha custam 13% a 15% dos tokens de arquivos reais de Java, C# e C++ e 4% dos de Python; a indentação sozinha vale ~8% a 10% nos exercícios de completar código. O modelo tende a repetir a formatação na saída. É real, mas secundário.

Recomendação: limpar contexto a cada tarefa, escolher modelo e esforço por tarefa, estabilizar o prefixo para cache, reduzir leituras e definições de ferramentas, impor tetos de gasto e medir custo por tarefa com o campo usage de cada resposta.

Escopo e qualidade das fontes

O estudo responde quatro perguntas: onde o custo de tokens se concentra (input ou output), quais erros de uso mais o geram, como evitá-los e quais estratégias de redução têm ganho medido em fonte primária ou caso de produção. Cobre Claude (Fable 5.1, Opus 5, Sonnet 5, Haiku 4.5), OpenAI (GPT-6 Astra e GPT-5.6 Sol, Terra e Luna) e Google (Gemini 3.1 Pro e 3.8 Flash), além dos arquivos de contexto do Claude Code, do Codex, do Gemini CLI, do Kimi Code CLI e do GLM. Data-base: 20/09/2026.

Método: cada número vem de página aberta em 20/09/2026, com prioridade para documentação oficial e papers. Onde a fonte é de um fornecedor que vende a solução ou de terceiros, isso está marcado. Cálculos próprios estão marcados como tais.

Cada fonte recebe uma nota de força:

A: paper, documentação ou página oficial.
B: medição de terceiro ou de fornecedor, com método descrito.
C: análise secundária.

Onde o custo se concentra: input em agentes, output em geração e raciocínio

O ponto de maior custo depende do padrão de uso.

Padrão de uso	Onde o custo pesa	Evidência
Chat e geração pontual	Output, 5x a 6x mais caro por token	Tabela de preços abaixo
Agente de código	Input, por releitura do contexto a cada passo	arXiv 2604.22750; trace de um PR
Modelo de raciocínio	Output invisível (thinking tokens)	Documentação da OpenAI e da Anthropic

Uso real em escala. O relatório OpenRouter/a16z (State of AI, 100 trilhões de tokens até nov/2025) mostra o prompt médio subindo de ~1,5 mil para mais de 6 mil tokens e a resposta de ~150 para ~400, uma razão de ~15 para 1 (cálculo nosso). Prompts de programação são 3 a 4x mais longos que os gerais e passam de 20 mil tokens de input, e mais de 50% dos tokens já passam por modelos de raciocínio. Com output 5x mais caro, o input ainda responde por ~75% do custo a preço cheio e sem cache (cálculo ilustrativo nosso). O dado vem de uma só plataforma e usa proxies para uso agêntico.

Agentes. Bai et al. (arXiv 2604.22750, abr/2026) analisaram trajetórias de 8 modelos de 2025 no SWE-bench Verified, com o agente OpenHands. Em média, uma tarefa agêntica usou 4,17 milhões de tokens (US$1,86), contra 1,19 mil (US$0,016) em raciocínio de código e 3,39 mil (US$0,023) em chat de código: de 1.200x a 3.500x mais tokens. A razão input/output é de ~154 para 1 em agentes, contra 0,16 e 1,33 nos outros dois, e o input puxa o custo mesmo com cache. Num estudo de caso com o Sonnet 4.5, a leitura de cache dominou volume e custo em todas as fases, embora o output custe muito mais por token.

A mesma tarefa varia: a run mais cara custa em média ~2x a mais barata, com extremos de até 30x. Mais tokens não garantem mais acerto (a acurácia sobe pouco e satura), e os modelos preveem o próprio gasto com correlação de no máximo 0,39, subestimando-o. Um loop ingênuo relê o histórico a cada passo: 20 passos de 1.000 tokens somam 210.000 tokens de input, não 20.000 (cálculo nosso).

Caso: um PR de 800 linhas (Sonar, 1/09/2026). O post da Sonar mede 512 idas e voltas, janela com pico de 458.700 tokens e ~156 milhões de tokens faturados por ~US$41: 152,8 milhões de leitura de cache, 3,1 milhões de escrita, 106 mil de input novo e 289 mil de output. Um arquivo de 618 linhas (6.472 tokens), lido para usar uma função de ~67 linhas, ficou no contexto por ~470 turnos: ~2,7 milhões de tokens relidos, cerca de US$0,54 à tarifa de cache citada (~US$0,20 por milhão). Em 18 PRs comparáveis, a média foi de ~234 milhões de tokens de contexto, ~700 idas e voltas e ~US$65 por PR (mediana ~US$52). Com essa tarifa, as 152,8 milhões de leituras custam ~US$30,6, cerca de 75% do total (cálculo nosso). Ressalvas: o post não nomeia o modelo nem o agente, mede um repositório e a Sonar vende a solução (análise crítica).

Documentação oficial: o custo cresce com a sessão. O Claude Code envia a conversa inteira a cada requisição, e cada uso de ferramenta gera outra requisição. Com cache, o histórico é relido à tarifa de cache, então uma pergunta de uma linha numa sessão aberta o dia todo consome o histórico inteiro. A primeira mensagem após uma pausa maior que o TTL reprocessa o contexto inteiro, e /compact é ele próprio uma requisição grande (docs).

Leitura: com agentes, otimizar input (contexto, cache, leituras) rende mais que otimizar output. Em geração direta e modelos de raciocínio, ocorre o inverso.

Evidência por modelo: o preço por token é parecido, o custo por tarefa não

Os modelos de topo custam de US$4 a US$10 por milhão de tokens de input, e o output custa 5x a 6x mais em todos; tokenizer, raciocínio e cache é que fazem o custo por tarefa divergir. A tabela traz US$ por milhão de tokens, contexto curto, tarifa padrão, lida nas páginas oficiais em 20/09/2026.

Modelo	Input	Output	Output/Input
Claude Fable 5.1	10	50	5x
GPT-6 Astra	10	50	5x
Claude Opus 5	5	25	5x
GPT-5.6 Sol	4 (promo)	20 (promo)	5x
Claude Sonnet 5	2	10	5x
GPT-5.6 Terra	2	12	6x
Gemini 3.1 Pro Preview	2	12	6x
Claude Haiku 4.5	1	5	5x
Gemini 3.8 Flash	0,75 (promo)	3,75 (promo)	5x
GPT-5.6 Luna	0,20	1,20	6x

O GPT-5.6 Sol está em promoção: a OpenAI garante US$4/20 pelo menos até 21/11/2026, e o preço anterior era US$5/30 (página oficial). Na Anthropic, o Sonnet 5 a US$2/10 é agora o preço padrão, e o aumento previsto para US$3/15 em 1/09/2026 não vai ocorrer. DeepSeek V4, Grok e Mistral ficaram fora da tabela porque não foram verificados em página oficial nesta revisão.

Fontes: páginas de preços da Anthropic, da OpenAI e do Google. O Gemini 3.8 Flash custa US$0,75/3,75 até 31/12/2026 e US$1,50/7,50 depois. GPT-6 Astra (OpenAI) e Claude Fable 5.1 (Anthropic) custam ambos US$10/50.

Cache, contexto longo e modos especiais: regras oficiais por fornecedor

Anthropic, OpenAI e Google cobram a leitura de cache a 10% do input (2,5% no Fable 5.1). A escrita, o prazo, o contexto longo e o que invalida o cache variam.

Fornecedor	Leitura de cache	Escrita ou armazenamento	Contexto longo
Anthropic	0,1x o input (0,025x no Fable 5.1)	Escrita 1,25x (5 min) ou 2x (1 h)	Janela de 1 milhão a preço padrão, sem sobretaxa (preços)
OpenAI	0,1x (Sol US$0,40; Astra US$1,00)	Escrita 1,25x (Sol US$5,00)	Acima de 272 mil tokens: 2x no input e 1,5x no output da requisição inteira (Sol)
Google	0,1x (3.1 Pro US$0,20; 3.8 Flash US$0,075)	Armazenamento por hora: US$4,50 por milhão (3.1 Pro), US$0,50 (3.8 Flash até 31/12/2026)	Acima de 200 mil tokens: US$4/18 no 3.1 Pro

Lote e prioridade. O Batch corta 50% do input e do output nos três fornecedores (Sol a US$2/10 no Batch). Os modos rápidos custam mais: fast mode do Opus 5 e do Opus 4.8 a US$10/50 (2x, indisponível no Batch), Fast mode da OpenAI 2x (Sol a US$8/40) e Priority do Gemini 3.1 Pro 1,8x (US$3,60/21,60).
Prazo. O TTL padrão é de 5 minutos, renova a cada uso e conta desde o início da requisição, inclusive o tempo de geração. No Claude Code o cache dura 1 h em assinatura e 5 min em API key ou com créditos de uso (docs).
O que invalida (Anthropic). O acerto exige prompt 100% idêntico até o breakpoint. Mudar definições de ferramentas invalida tudo. Ligar ou desligar web search ou citações e trocar o modo rápido invalidam sistema e mensagens. Mudar tool_choice, imagens, parâmetros de thinking ou output_config.effort invalida as mensagens. Em modelos com esforço por mensagem, mudar o esforço numa mensagem system preserva o prefixo (docs).
Erro clássico. Breakpoint num bloco que muda a cada requisição, como um timestamp: o cache é escrito toda vez e nunca lido. O ponto certo é o último bloco estável.
Mínimo. Abaixo de 512 tokens (Opus 5, Fable 5.1), 1.024 (Sonnet 5) ou 4.096 (Haiku 4.5) o prompt não entra em cache, sem erro.
Custo do erro. Reescrever o cache custa 12,5x mais que lê-lo (1,25x contra 0,1x) e 50x no Fable 5.1 (1,25x contra 0,025x); cálculo a partir das tarifas oficiais.
Residência de dados. inference_geo: "us" multiplica todos os tipos de token por 1,1x nos Claude 4.6 e posteriores; a OpenAI cobra +10% em endpoints regionais.

Tokenizer: o mesmo código vira 1,5x a 1,7x mais tokens no Claude atual que no GPT

A Anthropic informa que os modelos a partir do Claude 4.7 geram cerca de 30% mais tokens para o mesmo texto que o tokenizer anterior (preços). A Playcode comparou fornecedores com o count_tokens da Anthropic e conferiu contra requisições pagas. A tabela usa o o200k do GPT como 1,00x.

Conteúdo	Claude (novo)	Claude (antigo)	Gemini 3.x Flash
TypeScript (2.888 caracteres)	1,73x	1,32x	1,16x
Rust	1,58x	1,22x	1,19x
JavaScript	1,52x	1,26x	1,23x
Python	1,50x	1,22x	1,20x
Prosa em inglês	1,40x	1,05x	1,01x
Prosa em chinês	1,44x	1,45x	0,85x

Quem usa qual. Sonnet 5, Opus 4.8, Opus 5, Fable 5 e Fable 5.1 usam o tokenizer novo; Sonnet 4.6 e Opus 4.6 usam o antigo. O Fable 5.1 conta o input igual ao Fable 5.
Preço efetivo. Com a divergência média de 1,50x em pedidos típicos de código, a Playcode calcula que os US$5/25 do Opus 5 se comportam como US$7,50/37,50 na base do GPT, e os US$10/50 do Fable 5.1 como US$15/75. É estimativa de terceiro.
Cache também. Leituras e escritas de cache cobram por token, então a inflação as encarece na mesma proporção.
Output varia mais que input. Numa tarefa única (o mesmo SVG, esforço máximo, thinking incluído), os tokens de output foram: Sonnet 5 121.713; Fable 5.1 99.072; Opus 5 74.061; GPT-6 Astra 45.836; Fable 5 42.560; GPT-5.6 Terra 29.834; Gemini 3.7 Flash 13.863. É um prompt só: serve de indício, não de regra.
Agentes (modelos de 2025). No estudo de Bai et al., Claude Sonnet 4.5 e Kimi K2 consumiram em média mais de 1,5 milhão de tokens a mais que o GPT-5 nas mesmas tarefas (arXiv 2604.22750).

Compare por custo por tarefa, não por preço por token: rode o mesmo trabalho em cada modelo e leia o campo usage das respostas. O estudo de formatação da seção seguinte usou tokenizers de 2024–25 (GPT-4o, Claude 3.7, Gemini 1.5); não encontramos medição do efeito no tokenizer novo do Claude.

Reasoning tokens: cobrados como output, ligados por padrão e quase invisíveis

OpenAI e Anthropic documentam que tokens de raciocínio saem à tarifa de output, e a página de preços do Google rotula o output do Gemini como incluindo os tokens de thinking.

OpenAI. Os tokens de raciocínio não aparecem na API, ocupam a janela de contexto e são cobrados como output. Podem ir de algumas centenas a dezenas de milhares por resposta, e a OpenAI recomenda reservar ao menos 25.000 tokens para raciocínio e saída (guia). Se max_output_tokens se esgota durante o raciocínio, você paga input e raciocínio sem receber resposta visível.
Anthropic. No Claude Code o extended thinking vem ligado por padrão, é cobrado como output e seu orçamento padrão pode chegar a dezenas de milhares de tokens por requisição. Nos modelos Fable não dá para desligá-lo. MAX_THINKING_TOKENS só vale em modelos de orçamento fixo; os de raciocínio adaptativo ignoram orçamentos não nulos, então o controle é o esforço (/effort) (docs).
Padrões e modos (OpenAI). O GPT-5.6 usa esforço medium por padrão. O modo pro agrega mais trabalho do modelo e cobra pelas tarifas normais, então gasta mais tokens. O GPT-6 Astra não aceita none. O GPT-5.6 também renderiza por padrão o raciocínio de turnos anteriores (all_turns); current_turn reduz o contexto renderizado em fluxos longos.
Trocar o esforço e o cache. Na Anthropic, mudar o esforço invalida o cache de mensagens, salvo em modelos com esforço por mensagem. Na OpenAI, o item configuration_update (só no GPT-6 Astra) muda o esforço preservando o prefixo do prompt.
Ordem de grandeza. 4.000 tokens de thinking mais uma resposta de 500 somam 9x os tokens de output da resposta sozinha (cálculo nosso).
Mais raciocínio não é mais acerto. No estudo de agentes, a acurácia costuma atingir o pico em custo intermediário e satura depois (arXiv 2604.22750).

Formatação custa de 4% a 15% dos tokens em arquivos reais e ~25% em trechos de exercício

O estudo de Pan et al. (arXiv 2508.13666, lido na íntegra) mede o custo da formatação em duas etapas: uma amostra do Stack v2 (100 mil arquivos por linguagem em Java, C# e C++, tokenizer do GPT-4o) e um experimento principal com 10 modelos. Ambas removem só o que não altera a sintaxe. O paper cita o Python (4,0%) no mesmo estudo preliminar, sem repetir a amostra para ele.

Linguagem	Arquivos reais (GPT-4o)	Exercícios de completar código (média de 10 modelos)
Java	14,7%	34,9%
C++	13,2%	31,1%
C#	13,2%	25,3%
Python	4,0%	6,5%

No experimento principal, os modelos completam um trecho de código em Java, Python, C++ e C#, com cinco modelos comerciais (entre eles GPT-4o, Claude 3.7 e Gemini 1.5) e cinco de pesos abertos. Remover indentação, espaços e quebras de linha cortou em média 24,5% dos tokens de input (o texto do paper também cita 24,6% e 25,8%). Nenhum modelo perdeu mais de 4,2 pontos de Pass@1, e nenhuma queda foi significativa. No Claude 3.7 a redução média foi de 23,0%. Python cai menos porque a indentação é sintaxe.

Cada elemento (C++, Java, C#). A indentação sozinha responde por 7,9% dos tokens de input no Claude 3.7, 8,9% no Gemini 1.5 e 9,6% no GPT-4o. As quebras de linha pesam mais nos dois primeiros (14,6% e 17,5%); no GPT-4o, os espaços (10,7%) pesam mais que as quebras (7,5%). A diferença vem dos tokenizers.
Saída. O modelo repete a formatação mesmo com entrada sem ela: a redução média de output foi de só 2,5%. Pedir código sem formatação cortou 27,2% do output no GPT-4o sem perder acerto (Java, C++ e C#), mas o Gemini 1.5 quebrou a sintaxe e o Pass@1 em C++ caiu de 67,2% para 11,1%. Ajuste fino com 50 exemplos de Java reduziu o output em 24,8% (GPT-4o) e 35,9% (Gemini 1.5).
Limites. A tarefa é completar código, em quatro linguagens e com modelos de 2024–25. Os autores citam limites de generalização e a opacidade dos modelos comerciais. Nenhum modelo atual foi testado.

Leitura: a formatação é de 13% a 15% dos tokens em arquivos reais de Java, C# e C++, e a indentação sozinha vale cerca de 8% a 10% nos exercícios de completar código (Claude 3.7, Gemini 1.5 e GPT-4o). Como o output custa 5x a 6x o input, a formatação que o modelo gera pesa mais que a que você envia, mas ele tende a mantê-la. Pedir "sem formatação" exige teste, porque pode quebrar a sintaxe. A alternativa dos autores é uma ferramenta que remove a formatação na entrada e a restaura na saída.

Arquivos de contexto (CLAUDE.md, AGENTS.md, GEMINI.md): o que custam e quando compensam

Esses arquivos entram no contexto de toda sessão. O texto em si custa pouco com cache; o custo relevante vem do que ele faz o agente fazer. A medição mais rigorosa é a de Gloaguen et al. (arXiv 2602.11988, v2 de jun/2026, lido na íntegra): quatro agentes (Claude Code com Sonnet 4.5, Codex com GPT-5.2 e GPT-5.1 Mini, Qwen Code com Qwen3-30B), 300 tarefas do SWE-bench Lite e 138 tarefas de 12 repositórios com arquivos escrit

Métricas de efetividade de uso de IA — Spark Monitor

Diego de Sousa Brandão — Fri, 18 Sep 2026 13:00:57 +0000

Métricas de efetividade de uso de IA — Spark Monitor

Resumo da pesquisa sobre como medir se uma sessão de IA (Claude Code) foi produtiva, e como ranquear uso entre várias pessoas de forma fidedigna.

Problema-base

Token bruto (input/output/cache) mede atividade, não resultado. Ranquear pessoas só por isso vira Goodhart's law: o comportamento se otimiza para o número, não para a entrega.

Métricas para somar ao que o Spark Monitor já captura

Cache hit ratio = cache_read / (cache_read + input) — sinal de reuso eficiente de contexto.
Output por task fechada, não por sessão — normaliza por dificuldade da tarefa.
Sessões por task — muitas sessões para fechar 1 task indica retrabalho ou task mal escopada.
Rework rate real — % de código gerado por IA que é revertido ou reescrito em N dias. É a 5ª métrica oficial do DORA desde 2025. Sem esse dado, as métricas acima medem atividade, não qualidade.

Base acadêmica

Paper: Chen et al., "Beyond the Commit: Developer Perspectives on Productivity with AI Coding Assistants" — ICSE-SEIP 2026 (CMU + BNY Mellon). Survey com 2989 devs + 11 entrevistas.

Correlação entre satisfação percebida e tempo economizado auto-reportado: r = 0,34 (fraca). Confirma que métrica única não captura produtividade.
6 fatores identificados, agrupados em desenvolvimento / deploy / longo prazo:
1. Autossuficiência
2. Fricção e carga cognitiva
3. Taxa e qualidade de conclusão de tarefa
4. Facilidade de peer review
5. Expertise técnica (longo prazo)
6. Ownership do código (longo prazo)
Achado direto ao caso: commit frequency e taxa de aceite de sugestão (o que o Spark Monitor já capta) cobrem apenas o fator de deployment — não medem tempo real gasto nem qualidade.
Risco documentado: ranking competitivo por atividade tende a empurrar devs júnior a confiar demais na IA, corroendo aprendizado e senso de ownership.
Meta usa métrica própria, Diff Authoring Time (DAT) — tempo real de autoria de um diff, sinal mais fino que token bruto (Beller et al. 2025).

Gate de avaliação por LLM (se for implementado)

Riscos documentados de usar um LLM como juiz de código:

Viés de verbosidade — o juiz tende a preferir código/resposta mais longa, mesmo sem ganho real de conteúdo.
Autopreferência — o modelo tende a preferir a própria saída/estilo (efeito de menor "perplexidade").
Boa notícia: em tarefas verificáveis (código com teste/build), a autopreferência tende a refletir qualidade real — diferente de tarefas subjetivas como chat/resumo.

Desenho recomendado — gate em 2 camadas:

Camada objetiva (sem viés): testes automatizados passam, build ok, lint/análise estática.
Camada LLM-juiz: só para o que a camada objetiva não pega — legibilidade, aderência a padrão. Rubrica fixa, temperatura baixa, modelo juiz logado (idealmente diferente do modelo gerador). Calibrar periodicamente contra o rework rate real.

Mercado — não existe score pronto, mas existe a categoria

GitClear — mede churn, duplicação, idade do código, atribuição IA vs. humano. ~US$15/contribuidor/mês.
DX — feito pelos autores do SPACE e do DORA; lançou framework de IA dedicado em 2026 (utilização, impacto, custo).
Nenhuma resolve o problema sozinha. A própria DX publicou (mar/2026) que DORA isolado não é suficiente para times usando IA.

Dados já disponíveis para implementação

Projeto: campo cwd presente em cada linha do JSONL de sessão do Claude Code (~/.claude/projects/<cwd-codificado>/<uuid>.jsonl — no Windows, %USERPROFILE%\.claude\projects\), mais gitBranch. Já está no dado que o Spark Monitor lê.
Push feito pela própria IA: já registrado no mesmo JSONL, como tool_use/tool_result do Bash rodando git push.
Push manual do humano (fora do Claude Code): não está no log do Claude Code. Requer hook git global (git config --global core.hooksPath <pasta>, hook pre-push) — cobre todos os repositórios de uma vez. Atenção: pre-push confirma a intenção do push, não garante que a transferência de rede terminou com sucesso.
Atenção: "subiu pro remoto" ≠ "foi pra produção". Confirmar deploy real exige integração com CI/CD.

Fontes

Acadêmico

Chen et al., "Beyond the Commit: Developer Perspectives on Productivity with AI Coding Assistants", ICSE-SEIP 2026 — https://arxiv.org/abs/2602.03593
Wataoka et al., "Self-Preference Bias in LLM-as-a-Judge" — https://arxiv.org/html/2410.21819v1
"Judging the Judges: A Systematic Evaluation of Bias Mitigation Strategies in LLM-as-a-Judge Pipelines" — https://arxiv.org/pdf/2604.23178
"Do LLM Evaluators Prefer Themselves for a Reason?" (Univ. of Virginia, 2025) — https://papers.lunadong.com/paper/6021
DORA Research, AI Capabilities Model — https://dora.dev/research/ai/ai-capabilities-model

Indústria / mercado

GetDX, "How to Implement the AI Measurement Framework" — https://getdx.com/blog/how-to-implement-ai-measurement-framework/
GitClear, estudo de churn/duplicação em código gerado por IA — via https://arc.dev/talent-blog
Faros AI, "AI Engineering Report 2026" — https://www.faros.ai

Documentação técnica Claude Code

Formato JSONL de sessão — https://claude-dev.tools/docs/jsonl-format
Local dos logs (~/.claude/) — https://claude-dev.tools/docs/log-locations

Template de Avaliação de IAs de Coding

Diego de Sousa Brandão — Wed, 01 Jul 2026 18:01:36 +0000

Resumo Executivo

O que é este documento: um modelo padronizado para avaliar, de forma comparável e replicável, a capacidade real de ferramentas de IA aplicadas a desenvolvimento (Codex, Devin, Claude e demais), identificando com precisão o que cada uma faz bem, faz mal, ou não faz.

Por que essa metodologia: hoje o mercado divulga números de benchmarks públicos (como SWE-bench e Terminal-Bench) que servem como referência de capacidade geral, mas apresentam duas limitações relevantes para decisão de negócio:

Medem desempenho em projetos abertos de terceiros (majoritariamente Python), não refletem o comportamento em codebases proprietários, legados e no stack específico da empresa.
O resultado divulgado depende fortemente da ferramenta usada em torno do modelo (a forma como a IA é operacionalizada), não só do modelo em si — comparações "cruas" entre fornecedores tendem a ser enganosas.

Por isso, este template combina três referências reconhecidas no mercado — benchmarks públicos como ponto de partida, uma métrica de escala de dificuldade usada por institutos de avaliação de IA (METR) para medir até onde a ferramenta aguenta, e uma estrutura de avaliação usada em processos de seleção corporativa de ferramentas de IA (dimensões como confiabilidade, rastreabilidade, segurança e custo real) — com um piloto controlado, executado sobre código real da nossa operação, com critério e revisor únicos para todas as ferramentas testadas.

Resultado esperado: uma matriz objetiva, com evidência documentada, que sustenta a recomendação de qual ferramenta adotar, para qual finalidade, e com quais limitações conhecidas.

Princípio metodológico: o teste deve ser conduzido sobre uma tarefa real do backlog, nunca sobre um projeto de demonstração simplificado. A avaliação deve ser conduzida pelo mesmo revisor, com os mesmos critérios, para todas as ferramentas — garantindo comparabilidade.

1. Preparação do teste

Repositório real, com código legado, particularidades e convenções próprias — não um projeto novo e simplificado. É diante da complexidade real que se evidenciam os limites de cada ferramenta.
Linha de base humana: cronometrar quanto tempo um desenvolvedor Pleno leva para executar a mesma tarefa, como referência de comparação.
Revisor único: mesma pessoa e mesmo critério de avaliação (checklist de PR) para todas as ferramentas testadas.
Repetição: executar cada tarefa 2 a 3 vezes por ferramenta. O resultado de uma IA generativa varia entre execuções, mesmo para o mesmo pedido — uma única tentativa pode distorcer a avaliação.

2. Matriz de Capacidade por Ferramenta

Escala: 0 = não realiza | 1 = realiza com baixa qualidade, exige reescrita | 2 = realiza de forma razoável, exige ajustes | 3 = realiza em nível pronto para PR

Capacidade avaliada	Codex	Devin	Claude	Outra
Corrigir um bug simples em um único arquivo
Corrigir um bug que envolve múltiplos serviços simultaneamente
Alterar a assinatura de uma função e ajustar todos os pontos que a utilizam
Criar um novo endpoint seguindo o padrão já existente no projeto
Reter contexto de uma decisão do projeto após reabertura de sessão
Responder "se eu alterar isso, o que mais é impactado?" apenas com análise, sem executar mudanças
Escrever testes que cobrem cenários relevantes, não apenas o caminho principal
Compreender uma dependência de um projeto que não está aberto no contexto atual
Seguir os padrões de arquitetura do time sem instrução repetida
Reconhecer limitação de conhecimento e solicitar mais contexto, em vez de gerar resposta incorreta com aparência de correta

3. Teste de Limite de Capacidade

A dificuldade da tarefa deve ser escalonada progressivamente até que a ferramenta apresente falha — o objetivo é documentar em qual estágio cada uma deixa de performar de forma confiável:

Tarefa de 1 arquivo, equivalente a menos de 30 min de trabalho humano
Tarefa de 2 a 3 arquivos, equivalente a 1-2h de trabalho humano
Tarefa que atravessa múltiplos serviços/repositórios, equivalente a meio dia de trabalho humano
Tarefa sem especificação clara, que exige tomada de decisão de design, equivalente a um dia de trabalho humano

Esta abordagem é baseada no conceito de Time Horizon, métrica usada pelo instituto de pesquisa
METR para medir não "se a IA acerta", mas até qual complexidade/duração de tarefa humana a ferramenta
ainda mantém taxa de sucesso aceitável. Identificar o estágio em que cada ferramenta falha fornece
mais informação para decisão do que uma nota única.

4. Critérios Corporativos Complementares

Dimensão	Critério de avaliação	Codex	Devin	Claude
Consistência	O resultado varia significativamente entre execuções para o mesmo pedido?
Rastreabilidade	É possível identificar posteriormente qual ferramenta/versão gerou cada alteração?
Retenção de contexto	A ferramenta compreende o projeto como um todo ou apenas o que está aberto no momento?
Reversibilidade	Em caso de erro, é possível reverter apenas a alteração específica, ou o impacto se espalha por múltiplos arquivos?
Segurança da informação	Onde o código é processado/armazenado? Há uso do código para treinamento de modelo?
Custo real	Qual o tempo de revisão humana efetivamente economizado, descontado o tempo gasto em correções?

5. Ressalvas Metodológicas

A camada de operacionalização (produto) tem tanto peso quanto o modelo em si. O mesmo modelo (ex.: Claude) executado por diferentes produtos pode apresentar resultados distintos. Recomenda-se registrar não apenas "qual IA", mas "qual IA, em qual produto".
Benchmarks públicos não são preditivos do caso de uso específico. Os benchmarks de mercado avaliam majoritariamente projetos abertos em Python; não refletem o comportamento em ambiente Java de fintech legado, com Kafka e IBM MQ. Devem ser tratados como referência geral, não como critério de decisão.
Números divulgados por fornecedores devem ser tratados com cautela, especialmente quando não há metodologia reprodutível associada.
Demonstração de fornecedor não equivale a piloto controlado. O cenário apresentado em demonstrações tende a ser favorável (projeto simples e recente). A avaliação deve ocorrer sobre código real da operação, incluindo débito técnico.
O custo oculto deve ser mensurado. Tempo adicional de revisão sênior para correção do que foi gerado pela IA é custo, não apenas o tempo nominal economizado — deve compor o cálculo final de ganho de produtividade.

6. Prompts Padronizados para Execução dos Testes

Recomenda-se aplicar os mesmos prompts (ajustando apenas nome de arquivo/função) em Codex, Devin e Claude, garantindo comparabilidade entre os testes.

Correção de bug simples (1 arquivo)

"No arquivo [caminho], o teste [nome do teste] está falhando. Investigue a causa e corrija, sem alterar o comportamento esperado do teste."

Correção de bug cross-service

"O serviço [A] está retornando erro quando chama [B]. Rastreie o fluxo completo entre os dois serviços, identifique a origem do problema e proponha a correção. Antes de editar, indique quais arquivos pretende alterar."

Análise de impacto de mudança de assinatura

"Quero alterar a assinatura do método [nome] de [assinatura atual] para [nova assinatura]. Antes de qualquer alteração, liste todos os pontos do projeto que chamam esse método e o que será impactado."

Aderência a padrão existente

"Crie um novo endpoint [descrição] seguindo exatamente o mesmo padrão de arquitetura, nomenclatura e tratamento de erro já utilizado nos demais endpoints deste projeto. Não introduza um padrão novo."

Retenção de contexto (executar em sessão nova)

"Sem que eu forneça o contexto novamente: qual é a convenção que este projeto utiliza para tratamento de exceções? E para nomenclatura de branches?"
(aplica-se quando a ferramenta possui memória entre sessões — caso ela solicite o contexto de volta, esse já é um dado relevante sobre sua limitação)

Reconhecimento de limitação de conhecimento

"Implemente [funcionalidade dependente de uma biblioteca ou API que você sabe que não existe ou mudou recentemente]."
Objetivo: verificar se a ferramenta sinaliza incerteza, ou gera código plausível porém incorreto.

Análise sem execução

"Não realize nenhuma alteração ainda. Apenas explique: se eu alterar o tipo de retorno de [função] de X para Y, o que é impactado no projeto?"

Cobertura de teste

"Escreva testes unitários para [classe/função]. Inclua ao menos um cenário de borda não óbvio — entrada nula, lista vazia, concorrência ou timeout."

Teste de limite de complexidade (estágio 4 da seção 3)

"Preciso de [funcionalidade nova, sem especificação detalhada, que exige decisão de design]. Propositalmente não fornecerei todos os detalhes — faça as perguntas que considerar necessárias antes de iniciar a implementação."
Objetivo: verificar se a ferramenta solicita esclarecimento antes de agir, ou avança sobre premissas não validadas.

7. Fontes

SWE-bench / SWE-bench Verified / Pro — arxiv.org/pdf/2509.16941, swebench.com
Terminal-Bench 2.1 — tbench.ai, arxiv.org/html/2601.11868v1
METR Time Horizon — metr.org/time-horizons, arxiv.org/html/2503.14499v1
Checklist enterprise 6 dimensões (adaptado) — augmentcode.com/guides/cto-ai-coding-checklist
Pilot enterprise (metodologia de rollout) — lumenalta.com/insights/how-to-evaluate-ai-coding-tools-for-enterprise-teams
Governança de benchmarks / harness effect — digitalapplied.com/blog/swe-bench-terminal-bench-benchmark-guide-2026
Devin SWE-bench technical report — cognition.ai/blog/swe-bench-technical-report

JIT Compilation — Guia Didático

Diego de Sousa Brandão — Tue, 09 Jun 2026 01:55:42 +0000

O que você vai aprender:
Como a JVM decide o que compilar e quando · A diferença real entre C1 e C2 · O que é o Code Cache e por que ele pode derrubar sua performance · GraalVM: JIT vs Native Image · Project Leyden: como o Java 25 resolve o warmup de vez

Índice

1. O Problema Original
- A cena que todo dev Java já viveu
- Comparativo das abordagens
2. Just-In-Time Compilation
- O processo completo de um método na JVM
- Fluxo visual
- Por que a compilação não trava a aplicação
- Deoptimização — o que o curso não menciona
3. Os Dois Compiladores: C1 e C2
- Otimizações que o C2 aplica e o C1 não consegue
4. Code Cache
- Tamanhos padrão por versão
- O aviso mais temido em produção
- Flags essenciais para diagnóstico e tuning
- Detalhe importante sobre o CompileThreshold
5. GraalVM
- 5.1 Graal JIT — substituto do C2
- 5.2 Native Image — AOT total
- Comparativo: JIT clássico vs GraalVM Native Image
- Por que Native Image tem peak performance menor
6. Project Leyden
- Como funciona — em dois passos
- Linha do tempo dos JEPs do Leyden
- Comparativo final: os três mundos
7. Quando Parar de se Preocupar com Warmup
- Resposta direta: Java 25+
- Contexto prático para Kubernetes
8. Linha do Tempo e Resumo Executivo
- Evolução completa da performance JVM
- Resumo executivo — referência rápida
9. GraalVM vs sem GraalVM — análise com dados reais
- O que os dados dizem sobre adoção em produção
- Cenário 1 — Sem GraalVM: HotSpot JIT puro
- Cenário 2 — GraalVM modo JIT
- Cenário 3 — GraalVM Native Image
- Decisão rápida
Referências Bibliográficas

Seção 1 — O Problema Original

Por que o Java era lento e, como ele resolveu isso

A cena que todo dev Java já viveu

💡 Você mede a performance de um método logo que a aplicação sobe: 200ms.
Mede de novo 30 segundos depois: 8ms.
O que aconteceu? A aplicação estava "esquentando".
Isso tem nome, tem mecanismo e, a partir do Java 25, tem solução definitiva.

Java compila código-fonte (.java) para bytecode (.class) — um formato intermediário, agnóstico de plataforma. A JVM interpreta esse bytecode em qualquer máquina. Isso é o famoso write once, run anywhere.

O custo: interpretação instrução por instrução é lenta. Em 1996, Java rodava 10 a 20× mais lento que C.

Comparativo das abordagens

Abordagem	Portabilidade	Performance	Exemplo
Compilado nativo	❌ Binário por SO	⭐⭐⭐⭐⭐ Máxima	C / C++
Interpretado puro	✅ Bytecode universal	⭐ Baixa	Java 1.0 (1996)
JIT — híbrido	✅ Bytecode universal	⭐⭐⭐⭐⭐ Alta	Java 1.3+ (2000)
AOT Cache (Leyden)	✅ Bytecode universal	⭐⭐⭐⭐⭐ Alta + startup rápido	Java 24+ (2024)

💬 A pergunta que originou o JIT: e se a JVM pudesse aprender enquanto roda quais partes merecem ser compiladas para código nativo — sem abrir mão da portabilidade?

Seção 2 — Just-In-Time Compilation

Como a JVM observa, decide e compila em tempo real

O JIT é o mecanismo pelo qual a HotSpot JVM observa o código em execução e, quando identifica trechos chamados com frequência (hot spots), os compila para código de máquina nativo — em uma thread separada, sem parar a aplicação.

O processo completo de um método na JVM

Passo 1 — Execução interpretada (Tier 0)

A JVM começa interpretando o bytecode linha a linha. Lento, mas funciona imediatamente. Ao mesmo tempo, dois contadores são incrementados por método:

Method invocation count — quantas vezes o método foi chamado
Loop back-edge count — quantas vezes os loops do método executaram

Passo 2 — Compilação pelo C1, rápida e com profiling (Tiers 1–3)

Quando os contadores cruzam o Tier3CompileThreshold (padrão: 2.000 invocações), o método entra na fila JIT. O compilador C1 gera código nativo rapidamente e continua coletando dados de comportamento (profiling). A aplicação já roda mais rápido, mas ainda não no máximo.

Passo 3 — Compilação pelo C2, otimização agressiva (Tier 4)

Quando o método atinge o Tier4CompileThreshold (padrão: 15.000 invocações), o C2 entra em ação. Ele usa os dados de profiling do C1 para aplicar otimizações impossíveis de fazer sem observar o comportamento real: inlining, devirtualization, escape analysis e muito mais.

Passo 4 — Armazenamento no Code Cache

O código nativo compilado pelo C2 vai para o Code Cache — uma região especial da memória fora do heap. A partir daí, o método roda na velocidade máxima possível, sem interpretação, sem compilação, sem overhead.

Fluxo visual

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐     ┌──────────────┐
│   TIER 0    │ ──► │   TIERS 1 – 3    │ ──► │    TIER 4       │ ──► │  CODE CACHE  │
│             │     │                  │     │                 │     │              │
│ Interpretado│     │ C1 compila       │     │ C2 otimiza      │     │ Nativo em    │
│ puro        │     │ + coleta         │     │ agressivamente  │     │ memória      │
│             │     │ profiling        │     │                 │     │ especial     │
└─────────────┘     └──────────────────┘     └─────────────────┘     └──────────────┘
    Lento               Rápido                   Máximo                Ultra-rápido

O símbolo % no output de -XX:+PrintCompilation indica que o método está no Code Cache — o estado mais otimizado possível.

Por que a compilação não trava a aplicação?

✅ A fila JIT e os compiladores rodam em threads separadas. Enquanto um método está sendo compilado pelo C2, a JVM continua usando a versão C1 (ou interpretada) para atender requests. Quando a versão C2 fica pronta, a JVM faz o swap automaticamente — transparente para você.

⚠️ Deoptimização — o que o curso não menciona

❌ O C2 faz otimizações especulativas baseadas no que observou até agora. Se o comportamento mudar (ex: um método que era sempre chamado com Integer agora recebe String), a JVM pode deoptimizar o método — jogar fora a versão C2 e voltar para o C1 ou interpretado. Esse ciclo pode se repetir. Em produção, deoptimizações frequentes aparecem nos logs JIT como made not entrant e são sinais de código com comportamento inconsistente.

Seção 3 — Os Dois Compiladores: C1 e C2

Filosofias opostas, usadas na ordem certa

	C1 — Client Compiler	C2 — Server Compiler
Tiers	1, 2, 3	4 exclusivamente
Filosofia	Compila RÁPIDO, otimiza POUCO	Compila DEVAGAR, otimiza MUITO
Tempo de startup	Excelente	Ruim isolado
Peak performance	Boa	Máxima
Coleta profiling	Sim (tier 3)	Usa o que o C1 coletou
Escrito em	C++	C++ (HotSpot) / Java (Graal)
Caso ideal	Apps curta duração, CLIs	APIs, servidores, microsserviços

💬 Analogia: C1 é o mecânico que faz uma regulagem rápida para você sair logo. C2 é o engenheiro de F1 que passa a noite otimizando cada componente. A Tiered Compilation usa os dois na ordem certa, sem que você precise decidir.

Otimizações que o C2 aplica e o C1 não consegue

1. Method Inlining

// Antes — chamada separada com overhead
result = calculate(x);

int calculate(int x) {
    return x * 2 + 1;
}

// Depois — C2 inlina o corpo diretamente
result = x * 2 + 1;  // chamada eliminada

Elimina o overhead de chamada de método em hot paths. É a otimização mais impactante do C2.

2. Escape Analysis

// Antes — parece precisar de alocação no heap
Point p = new Point(x, y);
return p.x + p.y;

// Depois — C2 detecta que p não escapa do método
return x + y;  // objeto eliminado, zero alocação

Se o objeto não sai do método, C2 pode alocar na stack ou eliminar completamente. Reduz pressão no GC.

3. Devirtualization

// Antes — polimórfico: qual método chamar?
animal.sound();  // Dog? Cat? Bird?

// Depois — C2 observou: 99% das vezes é Dog
dog.sound();  // chamada direta + inlining

Se 99% das chamadas são para o mesmo tipo concreto, C2 inlina esse tipo e adiciona um guard raro.

4. Loop Unrolling

// Antes — loop com overhead de controle
for (int i = 0; i < 4; i++)
    sum += arr[i];

// Depois — C2 desenrola o loop
sum += arr[0];
sum += arr[1];
sum += arr[2];
sum += arr[3];

Reduz iterações, habilita vetorização SIMD e elimina o custo do contador de loop.

5. Dead Code Elimination

// Antes
boolean DEBUG = false;
if (DEBUG) {
    log.trace("calculando...");  // nunca vai rodar
}
return x * 2;

// Depois — C2 remove o bloco morto completamente
return x * 2;

6. Range Check Elimination

// Antes — Java verifica bounds a cada acesso
for (int i = 0; i < arr.length; i++)
    sum += arr[i];  // arr[i] verifica bounds toda vez

// Depois — C2 prova que o índice é sempre válido
// verificação eliminada no loop quente

Seção 4 — Code Cache

A região de memória que faz tudo isso funcionar e, que pode te trair

Após compilação pelo C2, o código nativo vai para o Code Cache — uma região de memória fora do heap Java, gerenciada separadamente. Métodos no Code Cache são executados diretamente pelo processador, sem qualquer overhead de interpretação.

Tamanhos padrão por versão

Versão Java	Tamanho padrão	Observação
Java ≤ 7 (32-bit)	32 MB	JVM 32-bit — removida no JDK 24
Java ≤ 7 (64-bit)	48 MB	—
Java 8+ (64-bit)	240 MB	Padrão atual — adequado para a maioria

❌ O aviso mais temido em produção

CodeCache is full. Compiler has been disabled.

A aplicação não cai. Mas o JIT para. Novos métodos não são compilados. Métodos podem ser desalojados e recompilados em loop. Performance degrada silenciosamente e, sem esse aviso nos logs, você não vai saber por quê.

Flags essenciais para diagnóstico e tuning

# Ver o que está sendo compilado em tempo real
-XX:+PrintCompilation

# Inspecionar tamanho atual do Code Cache
-XX:+PrintCodeCache

# Log completo para arquivo (útil em servidores remotos)
-XX:+UnlockDiagnosticVMOptions -XX:+LogCompilation

# Ajustar tamanho máximo do Code Cache
-XX:ReservedCodeCacheSize=256m

# Threads de compilação (1/3 para C1, 2/3 para C2)
-XX:CICompilerCount=6

# Threshold de invocações (só funciona sem Tiered Compilation)
-XX:CompileThreshold=10000

⚠️ Detalhe importante sobre o CompileThreshold

O -XX:CompileThreshold=10000 é amplamente citado mas quase nunca é o que a JVM usa. Com Tiered Compilation ativa (padrão desde o Java 8), a JVM usa thresholds por tier:

Tier3CompileThreshold = 2.000

Tier4CompileThreshold = 15.000

O CompileThreshold genérico só é relevante quando você desativa a Tiered Compilation com -XX:-TieredCompilation.

Seção 5 — GraalVM

Um terceiro compilador e, uma alternativa radical ao JIT

O GraalVM não é "só uma JVM mais rápida". É uma plataforma com duas abordagens fundamentalmente diferentes — que você precisa entender separadamente.

5.1 Graal JIT — substituto do C2, mesmo modelo JIT

O compilador Graal pode substituir o C2 dentro da HotSpot JVM usando a interface JVMCI (disponível desde o Java 9). Nesse modo, tudo continua igual: Tiered Compilation, Code Cache, profiling só o compilador do tier 4 muda.

-XX:+UseJVMCICompiler    # ativa o Graal JIT no lugar do C2

O Graal JIT é escrito em Java (não em C++ como o C2), o que permite otimizações mais sofisticadas e facilita evolução. Em benchmarks específicos, ele supera o C2 em throughput de pico.

5.2 Native Image — AOT total, sem JVM em runtime

A opção mais radical do GraalVM: compilação AOT (Ahead-Of-Time) completa. O bytecode vira um executável nativo antes da execução. Não há JVM em runtime. Não há JIT. Não há warmup.

# Gerar executável nativo
native-image -jar minha-aplicacao.jar

# Resultado: binário nativo (~50ms startup, memória mínima)

Comparativo: JIT clássico vs GraalVM Native Image

Característica	JIT (HotSpot padrão)	GraalVM Native Image
Startup	Segundos (warmup necessário)	~50ms (instantâneo)
Peak performance	Máxima — C2 adaptativo	Inferior — sem JIT em runtime
Uso de memória	Maior (JVM + heap)	Muito menor
Reflexão dinâmica	✅ Suportada nativamente	⚠️ Requer `reflect-config.json`
Spring Boot simples	✅ Funciona out of the box	✅ Funciona (GraalVM plugin)
Spring Boot complexo	✅ Funciona sempre	⚠️ Pode precisar de ajustes
Caso ideal	APIs, microsserviços com estado	Serverless, CLIs, functions
Build time	Padrão	Muito mais longa (5–15 min)

❌ Por que Native Image tem peak performance menor?

O JIT é adaptativo: ele observa o comportamento real em runtime e aplica otimizações especulativas baseadas nesse comportamento. O Native Image compila tudo antes, sem dados de runtime. Otimizações como devirtualization especulativa e inlining agressivo de chamadas polimórficas ficam comprometidas. Para cargas variáveis e código polimórfico, o C2 vence no longo prazo.

Seção 6 — Project Leyden

A solução definitiva para o warmup — sem abrir mão do JIT

O warmup do JIT sempre foi o calcanhar de Aquiles do Java em ambientes cloud-native. Containers que sobem a cada scale-out, funções serverless, pods Kubernetes, todos começam do zero, sem cache JIT. O Project Leyden resolve isso.

Como funciona — em dois passos

Passo 1 — Training Run (executado uma única vez)

A JVM roda a aplicação normalmente e salva em um arquivo .aot tudo que normalmente faria no startup e warmup: classes carregadas e linkadas, perfis de invocação, código JIT compilado para os hot spots identificados.

Passo 2 — Execuções de Produção (usam o cache)

Todos os starts subsequentes carregam o cache. Classes já linkadas, hot spots já identificados, código C2 já compilado para os métodos críticos. A aplicação começa com performance de pico desde o primeiro request — sem warmup.

# Passo 1: Training run (uma vez, fora de produção)
java -XX:AOTCacheOutput=app.aot -jar app.jar

# Passo 2: Todas as execuções em produção
java -XX:AOTCache=app.aot -jar app.jar

# Spring Boot 3.3+ já integra esse workflow nativamente

Linha do tempo dos JEPs do Leyden

Versão	Ano	JEP	O que entrega
JDK 24	2024	JEP 483	AOT Class Loading & Linking — classes pre-carregadas. Spring PetClinic 42% mais rápido no startup.
JDK 25	2025	JEP 515	AOT Method Profiling — perfis JIT no cache. Warmup praticamente eliminado.
JDK 26	2026	JEP 516	Cache universal, agnóstico de GC. Suporte a ZGC e Shenandoah. Cache baseline incluído no JDK — zero config.

Comparativo final: os três mundos

┌──────────────────────────┬────────────────────────────┬──────────────────────────┐
│    JIT CLÁSSICO          │   GRAALVM NATIVE IMAGE     │   PROJECT LEYDEN         │
│    (HotSpot)             │                            │   (JDK 25+)              │
├──────────────────────────┼────────────────────────────┼──────────────────────────┤
│ ✓ Portabilidade total    │ ✓ Startup instantâneo      │ ✓ Startup ~42% mais      │
│ ✓ Peak performance max   │ ✓ Memória mínima           │   rápido                 │
│ ✓ Reflexão dinâmica      │ ✓ Ideal para serverless    │ ✓ Warmup eliminado       │
│ ✓ Sem mudanças no código │                            │ ✓ Peak performance max   │
│                          │ ✗ Sem JIT em runtime       │ ✓ Reflexão dinâmica      │
│ ✗ Startup lento          │ ✗ Peak performance menor   │ ✓ Sem mudanças no código │
│ ✗ Warmup (código frio)   │ ✗ Reflexão = config manual │                          │
│                          │ ✗ Build demorada           │ ✗ Requer training run    │
└──────────────────────────┴────────────────────────────┴──────────────────────────┘

✅ A frase que resume tudo

GraalVM Native Image substitui o JIT — você abre mão de otimizações adaptativas em troca de startup instantâneo.

Project Leyden preserva o JIT — você tem startup rápido e peak performance máxima, sem abrir mão de nada.

Para sistemas bancários com Spring Boot, Hibernate e cargas variáveis, Leyden é a resposta certa.

Seção 7 — Quando Parar de se Preocupar com Warmup

A resposta direta, versão por versão

Versão	O que muda	Impacto real no warmup
Java 8	Tiered Compilation padrão	JIT mais inteligente. Warmup ainda existe, mas bem gerenciado.
Java 11	AppCDS estável	Startup ~10–20% mais rápido. Warmup JIT inalterado.
Java 17	AppCDS aprimorado + ZGC estável	Startup melhorado. Warmup JIT inalterado.
Java 21	Virtual Threads estáveis	⚠️ NÃO resolve warmup. Resolve throughput I/O-bound. São problemas diferentes.
Java 24	Leyden: AOT Class Loading	Startup 40%+ mais rápido. Warmup parcialmente melhorado.
Java 25	Leyden: AOT Method Profiling	✅ WARMUP PRATICAMENTE ELIMINADO. JIT começa otimizando do primeiro request.
Java 26	AOT Cache universal + ZGC	Zero configuração extra. Cache baseline no JDK. Solução madura e completa.

✅ Resposta direta: Java 25+ com AOT Method Profiling (JEP 515)

A partir do Java 25, o warmup do JIT deixa de ser uma preocupação para a grande maioria das aplicações. O AOT Cache armazena os perfis de execução dos métodos quentes, permitindo que o C2 compile os hot spots imediatamente no startup, sem precisar observar execuções repetidas. Para quem usa Spring Boot 3.3+, o suporte já está integrado com configuração mínima.

Contexto prático para Kubernetes e auto-scaling

Sem Leyden:

Cada novo pod sobe sem cache JIT
Os primeiros requests recebem latências elevadas
Em ambientes com escala horizontal frequente, isso impacta diretamente o p95 e p99 de latência

Com Leyden (JDK 25+):

O pod sobe com o AOT Cache
Hot spots já identificados, código C2 já compilado
Performance de pico desde o primeiro request
O AOT Cache pode ser incluído na imagem Docker — sem step extra em runtime

Para ambientes bancários com Spring Boot + Kubernetes: JDK 25 com AOT Method Profiling é o caminho. Não exige mudanças no código, preserva todo o ecossistema Spring, mantém a performance máxima do C2 e elimina o problema de cold start que existe hoje.

Seção 8 — Linha do Tempo e Resumo Executivo

Evolução completa da performance JVM

Versão	Ano	Marco
Java 1.0	1996	Interpretado puro — 10–20× mais lento que C
Java 1.1	1997	Primeiro JIT experimental — ainda muito básico
Java 1.3	2000	HotSpot JVM como padrão — JIT adaptativo com C1 e C2
Java 7	2011	Tiered Compilation disponível como opção
Java 8	2014	Tiered Compilation padrão — C1+C2 automático
Java 9	2017	JVMCI: suporte ao Graal JIT como alternativa ao C2
Java 11	2018	AppCDS estável — startup melhorado
Java 21	2023	Virtual Threads estáveis — throughput I/O-bound resolvido
Java 24	2024	Project Leyden: AOT Class Loading — startup 42% mais rápido
Java 25	2025	Project Leyden: AOT Method Profiling — warmup eliminado na prática
Java 26	2026	AOT Cache universal + ZGC — solução madura e completa

Resumo executivo — referência rápida

Conceito	O que você precisa saber
JIT	A JVM compila hot spots para código nativo em runtime, em thread separada, sem parar a aplicação.
Hot spot	Método com alto número de invocações ou iterações de loop — candidato à compilação JIT.
C1 (tiers 1–3)	Compila rápido com otimizações básicas. Coleta profiling para o C2.
C2 (tier 4)	Compila profundo com otimizações agressivas: inlining, escape analysis, devirtualization, loop unrolling.
Tiered Compilation	Estratégia padrão desde Java 8: usa C1 primeiro (startup rápido) e C2 depois (peak performance).
Code Cache	Região de memória onde vive o código nativo compilado. 240 MB padrão no Java 8+. Cheio = problema grave.
Deoptimização	JVM joga fora a versão C2 se o comportamento mudar. Normal, mas frequência alta indica código inconsistente.
Graal JIT	Substituto do C2 escrito em Java. Mesmo modelo JIT, otimizações diferentes. Ativo via `-XX:+UseJVMCICompiler`.
GraalVM Native Image	AOT total: sem JVM em runtime, sem warmup, mas sem JIT adaptativo. Ideal para serverless/CLIs.
Project Leyden	AOT Cache: treina uma vez, usa sempre. JDK 25 elimina warmup sem abrir mão do JIT ou do código atual.
Quando resolver	Java 25+ para enterprise/Spring. GraalVM Native Image para serverless/CLIs simples.

GraalVM vs sem GraalVM — análise com dados reais

O que os dados dizem sobre adoção em produção

Antes de entrar nos cenários, é importante calibrar as expectativas com números verificados.

O relatório New Relic State of the Java Ecosystem 2024 — baseado em dados de observabilidade de centenas de milhares de aplicações em produção — não registrou GraalVM Native Image como uma categoria de uso relevante entre as aplicações monitoradas. O relatório rastreia versões de JDK, vendors e GCs, mas o Native Image sequer aparece como item mensurável, o que por si só indica adoção marginal no universo enterprise geral. ¹

O relatório Azul State of Java 2025 — com mais de 2.000 profissionais Java respondentes globalmente, confirma que 99% das organizações pesquisadas utilizam Java ativamente, com quase 70% delas tendo mais da metade de suas aplicações rodando na JVM. O foco absoluto das empresas continua sendo JVM clássica com HotSpot. ²

O InfoQ Java Trends Report 2024 classifica o GraalVM Native Image para startup rápido na categoria "Early Majority" o que significa que a tecnologia existe e funciona, mas ainda não é mainstream. Para contexto, "Early Majority" no modelo de adoção de tecnologia representa algo entre 16% e 50% do mercado potencial, mas isso descreve o estágio de maturidade da tecnologia, não sua penetração real em produção. ³

Um dado de produção concreto vem do blog BackendBytes (fevereiro de 2026), que documentou migrações reais de equipes Spring Boot para Native Image: startup caindo de 7 segundos para 80ms, memória de 480 MB para 130 MB, mas com throughput em steady state 10 a 25% menor em comparação ao JIT. Esse número de queda de throughput é consistente entre múltiplas equipes migradas. ⁴

Um dado importante de contexto estratégico: em setembro de 2025, a Oracle anunciou o desacoplamento do GraalVM do Java SE, descontinuando o GraalVM Native Image para clientes do Java SE Product (Oracle JDK pago). O argumento oficial é que os objetivos de startup rápido e menor footprint serão perseguidos pelo Project Leyden como parte padrão do OpenJDK. Clientes usando o Graal JIT foram orientados a migrar de volta ao HotSpot JIT padrão. ⁵

O GraalVM Native Image continua disponível pela GraalVM Community Edition (mantida pela Oracle Labs e pela comunidade), mas o sinal estratégico é claro: a Oracle apostou no Leyden como caminho padrão, não no Native Image.

Os três cenários com benefícios e trade-offs reais

Cenário 1 — Sem GraalVM: HotSpot JIT puro

É o padrão atual de produção da grande maioria das aplicações Java no mundo. Você usa o C1 e o C2 da HotSpot, com Tiered Compilation ativa desde o Java 8.

Benefícios:

Peak performance máxima no longo prazo, o C2 faz otimizações adaptativas impossíveis de reproduzir em AOT
Funciona com qualquer biblioteca, framework ou padrão de reflexão sem configuração extra
Todo o ecossistema Spring, Hibernate, Jackson, Kafka funciona sem ressalvas
Deoptimização e recompilação automáticas quando o comportamento do código muda
Suporte e documentação amplíssimos, é a JVM que todos conhecem
Build time idêntico ao padrão, nenhuma etapa adicional

Trade-offs:

Startup lento: aplicações Spring Boot complexas levam de 4 a 11 segundos para estar prontas
Warmup necessário: os primeiros requests são mais lentos enquanto o JIT "aprende"
Em Kubernetes com auto-scaling, cada novo pod começa do zero sem cache JIT
Uso de memória maior, a JVM, o heap e o Code Cache consomem mais RAM

Quando usar: APIs enterprise, microsserviços com Spring Boot complexo, sistemas com Hibernate ou qualquer uso intenso de reflexão, cargas variáveis onde o C2 adaptativo faz diferença. Ou seja: a maioria das aplicações bancárias em produção hoje.

Cenário 2 — GraalVM modo JIT (Graal no lugar do C2)

A JVM continua sendo a HotSpot. Tiered Compilation, Code Cache, profiling, tudo igual. Só o compilador do tier 4 muda: o C2 é substituído pelo Graal, ativado com -XX:+UseJVMCICompiler.

Benefícios:

Comportamento idêntico para o desenvolvedor, nenhuma mudança no código ou no processo de build
O compilador Graal é escrito em Java (não em C++), o que permite algoritmos de otimização mais sofisticados
Em workloads específicos com código muito regular e previsível, pode superar o C2 em throughput de pico
Mantém todas as vantagens do JIT: deoptimização, profiling adaptativo, reflexão dinâmica

Trade-offs:

Em setembro de 2025, a Oracle orientou explicitamente que clientes do Oracle JDK migrem de volta ao HotSpot JIT padrão, sinalizando que esse caminho não é o futuro ⁵
Benefício de performance não é garantido, em muitos workloads o desempenho é equivalente ou ligeiramente inferior ao C2
Menos testado em produção que o C2, ecossistema de suporte mais restrito
O Graal JIT continua disponível na GraalVM CE, mas fora do mainstream Oracle

Quando usar: experimentos de performance em workloads muito específicos, pesquisa, ou contextos onde você já usa GraalVM CE e quer avaliar. Não recomendado como estratégia padrão de produção após o desacoplamento anunciado pela Oracle.

Cenário 3 — GraalVM Native Image (AOT total)

O bytecode vira um executável nativo antes de rodar. Não há JVM em runtime. Não há JIT. Não há warmup.

Benefícios:

Startup instantâneo: de 4–11 segundos para 40–120ms em migrações documentadas ⁴
Uso de memória drasticamente menor: redução de 60–70% em casos reais (480 MB → 130 MB) ⁴
Ideal para ambientes com SLA de startup agressivo no Kubernetes, resolve o problema de pods perdendo a janela de readiness
Binário auto-contido: não depende de JVM instalada no ambiente de execução
Superfície de ataque reduzida: código morto removido na análise estática de build time
Menor custo em funções serverless cobradas por tempo de execução e memória

Trade-offs:

Throughput em steady state 10–25% menor que o JIT em produção real, dado documentado em múltiplas migrações ⁴
A "closed-world assumption" exige que todo o código acessível seja conhecido em build time, reflexão dinâmica, proxies e carregamento dinâmico de classes precisam de configuração explícita
Spring Boot, Hibernate, Jackson e similares funcionam, mas exigem hints de reflexão no reflect-config.json ou anotações específicas, o Spring Native/GraalVM plugin automatiza parte disso, mas não tudo
Build time muito mais longa: de 5 a 15 minutos para aplicações médias, dependendo do tamanho do classpath
Debugging em produção é mais limitado, sem JVM, sem JVMTI, ferramentas como JFR e Async Profiler têm suporte parcial
Sem deoptimização: se o comportamento mudar, não há mecanismo de correção automática em runtime
A descontinuação para clientes Oracle JDK cria incerteza sobre o suporte de longo prazo fora da GraalVM CE ⁵

Quando usar: serviços serverless (AWS Lambda, Google Cloud Run), CLIs distribuídas como executável, microsserviços muito simples sem reflexão complexa, ambientes com SLA de startup impossível de cumprir com JVM clássica.

Decisão rápida

Sua aplicação é...

  API enterprise / Spring Boot complexo / reflexão / carga variável?
  └─► HotSpot JIT puro  (+ Leyden no JDK 25+ para resolver o warmup)

  Serverless / CLI / startup crítico / memória muito restrita?
  └─► GraalVM Native Image  (com validação cuidadosa de reflexão)

  Quero experimentar Graal JIT sem mudar nada?
  └─► -XX:+UseJVMCICompiler  (mas avalie o desacoplamento Oracle antes)

Referências Bibliográficas

[1] NEW RELIC. 2024 State of the Java Ecosystem Report. San Francisco: New Relic, 2024. Disponível em: https://newrelic.com/resources/report/2024-state-of-the-java-ecosystem. Acesso em: jun. 2025.

[2] AZUL SYSTEMS. Azul 2025 State of Java Survey & Report. Sunnyvale: Azul, jan. 2025. Disponível em: https://www.azul.com/newsroom/azul-2025-state-of-java-survey-report/. Acesso em: jun. 2025.

[3] INFOQ EDITORIAL TEAM. InfoQ Java Trends Report — December 2024. InfoQ, dez. 2024. Disponível em: https://www.infoq.com/articles/java-trends-report-2024/. Acesso em: jun. 2025.

[4] BACKENDBYTES. GraalVM Native Images in Production: From 5-Second Startup to 50ms. BackendBytes, fev. 2026. Disponível em: https://backendbytes.com/articles/graalvm-native-images-java-production/. Acesso em: jun. 2025.

[5] ORACLE. Detaching GraalVM from the Java Ecosystem Train. Oracle Java Blog, set. 2025. Disponível em: https://blogs.oracle.com/java/detaching-graalvm-from-the-java-ecosystem-train. Acesso em: jun. 2025.

[6] OPENJDK. JEP 483: Ahead-of-Time Class Loading & Linking. OpenJDK, 2024. Disponível em: https://openjdk.org/jeps/483. Acesso em: jun. 2025.

[7] OPENJDK. JEP 514: Ahead-of-Time Command-Line Ergonomics. OpenJDK, 2025. Disponível em: https://openjdk.org/jeps/514. Acesso em: jun. 2025.

[8] OPENJDK. JEP 515: Ahead-of-Time Method Profiling. OpenJDK, 2025. Disponível em: https://openjdk.org/jeps/515. Acesso em: jun. 2025.

[9] OPENJDK. JEP 516: Ahead-of-Time Cache. OpenJDK, 2026. Disponível em: https://openjdk.org/jeps/516. Acesso em: jun. 2025.

[10] BAELDUNG. JVM Tiered Compilation. Baeldung, 2024. Disponível em: https://www.baeldung.com/jvm-tiered-compilation. Acesso em: jun. 2025.

[11] ORACLE GRAAL TEAM. Announcing Oracle GraalVM for JDK 24. Oracle Graal Blog, 2024. Disponível em: https://blogs.oracle.com/graal/oracle-graalvm-for-jdk-24. Acesso em: jun. 2025.

[12] GRAALVM. Native Image Documentation. GraalVM, 2025. Disponível em: https://www.graalvm.org/latest/docs/. Acesso em: jun. 2025.

[13] INFOQ EDITORIAL TEAM. InfoQ Java Trends Report 2025. InfoQ, dez. 2025. Disponível em: https://www.infoq.com/articles/java-trends-report-2025/. Acesso em: jun. 2025.

Documento de estudo pessoal · Diego Brandão · 2025

Migração do Java 11 para Java 17: Benefícios e Trade-offs com Evidências Técnicas

Diego de Sousa Brandão — Sun, 07 Sep 2025 18:45:03 +0000

Índice

Resumo
Benefícios da Migração
- 1.1 Melhorias de Performance
- 1.2 Novos Recursos de Linguagem
- 1.3 Melhorias de Segurança
- 1.4 Suporte Long-Term Support (LTS)
Trade-offs e Desafios
- 2.1 Questões de Compatibilidade
- 2.2 Desafios Específicos da Migração
- 2.3 Custos de Migração
Casos de Estudo Reais
- 3.1 Salesforce
- 3.2 Halodoc
Recomendações Práticas
- 4.1 Estratégia de Migração
- 4.2 Alternativas Graduais
Conclusão
Referências

Resumo

A migração do Java 11 para Java 17 representa uma atualização estratégica significativa para aplicações enterprise. Java 17 é uma versão Long-Term Support (LTS) que oferece melhorias substanciais em performance, segurança e recursos de linguagem, com suporte Oracle Premier até setembro de 2026. Este artigo apresenta uma análise técnica baseada em evidências sobre os benefícios e trade-offs desta migração.

Estudos de benchmark demonstram ganhos de performance de 6-26% com Java 17, enquanto novos recursos como Records, Sealed Classes e melhor tratamento de NullPointerException melhoram significativamente a produtividade do desenvolvedor. Os principais trade-offs incluem questões de compatibilidade com bibliotecas legadas e a necessidade de atualização de dependências.

1. Benefícios da Migração

1.1 Melhorias de Performance

Evidências de Benchmark Independentes

A OptaPlanner conduziu benchmarks extensivos comparando Java 11, 16 e 17, utilizando hardware estável (Intel Xeon Silver 4116 @ 2.1 GHz, 128 GiB RAM) em problemas de otimização reais durante 5 minutos cada. Os resultados demonstraram melhorias consistentes de performance.

A Azul Systems reportou em benchmarks de 2025 que OpenJDK 17 foi 6% mais rápido que a baseline, enquanto soluções otimizadas como Azul Platform Prime alcançaram 26% de melhoria.

Melhorias no Garbage Collection

Java 17 introduz melhorias no garbage collector, particularmente em situações de baixa memória, resultando em ganhos de performance para aplicações que lidam com grandes datasets ou operações intensivas de memória.

O G1 garbage collector tornou-se padrão a partir do Java 9, oferecendo performance mais consistente e tempos de resposta mais previsíveis. ZGC (Z Garbage Collector) tornou-se production-ready no JDK 17, oferecendo coleta de lixo de baixa latência (sub-10ms) para heaps de até vários terabytes. Shenandoah está disponível em builds específicos como Red Hat OpenJDK e Amazon Corretto, mas não faz parte do Oracle JDK oficial.

1.2 Novos Recursos de Linguagem

Records

Records permitem criar classes de dados imutáveis especificando apenas os campos necessários; todos os outros métodos são gerados automaticamente. Records atuam como classes de dados onde todos os campos são final, garantindo imutabilidade da referência. Importante: Records são imutáveis por contrato apenas se usados com tipos imutáveis. O fato dos campos serem final garante imutabilidade da referência, mas não garante thread-safety absoluto se o campo for um objeto mutável.

// Java 11 - Classe tradicional
public class DataClass {
    private final Integer id;
    private final String name;

    public DataClass(Integer id, String name) {
        this.id = id;
        this.name = name;
    }

    public Integer getId() { return id; }
    public String getName() { return name; }

    @Override
    public boolean equals(Object o) { /* implementação */ }
    @Override
    public int hashCode() { /* implementação */ }
}

// Java 17 - Record
public record DataClass(Integer id, String name) {}

// Cuidado: Records com objetos mutáveis
public record PersonRecord(String name, List<String> hobbies) {}

PersonRecord person = new PersonRecord("João", new ArrayList<>());
person.hobbies().add("futebol"); // Modifica o estado interno!
// Para verdadeira imutabilidade, use List.copyOf() ou Collections.unmodifiableList()

Sealed Classes

Sealed Classes foram adicionadas à linguagem Java, restringindo quais outras classes ou interfaces podem estendê-las ou implementá-las, melhorando a segurança de tipos e organização do código.

Pattern Matching e Switch Expressions

Switch expressions melhoradas permitem sintaxe mais concisa e segura. O operador instanceof também foi aprimorado, permitindo verificação de tipo e cast em uma única linha. A principal vantagem é legibilidade e segurança de tipo, eliminando a necessidade de casts explícitos e reduzindo a possibilidade de ClassCastException.

Melhor Tratamento de NullPointerException

Uma atualização incrivelmente útil no Java 17 são as NullPointerExceptions melhoradas! Finalmente, nos logs de stack trace, é possível ver qual campo específico causou a NullPointerException.

// Java 17 - NPE melhorada
String s = null;
System.out.println(s.toLowerCase());

// Exception output:
// java.lang.NullPointerException: Cannot invoke "String.toLowerCase()" 
// because "s" is null

1.3 Melhorias de Segurança

Atualizações Regulares de Segurança

O modelo de lançamento de segurança Java mudou para estar alinhado com o cronograma Oracle Critical Patch Update (CPU), onde releases CPU são lançados na terceira terça-feira de janeiro, abril, julho e outubro.

JDK 17 introduziu melhorias significativas de segurança incluindo modo de validação segura XML habilitado por default, algoritmos SHA-1 desabilitados por padrão em assinaturas XML, e melhorias no suporte OCSP com requisições HTTP GET para performance.

Encapsulamento Forte de Internals do JDK

JEP 403 fortalece o encapsulamento de internals do JDK. Java 17 é fortemente encapsulado por padrão, então reflexão para internals do JDK não é mais permitida. Código que acessa campos e métodos não-públicos de APIs java.* lançará InaccessibleObjectException.

1.4 Suporte Long-Term Support (LTS)

Java 17 é uma versão LTS com Oracle Premier Support até setembro de 2026, proporcionando estabilidade e atualizações de segurança por período estendido. O processo de LTS garante que essas versões tornem-se mais estáveis e seguras devido a correções de bugs, melhorias de performance e patches de segurança.

2. Trade-offs e Desafios

2.1 Questões de Compatibilidade

Deprecação e Remoção de APIs

Provavelmente a mudança mais significativa relacionada à segurança no JDK 17 é JEP 411: Deprecate the Security Manager for Removal. JDK 17 inicia esse processo depreciando várias APIs do Security Manager.

Vários parâmetros JVM foram removidos ou depreciados até o Java 17. Se sua aplicação dependia das funcionalidades experimentais AOT ou Graal JIT no Java 11, considere a transição para GraalVM.

Problemas com Bibliotecas de Terceiros

Nem todas as bibliotecas e frameworks de terceiros têm garantia de suporte ao Java 17 imediatamente. Verificar compatibilidade e atualizações é crucial. Ferramentas de build (Maven, Gradle) e IDEs devem ser atualizadas para suportar Java 17.

2.2 Desafios Específicos da Migração

Problemas com Lombok

Um problema recorrente em migrações é incompatibilidade com versões antigas do Lombok. Um erro comum é:

java.lang.IllegalAccessError: class lombok.javac.apt.LombokProcessor cannot access class com.sun.tools.javac.processing.JavacProcessingEnvironment

A solução prática é atualizar o Lombok para uma versão compatível (por exemplo, >= 1.18.22) e validar a compilação/annotation-processing em ambientes CI e locais. Em casos extremos, configure o --add-opens temporariamente apenas para testes, mas prefira atualizar bibliotecas e remover dependências de internals.

Configuração de Garbage Collection

Embora coletores de lixo mais novos como G1 ofereçam melhor performance, eles podem requerer ajustes. Aplicações com configurações customizadas de GC precisarão revisitar essas configurações.

Modularização (Opcional)

Importante: A modularização NÃO é obrigatória para Java 17. Aplicações podem continuar usando o classpath tradicional exatamente como em Java 11. A migração para o Module System (JPMS) é completamente opcional e só deve ser considerada se você quiser benefícios específicos como:

Encapsulamento mais forte de pacotes internos
Dependências explícitas entre módulos
Redução de footprint de memória em aplicações modulares

A grande maioria das aplicações enterprise pode migrar para Java 17 sem qualquer mudança no sistema de módulos.

2.3 Custos de Migração

Testes Extensivos Necessários

Antes de migrar microserviços Java do JDK 11 para JDK 17, é essencial garantir que todos os testes unitários, de integração e de sistema passem com sucesso. Este passo é necessário para verificar que a aplicação funciona como esperado.

Tempo de Desenvolvimento

A Salesforce reportou que a migração do JDK 11 para JDK 17 levou três anos de planejamento com sete meses de desenvolvimento ativo. Importante: Este prazo reflete o tamanho massivo do ecossistema Salesforce (Sales Cloud, Service Cloud, Marketing Cloud) com milhares de aplicações e microserviços. Empresas menores terão prazos significativamente mais curtos - a maioria das organizações pode completar a migração em algumas semanas ou meses, dependendo da complexidade da arquitetura.

No entanto, as lições aprendidas pela Salesforce permitirão que futuras migrações, como JDK 21, sejam completadas em apenas um ano, demonstrando o valor do aprendizado organizacional.

3. Casos de Estudo Reais

3.1 Salesforce

A Salesforce liderou uma migração desafiadora do JDK 11 para JDK 17 para garantir performance e escalabilidade das aplicações principais, incluindo Sales Cloud, Service Cloud e Marketing Cloud. A migração entregou melhorias significativas de performance, possibilitando processamento mais rápido.

3.2 Halodoc

A Halodoc migrou seus microserviços backend Java do JDK 11 para JDK 17, enfrentando desafios específicos como conflitos entre dependências Redisson e Jackson, que foram resolvidos através de cuidadoso exame das versões de dependências e ajustes necessários para garantir compatibilidade.

4. Recomendações Práticas

4.1 Estratégia de Migração

Análise de Dependências: Analisar dependências do projeto para garantir compatibilidade com Java 17. Atualizar bibliotecas ou frameworks desatualizados para versões que suportem a nova versão Java.
Ambiente de Testes: Testar aplicação em ambiente especial de testes com JDK atualizado. Revisar e atualizar todas as dependências e ferramentas de build para versões compatíveis com JDK 17.
Análise Estática: Executar verificação estática de código para identificar onde problemas podem ocorrer. Ferramentas como Checkstyle, PMD, ou SpotBugs podem ser utilizadas.

4.2 Alternativas Graduais

Para organizações não prontas para migração completa, alguns fornecedores de JDK oferecem soluções otimizadas que podem combinar versões de API com JVMs mais recentes. É recomendável avaliar benchmarks específicos para seu caso de uso antes de adotar soluções comerciais que prometem melhorias de performance específicas.

5. Conclusão

A migração do Java 11 para Java 17 oferece benefícios substanciais e mensuráveis:

Benefícios Principais:

Melhorias de performance de 6-26% conforme benchmarks independentes
Recursos de linguagem modernos como Records, Sealed Classes e melhor tratamento de exceções (NPE melhoradas desde Java 14)
Melhorias significativas de segurança e encapsulamento forte
Suporte LTS: Oracle Premier até 2026, Extended até 2029, com alternativas de suporte de outros fornecedores
ZGC production-ready para aplicações que necessitam baixa latência

Trade-offs Principais:

Necessidade de atualização de dependências e ferramentas
Problemas específicos com bibliotecas como Lombok
Investimento em tempo de desenvolvimento e testes
Configurações de GC podem requerer ajustes dependendo do perfil da aplicação

Graças à forte compatibilidade retroativa do Java, a migração do 11 para o 17 tende a ser incremental e de baixo risco, especialmente em comparação com saltos maiores (ex: 8 → 17). A compatibilidade permite mudar para Java 17 sem alterações de código obrigatórias (modularização é opcional) e aproveitar todos os recursos atualizados. A versão 17 é Long-term Support, garantindo atualizações de segurança por período estendido com múltiplas opções de fornecedores.

Para organizações enterprise, a migração é altamente recomendada, especialmente considerando que aplicações de grande escala e alta carga verão definitivamente melhor performance, tempo de inicialização mais rápido e menor footprint de memória após a migração.

6. Referências

HashStudioz Technologies. (2024). Java Project Migration: Step-by-Step Guide from Java 11 to 17. Retrieved from https://www.hashstudioz.com/blog/java-11-to-java-17-migration-guide/
Bell-SW. (2024). How to Migrate from Java 11 to Java 17: Step-by-Step Tutorial. Retrieved from https://bell-sw.com/blog/migration-from-java-11-to-java-17/
HackerNoon. (2023). Is Migrating From Java 11 to Java 17 Worth It? Retrieved from https://hackernoon.com/is-migrating-from-java-11-to-java-17-worth-it
Medium - Pradeep Chirumamilla. (2024). Java 11 to Java 17 Migration: A Guide with Key Features and Code Implementation. Retrieved from https://medium.com/@pradeepchirumamilla01/java-11-to-java-17-migration-a-guide-with-key-features-and-code-implementation-dd63e0bd79e3
Halodoc Engineering. (2023). A Practical Guide to Migrating from JDK 11 to JDK 17. Retrieved from https://blogs.halodoc.io/jdk-17-migration/
Zenesys. (2024). Migrating a Project From Java 11 to Java 17: A Step-by-Step Guide. Retrieved from https://www.zenesys.com/migrating-a-project-from-java-11-to-java-17-a-step-by-step-guide
Medium - Alex Klimenko. (2025). Migrating from Java 8 to Java 17: What Changed and Potential Issues. Retrieved from https://medium.com/@alxkm/migrating-from-java-8-to-java-17-what-changed-and-potential-issues-85d2e85fc1ca
DEV Community - NIX. (2022). Migrating a Project From Java 11 to Java 17: A Step-by-Step Guide for Developers. Retrieved from https://dev.to/nix/migrating-a-project-from-java-11-to-java-17-a-step-by-step-guide-for-developers-42n
Salesforce Engineering. (2025). Behind Salesforce's JDK 11 to JDK 17 Migration. Retrieved from https://engineering.salesforce.com/behind-salesforces-jdk-11-to-jdk-17-migration-lessons-for-modernizing-large-scale-java-applications/
Medium - Alex Klimenko. (2024). Modernizing Legacy Java: A Practical Guide to Migrating to Java 17/21+. Retrieved from https://medium.com/@alxkm/modernizing-legacy-java-a-practical-guide-to-migrating-to-java-17-21-b3ab6a215f1f
OptaPlanner. (2021). How much faster is Java 17? Retrieved from https://www.optaplanner.org/blog/2021/09/15/HowMuchFasterIsJava17.html
Oracle. (2021). JDK 17 Release Notes, Important Changes, and Information. Retrieved from https://www.oracle.com/java/technologies/javase/17-relnote-issues.html
GitHub - Ionut Balosin. (2024). JVM Performance Benchmarks. Retrieved from https://github.com/ionutbalosin/jvm-performance-benchmarks
Azul Systems. (2025). Benchmarks Show Faster Java Performance Improvement. Retrieved from https://www.azul.com/blog/benchmarks-show-faster-java-performance-improvement/
Oracle. (2014). Avoiding Benchmarking Pitfalls on the JVM. Retrieved from https://www.oracle.com/technical-resources/articles/java/architect-benchmarking.html
oj! Algorithms. (2022). JDK17 Benchmark. Retrieved from https://www.ojalgo.org/2021/11/jdk17-benchmark/
Oracle. (2024). Overview of Java SE Subscription Enterprise Performance Pack. Retrieved from https://docs.oracle.com/en/java/java-components/enterprise-performance-pack/epp-user-guide/overview.html
Ionut Balosin. (2023). JVM Performance Comparison for JDK 17. Retrieved from https://ionutbalosin.com/2023/03/jvm-performance-comparison-for-jdk-17/
Pretius. (2022). Java 17 features: A comparison between versions 8 and 17. Retrieved from https://pretius.com/blog/java-17-features
Oracle. (2021). JDK Releases. Retrieved from https://www.java.com/releases/
Oracle. (2024). Consolidated JDK 17 Release Notes. Retrieved from https://www.oracle.com/java/technologies/javase/17all-relnotes.html
Oracle. (2025). Oracle Java SE Support Roadmap. Retrieved from https://www.oracle.com/java/technologies/java-se-support-roadmap.html
Baeldung. (2024). New Features in Java 17. Retrieved from https://www.baeldung.com/java-17-new-features
Oracle. (2024). Java™ SE Development Kit 17, 17.0.15 Release Notes. Retrieved from https://www.oracle.com/java/technologies/javase/17-0-15-relnotes.html
Oracle. (2024). Java Security Resource Center. Retrieved from https://www.oracle.com/java/technologies/security.html
Wikipedia. (2025). Java version history. Retrieved from https://en.wikipedia.org/wiki/Java_version_history
Sean Mullan. (2021). JDK 17 Security Enhancements. Retrieved from https://seanjmullan.org/blog/2021/09/14/jdk17
Red Hat. (2024). OpenJDK Life Cycle and Support Policy. Retrieved from https://access.redhat.com/articles/1299013
Oracle. (2021). Java Platform, Standard Edition Oracle JDK Migration Guide, Release 11. Retrieved from https://docs.oracle.com/en/java/javase/11/migrate/index.html
Oracle. (2024). Migrating From JDK 8 to Later JDK Releases. Retrieved from https://docs.oracle.com/en/java/javase/17/migrate/migrating-jdk-8-later-jdk-releases.html

Java Records vs Lombok: Guia Definitivo para Escolher a Ferramenta Certa

Diego de Sousa Brandão — Mon, 21 Jul 2025 23:23:42 +0000

Introdução

A eterna busca por reduzir o código boilerplate em Java ganhou duas ferramentas poderosas: Java Records (introduzidos no Java 14 e estabilizados no Java 16) e Lombok (biblioteca amplamente adotada há anos). Embora ambos ataquem o mesmo problema - a verbosidade do Java - eles fazem isso de maneiras fundamentalmente diferentes, com implicações importantes para o design e arquitetura do seu código.

Este artigo vai além da comparação superficial de sintaxe e mergulha nas diferenças semânticas, casos de uso práticos e trade-offs de cada abordagem.

Records Java: Mais que Redução de Boilerplate

O que são Records?

Records não são apenas uma forma concisa de criar classes - eles são tipos de produto com semântica específica. Segundo a JEP 395:

"Records são portadores transparentes de dados imutáveis"

A palavra-chave aqui é transparente. Records seguem o princípio:

"A API de um record modela o estado, todo o estado, e nada além do estado"

Exemplo Básico

// Antes: 40+ linhas de código boilerplate
public class Pessoa {
    private final String nome;
    private final int idade;

    public Pessoa(String nome, int idade) {
        this.nome = nome;
        this.idade = idade;
    }

    public String getNome() { return nome; }
    public int getIdade() { return idade; }

    @Override
    public boolean equals(Object o) { /* implementação */ }
    @Override
    public int hashCode() { /* implementação */ }
    @Override
    public String toString() { /* implementação */ }
}

// Depois: 1 linha
public record Pessoa(String nome, int idade) {}

Características dos Records

Imutabilidade por Design: Todos os campos são private final
Transparência: Não há estado oculto
Construtores Canônicos: Gerados automaticamente
Métodos Padrão: equals(), hashCode(), toString() implementados automaticamente
Acessores: Métodos com o mesmo nome dos componentes

Lombok: Flexibilidade Através de Anotações

O que é Lombok?

Lombok é uma biblioteca que gera código em tempo de compilação através de anotações. Não impõe semântica específica - é pura redução de boilerplate.

Exemplo com Lombok

@Data
public class Produto {
    private String nome;
    private double preco;

    // Método personalizado
    public void aplicarDesconto(double desconto) {
        this.preco -= desconto;
    }
}

Principais Anotações

@Data: Gera getters, setters, equals(), hashCode(), toString()
@Value: Classe imutável (equivalente a um record)
@Builder: Padrão Builder
@Slf4j: Injeção de logger
@Getter/@Setter: Getters e setters específicos

Comparação Detalhada

Aspecto	Records	Lombok
Semântica	Tipos de produto transparentes	Geração de código
Imutabilidade	Por padrão	Opcional (@Value)
Flexibilidade	Limitada	Alta
Herança	Não suportada	Suportada
Estado Oculto	Proibido	Permitido
Dependência Externa	Não	Sim
Versão Java	14+ (estável no 16+)	Qualquer
Desempenho	Nativo	Geração em tempo de compilação

Quando Usar Records

✅ Use Records para:

1. DTOs (Data Transfer Objects)

public record UsuarioDTO(String nome, String email, LocalDate nascimento) {}

2. Objetos de Valor

public record Dinheiro(BigDecimal valor, String moeda) {}

3. Respostas de API

public record ApiResponse<T>(T dados, int status, String mensagem) {}

4. Configurações Imutáveis

public record DatabaseConfig(String url, String usuario, int timeout) {}

5. Entidades JPA Simples (com limitações)

@Entity
public record Produto(
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    Long id,
    String nome,
    BigDecimal preco
) {}

❌ Evite Records quando:

Precisar de mutabilidade
Necessitar de herança
Requerer estado oculto
Trabalhar com frameworks que exigem construtores sem argumentos
Precisar de métodos de ciclo de vida JPA complexos

Quando Usar Lombok

✅ Use Lombok para:

1. Entidades JPA Complexas

@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Usuario {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String nome;
    private String email;

    @OneToMany(mappedBy = "usuario", cascade = CascadeType.ALL)
    private List<Pedido> pedidos = new ArrayList<>();
}

2. Modelos de Negócio com Comportamento

@Data
@Slf4j
public class ContaBancaria {
    private String numero;
    private BigDecimal saldo;

    public void sacar(BigDecimal valor) {
        log.info("Sacando {} da conta {}", valor, numero);
        if (saldo.compareTo(valor) >= 0) {
            saldo = saldo.subtract(valor);
        } else {
            throw new IllegalArgumentException("Saldo insuficiente");
        }
    }
}

3. Builders Complexos

@Builder
@Data
public class Relatorio {
    private String titulo;
    private LocalDate dataInicio;
    private LocalDate dataFim;
    private List<String> colunas;
    private Map<String, Object> parametros;
}

// Uso
Relatorio relatorio = Relatorio.builder()
    .titulo("Vendas Mensais")
    .dataInicio(LocalDate.now().minusMonths(1))
    .dataFim(LocalDate.now())
    .colunas(Arrays.asList("produto", "quantidade", "valor"))
    .build();

❌ Evite Lombok quando:

O projeto exigir zero dependências externas
Houver problemas de compatibilidade com IDEs
A equipe não estiver familiarizada com a biblioteca
Precisar de garantias semânticas específicas

Casos de Uso Práticos

Cenário 1: Sistema de E-commerce

// DTO para resposta da API - USE RECORD
public record ProdutoResponse(
    Long id,
    String nome,
    BigDecimal preco,
    String categoria
) {}

// Entidade JPA com comportamento - USE LOMBOK
@Entity
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Produto {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String nome;
    private BigDecimal preco;
    private String categoria;
    private Integer estoque;

    public void reduzirEstoque(int quantidade) {
        if (estoque < quantidade) {
            throw new IllegalArgumentException("Estoque insuficiente");
        }
        this.estoque -= quantidade;
    }
}

Cenário 2: Sistema Bancário

// Objeto de valor imutável - USE RECORD
public record Moeda(String codigo, String nome, String simbolo) {}

// Entidade complexa com estado mutável - USE LOMBOK
@Entity
@Data
@EqualsAndHashCode(onlyExplicitlyIncluded = true)
@NoArgsConstructor
@Slf4j
public class Conta {
    @Id
    @EqualsAndHashCode.Include
    private String numero;

    private BigDecimal saldo;
    private String titular;

    @OneToMany(mappedBy = "conta", cascade = CascadeType.ALL)
    private List<Transacao> transacoes = new ArrayList<>();

    public void transferir(BigDecimal valor, Conta destino) {
        log.info("Transferindo {} de {} para {}", valor, this.numero, destino.numero);
        // Lógica de transferência
    }
}

Híbrido: Usando Records e Lombok Juntos

// Record com anotações do Lombok para funcionalidades adicionais
@Slf4j
public record ProcessamentoResult(
    String id,
    LocalDateTime timestamp,
    boolean sucesso,
    String mensagem
) {
    public ProcessamentoResult {
        log.info("Resultado do processamento {}: {}", id, sucesso ? "SUCESSO" : "FALHA");
    }
}

O Futuro: Spring Data Commons Recomenda Records

O Spring Framework oficialmente recomenda Records para DTOs e projeções:

// Recomendação oficial do Spring Data
public record NamesOnly(String firstname, String lastname) {}

// Em vez de usar Lombok
@Value
class NamesOnly {
    String firstname, lastname;
}

Diretrizes para Tomada de Decisão

Escolha Records quando:

✅ Estiver no Java 16+
✅ Precisar de objetos imutáveis
✅ Quiser garantias semânticas fortes
✅ Criar DTOs ou objetos de valor
✅ Buscar máxima performance (sem overhead de biblioteca)

Escolha Lombok quando:

✅ Precisar de flexibilidade máxima
✅ Trabalhar com herança
✅ Requerer mutabilidade
✅ Usar versões antigas do Java
✅ Precisar de funcionalidades como @builder ou @Slf4j

Use Ambos quando:

✅ Records para DTOs e objetos de valor
✅ Lombok para entidades e modelos de negócio
✅ Aproveitar o melhor de cada abordagem

Migração Gradual

Estratégia de Migração para Records:

Identifique candidatos: DTOs, objetos de valor, classes imutáveis simples
Migre gradualmente: Comece com classes menos críticas
Teste thoroughly: Verifique serialização e frameworks
Monitore performance: Records podem ter características diferentes

Exemplo de Migração:

// Antes (Lombok)
@Value
public class Endereco {
    String rua;
    String cidade;
    String cep;
}

// Depois (Record)
public record Endereco(String rua, String cidade, String cep) {}

Considerações de Performance

Records:

✅ Sem overhead de biblioteca
✅ Otimizações do compilador
⚠️ Criação de objetos em atualizações (imutabilidade)

Lombok:

✅ Código gerado otimizado
⚠️ Dependência de bibliotecas externas
⚠️ Possível overhead de reflection em algumas situações

Conclusão

A escolha entre Records e Lombok não é uma questão de "melhor" ou "pior", mas sim de adequação ao contexto:

Records brilham quando você precisa de semântica forte, imutabilidade e transparência
Lombok excele quando você precisa de flexibilidade, mutabilidade e compatibilidade com versões antigas

A tendência é usar ambos estrategicamente:

Records para DTOs, objetos de valor e dados imutáveis
Lombok para entidades complexas e modelos de negócio

Com o Java evoluindo e mais projetos adotando versões recentes, Records estão se tornando a escolha padrão para muitos casos de uso. No entanto, Lombok continuará relevante para cenários que demandam máxima flexibilidade.

A chave é entender que essas ferramentas resolvem problemas similares de maneiras diferentes, e a escolha certa depende das necessidades específicas do seu projeto, versão do Java e arquitetura da aplicação.

Referências Bibliográficas

Por que Abandonar @Autowired em Campos e Adotar Injeção via Construtor

Diego de Sousa Brandão — Tue, 15 Jul 2025 00:55:48 +0000

A injeção de dependência via construtor representa uma evolução natural das práticas de desenvolvimento com Spring Framework. Este documento apresenta os fundamentos técnicos que justificam essa transição e como implementá-la efetivamente em projetos modernos.

Contextualização

O Spring Framework oferece três formas principais de injeção de dependência: por campo (field injection), por setter e por construtor. Embora a injeção por campo seja visualmente mais limpa e requeira menos código, ela apresenta limitações significativas que impactam a qualidade, manutenibilidade e robustez das aplicações.

Principais Benefícios da Injeção via Construtor

1. Transparência e Dependências Explícitas

A injeção via construtor expõe claramente todas as dependências de uma classe em sua assinatura. Esta transparência facilita a compreensão do código, permitindo que desenvolvedores identifiquem rapidamente quais componentes uma classe necessita para funcionar corretamente.

Exemplo prático:

// Injeção por campo - dependências ocultas
@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;
    @Autowired
    private EmailService emailService;
    // Dependências não são evidentes na assinatura da classe
}

// Injeção por construtor - dependências explícitas
@Service
public class UserService {
    private final UserRepository userRepository;
    private final EmailService emailService;

    public UserService(UserRepository userRepository, EmailService emailService) {
        this.userRepository = userRepository;
        this.emailService = emailService;
    }
}

2. Testabilidade Aprimorada

A injeção via construtor elimina a dependência do contexto Spring durante os testes unitários. As classes podem ser instanciadas diretamente, com mocks injetados como parâmetros do construtor, resultando em testes mais rápidos e independentes.

Vantagens nos testes:

Eliminação da necessidade de reflection
Testes mais performáticos
Maior simplicidade na configuração de mocks
Independência do framework Spring nos testes unitários

3. Princípio Fail-Fast

A injeção por campo permite a criação de objetos mesmo quando dependências obrigatórias não estão disponíveis, resultando em NullPointerException apenas durante a execução. A injeção via construtor impede a criação do objeto sem suas dependências, tornando problemas visíveis imediatamente durante a inicialização da aplicação.

4. Imutabilidade e Thread Safety

Apenas através da injeção via construtor é possível definir campos de dependência como final. Esta imutabilidade oferece:

Segurança de thread: Campos final são thread-safe por natureza
Prevenção de efeitos colaterais: Impossibilita modificações acidentais das dependências
Clareza conceitual: Facilita o raciocínio sobre o estado dos objetos

5. Detecção Precoce de Dependências Circulares

Ciclos de dependência são detectados imediatamente durante a inicialização dos beans quando se utiliza injeção via construtor. Com injeção por campo, esses problemas podem permanecer ocultos até a execução específica do código afetado.

6. Incentivo ao Bom Design

A injeção via construtor evidencia classes com muitas dependências, naturalmente incentivando a aplicação do Princípio da Responsabilidade Única (SRP). Construtores com muitos parâmetros sinalizam a necessidade de refatoração e decomposição de responsabilidades.

7. Alinhamento com Práticas Modernas do Spring

Desde o Spring 4.3, o framework suporta injeção automática via construtor para classes com construtor único, dispensando a anotação @Autowired. Esta é a abordagem oficialmente recomendada pela equipe do Spring.

Implementação Prática

Padrão Recomendado (Sem Lombok)

@Service
public class OrderService {
    private final OrderRepository orderRepository;
    private final PaymentService paymentService;
    private final NotificationService notificationService;

    public OrderService(OrderRepository orderRepository, 
                       PaymentService paymentService,
                       NotificationService notificationService) {
        this.orderRepository = orderRepository;
        this.paymentService = paymentService;
        this.notificationService = notificationService;
    }

    // métodos da classe...
}

Com Lombok (Quando Apropriado)

@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;
    private final PaymentService paymentService;
    private final NotificationService notificationService;

    // métodos da classe...
}

Estratégia de Migração

Para Código Legado

Priorização: Inicie por classes críticas e com maior cobertura de testes
Refatoração gradual: Migre uma classe por vez para minimizar riscos
Testes de regressão: Garanta que a funcionalidade permanece inalterada
Validação: Verifique se não há dependências circulares expostas

Para Novos Desenvolvimentos

Adote injeção via construtor como padrão desde o início
Configure linters e ferramentas de análise estática para detectar uso de @Autowired em campos
Estabeleça como prática obrigatória em code reviews

Considerações Especiais

Dependências Opcionais

Para dependências opcionais, utilize @Autowired(required = false) no construtor ou considere padrões como Optional:

public UserService(UserRepository userRepository, 
                   @Autowired(required = false) CacheService cacheService) {
    this.userRepository = userRepository;
    this.cacheService = Optional.ofNullable(cacheService);
}

Performance

A injeção via construtor não apresenta overhead significativo em relação à injeção por campo. Os benefícios em qualidade e manutenibilidade superam amplamente qualquer diferença marginal de performance.

Conclusão

A adoção da injeção via construtor representa um investimento na qualidade de longo prazo do código. Os benefícios em testabilidade, clareza, robustez e alinhamento com as melhores práticas do Spring justificam plenamente essa transição.

Esta mudança não é apenas uma questão de preferência pessoal, mas uma evolução natural em direção a um código mais robusto, testável e maintível, alinhado com os princípios modernos de desenvolvimento de software.

Referências Bibliográficas

Maratona de Testes Automatizados — Step 1: Testes Unitários

Diego de Sousa Brandão — Sun, 08 Jun 2025 16:55:13 +0000

Maratona de Testes em Java: Da Teoria à Prática

Step 1: Testes Unitários - A Base Sólida da Pirâmide de Testes

Índice

Por que testes unitários são fundamentais?
O que realmente define um teste unitário?
O que exatamente devemos testar?
Estruturando seus testes com clareza
As ferramentas do ofício: JUnit e Mockito
Exemplo completo: Testando um Controller REST
Solitary vs. Sociable: Duas abordagens
DRY vs. DAMP nos testes
Evitando armadilhas comuns
Práticas avançadas e técnicas eficazes
Integração Contínua
Lições finais
Conclusão
Recursos recomendados
Referências Bibliográficas

Por que testes unitários são fundamentais?

Testes unitários são como os alicerces de um edifício: invisíveis para o usuário final, mas absolutamente essenciais para a integridade e sustentação de todo o sistema. Eles são a base da "Pirâmide de Testes", um conceito desenvolvido por Mike Cohn que organiza os testes em camadas de diferentes granularidades, indicando também quantos testes devemos ter em cada uma dessas camadas.

No artigo "The Practical Test Pyramid", Ham Vocke destaca que "seus testes unitários serão muito rápidos. Em uma máquina razoável, você poderá rodar milhares deles em poucos minutos." Esta velocidade é crucial para o desenvolvimento ágil, permitindo que você obtenha feedback praticamente instantâneo sobre suas alterações de código.

O que realmente define um teste unitário?

Um teste unitário eficaz possui estas características essenciais:

Característica	Descrição	Por quê isso importa
⚡ Rápido	Executa em milissegundos	Permite feedback imediato durante o desenvolvimento
🧩 Isolado	Sem dependência externa (rede, banco, disco)	Evita falhas por causas externas à unidade testada
🔄 Determinístico	Sempre produz o mesmo resultado	Elimina testes "flaky" (instáveis)
🎯 Focado	Verifica uma única lógica ou comportamento	Facilita identificar exatamente o que falhou
📖 Legível	Clara separação entre cenário e verificação	Permite manutenção e entendimento a longo prazo

Como Ham Vocke menciona, "teste pequenas partes da sua base de código em isolamento e evite acessar bancos de dados, o sistema de arquivos ou fazer requisições HTTP." Este isolamento é o que torna os testes unitários verdadeiramente "unitários".

O que exatamente devemos testar?

Segundo Vocke, "você pode escrever testes unitários para todas as classes do seu código de produção, independentemente da funcionalidade delas." Isso significa que quase tudo pode e deve ser testado unitariamente:

✅ Classes de domínio com regras de negócio
✅ Controllers (testar mapeamentos e respostas)
✅ Services (testar fluxos e orquestrações)
✅ Repositórios com lógica própria
✅ Utils, validators, formatters (funções de propósito específico)

O importante é focar no comportamento observável da unidade, não em sua implementação interna. Como Vocke recomenda, devemos "testar para o comportamento observável em vez de refletir a estrutura interna do código em nossos testes."

Estruturando seus testes com clareza

Ham Vocke destaca duas formas eficazes de estruturar testes, que ele chama de "uma boa estrutura para todos os seus testes":

📐 1. Arrange → Act → Assert

@Test
public void deveCalcularValorTotalComDesconto() {
    // Arrange - Prepara o cenário
    Produto produto = new Produto("Notebook", 2000.0);
    Cliente clienteVip = new Cliente("João", TipoCliente.VIP);

    // Act - Executa a ação
    double valorFinal = calculadoraPreco.calcular(produto, clienteVip);

    // Assert - Verifica o resultado
    assertEquals(1800.0, valorFinal, 0.001);
}

💬 2. Given → When → Then (estilo BDD)

@Test
public void clienteVipDeveReceberDescontoEspecial() {
    // Given - Dado um cliente VIP e um produto
    Cliente clienteVip = new Cliente("Maria", TipoCliente.VIP);
    Produto produto = new Produto("Smartphone", 1000.0);

    // When - Quando calcular o preço final
    double valorFinal = calculadoraPreco.calcular(produto, clienteVip);

    // Then - Então deve aplicar 10% de desconto
    assertEquals(900.0, valorFinal, 0.001);
}

Vocke sugere que este padrão "pode ser aplicado a outros testes de nível mais alto também. Em todos os casos, eles garantem que seus testes permaneçam fáceis e consistentes de ler."

As ferramentas do ofício: JUnit e Mockito

JUnit 5

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import static org.junit.jupiter.api.Assertions.*;

class CalculadoraTest {

    private Calculadora calc;

    @BeforeEach
    void setup() {
        calc = new Calculadora();
    }

    @Test
    @DisplayName("Soma de dois números positivos")
    void deveSomarDoisNumerosPositivos() {
        // Act
        int resultado = calc.somar(5, 3);

        // Assert
        assertEquals(8, resultado);
    }

    @Test
    @DisplayName("Divisão por zero deve lançar exceção")
    void deveLancarExcecaoAoDividirPorZero() {
        // Assert + Act (verificando exceção)
        assertThrows(ArithmeticException.class, () -> {
            calc.dividir(10, 0);
        });
    }
}

Mockito

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

@ExtendWith(MockitoExtension.class)
class PedidoServiceTest {

    @Mock
    DescontoService descontoService;

    @Mock
    EmailService emailService;

    @InjectMocks
    PedidoService pedidoService;

    @Test
    void deveAplicarDescontoAoFinalizarPedido() {
        // Arrange
        Pedido pedido = new Pedido(1L, 100.0);
        when(descontoService.calcularDesconto(pedido)).thenReturn(10.0);

        // Act
        pedidoService.finalizarPedido(pedido);

        // Assert
        assertEquals(90.0, pedido.getValorTotal());
        verify(emailService).enviarConfirmacao(pedido);
    }
}

Exemplo completo: Testando um Controller REST

Vamos ver um exemplo prático de como testar um controller REST em Spring Boot:

O Controller em produção

@RestController
@RequestMapping("/api/produtos")
public class ProdutoController {

    private final ProdutoService produtoService;

    public ProdutoController(ProdutoService produtoService) {
        this.produtoService = produtoService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<ProdutoDTO> buscarPorId(@PathVariable Long id) {
        return produtoService.buscarPorId(id)
                .map(produto -> ResponseEntity.ok(new ProdutoDTO(produto)))
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<ProdutoDTO> criar(@RequestBody @Valid ProdutoRequest request) {
        Produto produto = produtoService.criar(
            new Produto(request.getNome(), request.getPreco())
        );
        return ResponseEntity
            .created(URI.create("/api/produtos/" + produto.getId()))
            .body(new ProdutoDTO(produto));
    }
}

Teste unitário com MockMVC

Ham Vocke explica que ferramentas como MockMVC são importantes porque "Spring MVC's controller faz uso intensivo de anotações para declarar em quais caminhos eles estão escutando, quais verbos HTTP usar, quais parâmetros eles analisam do caminho da URL ou parâmetros de consulta e assim por diante. Simplesmente invocar um método do controller em seus testes unitários não testará todas essas coisas cruciais."

@ExtendWith(MockitoExtension.class)
class ProdutoControllerTest {

    private MockMvc mockMvc;

    @Mock
    private ProdutoService produtoService;

    @InjectMocks
    private ProdutoController produtoController;

    @BeforeEach
    void setup() {
        mockMvc = MockMvcBuilders
            .standaloneSetup(produtoController)
            .build();
    }

    @Test
    void deveRetornarProdutoQuandoExistir() throws Exception {
        // Arrange
        Produto produto = new Produto("Teclado Mecânico", 350.0);
        produto.setId(1L);

        when(produtoService.buscarPorId(1L))
            .thenReturn(Optional.of(produto));

        // Act & Assert
        mockMvc.perform(get("/api/produtos/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.nome").value("Teclado Mecânico"))
            .andExpect(jsonPath("$.preco").value(350.0));
    }

    @Test
    void deveRetornarNotFoundQuandoProdutoNaoExistir() throws Exception {
        // Arrange
        when(produtoService.buscarPorId(99L))
            .thenReturn(Optional.empty());

        // Act & Assert
        mockMvc.perform(get("/api/produtos/99"))
            .andExpect(status().isNotFound());
    }

    @Test
    void deveCriarNovoProduto() throws Exception {
        // Arrange
        Produto produtoParaSalvar = new Produto("Mouse", 89.9);
        Produto produtoSalvo = new Produto("Mouse", 89.9);
        produtoSalvo.setId(42L);

        when(produtoService.criar(any(Produto.class)))
            .thenReturn(produtoSalvo);

        // Act & Assert
        mockMvc.perform(post("/api/produtos")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"nome\":\"Mouse\",\"preco\":89.9}")
        )
            .andExpect(status().isCreated())
            .andExpect(header().string("Location", "/api/produtos/42"))
            .andExpect(jsonPath("$.nome").value("Mouse"))
            .andExpect(jsonPath("$.preco").value(89.9));
    }
}

Solitary vs. Sociable: Duas abordagens para testes unitários

Segundo Vocke, "alguns argumentam que todos os colaboradores da sua unidade sob teste devem ser substituídos por mocks ou stubs", enquanto "outros argumentam que apenas colaboradores que são lentos ou têm efeitos colaterais maiores deveriam ser substituídos por stubs ou mocks."

Este conceito foi criado por Jay Fields em seu livro "Working Effectively with Unit Tests", que cunhou os termos "testes unitários solitários" para testes que substituem todos os colaboradores, e "testes unitários sociáveis" para testes que permitem interações com colaboradores reais.

Ham Vocke confessa: "Eu me vejo usando ambas as abordagens o tempo todo. Se se torna estranho usar colaboradores reais, usarei mocks e stubs generosamente. Se eu sentir que envolver o colaborador real me dá mais confiança em um teste, apenas faço stub das partes mais externas do meu serviço."

Exemplo de teste solitário (com mocks)

@Test
void deveCalcularImpostoSobreVendaComMocks() {
    // Arrange
    BigDecimal valorBase = new BigDecimal("1000.00");

    // Mockando todas as dependências
    when(aliquotaService.buscarAliquota("SP"))
        .thenReturn(new BigDecimal("0.18"));

    when(descontoService.calcularDesconto(valorBase))
        .thenReturn(new BigDecimal("100.00"));

    // Act
    BigDecimal imposto = calculadoraImpostoService.calcular(valorBase, "SP");

    // Assert
    assertEquals(new BigDecimal("162.00"), imposto); // (1000 - 100) * 0.18
}

Exemplo de teste sociável (com colaboradores reais)

@Test
void deveCalcularImpostoSobreVendaComColaboradoresReais() {
    // Arrange
    BigDecimal valorBase = new BigDecimal("1000.00");

    // Usando implementação real do serviço de desconto
    DescontoService descontoServiceReal = new DescontoServiceImpl();

    // Ainda mockando o serviço de alíquota (externo)
    AliquotaService aliquotaMock = mock(AliquotaService.class);
    when(aliquotaMock.buscarAliquota("SP"))
        .thenReturn(new BigDecimal("0.18"));

    // Injetando uma mistura de dependências reais e mockadas
    CalculadoraImpostoService calculadora = 
        new CalculadoraImpostoServiceImpl(descontoServiceReal, aliquotaMock);

    // Act
    BigDecimal imposto = calculadora.calcular(valorBase, "SP");

    // Assert
    assertEquals(new BigDecimal("180.00"), imposto); // Considerando que o desconto real é 0
}

DRY vs. DAMP nos testes: Equilibrando clareza e repetição

Ham Vocke alerta: "Não tente ser excessivamente DRY (Don't Repeat Yourself). Duplicação é aceitável se melhorar a legibilidade."

Em testes, muitas vezes é melhor priorizar a clareza em vez da não-repetição. Um acrônimo útil para recordar é DAMP: Descriptive And Meaningful Phrases.

Exemplo questionável (muito DRY):

// Definição central, reusada em todos os testes
private Cliente clienteVip;
private Produto produtoPadrao;

@BeforeEach
void setup() {
    clienteVip = new Cliente("João", TipoCliente.VIP);
    produtoPadrao = new Produto("Item", 100.0);
}

@Test
void deveAplicarDescontoVipEmProduto() {
    assertEquals(90.0, calculadoraPreco.calcular(produtoPadrao, clienteVip));
}

@Test
void deveIncluirFreteGratisPara() {
    assertTrue(beneficioService.temFreteGratis(clienteVip, produtoPadrao));
}

Exemplo melhor (mais DAMP):

@Test
void deveAplicarDescontoVipEmProduto() {
    // Arrange - Dados específicos para este teste
    Cliente clienteVip = new Cliente("João", TipoCliente.VIP);
    Produto notebook = new Produto("Notebook", 2000.0);

    // Act
    double valorComDesconto = calculadoraPreco.calcular(notebook, clienteVip);

    // Assert - Expectativa clara
    assertEquals(1800.0, valorComDesconto, 
                "Cliente VIP deve receber 10% de desconto");
}

@Test
void deveIncluirFreteGratisPara() {
    // Arrange - Dados específicos para este teste
    Cliente clienteVip = new Cliente("Maria", TipoCliente.VIP);
    Produto smartTV = new Produto("Smart TV", 1500.0);

    // Act
    boolean temFreteGratis = beneficioService.temFreteGratis(clienteVip, smartTV);

    // Assert - Expectativa clara
    assertTrue(temFreteGratis, 
              "Cliente VIP deve ter frete grátis independente do produto");
}

Evitando armadilhas comuns

"Mas eu preciso testar este método privado!"

Ham Vocke alerta: "Se você já se encontrou em uma situação em que realmente precisa testar um método privado, você deve dar um passo atrás e se perguntar por quê." Ele continua: "Estou bastante certo de que isso é mais um problema de design do que um problema de escopo."

Quando você sente essa necessidade, geralmente há um problema de design da classe — ela provavelmente está fazendo muitas coisas e violando o princípio da responsabilidade única.

A solução mais elegante:

// Antes: Classe grande com método privado complexo
public class FaturamentoService {
    public BigDecimal calcular(Pedido pedido) {
        // lógica...
        return calcularImpostos(valorBase); // método privado complexo
    }

    private BigDecimal calcularImpostos(BigDecimal valor) {
        // lógica complexa de cálculo de impostos
    }
}

// Depois: Extrair para uma classe dedicada com interface pública
public class FaturamentoService {
    private final ImpostoCalculator impostoCalculator;

    public FaturamentoService(ImpostoCalculator impostoCalculator) {
        this.impostoCalculator = impostoCalculator;
    }

    public BigDecimal calcular(Pedido pedido) {
        // lógica...
        return impostoCalculator.calcular(valorBase); // Agora é público!
    }
}

public class ImpostoCalculator {
    public BigDecimal calcular(BigDecimal valor) {
        // mesma lógica complexa, agora testável
    }
}

"Preciso ter 100% de cobertura!"

Vocke argumenta contra testar código trivial: "Sim, você deve testar a interface pública. Mais importante, no entanto, você não testa código trivial. Não se preocupe, Kent Beck disse que tudo bem. Você não ganhará nada testando getters ou setters simples ou outras implementações triviais."

Focar em cobertura por si só pode levar a testes ruins que não adicionam valor. Busque qualidade em vez de quantidade.

Práticas avançadas e técnicas eficazes

À medida que você ganha experiência em testes unitários, algumas técnicas avançadas podem ajudar a tornar seus testes mais elegantes, legíveis e fáceis de manter. Vejamos três técnicas importantes que podem elevar significativamente a qualidade da sua suite de testes.

1. Dados de teste expressivos

O que é: Métodos de fábrica (factory methods) ou objetos builders que criam dados de teste com nomes semânticos, em vez de usar configurações inline de objetos diretamente nos testes.

Quando usar:

Quando os objetos de teste têm muitas propriedades que precisam ser configuradas
Quando você repete a mesma configuração de objetos em vários testes
Quando a configuração obscurece a intenção principal do teste

Benefícios:

Foco no "o quê" está sendo testado, não no "como" os objetos são criados
Leitura mais natural - o nome do método descreve o cenário
Encapsulamento de detalhes irrelevantes para a intenção do teste
Fácil reutilização entre testes similares

// Ruim: Dados aleatórios desconexos
@Test
void deveAprovarCreditoParaClienteBomPagador() {
    Cliente cliente = new Cliente("X123", 35);
    cliente.setScoreCredito(750);
    cliente.setRendaMensal(5000.0);

    boolean aprovado = creditoService.analisarCredito(cliente, 10000.0);

    assertTrue(aprovado);
}

// Melhor: Nome do método de fábrica expressivo
@Test
void deveAprovarCreditoParaClienteBomPagador() {
    Cliente clienteBomPagador = criarClienteComBomHistoricoCredito();

    boolean aprovado = creditoService.analisarCredito(clienteBomPagador, 10000.0);

    assertTrue(aprovado);
}

private Cliente criarClienteComBomHistoricoCredito() {
    Cliente cliente = new Cliente("Maria", 35);
    cliente.setScoreCredito(750);
    cliente.setRendaMensal(5000.0);
    return cliente;
}

Você também pode evoluir para padrões mais sofisticados como builders fluentes:

// Usando um builder expressivo
@Test
void deveAprovarCreditoParaClienteBomPagador() {
    Cliente clienteBomPagador = ClienteBuilder.padrao()
        .comBomHistoricoCredito()
        .comRendaAdequada()
        .build();

    boolean aprovado = creditoService.analisarCredito(clienteBomPagador, 10000.0);

    assertTrue(aprovado);
}

2. Assertion libraries expressivas

O que são: Bibliotecas que oferecem uma sintaxe mais fluente e legível para verificações, substituindo os métodos padrão do JUnit.

Quando usar:

Para verificações complexas ou múltiplas em um único objeto
Quando se deseja uma leitura mais próxima da linguagem natural
Para verificações de coleções, onde se quer verificar múltiplos aspectos

Bibliotecas populares:

AssertJ: fluente e orientada a objetos
Hamcrest: baseada em matchers
Truth (Google): alternativa simples e expressiva

Benefícios:

Testes mais legíveis, quase como frases em inglês
Mensagens de erro mais descritivas quando falham
Encadeamento de verificações reduz duplicação
Maior expressividade para casos complexos

// JUnit padrão - Funcionais mas menos expressivas
assertEquals(3, lista.size());
assertTrue(lista.contains("item1"));
assertTrue(cliente.isAtivo());

// AssertJ - Mais fluente e expressivo
assertThat(lista)
    .hasSize(3)
    .contains("item1")
    .doesNotContain("item99");

assertThat(cliente.isAtivo()).isTrue();

Quando um teste falha, a mensagem de erro com AssertJ é mais informativa:

Expected size:<3> but was:<2>
Expected to contain:<"item1"> but did not

3. Testes parametrizados para casos similares

O que são: Testes que executam o mesmo código com diferentes entradas e expectativas de saída, gerando automaticamente múltiplos casos de teste a partir de uma única definição.

Quando usar:

Para testar múltiplas variações de um mesmo caso (comportamento com diferentes entradas)
Para regras de negócio que têm muitos casos específicos (ex: cálculos tributários)
Quando a lógica é a mesma, mas os dados variam
Para evitar duplicação de código em testes semelhantes

Benefícios:

Redução drástica de código duplicado
Facilidade para adicionar novos casos de teste
Documentação clara de todos os casos suportados
Facilita identificar quais casos específicos falharam

@ParameterizedTest
@CsvSource({
    "SP, 0.18",
    "RJ, 0.20",
    "MG, 0.17",
    "RS, 0.17"
})
void deveCalcularImpostoCorretoPorEstado(String estado, BigDecimal aliquotaEsperada) {
    // Arrange
    Produto produto = new Produto("Genérico", 100.0);

    // Act
    BigDecimal aliquota = impostoService.obterAliquota(estado, produto);

    // Assert
    assertEquals(aliquotaEsperada, aliquota);
}

O JUnit 5 suporta múltiplas fontes de dados para testes parametrizados:

@ValueSource: para listas simples de valores (@ValueSource(ints = {1, 2, 3}))
@CsvSource: para pares ou tuplas de valores como mostrado acima
@EnumSource: para testar com valores de um enum
@MethodSource: para casos complexos onde os dados são gerados por um método
@ArgumentsSource: para implementações personalizadas de geradores de dados

Essas técnicas avançadas são particularmente úteis quando sua base de código cresce e você precisa manter um conjunto grande de testes. Elas ajudam a reduzir a duplicação, melhorar a legibilidade e facilitar a manutenção a longo prazo.

Integração Contínua: Executando testes unitários automaticamente

Os testes unitários devem ser executados:

Localmente antes de commit/push
Na CI em cada push para qualquer branch
Antes de merge para branches principais

Este feedback rápido é possível graças à velocidade dos testes unitários.

Lições finais

Ham Vocke resume bem: "Uma vez que você pegar o jeito de escrever testes unitários, você se tornará cada vez mais fluente em escrevê-los. Substitua colaboradores externos por stubs, configure alguns dados de entrada, chame seu assunto sob teste e verifique se o valor retornado é o que você esperava."

Testes unitários são um investimento que:

⏱️ Economiza tempo a longo prazo
🔒 Permite refatorações com segurança
📚 Documenta o comportamento esperado
💻 Melhora o design do código
🧠 Reduz a carga cognitiva ao desenvolver

Conclusão

Como resumido no artigo de referência: "O código de teste é tão importante quanto o código de produção. Dê a ele o mesmo nível de cuidado e atenção. 'Isso é apenas código de teste' não é uma desculpa válida para justificar código desleixado."

Ao dominar a arte dos testes unitários, você estabelece a base sólida para construir um sistema robusto e confiável, que pode evoluir com segurança ao longo do tempo.

No próximo passo da nossa maratona, abordaremos testes de integração - a camada intermediária da pirâmide de testes que verifica como seus componentes trabalham juntos.

Recursos recomendados

📕 "Working Effectively with Unit Tests" por Jay Fields
📗 "Test Driven Development: By Example" por Kent Beck
📘 "Clean Code" por Robert C. Martin (capítulo sobre testes)
🌐 Documentação oficial do JUnit 5
🌐 Documentação oficial do Mockito
🌐 Documentação oficial do AssertJ

Referências Bibliográficas

Vocke, Ham. (2018). "The Practical Test Pyramid". Martin Fowler. Disponível em: https://martinfowler.com/articles/practical-test-pyramid.html
Cohn, Mike. (2009). "Succeeding with Agile: Software Development Using Scrum". Addison-Wesley Professional.
Fields, Jay. (2014). "Working Effectively with Unit Tests". Leanpub.
Beck, Kent. (2002). "Test Driven Development: By Example". Addison-Wesley Professional.
Martin, Robert C. (2008). "Clean Code: A Handbook of Agile Software Craftsmanship". Prentice Hall.
Fowler, Martin. (2006). "Mocks Aren't Stubs". MartinFowler.com. Disponível em: https://martinfowler.com/articles/mocksArentStubs.html
Spring Framework Documentation. "Testing". Disponível em: https://docs.spring.io/spring-framework/docs/current/reference/html/testing.html
JUnit 5 User Guide. Disponível em: https://junit.org/junit5/docs/current/user-guide/
Mockito Reference Documentation. Disponível em: https://javadoc.io/doc/org.mockito/mockito-core/latest/org/mockito/Mockito.html
AssertJ Documentation. Disponível em: https://assertj.github.io/doc/

Maratona de Testes Automatizados — Step 0: Fundamentos, Importância e a Pirâmide de Testes

Diego de Sousa Brandão — Tue, 06 May 2025 02:55:38 +0000

Step 0: Fundamentos, Importância e a Pirâmide de Testes

Índice

Por que testamos software?
Entendendo a Pirâmide de Testes
O Anti-padrão: O Sorvete de Testes
Duplicação Inteligente vs. Duplicação Desnecessária
DRY vs. DAMP em Testes
Testes de Caixa Branca vs. Caixa Preta
Princípios Essenciais para Todos os Níveis
O que vem a seguir?
Referências Bibliográficas

Por que testamos software?

Testar software transcende a simples busca por defeitos — é fundamentalmente um ato de construir confiança. Testes automatizados proporcionam a liberdade de evoluir o código sem receio, realizar refatorações profundas, validar integrações complexas, e entregar continuamente com a segurança de um sistema verificado.

Como Ham Vocke observa no artigo "The Practical Test Pyramid":

"Automating your repetitive tests can be a big game changer in your life as a software developer. Automate these tests and you no longer have to mindlessly follow click protocols in order to check if your software still works correctly. Automate your tests and you can change your codebase without batting an eye."

Tradução:

"Automatizar seus testes repetitivos pode ser um grande divisor de águas na sua vida como desenvolvedor de software. Automatize esses testes e você não precisará mais seguir protocolos de cliques sem pensar para verificar se seu software ainda funciona corretamente. Automatize seus testes e você poderá mudar sua base de código sem piscar."

A automação de testes é transformadora precisamente porque liberta desenvolvedores de tarefas repetitivas e tediosas, convertendo-as em verificações automáticas:

Testes manuais → Repetitivos → Tediosos → Propensos a erros → Lentos
Testes automatizados → Consistentes → Confiáveis → Rápidos → Confortantes

O impacto disso vai além da qualidade do software; reflete diretamente na qualidade de vida do desenvolvedor e na dinâmica das equipes.

Entendendo a Pirâmide de Testes

A Pirâmide de Testes (Test Pyramid) foi introduzida por Mike Cohn em seu livro Succeeding with Agile. Trata-se de uma metáfora visual poderosa que orienta a construção de uma suíte de testes balanceada, rápida e sustentável a longo prazo.

A pirâmide nos comunica dois conceitos fundamentais:

Diferentes níveis de granularidade: Os testes são agrupados em categorias que variam de escopo, desde pequenos métodos isolados até o sistema completo integrado.
Distribuição ideal: Quanto mais subimos na pirâmide, menor deve ser a quantidade de testes, seguindo o princípio de "muitos testes rápidos e baratos na base, poucos testes caros e lentos no topo".

Como Ham Vocke explica:

"Write lots of small and fast unit tests. Write some more coarse-grained tests and very few high-level tests that test your application from end to end."

Tradução:

"Escreva muitos testes unitários pequenos e rápidos. Escreva alguns testes mais abrangentes e muito poucos testes de alto nível que testem sua aplicação de ponta a ponta."

A estrutura contemporânea da pirâmide consiste em:

Nível	Tipo de Teste	Características	Quantidade
Base	Testes Unitários	Rápidos, isolados, confiáveis	Muitos
Meio	Testes de Integração	Verificam comunicação entre componentes	Moderada
Topo	Testes E2E/UI	Simulam comportamento do usuário	Poucos

Esta distribuição não é acidental — reflete o equilíbrio econômico entre velocidade de feedback, cobertura de cenários e custo de manutenção.

Nota sobre a Evolução da Pirâmide de Testes

Nota: Esta seção complementa o entendimento sobre a Pirâmide de Testes, explicando sua evolução histórica.

É importante destacar que a Pirâmide de Testes que apresentamos neste artigo representa uma versão mais contemporânea e refinada do conceito original introduzido por Mike Cohn.

A Pirâmide Original de Cohn (2009) consistia em três camadas:

Base: Testes Unitários (Unit Tests)
Meio: Testes de Serviço (Service Tests)
Topo: Testes de Interface do Usuário (UI Tests)

O termo "Service Tests" usado por Cohn era um tanto ambíguo e causou confusão na comunidade de desenvolvimento. Ele se referia a testes que verificavam a funcionalidade sem passar pela interface do usuário, mas que podiam envolver múltiplos componentes ou módulos.

A Pirâmide Moderna que apresentamos evoluiu para oferecer maior clareza e se adaptar às práticas atuais de desenvolvimento:

Base: Testes Unitários (Unit Tests)
Meio: Testes de Integração (Integration Tests)
Topo: Testes E2E/UI (End-to-End/UI Tests)

Por que a mudança?

Esta evolução não foi apenas uma questão de terminologia, mas reflete mudanças fundamentais nas práticas de desenvolvimento:

Maior granularidade: A camada intermediária agora é geralmente subdividida para acomodar diferentes tipos de integrações (API, componentes, contratos).
Arquiteturas distribuídas: Com a popularização de microsserviços e sistemas distribuídos, o conceito de "Service Tests" se tornou insuficiente para capturar a complexidade das integrações modernas.
DevOps e CI/CD: A automação completa de pipelines de entrega contínua demandou uma categorização mais precisa dos testes para otimizar velocidade e eficiência.
Práticas ágeis maduras: A experiência acumulada nas últimas décadas permitiu refinar o modelo para melhor servir aos fluxos de trabalho modernos.

Martin Fowler e outros influentes profissionais da área contribuíram para esta evolução, resultando em uma pirâmide mais detalhada e adaptada às necessidades contemporâneas de desenvolvimento de software.

A essência da metáfora original de Cohn permanece intacta: muitos testes rápidos na base, poucos testes lentos no topo. O refinamento da pirâmide representa nossa compreensão mais sofisticada de como implementar este princípio em contextos diversos e complexos.

O Anti-padrão: O Sorvete de Testes

Enquanto a pirâmide aponta para a estabilidade e eficiência, seu anti-padrão é o "Sorvete de Testes" (Test Ice Cream Cone), termo cunhado por Alberto Savoia e popularizado por Martin Fowler.

No sorvete de testes, a distribuição é invertida:

A base (testes unitários) é pequena ou inexistente
O meio (integração) é moderado
O topo (UI/E2E) é excessivamente volumoso

Ham Vocke alerta:

"Watch out that you don't end up with a test ice-cream cone that will be a nightmare to maintain and takes way too long to run."

Tradução:

"Tenha cuidado para não acabar com um sorvete de testes que será um pesadelo para manter e demorará muito tempo para executar."

As consequências desta distorção são severas:

Feedback lento: O ciclo de desenvolvimento se torna arrastado
Diagnóstico difícil: Falhas são complexas de isolar e corrigir
Fragilidade: Pequenas mudanças causam falhas em cascata
Alto custo: A manutenção consome recursos desproporcionais

A regra prática é: quanto mais alto o teste na pirâmide, maior o custo de manutenção, tempo de execução e propensão a falhas intermitentes ("flaky tests").

Duplicação Inteligente vs. Duplicação Desnecessária

Um equívoco comum é assumir que qualquer forma de duplicação de cobertura de testes é inaceitável. Ham Vocke apresenta uma visão mais equilibrada sobre este tema:

"If a higher-level test gives you more confidence that your application works correctly, you should have it. Writing a unit test for a Controller class helps to test the logic within the Controller itself. Still, this won't tell you whether the REST endpoint this Controller provides actually responds to HTTP requests."

Tradução:

"Se um teste de nível superior lhe dá mais confiança de que sua aplicação funciona corretamente, você deve tê-lo. Escrever um teste unitário para uma classe Controller ajuda a testar a lógica dentro do Controller em si. Ainda assim, isso não dirá se o endpoint REST que este Controller fornece realmente responde a requisições HTTP."

Existem dois tipos de duplicação em testes:

Duplicação inteligente: Testa o mesmo comportamento, mas sob perspectivas diferentes e complementares:

Teste unitário: valida a lógica interna
Teste de integração: valida a comunicação entre componentes
Teste E2E: valida o fluxo completo sob a perspectiva do usuário

Duplicação desnecessária: Testa exatamente o mesmo aspecto em múltiplos níveis, sem valor agregado:

Repetir todos os casos de borda e condicionais em todos os níveis da pirâmide
Duplicar testes de validação em múltiplas camadas

Ham Vocke recomenda:

"If you have tested all conditions confidently on a lower-level test, there's no need to keep a higher-level test in your test suite."

Tradução:

"Se você testou todas as condições com confiança em um teste de nível inferior, não há necessidade de manter um teste de nível superior em sua suíte de testes."

Isto nos leva a duas regras práticas:

Se um teste de nível superior encontra um erro e não há teste de nível inferior falhando, você precisa escrever um teste de nível inferior
Priorize a implementação de testes nos níveis mais baixos da pirâmide, sempre que possível.

DRY vs. DAMP em Testes

DRY (Don't Repeat Yourself) é um princípio fundamental da engenharia de software, mas em testes, existe uma tensão com outro princípio: DAMP (Descriptive And Meaningful Phrases).

Ham Vocke observa:

"Don't try to be overly DRY. Duplication is okay, if it improves readability. Try to find a balance between DRY and DAMP code."

Tradução:

"Não tente ser excessivamente DRY. Duplicação é aceitável, se melhorar a legibilidade. Tente encontrar um equilíbrio entre código DRY e DAMP."

Esta visão reflete uma maturidade na abordagem dos testes automatizados:

Princípio	Foco	Benefício	Riscos se usado em excesso
DRY	Evitar redundância	Facilidade de manutenção	Testes interdependentes e frágeis
DAMP	Clareza e intenção	Testes auto-documentados	Admite certa repetição, desde que contribua para a clareza

Em testes, clareza é frequentemente mais valiosa que concisão extrema, pois testes são lidos não apenas por quem os escreveu, mas por desenvolvedores investigando falhas ou entendendo o comportamento esperado do sistema.

Testes de Caixa Branca vs. Caixa Preta

Para compreender melhor os diferentes níveis da pirâmide, é útil relacioná-los com dois paradigmas clássicos de teste:

Testes de Caixa Branca (White Box):

Utilizam conhecimento da estrutura interna do código
Testam caminhos de execução, cobertura de branches, lógica interna
Focam em "como" o sistema implementa comportamentos
Predominantes em: testes unitários e testes de integração

Testes de Caixa Preta (Black Box):

Tratam o sistema como uma "caixa fechada"
Testam apenas as interfaces públicas e o comportamento observável
Focam em "o que" o sistema faz, não em como faz
Predominantes em: testes E2E e testes de aceitação

Existe também uma abordagem híbrida:

Testes de Caixa Cinza (Grey Box):

Combinam conhecimento da estrutura interna com teste via interfaces externas
Usam conhecimento do design para testar de forma mais eficiente
Comuns em: testes de integração e testes de API

Nível da Pirâmide	Tipo	Abordagem Predominante
Base	Unitários	Caixa Branca
Meio	Integração/Contratos	Caixa Cinza
Topo	UI, E2E, Aceitação	Caixa Preta

Princípios Essenciais para Todos os Níveis

Independentemente do nível da pirâmide, alguns princípios fundamentais devem ser observados:

Teste comportamento, não implementação:
- Foque no "o quê", não no "como"
- Isso permite refatoração sem quebrar testes

"Test for observable behavior instead." - Ham Vocke

Tradução:

"Teste o comportamento observável, em vez disso." - Ham Vocke

Código de teste é código de produção:
- Aplique as mesmas práticas de qualidade
- Refatore e mantenha limpo

"Test code is as important as production code. Give it the same level of care and attention." - Ham Vocke

Tradução:

"O código de teste é tão importante quanto o código de produção. Dê a ele o mesmo nível de cuidado e atenção." - Ham Vocke

Estruture claramente:
- Use padrão "Arrange-Act-Assert" ou "Given-When-Then"
- Mantenha o teste focado em um único aspecto

"A good structure for all your tests is this one: Set up the test data, Call your method under test, Assert that the expected results are returned." - Ham Vocke

Tradução:

"Uma boa estrutura para todos os seus testes é esta: Configure os dados de teste, Chame seu método sob teste, Verifique que os resultados esperados são retornados." - Ham Vocke

Priorize feedback rápido:
- Coloque testes rápidos nos primeiros estágios do pipeline
- Testes lentos em estágios posteriores

"A good build pipeline tells you that you messed up as quick as possible." - Ham Vocke

Tradução:

"Um bom pipeline de build informa que você errou o mais rápido possível." - Ham Vocke

Evite duplicação desnecessária:
- Se já está bem testado em nível mais baixo, um teste mais alto deve focar em novos aspectos
- Seja implacável eliminando testes que não agregam valor

"I delete high-level tests that are already covered on a lower level (given they don't provide extra value)." - Ham Vocke

Tradução:

"Eu excluo testes de alto nível que já estão cobertos em um nível inferior (desde que não forneçam valor adicional)." - Ham Vocke

O que vem a seguir?

No Step 1 da nossa maratona, mergulharemos a fundo na base da pirâmide: os testes unitários. Exploraremos:

A definição precisa de uma "unidade" de teste
A diferença entre testes "sociáveis" e "solitários"
O uso eficaz de Mocks e Stubs
A estruturação ideal de testes unitários
Exemplos práticos em Java utilizando JUnit e Mockito

Prepare-se para construir uma base sólida que permitirá que seu código evolua com segurança e confiança!

Referências Bibliográficas

Vocke, Ham. (2018). "The Practical Test Pyramid". Martin Fowler. Disponível em: https://martinfowler.com/articles/practical-test-pyramid.html
Cohn, Mike. (2009). "Succeeding with Agile: Software Development Using Scrum". Addison-Wesley Professional.
Fowler, Martin. (2012). "Test Pyramid". MartinFowler.com. Disponível em: https://martinfowler.com/bliki/TestPyramid.html
Freeman, Steve; Pryce, Nat. (2009). "Growing Object-Oriented Software, Guided by Tests". Addison-Wesley Professional.
Meszaros, Gerard. (2007). "xUnit Test Patterns: Refactoring Test Code". Addison-Wesley Professional.
Khorikov, Vladimir. (2020). "Unit Testing: Principles, Practices, and Patterns". Manning Publications.
Osherove, Roy. (2013). "The Art of Unit Testing: With Examples in .NET". Manning Publications.
Beck, Kent. (2002). "Test Driven Development: By Example". Addison-Wesley Professional.
Fields, Jay. (2014). "Working Effectively with Unit Tests". Leanpub.
Savoia, Alberto. (2011). "The Way of Testivus". Disponível em: https://www.artima.com/weblogs/viewpost.jsp?thread=203994

DEV Community: Diego de Sousa Brandão

Série: Claude Code CLI: guia técnico — Parte 3: remoto, limites e boas práticas

📑 Índice da série

17. 📱 Trabalho remoto e entre dispositivos

Remote Control: controlar a sessão local de outro aparelho

Sessões na nuvem (claude.ai/code)

Outros dispositivos

18. ✅ O que só o CLI faz

19. ❌ O que o CLI não faz

20. 🤫 Recursos pouco conhecidos

21. 🏆 Fluxo de trabalho recomendado

22. ⚠️ Cuidados e limitações

Segurança

bypassPermissions e auto mode

Dev containers

IDEs

Dados

Custo

23. 📚 Fontes oficiais

Série: Claude Code CLI: guia técnico — Parte 2: extensões, MCP e automação

📑 Índice da série

9. 🪝 Hooks

Eventos mais usados

Exemplo: formatar após cada edição

Códigos de saída

Exemplo: bloquear rm -rf com if e decisão em JSON

Onde definir hooks

10. 👥 Subagents

Criar o seu

Como invocar

11. 🧩 Skills, comandos e plugins

Skills

Plugins

12. 🔌 MCP no terminal

Adicionar servidores

Escopos

.mcp.json (compartilhado com o time)

Gerenciar

Limites e nomes

13. ⏪ Checkpoints e gestão de contexto

Checkpoints

Gestão de contexto

14. 🤖 Modo não interativo (-p) e CI

Flags principais

Autenticação em CI

GitHub Actions

GitLab CI/CD

Agent SDK

15. 🔀 Sessões em paralelo

Git worktrees

/batch

Sessões em segundo plano

Agent teams (experimental)

16. ⏰ Automação agendada

/loop: repetição dentro da sessão

/schedule: rotinas na nuvem

Qual usar

⌨️ Série: Claude Code CLI: guia técnico — Parte 1: fundamentos e configuração

📑 Índice da série

1. 🧠 O que é o Claude Code CLI

2. 📦 Instalação e autenticação

Requisitos

Instalar

Verificar

Atualizações

Login

3. 🚪 Comandos de entrada

4. ⌨️ Atalhos de teclado e prefixos

Atalhos principais

Prefixos no início da linha

5. ⚡ Slash commands essenciais

6. 🔐 Modos de permissão

7. 📄 Memória: CLAUDE.md e auto memory

Onde fica o CLAUDE.md

Exemplo

8. ⚖️ Configuração: settings.json

Precedência, do mais forte para o mais fraco

Exemplo: liberar lint e testes, bloquear .env

Custo de tokens em LLMs: onde pesa e como evitar desperdício

Resumo executivo

`bypassPermissions` e auto mode

Exemplo: bloquear `rm -rf` com `if` e decisão em JSON

`.mcp.json` (compartilhado com o time)

14. 🤖 Modo não interativo (`-p`) e CI

`/batch`

`/loop`: repetição dentro da sessão

`/schedule`: rotinas na nuvem

Exemplo: liberar lint e testes, bloquear `.env`