Codex para revisión de código: cómo dejar que la IA revise PR sin que modifique todo

Llega una PR de 800 líneas con el título fix y una descripción que dice solo “arreglé algunas cosas”. Miras el diff, no sabes dónde está el riesgo principal y tampoco quieres leer cada archivo cambiado línea por línea. Alguien escribe en un comentario de PR: @codex review for auth bypass and PII logging. Unos minutos después, aparece un inline comment apuntando a logger.info(user.email).

Ahora tienes que decidir: ¿dejas que Codex haga el fix, lo corriges tú o preguntas primero al equipo de negocio si esa línea de log cumple la política? Esta guía aclara las condiciones de disparo, cómo escribir Review guidelines, qué significan P0/P1, cómo tratar los findings y dónde debe quedar la confirmación humana.

@codex review no es un hechizo universal

@codex review no es un interruptor para que la IA cambie código automáticamente. Solo pide a Codex que lea el diff de la PR y publique review comments siguiendo tus reglas. Que se dispare, qué revise y qué hacer con el resultado depende de la configuración previa y del criterio humano.

Disparos y configuración de GitHub Cloud

Para usar Codex en code review, el repository debe tener Codex Cloud configurado y tú debes tener acceso a los code review settings. Hay dos formas de dispararlo: escribir @codex review en un comentario de PR, o activar Automatic reviews en settings para que Codex publique una review cuando una nueva PR esté opened for review.

Después del disparo, Codex lee el PR diff, sigue la repository guidance, normalmente las Review guidelines en AGENTS.md, y publica inline comments como una GitHub code review estándar. @codex review no equivale a approval. Automatic reviews tampoco significa aprobación automática. Cambios sensibles como auth, payment o data migration siguen necesitando confirmación humana.

Puedes combinar los disparadores de PR y los workflows de CI con branch protection rules para que la AI review sea solo una comprobación más. Para configurar disparadores de PR, mira el artículo anterior sobre disparadores de PR en GitHub Actions.

Enfocarse en P0/P1, no en una lista interminable

Por defecto, Codex solo marca problemas de prioridad P0/P1. P0 es un problema bloqueante: security regressions, auth bypass o data loss. P1 es un problema que debe corregirse: performance, concurrency o logging sensitive data.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Ese foco evita que los review comments exploten, mantiene la señal alta y reduce el ruido de poco valor. Puedes sobrescribir la regla por defecto en la sección Review guidelines de AGENTS.md. Por ejemplo, puedes pedir que Codex solo mire auth bypass, PII logging y concurrency, y que no comente code style, que queda para Prettier, ni minor performance fuera de rutas críticas. La siguiente sección desarrolla cómo escribir esas Review guidelines.

Las Review guidelines van en AGENTS.md, no en el comentario de cada PR

Las Review guidelines deciden el foco y la prioridad de Codex review. Deben escribirse en el archivo AGENTS.md del repository, no repetirse en cada comentario de PR.

Lectura por capas de AGENTS.md y escritura de Review guidelines

Codex lee AGENTS.md antes de empezar a trabajar. El orden va desde el Git root hasta el directorio de trabajo actual, y las instrucciones más cercanas son más específicas. Por ejemplo, un AGENTS.md dentro de auth/ puede sobrescribir las reglas globales y centrarse solo en riesgos de auth.

Una sección típica de Review guidelines:

## Review guidelines

Fíjate solo en estos riesgos:
1. Security regressions(auth bypass、path traversal)
2. PII logging(user.email、phone number)
3. Concurrency issues(race condition、deadlock)

No revises:
- Code style(automatizado con Prettier)
- Minor performance(rutas no críticas)

La ventaja es clara: todas las PR comparten una misma base de reglas, no tienes que repetirlas en cada comentario, y el AGENTS.md más cercano a los changed files puede ser más específico.

Ten en cuenta que los archivos de instrucciones están sujetos a project_doc_max_bytes, con 32 KiB por defecto. Si el archivo es demasiado largo, puede truncarse. La escritura completa de AGENTS.md, incluyendo Project rules, Review guidelines y Coding style, queda para otros artículos de la guía práctica de Codex. Aquí nos centramos solo en la estructura y la prioridad de Review guidelines.

Usa el Codex app review pane para entender el diff antes de decidir

El review pane de Codex app no muestra solo sugerencias de cambios de la IA. Refleja el estado completo del Git repository. Por defecto se centra en uncommitted changes, pero también puede cambiarse a all branch changes o last turn changes.

Inline comments y PR context

Los inline comments del review pane están pegados directamente a las líneas del diff. Puedes usar ese feedback preciso para decidir el siguiente paso: dejar que Codex haga el fix, modificarlo tú o marcarlo como false positive. Después de ejecutar /review, el resultado aparece como inline comments dentro del review pane.

Si Codex tiene GitHub access y el proyecto actual está en una PR branch, la app puede mostrar PR context: reviewer feedback, changed files y PR description. Para eso necesitas GitHub CLI instalado y autenticado con gh auth login. Si falta, puede que no aparezcan los PR details y solo veas el diff local.

Controlar la granularidad: stage/revert por file o hunk, no todo el commit

El review pane permite stage, unstage y revert a nivel de entire diff, file o hunk. No conviene hacer revert de todo el commit apenas ves un finding, sobre todo cuando el cambio toca varios files. Trabajar por hunk permite conservar cambios seguros y retirar solo la parte riesgosa.

Tratamiento de review findings: después de @codex fix, mira diff, CI y pruebas

Cuando aparece un P0/P1, no lo delegues todo de inmediato a @codex fix. Primero debes decidir si el finding es real, si la corrección es razonable y si el cambio toca una zona sensible que necesita confirmación del equipo.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Tabla de triage de review findings

Flujo ejecutable para tratar findings

Confirmar si el finding es real: mira la línea del diff señalada por el inline comment y verifica que el problema existe.

Decidir el límite del fix: auth, payment y data migration son cambios sensibles y requieren confirmación humana. style y minor perf pueden ignorarse o dejarse a la toolchain.

Elegir cómo tratarlo:

• Dejar que Codex lo corrija: escribe @codex fix the P1 issue en el comentario de PR; Codex inicia una cloud task basada en el PR context
• Corregirlo tú: edita el código manualmente, ejecuta pruebas locales y luego haz push
• Pedir pruebas: abre una follow-up issue o explica la necesidad en un comentario
• Marcar false positive: explica la razón en el comentario para evitar que se repita

Mirar diff y CI: aunque @codex fix tenga permiso para hacer push a la PR branch, debes revisar el diff, el resultado de CI y la cobertura de pruebas. Un fix de Codex no es un merge automático, no equivale a CI aprobada y no sustituye la approval de un reviewer humano.

Confirmar cambios sensibles con humanos: auth bypass, payment flow y data migration tocan límites de seguridad. Un reviewer del equipo debe confirmarlos. No saltes esa revisión.

Cosas que no debes hacer

• No hagas push/merge automático: @codex fix solo pide a la IA que cambie código; no es permiso de merge
• No saltes la CI: aunque Codex corrija el problema, la CI debe ejecutarse para asegurar que no se rompen otras pruebas
• No ignores la opinión de reviewers humanos: la AI review es una segunda revisión, no un reemplazo del reviewer del equipo
• No des permisos excesivos a Codex: main branch push, force push y write access a directorios sensibles deben estar limitados

Los límites de seguridad y el control de permisos para cambios sensibles se desarrollarán en artículos posteriores de la guía práctica de Codex sobre permisos y Secrets. Para buenas prácticas de CI, consulta la guía anterior de pipeline CI con GitHub Actions.

Commit message y PR description: deja que la IA redacte, pero no inventes normas

@codex generate commit message o @codex generate PR description permite que Codex genere texto a partir del diff y del PR context. Revisa el resultado, no lo uses a ciegas. El commit message debe seguir Conventional Commits; no conviene inventar un formato propio.

Conventional Commits y plantilla de commit message

El formato de Conventional Commits es <type>[optional scope]: <description>. Tipos comunes: fix corresponde a una versión PATCH, feat a una versión MINOR, y un footer BREAKING CHANGE o ! indica un cambio incompatible.

Ejemplo:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

fix(auth): prevent bypass in login flow

- Add session validation before auth redirect
- Reject expired tokens within 5 minutes

Refs: #123

Conventional Commits se usa porque es un estándar ampliamente adoptado. Toolchains como semantic-release, auto-changelog y commitlint dependen de este formato para generar changelogs y decidir versiones. Inventar una norma propia rompe esas automatizaciones y aumenta el costo de colaboración del equipo.

Plantilla de PR description

Una PR description debe incluir al menos cinco partes:

1. Contexto: por qué se hace el cambio (feedback de usuarios, problema de rendimiento, riesgo de seguridad)
2. Alcance del cambio: qué módulos se ven afectados (auth, payment, logging)
3. Pruebas: escenarios verificados (pruebas locales, cobertura en CI, verificación manual)
4. Riesgos: condiciones límite conocidas (concurrencia, comportamiento bajo mucho tráfico)
5. Rollback: cómo volver atrás rápido (revert commit, feature flag, config toggle)

Cuando Codex la genere, revisa si las cinco partes están completas, si la descripción es precisa y si faltan riesgos o rollback. No commitees texto generado directamente, especialmente si el cambio toca una zona sensible.

Para definir cómo generar commit message y PR description, puedes escribir una instrucción concreta en el comentario de PR, por ejemplo @codex generate commit message following Conventional Commits, para que la IA siga el formato estándar.

Resumen

Codex review es una segunda revisión de alta señal, no un permiso de merge. @codex review solo pide a la IA que lea el diff y publique inline comments; Automatic reviews solo automatiza el disparo, no la approval ni el merge.

Flujo central:

1. En las Review guidelines de AGENTS.md, enfócate en 1 o 2 riesgos, como auth bypass, PII logging o concurrency. No intentes cubrirlo todo
2. P0/P1 es el foco por defecto para evitar que los review comments exploten. P0 debe corregirse; P1 requiere decidir cómo tratarlo
3. Cuando aparece un finding, mira la línea del diff señalada por el inline comment y confirma si el problema es real. Cambios sensibles como auth, payment o data migration requieren confirmación humana
4. Después de @codex fix, sigue revisando diff, resultado de CI, cobertura de pruebas y criterio humano. No hagas push/merge automático, no saltes CI y no ignores a los reviewers del equipo
5. Usa Conventional Commits para commit messages. No inventes formatos; la toolchain depende del estándar para generar changelogs y decidir versiones

Acciones recomendadas:

• Añade AGENTS.md a tu repository y escribe una sección breve de Review guidelines centrada en 1 o 2 riesgos
• Prueba @codex review en la próxima PR y comprueba si los inline comments respetan tus reglas
• En cambios sensibles, lee los artículos posteriores de la guía práctica de Codex sobre permisos, secrets y análisis de fallos antes de decidir si usar @codex fix

Artículos relacionados

• Disparadores de PR en GitHub Actions: configurar PR triggers y branch protection rules
• Buenas prácticas de pipeline CI con GitHub Actions: comprobaciones de CI y responsabilidades del reviewer humano
• Comparativa de asistentes de programación con IA: Claude Code vs Cursor vs Copilot: elegir herramientas de AI coding