Cómo construir un asistente RAG para código Angular

¿Quieres un asistente que sepa más de tu repo Angular que la mitad del equipo?

Tiempo estimado de lectura: 6 min

Ideas clave:
1. Un RAG bien diseñado para un repo Angular requiere chunking semántico (AST) y metadatos por fragmento.
2. Combina embeddings, una Vector DB, y búsquedas híbridas (semántica + léxica) para precisión y cobertura.
3. Actualiza la indexación en CI/CD, filtra secretos y controla acceso; mide precisión y freshness.

Bien. Poca gente lo hace bien: indexan archivos y esperan magia. Lo que propongo es práctico, reproducible y —esto es importante— no te convierte en esclavo de la “caja negra” de la IA.

Esto no es teoría. Es el plan para montar un RAG (Retrieval‑Augmented Generation) que entienda tu código Angular y responda preguntas útiles: “¿Dónde está la lógica de autenticación?” o “¿Qué componentes usan este servicio?”. Resultado: menos búsqueda manual, menos onboarding traumático y menos reuniones de 30 minutos para encontrar un import.

Resumen rápido (lectores con prisa)

RAG para repos Angular: chunking semántico con AST, embeddings con metadatos por fragmento, almacenaje en Vector DB, búsqueda híbrida (semántica + léxica), y prompting estricto. Actualiza desde CI y filtra secretos. Resultado: asistente auditables que devuelven archivos y líneas exactas.

Resumen rápido: la arquitectura

Repo Angular
↓
Chunking inteligente (AST)
↓
Embeddings (vectores)
↓
Vector DB (Qdrant/Pinecone/Chroma)
↓
Retriever + Prompting
↓
LLM (Claude/GPT‑4o/Gemini) → Respuesta

Es como un GPS para tu repo: no te dice sólo la dirección; te guía por el camino con referencias exactas.

Paso 1 — Ingesta y chunking: no cortes a lo bruto

El error número uno: trocear por caracteres. Si rompes una clase en tres pedazos, el asistente no entenderá nada.

Hazlo así:

Extrae solo .ts, .html, .scss (ignora node_modules, dist).
Usa un parser AST (ts-morph, TypeScript compiler API).
Chunk por unidad semántica: clase, método, decorador @Component, template completo.
Adjunta metadatos con cada chunk: ruta de archivo, rango de líneas, exports, imports, dependencias.

¿Por qué? Porque mantener la semántica preserva referencias internas: inyectados, nombres de métodos y comentarios relevantes. La búsqueda semántica funciona mejor con sentido, no con cortes arbitrarios.

Paso 2 — Embeddings: convierte código en significado

Usa un modelo de embeddings que soporte código (o buen embedding textual). Ejemplos: OpenAI embeddings, Anthropic embeddings o modelos open‑source.

Incluye metadatos en cada vector:

filePath
startLine/endLine
repoCommitHash
language (TS/HTML)

Esto te permitirá enlazar respuesta → archivo exacto.

Paso 3 — Vector DB: guarda, busca y devuelves contexto

Qdrant, Pinecone, Chroma o Milvus. Elige según:

Latencia y coste.
Necesidad de búsquedas híbridas (vectores + texto).
Facilidad de actualización incremental.

Guarda los vectores con su metadata. En las búsquedas devuelve los top N (5–10) fragments y su score.

Paso 4 — Recuperación y Prompting: controla lo que el LLM ve

No mandes 200 fragments al LLM. Haz un pipeline:

Convertir la pregunta en vector.
Recuperar top N fragments.
Re‑ordenar (rerank) con un modelo más pequeño (o BM25 híbrido) si hace falta.
Construir prompt: system prompt (rol, reglas), contexto (fragments con filePath), user prompt (la pregunta).

System prompt ejemplo (corto y estricto):

“Eres un Senior Engineer que conoce este repo Angular. Responde citando archivos y líneas. Si no estás seguro, di ‘No encontrado’ y sugiere búsqueda exacta.”

User prompt:

“¿Dónde está la lógica de autenticación? Resume en 3 líneas y lista archivos con líneas relevantes.”

Consejo: limita tokens del contexto y prioriza fragments con mayor score y mayor cobertura de imports/exports.

Paso 5 — Búsqueda híbrida: semántica + léxica

La búsqueda vectorial falla en identificadores exactos. Combínala con BM25/Elasticsearch:

Si la query contiene un identificador exacto (ej. MAX_RETRY_COUNT) lanza búsqueda léxica.
Fusiona resultados léxicos y semánticos, rerankeando por heurística (match exacto primero, luego semántica).

Paso 6 — Actualización (CI/CD): no dejes la DB caduca

Tu repo cambia. Si no actualizas, el asistente te miente.

Estrategia:

GitHub Action on push/merge a main.
Detecta archivos cambiados.
Recalcula embeddings solo para los chunks afectados.
Upsert en la Vector DB (mantén id por filePath+chunkIndex).
Opcional: reindex completo nocturno semanalmente.

Paso 7 — Seguridad y compliance

No indexes secretos ni .env. Filtro obligatorio:

Excluir archivos con pattern (*.pem, *.key, *.env, secrets/*).
Escanea por secretos (truffleHog/commit hooks) antes de ingest.
Control de acceso: el asistente debe vivir en la red privada o detrás de SSO.

UI: cómo lo ve el equipo

No necesitas un chat bonito para empezar. Un endpoint REST que responda JSON es suficiente. Después añade:

Web UI (Next.js/Vercel) con chat y “open file” links que abren la ruta y saltan a la línea (vía deep link).
Integración en Slack/Teams.
Extensión VS Code que haga preguntas desde el editor.

Métricas que realmente importan

Precision@5: ¿Top5 fragments contienen la respuesta?
Freshness lag: tiempo desde commit → indexado.
False positives rate: respuestas con referencias no existentes.
Cost per query (tokens + vector ops).

Monitoreo

Loggea queries y feedback del usuario (útil/no útil). Si varias queries fallan same intent → recalibrar chunking/prompt.

Ejemplo de flujo técnico (resumido)

1. Push a main → GitHub Action lées files cambiados.
2. Parser AST genera chunks.
3. Embeddings API produce vectores.
4. Vector DB upsert.
5. Usuario pregunta → retriever devuelve top N.
6. LLM genera respuesta con fragments citados.
7. UI muestra respuesta + enlaces a archivos.

Snippets útiles (conceptual)

Chunking: usa ts-morph para obtener clases y decoradores.

Metadata: filePath, startLine, endLine, exportedSymbols.

ID vector: sha256(filePath + startLine + endLine + commitHash).

Prompts prácticos para el assistant

System:

“Eres un asistente que conoce el repo. Responde con: 1) short summary (1–3 lines), 2) list of files with line ranges, 3) confidence (low/med/high). Si no hay evidencia, responde ‘No encontrado’.”

User:

“Find where authentication is implemented and list files and exact lines. Provide short explanation and note any async flows or token persistence.”

Errores comunes y cómo evitarlos

Respuestas demasiado especulativas: limita el LLM a generar solo si score > threshold o si hay 2+ fragments con cobertura.
Señalar rutas obsoletas: siempre incluye commitHash o timestamp en la respuesta si la indexación no es inmediata.
Uso de versiones de Angular distintas: guarda version metadata (package.json) y advierte si query puede estar afectada por versiones.

Costes y tradeoffs

Más fragments → mejor recall → más tokens → mayor coste. Vector DB más rápido → mayor coste operativo. Empieza pequeño: indexa core modules primero (core, shared, features/*), añade el resto por demanda.

Checklist de implementación (rápido)

[ ] Definir scope de archivos a indexar.
[ ] Implementar chunking AST.
[ ] Elegir embeddings provider.
[ ] Seleccionar Vector DB.
[ ] Construir retriever + prompt templates.
[ ] Pipeline CI para upserts incrementales.
[ ] UI minimal + links a código.
[ ] Monitoreo y feedback loop.

Esto no es una caja negra. Es un asistente que puedes auditar, versionar y controlar.

Si quieres, te doy el kit listo:

GitHub Action para reindexar archivos cambiados.
Script Node.js de chunking con ts-morph.
Ejemplo LangChain/LlamaIndex que hace retrieval + LLM.
Prompt templates y policy de seguridad.

Dime cuál quieres: “ACTION” (GitHub Action + workflow), “CHUNKER” (script ts-morph), “LANGCHAIN” (ejemplo de retriever+prompt) o “KIT” (todo lo anterior). Te lo preparo para pegar y usar.

No lo dejes para “más adelante”. Si tardas, alguien más en tu equipo seguirá perdiendo horas buscando imports. Monta el asistente y gana tiempo real. ¿Qué quieres primero — la Action que indexe tu repo o el prompt que haga respuestas precisas?

Si quieres experimentar con pipelines de automatización e IA aplicada similares a lo descrito, puedes ver recursos y experimentos en Dominicode Labs. Allí hay ejemplos y guías prácticas que complementan este enfoque y ayudan a acelerar la implementación en equipos frontend y de plataforma.

¿Qué archivos debo indexar?

Extrae principalmente .ts, .html y .scss. Ignora carpetas como node_modules y dist, y excluye patrones de secretos (*.pem, *.key, *.env, secrets/*).

¿Por qué usar AST para chunking?

El chunking semántico preserva unidades lógicas (clases, métodos, decoradores) y mantiene referencias internas útiles para recuperación y contexto. Evita cortar una entidad en trozos que pierdan sentido.

¿Qué Vector DB elegir?

Depende de latencia, coste y necesidad de búsquedas híbridas. Opciones comunes: Qdrant, Pinecone, Chroma, Milvus. Elige según tus requisitos operativos y presupuesto.

¿Cómo evitar indexar secretos?

Implementa filtros por patrón, escaneo de secretos (truffleHog/commit hooks) antes de ingest y reglas CI que bloqueen upserts si detectan credenciales.

¿Cada cuánto reindexar?

Indexa cambios en push/merge (CI). Recalcula embeddings solo para chunks afectados y considera reindex completo nocturno/semanal según tamaño del repo y ritmo de cambios.

¿Cómo manejar identificadores exactos?

Usa búsqueda híbrida: si la query contiene un identificador exacto, ejecuta búsqueda léxica (BM25) y fusiona con resultados semánticos, priorizando matches exactos.

¿Qué métricas debo monitorear?

Precision@5, freshness lag, false positives rate y coste por query (tokens + vector ops). Además, registra feedback de usuario para recalibrar.