Orca 사용법: Codex·Claude Code 병렬 실행하기

Orca를 설치했다면 이제 실제 작업을 만들어볼 차례입니다. 이번 글에서는 하나의 문제를 Codex와 Claude Code에 동시에 맡기고, 두 결과를 비교한 뒤 더 나은 쪽을 선택하는 과정을 따라갑니다.

아직 설치하지 않았다면 먼저 Orca 설치 방법과 기본 설정을 확인해 주세요. Orca가 어떤 도구인지 궁금하다면 Orca, AI 코딩 에이전트를 위한 관리 도구부터 읽어도 좋습니다.

이번 실습에서 할 일

전체 흐름은 다음과 같습니다.

저장소 추가
→ 같은 기준점에서 worktree 2개 생성
→ Codex와 Claude Code에 같은 작업 요청
→ 브라우저와 테스트로 결과 확인
→ diff 비교
→ 더 나은 결과를 커밋하고 push

예시는 로그인 폼의 중복 제출 문제를 수정하는 작업입니다. 실제 프로젝트에서는 버그 수정, UI 시안 비교, 리팩터링 방법 탐색처럼 결과를 나란히 비교하고 싶은 작업을 넣으면 됩니다.

Orca를 사용하려면 로컬 Git 저장소와 사용할 에이전트 CLI가 준비되어 있어야 합니다. Codex나 Claude Code의 로그인과 기본 설정도 먼저 마쳐두는 편이 좋습니다.

1. Git 저장소 추가하기

Orca를 열고 저장소를 추가합니다. 이미 컴퓨터에 내려받은 프로젝트라면 로컬 폴더를 선택하면 됩니다.

저장소가 등록되면 기준 브랜치를 확인합니다. 보통 main이나 develop을 사용하며, 원격 저장소의 최신 상태에서 시작하려면 터미널에서 먼저 다음 명령을 실행합니다.

git fetch origin

여기서 저장소는 프로젝트의 기준점이고, 실제 에이전트 작업은 별도의 worktree에서 진행됩니다. Git 용어가 낯설다면 Repository 뜻과 Work Tree 뜻을 먼저 확인해도 좋습니다.

2. Codex용 worktree 만들기

저장소 화면에서 새 worktree를 만듭니다. 이름은 작업 목적과 에이전트를 함께 적으면 구분하기 쉽습니다.

이름: fix-login-codex
시작 기준: origin/main
에이전트: Codex

worktree가 만들어지면 독립된 작업 폴더와 브랜치, 에이전트 터미널이 준비됩니다. 원래 프로젝트 폴더를 복사해 쓰는 방식이 아니라 Git의 실제 worktree 기능을 이용하므로, 두 작업의 파일 변경과 브랜치가 서로 섞이지 않습니다.

Codex 터미널에 아래처럼 작업을 요청합니다.

로그인 폼의 중복 제출 문제를 확인하고 수정해주세요.

요구사항:
- 요청 중에는 제출 버튼을 비활성화할 것
- 기존 UI 스타일을 유지할 것
- 관련 테스트가 있다면 업데이트할 것
- 마지막에 수정한 파일과 검증 결과를 정리할 것

좋은 결과를 비교하려면 문제뿐 아니라 완료 조건과 검증 방법도 함께 전달하는 것이 중요합니다.

3. Claude Code용 worktree 만들기

두 번째 worktree도 같은 기준점에서 만듭니다.

이름: fix-login-claude
시작 기준: origin/main
에이전트: Claude Code

이번에도 앞에서 사용한 프롬프트를 그대로 입력합니다. 시작 기준과 요청이 같아야 구현 방식의 차이를 비교하기 쉽습니다.

Orca에서는 여러 worktree를 동시에 열고 상태를 확인할 수 있습니다. 한쪽 에이전트가 코드를 탐색하는 동안 다른 쪽은 구현이나 테스트를 진행할 수 있고, 필요하면 터미널 패널을 나눠 개발 서버와 에이전트를 함께 띄울 수도 있습니다.

다만 같은 문제라고 해서 항상 여러 에이전트를 실행할 필요는 없습니다. 정답이 분명한 작은 수정은 하나의 worktree로 충분합니다. 구현 방향이 여러 개이거나 결과를 비교할 가치가 있을 때 병렬 작업의 효율이 커집니다.

4. 브라우저에서 결과 확인하기

에이전트가 작업을 마치면 각 worktree에서 프로젝트를 실행합니다. 프로젝트에 맞는 패키지 관리자를 사용하면 됩니다.

pnpm install
pnpm dev

Orca의 브라우저는 worktree별 개발 화면을 확인할 수 있는 Chromium 기반 브라우저입니다. 별도의 브라우저 창과 터미널을 오가지 않고, 에이전트가 수정한 UI를 같은 작업 공간에서 바로 확인할 수 있습니다.

두 개발 서버를 동시에 실행하면 포트가 겹칠 수 있습니다. 한쪽은 3000, 다른 쪽은 3001처럼 서로 다른 포트를 사용하세요. 프레임워크가 자동으로 다음 포트를 선택했다면 터미널에 표시된 주소를 확인하면 됩니다.

로그인 버튼을 빠르게 두 번 눌렀을 때 요청이 한 번만 처리되는지, 요청 중 버튼이 비활성화되는지, 기존 디자인이 깨지지 않았는지 차례로 확인합니다. 화면만 보지 말고 에이전트가 실행한 테스트 결과와 브라우저 콘솔 오류도 함께 살펴보는 편이 안전합니다.

5. 두 구현의 diff 비교하기

이제 각 worktree의 diff를 엽니다. Orca의 diff 화면에는 시작 기준 이후 변경된 내용이 표시되며, staged·unstaged 파일과 새로 만든 파일을 함께 검토할 수 있습니다.

두 결과를 비교할 때는 코드 양보다 다음 항목을 먼저 확인합니다.

요청한 조건을 모두 충족했는가
기존 코드 구조와 자연스럽게 어울리는가
불필요한 파일까지 수정하지 않았는가
테스트가 추가되거나 기존 테스트가 통과했는가
오류 처리와 접근성까지 고려했는가

예를 들어 Codex 결과는 수정 범위가 작고 기존 테스트를 활용했지만, Claude Code 결과는 별도의 상태 관리 로직과 새로운 테스트를 추가했을 수 있습니다. 어느 쪽이 더 좋은지는 변경 줄 수가 아니라 프로젝트의 규칙과 유지보수 비용을 기준으로 판단해야 합니다.

검토 중 발견한 문제는 주석으로 남기거나 해당 에이전트에 다시 요청해 보완할 수 있습니다. 첫 결과를 그대로 채택하기보다 ‘이 상태에서 한 번 더 리뷰한다’는 감각으로 사용하는 것이 좋습니다.

6. 선택한 결과 커밋하고 push하기

더 나은 결과를 고른 뒤 필요한 변경만 stage합니다. Orca의 diff 화면에서는 파일 단위뿐 아니라 변경 묶음 단위로도 stage할 수 있어, 에이전트가 만든 불필요한 수정은 제외할 수 있습니다.

커밋 메시지를 작성하고 커밋합니다.

fix: prevent duplicate login submissions

커밋 과정에서는 저장소에 설정된 Git hook도 실행됩니다. 검사에 실패했다면 우회하기보다 오류 내용을 확인하고 수정하는 편이 좋습니다. 커밋 개념이 낯설다면 Commit 뜻에서 간단히 확인할 수 있습니다.

그다음 브랜치를 원격 저장소에 push합니다. Orca는 필요한 upstream을 설정해 push할 수 있지만, 기존 원격 기록을 바꾸는 force push를 조용히 실행하지는 않습니다. push가 끝나면 호스팅된 리뷰 화면이나 GitHub에서 Pull Request를 만들어 최종 검토를 진행합니다.

선택하지 않은 worktree는 필요한 코드가 없는지 다시 확인한 뒤 삭제합니다. worktree 삭제는 해당 작업 디렉터리와 브랜치에 영향을 줄 수 있으므로, 남겨야 할 변경이 있다면 먼저 커밋하거나 다른 곳으로 옮겨야 합니다.

막힐 때 확인할 것

에이전트가 실행되지 않는다면 Codex 또는 Claude Code CLI가 터미널에서 정상적으로 실행되는지 먼저 확인하세요. Orca를 실행한 환경에서 CLI 경로를 찾지 못하는 경우도 있습니다.

worktree 생성에 실패한다면 git fetch origin을 실행하고 시작 기준으로 선택한 브랜치가 실제로 존재하는지 확인합니다. 개발 서버가 열리지 않으면 해당 worktree에서 의존성을 설치했는지, 사용하려는 포트가 이미 사용 중인지 살펴보세요.

또한 worktree는 작업을 분리하는 Git 기능이지 보안 샌드박스는 아닙니다. 에이전트가 실행하려는 명령과 파일 접근 범위를 확인하고, 중요한 환경 변수나 운영 데이터는 작업 공간에 그대로 두지 않는 것이 좋습니다.

마치며

Orca의 핵심은 에이전트에게 명령을 보내는 것보다 여러 작업을 분리하고 비교하며 검토하는 과정에 있습니다. 처음에는 두 worktree에 같은 작은 버그를 맡겨보세요. 브라우저와 diff를 오가며 결과를 비교해 보면, 어떤 작업에 병렬 에이전트가 유용한지 빠르게 감을 잡을 수 있습니다.

어떤 사람에게 이 방식이 잘 맞는지는 Orca는 누가 사용하면 좋을까? 활용 사례 정리에서 더 자세히 정리했습니다.

자주 묻는 질문

꼭 두 개의 AI 에이전트를 사용해야 하나요?

아닙니다. 하나의 worktree에서 한 에이전트만 사용해도 됩니다. 결과를 비교하고 싶거나 서로 다른 구현 방식을 탐색할 때 여러 worktree를 만드는 방식이 유용합니다.

같은 worktree에서 Codex와 Claude Code를 함께 실행해도 되나요?

가능하더라도 같은 파일을 동시에 수정하면 변경 내용이 섞이거나 충돌할 수 있습니다. 결과를 독립적으로 비교하려는 목적이라면 에이전트마다 worktree를 나누는 편이 안전합니다.

두 에이전트에 반드시 같은 프롬프트를 입력해야 하나요?

공정하게 결과를 비교하려면 시작 기준과 핵심 요구사항을 같게 유지하는 것이 좋습니다. 이후 보완 요청은 각 결과의 문제에 맞춰 다르게 전달해도 됩니다.

개발 서버 포트가 겹치면 어떻게 하나요?

각 worktree에서 서로 다른 포트를 지정하세요. 예를 들어 한쪽은 3000, 다른 쪽은 3001을 사용하면 두 화면을 동시에 확인할 수 있습니다.

worktree를 삭제하면 작업한 코드도 사라지나요?

커밋하지 않은 변경은 잃을 수 있습니다. 삭제 전 diff를 확인하고 필요한 변경은 커밋하거나 별도로 보관하세요. Orca도 삭제 전에 확인 과정을 거칩니다.

GitHub가 꼭 필요한가요?

로컬 worktree 생성과 비교, 커밋까지는 Git 저장소만으로 진행할 수 있습니다. GitHub는 원격 push와 Pull Request를 이용해 협업하거나 리뷰할 때 필요합니다.