Using skills to accelerate OSS maintenance

Как OpenAI использует Codex для ускорения поддержки Open-Source проектов

Введение

OpenAI применяет инструмент Codex для автоматизации рутинных инженерных задач в репозиториях Agents SDK. Комбинация из локальных навыков (skills), файла AGENTS.md и GitHub Actions позволяет превратить повторяющиеся операции — верификацию кода, подготовку релизов, тестирование примеров и проверку PR — в воспроизводимые рабочие процессы. За три месяца количество смерженных PR выросло с 316 до 457 — прирост составил 45%.

Ключевые метрики (по состоянию на март 2026):

📊 Таблица: Период | Python PR | TypeScript PR | Всего

сен–ноя 2025 - Python PR: 182, TypeScript PR: 134, Всего: 316
дек 2025 – фев 2026 - Python PR: 226, TypeScript PR: 231, Всего: 457

Популярность SDK: Python-пакет — 14,7 млн загрузок на PyPI за 30 дней, TypeScript-пакет — 1,5 млн на npm.

Архитектура решения: три компонента

Система строится на трёх элементах:

AGENTS.md — файл с политикой репозитория, который Codex читает перед началом работы. Содержит обязательные правила и триггеры для навыков.
Локальные навыки в .agents/skills/ — пакеты с инструкциями (SKILL.md), опциональными скриптами и ссылками. Каждый навык имеет узкую специализацию, чёткий триггер и конкретный результат.
Codex GitHub Action — позволяет запускать те жеworkflows в CI.

Такая архитектура даёт Codex стабильный контекст о том, как устроен репозиторий, что ускоряет и повышает точность рутинных задач.

Навыки Python-репозитория

В репозитории openai-agents-python определены восемь основных навыков:

code-change-verification — запускает форматирование, линтинг, проверку типов и тесты при изменении кода или поведения сборки.
docs-sync — сверяет документацию с кодовой базой, находит отсутствующую или устаревшую информацию.
examples-auto-run — запускает примеры в автоматическом режиме с логами и файлами для повторного запуска.
final-release-review — сравнивает предыдущий релиз с кандидатом и проверяет готовность к выпуску.
implementation-strategy — определяет границы совместимости и подход к реализации перед изменением runtime или API.
openai-knowledge — подтягивает актуальную документацию OpenAI через Docs MCP.
pr-draft-summary — готовит название ветки, заголовок PR и черновик описания при передаче работы.
test-coverage-improver — анализирует покрытие, находит крупные пробелы и предлагает высокоимпактные тесты.

Специфика JavaScript-репозитория

Репозиторий openai-agents-js использует те же паттерны, плюс три дополнительных навыка для npm-монорепо:

changeset-validation — проверяет, что changesets и уровни версий соответствуют diff-у пакета. Требует создания или обновления changeset при изменениях в packages/ или .changeset/.
integration-tests — публикует пакеты в локальный Verdaccio-реестр и проверяет установку и работу в Node.js, Bun, Deno, Cloudflare Workers и Vite React-приложении.
pnpm-upgrade — координированно обновляет локальную версию pnpm, packageManager и CI-пины.

Эти навыки перекрывают разные классы проблем: не только «пример работает в репозитории», но и «пакет корректно ведёт себя после публикации и установки».

Обязательные правила через AGENTS.md

Ключевой принцип — навыки становятся по-настоящему полезными, когда репозиторий требует их в нужный момент. В AGENTS.md описаны обязательные правила использования:

Перед редактированием runtime или API-изменений — вызвать $implementation-strategy.
При изменении runtime-кода, тестов, примеров или поведения сборки — запустить $code-change-verification.
При изменении JavaScript-пакета, влияющем на метаданные релиза — вызвать $changeset-validation.
При работе с OpenAI API или платформенными интеграциями — использовать $openai-knowledge.
Когда работа завершена и готова к передаче — вызвать $pr-draft-summary.

Файл также содержит совместимостные правила. Например, в Python-репозитории закреплено: сохранять позиционный смысл публичных конструкторов и dataclass-полей, добавлять новые опциональные параметры в конец, добавлять тесты совместимости при переупорядочивании.

Автоматизация тестирования примеров

До внедрения системы валидация примеров была частично ручной. Теперь реализовано два уровня:

Первый уровень — examples-auto-run:

Python: оборачивает uv run examples/run_examples.py --auto-mode
JavaScript: запускает pnpm examples:start-all в автоматическом режиме
Для каждого примера сохраняются stdout и stderr в отдельных логах
Codex построчно сравнивает логи с исходным кодом, выводя точную проверку поведения

Второй уровень (только JS) — integration-tests:

Публикует пакеты в локальный Verdaccio
Тестирует установку и запуск в нескольких средах: Node.js, Bun, Deno, Cloudflare Workers, Vite React

Это точнее и гибче, чем простой exit code: для примеров, работающих с реальными API и инструментами, одного успешного завершения недостаточно.

Подготовка релизов и PR

Release review работает так:

Находит предыдущий тег, сравнивает с последним main
Анализирует diff на предмет проблем обратной совместимости, регрессий, пропущенных миграционных заметок
Выносит вердикт: зелёный свет или заблокировано с конкретным чеклистом

Пример из PR #2480: релиз получил зелёный свет, но с пометкой о необходимости указать в release notes удаление поддержки Python 3.9.

pr-draft-summary генерирует готовый блок для PR:

Branch: fix/tracing-lazy-init-fork-safety
Title: fix: #2489 lazily initialize tracing globals
Description: This pull request fixes import-time tracing side effects...

Это удерживает передачу работы в консистентном формате и избавляет от рутинного писания после завершения кодинга.

Заключение: результаты и рекомендации

Внедрение навыков в Agents SDK репозиториях дало измеримый результат: +45% смерженных PR, ускорение проверок и подготовки релизов, снижение задержек из-за ожидания ревью.

Ключевые паттерны:

Тратить время на описание навыка — это основной сигнал для роутинга. «Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior» лучше, чем «Run verification».
Скрипты — для детерминированной работы (запуск команд, сбор логов), модель — для контекстной (анализ, сравнение, объяснение).
AGENTS.md кодирует и политику, и совместимостные правила — всё в одном месте.
Codex GitHub Action автоматизирует навыки в CI, но только после отладки на локальном использовании.

Для open-source проектов OpenAI предлагает программу Codex for Open Source: участники могут получить ChatGPT Pro с Codex, API-кредиты и условный доступ к Codex Security.

📢 Информация предоставлена телеграм-каналом: Data&AI Insights

🤖 Data&AI Insights - Ваш источник инсайтов о данных и ИИ