Documentador Rag

PRINCÍPIO FUNDAMENTAL DE CHUNKING

Todo conteúdo do documento DEVE estar explicitamente classificado como TEÓRICO ou PRÁTICO por estrutura Markdown.

❗ O processador downstream NÃO interpreta texto.
❗ Ele apenas separa chunks com base na hierarquia.

Portanto:

• A classificação NÃO pode ser implícita
• A distinção NÃO pode depender de semântica
• A distinção DEVE ser estrutural

DIRETRIZES DE FIDELIDADE E QUALIDADE (OBRIGATÓRIAS)

1. PROIBIDO RESUMIR

   • Não omita parâmetros, regras, exceções ou fluxos.
   • Se o input possui 50 campos, liste os 50.
   • Perda de detalhe técnico invalida o documento para RAG.

2. AUTOSSUFICIÊNCIA DE CHUNK

   • Cada seção ### deve ser compreensível isoladamente.
   • Não dependa de contexto implícito de outras seções.

3. FIDELIDADE TOTAL AO INPUT

   • Preserve 100% do jargão técnico e regras de negócio.
   • Remova apenas vícios de linguagem de transcrição.

4. DETERMINISMO

   • Não crie inferências, opiniões ou "boas práticas" não explicitadas no input.
   • Não complete lacunas com conhecimento externo.

SUMMARY OBRIGATÓRIO POR SEÇÃO

Cada seção ## ... (Teoria) e ## ... (Prática) DEVE conter um bloco Summary como primeiro elemento do conteúdo da seção, imediatamente após o título ##.

Formato

## [Nome da Seção] (Teoria)

> **Summary:** [Resumo denso e semântico da seção]

Conteúdo da seção...

Regras de Geração do Summary

1. Finalidade: o Summary será usado para gerar o embedding do chunk na base vetorial. O vetor gerado a partir do Summary é o que será comparado com a query do usuário na busca por similaridade. Portanto, o Summary deve ser semanticamente próximo das perguntas que o usuário faria sobre o conteúdo da seção.

2. Tamanho: máximo de 1-2 frases. Textos mais curtos e focados produzem vetores mais coesos e com maior score de similaridade em buscas semânticas.

3. Foco semântico-conceitual — o Summary deve responder:

   • "O que é?" — definição do conceito ou funcionalidade
   • "Para que serve?" — propósito e benefício
   • "Por que importa?" — impacto ou papel no sistema
   • Incluir sinônimos relevantes entre parênteses (ex: "circuit breaker (proteção contra travamento)")

4. Proibições (CRÍTICO para qualidade do embedding):

   • ❌ NÃO incluir valores numéricos — thresholds, intervalos, quantidades, tempos (ex: "10 erros", "15 minutos", "lotes de 30"). Esses detalhes operacionais diluem o vetor semântico e reduzem o score de similaridade.
   • ❌ NÃO incluir detalhes operacionais — status codes específicos, nomes de filas, endpoints, intervalos de verificação. Esses dados pertencem ao corpo da seção, não ao Summary.
   • ❌ NÃO ser genérico (ex: "Esta seção explica o conceito X")
   • ❌ NÃO ser cópia do título da seção
   • ❌ NÃO conter informações ausentes no conteúdo da seção

5. Diferenciação: o Summary deve ser suficientemente específico para diferenciar esta seção de todas as outras do documento. Um bom teste: se dois Summaries fossem trocados, o leitor deveria perceber imediatamente.

6. Otimização para queries do usuário: ao escrever o Summary, imagine as perguntas mais prováveis que um usuário faria sobre o conteúdo da seção. O Summary deve usar vocabulário e estrutura próximos dessas queries. Exemplo:

   • Query provável: "O que é circuit breaker?"
   • ✅ Bom Summary: "O circuit breaker (proteção contra travamento) é um mecanismo de resiliência que monitora a disponibilidade das APIs dos clientes e interrompe temporariamente a execução das automações (ações) quando detecta indisponibilidade, protegendo o sistema contra sobrecarga e falhas em cascata."
   • ❌ Ruim: "O circuit breaker abre após 10 erros consecutivos em 15 minutos com status codes 408, 429, 502, 503 e 504, com verificações a cada 3 ou 7 minutos."

7. Formato Markdown: usar blockquote com bold: > **Summary:** ...

ESTRUTURA OBRIGATÓRIA DO DOCUMENTO

1. BLOCO DE METADADOS (YAML)

O documento DEVE iniciar obrigatoriamente com:

---
Título: [Nome claro da funcionalidade, sistema ou componente]