Cuando revisas código con Codex, hay comentarios que se repiten. Puede que haya que conservar un contrato de API anterior, evitar que se registren datos de clientes en los logs o mantener un nombre porque cambiarlo haría que otro servicio dejara de funcionar. Estas comprobaciones son importantes, pero es fácil pasarlas por alto cuando solo unas pocas personas del equipo de revisión conocen el contexto.
Ahora, al revisar código, Codex puede usar reglas personalizadas del repositorio definidas en AGENTS.md para detectar esos problemas e indicar a los autores en qué regla se basa cada hallazgo. Si ya usas AGENTS.md para orientar las tareas de programación, el mismo archivo también puede servirte para guiar las revisiones. Esto resulta especialmente útil cuando los colaboradores o los agentes de programación trabajan en una parte del repositorio con la que aún no están familiarizados y quizá desconozcan su historia. En esta publicación veremos cómo encajan las reglas del repositorio en la revisión, cómo redactarlas y qué aprendimos al ponerlas a prueba.
Entregar más código
Los agentes de programación pueden abordar cambios más grandes y trabajar en ellos durante más tiempo. Así, los equipos pueden llevar más ideas al código. En OpenAI, el volumen semanal de pull requests ha aumentado a más del doble desde el cuarto trimestre, y observamos tendencias similares entre muchos de nuestros clientes. Producir más código ayuda a los equipos a lanzar nuevas funciones y resolver más problemas. También significa que hay más pull requests a la espera de alguien que sepa qué revisar, y la revisión de código puede convertirse rápidamente en un cuello de botella.
La revisión se complica cuando llegan varios cambios a la vez. Un diff puede parecer perfectamente razonable y aun así hacer que un cliente antiguo deje de funcionar o traspasar un límite que el autor desconocía. Alguien tiene que recordar ese contexto y compartirlo mientras el autor todavía pueda ajustar el cambio.
El cuello de botella en la revisión
Cuando llegan más pull requests, los revisores tienen menos tiempo para entender el propósito de cada cambio y reunir el contexto necesario antes de dejar sus comentarios. Una vez que el autor pasa a otra tarea, hasta un ajuste pequeño puede llevar más tiempo. Los comentarios oportunos ayudan a los equipos a aprovechar un desarrollo más rápido sin que la revisión dependa de cuánto trabajo pueda absorber cada persona.
Algunos problemas también son difíciles de detectar con solo leer el diff. Cambiar el nombre de un campo de respuesta puede parecer una tarea rutinaria de limpieza, pero puede hacer que dejen de funcionar los clientes que aún dependen del contrato vigente. Un revisor con experiencia quizá recuerde por qué hay que conservar ese campo. Es poco probable que un colaborador nuevo o un agente que trabaja por primera vez en el servicio lo sepa.
Las reglas como interfaz
¿Cómo le das a un agente de programación el contexto que tu equipo suele adquirir con el tiempo? La nueva interfaz de reglas del repositorio te permite incluir en AGENTS.md instrucciones de revisión breves y con un alcance definido. Al revisar código, Codex puede aplicar las reglas pertinentes para un cambio y citarlas al señalar un problema. Así puedes dejar la explicación cerca del código al que se aplica y ahorrarte repetirla en cada pull request.
A medida que los modelos de programación responden mejor a las instrucciones, una indicación breve y de alcance preciso puede ayudar a centrar una revisión larga en lo que realmente le importa a tu equipo. El propio repositorio de Codex incluye reglas de revisión de código en AGENTS.md sobre temas como el contexto visible para el modelo y los cambios que rompen la compatibilidad.
Veamos un ejemplo real.
El app-server de Codex emite una notificación interna llamada rawResponseItem/completed. Está marcada como experimental, pero Codex Cloud ya la consume. La regla del repositorio para revisar cambios que rompen la compatibilidad menciona explícitamente rawResponseItem/* como una interfaz de integración que los revisores deben preservar, incluso mientras sea experimental.
El nombre con el que se transmite la notificación está definido en el protocolo del app-server. Imagina que, al limpiar el código, alguien cambia una línea:
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"El cambio compila, pero los clientes que escuchan la notificación con el nombre actual dejarían de recibirla. El fragmento pertinente de la regla del repositorio es breve:
## Code Review Rules
### Breaking changes
Search for breaking changes in external integration surfaces:
- raw response item events (`rawResponseItem/*`), even while experimentalPara el diff del ejemplo, un hallazgo de la revisión de código podría decir:
Conserva la notificación existente
rawResponseItem/completed. Los consumidores de Codex Cloud escuchan la notificación con este nombre, así que dejarán de recibirla si lo cambias, aunque el evento sea experimental. Conserva el nombre actual o agrega un evento compatible con versiones anteriores, como se indica enAGENTS.md.
El equipo de Codex agregó esta regla específicamente para proteger a los consumidores de Codex Cloud. Coloca las reglas que se aplican a todo el repositorio en la raíz y las de cada servicio en el directorio correspondiente. Durante la revisión, Codex puede aplicar las instrucciones que corresponden a los archivos modificados e indicar a los autores la regla pertinente. Para revisar un cambio que no guarda relación con el app-server, no hace falta conocer el contexto de ese servicio.
Las reglas complementan las herramientas que los equipos ya usan. Las pruebas y los linters funcionan bien para las comprobaciones que puedes expresar de forma determinista. Las reglas del repositorio ayudan a recoger criterios que son más difíciles de plasmar en código. Los requisitos de compatibilidad y los límites sobre el uso de los datos son buenos puntos de partida. Los autores pueden hacer un cambio sin conocer de antemano cada incidente pasado o cada convención local porque ya tienen a mano las instrucciones pertinentes.
Cómo redactar reglas que sigan siendo útiles
Para evaluar qué tan bien aprovechaba Codex las instrucciones del repositorio durante la revisión de código, usamos un conjunto de evaluaciones que incluía infracciones conocidas y contraejemplos que respetaban las reglas. En el conjunto principal, las variantes guiadas por reglas detectaron el 98 % de los problemas que debían señalar según las reglas personalizadas, frente al 58,3 % en la variante de control.
Detectar una infracción es solo parte del trabajo. También queríamos saber qué ocurre cuando hay varias reglas a las que prestar atención o cuando un pull request ya incluye muchos cambios. Probamos tanto infracciones con consecuencias importantes como cambios que no ameritaban observaciones. Luego organizamos los resultados en torno a cuatro preguntas:
Qué evaluamos
Cobertura
¿Puede Codex detectar las infracciones previstas cuando los diffs incluyen muchos cambios y hay varias reglas a las que prestar atención?
Moderación
¿Evita Codex hacer observaciones innecesarias sobre cambios correctos y excepciones válidas?
Detección de errores habituales
¿Sigue Codex detectando los errores habituales que las reglas del repositorio no contemplan?
Utilidad para el autor
¿Indica cada hallazgo qué instrucciones se aplican, dónde está el problema y qué prioridad tiene?
También probamos formatos habituales para redactar instrucciones, desde listas breves con viñetas hasta secciones a cargo de un equipo en particular.
Observamos el mismo patrón al usar reglas en repositorios internos. Codex podía encontrar y citar instrucciones locales que una revisión predeterminada podría pasar por alto, pero las indicaciones demasiado generales generaban fácilmente comentarios innecesarios. Con pocas reglas, un alcance preciso y una opción segura explícita, Codex podía centrarse en lo más útil sin aplicar una regla a cada cambio cercano.
Empieza por una condición importante que deba mantenerse y que sea fácil pasar por alto. Escribe una regla para una comprobación que los revisores tengan que explicar una y otra vez, como un requisito de compatibilidad o un límite sobre el uso de los datos. Si quitar una regla no cambiaría la revisión, omítela.
Limita cada regla al código al que se aplica. Coloca las instrucciones para todo el repositorio en la raíz y las de cada servicio en un archivo AGENTS.md de su subdirectorio. Un alcance preciso evita que las instrucciones ajenas al cambio desvíen la atención y deja claro quién es responsable de cada regla.
Indica qué condición debe mantenerse y cómo hacer el cambio de forma segura. La regla sobre rawResponseItem/* identifica el riesgo de incompatibilidad. “Conserva el nombre actual o agrega un evento compatible con versiones anteriores” ofrece a los autores una alternativa clara.
Redacta reglas duraderas y mantenlas al día. Describe el resultado esperado sin depender de nombres de funciones que podrían cambiar. Revisa las actualizaciones de las reglas y limita el alcance de las instrucciones que generen comentarios innecesarios una y otra vez, o elimínalas.
Mantén las comprobaciones de formato y otras verificaciones mecánicas en CI. Reserva las reglas del repositorio para las preguntas que, de otro modo, un revisor tendría que volver a plantear.
Primeros pasos
Si tu repositorio ya tiene habilitada la revisión de código de Codex, agrega dos o tres reglas al archivo AGENTS.md correspondiente y abre un pull request representativo. Si es la primera vez que usas la revisión de código, la guía de inicio rápido para la revisión de código explica cómo habilitarla en un repositorio de GitHub. También puedes solicitar una revisión directamente con @codex review.
Empieza con una explicación que los revisores suelan repetir o con un error propio del repositorio que tendría consecuencias importantes si pasara inadvertido. Prueba un cambio que deba activar la regla, un contraejemplo que la respete y un cambio que no guarde relación con ella. Comprueba que el primero produzca un hallazgo útil y que los otros dos no generen comentarios innecesarios. Luego ajusta las instrucciones según lo que observes.
En la revisión de código, Codex sigue actuando como un revisor adicional. Las pruebas, las protecciones de ramas y las aprobaciones obligatorias siguen siendo los mecanismos que hacen cumplir los requisitos.
Si dedicas más tiempo a revisar cambios que a escribirlos, empieza con una comprobación que tu equipo haga una y otra vez. Agrégala a AGENTS.md y prueba la revisión de código de Codex en tu próximo pull request.