Tus esquemas de datos están listos para humanos. ¿También para la IA?

Cada vez le pedimos a más agentes de IA que hagan trabajo analítico de verdad: escribir SQL, responder preguntas de negocio, detectar patrones o apropiarse de modelos de datos. Asumamos que tu esquema está documentado lo bastante bien para una persona que ya conoce el contexto (mucho asumir en la mayoría de los casos), pero ¿también lo está para un agente que llega en frío?

Si hay conocimiento implícito, el agente tomara decisiones y hará asunciones para generar un SQL razonable. Todo compila, corre e incluso puede devolver números plausibles. Pero, ¿puedo asegurar que el agente no va a meter la pata semánticamente? Igual no sabe que un campo status solo admite cuatro valores válidos y ya puestos no entiende lo que significan cada uno de estos valores o si tiene repercusiones en el resto de columnas o implica cambios en la forma de leer los resultados. Igual interpreta una fecha nullable como “dato desconocido” cuando en realidad significa “esto nunca pasó”. Igual ve tres campos acabados en _id y asume que la PK es la composición de todos ellos cuando no lo es. Nada de eso es exactamente un fallo del modelo. Es, sobre todo, una falta de documentación.

Veamos un ejemplo. Estoy tratando con un modelo de datos de merchants. Te pones a trabajar con el modelo para construir un modelo para predecir churn y lo primero que hace el modelo es suponer que 15 días sin vender nada significan churn. Y resulta que un porcentaje significativo de los merchants manejan suscripciones mensuales o venden tickets para eventos que ocurren cada cierto número de semanas, de modo que sus ventas se concentran en ráfagas. Si tienes el conocimiento tácito sobre la manera en que trabajan tus merchants, guay. Si no lo tienes, puede que nunca te enteres de que el modelo está prediciendo churn partiendo de un porcentaje significativo de los positivos que no lo son. O que te enteres dos semanas más tarde cuando no hay manera de hacer un modelo potable y empiezas a rebuscar las razones. Lo primero es una tragedia troyana y lo segundo una telenovela turca.

Así que la pregunta es ¿Puedo saber hasta qué punto está preparado un esquema para que lo entienda y lo use bien un agente de IA?

De “está documentado” a “la IA lo puede entender”

Está documentado es una descripción vaga. Los agentes lo entienden, es aún borroso como definición pero marca un camino y define casos claros de no adherencia, cuando los agentes patinan y toman asunciones plausibles pero erradas.

¿Hay alguna manera de formular agent readiness de manera práctica?

Frameworks de evaluación de la documentación

Si, claro, la hay. Pasar tests. Creamos una batería de preguntas y usamos dos modelos, un respondent model que usa el AGENTS.md como contexto y carga bajo demanda todo lo que necesita y responde. Y un modelo juez que analiza la respuesta y la evalúa / puntúa respecto de una rúbrica a la que, por descontado, el respondent no tiene acceso (por ejemplo usando la métrica GEval de DeepEval)

Esto es robusto porque comprueba la precisión de forma empírica: dada esta documentación, el modelo es capaz de producir respuestas correctas de acuerdo con lo esperado. Pero también es pesado y limitado. Es limitado porque se compara respecto a un número determinado de preguntas, porque las mediciones dependen del modelo usado para responder e incluso de cada lanzamiento. Y sobre todo, a mi lo que me mata es que es un método muy pesado porque he tenido que definir las preguntas y respuestas de antemano.

¿Y algo más ligero?

A Una comprobación de la estructura de la documentación

Podemos hacer algo más ligero y que me es útil siempre, y cubre lo necesario en la amplísima mayoría de los use cases. Y si preguntamos simplemente ¿esta documentación tiene las propiedades estructurales que hacen posible la generación de respuestas coherentes, sin importar la pregunta’? Entonces estamos hablando de un check estructural. Ninguno de los dos subsume al otro. La evaluación simplemente te dice si las preguntas que elegiste eran respondidas correctamente, mientras que una comprobación de la estructura te dice si la misma es sólida. Son complementarios. Peor esta segunda es mucho más directa y sencilla de implementar.

Entonces el Agent Readiness significa esto: hasta qué punto un esquema permite a un agente autónomo entender y razonar correctamente sobre los datos sin conocimiento previo del dominio, sin preguntas de seguimiento y sin desperdiciar contexto por culpa de la ambigüedad. El primer paso… frecuentemente ignorado es que si no es 100% comprensible para un humano, no lo va a ser para un agente. No te hagas líos.

Vale, pues entonces, ¿qué es razonar correctamente? Lo podemos hacer ingeniería inversa desde los riesgos o escenarios de razonamiento incorrecto, como por ejemplo:

Desambiguación: Hay tablas similares en el DWH que sirven a propósitos similares, pero no idénticos. Usar la tabla incorrecta no avisa con errores, sino que el agente simplemente te da el resultado equivocado, de manera segura. Condident que dicen en la lengua del imperio.
El significado está oculto. Gran parte de la definición tácita de una tabla —su grano, su freshness, lo que excluye…— vive en el código del pipeline, no en las columnas ni en la documentación del esquema. Entonces, un agente podría descubrirla… si tiene razones para mirar el pipeline. Pero si la tabla ‘parece’ documentada o si puede tomar asunciones verosímiles… muy probablemente no lo hará. Y la liará.
Fallos silenciosos. Joins N a N que inflan las cuentas de filas, los nulls sin gestionar pueden distorsionar los agregados. De nuevo no tendré el incómodo, pero amistoso aviso de un error. Me las veré con resultados aparentemente correctos, pero que no lo son.
El contexto se mudó fuera de la tabla, pero dejó las luces encendidas. Parece que las tablas explican el significado -el agente está confiado en que tiene todo lo que necesita-, pero no están actualizadas. Una métrica que cambió, un cambio en el funcionamiento de un proceso que hace que los contenidos de las tablas cambien. Es posible que este contexto esté en hilos de Slack, en documentos de proyecto, en conversaciones, en posts internos… Pero no está donde tiene que estar para que agente sea consciente.

Desde ‘Está documentado’ a ‘Los agentes lo entiendeN’

A partir de los riesgos o escenarios que queremos precisamente evitar, podemos construir una checklist con cosas muy, muy concretas. Y según descubramos más, pues podemos añadir nuevos elementos. Esa es, en mi opinión, la idea: no pretender hacerlo perfecto a la primera, sino refinar iterativamente la lista. Y por otro lado, aplicar el sentido común: no existen absolutos. Es muy posible que una tal checklist contenga elementos que no sean necesarios ni convenientes, según el caso. Pero aún conviene pensarlo, aunque sea para decidir no aplicarlo.

¿Qué cosas concretas puede tener ‘una checklist para asegurar que la estructura mejora la legibilidad para agentes de un modelo de datos? Algunos ejemplos.

¿Puede el agente deducir cómo unir tablas sin tener que ir adivinando? ¿Es decir, está explícitamente marcado qué son PK y FK? ¿Se ha comprobado que lo marcado como clave es único?
¿Están explícitamente documentados los valores válidos de un campo categórico?
¿Se entiende -se entiende es sinónimo de está explicitamente descrito :)- qué significa null en términos de negocio, no solo en términos de base de datos?
¿Está descrito de dónde vienen los datos y para qué se usan después, en esos casos donde puede haber dudas —porque el mismo campo está en varias tablas upstream o porque en el downstream description no queda claro si se usó algo proveniente de esta tabla—?
¿Se conoce el grano de la tabla?

Cuantas más de esas preguntas responda el esquema por sí solo, menos tendrá que improvisar el agente. Recuerda: Las películas de SQL improvisado son del género de terror.

Desenlace: Una rúbrica con cinco dimensiones

Más que para medir legibilidad o agent readiness, la idea era comparar unas tablas con otras o incluso la misma tabla antes y después de aplicarle cambios. Lo que hice fue crear una rúbrica con cinco dimensiones priorizadas (con puntuaciones en escalera de 10 a 25) y que sumaban un total de 100 puntos. La puntuación es proporcional: miras qué fracción de los campos o tablas cumple cada criterio y la multiplicas por la puntuación máxima de esa dimensión. ¿Es una puntuación arbitraria? Sin duda. Pero que no tiene incienso ni magia y está clarita, también.

Dimensión	Max. Pts	Qué cubre
Documentación estructural	25	Comentarios de campos, descripción de tablas, nulabilidad y semántica del null
Riqueza semántica	30	Restricciones, valores válidos, lógica de campos derivados y referencias cruzadas
Contexto relacional	20	Lineage, cardinalidad, claves de join y contexto del pipeline
Validación de restricciones	15	Unicidad, reglas de negocio e integridad referencial
Comprensión humano-IA	10	Claridad terminológica, contexto de negocio y casos límite

Y después de puntuar pues podemos también fijar – de nuevo arbitrariamente- unos buckets o agrupaciones de puntuaciones para de algún modo establecer un criterio de priorización de cambios o de comparación.

Puntuación	Valoración
80–100	🟢 Preparado para IA
60–79	🟡 Útil con matices
40–59	🟠 Necesita trabajo
20–39	🔴 Carencias críticas
0–19	⚫ Nada preparado para IA

Ala, diseccionemos la rúbrica.

1. Documentación estructural (25 puntos)

La pregunta: ¿Tu esquema incluye la documentación estructural esencial?

Qué buscamos:

Encabezado del protocolo (3 pts): formato, versión y convenciones declaradas al inicio.
Documentación a nivel de campo (7 pts): anotaciones significativas que expliquen qué representa cada campo.
Documentación a nivel de tabla (8 pts): propósito, grano (qué hace única a una fila) y audiencia (quién usa esta tabla).
Declaración de nulabilidad (2 pts): marcadores explícitos de nullable o required. En nuestro AVDL, esto siempre es TRUE por defecto.
Semántica de los nulos (5 pts): el significado de negocio de null está documentado para los campos nullable; por ejemplo, “null significa que el usuario nunca ha iniciado sesión”.

Antes:

record OrdersSnapshot { ... }

Después:

			
/**
 * OrdersSnapshot - Estado actual de pedidos por día
 *
 * Fuente: Derivado de eventos de pedido y registros de facturación
 * Grano: Una fila por pedido y fecha de snapshot
 * Audiencia: Se usa para reporting operativo y análisis de retención
 * Dependency graph: [link]
 */
record OrdersSnapshot { ... }

		

2. Riqueza semántica (30 puntos)

La pregunta: ¿Las anotaciones capturan explícitamente la lógica de negocio?

Esta es la dimensión con mayor peso, y con razón. Las relaciones explícitas y los valores permitidos son lo que permite a los agentes de IA razonar sobre tus datos sin tener que adivinar. Además, ahorra contexto.

Qué buscamos:

Claves primarias estan todas marcadas explicitamente y son únicas (8 pts)
Claves foráneas con columnas explícitas (6 pts): anotaciones FK declaradas, no solo convenciones de nombres.
Campos categóricos con opciones expresamente enumeradas (6 pts): Los conjuntos finitos de valores declarados explícitamente.
Campos calculados con fórmulas (5 pts): si un campo es calculado, por ejemplo mrr_per_user = mrr / active_users, la fórmula está documentada.
Referencias cruzadas y definiciones compartidas (5 pts): Uso la herencia de documentación hacia esquemas externos y referencias explícitas a tablas upstream.

Antes:

string? status;

Después:

			
/* Estado del pedido */
@AllowedValues(["active", "cancelled", "pending", "refunded"])
string? status;

Ahora un agente que escriba una cláusula WHERE status = ... ya no tiene que inventarse nada. Lo mismo con los joins

Antes:

long? customer_id;

Después:

			
/* Identificador de cliente procedente del CRM */
@ForeignKey(["crm.customers", "id"])
long? customer_id;

3. Contexto relacional (20 puntos)

La pregunta: ¿El esquema incluye lineage y procedencia upstream?

Las personas —y los agentes de IA— sin un conocimiento profundo de los datos pueden verse tentados a usar una tabla sin entender de dónde vienen los datos o hacia dónde van. La información de linaje explícita corrige eso.

Qué buscamos:

Linaje de la tabla (Source / Used by) (6 pts): de dónde vienen los datos y hacia dónde van.
Pistas de cardinalidad (5 pts): documentar relaciones 1:1, 1:N y N:M para que los agentes sepan si un JOIN va a multiplicar filas.
Claves de JOIN con columnas explícitas (5 pts): ¿Puede un agente determinar cómo unir tablas sin tener que adivinar?
Narrativas del flujo de datos (4 pts): cadencia de actualización, expectativas de latencia y dependencias del pipeline.

4. Validación de restricciones (15 puntos)

La pregunta: ¿Las afirmaciones pueden verificarse contra la realidad?

La documentación que dice “esta columna es única”, pero en realidad no lo es en producción, es peor que no tener documentación: es activamente engañosa. Esta dimensión recompensa las restricciones que pueden verificarse.

Regla crítica: solo cuentan las restricciones que estén REALMENTE DECLARADAS con anotaciones formales (@Unique, @ForeignKey, @Check). Las restricciones “implícitas” u “obvias” puntúan cero.

Qué buscamos:

Restricciones de unicidad (5 pts): @Unique declarado, no solo un campo id.
Validaciones de reglas de negocio (4 pts): lógica de dominio como “si status = 'active', churn_date debe ser NULL”.
Integridad referencial verificada (6 pts): la FK está declarada y la tabla referenciada existe en el esquema.

Aquí hay muchísimo margen para la interpretación por parte del agente. ¿Cómo podemos saber si @Unique está declarado para todos los campos realmente únicos? Solo consultando la base de datos. Y mira, esto es algo que un agente puede hacer de una vez. Puede que tarde un poquito, pero si lo documenta, es trabajo adelantado para el futuro.

5. Comprensión humano-IA (10 puntos)

La pregunta: ¿Puede un agente entender esto sin conocimiento del dominio?

Descripciones cargadas de jerga, acrónimos sin explicación o documentación incompleta sobre casos límite se cargan la comprensión, tanto para humanos como para agentes.

Qué buscamos:

Claridad terminológica (4 pts): términos de dominio, acrónimos y nombres internos definidos dentro del esquema.
Contexto de negocio (3 pts): por qué existe esta tabla, quién la usa y qué decisiones ayuda a tomar.
Documentación de casos límite (3 pts): huecos históricos, peculiaridades conocidas y excepciones señaladas explícitamente.

Dos herramientas para que mejorar esto no sea un suplicio

Guay, ya tenemos claro como puntuar esquemas. Pero nadie quiere revisarlos a mano, tabla por tabla, para siempre jamás. Así que monté dos skills

1. Evaluate Schema for AI Readiness

Esta skill ejecuta la rúbrica sobre un archivo de esquema y devuelve una lista priorizada de recomendaciones concretas. Puedes apuntarla a un archivo en un repositorio o pegar el esquema directamente. En pocos minutos te dice no solo la puntuación, sino qué conviene arreglar primero. Evidentemente yo he dicho aquí mi priorización y mis puntuaciones. Para dar peso a unas cosas sobre otras, pues simplemente cambias los pesos. Sooooo simple.

2. schema improvement

Esta es modular. En lugar de intentar mejorar todo en una sola pasada gigante, trabaja por fases y puedo lanzar una o varias fases -o incluso una parte de una fase- sobre una o varias tablas de un esquema:

Fase 1: añade una cabecera de protocolo con fuentes de datos, tipos de tabla, convenciones de nombres y enlaces de referencia
Fase 2: documenta cada tabla con propósito, grano y audiencia prevista
Fase 3: documenta campos, identifica primary keys, anota foreign keys y detecta campos categóricos que necesitan enumeración de valores válidos
Fase 4: elimina documentación duplicada apuntando los campos repetidos a una fuente canónica
Fase 5 revisa datos de producción para detectar campos marcados como nullable que en realidad nunca son null y ajusta el esquema en consecuencia

El principio de diseño detrás de esto es el descubrimiento progresivo: cada fase carga solo el contexto que necesita. Eso hace el proceso más ligero, más fiable y más fácil de paralelizar a medida que los esquemas crecen. Níquel, que dicen en la lengua de la numinosa fraternidad.

Iteraciones, probaturas y refinamiento progresivo

Tras varias iteraciones y probaturas, refinando ambos skills, hubo algo incambiable. Ningún esquema alcanzó el umbral de “preparado para IA” que me había fijado. De nuevo el umbral era arbitrario, pero en todo caso era una expresión de lo que yo deseaba que mis esquemas fueran y esperaba que tuviera alguno de ellos. Pero ninguno, oye.

Puede sonar dramático, pero el patrón era bastante terrenal. Muchos esquemas tenían comentarios decentes a nivel de campo. Algunos incluían descripciones de tablas. Pero a menudo faltaban justo las piezas de las que más depende un agente cuando no puede pedir aclaraciones:

declaraciones explícitas de relaciones
semántica del null
enumeraciones de valores válidos
lineage y contexto upstream/downstream
significado de negocio, en especial para los casos límite

Es decir: justo las cosas que son obvias para quien lleva meses retorciendo el brazo a una fuente de datos y que son completamente invisibles para alguien que viene de nuevas a ese negocio o para un modelo al que acabas de darle la camisa sudada a oler hace cinco segundos.

No me quedó claro si se dice un skill o una skill, pero si que

1. Lo explícito gana a lo implícito

Si una relación de foreign key no está documentada explícitamente, no debería contarse. A veces el nombre del campo deja clara la unión. Y a veces no. Un agente no tiene tu conocimiento tácito, ni la memoria del equipo, ni esos seis meses de “ah, claro, esta columna es rara por una migración de hace dos años”.

2. La semántica del null importa muchísimo

nullable: true no le dice casi nada a un agente. Pero documentar algo como “Null si el cliente nunca ha hecho upgrade”, eso es oro. Esa diferencia cambia filtros, agregaciones e interpretación. Es la diferencia entre “dato ausente” y “ausencia significativa”, una de esas distinciones capaces de cargarse un análisis sin que te enteres.

3. El grano y la audiencia deberían vivir en el esquema

Notas cortas como “una fila por cliente y periodo de suscripción” o “se usa para reporting financiero” evitan una cantidad sorprendente de joins equivocados y, lo que es mucho peor, de conclusiones dudosas. Esto también ayuda a los humanos, claro. Los humanos molan porque se quejan 😀 La IA tira para delante y para cuando te enteras de que debería haberse quejado, ya es el momento del llanto y del rechinar de dientes.

Referencias y Estándares

Photo by Vinicius A. Nascimento on Pexels.com

Artículos Académicos

Datasheets for Datasets — Gebru et al. propusieron documentación estandarizada para conjuntos de datos, incluyendo motivación, composición y usos previstos. Leer el artículo
Model Cards for Model Reporting — Mitchell et al. introdujeron documentación estructurada para modelos de ML que incluye métricas de rendimiento en diferentes condiciones. Leer el artículo
FAIR Principles — Wilkinson et al. establecieron principios para hacer los datos Encontrables, Accesibles, Interoperables y Reutilizables. Leer el artículo
Data Cards Playbook — El equipo de Google Research creó una guía práctica para documentar conjuntos de datos con transparencia. Ver el playbook

Estándares

Croissant — MLCommons desarrolló un formato de metadatos para conjuntos de datos de ML que mejora la descubribilidad y reproducibilidad. Más información
HuggingFace Dataset Cards — Documentación estandarizada para conjuntos de datos alojados en el Hub de HuggingFace. Ver documentación
Dataset Nutrition Label — El Data Nutrition Project proporciona un marco para evaluar la “nutrición” de los conjuntos de datos. Visitar el proyecto | Leer el artículo

Frameworks de Evaluación

Ragas — Framework de código abierto para evaluar pipelines de RAG con métricas como faithfulness, relevancia de respuesta y relevancia de contexto. Documentación | Métricas disponibles
DeepEval — Framework de evaluación de LLMs que incluye métricas específicas para RAG. Ver repositorio
LlamaIndex Evaluation — Módulo de evaluación integrado para medir la calidad de recuperación y generación. Ver documentación