Revisión con instancias independientes y en varias pasadas

Claude Code genera un arreglo y, en la misma sesión, le pedís que lo revise. Dice que está bien. En producción aparece el bug. No es mala suerte: el revisor tenía en el contexto todo el razonamiento que lo llevó a esa solución.

Por qué falla la autorrevisión

En la autorrevisión (self-review), el modelo conserva el contexto de razonamiento de cuando generó el código. Las justificaciones que lo convencieron siguen ahí, así que es poco probable que cuestione sus propias decisiones. Pedirle “revisá críticamente” o darle más pensamiento extendido no cambia eso: sigue mirando con los mismos supuestos.

La instancia independiente

Una instancia independiente (independent review instance) es otra llamada a Claude, sin el historial del generador. Recibe:

• la salida (el diff o el código);
• los requisitos;
• criterios explícitos de revisión.

No recibe el razonamiento del generador ni veredictos anteriores. Así juzga la evidencia y no hereda la conclusión. En CI, el revisor es una ejecución separada de la que escribió el código.

Pasadas acotadas

Un PR de 40 archivos revisado en una sola pasada termina con hallazgos profundos en los primeros archivos y superficiales en los últimos, y a veces contradictorios entre sí. Es dilución de la atención (attention dilution). La revisión en varias pasadas (multi-pass review) la evita:

1. Una pasada por archivo para los problemas locales.
2. Una pasada de integración para el flujo de datos entre archivos, alimentada con resúmenes compactos de interfaces y llamadas, no con todo el código crudo. Es la que encuentra un cambio en una API pública que rompe a otro paquete.

(La lógica de dividir así está en la lección de descomposición de tareas.) Otra forma de acotar es por categoría: si una sola pasada tiene que cubrir seguridad, rendimiento y estilo, la atención se reparte y se escapa la categoría más difícil.

Verificar cada hallazgo

Una instancia revisora reporta 12 hallazgos y 5 son falsos. En lugar de esconder todo o publicar todo, agregá una pasada de verificación (verification pass):

• una instancia por hallazgo recibe el hallazgo, el código y los criterios, y lo confirma o lo rechaza;
• se publica solo lo confirmado y se registra lo rechazado, para auditar qué se descartó sin perder cobertura de seguridad;
• el verificador necesita criterios explícitos, no “¿es un bug real?”: así dos hallazgos parecidos reciben el mismo veredicto en cada corrida.

La guía suma una variante: que el modelo informe su confianza junto a cada hallazgo para enrutar la revisión (lo dudoso a una persona, lo claro directo). Esa confianza sirve para enrutar, no para decidir qué es un hallazgo; eso lo deciden los criterios.

Si dos instancias reportan el mismo bug con distintas palabras, deduplicá en código por ubicación y tipo de problema. Si dos instancias con criterios distintos no coinciden, el desacuerdo va al verificador y se registra.

Las trampas típicas

• “Revisá tu propio código con cuidado” en la misma sesión.
• Pasarle al revisor el razonamiento del generador “para que tenga contexto”.
• Una sola pasada gigante sobre todo el PR, o una ventana de contexto más grande como solución.
• Pasadas por archivo sin una pasada de integración, que no ven los fallos entre archivos.

En el examen

Si el revisor y el generador comparten sesión, la respuesta es una instancia separada sin ese contexto. Si la calidad cae en los últimos archivos, pasadas por archivo más integración. Si el problema son falsos positivos sin perder recall, verificación por hallazgo con criterios explícitos.