🧭 Por qué existe un RAG equivocado
La mayoría de los RAG falla por la misma razón: tratar todos los datos iguales. «Divide todo en chunks, genera embeddings, busca el top-k». Esto funciona para lo simple: una FAQ, un manual. Pero en cuanto los datos se vuelven complejos, el enfoque se desmorona y el sistema empieza a recuperar información equivocada.
🎯 La tesis central
No existe "el RAG". Existen arquitecturas diferentes, y cuál encaja depende del dato:
- •Un catálogo con códigos SKU necesita enrutamiento exacto, no solo de búsqueda vectorial.
- •Los tickets, los manuales en PDF y los documentos de Notion necesitan índices separados, no de una sola vez.
- •Los casos jurídicos con citas necesitan recorrido del grafo, no de la búsqueda por similitud.
⚠️ El síntoma
"Mi RAG no recupera la información correcta." Casi siempre, la causa no es el modelo ni el prompt: es la arquitectura elegida antes de entender los datos. Elegir mal aquí cuesta semanas de retrabajo.
👥 Para quién es (y quién decide)
Es para cualquiera que conecte datos a un LLM. Ni siquiera necesitas saber qué significa RAG. Describes lo que tienes y lo que quieres preguntar; la skill descubre qué arquitectura encaja, explica por qué y entrega el código. Ese es el enfoque de consultoría: el cliente habla de negocio y la skill habla de ingeniería.
🔍 Las señales que la skill lee en tus datos
- Distribución del tamaño del texto — los registros cortos y uniformes frente a los documentos largos definen la estrategia de chunk.
- Relaciones — referencias cruzadas y menciones entre archivos: alta interconexión → Graph RAG.
- Cardinalidad — columnas de ID/categoría frente a texto libre: solo el texto libre se beneficia de embeddings.
- Escala — pequeño (<1K docs), mediano (1K–100K), grande (100K+) influye en la elección de la base de datos vectorial.
- Patrón de consulta — ¿las preguntas mezclan intención semántica con búsquedas exactas (SKU, IDs)? Eso indica una búsqueda híbrida.
✓ Cómo describir bien el dato
- ✓"3 mil tickets de soporte, formato inconsistente."
- ✓"Catálogo con SKU y descripción; las preguntas mezclan códigos y texto."
- ✓"Estoy en Supabase y quiero hacer preguntas en lenguaje natural."
✗ Lo que dificulta la decisión
- ✗"Quiero un RAG" — sin decir nada sobre los datos.
- ✗Pedir Graph RAG porque parece avanzado.
- ✗Ocultar que los datos están en cuatro lugares.
🗂️ Las cuatro arquitecturas
El corazón de la skill: cuatro arquitecturas, cada una con un disparador claro. Conocer las cuatro y saber cuándo encaja cada una es lo que distingue una recomendación útil de una suposición.
1 · Naive RAG
dato simple y uniformeCuando: dato bien estructurado, fuente única, tipos de documentos uniformes, consultas directas.
Cómo funciona: fragmento → embed → base de datos vectorial → top-k → generar respuesta.
Encaja en: FAQ de la empresa, documentación del producto, un único manual.
2 · Advanced RAG
semántico + códigos exactosCuando: dato mezcla contenido semántico con identificadores exactos (SKU, IDs, n.º de ticket); las consultas combinan lenguaje natural con filtros estructurados.
Cómo funciona: Naive + búsqueda híbrida (vector + BM25), análisis de consultas (detectar patrones exactos), reranking y enrutamiento directo a la búsqueda en los campos exactos.
Consejo de rendimiento: almacena en caché las búsquedas determinísticas: una consulta de SKU siempre devuelve el mismo resultado.
3 · Modular / Agentic RAG
multifuente con enrutadorCuando: múltiples fuentes, cada una con su propia estructura, frecuencia de actualización y características; a veces es necesario descomponer la consulta.
Cómo funciona: capa de orquestación con enrutador de consultas, índices separados por fuente (no un índice único con filtro), recuperación paralela, fusión con diversidad de fuentes y reranking.
Encaja en: base de conocimiento que abarca Notion, Confluence, Slack y una base de datos SQL.
4 · Graph RAG
relaciones entre entidadesCuando: dato muy relacional, donde la relación entre entidades importa tanto como el contenido; las preguntas implican recorrerlo ("¿quién trabajó con quién?", "todos los casos que mencionan X").
Cómo funciona: grafo de conocimiento (entidades + relaciones) sobre la búsqueda vectorial: extracción de entidades, construcción del grafo (Neo4j o Apache AGE en Postgres) y un clasificador de consultas que deriva al grafo, al vector o a ambos.
Encaja en: bases jurídicas con citas, datos organizacionales, literatura biomédica.
🧩 Consejo práctico: no sobreingenierices
Ajusta la complejidad al problema. No recomiendes Graph RAG para un FAQ simple. Una buena recomendación también explica por qué se descartaron las alternativas, no solo por qué se eligió la ganadora.
✂️ Decisiones de implementación
Una vez elegida la arquitectura, la skill ofrece un plan concreto. Lo que diferencia un buen plan de uno genérico es justificar los números mágicos — chunk size, top-k, con un razonamiento que el usuario pueda usar para ajustarlos después.
| Decisión | Default | Cómo justificar |
|---|---|---|
| Tamaño del chunk | 800–1500 tokens | Según la extensión del texto, no de forma arbitraria. |
| Embedding | text-embedding-3-small | Compromiso de dimensiones, si es relevante. |
| Vector DB | Supabase pgvector | Cero infraestructura nueva si ya está en Supabase. |
| candidatos top-k | ~20 antes del rerank | Diversidad suficiente, latencia <200ms. |
📊 Método de recuperación por arquitectura
- Naive: búsqueda por similitud top-k.
- Advanced: búsqueda híbrida + reranking + preprocesamiento de consultas + enrutamiento exacto.
- Modular: recuperación por fuente con lógica de enrutamiento, ejecución en paralelo y fusión con diversidad.
- Graph: clasificación de la consulta → recorrido del grafo / búsqueda vectorial / ambos → combinación.
🧩 Conciencia del stack
Si el usuario menciona su stack (Supabase, Vercel, Python, n8n), la recomendación tienes que usarla. Si usas Supabase, recibes pgvector, no "instala Qdrant". Si usas Python, recibes un scaffold en Python. Una recomendación genérica que ignora la infraestructura existente es activamente inútil.
📦 Scaffold ejecutable, no stub
La diferencia entre una skill útil y un generador de boilerplate: código que funciona a la primera. La skill genera un miniproyecto con migraciones SQL completas y un README que guía la configuración de principio a fin.
/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 verdad
- ✓SQL completo en
config.ts— copiar y pegar en el editor de Supabase y funciona. - ✓Cada fuente tiene una ingestión y una query funcionales, no un comentario-placeholder.
- ✓SDK oficiales (
openai,@anthropic-ai/sdk), nofetch()crudo. - ✓README con
npm installexacto y comando de prueba.
✗ Qué no vale la pena entregar
- ✗
// implemente a ingestão aquicomo cuerpo de la función. - ✗"Consulta la recomendación para SQL" en lugar del SQL real.
- ✗API externa (Notion) sin endpoint, header ni parsing reales.
- ✗README sin dependencias ni variables de entorno.
📊 Regla de oro
Un usuario que siga el README de principio a fin debe terminar con un sistema funcionando. Los únicos valores que hay que completar están marcados con // TODO: — todo lo demás es código real y ejecutable.
🛠️ Empaquetando tu arquitecto
Este es el ejemplo más avanzado de la ruta: una skill que hace criterio de ingeniería, no solo de generación de texto. El SKILL.md guía cinco fases: entender el dato, recomendar, planificar, crear el scaffold y, de forma opcional, crear el build companion.
Entender el dato
Capturar las señales que importan (tamaño, relaciones, cardinalidad, escala, patrón de consulta) — de forma concisa, sin convertirlo en un ensayo.
Recomendar
Cuál de las 4 arquitecturas, por qué encaja, qué saldría mal con algo más simple y cuáles son las ventajas y desventajas reales.
Planificar y generar scaffold
Plan de chunk/embedding/DB/retrieval + el miniproyecto ejecutable con migrations y README.
Build companion (opcional)
"¿Quieres que te ayude a construirlo y probarlo?" — conectar el pipeline con los datos reales, ejecutar queries de prueba y ajustar chunk/top-k.
--- 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 activar la skill
📝 Resumen del módulo
🎯 Ejercicios prácticos
- Para 3 conjuntos de datos (FAQ; catálogo con SKU; base jurídica con citas), elige la arquitectura y justifica por qué descartaste las demás.
- Justifica un chunk size y un top-k para documentos largos frente a registros cortos; explica el razonamiento, no solo el número.
- Esboza el
config.tscon las migraciones SQL para un Naive RAG en pgvector (tabla + índice + función de coincidencia). - Crea un SKILL.md ejecutable llamado
rag-architectque guíe las 5 fases, recomiende 1 de 4 arquitecturas a partir de una descripción de datos y genere el scaffold/rag-setup. Prueba con el prompt del tema 6.
Fin de la Ruta 5:
Siguiente: Ruta 6 — Arquitectura avanzada de Skills