코덱스, CI, Apidog API 테스트 활용 나만의 소프트웨어 팩토리 구축 가이드

이번 주 Gergely Orosz의 OpenAI 내부 소프트웨어 팩토리 다이어그램이 화제가 되었습니다. 이 다이어그램에 따르면, 개발자가 결과물을 제출하면 Codex가 코드를 작성하고, 전문 리뷰 에이전트 팀이 위험에 대해 논의하며, 한 에이전트가 직접 만든 대시보드를 보면서 배포를 관리합니다. 또한, OpenAI 엔지니어들에게 가장 중요한 부분은 설치할 수 없는 내부 도구에 대한 설명이기도 합니다.

Perf Factory, Sevbot, 그리고 자체 구축 대시보드를 사용하는 에이전트 기반 배포는 OpenAI 자체의 관측 가능성 스택에서 실행되며, 구매할 수 있는 Codex 제품의 일부가 아닙니다. 이번 주에 여러분이 구축할 수 있는 것은 여전히 실제 작업을 수행하는 더 작은 루프입니다. 개발자가 결과물을 이슈로 정의하면, Codex가 브랜치 작업을 하고, CI가 변경 사항이 실제로 작동하는지 확인하며, 한두 명의 리뷰어 에이전트가 이를 검토하고, 위험한 모든 것은 플래그 뒤로 배포되기 전에 사람이 승인합니다. 이 모든 것은 원래 다이어그램이 간과한 한 가지 세부 사항에 달려 있습니다. 즉, “CI 통과”는 CI가 올바른 것을 확인할 때만 의미가 있습니다. API의 경우, 이는 API를 호출하는 코드뿐만 아니라 API 자체를 테스트하는 것을 의미합니다.

button

다이어그램이 정확히 짚은 것 (그리고 복사할 수 없는 것)

프래그마틱 엔지니어 기사의 공개 부분은 Codex가 “목표에 도달할 때까지 일련의 코드 변경을 수행한 다음, 소프트웨어가 예상대로 작동하는지 확인”하는 핵심 루프를 설명합니다. 낮은 위험 영역은 자동 승인될 수 있으며, 높은 위험 변경 사항은 더 많은 AI 검토 또는 필수적인 사람의 승인을 받습니다. 제안, 확인, 위험 등급별 검토라는 이 구조는 이식 가능합니다. 팀들은 수년 동안 풀 리퀘스트 봇과 CI 게이트를 사용하여 이를 근사화해왔으며, 에이전트는 단순히 루프를 더 빠르고 덜 감독하게 만듭니다.

이식 불가능한 것은 그 주변의 내부 메커니즘입니다. Perf Factory는 지연 회귀를 찾아내고 수정 사항을 제안하기 위해 알림과 대시보드를 분류합니다. Sevbot은 사고를 조사하고 Slack에서 질문에 답변하지만, 자체적으로 완화 조치를 실행하지는 않습니다. 에이전트 기반 배포는 변경 사항이 프로덕션으로 배포되는 것을 지켜보고 OpenAI의 내부 텔레메트리 스택을 사용하여 자체 모니터링을 구축합니다. 이 세 가지 모두 외부 Codex 제품에는 포함되어 있지 않습니다. 출시된 것은 데스크톱 앱, 장기 실행 작업을 위한 /goal 명령어, 그리고 직접 구성하는 역할 플러그인과 스킬입니다. OpenAI의 Codex 제품 페이지에서 실제로 사용 가능한 내용을 다루고 있습니다.

이번 주에 실행할 수 있는 5단계 루프

축소된 버전은 다음과 같습니다:

**개발자가 결과물을 이슈로 제출합니다.** 작업 목록이 아니라 최종 상태에 대한 설명입니다: “주문은 총액을 줄이는 선택적 할인 코드를 포함할 수 있습니다.” 동일한 GitHub 이슈를 Sharkly의 에이전트에게 넘기는 것이 출시된 통합 기능입니다. 이슈는 작업(Task)이 되고, 실행 결과는 조정할 별도의 티켓이 아닌 PR로 반환됩니다. 현재 10인 이하 조직은 무료입니다.
**Codex가 /goal을 사용하여 브랜치를 작업합니다.** /goal 명령이 자율적인 Codex 및 Claude Code 실행을 어떻게 이끄는지에서 다룬 바와 같이, 에이전트에게 목표를 제시하고 목표가 충족될 때까지 자체적으로 반복하게 합니다.
**CI는 빌드, 단위 테스트, API 테스트 시나리오를 실행합니다.** 이 단계는 대부분의 팀이 건너뛰거나 불완전하게 구축하는 부분입니다.
**한두 명의 리뷰어 에이전트가 diff를 확인하고, 사람이 낮은 위험 이상의 모든 것을 검토합니다.** AI 코드 리뷰 도구는 사람이 PR을 열기 전에 많은 것을 잡아낼 수 있습니다. Sharkly에서는 ‘Ready for Release’가 이 작업을 수행합니다. 사람이 이 상태에서 작업을 옮겨야만 ‘완료(Done)’ 상태로 넘어갈 수 있으며, 별도의 리뷰어 에이전트가 코드를 작성한 에이전트와 같은 팀(Crew)에 속할 수 있습니다.
**기능 플래그 뒤에 배포합니다.** 따라서 잘못된 병합은 인시던트가 아니라 토글로 처리됩니다.

3단계는 루프가 작동하거나 또는 여러분을 속이는 지점입니다.

CI가 코드뿐만 아니라 API를 테스트해야 하는 이유

Codex 코드 리뷰 작동 방식에서 다룬 Codex 자체의 리뷰 기능은 diff를 읽고 명백한 문제를 표시합니다. 그러나 서비스는 실행하지 않으며 반환값을 확인하지 않습니다. 에이전트가 작성하거나 유지한 단위 테스트는 대부분 코드가 의도한 대로 작동하는지 확인하지만, 이는 API가 계약에서 약속한 대로 작동하는지 확인하는 것과는 다릅니다. 핸들러를 편집하는 에이전트는 모든 단위 테스트를 통과하면서도 모든 클라이언트가 의존하는 응답을 조용히 손상시킬 수 있습니다.

주문 API를 운영한다고 가정해 봅시다. POST /api/orders는 주문을 생성하고 해당 기록을 반환하며, GET /api/orders/{id}는 ID로 주문을 가져옵니다. 이 둘 모두에 대해 OpenAPI 스펙을 유지하고 있으며, 이에 대해 Apidog 테스트 시나리오를 구축했습니다. 주문을 생성하고, 다시 가져와서 단위 테스트에서는 일반적으로 확인하지 않는 네 가지를 확인합니다:

**상태 코드.** POST /api/orders는 유효성 검사 예외 상황에서 200 또는 조용한 500이 아닌 201을 반환합니다.
**OpenAPI 스펙에 대한 응답 스키마.** total_amount 필드는 숫자로 유지되고, status는 정의한 열거형 값 중 하나로 유지되며, 클라이언트가 의존하는 어떤 필드도 조용히 사라지거나 이름이 변경되지 않습니다.
**인증 실패.** 유효한 토큰이 없는 요청은 빈 본문과 함께 200이 아닌 401을 반환합니다. 이는 놀랍도록 흔한 회귀 현상입니다.
**지연 시간 임계값.** 시나리오는 응답이 설정된 제한 시간 내에 돌아오는지 확인하므로, 핸들러 내부에 배치 처리되지 않은 데이터베이스 호출을 추가하는 변경 사항은 고객이 알아차리기 전에 감지됩니다.

이것들은 핸들러 수준의 리팩토링이 모든 단위 테스트가 통과하는 동안에도 조용히 깨뜨릴 수 있는 정확한 확인 사항입니다. 왜냐하면 단위 테스트는 API 시나리오가 실제로 실행하는 경계를 일반적으로 모의하기 때문입니다.

파이프라인에 연결하기

Codex에서 Apidog CLI 사용 방법을 따랐다면, 이미 이러한 시나리오의 CLI 버전을 로컬에서 실행하고 있을 것입니다. 동일한 명령어가 CI에서 실행됩니다. 빌드, 단위 테스트 실행, 그리고 Apidog 시나리오를 실행하는 GitHub Actions 작업은 다음과 같습니다:

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  build-test-verify:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build and run unit tests
        run: npm run build && npm test

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run orders API test scenario
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: |
          apidog run \
            --access-token $APIDOG_ACCESS_TOKEN \
            -t 88214 \
            -e 3301 \
            -r cli,junit

      - name: Upload Apidog reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-reports
          path: apidog-reports/

-t 및 -e 값은 여러분이 임의로 만든 플레이스홀더가 아니라, Apidog에서 가져온 실제 시나리오 및 환경 ID입니다. apidog run 명령어 참조는 모든 플래그를 다루고, Apidog CLI 테스트 보고서는 작업이 업로드하는 JUnit 출력을 설명합니다. apidog run은 실패한 어설션이 있을 경우 0이 아닌 값으로 종료되므로, GitHub Actions는 실패한 단위 테스트와 동일한 방식으로 해당 작업을 실패로 표시합니다.

에이전트 프롬프트의 예시

/goal의 핵심은 결과와 종료 조건을 설명하는 것이고, Codex는 여러분이 모든 단계를 승인하지 않아도 반복한다는 것입니다. 할인 코드 예시의 경우, 합리적인 프롬프트는 다음과 같습니다:

/goal POST /api/orders에 선택적 `discount_code` 필드를 추가합니다. 이를
프로모션 서비스에 대해 유효성을 검사하고 응답의 `total_amount`에 할인을
적용합니다. 기존 응답 필드의 이름을 변경하거나 제거하지 마십시오. 완료하기 전에
`npm test` 및 `apidog run --access-token $APIDOG_ACCESS_TOKEN -t 88214 -e 3301
-r cli`를 실행하십시오. 둘 다 0으로 종료되어야 합니다. Apidog 실행이 실패하면,
실패한 어설션을 읽고 테스트가 아닌 핸들러를 수정하십시오.

마지막 줄이 중요합니다. 검사를 통과시키려는 압박을 받는 에이전트는 때때로 버그 대신 어설션을 수정할 수 있습니다. 루프의 어느 부분을 수정해야 하는지 명확하게 알려줌으로써 테스트 시나리오를 진실의 근원으로 유지하고, 우회해야 할 장애물이 아닌 것으로 만듭니다.

에이전트가 계약을 위반할 때

Codex는 할인 필드를 추가하고, 이 과정에서 `total_amount`를 `totalAmount`로 이름을 변경합니다. 이는 인근 파일에서 읽은 규칙 때문입니다. 단위 테스트는 여전히 통과합니다. 단위 테스트는 할인 계산을 확인하지 필드 이름을 확인하지 않습니다. 빌드는 성공합니다. 그런 다음 Apidog 시나리오가 CI에서 실행되어 OpenAPI 스펙에 대해 응답을 검증하고 실패합니다. 스펙에는 `total_amount`라고 되어 있지만, 응답에는 `totalAmount`가 있어 스키마 어설션이 즉시 이를 감지합니다.

CI는 0이 아닌 종료 코드를 보고하고 JUnit 출력에서 실패한 스키마 어설션을 지적합니다. Codex는 실패를 읽고, 이름 변경이 원인임을 확인한 후, 할인 로직은 유지하면서 이를 되돌립니다. 시나리오가 통과하고, 빌드가 성공하며, 풀 리퀘스트는 “통과”라는 단어 뒤에 실제 보장을 가지고 검토로 넘어갑니다. API 수준의 검사가 없었다면, 해당 이름 변경이 배포되어 `total_amount`를 파싱하는 모든 클라이언트가 다음 릴리스에서 작동하지 않았을 것입니다.

스펙에 기반을 둔 위험 계층화

낮은 위험으로 간주되는 것에 대한 모호한 느낌 대신, 위험 분류를 OpenAPI diff에 연결하세요. 기본값을 가진 선택적 필드를 추가하는 변경 사항은 테스트 통과 후 자동 병합 대상이 될 수 있습니다. 필드를 제거하거나, 이름을 바꾸거나, 상태 코드를 변경하는 변경 사항은 나머지 diff가 어떻게 생겼든 관계없이 절대 낮은 위험이 아닙니다. 이 단일 규칙은 전문 리뷰 에이전트가 어쨌든 표시할 대부분의 것을 잡아냅니다. 이 규칙이 표시하는 모든 것은 병합 전에 사람 리뷰어나 AI 코드 리뷰 도구의 2차 검토로 넘기세요.

공허가 아닌 플래그 뒤에 배포하기

변경 사항이 CI와 검토를 통과하면, 모든 사용자에게 직접 배포하는 대신 기능 플래그 뒤에 배포하세요. 이것은 OpenAI의 에이전트 기반 배포 단계를 위한 저렴한 대안입니다. 배포를 관리하거나 자체 대시보드를 구축하는 에이전트는 없습니다. 트래픽 5%에서 시작하여 오류율을 확인한 후 100%로 전환하는 플래그와 사람이 있다면, 내부 도구 없이도 대부분의 안전을 확보할 수 있습니다. 문제가 발생하면 압박 속에서 병합을 롤백하는 대신 플래그를 비활성화하면 됩니다.

이미 존재하는 스캐폴드

다섯 단계를 처음부터 모두 연결할 필요는 없습니다. orchflows는 Orosz의 스레드 답글에 나타난 오픈 소스 프로젝트입니다. 이는 재사용 가능한 소수의 스킬을 기반으로 구축된 Claude Code 및 Codex용 MIT 라이선스 /software-factory 명령어입니다. 이는 위에 언급된 CI 및 검토 단계를 대체하는 것이 아니라 시작점 역할을 하는 스캐폴드이며, 여전히 자체 테스트 시나리오와 위험 규칙을 가리키도록 설정해야 합니다.

구축을 건너뛸 것들

Perf Factory, Sevbot, 또는 자체 구축 대시보드를 사용하는 에이전트 기반 배포를 재현하려고 시도하지 마십시오. 이들은 대부분의 팀이 실행하지 않는 텔레메트리에 연결된 OpenAI 내부 시스템입니다. OpenAI의 인간은 여전히 결과물을 정의하고, 고위험 변경 사항을 승인하며, 사고 완화를 승인하고, 온콜(oncall) 근무를 수행합니다. OpenAI가 말했듯이, “온콜 근무는 과거의 일이 아닙니다.” 단순히 훌륭한 엔지니어링 규율에 해당하는 루프의 부분을 복사하십시오. 즉, 병합 전에 확인하고, 실제로 변경된 내용에 따라 위험을 계층화하며, 명확히 안전하지 않은 모든 것에 대해서는 인간의 개입을 유지하십시오.

루프 실행하기

CI 단계부터 시작하십시오. 이 단계는 다른 모든 단계를 신뢰할 수 있게 만듭니다. Apidog에서 상태 코드, 스키마, 인증 및 지연 시간 예산을 포함하는 주문 API 테스트 시나리오를 구축하십시오. CLI를 사용하여 파이프라인에 연결하고, 실제 이슈에 /goal을 지정하고, 에이전트의 말을 신뢰하는 대신 실제로 API 동작을 어설션하는 검사에 대해 Codex가 반복하도록 하십시오. 첫 번째 시나리오를 구축하려면 Apidog를 다운로드하고, 루프가 자체적으로 입증되면 검토자 및 플래그 단계를 추가하십시오.