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

Nas revisões de código com o Codex, alguns comentários se repetem. Pode ser um lembrete para preservar um contrato de API antigo, manter dados de clientes fora dos logs ou evitar uma mudança de nome que faria outro serviço parar de funcionar. Essas verificações são importantes, mas é fácil deixá-las passar quando só alguns revisores conhecem o contexto.

Agora, a revisão de código do Codex pode usar regras personalizadas do repositório definidas em AGENTS.md para identificar esses problemas e indicar aos autores qual orientação fundamenta cada apontamento. Se você já usa AGENTS.md para orientar tarefas de programação, o mesmo arquivo também pode orientar as revisões. Isso é especialmente útil quando colaboradores ou agentes de programação trabalham em uma parte do repositório que ainda não conhecem bem e talvez não saibam por que certas decisões foram tomadas. Neste artigo, mostramos onde usar as regras do repositório e como escrevê-las, com base no que aprendemos ao testá-las.

Entregando mais código

Os agentes de programação conseguem assumir mudanças maiores e trabalhar por períodos mais longos, o que ajuda 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. Com mais código, as equipes conseguem lançar novos recursos e resolver mais problemas. Também há mais pull requests à espera de alguém que saiba o que verificar, e a revisão de código pode rapidamente se tornar um 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 a compatibilidade com 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 ajustar a mudança.

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 necessário antes de comentar. Depois que o autor passa para outra tarefa, até um pequeno ajuste pode demorar mais. Receber comentários rapidamente ajuda a equipe a aproveitar o ritmo mais acelerado de desenvolvimento sem sobrecarregar quem faz a revisão.

Também há problemas difíceis de identificar só pelo diff. Renomear um campo de resposta pode parecer um ajuste de rotina, mas a mudança pode fazer com que clientes que ainda dependem do contrato atual parem de funcionar. Um revisor experiente talvez se lembre de por que o campo precisa manter o nome. Quem acabou de começar a contribuir, ou um agente que trabalha no serviço pela primeira vez, provavelmente desconhece o motivo.

Regras como interface

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

À medida que os modelos de programação respondem melhor a instruções, uma orientação curta e de escopo bem definido pode direcionar uma revisão longa para o que realmente importa para a equipe. O próprio repositório do Codex mantém regras de revisão de código em AGENTS.md. Elas tratam de questões como o contexto visível ao modelo e as 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 menciona explicitamente rawResponseItem/* como um ponto de integração que os revisores devem preservar, mesmo enquanto os eventos forem experimentais.

O protocolo do app-server define o nome usado para transmitir a notificação. Imagine que alguém altere uma linha ao reorganizar o código.

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

O código compila, mas os clientes que escutam a notificação pelo nome atual deixariam de recebê-la. O trecho da regra do repositório que se aplica aqui é curto.

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

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

Para o diff desse exemplo, a revisão de código poderia apontar o seguinte problema:

Mantenha a notificação rawResponseItem/completed com o nome atual. Os consumidores do Codex Cloud escutam esse nome no protocolo. Se ele mudar, deixarão de receber a notificação, mesmo que o evento seja experimental. Mantenha o nome atual ou adicione um evento compatível com versões anteriores, conforme a orientação em AGENTS.md.

A equipe do Codex adicionou essa regra especificamente para proteger os consumidores do Codex Cloud. Mantenha na raiz as regras que valem para todo o repositório e, no diretório correspondente, as regras específicas de cada serviço. 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 dispensa esse contexto.

As regras complementam as ferramentas que as equipes já usam. Testes e linters funcionam bem para verificações que você consegue expressar de forma determinística. As regras do repositório ajudam a registrar critérios de revisão mais difíceis de traduzir em código. Requisitos de compatibilidade e limites para o uso de dados são bons pontos de partida. Os autores podem fazer uma mudança sem precisar conhecer todos os incidentes anteriores ou todas as convenções locais, pois as orientações relevantes já estão no repositório.

Como escrever regras que continuam úteis

Para testar até que ponto a revisão de código conseguia aplicar as orientações do repositório, usamos um conjunto de avaliações que incluía violações conhecidas das regras e contraexemplos seguros. No conjunto principal, as variantes que usaram as regras identificaram 98% dos problemas que deveriam apontar com base nas regras personalizadas, contra 58,3% no grupo de controle.

Identificar uma violação é só parte do trabalho. Também queríamos saber o que acontece quando várias regras disputam a atenção do revisor ou quando um pull request já reúne muitas mudanças. Testamos tanto violações com consequências importantes quanto mudanças que dispensavam comentários. Depois, organizamos os resultados em torno de quatro perguntas.

Também experimentamos formatos conhecidos para registrar orientações, desde listas curtas de tópicos até seções sob a responsabilidade de uma equipe específica.

Observamos o mesmo padrão ao usar regras em repositórios internos. O Codex conseguia encontrar e citar orientações locais que poderiam passar despercebidas em uma revisão padrão, mas instruções muito amplas facilmente geravam comentários desnecessários. Com poucas regras de escopo delimitado e uma alternativa segura explícita, o Codex conseguia se concentrar no que era mais útil sem aplicar uma regra a toda mudança em trechos de código próximos.

Comece com uma condição importante e pouco óbvia que o código precisa preservar. Registre uma verificação que os revisores precisam explicar com frequência, como um requisito de compatibilidade ou um limite para o uso de dados. Se remover a regra não fizer diferença na revisão, deixe-a de fora.

Limite cada regra ao código ao qual ela se aplica. Coloque as orientações gerais na raiz do repositório e as específicas de um serviço em um arquivo AGENTS.md no subdiretório correspondente. Um escopo delimitado evita que instruções sem relação com a mudança disputem atenção e deixa claro quem responde por elas.

Explique o que precisa ser preservado e como fazer a mudança com segurança. A regra sobre rawResponseItem/* identifica o risco de incompatibilidade. A orientação “Mantenha o nome atual ou adicione um evento compatível com versões anteriores” oferece aos autores uma alternativa clara.

Escreva regras que continuem válidas e mantenha-as atualizadas. Descreva o resultado esperado e evite depender de nomes de funções que podem mudar. Revise as alterações nas regras. Se uma orientação gerar comentários desnecessários com frequência, restrinja seu escopo ou remova-a.

Deixe a verificação de formatação e outras checagens mecânicas na integração contínua. Reserve as regras do repositório para as questões que um revisor teria de levantar repetidamente.

Primeiros passos

Se a revisão de código do Codex já estiver habilitada no seu repositório, adicione duas ou três regras ao arquivo AGENTS.md correspondente e abra um pull request que represente o tipo de mudança que sua equipe costuma fazer. Se você está começando a usar a revisão de código, o guia de início rápido da revisão de código explica como habilitá-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 sempre precisam repetir 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 a regra. Verifique se a primeira gera um apontamento útil e se as outras passam sem comentários desnecessários. Depois, refine a orientação com base no que observar.

O Codex atua como revisor adicional. Os testes, as proteções de branch e as aprovações obrigatórias continuam garantindo o cumprimento dos requisitos.

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