Evaluación de la deuda en el diseño del esquema GraphQL con LLMs y un sistema CI Ratchet

Un esquema GraphQL que es modificado por docenas o cientos de ingenieros en diversos dominios de productos acaba desviándose, sin importar cuán buena sea la guía de estilo. Los herramientas de linting detectan los problemas mecánicos, pero los más graves requieren juicio: un String que debería ser un enum, una lista que crece sin límites, un campo nulable que en realidad nunca devuelve null. Este artículo describe un sistema de dos partes para esos casos: un revisor asistido por LLM que evita nuevas deudas de diseño desde la solicitud de integración, y una evaluación del esquema existente que convierte las deudas antiguas en tareas prioritarias y rastreables, controladas mediante un mecanismo de CI.

Por qué la calidad de las API se convierte en un problema sistémico

Con un puñado de ingenieros, tener una API consistente se reduce en gran medida a cuestiones de gusto compartido. La gente trabaja junta, revisa los cambios en los esquemas de los demás y llega a patrones similares. A medida que la organización crece, esto deja de funcionar. Se lanzan constantemente nuevas funcionalidades, las convenciones antiguas coexisten con las más recientes, y las decisiones que parecían obvias para el equipo original son aplicadas de manera diferente por equipos que nunca los conocieron.

En ese punto, hay tres preguntas que requieren respuestas que no dependan de la atención de un solo revisor:

• ¿Cómo mantener un diseño de API consistente cuando varios equipos editan el esquema en paralelo?
• ¿Cómo asegurarse de que los nuevos tipos y campos sigan las mejores prácticas actuales?
• ¿Cómo identificar las partes de la API que se diseñaron antes de que existieran esas prácticas?

Los dos primeros se refieren a la prevención. El tercero trata sobre arqueología y es el que más suelen pasar por alto los esfuerzos de gobernanza.

Dónde terminan las reglas de lint y comienza el juicio

Una gran parte de los estándares API son mecánicos, y el análisis estático los maneja bien. Las convenciones de nomenclatura, el uso de campos obsoletos, las descripciones obligatorias y una estructura de errores consistente son todas propiedades de tipo sí-o-no del esquema: un campo o sigue la regla o no, y un herramienta de lint puede indicar cuál es el caso.

Otros estándares no pueden reducirse a una regla simple. Ejemplos típicos:

• ¿Debería este String ser un enum?
• ¿Debería esta lista paginarse?
• ¿Debería este Int ser un escalar personalizado?
• ¿Podría este campo nulo convertirse de forma segura en no nulo?
• ¿Esta estructura coincide con la forma en que se modelan conceptos similares en otras partes de la API?

Ninguno de estos casos tiene una respuesta sin contexto. Devolver un String, o incluso un bloque JSON sin tipado, a veces es correcto. Para determinar si eso es correcto se deben considerar tres aspectos al mismo tiempo: la declaración del esquema, la implementación del resolvedor detrás de él y la intención de exponer esos datos a los clientes. Solo con estos tres elementos se puede decidir qué formato será el más útil para los clientes.

Las organizaciones suelen abordar esto mediante revisiones de código, sesiones de consulta con el equipo de la plataforma y pautas escritas. Eso funciona, pero tiene escasa escalabilidad. La presión por entregar resultados acorta las revisiones, el equipo de la plataforma no puede analizar cada cambio en los esquemas de cada repositorio, y las buenas prácticas evolucionan más rápido de lo que se vuelven a revisar las APIs antiguas. El resultado son dos problemas relacionados: evitar nuevas deudas de diseño y detectar las que ya existen.

Desplazamiento hacia la izquierda: un revisor de LLM para cambios en esquemas

La primera mitad del sistema codifica las pautas de diseño de la API en un agente automatizado para revisiones de código. El objetivo no es reemplazar a los revisores humanos, sino brindarles una segunda opinión sobre exactamente las cuestiones que pasan desapercibidas durante una revisión normal de solicitudes de integración. Que el equipo de la plataforma apruebe personalmente cada cambio en GraphQL en todos los repositorios no es escalable; en cambio, aplicar los estándares preferidos a un revisor de IA que funciona en todas partes sí lo es.

Dado que el agente ve más que solo las diferencias en el esquema, puede razonar sobre el contexto en lugar de la sintaxis. Lee la declaración, la implementación que respalda el campo y el texto de política relevante, y luego plantea preguntas específicas. Dos comentarios representativos:

• Un campo llamado updatedAt está declarado como String. Si el resolvedor devuelve una marca de tiempo ISO 8601, probablemente debería utilizar en su lugar el escalar dedicado ISO8601DateTime.
• Company.employees devuelve una lista simple. El número de empleados de una empresa no tiene un límite superior natural, por lo que este campo debería devolver una conexión paginada.

Ninguno de estos casos es algo que un analizador de código pueda detectar de manera fiable. Una regla de análisis que establezca que “los campos que terminan en At deben ser escalares de fecha” genera falsos positivos y pasa por alto lastModified; una regla que diga “todas las listas deben estar paginadas” es incorrecta para un campo que devuelve las tres monedas soportadas. El LLM puede observar lo que hace realmente el resolvedor.

Lo importante es el momento oportuno. Es económico detectar estos problemas mientras la API aún está en fase de diseño. Detectarlos después de que los clientes ya hayan adoptado su estructura implica un ciclo de descontinuación y una migración.

Mirando hacia atrás: evaluando el esquema que ya se tiene

La prevención no sirve de nada para la superficie existente, y en una API madura esa superficie es muy amplia. Parte de ella data de antes de los estándares actuales. Algunas partes reflejan compromisos que tenían sentido en su momento. Y otras son simplemente desiguales, porque equipos separados modelaron el mismo concepto a su manera. Se necesita una forma de mirar hacia atrás.

La segunda mitad del sistema es un proceso por lotes que complementa las herramientas de análisis estático que ya están analizando el esquema. Su flujo de trabajo es:

1. Recorrer el esquema dominio por dominio y seleccionar campos o tipos en los que sea necesario aplicar un juicio subjetivo de diseño.

Reúna la declaración del esquema junto con el código de implementación relevante.

Envíe ese contexto a un LLM en una instrucción que incluya las políticas de diseño de API por escrito.

Pregunte al modelo si el campo parece violar alguna de esas prácticas subjetivas.

Guarde el resultado como una puntuación más una explicación por escrito.

Resuma los hallazgos por dominio del producto o equipo responsable.

El paso 1 es importante para controlar costos y ruido. No hay razón para preguntarle al modelo sobre campos que ya han sido clasificados mediante una verificación determinística; el LLM solo debe analizar aquellos casos donde realmente se necesita juicio.

Por qué una puntuación de 1 a 5 es mejor que aprobar/rechazar

Dado que se trata de decisiones subjetivas, forzar cada hallazgo en un veredicto binario desperdicia información. En su lugar, cada campo recibe una puntuación de revisión del 1 al 5:

• 1: el campo parece adecuado según lo diseñado.
• 2: hay una señal débil, pero probablemente esté bien.
• 3: alguien debería echarle un vistazo.
• 4: es probable que el campo infrinja la política.
• 5: el campo es un caso típico del patrón que se debe evitar.

Para concretarlo: un campo String que contiene texto escrito por el usuario de forma arbitraria debería situarse cerca del 1. Un campo String llamado errorCode cuyo resolvedor solo puede devolver uno de tres valores predefinidos debería situarse cerca del 5, ya que se trata en realidad de un enum disfrazado.

Una puntuación calificada proporciona una señal mucho más útil que una lista simple de violaciones. Los equipos pueden comenzar con las calificaciones de 4 y 5, que indican un alto nivel de confianza, y aún así identificar las áreas de menor confianza que podrían requerir un análisis más detallado. La zona intermedia de la escala tiene otra utilidad: un grupo de calificaciones 3 indica al equipo de la plataforma dónde el texto de la política o la instrucción es ambiguo, lo cual sirve como retroalimentación para mejorar las instrucciones de evaluación hasta obtener resultados más fiables.

Si creas algo similar, pide al modelo que genere una salida estructurada (una puntuación y una explicación en campos separados) para que los resultados puedan almacenarse y agregarse sin tener que analizar texto narrativo. Además, mantén versionadas tanto el texto de la política como la rúbrica de puntuación junto con la instrucción, de modo que los cambios en las puntuaciones puedan relacionarse con los cambios en las reglas.

Convierte los hallazgos en acciones

Las puntuaciones en una base de datos no cambian por sí solas. Al agruparlas por dominio en un panel de control, cada equipo responsable obtiene una visión concreta de la deuda en el diseño de la API en su área: no anécdotas dispersas ni comentarios puntuales, sino una lista priorizada de campos y tipos que podrían necesitar migración.

Los mismos datos permiten avanzar de forma gradual en la integración continua. El objetivo no es arreglar todo de una vez, lo cual es irrealista para una API grande con muchos clientes en producción. El objetivo es asegurarse de que la situación no empeore mientras la superficie existente mejora con el tiempo:

• Los nuevos cambios en el esquema deben cumplir con el estándar actual.
• Los problemas existentes se registran como deuda conocida en lugar de ignorarse silenciosamente.
• A medida que los equipos migran o deprecian patrones antiguos, el umbral permitido se vuelve más estricto, de modo que la deuda ya resuelta no pueda reaparecer.

Los engranajes representan un patrón común en las migraciones de datos: se registra el número actual de infracciones por área, la compilación falla si un cambio lo incrementa, y se reduce el valor de referencia registrado cada vez que alguien corrige una instancia.

Este enfoque es especialmente importante para APIs públicas o de amplio uso, donde la limpieza depende de las migraciones realizadas por los clientes. El resultado no es una instrucción para eliminar cada campo defectuoso, sino un mapa priorizado que muestra dónde la API ya no cumple con los estándares actuales, lo cual permite a los equipos planificar sus acciones.

Por qué un LLM es la herramienta adecuada para esta tarea

Los LLM no son jueces impecables del diseño de APIs, y el sistema tampoco los trata como tales. Su fortaleza aquí es más específica: leer código y esquemas juntos, compararlos con políticas redactadas en lenguaje sencillo y generar una evaluación estructurada para casos que ninguna regla estática puede abordar.

Una regla estática puede indicarte que un campo devuelve una lista. No puede decirte si esa lista crece con las entradas del usuario y, por lo tanto, necesita paginación. Un modelo puede leer el resolvedor, compararlo con los ejemplos de la política y explicar por qué el campo sí o no se ajusta al patrón.

Esa explicación vale más que el número asociado a ella. Cuando un campo se marca como problemático, el equipo responsable necesita saber por qué, para poder decidir rápidamente si el hallazgo es real y, de serlo, cómo planificar la migración. Una puntuación sin motivo solo crea otra cola de triaje.

Límites que debes tener en cuenta

La revisión con LLM no reemplaza la responsabilidad del equipo de API ni el juicio del diseñador humano, y es útil ser explícito sobre lo que queda:

• Aún ocurren falsos positivos.

A veces, la implementación por sí sola no revela la imagen completa, por ejemplo cuando una restricción se encuentra en otro servicio.

Las restricciones del producto pueden hacer que una forma imperfecta sea, de todos modos, la mejor opción en términos de equilibrio.

El sistema no migra a los clientes ni garantiza que los cambios causen problemas. Solo identifica deudas técnicas; los equipos siguen teniendo que planificar y ejecutar las migraciones con cuidado.

Lo que sí proporciona es una forma escalable de identificar patrones que anteriormente estaban limitados por la cantidad de revisión humana disponible. Las pautas se codifican una vez, se aplican de manera consistente en todos los repositorios, y los resultados brindan a los equipos un punto de partida factual para las conversaciones de diseño.

Conclusión

El sistema consta de dos partes que comparten una misma idea. Al presentarse una solicitud de integración, un revisor basado en LLM aplica las pautas de diseño a los nuevos cambios en el esquema antes de que los clientes dependan de ellos. De forma por lotes, el mismo sistema califica el esquema existente del 1 al 5; estas puntuaciones se recopilan en paneles de control por equipo, y un mecanismo de control integrado evita que la suma total aumente a medida que los umbrales se vuelven más estrictos con el tiempo. No se trata de una gobernanza completamente automatizada, ni está diseñado para serlo. Hace que la calidad de las API sea lo suficientemente visible como para que los equipos puedan tomar medidas al respecto, y proporciona al equipo de la plataforma un ciclo de retroalimentación para perfeccionar sus propias reglas a medida que el enfoque se extiende a más partes del esquema.

Lecturas relacionadas

• Servir Qwen3.8-27B en un RTX 3090 con vLLM y DFlash2 parcheados — Cómo una versión modificada de vLLM 0.28.0 con embeddings requantizados y la técnica DFlash2 permite ejecutar un modelo híbrido de 27 mil millones de parámetros en una tarjeta de 24 GB, y por qué los contextos largos ralentizan su funcionamiento.
• Construir un refinador y generador personal de promptes con archivos de Claude — Cómo transformar una conversación en Claude en una herramienta reutilizable de promptes que mejora los promptes débiles y desarrolla ideas preliminares en versiones básicas, avanzadas y expertas.