Codex 작업 하나가 돌아가고 있고, 넘기고 싶은 버그 수정이 있고, 커버리지가 필요한 테스트 스위트가 있고, 계속 미뤄온 리팩터링이 있습니다. 이 네 가지는 서로 독립적입니다. 동시에 실행하지 못할 이유는 없습니다. 다만 현실적인 이유 하나가 있습니다. 두 개의 Codex 세션을 같은 체크아웃에 연결하면 서로의 수정을 덮어쓰기 시작합니다. 원했던 병렬성이 원하지 않았던 병합으로 바뀌는 것이죠.
Codex 작업을 여러 개 동시에 실행하는 것은 켜는 기능이라기보다 짜맞추는 설정에 가깝습니다. 방법은 세 가지입니다. Codex 클라우드 작업, 여러 개의 로컬 CLI 세션, 그리고 하나의 세션 안에서 돌아가는 서브에이전트입니다. 각각 실제 동시성을 제공하지만, 쓰기가 겹치는 순간 드러나는 실패 유형을 하나씩 가지고 있습니다. 이 가이드에서는 세 가지 방법을 명령어와 함께 살펴보고 각 단계에서 발생하는 실패를 짚은 다음, 태스크 보드가 어디서부터 그 역할을 대신하는지 보여줍니다.
그 태스크 보드가 바로 Sharkly입니다. Codex는 이미 가지고 계실 겁니다. Sharkly는 그 위에 올라갑니다. Codex를 Runtime으로 실행하고, 각 병렬 실행을 자체적인 격리된 체크아웃과 로그, 리뷰어를 가진 Task로 바꿔줍니다. 이 글에서는 수동 설정을 먼저 다룹니다. 자동화하기 전에 무엇을 자동화하는지 이해해야 하니까요.
TL;DR
Codex 병렬 에이전트란 한 번에 하나씩이 아니라 여러 Codex 작업을 동시에 실행하는 것을 뜻합니다. 방법은 세 가지입니다. Codex 클라우드 작업(OpenAI 문서에 따르면 각각 격리된 환경에서 실행), 여러 개의 로컬 codex CLI 세션, 또는 하나의 세션 안에 있는 서브에이전트입니다. 이 모든 방법을 관통하는 원칙은 작업 단위마다 작업 복사본 하나입니다. 즉 각 작업에 자체 git worktree를 부여해서 동시 수정이 같은 파일을 건드리지 않도록 하는 것입니다. 작업이 몇 개일 때는 문제없이 확장됩니다. 그 이상으로 넘어가면 어떤 에이전트가 무엇을 했는지 추적하고 각 결과를 개별적으로 리뷰하는 일이 병목이 되는데, Sharkly가 바로 이 계층을 추가합니다.
Codex를 병렬로 실행하는 세 가지 방법
어떤 방법이 가장 강력해 보이는지가 아니라, 작업이 어디서 실행되는지와 얼마나 많은 것을 확인해야 하는지를 기준으로 방법을 고르세요.
| 방법 | 실행 방식 | 격리 | 적합한 용도 |
|---|---|---|---|
| Codex 클라우드 작업 | 각 작업이 자체 클라우드 환경에서 실행 | 작업별로 강력한 격리 | 위임해서 나중에 리뷰하는 독립적인 작업 |
| 여러 CLI 세션 | 내 컴퓨터에서 여러 codex 프로세스 실행 |
기본적으로 없음, 체크아웃 공유 | 실시간으로 지켜보고 싶은 로컬 작업 |
| 한 세션 안의 서브에이전트 | 하나의 세션이 생성된 스레드를 디스패치 | 세션 디렉터리 공유 | 읽기 위주의 작업: 탐색, 트리아지, 테스트 |
작업 범위가 명확하고 나중에 결과를 확인해도 괜찮다면 Codex 클라우드 작업을 사용하세요. 실행되는 과정을 직접 조율하고 싶다면 로컬 CLI 세션을 사용하세요. 작업이 대부분 읽기라면 서브에이전트를 사용하세요. 생성된 에이전트들이 하나의 작업 디렉터리를 공유하고, Codex 서브에이전트 동작 방식에 따르면 세션이 이들 모두를 기다린 뒤 하나로 통합된 응답을 반환하기 때문입니다. 이 마지막 방식은 병렬 쓰기에는 맞지 않습니다. 에이전트들이 동시에 코드를 수정하면 충돌이 생기고, 하나의 요약은 부분별로 리뷰할 수 없습니다.
단계별 가이드: 충돌 없이 여러 Codex 작업을 로컬에서 실행하기
로컬 방식은 대부분의 사람이 가장 먼저 손을 뻗는 방법이자, 가장 먼저 무너지는 방법입니다. 여기 살아남는 설정을 소개합니다.
1단계. 각 작업에 자체 체크아웃을 부여하세요. git worktree는 같은 저장소를 기반으로 하면서 자체 브랜치를 가진 두 번째 작업 디렉터리입니다. 작업마다 하나씩 만드세요:
git worktree add ../app-authfix -b fix/token-refresh
git worktree add ../app-tests -b test/checkout-coverage
git worktree add ../app-refactor -b refactor/api-client
이 단계를 건너뛰면 생기는 문제: 같은 폴더에서 두 개의 codex 세션이 같은 파일을 수정하고, 나중에 쓴 내용이 조용히 이기며, 둘 다 성공했다고 보고합니다. 손실은 리뷰 단계에서, 아니면 프로덕션에서 발견하게 됩니다.
2단계. worktree마다 Codex 세션을 하나씩 시작하세요. 각 디렉터리에서 터미널을 열고 그곳에서 Codex를 실행하세요:
cd ../app-authfix && codex
이 단계를 건너뛰면 생기는 문제: 컨텍스트에 네 가지 목표를 담은 세션 하나가 목표 사이를 오가며 어떤 변경이 어떤 작업에 속하는지 놓치게 됩니다.
3단계. 사람이 키보드 앞에 있을 필요 없는 작업은 스크립트로 돌리세요. 독립적인 작업이라면 비대화형 모드가 프롬프트 없이 끝까지 실행됩니다:
cd ../app-tests && codex exec "add tests for the checkout flow until coverage passes"
이 단계를 건너뛰면 생기는 문제: 굳이 지켜볼 필요도 없었던 세션을 붙잡고 앉아 있게 되고, 병렬로 돌리는 의미가 사라집니다.
4단계. 한 번에 브랜치 하나씩, 신중하게 병합하세요. 각 worktree는 하나의 브랜치이므로 따로따로 리뷰하고 병합하세요. 에이전트끼리 서로의 작업을 병합하게 두지 마세요. 이 단계를 건너뛰면 생기는 문제: 세 브랜치가 한꺼번에 반영되고, 병합 커밋에서 충돌이 드러나는데, 어느 에이전트의 변경이 원인인지 더는 알 수 없게 됩니다.
작업이 끝난 뒤 worktree를 깔끔하게 정리하는 방법은 정리 작업의 번거로움 없이 코딩 에이전트용 worktree 관리하기를 참고하세요. 같은 worktree 패턴이 여러 Claude Code 에이전트 실행하기에도 적용됩니다. 설계 자체가 런타임 중립적이기 때문입니다.
직접 구성한 설정이 확장을 멈추는 지점
worktree는 충돌을 해결해 줍니다. 하지만 모든 것을 해결하지는 못하며, 한계는 보이는 것보다 가까이 있습니다.
작업이 서너 개일 때는 이 설정이 버텨줍니다. 여덟 개쯤 되면 터미널 격자는 작업 공간이 아니라 기억력 테스트가 됩니다. 실패는 극적이지 않고, 조금씩 쌓입니다:
- 지도를 잃어버립니다. 어느 창이 인증 수정이었지? 어느 게 끝났지? 어느 게 20분 전에 실패하고 그 뒤로 멈춰 있지? 상태는 머릿속에만 존재하고, 화면에서는 스크롤과 함께 사라집니다.
- 리뷰에 이음새가 없습니다. 각 세션의 출력은 스크롤백의 벽입니다. 무엇을 건드렸고, 무엇을 실행했고, 어디서 멈췄는지에 대한 작업별 기록이 없으니, 한 결과는 받아들이고 다른 결과는 깔끔하게 거부할 수가 없습니다.
- 공유되는 것이 없습니다. 동료가 진행 상황을 봐야 하는 순간, 여러분은 diff를 Slack 스레드에 복사해 붙여넣고 있습니다. 작업은 실재하지만 보이지 않습니다.
이것은 모든 병렬 에이전트 워크플로가 결국 수렴하는 동일한 세 가지 문제이며, 개수가 늘어나면 팀이 병렬 코딩 에이전트를 관리하는 전용 도구를 찾게 되는 이유입니다. 격리는 이미 해결된 문제입니다. 가시성과 리뷰는 그렇지 않습니다. 적어도 터미널 격자로는요.
태스크 보드가 더해 주는 것
바로 여기서 에이전트 위에 얹히는 계층이 존재 가치를 증명합니다. Sharkly에서 Task는 하나의 작업 단위에 대한 공유 기록이며, Codex 작업을 병렬로 실행하는 일은 Task를 병렬로 실행하는 일이 됩니다.
각 Task는 자동으로 격리된 git worktree를 확보하므로, 격리된 worktree에서 실행되는 병렬 에이전트는 스크립트로 직접 짜야 하는 것이 아니라 기본값이 됩니다. 하나의 저장소에 대해 Task 열 개, 공유 상태는 전무, git worktree add를 손으로 입력할 필요도 없습니다. 편집을 수행하는 Runtime은 여전히 Codex이고, 격리는 그 주위에 제공됩니다.
핵심은 역할 분담입니다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 받아들입니다. 자동화는 팀의 판단이 필요한 지점에서 멈춥니다. 그래서 각 실행은 트리거와 도구 호출, 중단 지점을 담은 자체 실행 로그를 유지하고, 최종 결과는 터미널에서 흘러 지나가는 대신 Task로 돌아옵니다. 컨텍스트, 진행 상황, 장애 요소, 결과, 사람의 리뷰가 요청부터 릴리스까지 계속 보이고, 요약의 요약을 읽는 대신 각각을 개별적으로 리뷰합니다. 이와 관련된 보고 측면은 AI 코딩 에이전트가 완료한 작업을 추적하는 방법을 참고하세요.
Sharkly는 Codex를 대체하는 것이 아닙니다. 이미 실행 중인 에이전트 주위에 공유 태스크, 체크아웃, 컨텍스트, 리뷰 계층을 더해줍니다. Codex 세션을 한 번에 하나만 실행한다면 필요하지 않습니다. 하나의 코드베이스에 여러 세션을 돌리다가 흐름을 놓치고 있다면, 바로 그 문제를 위해 만들어진 것입니다. 위의 worktree 설정을 직접 구축해도 되고, 기존 Codex 작업을 Sharkly로 실행해서 워크플로가 상태를 대신 관리하게 해도 됩니다.
오늘 바로 실행할 수 있는 체크리스트
- 작업마다 git worktree 하나, 각각 자체 브랜치에. 두 작업이 같은 체크아웃을 공유하지 않도록 합니다.
- worktree마다 Codex 세션 하나, 또는 사람이 필요 없는 작업에는
codex exec를 사용합니다. - 서브에이전트는 읽기 위주 작업에만 사용하고, 동시 쓰기는 별도 체크아웃에서 처리합니다.
- 한 번에 브랜치 하나씩 병합하고, 반영되기 전에 각각을 리뷰합니다.
- 어떤 작업이 무엇인지, 각 작업이 무엇을 건드렸는지, 결과는 무엇인지를 동료가 볼 수 있는 곳에 기록해 둡니다.
- 터미널 격자가 머릿속에 담기지 않기 시작하면, 추적과 리뷰를 Task 보드로 옮겨 각 실행이 결과를 하나의 공유된 장소로 반환하도록 합니다.
FAQ
Codex가 여러 작업을 동시에 실행할 수 있나요? 네. Codex 클라우드는 OpenAI 문서에 따라 격리된 환경에서 작업을 실행하며, 로컬에서는 여러 개의 codex 세션을 동시에 실행할 수 있습니다. 제약은 Codex가 아니라 체크아웃입니다. 각 로컬 작업에 자체 git worktree를 부여해서 수정 내용이 충돌하지 않게 하세요.
병렬 Codex 에이전트를 몇 개나 실행할 수 있나요? 머신과 모델 할당량이 허용하는 만큼입니다. 다만 현실적인 상한은 더 낮습니다. 한 사람이 실제로 리뷰할 수 있는 동시 결과의 개수입니다. 몇 개를 넘어가면 연산 능력이 아니라 추적과 리뷰가 한계가 됩니다.
worktree가 꼭 필요한가요, 아니면 터미널을 더 열기만 하면 되나요? 같은 디렉터리에서 터미널을 더 여는 것은 같은 파일에 대한 동시 쓰기와 조용한 덮어쓰기를 의미합니다. worktree는 각 세션에 자체 디렉터리와 브랜치를 부여하며, 이것이 로컬 병렬 실행을 안전하게 만드는 요소입니다. AI 코딩 에이전트를 위한 git worktree를 참고하세요.
Codex 서브에이전트와 병렬 작업의 차이는 무엇인가요? 서브에이전트는 하나의 세션 안에서 실행되고, 그 세션의 작업 디렉터리를 공유하며, 하나로 통합된 응답을 반환합니다. 읽기와 트리아지에 적합합니다. 병렬 작업은 각각 별도의 체크아웃을 가진 독립적인 실행이며, 동시 쓰기와 독립적인 리뷰에 적합합니다.
