Workflow: Debug em Produção

Playbook para investigar problemas em agentes que estão em produção. Use quando algo está dando errado e o Alex pediu pra investigar.

Quando usar

Use quando o Alex disser:

“O agente do {cliente} está dando problema”
“Investiga esse trace aqui”
“Por que a conversão caiu?”
/investigar-trace TRACE_ID

Princípio fundamental

Nunca mexa em produção sem entender o problema. Sempre investigue antes de aplicar fix. O custo de uma mudança errada em prod é muito maior que 30 minutos de investigação.

Passo 1: Coletar contexto inicial

Pergunte ao Alex (uma só pergunta por vez se faltar info):

Qual cliente / tenant_id?
Qual o sintoma observado? (custo alto, erro, qualidade ruim, latência, etc)
Quando começou? (importante para correlacionar com deploys)
Tem trace ID específico? (acelera muito a investigação)

Passo 2: Verificar saúde básica

Comandos rápidos para descartar problema infraestrutural:

# Status do agente
curl https://{tipo}.triadeflow.com/health/{tenant_id}

# Logs recentes do container
ssh hetzner "docker logs --tail 200 agent-{tipo}-{tenant_id}"

# Filas BullMQ — pendências?
ssh hetzner "docker exec redis redis-cli LLEN bull:agent-{tipo}:waiting"

# Qdrant alcançável?
curl https://qdrant.triadeflow.com/collections/{tenant_id}

# Langfuse alcançável?
curl https://langfuse.triadeflow.com/api/public/health

Se algo aqui está caído, é problema de infra — segue para .claude/workflows/incident-infra.md.

Passo 3: Análise de traces no Langfuse

Se há trace ID específico

Acesse: https://langfuse.triadeflow.com/project/{project}/traces/{trace_id}

Capture do trace:

Input completo (mensagem do usuário, histórico)
Output gerado
Tools chamadas e seus resultados
Tokens consumidos (input + output + cache)
Latência por step
Score do LLM-as-judge (se houver)

Se não há trace específico

Filtre traces problemáticos no Langfuse:

filter:
  tenant_id = "{tenant_id}"
  agent_type = "{tipo}"
  created_at > "{data inicio do problema}"
  score < 0.7  # se quer focar em qualidade ruim
  custo_usd > 0.10  # se quer focar em custo alto

Pegue 10-20 traces representativos. Não precisa olhar todos — padrões aparecem rápido.

Passo 4: Correlacionar com mudanças recentes

# Últimos commits do agente
cd ~/triadeflow/agent-{tipo}/
git log --since="{data início do problema}" --oneline -20

# Histórico de mudanças do tenant específico
git log --since="{data}" -- tenants/{tenant_id}/

Se há deploy próximo ao início do problema, forte suspeito. Considere rollback antes de investigação profunda — restaura serviço, depois investiga calmamente.

Passo 5: Identificar categoria do problema

Use a matriz de .claude/reference/decisoes.md ou o framework de decisão:

Problema de qualidade

Hallucination → RAG raso
Tom errado → prompt mal calibrado
Não conclui tarefa → falta tool ou instrução fraca
Erra raciocínio → modelo subdimensionado

Problema de custo

Tokens elevados → contexto grande, RAG inflado
Modelo caro pra tarefa simples → fazer routing
System prompt repetido → ativar prompt caching

Problema de latência

LLM lento → considerar Haiku para sub-tarefas
Tools em série → paralelizar
Integração externa lenta → cache + circuit breaker

Problema de fluxo

Loop infinito → memory broken
Pula etapas → flow nodes mal encadeados
Não passa para humano → triggers de handoff fracos

Passo 6: Hipótese e validação

Forme 2-3 hipóteses baseadas no Passo 5. Não disparate uma só.

Exemplo:

HIPÓTESES:
1. RAG voltando chunks irrelevantes — top_k alto trazendo ruído (60%)
2. System prompt v3 deploy 28/04 piorou tom (30%)
3. Memory summarizer cortando contexto importante (10%)

VALIDAÇÃO:
- Hip 1: rodar test_rag.py com 5 queries comuns, ver se chunks são relevantes
- Hip 2: comparar 10 traces antes vs depois do deploy 28/04
- Hip 3: ver se há padrão de loop ou repetição em traces

Comece pela hipótese mais provável.

Passo 7: Aplicar fix

Fix mínimo viável

A primeira tentativa de correção deve ser a menor mudança possível que tem chance de resolver. Não refatore tudo de uma vez.

Tipos de fix por categoria

Problema	Fix mínimo
Hallucination	Adicionar conteúdo ao RAG do tenant
Tom errado	Ajustar 2-3 linhas no prompt
Loop	Verificar memory e adicionar regra anti-loop
Custo alto	Reduzir top_k do RAG primeiro
Latência	Streaming + paralelização de tools
Fluxo errado	Revisar conditional_edges no LangGraph

Sempre testar antes de promover

# Roda eval no dataset golden + casos novos do problema
python scripts/run_eval.py \
  --tenant {tenant_id} \
  --extra-cases {casos do problema}

# Compara resultado antes vs depois
python scripts/compare_eval.py \
  --baseline {commit_anterior} \
  --candidate {commit_atual}

Passo 8: Deploy do fix

Se eval passou, deploy. Em horário de baixo movimento sempre.

make deploy ENV=prod TENANT={tenant_id}

Monitore os primeiros 30 minutos pós-deploy:

Taxa de erro
Latência
Custo
Score LLM-as-judge

Se algo regredir, rollback imediato.

Passo 9: Documentar a investigação

Toda investigação vira aprendizado documentado. Adicione ao .claude/reference/incidentes.md:

## YYYY-MM-DD — {Cliente} — {Sintoma resumido}

**Sintoma**: {descrição}
**Tenant**: {tenant_id}
**Agente**: {tipo}
**Início**: {data/hora}
**Resolução**: {data/hora}
**Tempo total**: {duração}

**Causa raiz**: {explicação técnica}

**Fix aplicado**:
- {arquivo alterado 1}: {o que mudou}
- {arquivo alterado 2}: {o que mudou}

**Lição aprendida**: {generalizar pra evitar repetir}

**Prevenção**: {teste, alerta ou processo a adicionar}

Passo 10: Atualizar prevenção

Se a causa raiz era genérica (não específica desse tenant):

Adicione caso ao dataset eval de todos os tenants daquele tipo
Atualize a matriz em .claude/reference/decisoes.md
Considere alerta proativo no painel de operação para detectar antes
Documente em conventions.md se for algo a evitar no código

Saída para o Alex

✓ Investigação concluída — {Cliente}

Sintoma: {resumo}
Causa raiz: {explicação curta}
Tempo de investigação: {duração}

Fix aplicado:
- {fix1}
- {fix2}

Status atual:
- Latência p95: {valor antes} → {valor depois}
- Custo/conv: {valor antes} → {valor depois}
- Erro rate: {valor antes} → {valor depois}

Documentação:
- Incidente registrado em .claude/reference/incidentes.md
- {se aplicável} Prevenção adicionada em {arquivo}

Sugestões adicionais (opcional):
1. {sugestão}
2. {sugestão}

Erros comuns a evitar

Tentar consertar sem entender — sempre forme hipótese antes de mexer
Mudar 5 coisas ao mesmo tempo — fix mínimo, mede, próximo
Pular o eval — fix sem teste é como apagar incêndio com gasolina
Esquecer de documentar — incidente sem documentação é fadado a se repetir
Não comunicar o cliente se ele percebeu o problema — sempre dê retorno

Versão: 1.0 Relacionado: .claude/workflows/otimizar-custo.md, .claude/reference/incidentes.md