Módulo 5.3 · RAG Architect | Claude Skills na Prática

🧭 Por que existe um RAG errado

A maioria dos RAGs falha pela mesma razão: tratar todo dado igual. "Chunka tudo, embeda, busca o top-k." Isso funciona para o simples — um FAQ, um manual. Mas no momento em que o dado fica complexo, a abordagem desmorona, e o sistema passa a recuperar a informação errada.

🎯 A tese central

Não existe "o RAG". Existem arquiteturas diferentes, e qual encaixa depende do dado:

•Um catálogo com códigos SKU precisa de roteamento exato, não só busca vetorial.
•Tickets, manuais em PDF e docs do Notion precisam de índices separados, não de um monte só.
•Casos jurídicos com citações precisam de travessia de grafo, não de busca por similaridade.

⚠️ O sintoma

"Meu RAG não puxa a informação certa." Quase sempre, a causa não é o modelo nem o prompt — é a arquitetura escolhida antes de entender o dado. Escolher errado aqui custa semanas de retrabalho.

Chunk

Pedaço do documento.

Embedding

Vetor de significado.

Retrieval

Buscar o relevante.

Arquitetura

A decisão que importa.

👥 Para quem é (e quem decide)

É para qualquer um conectando dados a um LLM. Você nem precisa saber o que RAG significa. Você descreve o que tem e o que quer perguntar; a skill descobre qual arquitetura encaixa, explica por quê, e entrega o código. Esse é o posicionamento de consultoria: o cliente fala de negócio, a skill fala de engenharia.

🔍 Os sinais que a skill lê nos seus dados

Distribuição de tamanho do texto — registros curtos e uniformes vs. docs longos definem a estratégia de chunk.
Relacionamentos — referências cruzadas e menções entre arquivos: alta interconexão → Graph RAG.
Cardinalidade — colunas de ID/categoria vs. texto livre: só texto livre se beneficia de embedding.
Escala — pequeno (<1K docs), médio (1K–100K), grande (100K+) afeta a escolha do banco vetorial.
Padrão de consulta — as perguntas misturam intenção semântica com lookups exatos (SKU, IDs)? Isso sinaliza busca híbrida.

✓ Como descrever o dado bem

✓"3 mil tickets de suporte, formatação inconsistente."
✓"Catálogo com SKU e descrição, perguntas misturam código e texto."
✓"Estou no Supabase, quero perguntar em linguagem natural."

✗ O que atrapalha a decisão

✗"Quero um RAG" — sem dizer nada do dado.
✗Pedir Graph RAG porque parece avançado.
✗Esconder que os dados estão em quatro lugares.

🗂️ As quatro arquiteturas

O coração da skill: quatro arquiteturas, cada uma com um gatilho claro. Saber as quatro e quando cada uma encaixa é o que separa uma recomendação útil de um chute.

1 · Naive RAG

dado simples e uniforme

Quando: dado bem estruturado, fonte única, tipos de documento uniformes, consultas diretas.

Como funciona: chunk → embed → vector DB → top-k → gerar resposta.

Encaixa em: FAQ da empresa, documentação de produto, um único manual.

2 · Advanced RAG

semântico + códigos exatos

Quando: dado mistura conteúdo semântico com identificadores exatos (SKU, IDs, nº de ticket); consultas blendam linguagem natural com filtros estruturados.

Como funciona: Naive + busca híbrida (vetor + BM25), análise de consulta (detectar padrões exatos), reranking, e roteamento direto para lookup nos campos exatos.

Dica de performance: cacheie lookups determinísticos — uma consulta de SKU sempre retorna o mesmo resultado.

3 · Modular / Agentic RAG

multi-fonte com roteador

Quando: múltiplas fontes, cada uma com estrutura, frequência de atualização e características próprias; a consulta às vezes precisa ser decomposta.

Como funciona: camada de orquestração com query router, índices separados por fonte (não um índice único com filtro), recuperação paralela, fusão com diversidade de fonte e reranking.

Encaixa em: base de conhecimento spanning Notion, Confluence, Slack e um banco SQL.

4 · Graph RAG

relações entre entidades

Quando: dado altamente relacional, onde a relação entre entidades importa tanto quanto o conteúdo; perguntas envolvem travessia ("quem trabalhou com quem?", "todos os casos que citam X").

Como funciona: grafo de conhecimento (entidades + relações) sobre a busca vetorial — extração de entidades, construção do grafo (Neo4j ou Apache AGE no Postgres) e um query classifier que roteia para grafo, vetor ou ambos.

Encaixa em: bases jurídicas com citações, dados organizacionais, literatura biomédica.

🧩 Dica prática: não over-engineer

Escale a complexidade ao problema. Não recomende Graph RAG para um FAQ simples. Uma boa recomendação também explica por que as alternativas foram descartadas — não só por que a vencedora foi escolhida.

✂️ Decisões de implementação

Escolhida a arquitetura, a skill entrega um plano concreto. O que separa um plano bom de um genérico é justificar os números mágicos — chunk size, top-k — com um raciocínio que o usuário pode usar para ajustar depois.

Decisão	Default	Como justificar
Chunk size	800–1500 tokens	Pelo tamanho do texto, não arbitrário.
Embedding	text-embedding-3-small	Trade-off de dimensão se relevante.
Vector DB	Supabase pgvector	Zero infra nova se já está no Supabase.
top-k candidatos	~20 antes do rerank	Diversidade suficiente, latência <200ms.

📊 Método de recuperação por arquitetura

Naive: busca por similaridade top-k.
Advanced: busca híbrida + reranking + pré-processamento de consulta + roteamento exato.
Modular: recuperação por fonte com lógica de roteamento, execução paralela, fusão com diversidade.
Graph: classificação da consulta → travessia de grafo / busca vetorial / ambos → merge.

🧩 Stack-awareness

Se o usuário menciona a stack dele (Supabase, Vercel, Python, n8n), a recomendação tem que usá-la. Quem está no Supabase recebe pgvector, não "suba um Qdrant". Quem está em Python recebe scaffold em Python. Recomendação genérica que ignora a infra existente é ativamente inútil.

📦 Scaffold rodável, não stub

A diferença entre uma skill útil e um gerador de boilerplate: código que roda de primeira. A skill gera um mini-projeto com migrations SQL completas e um README que é um guia de setup do começo ao fim.

scaffold gerado /rag-setup

/rag-setup
├── ingest.ts     # chunk, embed, upsert no vector DB
├── query.ts      # pipeline de recuperacao + geracao
├── config.ts     # modelo, conexao, chunk size + SQL migrations
└── README.md     # o que rodar e em que ordem

✓ Scaffold de verdade

✓SQL completo em config.ts — copia-cola no editor do Supabase e funciona.
✓Cada fonte tem ingestão e query funcionais, não comentário-placeholder.
✓SDKs oficiais (openai, @anthropic-ai/sdk), não fetch() cru.
✓README com npm install exato e comando de teste.

✗ O que não vale entregar

✗// implemente a ingestão aqui como corpo da função.
✗"Veja a recomendação para o SQL" em vez do SQL real.
✗API externa (Notion) sem endpoint, header nem parsing reais.
✗README sem dependências nem variáveis de ambiente.

📊 Regra de ouro

Um usuário seguindo o README de cima a baixo deve terminar com um sistema funcionando. Os únicos valores a preencher ficam marcados com // TODO: — todo o resto é código real e rodável.

🛠️ Empacotando o seu arquiteto

Este é o exemplo mais avançado da trilha: uma skill que faz julgamento de engenharia, não só geração de texto. O SKILL.md conduz cinco fases — entender o dado, recomendar, planejar, scaffold e (opcional) build companion.

Entender o dado

Capturar os sinais que importam (tamanho, relações, cardinalidade, escala, padrão de consulta) — conciso, sem virar um ensaio.

Recomendar

Qual das 4 arquiteturas, por que ela encaixa, o que daria errado com algo mais simples, e os trade-offs honestos.

Planejar & gerar scaffold

Plano de chunk/embedding/DB/retrieval + o mini-projeto rodável com migrations e README.

Build companion (opcional)

"Quer que eu ajude a construir e testar?" — ligar o pipeline ao dado real, rodar queries de teste, tunar chunk/top-k.

SKILL.md — rag-architect (esqueleto) frontmatter + fases

---
name: rag-architect
description: |
  Projeta o RAG ideal para os dados do usuario. Analisa estrutura,
  formato, relacoes e escala para recomendar a arquitetura certa e
  entregar plano + codigo inicial. Dispara em qualquer pedido sobre
  RAG, busca vetorial, semantica, "conversar com meus dados", chunking
  ou qualidade de retrieval — mesmo sem dizer "RAG".
---

# RAG Architect

Voce e um arquiteto de sistemas RAG.

## Fase 1 — Entender o dado
Pergunte: que dado, quanto, que perguntas, qual stack
(default: Next.js + Supabase + Claude API).

## Fase 2 — Recomendar 1 de 4
Naive | Advanced | Modular/Agentic | Graph
=> qual, por que, o que daria errado simples, trade-offs.

## Fase 3 — Plano
chunk + overlap (justificado), embedding, vector DB, retrieval.

## Fase 4 — Scaffold rodavel
/rag-setup: ingest.ts, query.ts, config.ts (com SQL!), README.
SEM stubs. SDKs oficiais. Stack do usuario sempre.

## Fase 5 — Build companion (opcional)
"Quer construir e testar?" => wire + tune.

⚡ Prompt para disparar a skill

tenho 3 mil tickets de suporte em Postgres (Supabase), formatação inconsistente, e perguntas que misturam descrição do problema com número do ticket. Que arquitetura de RAG usar e me dá o código inicial.

📝 Resumo do Módulo

✓

Arquitetura por dado — tratar todo dado igual é a causa nº 1 do RAG errado.

✓

Descreva o dado, não o RAG — a skill lê os sinais (tamanho, relações, cardinalidade, escala, consulta) e decide.

✓

Quatro arquiteturas — Naive, Advanced, Modular/Agentic e Graph, cada uma com um gatilho claro.

✓

Números justificados + stack-awareness — chunk e top-k com raciocínio; usar sempre a infra do usuário.

✓

Scaffold rodável — migrations completas e README guia, sem stubs.

🎯 Exercícios práticos

Para 3 conjuntos de dados (FAQ; catálogo com SKU; base jurídica com citações), escolha a arquitetura e justifique por que as outras foram descartadas.
Justifique um chunk size e um top-k para docs longos vs. registros curtos — explique o raciocínio, não só o número.
Esboce o config.ts com as migrations SQL para um Naive RAG em pgvector (tabela + índice + função de match).
Crie um SKILL.md rodável chamado rag-architect que conduza as 5 fases, recomende 1 de 4 arquiteturas a partir de uma descrição de dados e gere o scaffold /rag-setup. Teste com o prompt do tópico 6.

Fim da Trilha 5:

Próxima: Trilha 6 — Arquitetura Avançada de Skills

← Módulo Anterior Trilha 6: Avançado →