🔬 Análise de falhas — 5 categorias
Para cada cenário FAIL, classifica causa-raiz. Causa errada = correção errada. "Vou melhorar o prompt" não resolve falha de RAG.
1. RAG não recuperou
Resposta correta existia na base mas não foi retornada. Sintoma: agente diz "não sei". Fix: ajustar chunking, query, top-K.
2. Prompt ambíguo
Instrução do system prompt permite interpretação dupla. Fix: esclarecer redação, adicionar exemplo.
3. Few-shot conflitante
Exemplo no prompt contradiz a regra desejada. Fix: remove exemplo problemático, adiciona contra-exemplo.
4. Tool não chamada
Agente deveria chamar buscar_produto mas respondeu de memória. Fix: reforçar instrução de "sempre chame tool".
5. Alucinação
Agente inventou info que não está na base. Fix: grounding mais forte ("responda apenas com base nos documentos").
📊 Planilha de causa-raiz
Coluna `causa_raiz` na bateria com 1 das 5 categorias. Permite priorizar: se 70% das falhas são RAG, foca em melhorar RAG antes de prompt.
✏️ Ajuste de prompt cirúrgico
Mudanças pequenas e direcionadas. Adicionar 1 regra. Esclarecer 1 instrução. Adicionar 1 few-shot. Não reescrever bloco inteiro.
✓ Ajuste cirúrgico
- • "Adicionar RT-19 sobre frete fora de zona"
- • "Esclarecer instrução de horário noturno"
- • "Adicionar 1 few-shot de devolução"
- • Roda bateria entre cada mudança
✗ Reescrita ampla
- • "Vou reescrever todo bloco de regras"
- • "Mudo todo o tom do agente"
- • "Refaço os 10 few-shots"
- • Quebra cenários que estavam ok
📊 1 mudança por iteração
Ajusta 1 coisa, roda bateria, observa impacto. Permite isolar causa do efeito. Múltiplas mudanças simultâneas mascaram qual delas fez diferença.
📚 Tunagem do RAG — chunking + re-rank
Se RAG recupera coisa errada: ajusta chunk size, metadata, query expansion, re-rank. RAG ruim = alucinação #1 em PME.
📐 Chunk size
300-500 tokens normalmente. Documento muito técnico: 200. Política/FAQ: 500-700. Overlap 50 tokens.
🏷️ Metadata filters
Adiciona categoria, data, fonte nos chunks. Filtra na query: "buscar onde categoria='preços'". Reduz ruído.
🔍 Query expansion
Antes de buscar, expande query do usuário: "preço cerveja" → "preço cerveja Heineken caixa unidade desconto". Mais matches.
🎯 Re-rank com Cohere/Voyage
Top-K=10 busca semântica → re-rank → top-3 mais relevantes. Precisão sobe 15-30%.
📊 Ordem de ajuste de RAG
1º chunking · 2º metadata · 3º query · 4º re-rank. Cada um resolve falhas diferentes. Começa pelo mais barato.
🔧 Adição de tool ou guardrail
Algumas falhas exigem tool nova (ex: calcular_desconto) ou guardrail (ex: bloquear desconto > 20%). Reconhecer quando ajustar prompt não basta.
🛠️ Tool nova
Quando agente precisa fazer cálculo determinístico ou consultar dado em tempo real.
- • Cálculo de preço com desconto
- • Verificação de estoque atual
- • Validação de CNPJ
- • Geração de PIX
🚧 Guardrail no n8n
Validação determinística antes de enviar resposta. Bloqueia comportamento perigoso.
- • Desconto > 20% bloqueia
- • Pedido > R$ 5k escala
- • Palavra-chave de reclamação escala
- • Resposta vazia → fallback
⚠️ Forçar prompt a fazer cálculo
"Calcule 15% de R$ 1.247,80" no prompt = receita pra bug. LLM erra cálculo às vezes. Tool resolve melhor — código Python ou function call.
⏱️ Quando parar de iterar — diminishing returns
Quando bateria estabilizou no critério (90%/70%/100%) e os últimos 2 ciclos só geram ganho marginal, para. Deploy > perfeição.
| Iteração | Happy pass | Exceção pass | Adversarial | Decisão |
|---|---|---|---|---|
| v1.0 | 22/30 (73%) | 7/15 (47%) | 3/5 | Iterar |
| v1.1 | 26/30 (87%) | 10/15 (67%) | 5/5 | Iterar |
| v1.2 | 28/30 (93%) | 12/15 (80%) | 5/5 | Critério! |
| v1.3 | 29/30 (97%) | 13/15 (87%) | 5/5 | Parar — vai pra homologação |
💡 Otimização eterna é fuga de deploy
Cliente aprende muito mais com agente real em produção que com 6ª iteração polida. Aos 2 ciclos com ganho <2%, vai pra homologação. Resto é tunado em manutenção.
📔 Changelog de iterações
Para cada iteração: o que mudou, por que, resultado na bateria. Vira documentação para cliente e próximo projeto.
📋 Exemplo de changelog
**Adicionado:**
- RT-19: regra de frete fora de zona
- Few-shot pra cenário de devolução parcial
- Tool calcular_desconto_volume
**Ajustado:**
- Esclarecida instrução de horário noturno
**Bateria:**
- Happy: 28/30 → 29/30
- Exceção: 12/15 → 13/15
- Adversarial: 5/5 → 5/5
📁 Arquivado por versão
Cada V tem doc próprio: changelog-v1.0.md, v1.1.md... Permite voltar a versão anterior.
🤝 Entregue ao cliente
Cliente recebe changelog. Vê o trabalho feito. Justifica investimento.
🧠 Aprendizado pra próximo projeto
Padrões nos changelogs revelam o que costuma falhar. Próximo cliente já começa melhor.
🔁 Resumo do módulo
Próximo módulo:
4.5 — Homologação com cliente · ambiente isolado · sessão presencial · 5-10 micro-vídeos · termo assinado.