Code review que demuestra cada bug que marca, con benchmark

Le pides a una IA que revise tu PR y te entrega un checklist impecable: inyección revisada, secretos revisados, autenticación revisada, todo bien. Suena a diligencia. Que realmente haya encontrado algo es otra cuestión — y el checklist es precisamente lo que oculta el fallo. Dirigimos un directorio que testea skills de Claude con benchmarks para ganarnos la vida, y cuando apuntamos nuestro propio benchmark a una skill de review que ya habíamos calificado como aprobada, pasó por alto un secreto hardcodeado que el baseline sin guía sí detectó. La lista no tenía una línea para ese punto, así que la revisora nunca miró ahí.

Ese fallo es la razón por la que existe review-discipline, y por la que va ya en su segunda versión. Es gratis y tiene licencia MIT: github.com/Skillproofdev/review-discipline. Cada hallazgo que reporta tiene que nombrar una entrada concreta que llegue al código y produzca un resultado incorrecto — o se degrada a [suspicion], nunca se afirma como hecho. En nuestro bench de bugs sembrados detecta 18.5 de 21 bugs plantados con cero falsos positivos y una ruta de fallo demostrada en el ~100% de los hallazgos.

La brecha: toda skill de review es un checklist, y los checklists generan visión de túnel

Antes de escribir una sola línea, revisamos 321 skills de review rastreadas más el terreno independiente — incluido el propio plugin de code-review de Anthropic. Tres mecánicas no aparecían en ninguna de ellas como reglas exigibles de un solo agente. Las tres se remontan al mismo fallo que vimos ocurrir en nuestro bench.

Un checklist le dice al revisor qué buscar. Eso también es una lista de lo que va a pasar por alto. Cuando las categorías no incluyen el bug, el bug sobrevive — y peor aún, la review sigue saliendo en verde, porque se marcó cada casilla que existía. Una review falla de dos formas: reportar suposiciones no demostradas como hechos (ruido) y saltarse en silencio un bug real porque es pequeño o porque uno más aparatoso absorbió toda la atención (cobertura perdida). Un checklist está estructuralmente diseñado para producir ambas cosas.

El plugin de Anthropic combate la mitad del ruido con agentes evaluadores en paralelo que votan un número de confianza. Es un mecanismo real, pero necesita varios agentes y no aborda la mitad de la cobertura en absoluto. Nadie ofrece lo que invierte la forma del checklist: cazar todo antes de recurrir a cualquier lista de categorías, demostrar o etiquetar cada hallazgo después, y descartar solo lo que realmente puedas refutar — en un solo agente, en un solo archivo instalable.

Ocho reglas, tres que nadie más exige

La skill es un conjunto de reglas exigibles (SKILL.md completo). Las partes conocidas están ahí: severidad P0–P3 con definiciones reales en vez de intuición, disciplina de alcance del diff (revisar el cambio, no todo el repo), avisos de tests faltantes ligados al comportamiento modificado, y cero relleno de elogios. Las partes que nadie más exige:

1. Sin ruta de fallo demostrada, no hay hallazgo. Cada hallazgo debe nombrar una entrada o estado concreto que llegue al código marcado y produzca un resultado incorrecto. ¿No puedes construir uno? Se envía como [suspicion], por debajo de cualquier hallazgo probado — nunca como hecho. Una afirmación no demostrada presentada como bug es la única salida prohibida de la skill.
2. Dos pasadas, caza abierta primero. Lee el cambio como una atacante sin ninguna lista de categorías en la mano y anota cada anomalía — sin umbral de severidad, algo que solo huele ligeramente raro también se apunta. Solo después recorre el checklist estándar (secretos, inyección, límites, aritmética, concurrencia…) por si la caza abierta se dejó algo. Cada competidor es el checklist; aquí va en segundo lugar, a propósito.
3. Mata tu propio hallazgo antes de reportarlo. Un intento honesto de refutación por hallazgo — protecciones previas, comportamiento intencional, cobertura de tests ya existente, alcanzabilidad — y el reporte dice qué se comprobó. La refutación es el único filtro autorizado para descartar un hallazgo; "no me molesté en demostrarlo" se convierte en [suspicion], no en un descarte silencioso. Los hallazgos que de verdad mueren, mueren en silencio.

La regla que sostiene todo es el orden: amplitud antes que profundidad. Recopila cada anomalía sin umbral de severidad antes de verificar ninguna, para que el análisis profundo de un bug nunca pueda truncar la caza del resto. Suena obvio. También es exactamente la regla que le faltaba a nuestra primera versión — y la razón por la que perdió.

El benchmark honesto (con resultados negativos incluidos)

Protocolo de bugs sembrados: muestras de código real (~200–400 líneas cada una, TypeScript / Python / JS) con bugs documentados de severidad conocida — lógica, seguridad, casos límite, concurrencia — con el ground truth fijado antes de cualquier ejecución. Cada muestra conserva código real e intacto para medir falsos positivos. Mismos prompts, mismo modelo; la única variable es si la agente lee el SKILL.md primero. Metodología completa: skillproof.dev/methodology.

4 muestras, 21 bugs sembrados, 12 trampas de falso positivo intencionalmente sanas. La columna interesante no es base contra skill — es v1 contra v2, porque nuestro propio bench fue lo que forzó la reconstrucción.

Métrica	Base (sin skill)	Skill v1	Skill v2
Bugs sembrados detectados (de 21)	17.0 (81%)	16.5 (79%)	18.5 (88%)
Detección de P0 (explotable / pérdida de datos)	3/3	3/3	3/3
Detección de P1 (comportamiento incorrecto, ruta realista)	7/7	7/7	7/7
Detección de P2 (casos límite / rutas aritméticas)	6/7	4/7	7/7
Sonda de secreto hardcodeado	detectado	detectado	detectado
Tasa de falsos positivos	5.6% (1 FP)	0%	0%
Hallazgos con ruta de fallo demostrada	~63%	~100%	~100%
Rebajas a [suspicion] (matices honestos)	0	3	5
Líneas de elogio / relleno	presentes	ninguna	ninguna

Fíjate en la columna del medio y verás el fallo que le dio nombre a esta skill. v1 obtuvo 16.5 — por debajo del 17 del baseline sin guía. Tenía la disciplina de ruta de fallo (bajó los falsos positivos a cero y demostró ~100% de sus hallazgos), pero era peor encontrando bugs, porque se fijó en los P0 llamativos de una muestra y nunca recorrió las líneas silenciosas de redondeo de dinero. Tuvo visión de túnel. Lo detectó nuestro propio bench público de una skill que habíamos calificado como aprobada: v1 se dejó dos P2 reales — un error lógico de prorate /30 y un truncamiento de int(amount × 100) — que el baseline captó solo con leer de forma lineal.

La solución fue la regla de amplitud-antes-que-profundidad. v2 recopila cada anomalía sin umbral de severidad antes de verificar ninguna. Resultado: P2 pasó de 4/7 a un limpio 7/7 (incluso recuperó un StopIteration de CSV vacío que tanto base como v1 se habían dejado), el recall total subió a 18.5 — superando el 17 de base — y la disciplina se mantuvo: sigue en cero falsos positivos, sigue con ~100% de rutas demostradas, y con más matices honestos de [suspicion] (5 contra 3) en vez de menos. La adjudicación completa a tres bandas está en bench/results/verdict.md.

El bench también acabó, sin rodeos, con un mito: la hipótesis de visión de túnel del checklist sobre secretos que motivó todo el proyecto no se reprodujo en la ejecución sembrada — los tres brazos detectaron la sonda de secreto hardcodeado (S4-B1). El fallo original fue real y es lo que nos enseñó la forma del problema; el bench sembrado solo mostró que el secreto en sí no es donde la amplitud da sus frutos. Los casos límite de redondeo de dinero sí lo son. Reportamos el mecanismo que de verdad movió los números, no el que daba la mejor historia de origen.

Dónde perdió v2 — publicado de todas formas

Nuestra metodología exige mostrar las derrotas junto a las victorias. v2 es el mejor brazo en todo lo que bloquea un merge, pero no es un superconjunto estricto de v1, y no vamos a fingir lo contrario.

Persiguiendo la amplitud exhaustiva, v2 dejó de profundizar en una función (_parse_tags) y pasó por alto una sospecha sutil de anidamiento profundo en literal_eval (S2-B5) que la pasada en profundidad de v1 había captado en solitario. Así que en el eje de P3 / fuera-de-checklist, v2 en realidad retrocedió — del 2.5/4 de v1 a 1.5/4. En conjunto es un buen intercambio (+2 medios por −1 P3 sutil), pero es un retroceso real en ese eje concreto, no un dominio limpio. La revisora ideal sería la amplitud de v2 más la disposición de v1 a seguir profundizando un nivel más en código que parece tranquilo — y preferimos decírtelo así antes que redondearlo.

También hay un bug que ningún brazo detectó: un empate estricto de < en la caducidad de un cupón (S1-B6), que se les escapó por igual a base, v1 y v2. La skill reduce los fallos; no vuelve infalible a Claude.

Instalación

git clone https://github.com/Skillproofdev/review-discipline ~/.claude/skills/review-discipline

Reinicia Claude Code. Un solo comando — el repo es la skill. Se activa con "revisa este PR/diff", "comprueba esto antes de hacer merge", "busca bugs en" y las comprobaciones previas al merge — y se mantiene al margen cuando escribes funcionalidades nuevas, en el linting puramente de estilo o en la revisión de prosa. Se suma a nuestra serie de disciplina: token-discipline recorta lo que cuesta un agente, research-discipline recorta lo que se equivoca en los hechos, y esta recorta lo que a una review se le escapa.

Preguntas frecuentes

¿En qué se diferencia del plugin de code-review de Anthropic? El plugin filtra falsos positivos haciendo que agentes evaluadores en paralelo voten un número de confianza — efectivo, pero necesita varios agentes y solo aborda el problema del ruido. review-discipline filtra con una ruta de fallo demostrada en un solo agente, en un solo archivo instalable, y además ataca el problema de cobertura que el plugin no toca: la regla de caza-abierta-antes-que-checklist que elevó nuestro propio recall de P2 de 4/7 a 7/7.

¿"Demostrar cada hallazgo" no hará que se le escapen cosas que no puede demostrar? No — para eso existe el mecanismo [suspicion]. Un bug real para el que no puedas construir una ruta de fallo (necesita un estado en tiempo de ejecución que no puedes ver, o un sistema externo) igualmente se reporta, marcado como [suspicion] y por debajo de los hallazgos confirmados, con una línea sobre qué falta. La herramienta es rebajar la confianza; descartar no lo es. En el bench, v2 emitió 5 de estos matices honestos en vez de tragárselos.

¿Revisa todo el repositorio o solo mi diff? Solo el cambio. Los hallazgos deben estar causados o activados por este diff; los problemas preexistentes van en una breve nota de fuera de alcance, no en la lista clasificada. La única excepción es un P0 preexistente — un secreto en vivo o una vulnerabilidad activa — que siempre se marca de forma destacada. Esa excepción existe precisamente por el fallo que dio origen a todo esto.

¿18.5/21 es suficiente para saltarse la revisión humana? No. Detecta todos los bloqueadores de merge P0 y P1 de nuestro bench y supera al baseline sin guía en recall total con cero falsos positivos — lo que la convierte en una primera revisora sólida que nunca aprueba por inercia y siempre nombra lo que atacó. Pero se dejó un bug sembrado por completo y sacrificó un P3 sutil a cambio de amplitud, ambas cosas documentadas arriba. Úsala para asegurarte de que los bugs obvios y los de aritmética silenciosa no lleguen a una persona; deja a la persona para el último nivel de profundidad.