Al revisar código con Codex, algunos comentarios se repiten. Pueden referirse a conservar un contrato de API anterior, evitar que los datos de los clientes aparezcan en los registros o impedir un cambio de nombre que haría fallar otro servicio. Estas comprobaciones son importantes, pero es fácil pasarlas por alto cuando solo unos pocos revisores conocen el contexto.
La revisión de código de Codex ahora puede usar reglas personalizadas del repositorio en AGENTS.md para detectar esos problemas e indicar a los autores qué instrucciones respaldan un hallazgo. Si ya usas AGENTS.md para orientar las tareas de programación, el mismo archivo también puede orientar las revisiones. Esto resulta especialmente útil cuando los colaboradores o los agentes de programación trabajan en una parte del repositorio que no conocen y cuyo historial quizá aún desconocen. En esta publicación, mostraremos qué lugar ocupan las reglas del repositorio y cómo redactarlas bien, incluido lo que aprendimos al probarlas.
Entregar más código
Los agentes de programación pueden encargarse de cambios más grandes y trabajar durante períodos más largos, lo que ayuda a los equipos a convertir más ideas en 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 en muchos de nuestros clientes. Tener más código es positivo: 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é buscar, y la revisión de código puede convertirse rápidamente en el cuello de botella.
La revisión se vuelve más difícil cuando llegan varios cambios a la vez. Un diff puede parecer totalmente razonable y aun así hacer fallar un cliente anterior o cruzar un límite que el autor desconocía. Alguien tiene que recordar ese contexto y compartirlo mientras el autor todavía puede actuar al respecto.
El cuello de botella de la revisión
Cuando llegan más pull requests, los revisores tienen menos tiempo para entender qué busca lograr cada cambio y reunir el contexto pertinente antes de dejar comentarios. Una vez que el autor pasa a otra cosa, incluso un pequeño ajuste puede tomar más tiempo. Los comentarios oportunos ayudan a los equipos a aprovechar un desarrollo más rápido sin convertir a las personas en el cuello de botella.
También hay problemas que son difíciles de detectar solo con el diff. Cambiar el nombre de un campo de respuesta puede parecer una limpieza rutinaria, pero puede hacer fallar clientes que aún dependen del contrato existente. Un revisor experimentado quizá recuerde por qué ese campo debe conservarse; un colaborador nuevo o un agente que trabaje en el servicio por primera vez probablemente no.
Las reglas como interfaz
Entonces, ¿cómo le das a un agente de programación el contexto que tu equipo normalmente adquiere con el tiempo? La nueva interfaz de reglas del repositorio te permite incluir en AGENTS.md instrucciones de revisión concisas y con un alcance definido. La revisión de código de Codex puede aplicar las reglas pertinentes para un cambio y citarlas en un hallazgo. En lugar de repetir la misma explicación en cada pull request, puedes mantenerla cerca del código al que se aplica.
A medida que los modelos de programación responden mejor a las instrucciones, una indicación breve y con un alcance bien definido puede ayudar a centrar una revisión larga en lo que realmente le importa a tu equipo. El propio repositorio de Codex mantiene reglas de revisión de código en AGENTS.md, que abarcan aspectos 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 de revisión de cambios que rompen la compatibilidad del repositorio señala explícitamente a rawResponseItem/* como una interfaz de integración que los revisores deben preservar, incluso mientras sea experimental.
El nombre actual usado en la comunicación está definido en el protocolo de app-server. Imagina que una limpieza cambiara una línea:
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"El cambio compila, pero los clientes que escuchan la notificación existente dejarían de recibirla. El fragmento pertinente de la regla del repositorio es conciso:
## Code Review Rules
### Breaking changes
Search for breaking changes in external integration surfaces:
- raw response item events (`rawResponseItem/*`), even while experimentalPara ese diff de ejemplo, un hallazgo de la revisión de código podría decir:
Conserva la notificación
rawResponseItem/completedexistente. Los consumidores de Codex Cloud escuchan este nombre en el protocolo, por lo que cambiarlo hará que fallen aunque el evento sea experimental. Conserva el nombre existente o agrega un evento retrocompatible, como se describe enAGENTS.md.
El equipo de Codex agregó esta regla específicamente para proteger a los consumidores de Codex Cloud. Mantén las reglas que se aplican a todo el repositorio en la raíz y las específicas de cada servicio en el directorio correspondiente. Durante la revisión, Codex puede aplicar las instrucciones que abarcan los archivos modificados e indicar a los autores la regla pertinente; un cambio no relacionado no necesita el contexto de app-server.
Las reglas complementan las otras herramientas en las que los equipos ya confían. Las pruebas y los linters funcionan bien para las comprobaciones que puedes expresar de forma determinista; las reglas del repositorio ayudan a plasmar los criterios que son más difíciles de codificar. Los requisitos de compatibilidad y los límites de uso de los datos son buenos puntos de partida. Los autores no necesitan conocer todos los incidentes anteriores ni las convenciones locales antes de hacer un cambio; las instrucciones pertinentes ya están ahí.
Redactar reglas que funcionen en la práctica
Probamos qué tan bien podía la revisión de código usar las instrucciones del repositorio con un conjunto de evaluaciones que incluía infracciones conocidas de las reglas y contraejemplos seguros. En el conjunto principal, las variantes guiadas por reglas detectaron el 98 % de los hallazgos personalizados requeridos, frente al 58,3 % del control de referencia.
Detectar una infracción de una regla es solo parte del trabajo. También queríamos saber qué sucede cuando varias reglas compiten por la atención o un pull request ya incluye muchos cambios. Probamos tanto infracciones con consecuencias importantes como cambios que no deberían recibir observaciones y 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 las reglas compiten por la atención?
Moderación
¿Los cambios correctos y las excepciones válidas quedan libres de hallazgos innecesarios?
Conservación de capacidades
¿La revisión de código sigue detectando errores comunes que no están contemplados en las reglas del repositorio?
Utilidad práctica
¿Cada hallazgo identifica las instrucciones pertinentes, la ubicación y la prioridad?
También probamos formas habituales de redactar instrucciones, desde listas breves con viñetas hasta secciones a cargo de un equipo específico.
Encontramos 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 instrucciones amplias podían generar ruido con facilidad. Los conjuntos pequeños de reglas con un alcance definido y una forma segura de proceder explícita ayudaron a Codex a concentrarse en lo más útil sin aplicar una regla a cada cambio cercano.
Empieza por una invariante importante que no sea obvia. Plasma una comprobación que los revisores expliquen repetidamente, como un requisito de compatibilidad o un límite de uso de los datos. Si eliminar una regla no cambiaría la revisión, omítela.
Limita el alcance de las reglas al código que rigen. Coloca las instrucciones que se aplican a todo el repositorio en la raíz y las específicas de cada servicio en un archivo AGENTS.md dentro de un subdirectorio. Un alcance acotado evita que las instrucciones no relacionadas compitan por la atención y deja claro quién es responsable.
Indica la invariante y la forma segura de proceder. La regla de rawResponseItem/* identifica el riesgo de compatibilidad. “Conserva el nombre existente o agrega un evento retrocompatible” ofrece a los autores una alternativa clara.
Mantén las reglas vigentes y útiles a largo plazo. Describe resultados, no nombres de funciones que puedan cambiar. Revisa las actualizaciones de las reglas y acota o elimina las instrucciones que generen ruido repetidamente.
Mantén las comprobaciones de formato y otras comprobaciones mecánicas en CI. Reserva las reglas del repositorio para las preguntas que, de otro modo, un revisor tendría que volver a hacer.
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 de revisión de código explica cómo habilitarla para un repositorio de GitHub. También puedes solicitar una revisión directamente con @codex review.
Empieza con una explicación que los revisores repitan constantemente o con un error específico del repositorio que tendría consecuencias importantes si pasara inadvertido. Prueba un cambio que deba activar la regla, un contraejemplo seguro y un cambio no relacionado. Comprueba que el primero produzca un hallazgo útil y que los otros no generen ruido; luego ajusta las instrucciones según lo que observes.
La revisión de código de Codex sigue siendo un revisor adicional; las pruebas, las protecciones de ramas y las aprobaciones obligatorias siguen siendo los mecanismos que exigen el cumplimiento.
Si dedicas más tiempo a revisar cambios que a escribirlos, empieza con una comprobación que tu equipo repita constantemente. Agrégala a AGENTS.md y prueba la revisión de código de Codex en tu próximo pull request.