JSON validado: cómo un revisor de código habla con CI

Convertir un revisor de código en IA para que emita salida JSON validada es el paso que separa un asistente que "opina" de uno que un pipeline automático puede consumir sin intervención humana. Si trabajas con continuous integration y quieres que un agente decida si bloquea o deja pasar un pull request, aquí aprendes por qué la prosa no sirve y cómo estructurar cada hallazgo.

El problema es simple: un revisor que dice "me preocupa que en la línea 42 podría haber un problema de seguridad" está bien para leerlo tú, pero es inservible para un workflow que tiene que decidir solo. Esa ambigüedad de la prosa produce pasos intermitentes, a veces pasan, a veces no, y por razones que nadie controla.

Por qué la prosa rompe un workflow automático de revisión

Un continuous integration no puede consumir texto libre. Necesita afirmaciones binarias, reglas concretas, líneas directas. Y aquí viene lo interesante: la solución no es pedirle a la IA que "sea más clara", sino forzarla a emitir un veredicto estructurado.

La idea central es transformar cada hallazgo en un JSON validado contra un esquema. Cada hallazgo deja de ser una opinión y pasa a ser una afirmación verificable.

¿Por qué un revisor de código con IA debe devolver JSON en vez de texto? Porque un pipeline automático necesita decidir sin humanos si bloquea o deja pasar un PR. El texto libre es ambiguo y produce resultados intermitentes; el JSON validado es determinista.

Qué campos debe tener el esquema del revisor

Un esquema mínimo y potente para el revisor se construye con campos que tienen un propósito operativo, no decorativo [00:38]. Cada uno cumple una función dentro del flujo de decisión.

• ruleID: agrupa cada hallazgo por categoría.
• severity: le dice al continuous integration si debe bloquear o no.
• location: ancla el hallazgo a una línea, lo que ayuda a combatir alucinaciones.
• message: explica por qué importa ese hallazgo.
• suggestedFix: convierte el hallazgo en algo accionable con una corrección breve.

Ese location es clave porque al obligar al modelo a citar archivo y línea reales, reduces el riesgo de que invente problemas que no existen.

Qué valores permite cada categoría y severidad

El esquema no acepta cualquier texto. Los valores están cerrados según la rúbrica definida previamente [01:55].

• category permite: correctness, security, performance, style, documentation.
• severity permite: blocker, advisory, info.

Si una categoría no tiene un hallazgo claro, no se agrega. Y si no hay hallazgos en absoluto, el revisor devuelve una lista vacía. Nada de rellenar por rellenar.

Cómo se valida el JSON sin usar otra IA

Aquí está la decisión de diseño más importante: la validación se hace con código determinista, no con otra IA [01:05]. ¿Por qué? Porque si validaras con otro modelo, volverías a introducir ambigüedad justo en el paso donde necesitas certeza absoluta.

Si el JSON no cumple el esquema, el paso falla de manera limpia. Sin adivinanzas, sin "casi pasa".

¿Cómo se valida la salida JSON de un agente de IA? Con un script determinista que revisa estructura, campos obligatorios y valores permitidos. Si algo falta o no coincide, el paso falla con un mensaje claro en vez de dejar pasar datos corruptos.

El prompt del revisor se modifica para que su única salida sea ese JSON. Se conserva el contexto y la rúbrica de la versión anterior, pero cambia la salida: crear un archivo JSON cuyo nombre cubra el PR revisado y termine en .json, sin Markdown dentro del archivo y sin explicaciones fuera del JSON [02:30].

Cómo probar que el validador realmente atrapa errores

Un validador que nunca falla no sirve de nada. Por eso conviene probarlo con un caso que sepas que está roto.

1. Corre el script validate-review sobre un archivo correcto, como el que se generó para manual-refunds, y confirma que todo sale ok [04:00].
2. Corre el mismo script sobre un JSON manipulado a propósito, al que se le quitó el campo severity [04:30].
3. Verifica que el error aparezca con un mensaje claro indicando exactamente qué campo falta.

Ese segundo caso es el que da confianza real. El validador detecta que falta severity y lo reporta sin ambigüedad, lo que garantiza que no se cuele basura hasta el workflow.

¿Qué pasa si el JSON del revisor está incompleto? El script de validación lo detecta y falla con un mensaje que dice qué campo falta, por ejemplo severity. Así el pipeline nunca recibe datos malformados.

Con todo esto, el revisor ya emite veredictos que el continuous integration puede consumir. Puedes generar el script tú mismo o pedirle a Claude que te construya uno que verifique la estructura exacta [03:40].

Qué límite sigue teniendo este revisor estructurado

Hay una tensión que todavía queda abierta. Si sueltas este revisor tal cual sobre un PR grande, va a comentar de más [05:20]. Es el mismo revisor genérico para Python y para TypeScript, y no prioriza según el tipo de archivo.

Ese es el siguiente reto: enseñarle a rutear, es decir, a aplicar criterios distintos según qué está revisando. ¿Cómo crees que debería priorizar un revisor entre un archivo de Python y uno de TypeScript? Cuéntame en los comentarios.