Criterios de gravedad con ejemplos

Cuando pide a Claude que revise código, la instrucción más débil que puede darle es una indicación vaga: be more precise o only flag important issues. El modelo no tiene una definición compartida de "importante", por lo que su criterio varía de un archivo a otro.

El principio del examen es claro: los criterios explícitos son mejores que los adjetivos vagos. Una escala de severidad (Critical / High / Medium / Low) solo resulta útil si cada nivel tiene una regla escrita que el modelo pueda aplicar de forma coherente; y la manera más fiable de concretar una regla es anclarla con un ejemplo de código concreto.

En esta lección creará una rúbrica de severidad para un agente de revisión de CI/CD, nivel por nivel, vinculando cada uno a un ejemplo.

Este es el tipo de prompt que parece correcto, pero funciona mal. Menciona niveles de severidad, pero nunca los define, así que el modelo adivina, y sus respuestas cambian en cada ejecución.

El resultado es exactamente el antipatrón que advierte el examen: revisiones ruidosas en las que tanto la ausencia de una comprobación de null como un comentario con errores ortográficos reciben la etiqueta "High". Los revisores dejan de confiar en las etiquetas.

La solución es estructural. Para cada nivel de severidad, proporcione al modelo dos elementos:

• Una regla: una condición comprobable ("causa pérdida de datos, una vulneración de seguridad o un fallo en producción").
• Un ejemplo de referencia: un fragmento breve que pertenezca inequívocamente a ese nivel.

Esto es prompting few-shot aplicado a una rúbrica: 2-4 ejemplos específicos por cada ambigüedad. El modelo generaliza a partir de los ejemplos de referencia; no se limita a repetirlos, por lo que unos pocos ejemplos bien elegidos calibran toda la escala.

Critical se reserva para problemas que causan pérdida de datos, una vulneración de seguridad o un fallo en producción. Ancle el nivel con algo indiscutible; en este caso, la interpolación directa de cadenas en SQL.

Observe que el ejemplo de referencia cumple una doble función: define el límite superior de la escala, para que el modelo sepa que nada menos grave debe alcanzar este nivel.

High abarca comportamientos incorrectos que no hacen que el proceso falle, pero producen resultados erróneos: un error lógico, un caso límite defectuoso o un error de uno. El ejemplo de referencia concreta el límite con Critical: no hay vulneración ni fallo, pero el resultado es incorrecto.

El extremo inferior de la escala es donde los prompts vagos generan más falsos positivos, así que debe anclarse con el mismo cuidado.

• Medium: riesgo de mantenibilidad o fiabilidad que todavía no es un error (por ejemplo, la falta de un tiempo de espera o una ruta de error no gestionada, pero poco frecuente).
• Low: solo estilo y nombres; sin impacto en el comportamiento.

Definir Low explícitamente es lo que le permitirá decir más adelante "no informe de problemas Low en las comprobaciones previas a la combinación" sin que el modelo lo cuestione.

Los niveles anclados se convierten en un bloque del system prompt. Mantenga este bloque estable y al principio: es el mismo para todos los archivos que revise, lo que lo convierte en un prefijo ideal para la caché de prompts. El diff de cada archivo debe ir en el turno del usuario, después de la rúbrica almacenada en caché.

Una rúbrica escrita indica al modelo cómo decidir; la salida estructurada garantiza la forma de la respuesta. Vincule la severidad a un enum de JSON Schema para que el campo nunca pueda ser un adjetivo de texto libre como "prettyBad".

Recuerde esta regla del examen: marque un campo como required solo si está presente siempre. severity y line siempre existen en un hallazgo real, por lo que son obligatorios; un suggested_fix opcional no lo es.

Ahora combine la rúbrica almacenada en caché y anclada con el esquema restringido mediante enum en una sola solicitud. El diff es la única parte volátil, por lo que se coloca al final del turno del usuario.

Esta combinación —criterios explícitos para la decisión y salida estructurada para el formato— es el patrón recomendado por el examen para realizar extracciones y clasificaciones fiables.

Una vez que la severidad es un enum limpio, la decisión de bloquear una combinación la toma código determinista, no el criterio del modelo. El modelo clasifica; su pipeline aplica los umbrales.

Esto refleja el principio de hooks del examen: cuando un fallo tiene consecuencias reales (una combinación defectuosa), aplíquelo mediante código determinista, no mediante un prompt probabilístico. La rúbrica hace que las etiquetas del modelo sean lo bastante fiables como para usarlas en el bloqueo.

Existe una trampa sutil: decirle al modelo en la fase de hallazgos que "solo informe de Critical y High" reduce la exhaustividad; descarta silenciosamente los problemas que considera de menor nivel y usted pierde cobertura que podría haber necesitado.

El patrón sólido es hacer que el modelo informe de todos los hallazgos con su severidad y filtrar después en un paso independiente (su conjunto BLOCKING o una revisión independiente). Primero la cobertura; después la clasificación. Los criterios anclados son los que hacen fiable esa clasificación posterior.

Conclusiones clave:

• Los adjetivos vagos varían; las reglas escritas no. Sustituya "importante" por una condición comprobable para cada nivel de severidad.
• Ancle cada nivel con un ejemplo de código. Entre 2 y 4 ejemplos few-shot específicos calibran la escala; el modelo generaliza a partir de ellos.
• Fije la etiqueta con un enum. La salida estructurada garantiza que severity siempre sea uno de los valores válidos; exija solo los campos que siempre están presentes.
• Almacene la rúbrica en caché y varíe el diff. Mantenga los criterios estables al principio del system prompt y coloque el código de cada archivo al final.
• Clasifique en el modelo y bloquee mediante código. Informe de todos los hallazgos con su severidad y, después, filtre o bloquee de forma determinista; nunca filtre por su cuenta durante la fase de hallazgos.