Cómo revisar un PR de un agente de IA y quitar cambios innecesarios

Un agente de programación puede corregir errores o implementar una función con rapidez, pero también formatear archivos ajenos, añadir abstracciones, cambiar configuración o reescribir más código del necesario. Antes de fusionar, el objetivo no es obtener el menor número de líneas. El objetivo es un conjunto de cambios donde cada edición importante responda a un requisito aceptado, una persona mantenedora pueda explicarla y el equipo pueda verificarla con pruebas u otras evidencias.

Un desarrollador describió en X una práctica personal: después de que un agente abre un PR, inicia otro agente con contexto nuevo y le pide buscar qué se puede recortar. El autor lo presentó como trabajo y tokens adicionales, no como una solución garantizada. Otro usuario contó que Codex corrigió muchos errores, pero cambió tanto el código que dejó de entenderlo. Son señales del problema; no demuestran que un segundo agente mejore siempre un PR.

En el flujo siguiente, el segundo agente actúa como revisor crítico, no como autoridad. La persona responsable del repositorio conserva la decisión sobre alcance, evidencia, riesgo y merge.

El flujo completo en siete pasos

1. Redactar un contrato de aceptación: comportamiento esperado, lo que no debe cambiar, alcance permitido, riesgos y comandos de validación.
2. Inventariar el cambio con Conversation, Commits, Checks, Files changed y comandos locales de Git.
3. Encargar a un agente con contexto nuevo una primera pasada solo de revisión, sin editar.
4. Clasificar cada hallazgo como conservar, simplificar, eliminar, separar o escalar, siempre con evidencia.
5. Aplicar únicamente recortes aprobados por una persona, en lotes pequeños y reversibles.
6. Ejecutar el mismo conjunto de pruebas relevantes antes y después del recorte.
7. Revisar el diff final desde cero y fusionar solo cuando el cambio completo sea explicable.

1. Escribe primero el contrato de aceptación

“Haz que este PR sea más limpio” es demasiado ambiguo y puede provocar otra reescritura subjetiva. El contrato debe incluir:

• Problema y resultado observable: qué verá el usuario o el código consumidor.
• Comportamiento que se conserva: interfaces, fallos, compatibilidad y semántica de datos.
• Alcance permitido: módulos, API, esquemas, configuración o pruebas que se espera modificar.
• No objetivos explícitos: sin actualización de framework, formato global, renombrado ajeno, abstracción especulativa o migración no requerida.
• Restricciones de riesgo: seguridad, permisos, migraciones, rendimiento, observabilidad, rollback y compatibilidad.
• Validación: comandos reales del repositorio para formato, lint, tipos, pruebas, build, migraciones o E2E.

Si el equipo no puede describir el resultado correcto, tampoco puede decidir con fiabilidad qué código sobra. Aclara el contrato antes de borrar.

2. Establece el diff completo, no el resumen del agente

GitHub distribuye la evidencia del PR entre varias vistas. Conversation contiene descripción y discusión; Commits muestra la evolución; Checks recoge validaciones automáticas; Files changed presenta el diff. El flujo oficial permite comentar líneas, sugerir cambios, marcar archivos como Viewed y terminar con Comment, Approve o Request changes.

Para ejecutar o modificar el PR localmente, GitHub documenta:

gh pr checkout <PR_NUMBER>
git fetch origin

Sustituye origin/main por la rama base real y revisa desde el ancestro común hasta HEAD:

git diff --stat origin/main...HEAD
git diff --name-status origin/main...HEAD
git log --oneline origin/main..HEAD

Git define git diff A...B como los cambios desde el merge base de A y B hasta B. Tras el resumen, lee el diff completo y los archivos sospechosos:

git diff origin/main...HEAD
git diff origin/main...HEAD -- path/to/suspicious-file

No borres nada durante este inventario. Clasifica los archivos:

Grupo	Pregunta
Implementación central	¿Implementa directamente un punto del contrato?
Soporte necesario	¿Las pruebas, documentación, migración o configuración son realmente necesarias?
Expansión sospechosa	¿Hay formato global, renombrados amplios, abstracciones ajenas o upgrades?
Salida generada	¿Debe versionarse junto al origen o entró por accidente?
Riesgo incierto	¿Toca seguridad, datos, compatibilidad o un dominio desconocido?

La complejidad no prueba que algo sea redundante. Las defensas, migraciones y rutas de compatibilidad pueden ser largas y necesarias.

3. Usa contexto nuevo para una primera pasada sin edición

El contexto nuevo permite asignar una meta distinta: cuestionar alcance y evidencia en lugar de terminar la implementación. Es una técnica razonada y un informe de práctica, no un requisito oficial ni una garantía medida.

Entrega al revisor el contrato, el diff completo, llamadas relevantes, pruebas e instrucciones del repositorio. Puedes usar:

Eres la persona revisora de segunda pasada de este pull request. Tu objetivo no es reescribir el código, sino encontrar el conjunto de cambios más pequeño y explicable que conserve el contrato de aceptación.

Primera pasada: solo revisión. No modifiques archivos.
Lee el objetivo del PR, el diff completo, llamadas relevantes, pruebas y restricciones del repositorio.

Para cada hallazgo devuelve:
1. archivo y hunk o símbolo exacto;
2. requisito al que sirve;
3. evidencia: llamada, prueba, contrato de interfaz, documentación o ausencia de evidencia;
4. riesgo de eliminarlo o simplificarlo;
5. acción: CONSERVAR / SIMPLIFICAR / ELIMINAR / SEPARAR / DECISIÓN HUMANA;
6. validación exacta tras el cambio.

Reglas:
- no propongas borrar solo porque el código sea largo o tenga otro estilo;
- las pruebas verdes no son la única prueba de que el requisito sea correcto;
- prioriza formato ajeno, abstracciones duplicadas, helpers sin uso, refactors fuera de alcance y cambios de dependencias/configuración sin explicación;
- conserva seguridad, compatibilidad, migraciones, manejo de errores y observabilidad salvo evidencia contraria;
- declara incertidumbre, no inventes reglas de negocio;
- termina con un plan de bajo a alto riesgo. Todavía no escribas código.

Pedir un informe antes de editar evita que el revisor cree otra gran reescritura. Cada recomendación debe apuntar a archivo, hunk y evidencia.

4. Una persona clasifica cada hallazgo con evidencia

Decisión	Cuándo corresponde	Evidencia a confirmar
Conservar	Implementa el contrato o una obligación de seguridad, compatibilidad, migración u operación	Mapeo a requisito, ruta de llamada, prueba, interfaz o restricción documentada
Simplificar	El comportamiento es necesario, pero hay ramas, wrappers o capas duplicadas	Equivalencia de comportamiento y cobertura de bordes importantes
Eliminar	El cambio es ajeno, no usado, sin contrato o solo formato/renombrado accidental	Búsqueda, build y pruebas relevantes no muestran dependencia
Separar	Puede ser útil, pero queda fuera del contrato actual	Se puede describir, probar, revisar y revertir por separado
Escalar	Afecta un dominio desconocido, seguridad, migración o regla oculta	Hace falta code owner, especialista o prueba de caracterización

Investiga, sin borrar automáticamente: muchas capas para una llamada; rutas vieja y nueva sin periodo de compatibilidad; formato, imports, nombres o movimientos ajenos; dependencias o configuración sin explicación; pruebas de detalles internos en vez de comportamiento; captura silenciosa de excepciones; helpers sin callers; código “por si acaso”.

La falta de pruebas tampoco significa falta de uso. Puede indicar cobertura insuficiente. Añade una prueba de caracterización o consulta a la persona responsable antes de eliminar comportamiento incierto.

5. Recorta por lotes pequeños y conserva un punto de recuperación

Antes de editar, comprueba el árbol y crea una referencia local:

git status --short
git branch backup/ai-pr-before-trim

Para devolver un archivo completo al estado base:

BASE=$(git merge-base origin/main HEAD)
git restore --source="$BASE" -- path/to/unrelated-file

Para hunks concretos:

git restore -p --source="$BASE" -- path/to/file

Git advierte que, si una ruta versionada no existe en la fuente de restauración, se elimina para igualarla. Verifica $BASE y la ruta, y revisa el diff inmediatamente. La edición manual también sirve; lo esencial es no introducir otro refactor ajeno.

Procesa un grupo aprobado cada vez:

git diff
git add -p
git diff --cached
git commit -m "Remove unrelated changes from AI-generated PR"

Los commits pequeños muestran qué se quitó, por qué y con qué validación. No ocultes el proceso reescribiendo destructivamente el historial durante la revisión.

6. Ejecuta validaciones comparables antes y después

Las pruebas deben demostrar que el comportamiento aceptado se conserva, no que el diff es más corto. Registra una línea base del PR original cuando sea posible y repite las mismas comprobaciones tras cada lote:

<format-check-command>
<lint-command>
<typecheck-command>
<targeted-unit-test-command>
<relevant-integration-test-command>
<build-or-e2e-command>

Usa comandos de la documentación o del CI, no inventados por el agente. Cubre ruta normal, bordes, fallos, permisos, valores vacíos, concurrencia, timeouts, reintentos, interfaces públicas, formatos serializados, migraciones, build, tipos, lint, seguridad y Checks obligatorios del último commit.

Si una eliminación rompe una prueba, revierte ese lote o recupéralo del backup y analiza la causa. No cambies a la vez prueba e implementación para obtener verde, salvo que el contrato declare obsoleta la expectativa y una persona apruebe el nuevo comportamiento.

Las pruebas verdes son evidencia necesaria, pero pueden ser incompletas. La comprensión humana sigue siendo obligatoria.

7. Revisa de nuevo el diff final y decide explícitamente

Después del recorte, abre Files changed y revisa todos los archivos desde el principio. GitHub quita la marca Viewed cuando cambia un archivo ya visto, ayudando a localizar lo que requiere otra pasada. Comprueba de nuevo Commits y Checks para asegurarte de que pertenecen a la última revisión.

Puedes hacer un último análisis con contexto nuevo, limitado al contrato y diff final, con una condición de parada: solo problemas respaldados por evidencia, sin un bucle infinito de estilo. Luego una persona envía:

• Approve: contrato cumplido, cambios explicables, riesgos tratados y validación requerida superada.
• Request changes: quedan alcance ajeno, lógica opaca o checks fallidos. Que bloquee el merge depende de reglas y protección de rama.
• Comment: feedback útil sin aprobar ni solicitar cambios formalmente.

Lista previa al merge

• Cada archivo cambiado corresponde al requisito actual, una prueba necesaria o soporte explícito.
• La persona mantenedora explica cada hunk importante sin repetir el resumen del agente.
• Dependencias, configuración, permisos, migraciones y archivos generados sin explicación fueron eliminados, separados o escalados.
• El PR original y el recortado usaron validaciones comparables.
• Pruebas locales, build y checks del último commit cumplen los requisitos.
• Riesgos de seguridad, datos y compatibilidad fueron revisados por quien corresponde.
• Si el diff sigue siendo amplio, el trabajo independiente se separó.
• La decisión y tareas posteriores quedaron registradas.

Fallos frecuentes y recuperación

El segundo agente vuelve a reescribir el módulo

Detén la ejecución. Vuelve a un informe sin edición, limita archivos y exige hunk, requisito y validación por propuesta. Rechaza refactors estéticos sin evidencia.

Los agentes discrepan

No votes. Compara callers, contratos de interfaz, rutas de fallo, pruebas y restricciones históricas. Si la evidencia es débil, conserva temporalmente, añade cobertura o consulta al responsable del dominio.

Las pruebas pasan, pero el código sigue siendo opaco

Cobertura no equivale a diseño comprensible. Separa el PR, documenta o exige una explicación del camino crítico. No fusiones código opaco solo por CI verde.

No hay pruebas fiables

Añade una prueba mínima de caracterización o una verificación manual repetible con resultado registrado. En código de alto riesgo, falta de evidencia significa pausa, no permiso para adivinar.

El PR es demasiado grande

Separa comportamiento central, refactor, upgrades, formato y migraciones en cambios revisables de forma independiente. Las unidades pequeñas son más fáciles de verificar y revertir.

Prompt de ejecución para hallazgos aprobados

Implementa únicamente estos IDs aprobados: [LISTA].
No modifiques archivos fuera de la lista ni hagas refactoring oportunista.
Para cada grupo lógico:
1. muestra el diff real;
2. ejecuta los comandos asignados;
3. informa comando, código de salida y resumen de fallos;
4. enumera incertidumbres restantes.
Detente y pide decisión humana si un punto cambia el contrato, una interfaz pública, seguridad o migraciones.

La idea central no es “usar más agentes”. Separa generación y revisión: un contexto propone una implementación, otro cuestiona alcance y evidencia, y una persona es dueña de la decisión. El resultado correcto no es el diff más corto, sino el cambio mínimo, explicable y verificado que resuelve la tarea.

Fuentes y alcance

• Experiencia personal: publicación y respuestas de Arnav Gupta en X sobre revisión de recorte con contexto nuevo; no es estadística general.
• Informe de usuario: un desarrollador dijo que dejó de entender el código tras una reescritura amplia de Codex; el original no incluye repositorio, diff ni datos de pruebas.
• Documentación de GitHub: revisar cambios propuestos, obtener PR localmente, referencia de pull requests.
• Documentación de Git: git diff y git restore.