Usar habilidades para acelerar a manutenção de OSS

Usamos o Codex para mudar a forma como mantemos os repositórios do OpenAI Agents SDK. Habilidades locais do repositório, AGENTS.md e GitHub Actions nos permitem transformar tarefas recorrentes de engenharia, como verificação, preparação de versões, testes de integração de exemplos e revisão de PRs, em fluxos de trabalho repetíveis. Mesmo com uma configuração bastante simples, isso nos ajudou a aumentar a taxa de processamento do trabalho de desenvolvimento nesses repositórios ativos. Entre 1º de dezembro de 2025 e 28 de fevereiro de 2026, os dois repositórios tiveram 457 PRs mesclados, contra 316 nos três meses anteriores, de 1º de setembro de 2025 a 30 de novembro de 2025 (Python: 182 -> 226, TypeScript: 134 -> 231).

Para contextualizar, o SDK está disponível em Python e TypeScript. Ele oferece os componentes essenciais para criar aplicativos agênticos e também permite criar, de forma concisa, agentes de voz com base na Realtime API, com múltiplos agentes, ferramentas e controles de participação humana. Seu uso é expressivo: em períodos recentes de 30 dias, com dados até 6 de março de 2026, o pacote Python registrou cerca de 14,7 milhões de downloads no PyPI, e o pacote TypeScript, cerca de 1,5 milhão de downloads no npm.

A configuração é simples:

• política do repositório em AGENTS.md
• habilidades locais do repositório em .agents/skills/
• scripts e referências opcionais dentro dessas habilidades
• Codex GitHub Action quando o mesmo fluxo de trabalho deve ser executado na CI

Essa configuração dá ao Codex um contexto estável sobre o funcionamento do repositório, o que melhora a velocidade e a precisão do trabalho recorrente de engenharia.

Mantenha os fluxos de trabalho no repositório

Nesses repositórios, usamos habilidades para registrar fluxos de trabalho específicos de cada repositório. Uma habilidade é um pequeno pacote de conhecimento operacional: um manifesto SKILL.md, além de scripts/, references/ e assets/ opcionais. A documentação de personalização do Codex explica por que isso funciona bem: habilidades são adequadas para fluxos de trabalho repetíveis porque podem incluir instruções mais completas, scripts e referências sem sobrecarregar o contexto do agente logo de início.

Isso segue o modelo de apresentação progressiva de informações usado pelas habilidades:

• primeiro, o agente vê metadados como name e description
• ele carrega SKILL.md somente quando a habilidade é selecionada
• ele lê referências ou executa scripts somente quando necessário

Os dois repositórios do SDK mantêm esses fluxos de trabalho próximos do código:

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

O repositório Python serve como base mais simples:

• code-change-verification executa as etapas obrigatórias de formatação, análise estática, verificação de tipos e testes quando há alterações no código ou no comportamento da compilação.
• docs-sync audita a documentação em relação à base de código e identifica documentação ausente, incorreta ou desatualizada.
• examples-auto-run executa exemplos no modo automático, com logs e recursos auxiliares para executá-los novamente.
• final-release-review compara a tag da versão anterior com a versão candidata atual e verifica se ela está pronta para lançamento.
• implementation-strategy define os limites de compatibilidade e a abordagem de implementação antes de fazer alterações no código de execução ou na API.
• openai-knowledge obtém a documentação atual da API e da plataforma da OpenAI por meio do fluxo oficial do MCP de documentação.
• pr-draft-summary prepara uma sugestão de nome de branch, um título de PR e um rascunho de descrição na hora de entregar o trabalho.
• test-coverage-improver mede a cobertura de testes, identifica as maiores lacunas e propõe testes de alto impacto.

O repositório JavaScript segue o mesmo padrão geral e acrescenta algumas habilidades específicas para seu monorepositório npm e seu processo de lançamento:

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

Mais importante do que a lista exata é o padrão. Cada habilidade tem um contrato de escopo delimitado, um gatilho claro e um resultado concreto.

Algumas das habilidades mais úteis não são verificações obrigatórias que bloqueiam o avanço. docs-sync e test-coverage-improver são fluxos de trabalho que começam por um relatório: inspecionam as diferenças atuais ou os artefatos de cobertura, priorizam o que importa e pedem aprovação antes de fazer alterações. No repositório Python, docs-sync também trata as docstrings e os comentários do código-fonte como a fonte de verdade para a documentação de referência gerada, em vez de corrigir manualmente o resultado gerado. A habilidade pnpm-upgrade, exclusiva do JavaScript, é outro bom 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, em vez de recorrer a uma busca e substituição generalizada.

Torne os fluxos de trabalho obrigatórios

As habilidades se tornam mais úteis quando o repositório exige seu uso no momento certo. É aí que entra AGENTS.md.

O guia de AGENTS.md descreve esses arquivos como instruções no nível do repositório que acompanham a base de código e se aplicam antes de o agente começar a trabalhar. Ele também recomenda mantê-los curtos. Nos repositórios do Agents SDK, usamos 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 curtas do tipo se/então para exigir o uso de habilidades. Antes de fazer alterações no código de execução ou na API, invoque $implementation-strategy para definir primeiro os limites de compatibilidade e a abordagem de implementação. Se a alteração afetar o código do SDK, testes, exemplos ou o comportamento da compilação, invoque $code-change-verification. Se uma alteração em um pacote JavaScript afetar os metadados da versão, invoque $changeset-validation. Se o trabalho envolver integrações com a API ou a plataforma da OpenAI, invoque $openai-knowledge. Quando o trabalho estiver concluído e pronto para entrega, invoque $pr-draft-summary.

Essa estrutura também segue as recomendações de agents.md: manter a visão geral do projeto, os comandos de compilação e teste, o estilo de código, as orientações de teste, as considerações de segurança e outras regras específicas do repositório em um só lugar. Os repositórios do Agents SDK seguem esse formato, mas começam pelos gatilhos operacionais mais importantes no trabalho diário. Uma versão compacta fica assim:

# 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 reais acrescentam detalhes específicos de cada repositório a essa base, como $changeset-validation no repositório JavaScript e orientações mais detalhadas sobre execução, documentação e lançamento em ambos os arquivos. Para ver exemplos completos, consulte AGENTS.md em openai-agents-python e AGENTS.md em openai-agents-js.

AGENTS.md não serve apenas para definir gatilhos de habilidades. O repositório Python também registra ali uma regra de compatibilidade da API pública: preservar o significado posicional dos parâmetros de construtores e campos de dataclasses exportados, acrescentar novos parâmetros e campos opcionais ao final quando possível e adicionar testes de compatibilidade se a reordenação for inevitável. Esse é outro bom padrão: manter as regras de compatibilidade essenciais para o lançamento no mesmo lugar que os gatilhos das habilidades.

Regras de verificação

Um exemplo claro é $code-change-verification.

Nos dois repositórios, a regra não é "sempre executar uma longa sequência de validações". A regra é "executá-la quando houver alterações no código de execução, nos testes, nos exemplos ou no comportamento de compilação/teste, e não marcar o trabalho como concluído até que todas as validações passem".

A condição mantém leve o trabalho restrito à documentação. A obrigatoriedade garante que alterações no código do SDK passem pelas etapas padrão de verificação do repositório.

As sequências de verificação estão definidas nas próprias habilidades.

No repositório Python, a habilidade exige:

make format
make lint
make typecheck
make tests

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

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

A habilidade registra o que o repositório considera "verificado", e AGENTS.md torna obrigatório cumprir essa definição.

Validação de changesets

O repositório JavaScript tem mais uma etapa obrigatória para alterações em pacotes: $changeset-validation, baseada em Changesets.

Quando algo em packages/ muda, ou quando há alterações em .changeset/, o modelo precisa fazer mais do que apenas executar testes. Ele deve criar ou atualizar o changeset correto, validar o nível de incremento de versão e confirmar que o changeset realmente corresponde às diferenças.

Essa habilidade faz mais do que verificar se um arquivo existe. Ela pede ao Codex que avalie o git diff e mantém as regras de validação em um prompt compartilhado para que execuções locais e GitHub Actions usem a mesma lógica. Ela também registra políticas específicas do repositório, como:

• usar o changeset existente na branch em vez de criar outro quando já houver um
• manter o resumo em uma única linha no estilo Conventional Commit para que também possa servir como título de commit
• antes da versão 1.0, evitar incrementos de versão principal no desenvolvimento normal de funcionalidades e tratar adições explicitamente identificadas como exclusivas de prévia como alterações de versão de correção, desde que não mudem o comportamento existente
• validar o nível de incremento de versão exigido com base nas alterações reais do pacote

Isso torna o Codex responsável por validar os metadados de versão que ele cria antes de poder dizer que o trabalho está concluído.

Use documentação atualizada

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

Essa habilidade é uma camada simples sobre o MCP de documentação oficial da OpenAI. Em vez de deixar o modelo responder de memória, ela orienta o Codex a usar o servidor MCP da documentação para desenvolvedores da OpenAI para consultar a documentação atual de recursos como Responses API, ferramentas, streaming, Realtime e MCP.

Se o servidor MCP ainda não estiver configurado no ambiente local do Codex, a habilidade indica aos mantenedores o guia de início rápido do MCP de documentação e o endpoint oficial do servidor MCP.

Prepare o PR para entrega

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

Essa habilidade só é acionada quando a tarefa está efetivamente concluída ou pronta para revisão e a alteração envolveu mudanças relevantes no código, nos testes, nos exemplos, na documentação com impacto no comportamento ou na configuração de build e testes. Ela então coleta automaticamente o nome da branch, o estado da árvore de trabalho, os arquivos alterados, as estatísticas do diff e os commits recentes, e produz:

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

O formato de saída é intencionalmente rígido. Um resultado típico é assim:

# 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ê confia no modelo para validar e resumir o próprio trabalho, pedir que ele produza o rascunho do PR é um último passo natural. Isso mantém a consistência da entrega e reduz a escrita repetitiva depois que o trabalho de programação já está concluído.

Escreva descrições melhores

O campo description no frontmatter do SKILL.md de uma habilidade faz parte do contrato de roteamento.

Isso é uma questão de estrutura, não de estilo. A especificação de habilidades de agentes define name e description como campos obrigatórios do frontmatter de SKILL.md, e seu modelo de apresentação progressiva estabelece que esses campos sejam carregados na inicialização para todas as habilidades. O corpo completo de SKILL.md e quaisquer conteúdos de scripts/, references/ ou assets/ só são carregados depois, quando a habilidade é efetivamente ativada.

A documentação de habilidades do Codex e a documentação de personalização descrevem o mesmo comportamento do ponto de vista do Codex: ele começa pelos metadados de cada habilidade para descobrir quais estão disponíveis, carrega SKILL.md somente quando escolhe a habilidade e lê referências ou executa scripts apenas quando necessário. O cookbook de habilidades na API da OpenAI descreve o funcionamento no shell hospedado com a mesma clareza: a OpenAI lê primeiro name, description e o caminho de cada habilidade, e o modelo usa essas informações para decidir quando ler o SKILL.md completo. A seção sobre o frontmatter de SKILL.md reforça esse ponto de forma mais direta: name e description são importantes para a descoberta e o roteamento.

Nos repositórios do Agents SDK, isso faz de description um dos principais sinais de roteamento antes de o Codex ler o restante da habilidade.

Veja um exemplo concreto de code-change-verification.

Vaga demais:

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

Melhor (a descrição real):

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á informa ao Codex o que a habilidade faz, mas ainda não diz quando ela se aplica, quais tipos de alteração devem acioná-la ou se as verificações são opcionais. A versão mais específica informa os três pontos ao modelo.

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

Vaga demais:

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

Melhor (a descrição real):

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 real serve como metadado de roteamento. Ela informa ao Codex que:

• essa é uma habilidade para o fim da tarefa
• ela se aplica a alterações substanciais, não a cada turno do chat
• a saída é um bloco pronto para o PR, não apenas um resumo em prosa

Uma lição prática desses repositórios é dedicar tempo ao campo description. Se o roteamento não parecer confiável, corrija os metadados antes de adicionar mais código.

Coloque as etapas mecânicas em scripts

Depois disso, a próxima questão é o que deve ficar a cargo do modelo e o que deve ser delegado a um script.

Uma divisão confiável é:

• a interpretação, a comparação e a elaboração de relatórios ficam com o modelo
• o trabalho determinístico e repetitivo no shell fica em scripts/

Isso está de acordo com as orientações públicas. A documentação de personalização do Codex descreve as habilidades como uma forma de fornecer ao Codex instruções, scripts e referências mais completos para fluxos de trabalho repetíveis, sem sobrecarregar o contexto logo de início. Isso combina com uma abordagem centrada no modelo: deixe o Codex cuidar das partes do trabalho que dependem do contexto e recorra a scripts para as partes determinísticas apenas quando necessário. O cookbook de habilidades na API da OpenAI também recomenda projetar os scripts das habilidades como pequenas CLIs: scripts que sejam executados pela linha de comando, produzam uma saída determinística em stdout, sinalizem falhas claramente com mensagens de uso ou erro e gravem as saídas em caminhos de arquivo conhecidos quando necessário.

Nos repositórios do Agents SDK, procuramos usar o modelo onde sua inteligência realmente é útil, por exemplo:

• ler o código-fonte para inferir o comportamento pretendido
• comparar os logs com esse comportamento pretendido
• decidir se o diff de uma versão contém um risco real de compatibilidade
• produzir uma explicação que permita ao mantenedor tomar providências

Os scripts cuidam das etapas mecânicas desse 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 de cada exemplo e gravar arquivos de reexecução para os casos de falha
• buscar a tag da versão anterior antes de uma revisão para avaliar se a nova versão está pronta para lançamento
• disponibilizar comandos auxiliares como start, stop, status, logs, tail, collect e rerun para facilitar a execução repetida do mesmo fluxo de trabalho

Se o modelo precisa redescobrir a mesma sequência de comandos shell toda vez, isso geralmente indica que essa sequência deveria ser um script. Se a tarefa depende de contexto, da avaliação de vantagens e desvantagens ou de explicações, essa parte deve ficar com o modelo.

Automatize os testes de integração

Uma das aplicações mais úteis dos fluxos de trabalho nos dois repositórios são os testes de integração automatizados. Há duas camadas relacionadas aqui: validar automaticamente os exemplos dentro de ambos os repositórios e, no repositório JavaScript, validar separadamente se os pacotes publicados continuam funcionando quando instalados da mesma forma que os usuários os instalam.

Antes dessa configuração, a validação dos exemplos era parcialmente manual. Era possível executar os exemplos, mas a etapa final muitas vezes dependia de verificar visualmente os logs ou inspecionar a saída para decidir se ela parecia correta. Isso é viável para um exemplo, mas não escala bem em um repositório de SDK em crescimento.

A primeira camada é examples-auto-run, mas a habilidade veio depois do executor. Para viabilizar a automação da validação dos exemplos, primeiro tivemos que criar o suporte à execução não interativa de exemplos nos dois repositórios. Isso significou permitir a execução de scripts de exemplo em modo automático, incluindo os que normalmente envolvem prompts ou aprovações.

Esse trabalho de base incluiu:

• responder automaticamente a prompts interativos comuns
• aprovar automaticamente ações de HITL, MCP, apply_patch e shell nos casos em que o executor oferece suporte a elas
• manter em uma lista de exemplos a ignorar automaticamente aqueles que ainda não são adequados para automação, como exemplos em tempo real ou de aplicativos Next.js que precisam de configuração adicional do ambiente de execução
• gravar logs estruturados para cada execução de exemplo
• gerar arquivos de reexecução para permitir novas tentativas dos casos que falharam sem executar tudo novamente

Com essa base pronta, nós a organizamos como uma habilidade para tornar o fluxo de trabalho reutilizável e fácil de acionar. No repositório Python, examples-auto-run encapsula uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir .... No repositório JavaScript, ela encapsula as verificações de build e depois executa pnpm examples:start-all em modo automático, com logs por exemplo e suporte à reexecução.

Para melhorar a qualidade da validação, o papel do executor é executar os exemplos e preservar stdout e stderr em logs individuais para cada exemplo. A habilidade então orienta o Codex a analisar 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 real de stdout e stderr
• fazer isso para cada exemplo executado com sucesso, não apenas para uma amostra

Isso é mais preciso e flexível do que tentar definir a correção do comportamento por meio de uma asserção fixa em um script. Um código de saída que indica sucesso é útil, mas não basta para exemplos que se comunicam com APIs reais, usam ferramentas ou produzem saída estruturada. Ao registrar primeiro a saída real e depois compará-la cuidadosamente com o código-fonte, podemos validar cada exemplo de acordo com seu verdadeiro propósito.

No repositório JavaScript, há ainda uma segunda camada: a habilidade separada integration-tests. Esse fluxo de trabalho vai além de executar os exemplos diretamente no repositório. Ele publica os pacotes em um registro local do Verdaccio 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 detecta outra classe de problemas: a pergunta deixa de ser “o exemplo funciona no repositório?” e passa a ser “o pacote continua se comportando corretamente após a publicação, a instalação e a integração com o ambiente de execução?”.

Juntos, esses fluxos de trabalho mostram por que é útil combinar habilidades, scripts e a capacidade de avaliação do modelo. Os scripts tornam as execuções repetíveis, registram as evidências e cobrem formas de instalação cuja verificação manual seria trabalhosa. O Codex então usa essas evidências para fazer uma comparação mais cuidadosa do que uma simples verificação de sucesso ou falha por script.

Adicione verificações de lançamento

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

O fluxo de revisão de lançamento nos dois repositórios começa localizando a tag da versão anterior, comparando-a com o estado mais recente de main e pedindo ao Codex que examine 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, incluindo pequenas mudanças no comportamento esperado
• ausência de notas de migração ou de atualizações nas notas de versão para mudanças que exigem essas informações

Com base nesses resultados, a habilidade emite um parecer geral sobre se a versão está pronta para lançamento.

Um exemplo concreto é openai/openai-agents-python#2480, em que a revisão de lançamento mantém um parecer geral favorável, mas destaca o fim do suporte ao Python 3.9 e a atualização necessária nas notas de 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 como se decide se o lançamento pode prosseguir. A revisão parte de um parecer de "seguro para lançar" e só passa a bloquear o lançamento quando o diff apresenta evidências concretas de um problema real. Todo parecer de bloqueio deve incluir uma lista específica do que é preciso fazer para desbloquear o lançamento. Isso torna o resultado muito mais fácil de usar: um resultado favorável significa que nenhum problema que impeça o lançamento foi encontrado no diff, e um resultado de bloqueio significa que há um problema real com um próximo passo claro.

Isso é mais útil do que um pedido genérico como "por favor, revise o lançamento". Obriga o modelo a raciocinar sobre um diff concreto e explicar o resultado em termos operacionais. Se for seguro lançar, diga isso. Caso contrário, aponte as evidências exatas e as ações específicas necessárias.

Execute fluxos de trabalho na CI

Quando uma habilidade se mostra útil localmente, o Codex GitHub Action facilita a automação do mesmo fluxo de trabalho na CI. Isso funciona melhor quando o fluxo local já está estável, pois é no uso manual que você identifica problemas nas instruções, aprimora os scripts e encontra os casos extremos reais.

Em repositórios públicos, a definição dos gatilhos importa tanto quanto a habilidade. A lista de verificação de segurança do GitHub Action recomenda limitar quem pode iniciar o fluxo de trabalho, dar preferência a eventos confiáveis ou aprovações explícitas, sanitizar entradas de prompts provenientes de PRs, commits, issues ou comentários, manter OPENAI_API_KEY protegida com drop-sudo ou um usuário sem privilégios e executar o Codex como a última etapa do job.

Se um fluxo de trabalho tem permissão de escrita e recebe entradas públicas não confiáveis, o risco costuma estar na definição dos gatilhos, no tratamento das entradas e nos privilégios do ambiente em que a habilidade é executada.

Use o Codex na revisão de PRs

As habilidades são parte dos ganhos de produtividade nesses repositórios. A revisão automática de PRs do GitHub pelo Codex é outra.

Desde que a revisão automática de PRs do GitHub pelo Codex ficou disponível, o Codex tem sido um revisor útil para a maioria das alterações de código nesses repositórios. Nós o usamos como parte habitual da revisão, não como uma ferramenta para casos especiais.

Para bugs simples de programação, regressões e testes ausentes, confiar no Codex como a etapa obrigatória de revisão já é suficientemente seguro na prática. Ele aplica de forma consistente os mesmos critérios para verificar se o código está correto, repetidas vezes, e eliminou um grande gargalo para pequenas correções e melhorias rotineiras.

A revisão por pares continua importante, mas para outro tipo de mudança.

A revisão humana continua essencial quando a principal pergunta não é "este código está correto?", mas "qual das várias opções válidas devemos escolher e como devemos disponibilizá-la?". Isso inclui:

• mudanças de API ou arquitetura em que há várias soluções razoáveis e os mantenedores precisam fazer uma escolha explícita
• mudanças de comportamento que afetam as expectativas sobre o produto, os compromissos de compatibilidade com versões anteriores ou a política de disponibilização
• decisões sobre nomenclatura, migração e comunicação de lançamentos em que a dificuldade está em escolher o que será mais claro para usuários e colaboradores
• mudanças que exigem alinhamento entre mantenedores ou equipes, como definir o escopo e a sequência do trabalho ou decidir o que deve ser lançado agora e o que fica para depois

O Codex ainda pode contribuir de forma útil em todos esses casos, mas eles continuam se beneficiando de uma pessoa responsável pela decisão e de uma discussão direta.

O AGENTS.md também pode registrar essa divisão: o repositório pode informar ao Codex o que é importante na revisão para verificar se o código está correto, e o Codex pode aplicar essas orientações de forma consistente.

Isso também contribuiu significativamente para aumentar a taxa de processamento das tarefas. As tarefas repetitivas de revisão e validação já não precisam esperar pelo tempo escasso dos revisores a cada mudança de baixo risco, enquanto os mantenedores podem se concentrar nas revisões que exigem mais contexto e nas quais seu julgamento faz mais diferença. Essa mudança nos ajudou a resolver bugs do backlog e implementar pequenas melhorias de funcionalidades com muito mais rapidez.

Considerações finais

Nos repositórios do OpenAI Agents SDK, as habilidades funcionam melhor quando fazem parte da configuração habitual de trabalho do repositório.

O AGENTS.md informa ao Codex quais fluxos de trabalho são obrigatórios. O campo description indica quando recorrer a esses fluxos. Os scripts em scripts/ cuidam das partes determinísticas. O modelo cuida das partes que dependem de contexto. E, quando um fluxo de trabalho está consolidado localmente, o Codex GitHub Action pode levar o mesmo processo para a CI.

Isso tornou o trabalho diário de engenharia nesses repositórios mais explícito e confiável. Também facilitou a entrega mais rápida de pequenas melhorias, pois a verificação, a revisão de lançamento e a preparação do PR para revisão agora seguem o mesmo processo repetível.

Recursos

• OpenAI Agents SDK para Python
• OpenAI Agents SDK para JS
• Habilidades no Codex
• Instruções personalizadas com AGENTS.md
• Codex GitHub Action
• Use 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