Phase 14 - Lesson 39

Agente Revisor: Separe el Constructor del Evaluador

El agente que escribió el código no puede calificarlo. Un revisor es un segundo bucle con un prompt de sistema diferente, un objetivo diferente y acceso de solo lectura a todo lo que el constructor produjo. La brecha entre el constructor y el revisor es donde reside la mayor parte de la confiabilidad.

Type: Build Languages: Python (stdlib) Prerequisites: Phase 14 · 38 (Verification Gate) Time: ~55 minutes

Learning Objectives

Explicar por qué el mismo agente no puede revisar su propio trabajo de manera confiable.
Construir un bucle de agente revisor que consuma artefactos del constructor y emita un informe de revisión estructurado.
Diseñar una rúbrica de revisor que califique dimensiones específicas, no impresiones generales.
Conectar al revisor con el banco de trabajo (workbench) para que el paso de revisión humana comience a partir de un artefacto real.

The Problem

Le pides al agente que corrija un error. Edita cuatro archivos, ejecuta las pruebas e informa que terminó. El gate de verificación (Phase 14 · 38) confirma que se ejecutó la aceptación y se mantuvo el alcance. El gate dice passed: true. Haces el merge. Dos días después, descubres que la solución resolvió la mitad equivocada del error.

La aceptación es necesaria, pero no suficiente. El revisor hace las preguntas que la aceptación no puede hacer: ¿resolvió esto el problema correcto? ¿Se amplió el alcance sin señalarlo? ¿Se documentaron suposiciones que debieron cuestionarse? ¿Se dejó el banco de trabajo en un estado del que la próxima sesión pueda continuar?

The Concept

flowchart LR
  Builder[Agente Constructor] --> Artifacts[diff + state + feedback + verdict]
  Artifacts --> Reviewer[Agente Revisor]
  Reviewer --> Rubric[reviewer_checklist.md]
  Reviewer --> Report[review_report.json]
  Report --> Human[Aprobación Humana]

Reviewer rubric

Cinco dimensiones, cada una calificada de 0 a 2.

Dimensión	Pregunta
Ajuste al problema	¿Resolvió el cambio la tarea tal como fue establecida y no una tarea cercana?
Disciplina de alcance	¿Se limitaron las ediciones al contrato o se amplió el contrato deliberadamente?
Suposiciones	¿Están todas las suposiciones ocultas escritas en algún lugar revisable?
Calidad de verificación	¿El comando de aceptación realmente demuestra el objetivo, o demostró una versión más débil?
Preparación para el traspaso	¿Podría la próxima sesión continuar limpiamente desde el estado actual?

Total de 10 puntos. Una ejecución por debajo de 7 es un soft fail; una ejecución por debajo de 5 es un hard fail.

The reviewer is a separate role, not a separate model

Puedes ejecutar el revisor con el mismo modelo que el constructor. La disciplina es la separación de roles: diferente prompt de sistema, diferentes entradas, sin acceso de escritura al diff. El cambio de postura es el cambio en la señal.

The reviewer cannot edit the diff

El revisor lee el diff, el estado, el feedback y el veredicto. Escribe un informe. No aplica un parche (patch) al diff. Si el informe dice "corrige esto", el siguiente turno del constructor realiza la corrección; el revisor vuelve a revisar. Mezclar roles destruye el distanciamiento necesario.

Reviewer rubric versus verification gate

El gate (Phase 14 · 38) verifica hechos deterministas: si se ejecutó la aceptación, si pasaron las pruebas, si se mantuvo el alcance. El revisor hace juicios cualitativos: si este fue el trabajo correcto, si está documentado, si el traspaso es utilizable. Ambos son necesarios.

Build It

code/main.py implementa:

Una dataclass ReviewerInputs que agrupa los artefactos que lee el revisor.
Un calificador de rúbrica con una función por dimensión. Cada función es determinista y simplificada (stub-grade) para la lección; las implementaciones reales llamarían a un LLM.
Un escritor de review_report.json con las opiniones y cinco puntuaciones, el total y un veredicto (pass, soft_fail, hard_fail).
Dos casos de demostración: un cambio limpio y un cambio del tipo "pruebas correctas, problema equivocado".

Ejecútalo:

python3 code/main.py

Salida: dos informes de revisión escritos en el disco y una tabla en la consola con las puntuaciones de cada dimensión.

Patrones de producción en el mundo real

Los datos reales: El sistema de AI Code Review de Cloudflare en abril de 2026 ejecutó 131,246 análisis en 48,095 merge requests en 5,169 repositorios en 30 dias. La revisión mediana se completó en 3 minutos y 39 segundos. Hasta siete revisores especialistas (seguridad, rendimiento, calidad del código, documentación, gestión de lanzamientos, cumplimiento, Engineering Codex) se ejecutaron en paralelo bajo un Review Coordinator que deduplicó los hallazgos y evaluó la gravedad. El modelo de primer nivel se reservó exclusivamente para el coordinador; los especialistas se ejecutaron en niveles más baratos.

Cuatro patrones hacen que esto funcione a escala.

Pool de especialistas, no un único gran revisor. Un revisor con una rúbrica de 5 dimensiones funciona para repositorios individuales. Una vez que la base de código tiene superficies críticas de seguridad, críticas de rendimiento y de documentación, divídela en especialistas con prompts más pequeños. El coordinador se encarga de la deduplicación; los especialistas nunca ejecutan la rúbrica completa. La separación por niveles de modelo surge de forma natural: especialistas baratos, coordinador caro.

Mitigación de sesgo como requisito de diseño, no optimización. Los jueces de LLM muestran cuatro sesgos confiables (Adnan Masood, abril de 2026): sesgo de posición (GPT-4 ~~40% inconsistente en el orden (A,B) vs (B,A)), sesgo de verbosidad (~~15% de inflación en la puntuación hacia salidas más largas), autopreferencia (los jueces prefieren salidas de la misma familia de modelos), autoridad (los jueces sobrevaloran las referencias a autores conocidos). Mitigaciones: evaluar ambos órdenes y contar solo victorias consistentes; usar escalas de 1 a 4 que recompensen explícitamente la concisión; rotar jueces entre familias de modelos; eliminar los nombres de los autores antes de calificar.

Conjunto de calibración, no impresiones vagas. Un conjunto histórico de 10 a 20 tareas con veredictos correctos conocidos. Ejecuta el revisor sobre él con cada cambio de prompt. Si la concordancia con el registro histórico cae por debajo del 80%, la rúbrica necesita revisión antes de enviar el revisor. Esto es lo que todos los equipos terminan redescubriendo; es mejor comenzar con ello.

Norma híbrida con el gate. El gate de verificación (Phase 14 · 38) maneja las verificaciones deterministas (si se ejecutó la aceptación, si pasaron las pruebas, si se mantuvo el alcance). El revisor maneja las verificaciones semánticas (si este fue el trabajo correcto, si las suposiciones están documentadas, si el traspaso es utilizable). Las pautas de Anthropic para 2026 son explícitas sobre esta división: no le pidas al revisor que rehaga lo que el gate ya demuestra.

Use It

Patrones de producción:

Subagentes de Claude Code. Un subagent revisor se ejecuta después de que el constructor cierra una tarea. Publica un comentario en el PR con las puntuaciones de la rúbrica.
Traspasos (handoffs) de OpenAI Agents SDK. El constructor traspasa la tarea al Revisor al completarse. El Revisor puede devolverla con una lista de hallazgos o escalarla a un humano.
Emparejamiento de dos modelos. El constructor se ejecuta en un modelo más rápido y barato. El revisor se ejecuta en un modelo más fuerte con un contexto más pequeño, enfocado en el juicio.

El revisor es el segundo par de ojos que el banco de trabajo desarrolla cuando los humanos no pueden realizar cada revisión por si mismos.

Ship It

outputs/skill-reviewer-agent.md genera una rúbrica de revisor específica del proyecto, un boceto (stub) de agente revisor conectado a los artefactos del constructor y una integración con el gate de verificación para que la revisión humana comience a partir de un informe escrito en lugar de una página en blanco.

Exercises

Agrega una sexta dimensión específica para el dominio de tu producto. Defiende por qué no es absorbida por las cinco existentes.
Ejecuta el revisor con dos prompts de sistema diferentes (conciso, detallado). ¿Cuál produce un informe que un humano tenga más probabilidades de leer?
Agrega un campo confidence por dimensión. Niégate a enviar el informe cuando la confianza en la dimensión más baja sea inferior a 0.6.
Construye un conjunto de calibración: 10 cierres de tareas históricas con veredictos correctos conocidos. Ejecuta el revisor sobre ellos. ¿Dónde discrepa del registro histórico?
Agrega una opción para "solicitar más evidencia": el revisor puede pedirle al constructor una ejecución de prueba específica antes de calificar. ¿Cuál es el retroceso (back-off) correcto para que esto no entre en bucle?

Key Terms

Término	Lo que dice la gente	Lo que realmente significa
Rúbrica del revisor	"Checklist"	Calificación de 0 a 2 en cinco dimensiones con una pregunta escrita por dimensión
Soft fail	"Necesita revisiones"	Total inferior a 7; el constructor recibe los hallazgos para abordar
Hard fail	"Rechazar"	Total inferior a 5 o cualquier dimensión en 0; detener y escalar a un humano
Separación de roles	"Prompt diferente"	El mismo modelo puede tener ambos roles; la disciplina reside en las entradas y la postura
Piso de confianza	"No enviar informes de baja señal"	Negarse a emitir un veredicto cuando la rúbrica sea incierta