OpenAI Symphony 완벽 가이드: 이슈가 곧 에이전트 파이프라인

"GitHub 이슈에 라벨 하나 붙였더니 다음 날 PR이 와 있었다면 어떨까?"

 

📌 핵심 3줄 요약

• OpenAI Symphony는 2026-05-06 공개된 Codex 오케스트레이션용 오픈소스 스펙으로, 라이브러리가 아니라 사양(spec)이다.
• 이슈 트래커(GitHub Issues 등)를 24/7 에이전트 파이프라인의 입력 큐로 표준화해 컨텍스트 스위칭 비용을 줄이는 것이 목표다.
• Codex CLI '시작하기'와 달리 이번 글은 스펙이 정의하는 흐름과 GitHub Actions·Jenkins 같은 자체 호스팅 CI와의 차이에 집중한다.

 

1. Symphony가 등장한 배경

Codex CLI는 단발 실행에 강하지만, 한 팀이 쌓아둔 백로그를 24시간 자동으로 처리하는 흐름까지는 표준이 없었다. 결국 회사마다 GitHub Actions·Jenkins·자체 큐를 엮어 자기만의 모양을 만들어 왔고, 이게 협업·관찰·재현을 어렵게 만들었다.

OpenAI가 내놓은 답이 Symphony다. 코드 라이브러리가 아니라 "어떤 입력이 들어오면 어떤 단계로 에이전트가 일하는가"를 정의한 오픈소스 스펙이다. 본질은 단순하다. 이슈 트래커를 큐로 보고, Codex를 워커로 보고, PR과 코멘트를 응답으로 본다.

💡 핵심 포인트

• Symphony는 "구현"이 아니라 "사양"이다. 별도 리포지토리에 참조 구현이 함께 공개됐지만, 다른 회사가 호환 러너를 만들 수 있는 구조다.
• 1차 자료: OpenAI 공식 발표 — An open-source spec for orchestration: Symphony

 

2. 스펙이 정의하는 3개 축

공식 문서를 읽어 보면 Symphony는 거창한 새 개념이 아니라 익숙한 큐·워커·결과 모델을 사양으로 못 박은 형태다. 핵심 축을 정리하면 다음과 같다.

축	역할	구체 예
입력 (Source)	이슈 트래커가 작업 큐 역할	GitHub Issues, Linear 등
실행 (Runner)	Codex 에이전트 컨테이너	Codex CLI · Codex 클라우드
결과 (Sink)	사람이 검토할 산출물 반환	PR, 코멘트, 상태 라벨

세부 필드명·라벨 규칙은 스펙이 빠르게 다듬어지는 중이라 본 글에서는 언급하지 않는다. 첫 도입이라면 OpenAI 공식 GitHub의 참조 구현 README를 그대로 따라가는 편이 안전하다.

 

3. GitHub Issues + Codex 실전 흐름

필자가 사이드 프로젝트 레포 한 곳에 라벨 한 줄로 Symphony를 검증한 결과, 흐름은 의외로 단순했다. 큰 그림은 다음 5단계다.

1. 이슈에 합의된 라벨(예시 기준 agent:ready) 부여 — 사람이 컨텍스트와 수락 기준을 본문에 정리
2. Symphony 러너가 라벨 변경을 감지해 큐에 enqueue
3. Codex 컨테이너가 레포를 체크아웃하고 작업 수행
4. PR 초안 생성 + 이슈 상태 라벨을 agent:in-review로 전환
5. 사람이 리뷰·머지 또는 반려 — 반려 시 코멘트가 다음 컨텍스트로 들어감

참고 구조 예시(실제 필드명은 공식 문서 확인 권장):

# symphony 러너 설정 — 예시 기준, 필드명은 공식 스펙 확인
source:
  type: github_issues
  repo: my-org/my-repo
  trigger_label: agent:ready
runner:
  type: codex
  container: default
sink:
  output: pull_request
  status_label: agent:in-review

핵심은 라벨이 "트리거"이자 "상태"라는 점이다. 한 이슈가 라벨을 따라 큐 → 작업 중 → 검토 중 → 완료를 오가는 작은 상태 머신이 된다.

 

4. 자체 호스팅 CI와 무엇이 다른가

"GitHub Actions로 워크플로 짜면 되지 않나?"는 한국 개발팀에서 가장 먼저 나오는 질문이다. 짚어 둘 만한 차이를 표로 정리했다.

구분	Symphony	GitHub Actions	Jenkins
트리거 모델	이슈 라벨·상태 머신	push·PR·cron 이벤트	SCM 폴링·웹훅
실행 단위	에이전트 작업(이슈 단위)	잡(Job)	파이프라인 스테이지
실패 처리	코멘트로 컨텍스트 누적	로그·재실행	로그·재실행
사람 개입 지점	PR 리뷰·라벨 변경	필요 시 환경 변수	승인 단계

요약하면 GitHub Actions·Jenkins는 "코드가 변하면 무엇을 빌드·배포할 것인가"에 답하고, Symphony는 "이슈가 열려 있는 동안 에이전트가 무엇을 시도할 것인가"에 답한다. 둘은 대체재가 아니라 인접한 레이어다.

 

5. 한국 개발팀 도입 체크포인트와 단점

먼저 도입 전에 짚어야 할 4가지.

• 보안: 이슈 본문에 사내 비공개 정보가 들어가는지부터 점검. Codex 호출 시 데이터 처리 정책을 컴플라이언스 담당과 합의.
• 비용: 호출 단가가 이슈 단위로 누적되므로, 처음부터 사이드 프로젝트 1~2개로 한도 테스트 후 전사 적용.
• 권한: GitHub Org 레포라면 OAuth 범위 승인이 Org Owner 권한이라 사전에 사내 Git 관리자 협의 필수.
• 라이선스: 스펙·참조 구현은 오픈소스이지만 Codex 모델 호출은 별도 OpenAI 과금 라인이라는 점을 유의.

그리고 솔직하게 짚는 한계.

• 신규 스펙(2026-05-06 공개) → 6개월 내 필드·라벨 컨벤션이 바뀔 가능성. 운영 코드에 하드코딩 자제.
• 비결정적 의사결정(디자인·UX 방향성) 작업은 부적합. 잘 정의된 이슈, 측정 가능한 수락 기준이 있을 때만 가치가 난다.
• LangGraph 같은 그래프 실행 엔진과 혼동 주의. Symphony는 사양, LangGraph는 실행 프레임워크라 같은 레이어가 아니다.
• 완전 자동 머지는 위험. 최소한 PR 단계 사람 리뷰는 유지해야 회귀 사고를 막을 수 있다.

 

6. 🚀 지금 바로 할 일

1. 사이드 프로젝트 레포 한 곳에 agent:ready 등 합의된 라벨부터 정의 — 라벨 컨벤션이 곧 워크플로다.
2. OpenAI 공식 발표와 참조 구현 GitHub를 열고 자기 환경의 권한·비용 한도부터 점검.
3. 1주일 운영 후 실패한 이슈 5개를 모아 "사람이 봤어야 했던 단계"를 회고 — 그 결과로 라벨 컨벤션을 한 번 더 손본다.

이미 GitHub Actions나 Jenkins로 비슷한 흐름을 운영 중이라면 Symphony 도입 시 가장 걸림돌이 무엇일지 댓글로 공유 부탁드립니다. 다음 글은 Symphony 참조 구현을 실제 OSS 레포에 붙여본 케이스 스터디를 다룰 예정입니다.

함께 보면 좋은 글

• MCP 시작 가이드 — 외부 API·DB 연동을 Plugins(MCP) 쪽에서 풀고 싶을 때 함께 보면 Skills와의 역할 분담이 분명해진다.
• Cursor 시작 가이드 — 같은 워크플로를 다른 에디터에서 어떻게 만드는지 비교해 보고 싶다면.
• Claude Projects vs Custom GPTs — 컨텍스트 주입 방식이 제품마다 어떻게 다른지 큰 그림을 잡는 데 도움이 된다.
• OpenAI Agents SDK 튜토리얼 — 같은 "에이전트 + 도구" 개념을 OpenAI 쪽에서는 어떻게 표현하는지 대조해 볼 수 있다.

참고 자료

• OpenAI 공식 발표 — An open-source spec for orchestration: Symphony
• GitHub Docs — About issues
• GitHub — openai/codex 리포지토리

---

작성자: AI·개발자 도구를 한국어로 정리하는 기술 블로거

최종 업데이트: 2026-05-06

참고 시점: Symphony는 공개 직후 단계라 스펙 필드·라벨 컨벤션이 빠르게 변할 수 있음. 분기 단위로 본문 점검 권장.