Regras personalizadas de revisão de código para o Codex

Ao revisar código com o Codex, alguns comentários se repetem. Eles podem tratar da preservação de um contrato antigo de API, de manter dados de clientes fora dos logs ou de evitar uma renomeação que quebraria outro serviço. Essas verificações são importantes, mas é fácil deixá-las passar quando só alguns revisores conhecem o contexto.

A revisão de código do Codex agora pode usar regras personalizadas do repositório em AGENTS.md para detectar esses problemas e indicar aos autores a orientação que fundamenta um apontamento. Se você já usa AGENTS.md para orientar tarefas de programação, o mesmo arquivo também pode ajudar a orientar as revisões. Isso é especialmente útil quando colaboradores ou agentes de programação trabalham em uma parte do repositório que não conhecem e talvez ainda não saibam seu histórico. Neste artigo, mostraremos onde as regras do repositório se encaixam e como escrevê-las bem, incluindo o que aprendemos ao testá-las.

Entregando mais código

Agentes de programação podem assumir mudanças maiores e trabalhar por períodos mais longos, ajudando as equipes a transformar mais ideias em código. Na OpenAI, o volume semanal de PRs mais que dobrou desde o quarto trimestre, e observamos tendências semelhantes entre muitos dos nossos clientes. Mais código é bom: ajuda as equipes a lançar novos recursos e resolver mais problemas. Isso também significa mais pull requests à espera de alguém que saiba o que procurar, e a revisão de código pode rapidamente se tornar o gargalo.

A revisão fica mais difícil quando várias mudanças chegam ao mesmo tempo. Um diff pode parecer perfeitamente razoável e ainda assim quebrar um cliente antigo ou ultrapassar um limite que o autor desconhecia. Alguém precisa lembrar desse contexto e compartilhá-lo enquanto o autor ainda pode agir com base nele.

O gargalo da revisão

Quando chegam mais pull requests, os revisores têm menos tempo para entender o objetivo de cada mudança e reunir o contexto relevante antes de dar feedback. Depois que o autor passa a trabalhar em outra coisa, até um pequeno ajuste pode levar mais tempo. O feedback rápido ajuda as equipes a aproveitar ao máximo um desenvolvimento mais ágil sem transformar as pessoas no gargalo.

Alguns problemas também são difíceis de identificar apenas pelo diff. Renomear um campo de resposta pode parecer uma limpeza rotineira no código, mas pode quebrar clientes que ainda dependem do contrato existente. Um revisor experiente talvez se lembre de por que esse campo precisa ser mantido; um novo colaborador ou um agente trabalhando no serviço pela primeira vez provavelmente não.

Regras como interface

Então, como dar a um agente de programação o contexto que sua equipe normalmente adquire com o tempo? A nova interface de regras do repositório permite inserir orientações de revisão concisas e com escopo delimitado em AGENTS.md. A revisão de código do Codex pode aplicar as regras relevantes para uma mudança e citá-las em um apontamento. Em vez de repetir a mesma explicação em cada pull request, você pode mantê-la perto do código ao qual ela se aplica.

À medida que os modelos de programação respondem melhor às orientações, uma instrução curta e com escopo bem definido pode ajudar a concentrar uma revisão longa no que realmente importa para sua equipe. O próprio repositório do Codex mantém regras de revisão de código em AGENTS.md, abordando questões como o contexto visível para o modelo e mudanças que quebram a compatibilidade.

Veja um exemplo real:

O app-server do Codex emite uma notificação interna chamada rawResponseItem/completed. Ela está marcada como experimental, mas o Codex Cloud já a consome. A regra do repositório para revisar mudanças que quebram a compatibilidade cita explicitamente rawResponseItem/* como uma interface de integração que os revisores devem preservar, mesmo enquanto for experimental.

O nome atual usado na comunicação está definido no protocolo do app-server. Imagine que uma limpeza no código alterasse uma linha:

-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"

O código compila com a mudança, mas os clientes que escutam a notificação existente deixariam de recebê-la. O trecho relevante da regra do repositório é conciso:

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

Para esse diff ilustrativo, um apontamento da revisão de código poderia dizer:

Mantenha a notificação existente rawResponseItem/completed. Os consumidores do Codex Cloud escutam esse nome no protocolo, então renomeá-lo quebrará seu funcionamento, mesmo que o evento seja experimental. Mantenha o nome existente ou adicione um evento retrocompatível, conforme descrito em AGENTS.md.

A equipe do Codex adicionou essa regra especificamente para proteger os consumidores do Codex Cloud. Mantenha as regras que se aplicam a todo o repositório na raiz e as regras específicas de cada serviço no diretório correspondente. Durante a revisão, o Codex pode aplicar as orientações que abrangem os arquivos alterados e indicar aos autores a regra relevante; uma mudança sem relação com o app-server não precisa do contexto dele.

As regras complementam as outras ferramentas que as equipes já usam. Testes e linters funcionam bem para verificações que podem ser expressas de forma determinística; as regras do repositório ajudam a registrar critérios de julgamento mais difíceis de codificar. Requisitos de compatibilidade e limites de uso de dados são bons pontos de partida. Os autores não precisam conhecer todos os incidentes passados ou convenções locais antes de fazer uma mudança; as orientações relevantes já estão disponíveis.

Escrevendo regras que funcionam na prática

Testamos a capacidade da revisão de código de usar as orientações do repositório com um conjunto de avaliações que incluía violações conhecidas de regras e contraexemplos seguros. No conjunto principal, as variantes orientadas por regras identificaram 98% dos apontamentos personalizados esperados, em comparação com 58,3% no controle de referência.

Encontrar uma violação de regra é apenas parte do trabalho. Também queríamos saber o que acontece quando várias regras disputam atenção ou um pull request já tem muitas mudanças. Testamos tanto violações com consequências importantes quanto mudanças que não deveriam receber apontamentos e, em seguida, organizamos os resultados em torno de quatro perguntas:

Também experimentamos formas conhecidas de escrever orientações, desde listas curtas com marcadores até seções sob a responsabilidade de uma equipe específica.

Encontramos o mesmo padrão ao usar regras em repositórios internos. O Codex conseguia encontrar e citar orientações locais que uma revisão padrão poderia deixar passar, mas instruções amplas podiam facilmente gerar ruído. Conjuntos pequenos de regras, com escopo delimitado e uma alternativa segura explícita, ajudaram o Codex a se concentrar no que era mais útil sem aplicar uma regra a toda mudança próxima.

Comece com um invariante importante e não óbvio. Registre uma verificação que os revisores explicam repetidamente, como um requisito de compatibilidade ou um limite de uso de dados. Se remover uma regra não mudaria a revisão, deixe-a de fora.

Limite o escopo das regras ao código que elas regem. Coloque as orientações para todo o repositório na raiz e as orientações específicas de cada serviço em um AGENTS.md dentro do subdiretório correspondente. Um escopo restrito evita que instruções sem relação entre si disputem atenção e deixa claro quem é responsável.

Declare o invariante e a alternativa segura. A regra de rawResponseItem/* identifica o risco de compatibilidade. “Mantenha o nome existente ou adicione um evento retrocompatível” oferece aos autores uma alternativa clara.

Mantenha as regras duradouras e atualizadas. Descreva resultados, não nomes de funções que podem mudar. Revise as atualizações das regras e restrinja ou remova orientações que geram ruído repetidamente.

Mantenha a formatação e outras verificações mecânicas na CI. Reserve as regras do repositório para as perguntas que um revisor teria que fazer de novo.

Primeiros passos

Se a revisão de código do Codex já estiver ativada no seu repositório, adicione duas ou três regras ao arquivo AGENTS.md correspondente e abra um pull request representativo. Se você está começando a usar a revisão de código, o guia de início rápido de revisão de código explica como ativá-la em um repositório do GitHub. Você também pode solicitar uma revisão diretamente com @codex review.

Comece com uma explicação que os revisores repetem ou com um erro específico do repositório que teria consequências importantes se passasse despercebido. Experimente uma mudança que deva acionar a regra, um contraexemplo seguro e uma mudança sem relação com ela. Verifique se a primeira gera um apontamento útil e se as outras não geram ruído; depois, refine as orientações com base no que observar.

A revisão de código do Codex continua sendo uma revisão adicional; testes, proteções de branch e aprovações obrigatórias continuam impondo o cumprimento dos requisitos.

Se você percebe que passa mais tempo revisando mudanças do que escrevendo código, comece com uma verificação que sua equipe repete com frequência. Adicione-a a AGENTS.md e experimente a revisão de código do Codex no seu próximo pull request.