🔍 Revisa más allá del diff
Un agente revisor puede explorar archivos relacionados, verificar contratos, analizar pruebas, encontrar duplicaciones, identificar riesgos, comparar con los patrones del repositorio, revisar la arquitectura, buscar fallas de seguridad, evaluar el rendimiento y verificar la compatibilidad. El diff es el punto de partida, no el límite.
🎯 Qué debe evaluar la revisión de código
🆕 ¿Nuevo por aquí?
Diff es el conjunto de líneas agregadas y eliminadas por un cambio. Duplicación semántica es cuando dos partes del sistema hacen lo mismo, escrito de formas diferentes: invisible para la búsqueda de texto, pero detectable por un agente que lee el repositorio. Adherencia al alcance es comprobar si el cambio hizo solo lo que se pidió.
Contexto
Todo el repo, si hace falta
Contrato
Quien lo consume no puede verse afectado
Duplicación
Semántica, no textual
Alcance
¿Hizo solo lo que se pidió?
👥 Separa al implementador del revisor
El agente que revisa no debe depender totalmente de las conclusiones del agente que implementó. La separación reduce el riesgo de que ambos repitan la misma suposición incorrecta — y es la diferencia entre una revisión de verdad y un segundo sello.
Cómo leer: a la izquierda, la flecha vuelve al mismo agente: revisa con el razonamiento que produjo el error. A la derecha, el revisor recibe solo especificación + diff, sin el historial del autor: eso es lo que le permite discrepar.
🧪 Ejercicio copiable — revisor independiente
Objetivo: hacer una revisión real de un cambio tuyo. Abre un sesión nueva del agente (contexto limpio, sin el historial de la implementación) y pega:
Você é o revisor independente. Não implementou nada disto e não deve confiar em nenhuma afirmação de quem implementou. Especificação da tarefa: <cole a spec> Diff a revisar: <cole a saída de: git diff origin/main...HEAD> Revise nesta ordem e leia os arquivos relacionados antes de concluir: 1. a mudança cumpre a spec? o que ficou faltando? 2. algo FORA do escopo foi alterado? 3. algum contrato/comportamento existente muda para quem consome? 4. o tratamento de erro cobre timeout, duplicidade e permissão negada? 5. existe duplicação semântica com algo que já existe no repositório? 6. os testes provam o comportamento novo ou só executam o código? Formato da resposta: lista de achados, cada um com [severidade: bloqueante | importante | menor] · arquivo:linha · por que é problema · como verificar. No máximo 7 achados — priorize. Se não houver bloqueante, diga isso explicitamente.
Cómo verificar: toma cada hallazgo «bloqueante» e intenta reproducirlo. Si dos de tres no se sostienen, tu revisor está generando ruido: ajusta el prompt (menos hallazgos, más evidencia exigida) antes de incorporarlo al flujo del equipo.
Contexto limpio
Sesión nueva, siempre
Spec + diff
No es el razonamiento del autor
Severidad
Un hallazgo sin ella es ruido
Límite de hallazgos
Fuerza la priorización
🏛️ Haz una revisión arquitectónica
Es el tipo de defecto que ninguna prueba detecta: el cambio funciona perfectamente y aun así está mal, porque cruza un límite, duplica una capacidad o crea un acoplamiento que después te pasará factura.
✓ Preguntas que revelan un problema real
- ✓¿Esta capa debería conocer esa otra?
- ✓¿Ya hay algo en el repositorio que haga esto?
- ✓¿Cuántos módulos deben cambiar juntos por esto?
- ✓¿Esta abstracción tiene más de un caso de uso hoy?
✗ Señales de violación arquitectónica
- ✗Import que cruza un límite de dominio
- ✗Regla de negocio dentro del controlador/handler
- ✗Tercera implementación de lo mismo, con otro nombre
- ✗Módulo nuevo que solo se usa en un lugar y nadie pidió
💡 Consejo práctico
Una regla arquitectónica que se repite tres veces en la revisión debe convertirse en una prueba: una verificación de dependencias que hace fallar la compilación cuando alguien importa a través de la frontera. Ese es el tema del módulo 3.3: una regla en texto se convierte en un control.
Frontera
El import es evidencia
Acoplamiento
Cuenta qué cambia junto
Abstracción
Necesita 2+ usos
Regla de 3 veces
Se convierte en prueba
🔐 Cubre seguridad, rendimiento y mantenimiento
Un revisor genérico encuentra cuestiones de estilo. Un revisor con una lente por iteración encuentra lo que duele. Ejecuta el mismo cambio tres veces, cada una con un enfoque.
Enfoque de seguridad
Entrada no validada, inyección, autorización ausente, secreto en el código, dato sensible en los registros, permisos demasiado amplios, dependencia con una CVE conocida.
Enfoque de rendimiento
Consulta dentro de un bucle (N+1), ausencia de índice, carga de toda la colección en memoria, llamada externa sin timeout, reintento sin espera creciente.
Enfoque de mantenimiento
Un nombre que no dice qué hace, demasiadas condicionales anidadas, configuración dispersa, pruebas que prueban la implementación en lugar del comportamiento, documentación que ya nació desactualizada.
Un enfoque
Por recorrido
Secreto
Bloqueo, no sugerencia
N+1
Clásico y costoso
Mantenimiento
Costo que llega después
🚧 Conoce los límites de la revisión automática
El revisor automático no conoce la intención de negocio, el acuerdo alcanzado en la reunión ni la razón histórica de un apaño. Y tiene un vicio: generar volumen. Treinta comentarios triviales por PR enseñan al equipo a ignorar las revisiones, incluso las buenas.
⚠️ Atención
En la revisión automática, la precisión vale más que la amplitud. Es mejor un revisor que señala tres cosas acertadas que uno que señala treinta, de las cuales cinco son reales. El costo del falso positivo no es el tiempo de lectura: es la confianza perdida.
Cómo calibrar el ruido
- • Limita la cantidad de hallazgos por revisión (5 a 7).
- • Exige severidad y "cómo verificar" en cada hallazgo.
- • Prohíbe los comentarios de estilo: eso es trabajo del lint, automático y silencioso.
- • Mide: de cada diez hallazgos, ¿cuántos se convirtieron en cambios? Si es menos de la mitad, ajusta el prompt.
Precisión
Por encima del alcance
Estilo
Es lint, no revisión
Falso positivo
Cuesta confianza
Medir
Hallazgo → cambio
🧑⚖️ Preserva el papel de la revisión humana
La IA filtra, explora y prepara. La decisión sigue siendo humana, no por formalidad, sino porque la intención, la prioridad y la aceptación del riesgo no son propiedades del código; son decisiones de quien responde por el sistema.
👤 Qué solo decide una persona
- •Si el problema resuelto era realmente el problema correcto.
- •Si el riesgo residual es aceptable para este negocio, en este momento.
- •Si conviene pagar la deuda ahora o registrarla y seguir adelante.
- •Quién responde si algo sale mal.
Verificación rápida: ¿qué configuración produce la revisión más confiable?
Intención
Solo el humano sabe
Riesgo
Aceptar es una decisión
PR pequeño
Hace posible la revisión
Responsabilidad
No se delega
📌 Resumen del módulo
Próximo módulo:
3.3 - Quality Gates: convertir una regla escrita en una verificación obligatoria.