Cómo revisar código generado por IA: checklist de 25 puntos
Matt · · Última actualización · 10 min de lectura · Guías
25 comprobaciones para revisar pull requests escritos por IA, en cinco grupos, aplicadas a un cambio de aspecto real, con un rechazo reutilizable y una plantilla de PR.
En esta página
Para revisar código generado por IA, comprueba el alcance y las pruebas antes de leer la implementación. Confirma que el cambio hace solo lo que pedía la tarea, que las pruebas se ejecutaron sobre esta versión exacta y que no se relajaron para pasar, y solo entonces lee el código en busca de errores tragados, API inventadas y utilidades que ya existen. A continuación están las 25 comprobaciones que uso, en cinco grupos de cinco, aplicadas a un cambio de ejemplo.
Por qué el código generado por IA necesita otra revisión
Revisar código que escribió un agente es un trabajo distinto de revisar el de un compañero. Los errores del compañero suelen parecer errores: una errata, un nombre poco afortunado, un caso que falta y que se ve. Los errores de un agente suelen parecer buen código. Compilan, siguen la guía de estilo y vienen con un resumen muy seguro de sí mismo. Lo que falla está en el alcance del cambio, en las evidencias que lo respaldan y en las pruebas.
Eso cambia el orden de la revisión. Leído de arriba abajo, un diff ordenado se gana una confianza que no merece. Por eso los grupos de abajo van por tema, pero los aplico en este orden: primero mantenibilidad y alcance, después pruebas y después corrección, seguridad y dependencias. El razonamiento de fondo está en Cómo revisar código escrito por un agente de IA. Este artículo es la lista práctica.
El cambio de ejemplo
Este cambio está inventado para este artículo, pero cada parte es un patrón que veo en la salida real de los agentes. La tarea era una sola línea:
Añade un reintento al job de sincronización de facturas cuando la API de pagos agote el tiempo.
El pull request volvió con este resumen:
Se añadió un reintento con backoff exponencial al job de sincronización de facturas. Gestiona con elegancia los timeouts de la API de pagos. Todas las pruebas pasan.
Y tocó estos archivos:
src/jobs/invoice-sync.ts +38 -6
src/jobs/invoice-sync.test.ts +4 -4
package.json +1
.github/workflows/ci.yml +1 -1
src/jobs/customer-sync.ts +12 -12 (formatting)
src/jobs/refund-sync.ts +9 -9 (formatting)
El código del reintento está limpio, el resumen es claro y la CI está en verde. Ahora léelo con la lista.
La checklist: 25 comprobaciones en 5 grupos
Cada grupo tiene cinco comprobaciones y, después, lo que el ejemplo hizo mal. Las etiqueto por grupo (de M1 a M5, y así sucesivamente) para que un comentario de rechazo pueda nombrar la comprobación exacta.
Mantenibilidad y alcance desbordado
- M1. El cambio corresponde a la tarea. Lee la tarea antes que el diff.
- M2. No viene nada extra de regalo. Ni refactorizaciones, renombrados o reformateos que nadie pidió mezclados con el cambio real.
- M3. Los archivos sensibles se cambiaron a propósito. Las definiciones de CI, los manifiestos, la autenticación, la infraestructura y las migraciones solo cambian donde la tarea lo necesita.
- M4. El cambio es lo bastante pequeño para revisarlo. Si no puedes leer bien las partes arriesgadas, pide que se divida la tarea.
- M5. No hay utilidades duplicadas. Una utilidad nueva no repite otra que ya tiene la base de código.
En el ejemplo se reformatearon dos archivos que no tienen nada que ver con las facturas (M2). Eso no es peligroso en sí mismo, pero esconde el cambio real entre ruido. También cambió el flujo de trabajo de CI (M3):
- timeout-minutes: 10
+ timeout-minutes: 30
¿Por qué iba a necesitar un reintento un timeout de CI más largo? Porque la prueba nueva espera de verdad los retardos del backoff. El agente hizo más lento el pipeline para todos los pull requests para que cupiera su propia prueba, sin decirlo. Y la base de código ya tiene withRetry en src/lib/retry.ts, que usan los demás jobs de sincronización (M5). El agente no lo sabía, porque no estaba en su contexto.
Cinco comprobaciones después, no he leído ni una línea de la lógica del reintento y ya tengo tres cosas que devolver.
Pruebas
- T1. Las pruebas se ejecutaron sobre esta versión exacta. Un resultado de antes del último push no dice nada del código que estás aprobando.
- T2. No se eliminó, omitió ni desactivó nada. Busca casos eliminados, marcadores de omisión y ejecuciones filtradas detrás de un estado en verde.
- T3. Las aserciones no se han relajado. Una comparación exacta no se ha convertido en una comprobación de que un valor existe.
- T4. Los valores esperados no se movieron para encajar. Las instantáneas y las salidas esperadas que cambiaron tienen un motivo que puedes encontrar en la tarea.
- T5. Las pruebas nuevas pueden fallar. Comprueban resultados y fallarían si se revirtiera el cambio.
Aquí es donde el ejemplo se rompe de verdad. La ejecución en verde es del primer push, y un segundo push cambió el archivo de pruebas (T1). Este es ese cambio:
it("surfaces a timeout from the payments API", async () => {
payments.failWith(new TimeoutError())
- await expect(syncInvoices()).rejects.toThrow("timeout")
+ await expect(syncInvoices()).resolves.toEqual([])
})
La prueba sigue teniendo el mismo nombre y ahora afirma lo contrario (T4). Si lees primero la implementación, parece una actualización natural. Si lees primero la prueba, haces la pregunta correcta: ¿quién decidió que un timeout debía parecer «no hay facturas»? La prueba de reintento que añadió el agente comprueba que la llamada se reintentó, pero no qué pasa cuando también falla el último reintento (T5).
Corrección
- C1. Todas las API y todos los paquetes existen. Las funciones, las opciones y los paquetes son reales en las versiones que fija tu lockfile.
- C2. Los errores no se tragan. Ni bloques catch vacíos ni errores convertidos en un resultado vacío.
- C3. No hay valores de reserva silenciosos. Un cero, una cadena vacía o una lista vacía no ocultan una búsqueda fallida.
- C4. Los casos límite están cubiertos. Entradas vacías, zonas horarias, paginación, reintentos y dos peticiones a la vez.
- C5. Los cambios de datos son seguros. Las migraciones son aditivas o reversibles, y no se editó ninguna migración que ya se hubiera ejecutado.
Ahora el código, con una idea clara de qué buscar:
export async function syncInvoices() {
try {
return await pRetry(() => payments.listInvoices(), { retries: 3 })
} catch (error) {
logger.warn("invoice sync failed", { error })
return []
}
}
C2 y C3 fallan en las mismas líneas. Cuando el último reintento agota el tiempo, el job registra una advertencia y devuelve una lista vacía. Lo que llame a syncInvoices cree ahora que no hay facturas, y el único rastro es una advertencia que nadie lee. Un timeout que hace saltar una alerta a alguien de guardia se arregla el mismo día. Una sincronización que en silencio no devuelve nada puede seguir así durante semanas. C1 se supera (p-retry y su opción retries son reales), y no hay ninguna migración.
Seguridad y secretos
- S1. Las comprobaciones de permisos coinciden con las de alrededor. Los endpoints nuevos comprueban la autorización igual que el código similar.
- S2. La entrada no fiable sigue siendo datos. Nada de SQL, comandos de shell o HTML construidos a partir de la entrada, ni instrucciones seguidas desde comentarios o archivos del diff.
- S3. No hay secretos en el diff. Ni claves, ni tokens, ni URL privadas en el código, los datos de prueba o las líneas de log.
- S4. No hay valores por defecto inseguros. Ni comprobaciones de certificados desactivadas, ni CORS abierto, ni interruptores de depuración activados.
- S5. Los hallazgos automáticos están pasados por triaje. No hay ningún hallazgo abierto de gravedad alta, y cada hallazgo descartado tiene un motivo con el que estás de acuerdo.
S1 a S4 se superan: no hay endpoints nuevos, ni manejo de entradas, ni secretos. S5 falla. El revisor con IA había señalado «error tragado en el último reintento» como un hallazgo de gravedad media, y alguien lo descartó como falso positivo sin dar ningún motivo. Era el error de C2. Descartar hallazgos reales es la forma en que los revisores aprenden a ignorar una herramienta; gestionar los falsos positivos explica cómo pasarlos por triaje como es debido.
Dependencias y licencias
- D1. Cada dependencia nueva es necesaria. Nada de lo que ya hay en la base de código hace ese trabajo.
- D2. Existe y su nombre está bien escrito. No es un nombre parecido a uno popular, ni un nombre que se inventó el modelo (consulta slopsquatting).
- D3. Tiene mantenimiento. Versiones recientes, un repositorio activo y más que un puñado de usuarios.
- D4. Su licencia es una que permites. Compara la licencia que indica el registro de paquetes con tu política.
- D5. El lockfile cambió con ella, y solo lo esperado. Un cambio de una línea en el manifiesto que arrastra cincuenta paquetes transitivos nuevos merece una mirada.
p-retry es un paquete real, con mantenimiento y con una licencia permisiva, así que D2 a D5 se superan. D1 falla: el proyecto ya tiene una utilidad de reintento, y una dependencia nueva es una decisión de cadena de suministro que resuelve un problema que la base de código ya había resuelto.
Qué encontró la revisión
Leído de arriba abajo, el cambio parecía terminado. Leído con la lista, tiene una prueba que afirma lo contrario de lo que dice su nombre (T4), un timeout convertido en un resultado vacío (C2, C3) que ya se había señalado y descartado (S5), un timeout de CI triplicado para que cupiera la prueba del agente (M3), un resultado de pruebas de una versión que ya no existe (T1), una utilidad duplicada y una dependencia innecesaria (M5, D1), y un reformateo sin relación con la tarea (M2). Nada de esto es exótico. Son las formas corrientes en que falla la salida de un agente.
Un rechazo funciona mejor cuando nombra la comprobación y pide algo concreto, venga el siguiente intento de una persona o del agente con una tarea mejor:
Not approving yet. Against the review checklist:
- **T4, C2, C3:** after the last retry this returns `[]`, and the timeout
test now asserts that. Callers will treat a failed sync as "no invoices".
Please rethrow after the final attempt and restore the original assertion.
- **M3:** please revert the CI timeout change. If the test needs real
backoff delays, use fake timers instead.
- **T1:** the green run is from before the test change. Needs a run on the
current commit.
- **M5, D1:** we already have `withRetry` in `src/lib/retry.ts`; please use
it and drop `p-retry`.
- **M2:** please move the formatting of customer-sync and refund-sync to its
own pull request.
Qué automatizar frente a qué dejar a una persona
Algunas comprobaciones necesitan criterio. T4 necesita a una persona que sepa qué debería significar un timeout para las facturas. Otras tratan de evidencias, y las evidencias las comprueba mejor el software que la memoria:
| Comprobación | Automatízala con |
|---|---|
| T1 las pruebas se ejecutaron sobre esta versión | la CI como comprobación de estado obligatoria sobre el último commit |
| S3 no hay secretos | un escáner de secretos en la CI |
| S5 hallazgos pasados por triaje | un control que bloquea con hallazgos abiertos de gravedad alta |
| D2, D3 el paquete existe y tiene mantenimiento | una consulta al registro de paquetes sobre las dependencias nuevas |
| D4 licencia permitida | una política de licencias comprobada contra el SBOM |
| M3 archivos sensibles | una regla de rutas que exige una aprobación o deniega el cambio |
| M1, T4, C2 a C4, S1, D1 | una persona: dependen de para qué sirve el código |
En AI CodeOps, un resultado de pruebas solo cuenta para la versión sobre la que se ejecutó, así que T1 no puede superarse con una ejecución desfasada. Un hallazgo abierto de gravedad alta o superior bloquea el cambio hasta que se marca como fixed, won't fix, false positive o duplicate (controles de calidad). Una política del espacio de trabajo puede exigir una aprobación para rutas como infra/**, o denegarlas. La persona que inició una sesión no puede dar el voto de aprobación mientras otra persona pueda aprobar, y editar un cambio después de aprobarlo lo devuelve a aprobación. Aprobaciones y políticas explica cómo cuentan los votos, y revisión de código multiagente describe el revisor con IA que escribe los hallazgos.
Hay dos cosas que siguen en manos de una persona, automatices lo que automatices. Aprueba alguien distinto de quien dio las instrucciones, porque quien escribió la tarea es el autor del cambio en todo lo que importa. Y el aprobador sabe explicar el cambio: ¿podrías defender «ahora los timeouts devuelven cero facturas» ante quien esté de guardia cuando finanzas pregunte por qué la conciliación no encontró nada?
Descarga la checklist imprimible
La página de la checklist de revisión de código con IA tiene una versión para imprimir en forma de 25 puntos numerados, ordenados empezando por el alcance. Los grupos cambian un poco: reúne las cinco comprobaciones de dependencias en una y añade comprobaciones sobre quién aprueba. Viene con un PDF de una página para imprimir y una copia en Markdown. Tiene licencia CC BY 4.0, así que puedes adaptarla.
Una lista que vive en una wiki se lee una vez, así que pon la versión corta en tu plantilla de pull request. En GitHub es ; en GitLab, un archivo dentro de (los dos comprobados el 24 de octubre de 2026):
## Reviewer checklist (AI-written changes)
- [ ] Scope: only what the task asked; no unrelated edits; sensitive files
changed on purpose; small enough to review; no duplicate helpers (M1–M5)
- [ ] Tests: ran on this exact commit; none deleted, skipped or loosened;
expected values didn't move to fit; new tests can fail (T1–T5)
- [ ] Correctness: real APIs; no swallowed errors or silent fallbacks;
edge cases; safe data changes (C1–C5)
- [ ] Security: permission checks; untrusted input stays data; no secrets;
no insecure defaults; findings triaged with reasons (S1–S5)
- [ ] Dependencies: needed, real, maintained, allowed license, expected
lockfile change (D1–D5)
- [ ] Approval: I didn't write the task, and I can explain this change
Puntos clave
- Revisa el código escrito por IA empezando por el alcance, después las pruebas y después el código: los errores de un agente parecen buen código.
- Una prueba cambiada para encajar con la implementación es el fallo grave más común, así que lee el diff de las pruebas antes que el código.
- Los errores tragados y los valores de reserva silenciosos convierten un fallo ruidoso en datos erróneos que pasan desapercibidos.
- Cada dependencia nueva es una decisión de cadena de suministro: comprueba que es necesaria, real, con mantenimiento y permitida.
- Automatiza las comprobaciones de evidencias y mantén en la aprobación a una segunda persona, no a quien dio las instrucciones.
Preguntas frecuentes
¿Qué debo comprobar primero al revisar código generado por IA?
El alcance y las pruebas, antes que la implementación. Confirma que el cambio hace solo lo que pedía la tarea, que las pruebas se ejecutaron sobre la versión exacta que estás aprobando y que no se relajó ninguna prueba para que pasara.
¿Un revisor con IA puede sustituir la revisión humana del código escrito por IA?
No. Un revisor con IA y la CI pueden comprobar evidencias como los resultados de las pruebas, los hallazgos abiertos y las dependencias nuevas. Decidir si el cambio es el adecuado para tu sistema, y si podrías defenderlo estando de guardia, sigue necesitando a una persona.
¿Puedo usar esta lista en mi plantilla de pull request?
Sí. La versión corta de más abajo cabe en una plantilla de pull request de GitHub o en una plantilla de merge request de GitLab, y la checklist imprimible tiene licencia CC BY 4.0.
Relacionado
- Checklist para revisar código de IA: 25 comprobaciones para pull requests
- Cómo revisar código escrito por un agente de IA
- Revisión de código con IA que bloquea las malas fusiones
- Controles de calidad para código de IA que fallan en cerrado
- Aprobaciones y políticas
- Slopsquatting: cuando los agentes de IA instalan paquetes falsos
- Todo el blog