Jamie-BitFlight/transcript-analysis

Análise de Transcrição

Analise transcrições de sessão em JSONL do Claude Code para detectar antipadrões, ineficiências e oportunidades de melhoria no fluxo de trabalho.

Localização dos Dados

Encontre as transcrições em ~/.claude/projects/ em diretórios específicos do projeto nomeados após o caminho do projeto (com hífens substituindo as barras).

Papel do DuckDB: Carregue a referência completa de campo/caminho de kaizen-analysis via get_transcript_jsonl_schema ou MCP resources/read kaizen://session-log/schema, então use kaizen-duckdb execute_query para executar qualquer SQL do DuckDB sobre esses arquivos (veja Padrões de Consulta DuckDB para exemplos e o fluxo de trabalho de consulta arbitrária). O histórico da sessão permanece em JSONL no disco. Regras de caminho para o MCP DuckDB (caminhos absolutos, sem ~ no SQL).

~/.claude/projects/{chave-do-projeto}/
├── {uuid}.jsonl              # Transcrições principais da sessão
├── agente-{id}.jsonl          # Transcrições de agente órfão
└── {uuid}/
    ├── subagentes/
    │   └── agente-{id}.jsonl  # Transcrições de subagente
    └── resultados-ferramenta/
        └── {id-uso-ferramenta}.txt # Saídas de tarefas assíncronas

Tipos de Registro JSONL

Cada linha JSONL é um objeto JSON discriminado pelo campo type.

Tipos de registro primários para análise:

• assistant — Turnos de resposta do LLM contendo chamadas de ferramenta e texto
• user — Entrada humana e resultados de ferramenta
• system — Eventos de metadados (stop_hook_summary, turn_duration, compact_boundary, api_error, local_command)
• progress — Execução de hook e streaming de subagente
• file-history-snapshot — Rastreamento de edição de arquivo
• summary — Título/resumo da sessão

Para detalhes completos do esquema, incluindo estruturas JSON para cada tipo de registro, veja Referência do Esquema JSONL.

Catálogo de Sinais

Cada dimensão de análise abaixo tem sua própria metodologia de extração.

1. Detecção de Uso Indevido de Ferramenta

Extraia de assistant.message.content[] onde name == "Bash". Analise input.command para padrões de operação de arquivo que devem usar ferramentas internas. Para consultas de extração SQL, veja Padrões de Consulta DuckDB.

Analise blocos tool_use para comandos Bash correspondentes a:

• grep → deve usar a ferramenta Grep
• find -name → deve usar a ferramenta Glob
• cat, head, tail → deve usar a ferramenta Read
• ls → deve usar Glob ou Bash(ls) com descrição
• sed, awk → deve usar a ferramenta Edit

Exclua usos legítimos em pipelines (git ... | grep, uv run ... | head).

2. Erros Repetidos

Extraia de resultados de ferramenta onde is_error: true. Classifique os tipos de erro:

• "Arquivo ainda não foi lido" — Antipadrão Editar-antes-Ler
• "String para substituir não encontrada" — Alvo de Edição desatualizado
• "Usuário negou uso da ferramenta" — Problema de permissão/confiança
• Falhas de hook pré-commit (código de saída 1)
• Binário ausente / comando não encontrado

3. Oportunidades de Ferramentas Ausentes

Identifique fluxos de trabalho manuais repetidos em várias etapas entre sessões por meio de análise de trigramas de sequência de ferramentas. Trigramas de alta frequência como Bash → Bash → Bash ou Read → Read → Read sugerem scripts ou habilidades ausentes.

4. Padrões de Delegação de Subagente

Extraia de blocos tool_use Task. Rastreie subagent_type, description, model. Sinalize quando general-purpose é usado onde existe um agente especializado.

5. Análise do Caminho Mais Curto

Compare tentativas bem-sucedidas versus malsucedidas do mesmo objetivo. Meça a contagem de chamadas de ferramenta entre a declaração do objetivo (turno do usuário) e o resultado bem-sucedido (turno final do assistente). Alta variância entre sessões para objetivos semelhantes indica etapas desperdiçadas.

6. Detecção de Pistas Falsas

Rastreie ramos de investigação que são abandonados. Sinal: uma sequência de chamadas Read/Grep/Bash em um tópico seguida por compact_boundary ou mudança de direção sem resolução. A frequência entre sessões dos mesmos caminhos abandonados revela pistas falsas sistemáticas.

7. Interrupções de Processo do Sistema

Extraia system.compact_boundary, system.api_error e eventos progress relacionados a hook. Mapeie sua posição relativa ao trabalho ativo para identificar quando os processos do sistema atrapalharam caminhos de execução corretos.

8. Hooks Ausentes

Identifique correções manuais que se repetem entre sessões. Quando a mesma correção aparece 3 ou mais vezes, é candidata a prevenção automatizada via hook PreToolUse (negar + redirecionar) ou hook SubagentStart (injetar contexto).

9. Consulta SQL com DuckDB

Use kaizen-analysis get_transcript_jsonl_schema ou recurso kaizen://session-log/schema para a referência completa de caminho, então kaizen-duckdb execute_query para qualquer SQL sobre JSONL (read_ndjson_auto com caminhos absolutos). Você não está limitado às consultas do livro de receitas.

Para o fluxo de trabalho de consulta arbitrária e exemplos, veja Padrões de Consulta DuckDB.

Metodologia de Mineração de Processos

Use as ferramentas do servidor MCP kaizen-analysis para análises que SQL não pode expressar:

• extract_tool_sequences — Converter JSONL → arrays ordenados de chamadas de ferramenta por sessão
• discover_process_model — Modelo de transição leve sobre sequências de chamadas de ferramenta
• check_conformance — Comparar sessões contra um modelo de processo de referência
• find_frequent_patterns — Mineração de padrões sequenciais PrefixSpan
• cluster_sessions — Agrupamento de rastreamento por similaridade comportamental

Fluxo de Trabalho de Análise

flowchart TD
    Start([Receber tarefa de análise]) --> Scope{Escopo definido?}
    Scope -->|--project flag| Project[Filtrar para transcrições do projeto]
    Scope -->|Sem flag| Default[Usar projeto atual]
    Project --> Discover[SQL — contar sessões, intervalo de datas, tipos de registro]
    Default --> Discover
    Discover --> Dimensions{Quais dimensões?}
    Dimensions -->|Todas| RunAll[Executar todas as dimensões]
    Dimensions -->|Especificadas| RunSelected[Executar dimensões selecionadas]
    RunAll --> Aggregate[Agregar descobertas]
    RunSelected --> Aggregate
    Aggregate --> Write[Escrever em .planning/kaizen/analysis-DATA.md]

Formato de Saída

Escreva as descobertas da análise em .planning/kaizen/ como markdown estruturado com:

• ID da sessão e data para cada descoberta
• Severidade (crítico / aviso / informativo)
• Evidência — caminhos e valores exatos dos campos JSON
• Frequência — quantas sessões exibem o padrão
• Tipo de recomendação — hook, patch de habilidade, correção de prompt do agente, atualização do CLAUDE.md