Design Codex, 저장소를 격리된 환경에서 수정하고 검증하는 소프트웨어 작업 시스템

사용자가 개발 작업을 위임하면 저장소 연결, 실행 환경 준비, 코드 탐색, 파일 수정, 명령 실행, 승인 요청, 테스트, diff 생성, Pull Request 작성이 서로 다른 처리 경로에서 진행됩니다.

Introduction & Requirements

아래 설계는 OpenAI Codex의 공개 문서와 제품 기능을 바탕으로 한 시스템 디자인 가정입니다. OpenAI 내부 구현을 그대로 설명하는 글은 아닙니다.

Codex는 사용자의 저장소를 읽고, 파일을 수정하고, 명령을 실행하고, 테스트 결과를 확인할 수 있습니다. 사용자는 터미널이나 IDE에서 현재 작업 폴더를 대상으로 Codex를 실행할 수 있고, 클라우드 환경에 작업을 넘겨 다른 작업과 병렬로 실행할 수도 있습니다.

여기서 작업(task)이라는 용어를 먼저 설명하겠습니다.

사용자가 다음과 같이 요청했다고 가정하겠습니다.

결제 API의 중복 요청 문제를 수정하고 관련 통합 테스트를 추가해 주세요.

시스템은 이 요청과 함께 아래 정보를 계속 기억해야 합니다.

어느 저장소를 수정하는가?
어느 branch 또는 commit을 기준으로 시작했는가?
어떤 환경에서 실행하는가?
어떤 파일을 읽고 수정했는가?
어떤 명령을 실행했는가?
사용자 승인이 필요한 작업이 있었는가?
테스트 결과는 무엇인가?
최종 diff는 무엇인가?
Pull Request를 만들었는가?

이렇게 사용자 요청, 실행 상태, 결과, 로그를 함께 관리하는 작업 단위를 이 글에서는 task라고 부르겠습니다.

처음 이 문제를 보면 코드 생성 API로 설계할 수 있습니다.

“사용자의 요청과 저장소 파일을 모델에 보내고 수정된 코드를 반환하면 되지 않을까요?”

파일 몇 개만 포함된 저장소에서 함수 하나를 수정하는 경우에는 이 방식으로 결과를 만들 수 있습니다. 사용자가 현재 파일과 오류 메시지를 보내면 모델이 코드 조각을 반환하게 됩니다.

하지만 실제 소프트웨어 작업에는 코드 생성 이후의 처리가 계속 이어집니다.

저장소 구조 파악
관련 파일 검색
프로젝트 지침 확인
의존성 설치
코드 수정
formatter 실행
linter 실행
unit test 실행
integration test 실행
실패 원인 분석
추가 수정
diff 검토
commit 또는 Pull Request 작성

모델이 코드 문자열을 생성했다고 작업이 완료되는 것은 아닙니다. 생성된 코드가 실제 저장소에서 빌드되고, 기존 테스트를 통과하고, 사용자의 프로젝트 규칙을 따르는지 확인해야 합니다.

면접관은 이렇게 물을 수 있습니다.

“우리가 설계하는 것은 코드를 반환하는 API인가요, 아니면 저장소를 격리된 실행 환경에서 수정하고 검증하는 작업 플랫폼인가요?”

코드 반환만 지원한다면 prompt, model request, response 정도로 구성할 수 있습니다.

하지만 Codex와 같은 시스템에서는 저장소 버전, 실행 환경, 파일 변경, 터미널 명령, 승인 요청, 테스트 결과, diff, Git 작업을 함께 관리해야 합니다.

특히 명령 실행은 일반적인 텍스트 생성과 다른 보안 조건을 가집니다.

에이전트가 다음 명령을 실행하려고 할 수 있습니다.

npm test

이 명령은 현재 작업 폴더 안에서 테스트를 실행하므로 비교적 제한된 작업입니다.

반면 다음 명령은 더 넓은 권한을 요구할 수 있습니다.

curl https://example.com/install.sh | sh

rm -rf ~/Documents

git push origin main

파일 시스템, 네트워크, 외부 저장소에 영향을 주는 작업은 별도의 실행 경계를 가져야 합니다.

에이전트가 접근할 수 있는 파일과 네트워크 범위를 제한하는 실행 환경을 sandbox라고 부르겠습니다.

sandbox는 에이전트가 자율적으로 명령을 실행하더라도 사용자의 다른 파일이나 허용되지 않은 네트워크에 접근하지 못하도록 제한합니다.

예를 들어 workspace-write 모드에서는 다음 작업을 허용할 수 있습니다.

현재 저장소 파일 읽기
현재 저장소 파일 수정
저장소 안에서 테스트 실행
임시 빌드 파일 생성

반면 다음 작업은 차단하거나 사용자 승인을 받을 수 있습니다.

작업 폴더 밖의 파일 수정
외부 인터넷 접속
운영 환경에 배포
원격 저장소에 push
사용자의 자격 증명 접근

sandbox와 함께 승인(approval) 처리도 구성해야 합니다.

승인은 에이전트가 현재 허용 범위를 넘어서는 작업을 실행하기 전에 사람이나 별도 검토 시스템의 허가를 받는 과정입니다.

Agent
  -> 외부 네트워크 접근 요청
  -> Approval Service
      -> 사용자 또는 검토 에이전트 판단
          -> 허용
          -> 거부

모든 명령을 승인받게 만들면 사용자가 계속 작업을 확인해야 하므로 자동화 수준이 낮아집니다. 반대로 모든 명령을 자동으로 허용하면 파일 삭제, 외부 전송, 비밀 정보 노출 가능성이 증가합니다.

그래서 실행 위치, 명령 종류, 파일 경로, 네트워크 domain, 저장소 권한을 기준으로 승인 정책을 나누게 됩니다.

클라우드 작업은 로컬 작업과 다른 실행 조건을 가집니다.