Como usamos habilidades para acelerar a manutenção de software de código aberto

Usamos o Codex para mudar a forma como mantemos os repositórios do OpenAI Agents SDK. Com habilidades definidas no próprio repositório, AGENTS.md e GitHub Actions, transformamos tarefas recorrentes de engenharia em fluxos de trabalho que podemos repetir. É assim que verificamos alterações, preparamos versões, executamos testes de integração dos exemplos e revisamos PRs. Mesmo com uma configuração relativamente simples, conseguimos aumentar a taxa de processamento de PRs nesses repositórios bastante ativos. De 1º de dezembro de 2025 a 28 de fevereiro de 2026, integramos 457 PRs nos dois repositórios, ante 316 nos três meses anteriores, de 1º de setembro a 30 de novembro de 2025. No repositório Python, passamos de 182 para 226 PRs e, no TypeScript, de 134 para 231.

O SDK está disponível em Python e TypeScript. Ele fornece os componentes essenciais para criar aplicativos com agentes de IA. Também permite criar agentes de voz com pouco código usando a Realtime API, vários agentes, ferramentas e controles para intervenção humana. O SDK já é usado em larga escala. Nos períodos recentes de 30 dias analisados até 6 de março de 2026, o pacote Python teve cerca de 14,7 milhões de downloads no PyPI, e o pacote TypeScript, cerca de 1,5 milhão no npm.

A configuração é simples:

• regras do repositório em AGENTS.md
• habilidades do próprio repositório em .agents/skills/
• scripts e referências opcionais dentro dessas habilidades
• GitHub Action do Codex quando o mesmo fluxo de trabalho precisa ser executado na integração contínua (CI)

Essa configuração dá ao Codex uma referência estável sobre o funcionamento do repositório, o que torna as tarefas recorrentes de engenharia mais rápidas e precisas.

Mantenha os fluxos de trabalho no repositório

Nesses repositórios, usamos habilidades para registrar fluxos de trabalho específicos de cada projeto. Uma habilidade é um pequeno pacote de conhecimento operacional que contém um manifesto SKILL.md e, opcionalmente, os diretórios scripts/, references/ e assets/. A documentação de personalização do Codex explica por que isso funciona bem. As habilidades são adequadas para fluxos recorrentes porque podem incluir instruções detalhadas, scripts e referências sem sobrecarregar o contexto inicial do agente.

O agente acessa o conteúdo de cada habilidade em etapas:

• primeiro, vê metadados como name e description
• carrega SKILL.md somente quando seleciona a habilidade
• lê referências ou executa scripts apenas quando necessário

Os dois repositórios do SDK mantêm esses fluxos junto ao código:

• .agents/skills no openai-agents-python
• .agents/skills no openai-agents-js

O repositório Python oferece o ponto de partida mais simples:

• code-change-verification executa as etapas obrigatórias de formatação, lint, verificação de tipos e testes quando há alterações no código ou no comportamento do build.
• docs-sync compara a documentação com o código e identifica o que está faltando, incorreto ou desatualizado.
• examples-auto-run executa os exemplos em modo automático, com logs e recursos para repetir a execução.
• final-release-review compara a tag da versão anterior com a versão candidata atual e verifica se ela está pronta para publicação.
• implementation-strategy define quais garantias de compatibilidade preservar e como implementar a mudança antes de alterar o código de execução ou a API.
• openai-knowledge consulta a documentação atual da API e da plataforma da OpenAI por meio do fluxo oficial do Docs MCP.
• pr-draft-summary sugere um nome para a branch e prepara o título e o rascunho da descrição do PR quando o trabalho está pronto para entrega.
• test-coverage-improver mede a cobertura dos testes, identifica as maiores lacunas e propõe testes de alto impacto.

O repositório JavaScript segue o mesmo padrão, com algumas habilidades específicas para o monorepositório npm e seu processo de publicação:

• changeset-validation verifica se os changesets e os níveis de incremento de versão correspondem às alterações nos pacotes.
• integration-tests publica os pacotes em um registro Verdaccio local e verifica se a instalação e a execução funcionam nos ambientes de execução compatíveis.
• pnpm-upgrade atualiza em conjunto as ferramentas do pnpm e as versões fixadas na CI.

O padrão importa mais do que a lista em si. Cada habilidade tem um escopo delimitado, uma condição clara para ser acionada e um resultado concreto.

Algumas das habilidades mais úteis orientam o trabalho sem bloquear seu andamento. docs-sync e test-coverage-improver começam com um relatório. Elas examinam o diff atual ou os artefatos de cobertura, priorizam o que importa e pedem aprovação antes de editar arquivos. No repositório Python, docs-sync também usa as docstrings e os comentários do código-fonte como fonte oficial da documentação de referência gerada, evitando ajustes manuais nos arquivos gerados. A habilidade pnpm-upgrade, exclusiva do repositório JavaScript, é outro exemplo de fluxo de manutenção com escopo delimitado. Ela atualiza em conjunto a versão local do pnpm, packageManager e as versões fixadas nos fluxos de trabalho, sem recorrer a uma busca e substituição geral.

Defina quando os fluxos de trabalho são obrigatórios

As habilidades ganham utilidade quando o repositório exige seu uso no momento certo. É para isso que usamos AGENTS.md.

O guia de AGENTS.md explica que esses arquivos contêm instruções do repositório que acompanham o código e já se aplicam antes de o agente começar a trabalhar. O guia também recomenda que sejam curtos. Nos repositórios do Agents SDK, reservamos esse espaço para as regras que o Codex deve seguir sempre e colocamos as mais importantes perto do início.

Na prática, os dois repositórios usam regras condicionais curtas para indicar quando uma habilidade é obrigatória. Antes de alterar o código de execução ou a API, acione $implementation-strategy para definir as garantias de compatibilidade e a abordagem de implementação. Se a alteração afetar o código do SDK, os testes, os exemplos ou o comportamento do build, acione $code-change-verification. Se uma mudança em um pacote JavaScript afetar os metadados da versão, acione $changeset-validation. Se o trabalho envolver a API da OpenAI ou integrações com a plataforma, acione $openai-knowledge. Quando o trabalho estiver concluído e pronto para entrega, acione $pr-draft-summary.

Essa estrutura também segue as recomendações de agents.md: reúna em um só lugar a visão geral do projeto, os comandos de build e teste, o estilo de código, as orientações sobre testes, as considerações de segurança e as demais regras específicas do repositório. Os repositórios do Agents SDK seguem essa estrutura e destacam logo no início as condições que acionam os fluxos mais importantes no dia a dia. Veja uma versão resumida:

# AGENTS.md

## Project overview

- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.

## Mandatory skill usage

- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.

## Build and test commands

- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`

## Compatibility rules

- Preserve positional compatibility for public constructors and dataclass fields.

Os arquivos usados nos projetos acrescentam detalhes específicos a essa base. É o caso de $changeset-validation no repositório JavaScript e das orientações mais detalhadas sobre execução, documentação e publicação nos dois arquivos. Para ver os exemplos completos, consulte AGENTS.md no openai-agents-python e AGENTS.md no openai-agents-js.

AGENTS.md também serve para registrar outras regras. O repositório Python inclui ali uma regra de compatibilidade da API pública: preserve o significado de cada posição na lista de parâmetros dos construtores exportados e nos campos das dataclasses, acrescente novos parâmetros ou campos opcionais ao final sempre que possível e adicione testes de compatibilidade se for inevitável mudar a ordem. É uma prática que vale adotar: mantenha as regras de compatibilidade essenciais para publicar uma versão no mesmo lugar que as condições de acionamento das habilidades.

Regras de verificação

Um exemplo claro é $code-change-verification.

Nos dois repositórios, a regra tem uma condição. Em vez de “execute sempre uma longa sequência de validações”, a instrução é “execute a sequência quando houver mudanças no código de execução, nos testes, nos exemplos ou no comportamento do build ou dos testes. Só marque o trabalho como concluído quando todas as verificações passarem”.

A condição evita sobrecarregar as mudanças que só afetam a documentação. A obrigatoriedade garante que alterações no código do SDK passem pelas verificações padrão do repositório.

As próprias habilidades definem as etapas de verificação.

No repositório Python, a habilidade exige:

make format
make lint
make typecheck
make tests

No repositório JavaScript, a habilidade exige esta ordem exata:

pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test

A habilidade define o que o repositório considera “verificado”, e AGENTS.md torna obrigatório cumprir esse critério.

Validação de changesets

O repositório JavaScript exige mais uma etapa para mudanças nos pacotes: $changeset-validation, baseada em Changesets.

Quando algo muda em packages/ ou em .changeset/, executar os testes é apenas parte do trabalho do modelo. Ele precisa criar ou atualizar o changeset adequado, validar o nível de incremento da versão e confirmar que o changeset corresponde ao diff.

Além de verificar a existência de um arquivo, a habilidade orienta o Codex a avaliar o diff do Git. As regras de validação ficam em um prompt compartilhado para que as execuções locais e o GitHub Actions usem a mesma lógica. A habilidade também define regras específicas do repositório:

• se a branch já tiver um changeset, use o existente em vez de criar outro
• escreva o resumo em uma linha no estilo Conventional Commit para que também possa servir de título do commit
• antes da versão 1.0, evite incrementar a versão principal ao desenvolver funcionalidades de rotina e trate como mudanças de patch as adições identificadas explicitamente como exclusivas da prévia, desde que preservem o comportamento existente
• valide o nível de incremento de versão exigido com base nas alterações efetivas do pacote

Assim, o Codex precisa validar os metadados da versão que ele próprio cria antes de declarar o trabalho concluído.

Consulte a documentação atual

Os dois repositórios também exigem $openai-knowledge quando o trabalho envolve a API da OpenAI ou integrações com a plataforma.

Essa habilidade fornece uma interface simples para o OpenAI Docs MCP oficial. Em vez de deixar o modelo responder de memória, ela orienta o Codex a consultar o servidor MCP da documentação para desenvolvedores da OpenAI. Assim, ele obtém informações atuais sobre recursos como a Responses API, ferramentas, streaming, Realtime e MCP.

Se o servidor MCP ainda não estiver configurado no ambiente local do Codex, a habilidade encaminha os mantenedores ao guia de início rápido do Docs MCP e ao endpoint oficial do servidor MCP.

Prepare o PR para revisão

Ao concluir um trabalho significativo, os dois repositórios usam $pr-draft-summary.

Essa habilidade só é acionada quando a tarefa está praticamente concluída ou pronta para revisão e envolve mudanças relevantes no código, nos testes, nos exemplos, na documentação que afeta o comportamento ou na configuração de build ou testes. A habilidade coleta automaticamente o nome da branch, o estado da árvore de trabalho, os arquivos alterados, as estatísticas do diff e os commits recentes. Com essas informações, ela produz:

• uma sugestão de nome para a branch
• um título para o PR
• um rascunho da descrição do PR

O formato da saída é fixo por escolha nossa. Veja um resultado típico:

# Pull Request Draft

## Branch name suggestion

git checkout -b fix/tracing-lazy-init-fork-safety

## Title

fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards

## Description

This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.

It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.

It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.

This pull request resolves #2489.

Quando você já confia no modelo para validar e resumir o próprio trabalho, pedir que ele prepare o rascunho do PR é um passo final natural. Assim, a entrega segue um padrão e há menos texto repetitivo para escrever depois de concluir o código.

Escreva descrições melhores

O campo description no frontmatter de SKILL.md faz parte das regras que determinam qual habilidade acionar.

Esse campo tem uma função estrutural. A especificação de habilidades de agentes exige os campos name e description no frontmatter de SKILL.md. Segundo o modelo de carregamento progressivo da especificação, esses campos são carregados na inicialização para todas as habilidades. O conteúdo completo de SKILL.md e os diretórios scripts/, references/ ou assets/, quando presentes, só são carregados mais tarde, quando a habilidade é ativada.

A documentação de habilidades do Codex e a documentação de personalização descrevem como isso funciona no Codex. Ele usa inicialmente os metadados para identificar as habilidades disponíveis, carrega SKILL.md somente quando seleciona uma habilidade e só lê referências ou executa scripts quando necessário. O guia sobre habilidades no cookbook da API da OpenAI explica o funcionamento no shell hospedado com a mesma clareza. A OpenAI lê primeiro os campos name e description e o caminho de cada habilidade. O modelo usa essas informações para decidir quando ler o SKILL.md completo. A seção sobre o frontmatter de SKILL.md é ainda mais direta: name e description são importantes para identificar as habilidades disponíveis e selecionar a adequada.

Nos repositórios do Agents SDK, description é, portanto, um dos principais critérios que o Codex usa para selecionar uma habilidade antes de ler o restante do conteúdo.

Veja um exemplo concreto de code-change-verification.

Descrição vaga demais:

description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.

Descrição mais precisa, usada no repositório:

description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.

A versão mais curta já diz ao Codex o que a habilidade faz, mas ainda deixa dúvidas sobre quando usá-la, quais mudanças devem acioná-la e se as verificações são opcionais. A versão mais específica esclarece os três pontos.

O mesmo padrão aparece em pr-draft-summary.

Descrição vaga demais:

description: Create a PR title and draft description for a pull request.

Descrição mais precisa, usada no repositório:

description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.

Aqui também a descrição usada no repositório funciona como metadado de seleção. Ela informa ao Codex que:

• a habilidade deve ser usada ao final da tarefa
• seu uso depende de mudanças significativas, e não de cada interação no chat
• a saída deve ser um bloco pronto para o PR, com mais do que um resumo em prosa

Uma lição prática desses repositórios é dedicar tempo ao campo description. Se o Codex estiver selecionando habilidades de forma inconsistente, ajuste os metadados antes de acrescentar mais código.

Use scripts para as etapas mecânicas

O próximo passo é decidir o que cabe ao modelo e o que convém implementar em um script.

Uma divisão que funciona bem é:

• deixar a interpretação, a comparação e a elaboração de relatórios com o modelo
• colocar em scripts/ as tarefas de shell repetitivas e determinísticas

Essa divisão segue as orientações públicas. A documentação de personalização do Codex explica que as habilidades podem fornecer ao Codex instruções detalhadas, scripts e referências para fluxos recorrentes sem sobrecarregar o contexto inicial. Isso favorece uma configuração em que o Codex cuida das partes que dependem do contexto e recorre a scripts para as etapas determinísticas somente quando necessário. O guia sobre habilidades no cookbook da API da OpenAI também recomenda projetar os scripts das habilidades como pequenas CLIs. Eles devem funcionar pela linha de comando, produzir resultados determinísticos em stdout, indicar claramente as falhas com instruções de uso ou mensagens de erro e, quando necessário, gravar os resultados em caminhos conhecidos.

Nos repositórios do Agents SDK, procuramos usar o modelo nas tarefas que de fato exigem sua capacidade de análise, por exemplo:

• ler o código-fonte para inferir o comportamento pretendido
• comparar os logs com esse comportamento
• avaliar se o diff de uma versão apresenta um risco real de compatibilidade
• explicar o resultado de modo que o mantenedor saiba como agir

Os scripts cuidam das etapas mecânicas que dão suporte a esse trabalho, por exemplo:

• executar os comandos de verificação exigidos pelo repositório em uma ordem fixa
• iniciar a execução dos exemplos, coletar logs individuais e gravar arquivos que permitam executar novamente os exemplos que falharam
• buscar a tag da versão anterior antes de avaliar se a próxima versão está pronta para publicação
• disponibilizar comandos auxiliares como start, stop, status, logs, tail, collect e rerun para facilitar a repetição do mesmo fluxo

Se o modelo precisa redescobrir a mesma sequência de comandos de shell a cada execução, provavelmente vale transformá-la em um script. Se parte da tarefa depende do contexto, da ponderação de alternativas ou de uma explicação, deixe essa parte com o modelo.

Automatize os testes de integração

Os testes de integração automatizados estão entre os fluxos mais úteis nos dois repositórios. A validação ocorre em duas camadas relacionadas. Em ambos os repositórios, validamos automaticamente os exemplos que acompanham o código. No repositório JavaScript, também verificamos separadamente se os pacotes publicados continuam funcionando quando instalados da mesma forma que os usuários os instalam.

Antes de adotarmos essa configuração, parte da validação dos exemplos era manual. Era possível executar os exemplos, mas a etapa final muitas vezes exigia ler os logs ou inspecionar a saída para decidir se o resultado parecia correto. Isso é viável para um exemplo isolado, mas fica difícil à medida que o repositório do SDK cresce.

A primeira camada é examples-auto-run, mas o executor de exemplos veio antes da habilidade. Para automatizar a validação, primeiro tivemos que implementar nos dois repositórios o suporte à execução não interativa. Isso exigiu permitir que os scripts de exemplo fossem executados em modo automático, inclusive os que normalmente pedem uma resposta ou aprovação.

Essa preparação incluiu:

• responder automaticamente aos prompts interativos mais comuns
• aprovar automaticamente ações que exigem intervenção humana (HITL), ações de MCP, apply_patch e ações de shell quando o executor oferece esse suporte
• manter uma lista de exemplos que o modo automático deve ignorar por ainda serem inadequados à automação, como os exemplos em tempo real ou de aplicativos Next.js que precisam de configuração adicional no ambiente de execução
• gravar logs estruturados para cada execução de um exemplo
• gerar arquivos de reexecução para repetir os exemplos que falharam sem precisar executar tudo de novo

Com essa base pronta, organizamos o fluxo como uma habilidade para facilitar seu acionamento e sua reutilização. No repositório Python, examples-auto-run aciona uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir .... No repositório JavaScript, a habilidade executa as verificações de build e depois roda pnpm examples:start-all em modo automático, com logs individuais por exemplo e suporte à reexecução.

Para melhorar a qualidade da validação, o executor fica responsável por executar os exemplos e registrar stdout e stderr nos logs de cada um. Em seguida, a habilidade orienta o Codex a examinar esses logs um por um e compará-los com o código-fonte:

• ler o código-fonte e os comentários do exemplo
• inferir o fluxo pretendido
• abrir o log correspondente
• comparar o comportamento pretendido com o conteúdo registrado em stdout e stderr
• repetir a análise para cada exemplo executado com sucesso, em vez de verificar apenas uma amostra

Essa abordagem é mais precisa e flexível do que tentar definir o que está correto por meio de uma asserção fixa em um script. Um código de saída que indica sucesso é útil, mas é insuficiente para exemplos que chamam APIs reais, usam ferramentas ou produzem saídas estruturadas. Ao registrar primeiro a saída real e depois compará-la cuidadosamente com o código-fonte, conseguimos validar cada exemplo de acordo com o que ele se propõe a demonstrar.

No repositório JavaScript, há uma segunda camada, implementada pela habilidade integration-tests. Esse fluxo vai além de executar os exemplos diretamente no repositório. Ele publica os pacotes em um registro Verdaccio local e testa a instalação e a execução em vários ambientes, incluindo Node.js, Bun, Deno, Cloudflare Workers e um aplicativo React com Vite. Isso revela outra categoria de problemas. A primeira camada responde à pergunta “o exemplo roda no repositório?”. A segunda responde à pergunta “o pacote continua funcionando corretamente depois de publicado, instalado e integrado ao ambiente de execução?”.

Juntos, esses fluxos mostram o valor de combinar habilidades, scripts e a capacidade de análise do modelo. Os scripts tornam as execuções repetíveis, registram as evidências e cobrem formas de instalação que seriam trabalhosas de verificar manualmente. Com essas evidências, o Codex faz uma comparação mais criteriosa do que uma verificação por script que apenas indica sucesso ou falha.

Adicione verificações antes da publicação

A preparação de versões é outra área em que esse padrão ajuda.

Nos dois repositórios, o fluxo de revisão de versões começa localizando a tag da versão anterior e gerando o diff em relação ao estado mais recente de main. Em seguida, o Codex examina o diff em busca de:

• problemas de compatibilidade com versões anteriores nas APIs públicas e no comportamento do SDK percebido pelos usuários
• regressões, inclusive pequenas alterações no comportamento esperado
• mudanças que exigem notas de migração ou atualizações nas notas da versão e ainda não foram documentadas

Com base nos resultados, a habilidade avalia se a versão como um todo está pronta para publicação.

Um exemplo concreto é openai/openai-agents-python#2480. A revisão dá sinal verde para a publicação, mas destaca o fim do suporte ao Python 3.9 e a necessidade de registrá-lo nas notas da versão:

Release readiness review (excerpt)

Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.

Scope summary:

- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
  `src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
  `pyproject.toml`, `uv.lock`.

Python 3.9 support removed

- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
  0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
  the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
  packaging metadata remains `>=3.10`.

A habilidade também define os critérios para bloquear uma publicação. A revisão parte da avaliação “é seguro publicar” e só bloqueia a versão quando o diff apresenta evidências concretas de um problema real. Toda decisão de bloqueio deve vir acompanhada de uma lista específica de ações para liberar a publicação. Isso facilita o uso do resultado. O sinal verde indica que a revisão do diff não encontrou nenhum impedimento à publicação. O bloqueio indica que existe um problema real e que há um próximo passo bem definido.

Isso é mais útil do que um pedido genérico como “revise a versão”. O modelo precisa analisar um diff concreto e explicar como proceder. Se for seguro publicar a versão, diga isso. Se houver um impedimento, indique a evidência exata e a ação necessária.

Execute os fluxos de trabalho na CI

Quando uma habilidade já funciona bem localmente, a GitHub Action do Codex facilita a automação do mesmo fluxo na CI. Isso funciona melhor quando o fluxo local já está estável, pois é no uso manual que você identifica problemas nas instruções, refina os scripts e descobre os casos extremos que ocorrem na prática.

Nos repositórios públicos, definir como o fluxo pode ser acionado é tão importante quanto definir a habilidade. A lista de verificação de segurança da GitHub Action recomenda limitar quem pode iniciar o fluxo, dar preferência a eventos confiáveis ou aprovações explícitas, sanitizar os dados de PRs, commits, issues ou comentários que entram nos prompts, proteger OPENAI_API_KEY com drop-sudo ou com um usuário sem privilégios e executar o Codex na última etapa do job.

Se um fluxo tem permissão de escrita e recebe dados públicos de fontes não confiáveis, o risco geralmente está nas condições de acionamento, no tratamento dos dados de entrada e nos privilégios com que a habilidade é executada.

Use o Codex na revisão de PRs

As habilidades explicam parte do ganho de produtividade nesses repositórios. Outra parte vem da revisão automática de PRs pelo Codex no GitHub.

Desde que a revisão automática de PRs pelo Codex ficou disponível no GitHub, ele tem ajudado a revisar a maioria das alterações de código nesses repositórios. A revisão pelo Codex passou a fazer parte da rotina.

Para bugs simples, regressões e testes ausentes, a experiência mostrou que já é suficientemente seguro adotar o Codex como revisor obrigatório. Ele verifica de forma consistente os mesmos critérios de correção, mesmo em tarefas repetitivas. Isso eliminou um gargalo importante nas pequenas correções e nas melhorias de rotina.

A revisão por pares continua importante para outro conjunto de mudanças.

A revisão humana é essencial quando a principal questão vai além de “este código está correto?” e passa a ser “qual destas opções válidas devemos escolher e como devemos disponibilizá-la?”. Isso inclui:

• mudanças de API ou arquitetura com várias soluções razoáveis, em que os mantenedores precisam fazer uma escolha explícita
• mudanças de comportamento que afetam as expectativas sobre o produto, as garantias de compatibilidade com versões anteriores ou a política de disponibilização gradual
• decisões sobre nomes, migração e comunicação de versões em que o desafio é escolher a opção mais clara para usuários e colaboradores
• mudanças que exigem acordo entre mantenedores ou equipes, por exemplo, para delimitar o escopo do trabalho, definir a ordem das etapas ou decidir o que publicar agora e o que deixar para depois

O Codex também pode contribuir em todos esses casos, mas a discussão direta e a participação de uma pessoa responsável pela decisão continuam valiosas.

AGENTS.md também pode registrar essa divisão de responsabilidades. O repositório pode indicar ao Codex quais critérios importam para verificar se o código está correto, e o Codex pode aplicá-los de forma consistente.

Essa mudança também contribuiu bastante para aumentar a taxa de processamento de PRs. A cada alteração de baixo risco, as revisões e validações repetitivas já não precisam esperar que um revisor tenha tempo disponível. Os mantenedores podem se concentrar nas revisões que exigem mais contexto e nas quais seu julgamento faz mais diferença. Com isso, conseguimos corrigir bugs acumulados e implementar pequenas melhorias de funcionalidade com muito mais rapidez.

Considerações finais

Nos repositórios do OpenAI Agents SDK, as habilidades funcionam melhor quando fazem parte da rotina do projeto.

AGENTS.md informa ao Codex quais fluxos de trabalho são obrigatórios. description indica quando acioná-los. Os scripts em scripts/ cuidam das etapas determinísticas. O modelo cuida das etapas que dependem do contexto. Quando o fluxo já funciona bem localmente, a GitHub Action do Codex permite executar o mesmo processo na CI.

Com isso, as tarefas diárias de engenharia nesses repositórios passaram a seguir regras mais explícitas e confiáveis. Também ficou mais fácil entregar pequenas melhorias com rapidez, porque a verificação, a revisão de versões e a preparação dos PRs para revisão agora seguem um processo que podemos repetir.

Recursos

• OpenAI Agents SDK para Python
• OpenAI Agents SDK para JS
• Habilidades no Codex
• Instruções personalizadas com AGENTS.md
• GitHub Action do Codex
• Como usar o Codex no GitHub
• Habilidades no cookbook da API da OpenAI
• Especificação de habilidades de agentes
• Habilidades na API da OpenAI: práticas operacionais recomendadas