Criterios explícitos en lugar de "sé conservador"

Un agente que revisa pull requests en CI marca casi todo. Al mes, el equipo resuelve los comentarios sin leerlos. El problema casi nunca es el modelo: es que el prompt le pide un juicio (“revisá que los comentarios sean correctos”, “marcá lo riesgoso”) sin decirle qué cuenta como hallazgo.

Qué es un criterio

Un criterio explícito (explicit criterion) describe algo observable y comprobable leyendo el código: un comportamiento, un patrón, una condición. “Usá tu criterio”, “sé exhaustivo” o “marcá lo riesgoso” son valores generales; cada ejecución los interpreta distinto.

Vago	Explícito
“Revisá que los comentarios sean correctos”	“Marcá un comentario solo cuando el comportamiento que describe contradice lo que hace el código”
“Marcá riesgos de SQL injection”	“Marcá solo cuando una entrada externa (request, archivo, otra fuente) llega a una consulta; salteá constantes y placeholders parametrizados”
“Reportá solo bugs reales”	“Reportá comportamientos que pueden romperse en ejecución; no estilo, nombres ni formato”

Un buen criterio dice las dos cosas: qué se marca y qué se saltea. La lista de exclusiones (patrones locales del equipo, estilo menor, casos ya protegidos antes en el camino) es lo que más baja los falsos positivos (false positives).

Por qué “sé conservador” no funciona

“Sé conservador” o “reportá solo hallazgos de alta confianza” no definen ninguna frontera. Y la confianza autoinformada (self-reported confidence) está mal calibrada: el modelo puede estar muy seguro de un hallazgo falso. Un umbral de 0,8 como único filtro no arregla nada. El orden correcto es primero criterios que decidan qué es un hallazgo, y recién después, si querés, la confianza para enrutar.

Tampoco ayudan las mayúsculas, repetir “NO reportes estilo” ni bajar la temperatura. Si el modelo sigue marcando estilo, sumá ejemplos de código que parece un problema de estilo y no se reporta, junto con el criterio de exclusión.

Los falsos positivos cuestan confianza

Una categoría ruidosa arrastra a las demás: si la mitad de los comentarios de “nombres de variables” son irrelevantes, los desarrolladores dejan de leer también los de seguridad. Por eso la guía propone desactivar temporalmente la categoría con más falsos positivos para recuperar la confianza mientras mejorás su prompt, y volver a activarla cuando las mediciones muestren que bajó el ruido. No es lo mismo que apagar categorías a ciegas ni que bajarles la severidad para que molesten menos: eso esconde los hallazgos reales y deja los falsos.

Severidad con ejemplos

Si “crítico”, “alto” y “menor” salen distintos en cada corrida, describir los niveles en prosa no alcanza. Lo que estabiliza la clasificación son criterios de severidad (severity criteria) con un ejemplo de código concreto por nivel y el motivo de su clasificación. El modelo compara contra casos, no interpreta adjetivos.

Lo mismo para que un hallazgo sea accionable: pedí archivo y línea, la condición que falla y un cambio concreto.

Medir el cambio

Para saber si el prompt nuevo mejoró, corré las dos versiones sobre un conjunto etiquetado (labelled set) de diffs pasados y compará la tasa de falsos positivos por categoría. Que “parezca” haber menos ruido en la semana siguiente no es evidencia.

Las trampas típicas

• “Sé cuidadoso”, “solo alta confianza” o un umbral de confianza como único filtro.
• Énfasis: mayúsculas, repetir la regla, temperatura 0.
• Bajar la severidad de la categoría ruidosa en vez de corregir su criterio.
• Una segunda pasada del modelo que repite el mismo juicio vago.

En el examen

El escenario suele ser Claude Code en CI con un equipo que ignora los comentarios. Buscá la opción que nombra patrones concretos para marcar y para saltear. Si la pregunta es de severidades inconsistentes, la respuesta es un ejemplo por nivel. Si es qué hacer ya con una categoría que destruye la confianza, desactivarla temporalmente mientras se mejora.