Política de calibración: matriz de confusión por categoría

Cuando quieres que un revisor con IA deje de dar veredictos sueltos y pase a guiar decisiones reales, necesitas una política de calibración. Esta guía te muestra cómo consolidar tu sistema de calidad con IA en un documento accionable usando una matriz de confusión por categoría, ideal para equipos de desarrollo que ya integran IA en sus revisiones de código.

El proyecto de ejemplo es payments-svc, una API de pagos en Python que ya tiene pruebas, prompts de revisión, historial de regresión, reglas de seguridad y un workflow de AI Review en GitHub Actions. Lo que falta es la pieza que convierte todos esos datos en instrucciones claras para el equipo.

¿Por qué un sistema de IA no está completo sin una política?

Un revisor que emite veredictos no le dice a nadie qué hacer con ellos. Y aquí viene lo interesante: sin una política, cada persona interpreta el output de la IA por sensación.

La idea es simple. Recopilas todo lo que construiste a lo largo del proyecto y lo transformas en decisiones operativas: cuándo autoaprobar, cuándo dejar la IA como consultiva, cuándo exigir revisión humana y cuándo declarar zonas donde la IA no participa [00:29].

¿Qué es una política de calibración de IA? Es un documento que convierte la evidencia del revisor con IA en decisiones operativas para el equipo. Define cuándo confiar en la IA, cuándo pedir humano y qué zonas quedan fuera del alcance de la IA.

El entregable final se llama calibration-policy.md. No es un apunte teórico: se revisa y se ejecuta cada vez que levantas un pull request, y el resultado aparece en el summary del pipeline [02:13].

¿Cómo funciona la matriz de confusión por categoría?

La base de todo es cruzar el output de la IA contra la verdad. La gracia está en que cada categoría de la rúbrica tiene su propia matriz, porque el costo de cada error cambia según el contexto [00:52].

En pagos, dejar pasar una inyección SQL es gravísimo, pero un falso positivo de estilo solo molesta. Esa diferencia de costo es la que define las acciones.

La matriz de confusión cruza cuatro escenarios:

• Verdadero positivo: hay un problema y la IA lo detectó. Es un acierto.
• Falso negativo: hay un problema y la IA dijo que no. Se perdió un bug.
• Falso positivo: no hay problema y la IA lo marcó. Genera ruido.
• Verdadero negativo: no hay problema y la IA confirmó que está limpio. Es un acierto.

Con estos cuatro cuadrantes por categoría dejas de confiar en la IA por sensación y empiezas a confiar con números concretos [01:38].

¿Qué es un falso negativo en revisión de código con IA? Es cuando existe un problema real pero la IA dice que no hay nada. En un contexto de pagos, un falso negativo puede significar dejar pasar una vulnerabilidad crítica.

¿Cómo generar el archivo calibration-policy.md con un prompt?

El truco es usar un prompt que se apoye en todos los archivos que ya construiste. Le pides a la IA que actúe como responsable de gobierno de calidad en el repositorio y que use como insumos las pruebas, prompts de revisión, historial de regresión, reglas de seguridad y el workflow existente [03:08].

El prompt exige que la política incluya secciones específicas:

1. La matriz de confianza con verdaderos positivos, falsos positivos, falsos negativos y verdaderos negativos por categoría.
2. Decisiones y acciones por categoría.
3. Zonas no IA.
4. Protocolo de override.

Un detalle clave: los ejemplos que devuelve la IA en el formato deben reemplazarse con los datos reales de los otros archivos del proyecto [04:24]. Si falta evidencia, la política debe declararlo como una limitación explícita [04:03].

¿Qué pasa cuando se ejecuta en un pull request?

Cuando corres un PR, la política se ejecuta y entrega un resumen real en Actions. Ahí ves qué secciones validó y cuáles entran como categorías en la matriz de confianza [05:11].

Por ejemplo, un caso de security injection aparece como verdadero positivo, bloqueante con evidencia, porque todavía no se ha resuelto ni pasado a regresión. Cada vez que alimentas el histórico, la matriz crece [05:32].

Si agregas una herramienta nueva como Sonar además de Semgrep, debes sumarla tanto al calibration como al prompt que genera las revisiones [05:50]. La calibración se vuelve más alineada con el tiempo: más verdaderos positivos, más verdaderos negativos y menos zona gris.

¿Cómo asigna acciones la política según el costo del error?

Aquí es donde la matriz se conecta con el impuesto de alucinación, que se mide por lenguaje y por codebase [07:00]. Con ese cruce, la política reparte acciones concretas.

• Autoaprobar donde los falsos negativos son raros y baratos.
• Exigir intervención humana donde esos errores son caros.
• Declarar zonas completas de no IA: cripto, el core de pagos y contextos regulatorios, donde la decisión humana es obligatoria.

Con esto, la calibración pasa de ser una opinión a ser una política. El equipo ve en vivo si el producto pasa pruebas, si el historial de regresión está consistente y si la matriz quedó bien escrita, sin adivinar la información de otros archivos [06:23].

¿Qué son las zonas no IA? Son áreas donde la decisión humana es obligatoria y la IA no aprueba nada por sí sola: cripto, el core de pagos y contextos regulatorios. Ahí el riesgo es demasiado alto para delegar.

¿Qué habilidades ganaste al construir este sistema?

Al inicio le pedías a la IA que escribiera tests o revisara un PR, y te devolvía basura verde y comentarios cosméticos [07:37]. Hoy payments-svc tiene un sistema completo, medido, gobernado y con una política escrita.

Lo que de verdad cambió no está en el repo, está en ti. Pasaste de consumidor a editor [08:00]. Aprendiste tres ideas que sostienen todo:

• La IA abarata producir, pero no transfiere la responsabilidad.
• Su confianza se mide categoría por categoría, con números.
• Las taxonomías estables son tu seguro cuando las herramientas cambian.

La premisa con la que abrimos sigue siendo la misma, pero ahora ganada: la IA acelera tu criterio, pero no lo reemplaza. Es tu deber leer la política y verificar que se ajusta a lo que construyes cada vez que levantas un cambio.

¿Tú cómo definirías el costo de un falso negativo en tu propio proyecto? Cuéntame en los comentarios.