저희는 Codex를 도입해 OpenAI Agents SDK 리포지터리의 유지보수 방식을 바꾸고 있습니다. 리포지터리에 둔 스킬과 AGENTS.md, GitHub Actions를 활용해 검증, 릴리스 준비, 예제 통합 테스트, PR 리뷰처럼 반복되는 개발 작업을 매번 같은 절차로 수행할 수 있게 했습니다. 비교적 간단한 구성만으로도 개발이 활발한 두 리포지터리의 개발 처리량이 늘었습니다. 2025년 12월 1일부터 2026년 2월 28일까지 두 리포지터리에서 병합한 PR은 457건으로, 직전 3개월(2025년 9월 1일~11월 30일)의 316건보다 늘었습니다(Python 182건 → 226건, TypeScript 134건 → 231건).
SDK는 Python과 TypeScript로 제공됩니다. 에이전트 기반 애플리케이션을 만드는 데 필요한 핵심 구성 요소를 제공하며, Realtime API를 기반으로 여러 에이전트와 도구, 사람이 중간에 개입할 수 있는 제어 기능을 갖춘 음성 에이전트도 간결하게 구현할 수 있습니다. 사용 규모도 상당합니다. 2026년 3월 6일 기준 최근 30일간 Python 패키지는 PyPI에서 약 1,470만 회, TypeScript 패키지는 npm에서 약 150만 회 다운로드되었습니다.
구성은 간단합니다.
AGENTS.md에 리포지터리 정책을 기록합니다..agents/skills/에 해당 리포지터리에서 사용할 스킬을 둡니다.- 필요한 경우 스킬 안에 스크립트와 참고 자료를 포함합니다.
- 같은 워크플로우를 CI에서 실행할 때는 Codex GitHub Action을 사용합니다.
이렇게 구성하면 Codex가 리포지터리의 작업 방식을 일관되게 파악할 수 있어 반복되는 개발 작업을 더 빠르고 정확하게 수행합니다.
공개 오픈 소스 프로젝트를 유지보수한다면 Codex for OSS를 참고하세요. 자격 요건을 충족하는 유지보수자는 Codex가 포함된 ChatGPT Pro, API 크레딧, Codex Security 조건부 이용 권한을 신청할 수 있습니다.
워크플로우를 리포지터리에서 관리하기
두 리포지터리에서는 각 리포지터리 고유의 작업 절차를 스킬로 정리합니다. 스킬은 작업에 필요한 지식을 담은 작은 패키지로, SKILL.md 매니페스트와 선택적으로 포함하는 scripts/, references/, assets/로 구성됩니다. Codex 맞춤 설정 문서에서는 스킬이 반복 작업에 적합한 이유를 설명합니다. 상세한 지침과 스크립트, 참고 자료를 담아도 에이전트가 처음부터 모든 내용을 컨텍스트에 불러올 필요가 없기 때문입니다.
스킬은 다음과 같이 정보를 단계적으로 제공합니다.
- 에이전트는 먼저
name과description같은 메타데이터를 확인합니다. - 해당 스킬을 선택했을 때만
SKILL.md를 불러옵니다. - 필요할 때만 참고 자료를 읽거나 스크립트를 실행합니다.
두 SDK 리포지터리 모두 워크플로우를 코드와 함께 관리합니다.
구성이 더 단순한 Python 리포지터리부터 살펴보겠습니다.
code-change-verification은 코드나 빌드 동작이 바뀌면 필수 포매팅, 린트, 타입 검사, 테스트를 실행합니다.docs-sync는 문서와 코드베이스를 대조해 누락되거나 잘못되었거나 오래된 내용을 찾습니다.examples-auto-run은 자동 모드로 예제를 실행하고 로그와 재실행 도구를 제공합니다.final-release-review는 이전 릴리스 태그와 현재 릴리스 후보를 비교해 릴리스 준비 상태를 점검합니다.implementation-strategy는 런타임이나 API를 수정하기 전에 호환성을 보장할 범위와 구현 방식을 정합니다.openai-knowledge는 공식 Docs MCP 워크플로우로 최신 OpenAI API 및 플랫폼 문서를 가져옵니다.pr-draft-summary는 작업을 인계할 때 브랜치 이름 제안, PR 제목, 설명 초안을 준비합니다.test-coverage-improver는 테스트 커버리지를 측정해 가장 큰 공백을 찾고 이를 효과적으로 메울 테스트를 제안합니다.
JavaScript 리포지터리도 기본 구성은 같지만, npm 모노리포와 릴리스 절차에 필요한 스킬이 몇 가지 더 있습니다.
changeset-validation은 변경 세트의 내용과 버전 인상 수준이 실제 패키지 변경 사항과 일치하는지 확인합니다.integration-tests는 패키지를 로컬 Verdaccio 레지스트리에 게시한 뒤 지원하는 여러 런타임에서 설치와 실행을 검증합니다.pnpm-upgrade는 pnpm 도구 체인과 CI에 고정한 버전을 함께 업데이트합니다.
구체적인 스킬 목록보다 중요한 것은 설계 방식입니다. 각 스킬은 맡은 일의 범위가 좁고, 호출 조건이 명확하며, 구체적인 결과물을 냅니다.
특히 유용한 스킬 중에는 다음 단계로 넘어갈지 판정하기보다 점검 결과를 먼저 보고하는 스킬도 있습니다. docs-sync와 test-coverage-improver가 그 예입니다. 현재 diff나 커버리지 결과를 살펴보고 중요한 항목부터 정리한 다음, 수정에 앞서 승인을 요청합니다. Python 리포지터리의 docs-sync는 자동 생성된 레퍼런스 문서를 직접 수정하는 대신, 문서의 원본인 소스 코드의 독스트링과 주석을 기준으로 삼습니다. JavaScript 전용 pnpm-upgrade도 범위를 좁게 잡은 유지보수 워크플로우입니다. 광범위하게 검색하고 치환하는 대신 로컬 pnpm 버전, packageManager, 워크플로우에 고정한 버전을 함께 업데이트합니다.
필요한 워크플로우를 필수로 지정하기
리포지터리에서 스킬이 필요한 시점에 사용을 의무화하면 스킬을 더 효과적으로 활용할 수 있습니다. 이때 사용하는 파일이 AGENTS.md입니다.
AGENTS.md 가이드에 따르면 이 파일에는 코드베이스와 함께 관리하며 에이전트가 작업을 시작하기 전에 적용하는 리포지터리 수준의 지침을 담습니다. 가이드는 파일을 짧게 유지할 것도 권장합니다. Agents SDK 리포지터리에서는 Codex가 매번 따라야 하는 규칙을 이 파일에 기록하고, 가장 중요한 규칙을 위쪽에 둡니다.
실제로 두 리포지터리는 어떤 조건에서 어떤 스킬을 반드시 써야 하는지 짧은 규칙으로 명시합니다. 런타임이나 API를 수정하기 전에는 $implementation-strategy를 호출해 호환성을 보장할 범위와 구현 방식을 먼저 정합니다. SDK 코드, 테스트, 예제 또는 빌드 동작에 영향을 주는 변경이라면 $code-change-verification을 호출합니다. JavaScript 패키지 변경이 릴리스 메타데이터에 영향을 준다면 $changeset-validation을 호출합니다. OpenAI API나 플랫폼 연동을 다룬다면 $openai-knowledge를 호출합니다. 작업을 마치고 인계할 준비가 되면 $pr-draft-summary를 호출합니다.
이 구조는 프로젝트 개요, 빌드 및 테스트 명령어, 코드 스타일, 테스트 지침, 보안 고려 사항 등 리포지터리 고유의 규칙을 한곳에 모으라는 agents.md의 권장 사항과도 일치합니다. Agents SDK 리포지터리도 이 구조를 따르되, 일상적인 작업에서 가장 중요한 스킬 호출 조건을 앞에 둡니다. 간추리면 다음과 같습니다.
# 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.실제 파일에는 이 기본 구성에 리포지터리별 세부 사항이 더해집니다. JavaScript 리포지터리에는 $changeset-validation이 있고, 두 파일 모두 런타임, 문서, 릴리스에 관한 지침을 더 자세히 다룹니다. 전체 예제는 openai-agents-python의 AGENTS.md와 openai-agents-js의 AGENTS.md에서 확인하세요.
AGENTS.md에는 스킬 호출 조건 외의 규칙도 담을 수 있습니다. Python 리포지터리는 공개 API 호환성 규칙도 여기에 기록합니다. 외부에 공개한 생성자 매개변수와 데이터 클래스 필드는 기존 위치가 가리키는 의미를 유지해야 합니다. 새로운 선택적 매개변수나 필드는 가능한 한 끝에 추가하고, 순서 변경이 불가피하면 호환성 테스트를 추가합니다. 이처럼 릴리스에 중요한 호환성 규칙을 스킬 호출 조건과 한곳에서 관리하는 것도 좋은 방법입니다.
검증 규칙
대표적인 예가 $code-change-verification입니다.
두 리포지터리의 규칙은 “항상 긴 검증 절차를 실행하세요”가 아닙니다. 실제 규칙은 “런타임 코드, 테스트, 예제 또는 빌드·테스트 동작이 바뀌면 검증 절차를 실행하고, 통과한 뒤에만 작업을 완료로 표시하세요”입니다.
실행 조건을 두면 문서만 수정할 때는 작업 부담이 줄어듭니다. SDK 코드를 수정할 때는 검증이 필수이므로 리포지터리의 표준 검증 절차를 반드시 거칩니다.
구체적인 검증 절차는 스킬 자체에 정의합니다.
Python 리포지터리에서는 다음 명령어를 실행해야 합니다.
make format
make lint
make typecheck
make testsJavaScript 리포지터리에서는 반드시 다음 순서대로 실행해야 합니다.
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test스킬은 리포지터리에서 무엇을 “검증 완료”로 보는지 정의하고, AGENTS.md는 그 기준을 반드시 따르도록 합니다.
변경 세트 검증
JavaScript 리포지터리에서 패키지를 변경할 때는 $changeset-validation을 반드시 실행해야 합니다. 이 스킬은 Changesets를 기반으로 하며 기존 검증 절차에 한 단계를 더합니다.
packages/ 아래에서 무엇이든 바뀌거나 .changeset/에 변경이 생기면 모델은 테스트 실행 외에도 할 일이 있습니다. 적절한 변경 세트를 생성하거나 업데이트하고, 버전 인상 수준을 검증하고, 변경 세트의 내용이 실제 diff와 일치하는지 확인해야 합니다.
이 스킬은 파일의 존재 여부만 확인하는 데 그치지 않습니다. Codex가 git diff를 보고 판단하도록 하며, 검증 규칙을 공통 프롬프트에 두어 로컬에서 실행할 때와 GitHub Actions에서 실행할 때 같은 로직을 사용합니다. 다음과 같은 리포지터리 고유의 정책도 스킬에 담습니다.
- 브랜치에 변경 세트가 이미 있으면 새로 만들지 않고 기존 변경 세트를 사용합니다.
- 요약은 커밋 제목으로도 쓸 수 있도록 Conventional Commit 형식의 한 줄로 작성합니다.
- 1.0 이전에는 일반적인 기능 개발로 메이저 버전을 올리는 것을 피합니다. 프리뷰 전용이라고 명시한 추가 기능이 기존 동작을 바꾸지 않으면 패치 변경으로 처리합니다.
- 실제 패키지 변경 사항을 기준으로 필요한 버전 인상 수준을 검증합니다.
따라서 Codex가 작업 완료를 보고하려면 자신이 생성한 릴리스 메타데이터부터 검증해야 합니다.
최신 문서 사용하기
두 리포지터리 모두 OpenAI API나 플랫폼 연동을 다룰 때 $openai-knowledge를 필수로 사용합니다.
이 스킬은 공식 OpenAI Docs MCP를 간단히 감싼 래퍼입니다. 모델이 기억에 의존해 답하는 대신, Codex가 OpenAI 개발자 문서 MCP 서버에서 Responses API, 도구, 스트리밍, Realtime, MCP 등에 관한 최신 문서를 조회하도록 합니다.
로컬 Codex 환경에 MCP 서버가 아직 설정되어 있지 않으면 스킬이 유지보수자에게 Docs MCP 빠른 시작 가이드와 공식 MCP 서버 엔드포인트를 안내합니다.
PR 인계 준비하기
두 리포지터리에서는 규모 있는 작업을 마무리할 때 $pr-draft-summary를 사용합니다.
이 스킬은 작업이 사실상 끝났거나 리뷰할 준비가 되었고, 코드, 테스트, 예제, 동작에 영향을 주는 문서 또는 빌드·테스트 설정에 의미 있는 변경이 있을 때만 호출합니다. 그러면 브랜치 이름, 작업 트리 상태, 변경된 파일, diff 통계, 최근 커밋을 자동으로 수집해 다음 결과를 만듭니다.
- 브랜치 이름 제안
- PR 제목
- PR 설명 초안
출력 형식은 의도적으로 엄격하게 정해 두었습니다. 일반적인 결과는 다음과 같습니다.
# 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.모델이 자신의 작업을 검증하고 요약하는 과정을 신뢰할 수 있게 되면, 마지막으로 PR 초안까지 맡기는 것이 자연스럽습니다. 인계 형식을 일관되게 유지하고, 코딩을 마친 뒤 같은 내용을 반복해서 작성하는 수고도 덜 수 있습니다.
스킬 설명을 더 구체적으로 작성하기
스킬의 description 필드는 SKILL.md 프런트매터에서 어떤 작업을 이 스킬로 연결할지 정하는 역할을 합니다.
이는 스킬의 동작을 결정하는 구조적 요소입니다. 에이전트 스킬 명세는 name과 description을 SKILL.md 프런트매터의 필수 필드로 지정합니다. 명세의 단계적 정보 제공 방식에 따르면 시작 시 모든 스킬에서 불러오는 정보는 이 두 필드입니다. SKILL.md 본문 전체와 scripts/, references/, assets/는 나중에 해당 스킬이 실제로 활성화된 후에만 불러옵니다.
Codex 스킬 문서와 맞춤 설정 문서에서도 Codex 관점에서 같은 동작을 설명합니다. Codex는 먼저 각 스킬의 메타데이터로 사용할 스킬을 찾습니다. 스킬을 선택해야 SKILL.md를 불러오고, 필요할 때만 참고 자료를 읽거나 스크립트를 실행합니다. OpenAI API 쿡북의 스킬 가이드도 호스팅 셸에서의 동작을 명확히 설명합니다. OpenAI는 각 스킬의 name, description, 경로를 먼저 읽고, 모델은 이 정보를 바탕으로 SKILL.md 전체를 읽을 시점을 결정합니다. 같은 가이드의 SKILL.md 프런트매터 섹션에서는 name과 description이 스킬 탐색과 라우팅에 중요하다고 명시합니다.
따라서 Agents SDK 리포지터리에서 description은 Codex가 스킬의 나머지 내용을 읽기 전에 어떤 스킬을 선택할지 판단하는 주요 단서입니다.
code-change-verification을 예로 들어 보겠습니다.
지나치게 모호한 설명입니다.
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.실제로 사용하는 설명은 더 구체적입니다.
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.짧은 설명도 스킬이 하는 일은 알려 줍니다. 하지만 언제 이 스킬을 적용하는지, 어떤 종류의 변경이 호출 조건인지, 검사를 생략할 수 있는지는 분명하지 않습니다. 구체적인 설명은 모델에 세 가지를 모두 알려 줍니다.
pr-draft-summary에서도 같은 차이를 볼 수 있습니다.
지나치게 모호한 설명입니다.
description: Create a PR title and draft description for a pull request.실제로 사용하는 설명은 더 구체적입니다.
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.여기서도 실제 설명은 라우팅을 위한 메타데이터로 쓰입니다. 이 설명을 통해 Codex는 다음 사항을 알 수 있습니다.
- 작업을 마무리할 때 사용하는 스킬입니다.
- 대화를 주고받을 때마다 쓰는 것이 아니라 의미 있는 변경을 마쳤을 때 사용합니다.
- 단순한 서술형 요약을 넘어 PR 작성에 바로 쓸 수 있는 형식으로 결과를 제공합니다.
두 리포지터리를 운영하며 얻은 교훈 중 하나는 description 작성에 시간을 들일 만하다는 것입니다. 스킬 선택이 일관되지 않다면 코드를 추가하기 전에 메타데이터부터 수정하세요.
반복 실행 절차를 스크립트로 옮기기
다음으로 정할 것은 어떤 일을 모델에 맡기고 어떤 일을 스크립트로 옮길지입니다.
다음과 같이 나누면 안정적으로 운영할 수 있습니다.
- 해석, 비교, 결과 보고는 모델에 맡깁니다.
- 절차가 정해져 있고 반복되는 셸 작업은
scripts/에 둡니다.
이는 공개 가이드의 지침과도 일치합니다. Codex 맞춤 설정 문서는 스킬을 활용하면 처음부터 컨텍스트를 과도하게 늘리지 않고도 반복 워크플로우에 필요한 상세한 지침과 스크립트, 참고 자료를 Codex에 제공할 수 있다고 설명합니다. 상황에 따라 판단해야 하는 부분은 Codex가 맡고, 절차가 정해진 부분에만 필요할 때 스크립트를 사용하는 방식입니다. OpenAI API 쿡북의 스킬 가이드 역시 스킬 스크립트를 작은 CLI처럼 설계하도록 권장합니다. 명령줄에서 실행할 수 있고, 같은 입력에는 같은 표준 출력을 내며, 실패하면 사용법이나 오류 메시지를 명확히 표시하고, 필요할 때는 미리 정한 파일 경로에 결과를 쓰도록 합니다.
Agents SDK 리포지터리에서는 다음처럼 판단이 필요한 작업에 모델을 활용합니다.
- 소스 코드를 읽고 의도한 동작 추론하기
- 로그를 의도한 동작과 비교하기
- 릴리스 diff에 실제 호환성 위험이 있는지 판단하기
- 유지보수자가 다음 조치를 취할 수 있도록 결과 설명하기
이러한 작업에 수반되는 실행 절차는 스크립트에 맡깁니다.
- 리포지터리의 필수 검증 명령어를 정해진 순서로 실행하기
- 예제를 실행하고, 예제별 로그를 수집하고, 실패한 예제를 위한 재실행 파일 작성하기
- 릴리스 준비 상태를 검토하기 전에 이전 릴리스 태그 가져오기
- 같은 워크플로우를 쉽게 반복 실행할 수 있도록
start,stop,status,logs,tail,collect,rerun같은 보조 명령어 제공하기
모델이 매번 같은 셸 명령어 조합을 다시 찾아내야 한다면 대개 그 절차를 스크립트로 만들 때입니다. 반면 컨텍스트를 이해하거나 장단점을 따지거나 설명해야 하는 부분은 모델에 맡기는 편이 좋습니다.
통합 테스트 자동화하기
두 리포지터리에서 워크플로우가 특히 유용한 분야는 통합 테스트 자동화입니다. 검증은 서로 연관된 두 단계로 나뉩니다. 두 리포지터리 모두 내부 예제를 자동으로 검증하고, JavaScript 리포지터리에서는 게시된 패키지를 사용자와 같은 방식으로 설치한 뒤에도 제대로 작동하는지 별도로 검증합니다.
이 구성을 도입하기 전에는 예제 검증에 수작업이 남아 있었습니다. 예제를 실행할 수는 있었지만, 마지막에는 로그를 눈으로 살펴보거나 출력이 적절해 보이는지 직접 판단해야 할 때가 많았습니다. 예제가 하나라면 감당할 수 있지만, SDK 리포지터리가 커지면서 모든 예제를 이런 식으로 확인하기는 어렵습니다.
첫 번째 단계는 examples-auto-run입니다. 다만 스킬보다 먼저 만든 것은 실행기였습니다. 예제 검증을 자동화하려면 우선 두 리포지터리에서 사용자 입력 없이 예제를 실행할 수 있어야 했습니다. 평소에는 입력이나 승인이 필요한 예제까지 포함해 예제 스크립트를 자동 모드로 실행할 수 있도록 했습니다.
이를 위해 다음과 같은 기능을 마련했습니다.
- 자주 나오는 대화형 입력 요청에 자동으로 응답합니다.
- 실행기가 지원하는 경우 HITL, MCP,
apply_patch, 셸 작업을 자동 승인합니다. - 별도의 런타임 설정이 필요한 실시간 예제나 Next.js 앱 예제처럼 아직 자동화하기 어려운 예제는 자동으로 건너뛸 목록에서 관리합니다.
- 예제를 실행할 때마다 구조화된 로그를 기록합니다.
- 모든 예제를 다시 실행하지 않고도 실패한 예제만 재시도할 수 있도록 재실행 파일을 생성합니다.
이 기반을 마련한 뒤 워크플로우를 쉽게 호출하고 재사용할 수 있도록 스킬로 정리했습니다. Python 리포지터리의 examples-auto-run은 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...를 호출합니다. JavaScript 리포지터리에서는 빌드 검사를 실행한 다음 pnpm examples:start-all을 자동 모드로 실행하며, 예제별 로그 기록과 재실행을 지원합니다.
검증 품질을 높이기 위해 실행기는 예제를 실행하고 표준 출력과 표준 오류를 예제별 로그에 그대로 남기는 일을 맡습니다. 그런 다음 스킬은 Codex가 로그를 하나씩 소스 코드와 대조하도록 합니다.
- 예제 소스와 주석을 읽습니다.
- 의도한 실행 플로우를 추론합니다.
- 해당 예제의 로그를 엽니다.
- 의도한 동작을 실제 표준 출력 및 표준 오류와 비교합니다.
- 대표 예제 하나만 확인하지 않고 실행에 성공한 모든 예제에 이 절차를 적용합니다.
이 방식은 스크립트에 고정된 단언문으로 동작의 정확성을 판정하는 것보다 정확하고 유연합니다. 성공을 나타내는 종료 코드는 유용하지만, 실제 API를 호출하거나 도구를 사용하거나 구조화된 출력값을 생성하는 예제를 검증하기에는 그것만으로 부족합니다. 실제 출력을 먼저 기록한 뒤 소스 코드와 꼼꼼히 대조하면 각 예제가 본래 의도대로 동작하는지 검증할 수 있습니다.
JavaScript 리포지터리에는 두 번째 단계로 별도의 integration-tests 스킬이 있습니다. 이 워크플로우는 리포지터리 안에서 소스 예제를 실행하는 것보다 더 넓은 범위를 검증합니다. 패키지를 로컬 Verdaccio 레지스트리에 게시한 뒤 Node.js, Bun, Deno, Cloudflare Workers, Vite React 앱 등 여러 환경에 설치해 실행합니다. 이렇게 하면 다른 종류의 문제를 발견할 수 있습니다. “리포지터리 안에서 예제가 실행되는가?”에 더해 “패키지를 게시하고 설치해 런타임에 연동한 뒤에도 올바르게 동작하는가?”까지 확인합니다.
이 두 워크플로우를 보면 스킬, 스크립트, 모델의 판단을 함께 활용하는 이유가 드러납니다. 스크립트는 실행 절차를 반복할 수 있게 하고, 검증에 필요한 자료를 기록하며, 일일이 확인하기 번거로운 설치 경로를 점검합니다. Codex는 이렇게 수집한 자료를 바탕으로 단순히 스크립트의 통과 여부를 보는 것보다 세밀하게 결과를 비교합니다.
릴리스 점검 추가하기
릴리스 준비에도 같은 방식을 활용할 수 있습니다.
두 리포지터리의 릴리스 검토 워크플로우는 이전 릴리스 태그를 찾아 최신 main과 비교하는 것으로 시작합니다. 그런 다음 Codex에 diff에서 다음 항목을 점검하도록 합니다.
- 공개 API와 사용자가 경험하는 SDK 동작의 하위 호환성 문제
- 예상 동작의 작은 변화까지 포함한 회귀 문제
- 마이그레이션 안내나 릴리스 노트 업데이트가 필요한 변경 사항에서 해당 내용이 누락되었는지 여부
스킬은 점검 결과를 종합해 릴리스할 준비가 되었는지 판단합니다.
구체적인 예로 openai/openai-agents-python#2480이 있습니다. 검토 결과는 릴리스 가능이었지만, Python 3.9 지원 종료와 그에 따라 릴리스 노트에 반영해야 할 내용도 명시했습니다.
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`.스킬에는 릴리스 진행 여부를 결정하는 기준도 정의합니다. 검토는 “릴리스해도 안전함”에서 시작해 diff에서 실제 문제의 구체적인 근거가 발견된 경우에만 “릴리스 차단”으로 바뀝니다. 차단 판정에는 반드시 차단을 해제하기 위해 수행할 구체적인 점검 목록이 따라야 합니다. 그래서 결과를 보고 바로 대응할 수 있습니다. 녹색 판정이면 diff에서 릴리스를 막을 문제를 찾지 못했다는 뜻이고, 차단 판정이면 실제 문제가 무엇이며 다음에 무엇을 해야 하는지 알 수 있습니다.
이는 막연히 “릴리스를 검토해 주세요”라고 요청하는 것보다 유용합니다. 모델이 구체적인 diff를 근거로 판단하고, 그 결과가 실제 릴리스에 어떤 의미인지 설명해야 하기 때문입니다. 안전하게 릴리스할 수 있다면 그렇게 명시하고, 그렇지 않다면 정확한 근거와 필요한 후속 조치를 제시합니다.
CI에서 워크플로우 실행하기
로컬에서 스킬의 유용성을 확인했다면 Codex GitHub Action으로 같은 워크플로우를 CI에서도 쉽게 자동화할 수 있습니다. 로컬 워크플로우가 이미 안정적으로 동작할 때 가장 효과적입니다. 직접 실행하는 과정에서 지침의 문제를 찾아 고치고, 스크립트를 다듬고, 실제로 발생하는 예외 사례를 발견할 수 있기 때문입니다.
공개 리포지터리에서는 스킬 자체만큼 호출 조건 설계도 중요합니다. GitHub Action 보안 체크리스트는 워크플로우를 시작할 수 있는 사람을 제한하고, 신뢰할 수 있는 이벤트나 명시적 승인을 우선 사용하도록 권장합니다. 또한 PR, 커밋, 이슈, 댓글에서 가져온 프롬프트 입력은 안전하게 정제하고, OPENAI_API_KEY는 drop-sudo를 사용하거나 권한이 제한된 사용자로 실행해 보호하며, Codex는 작업의 마지막 단계에서 실행하도록 권장합니다.
쓰기 권한이 있는 워크플로우가 신뢰할 수 없는 공개 입력을 받는다면, 위험은 대개 스킬을 호출하는 조건, 입력을 처리하는 방식, 실행 시 부여하는 권한에서 생깁니다.
PR 리뷰에 Codex 활용하기
두 리포지터리에서 생산성을 높인 방법 중 하나가 스킬이라면, 또 하나는 Codex의 GitHub PR 자동 검토입니다.
Codex의 GitHub PR 자동 검토 기능이 제공된 이후 Codex는 두 리포지터리의 코드 변경 대부분에서 유용한 리뷰어 역할을 해 왔습니다. 저희는 이 기능을 일상적인 리뷰 절차에 포함합니다.
단순한 프로그램 버그, 회귀 문제, 누락된 테스트의 경우 이제는 필수 리뷰를 Codex에 맡겨도 실무에서 충분히 안전합니다. Codex는 코드가 올바르게 동작하는지 확인하는 동일한 검사를 매번 일관되게 수행합니다. 덕분에 작은 수정이나 일상적인 개선을 지연시키던 주요 병목이 해소되었습니다.
다른 유형의 변경에서는 동료 리뷰가 여전히 중요합니다.
“이 코드가 올바른가?”보다 “타당한 여러 선택지 중 어느 것을 택하고 어떻게 출시할 것인가?”가 핵심이라면 사람의 리뷰가 꼭 필요합니다. 다음과 같은 경우입니다.
- API나 아키텍처를 변경할 때 타당한 설계가 여러 가지여서 유지보수자가 명시적으로 하나를 선택해야 하는 경우
- 동작 변경이 사용자가 제품에 기대하는 바, 하위 호환성 보장 또는 배포 정책에 영향을 주는 경우
- 이름, 마이그레이션 방식, 릴리스 안내 내용을 정할 때 사용자와 기여자가 가장 명확하게 이해할 방식을 고르는 것이 어려운 경우
- 작업 범위와 순서를 정하거나 지금 출시할 내용과 나중에 출시할 내용을 나누는 등 유지보수자나 팀 간 합의가 필요한 경우
Codex는 이 모든 경우에도 도움이 될 수 있지만, 사람이 직접 논의하고 결정할 때 더 좋은 결과를 얻을 수 있습니다.
AGENTS.md에 이러한 역할 분담을 명시할 수도 있습니다. 코드의 정확성을 검토할 때 무엇을 중요하게 봐야 하는지 리포지터리 지침으로 알려 주면 Codex가 그 기준을 일관되게 적용할 수 있습니다.
이러한 역할 분담 역시 개발 처리량을 높이는 데 크게 기여했습니다. 위험이 낮은 변경마다 리뷰어가 시간을 낼 때까지 반복적인 리뷰와 검증을 미룰 필요가 없어졌습니다. 유지보수자는 더 넓은 맥락을 이해하고 판단해야 하는 리뷰에 집중할 수 있습니다. 덕분에 밀려 있던 버그 수정과 소규모 기능 개선을 훨씬 빠르게 처리하게 되었습니다.
마무리
OpenAI Agents SDK 리포지터리에서는 스킬을 일상적인 작업 절차에 포함할 때 가장 효과적이었습니다.
AGENTS.md는 필수 워크플로우가 무엇인지 Codex에 알려 주고, description은 언제 해당 워크플로우를 선택해야 하는지 알려 줍니다. scripts/는 정해진 절차를 실행하고, 모델은 상황에 따라 판단해야 하는 부분을 맡습니다. 로컬에서 워크플로우가 안정되면 Codex GitHub Action으로 같은 절차를 CI에서도 실행할 수 있습니다.
이렇게 하니 두 리포지터리의 일상적인 개발 절차가 더 명확해지고 결과도 한층 안정적이었습니다. 검증, 릴리스 검토, PR 인계에 매번 같은 절차를 적용하면서 작은 개선 사항도 더 빠르게 출시할 수 있게 되었습니다.