Auditoria de Sessão agenttrace

O que Auditoria de Sessão agenttrace faz?

Visão Geral

Use esta skill para inspecionar sessões locais de agentes de codificação de IA com agenttrace. Ela foca no processo por trás de uma execução: picos de tokens e custo, falhas de ferramentas, loops de repetição, lacunas de latência, anomalias, pontuações de saúde e diferenças entre sessões.

O agenttrace é local-first e lê logs de sessão de ferramentas como Claude Code, Codex CLI, Gemini CLI, Aider, exportações do Cursor, OpenCode, Qwen Code, Kimi e traces JSON ou JSONL genéricos.

Quando Usar Esta Skill

• Use quando um usuário perguntar por que uma execução de codificação de IA foi lenta, cara, superficial ou não confiável.
• Use ao revisar logs locais de agente antes de repetir uma tarefa que falhou ou é suspeita.
• Use ao construir um portão de saúde leve de CI para sessões de codificação assistidas por IA.
• Use ao comparar duas tentativas e procurar por caminhos de ferramentas alterados, repetições ou padrões de custo.

Como Funciona

Passo 1: Descobrir Sessões Disponíveis

Prefira um binário agenttrace instalado quando disponível no PATH. Se o repositório atual for luoyuctl/agenttrace, use go run ./cmd/agenttrace em vez disso.

agenttrace --doctor
agenttrace --overview

Se nenhuma sessão for detectada, reporte os diretórios verificados por --doctor e pergunte pelo arquivo de sessão exportado ou diretório de logs.

Passo 2: Produzir uma Auditoria Legível para Humanos

Use Markdown quando o usuário quiser um relatório conciso que possa inspecionar ou compartilhar.

agenttrace --overview -f markdown -o agenttrace-overview.md

No relatório, comece com as sessões de maior risco e explique por que elas importam: anomalias críticas, falhas repetidas de ferramentas, desperdício de tokens ou custo, longas lacunas de latência, pontuações de saúde baixas e sessões suspeitamente superficiais.

Passo 3: Inspecionar uma Sessão ou Diretório

Use a sessão mais recente para uma verificação rápida, ou passe um caminho de exportação explícito quando o usuário fornecer um.

agenttrace --latest
agenttrace --latest -f json
agenttrace caminho/para/sessao-ou-exportacao.json
agenttrace --overview -d caminho/para/diretorio-de-sessao

Passo 4: Comparar Tentativas Quando a Semântica Importa

Métricas de tokens e latência podem parecer saudáveis mesmo quando um agente toma com confiança o caminho de implementação errado. Quando o risco é desvio semântico, emparelhe a auditoria de trace com um diff contra uma tentativa anterior ou conhecida como boa.

Procure por:

• arquivos alterados ou comandos que divergem da tarefa pretendida
• testes ausentes ou etapas de verificação em comparação com a tentativa de referência
• edições repetidas ao redor dos mesmos arquivos sem um motivo claro
• custo menor que veio de pular exploração necessária

Passo 5: Adicionar Portões de Automação

Para CI ou fluxos de trabalho de equipe repetíveis, use saída JSON ou limites de saúde.

agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15

Ajuste os limites para o projeto. Um portão rigoroso é útil para fluxos de trabalho críticos; um comando apenas de relatório é melhor enquanto a equipe está aprendendo sua linha de base.

Exemplos

Revisão Local Rápida

agenttrace --overview
agenttrace --latest

Use isto após uma longa execução de agente de codificação para decidir se o próximo prompt deve dividir a tarefa, evitar um caminho de ferramenta com falhas, adicionar testes ausentes ou redefinir contexto.

Verificação de Saúde de CI

agenttrace --overview --fail-under-health 80 --fail-on-critical

Use isto quando os logs de sessão do agente estiverem disponíveis no CI e a equipe quiser uma proteção simples contra anomalias críticas ou execuções não saudáveis.

Melhores Práticas

• Comece com --doctor quando a descoberta de sessão for incerta.
• Reporte campos ausentes claramente; não invente dados de custo, modelo, latência ou saúde.
• Trate prompts, código e conteúdos de sessão como dados locais privados.
• Prefira saída JSON para automação e saída Markdown para revisão humana.
• Use métricas de trace para falhas de processo e revisão de diff/referência para desvio semântico.

Limitações

• O agenttrace só pode analisar logs que estão presentes localmente ou fornecidos como exportações.
• Alguns agentes não expõem campos suficientes para inferir custo, modelo, uso de cache ou latência.
• Métricas de trace saudáveis não provam que o código final está correto; ainda execute testes e revise diffs.
• Portões de CI devem começar como consultivos até a equipe entender o comportamento normal da linha de base.

Notas de Segurança e Proteção

• Não envie logs de sessão privados para serviços externos a menos que o usuário aprove explicitamente.
• Não sobrescreva relatórios do usuário a menos que ele tenha solicitado exatamente aquele caminho de saída.
• Evite imprimir segredos encontrados em prompts, saída de ferramentas, variáveis de ambiente ou logs.

Armadilhas Comuns

• Problema: Nenhuma sessão é encontrada. Solução: Execute agenttrace --doctor, então aponte o agenttrace para o arquivo exportado ou diretório de logs.

• Problema: Uma execução parece barata e rápida, mas produziu a refatoração errada. Solução: Compare a sessão com uma tentativa anterior ou diff conhecido como bom; métricas de custo sozinhas perderão o desvio semântico.

• Problema: CI falha com muita frequência após adicionar um portão de saúde. Solução: Comece com relatório JSON ou Markdown, inspecione as linhas de base normais, então aperte os limites gradualmente.

Skills Relacionadas

• @langfuse - Use para rastreamento e avaliação de aplicações LLM em produção.
• @observability-engineer - Use para monitoramento de serviço mais amplo, SLOs e fluxos de trabalho de incidentes.