O Comando /insights do Claude Code: Auto-Análise de Sessões com IA

A maioria dos desenvolvedores que usa Claude Code não sabe como usa Claude Code. Sabe que gastou tokens. Sabe que terminou tarefas. Mas não sabe onde perde tempo, quais padrões repete sem perceber, ou quais recursos da ferramenta ignora por completo.

O comando /insights existe para resolver esse problema. É um comando nativo que analisa suas sessões anteriores e gera um relatório HTML interativo — não sobre quanto você gastou, mas sobre como você trabalha.

O Que Torna o /insights Diferente

Dashboards de uso medem tokens e chamadas de API. São métricas quantitativas. Úteis para controle de custo, inúteis para melhoria de processo.

O /insights faz algo diferente: usa o modelo Haiku para realizar análise qualitativa dos seus logs de sessão. Ele lê as transcrições, entende o contexto das suas interações, identifica padrões de comportamento e gera recomendações específicas.

A diferença é a mesma entre saber que você dirigiu 500 km e entender que você freia tarde demais nas curvas.

A Arquitetura: Seis Estágios de Processamento

O /insights não é um prompt único jogado contra um modelo. É um pipeline de seis estágios, cada um com uma função específica:

1. Filtragem

Antes de qualquer chamada ao LLM, o sistema descarta sessões que não contribuem para a análise. Sessões de sub-agentes (arquivos agent-*), sessões internas de extração de facetas, sessões com menos de duas mensagens e sessões com menos de um minuto de duração — tudo isso é removido. O que sobra são sessões reais de trabalho.

2. Sumarização

Transcrições acima de 30.000 caracteres são divididas em blocos de 25.000 e sumarizadas. A sumarização preserva o que importa: o que o usuário pediu, o que o Claude fez, onde houve fricção e qual foi o resultado. Nomes de arquivo, mensagens de erro e feedback explícito do usuário são mantidos.

3. Extração de Facetas

Este é o estágio central. Para cada sessão, o Haiku extrai um JSON estruturado com avaliações qualitativas. O schema inclui 13 categorias de objetivo (debug, feature, bug fix, refactor, config, deploy, entre outras), 12 tipos de fricção (pedido mal interpretado, abordagem errada, código com bug, mudanças excessivas) e sinais de satisfação do usuário — de “frustrated” a “happy”.

O resultado é um perfil detalhado de cada sessão: qual era o objetivo real, se foi atingido, onde houve atrito e como o usuário reagiu.

4. Agregação

Sete prompts especializados processam os dados compilados de todas as sessões. Cada prompt tem um foco: áreas de projeto, estilo de interação, o que funciona, pontos de fricção, sugestões de melhoria, recursos para experimentar e workflows para o futuro. Cada prompt opera com até 8.192 tokens de saída.

5. Sumário Executivo

A chamada final sintetiza tudo em quatro dimensões práticas: o que está funcionando, o que está atrapalhando (separado entre falhas do Claude e fricção do usuário), vitórias rápidas e workflows ambiciosos. O tom é de coaching, não de julgamento.

6. Renderização

O resultado é compilado em um relatório HTML interativo salvo em ~/.claude/usage-data/report.html. Tudo local, tudo privado.

O Detalhe Que Importa: Cache de Facetas

Um aspecto de engenharia que merece destaque: as facetas extraídas são salvas em ~/.claude/usage-data/facets/. Execuções subsequentes do /insights analisam apenas sessões novas. Isso significa que o custo computacional não cresce linearmente com o número total de sessões — apenas com as sessões adicionadas desde a última execução.

São no máximo 50 sessões novas por execução. O modelo usado é o Haiku, que é rápido e custo-eficiente. Na prática, rodar /insights mensalmente é viável para qualquer desenvolvedor.

O Ciclo de Melhoria Contínua

O valor real do /insights não está no relatório em si. Está no ciclo que ele viabiliza:

Use o Claude Code normalmente. Não filtre seu comportamento. Trabalhe como sempre trabalha.
Execute /insights periodicamente. A cada 30-50 sessões ou mensalmente.
Atualize o CLAUDE.md. O relatório identifica instruções que você repete em múltiplas sessões. Se você está dizendo a mesma coisa ao Claude mais de uma vez, isso deveria ser uma regra permanente no CLAUDE.md.
Experimente recursos sugeridos. MCP servers, hooks, skills, headless mode — o relatório recomenda recursos específicos com base nos seus padrões de uso.

Esse ciclo transforma o /insights de uma ferramenta de diagnóstico em um mecanismo de melhoria contínua. A cada iteração, o CLAUDE.md fica mais preciso, as fricções diminuem e o desenvolvedor descobre capacidades que não sabia que existiam.

Perspectiva Crítica: Limites e Considerações

Antes de tratar o /insights como solução definitiva, vale apontar limitações reais.

O modelo analista é o Haiku. A escolha faz sentido por custo e velocidade, mas Haiku tem capacidade de raciocínio inferior aos modelos maiores. Facetas extraídas por Haiku podem perder nuances que Sonnet ou Opus capturariam. Em sessões complexas com múltiplos objetivos interconectados, a classificação pode ser simplista.

50 sessões por execução é um limite arbitrário. Para desenvolvedores que acumulam centenas de sessões entre execuções, isso significa que várias rodadas são necessárias para uma análise completa. Não é um problema técnico grave, mas é uma fricção desnecessária.

A análise depende da qualidade dos logs. Sessões onde o desenvolvedor não dá feedback explícito (“obrigado”, “isso não está certo”, “perfeito”) produzem facetas menos ricas. O sistema rastreia sinais de satisfação, mas precisa desses sinais para funcionar bem.

O relatório não se integra ao workflow. É um HTML estático. Não há integração com CI/CD, não há alertas automáticos, não há tracking de progresso entre execuções. Para quem trabalha com equipes, a falta de agregação entre desenvolvedores é uma limitação significativa.

O Ecossistema Maior

O /insights não existe isolado. Faz parte de um ecossistema crescente de ferramentas de autoanálise:

/reflect faz reflexão estruturada por sessão individual — técnicas usadas, o que funcionou, lições aprendidas. É o complemento micro ao macro do /insights.

claude-reflect (open source, por BayramAnnakov) vai além: captura correções automaticamente via hooks e transforma padrões repetitivos em memória permanente. É a automação do ciclo que o /insights sugere manualmente.

A combinação dos três cria camadas complementares: /insights para padrões macro entre sessões, /reflect para aprendizado por sessão, e claude-reflect para captura contínua em tempo real.

Implicações Práticas

Para desenvolvedores individuais, a recomendação é direta: rode /insights uma vez por mês, leia o relatório com atenção e atualize seu CLAUDE.md. O investimento de tempo é mínimo e o retorno é imediato — menos repetição, menos fricção, descoberta de recursos.

Para líderes técnicos, a questão é mais interessante. O /insights oferece uma janela para entender como suas equipes interagem com ferramentas de IA. Que tipos de tarefa geram mais fricção? Quais recursos são subutilizados? Onde o treinamento teria mais impacto? Hoje essas respostas exigem análise manual dos relatórios individuais, mas o caminho está desenhado.

Para a indústria de ferramentas de IA, o /insights estabelece um precedente importante: ferramentas de desenvolvimento assistido por IA precisam de meta-análise. Não basta entregar código. É necessário ajudar o desenvolvedor a entender e melhorar sua relação com a ferramenta.

A análise qualitativa de sessões via LLM não é um luxo. É infraestrutura básica para qualquer sistema que pretende melhorar com o uso.

A análise técnica deste artigo é baseada no deep dive de Rob Zolkos (zolkos.com, fevereiro de 2026) e na documentação oficial da Anthropic.

Para discutir como sua equipe pode estruturar workflows de melhoria contínua com ferramentas de IA: contato@victorino.com.br | www.victorino.com.br