Claude 코드를 병렬로 돌리려면 Orca가 편리했다

서론

SonicMove 주식회사 엔지니어 nohe입니다.

지난 반년 동안은 구현을 거의 AI에 맡기게 되었습니다. VS Code는 열려 있지만, 화면은 거의 터미널이 차지하고 있었고, 에디터는 프롬프트 초안 작성 용도로만 사용했습니다.

그 과정에서 구현과 리뷰 등을 병행하면서, 구현 중인 브랜치가 바뀌거나 가끔 사고가 치는 상황이었습니다. 그래서 한 달 전부터 에이전트에게 맡기는 것을 전제로 만들어진 Orca로 바꿔보았고, 이에 대해 소개하고자 합니다.

먼저 결론부터 말씀드립니다.

• 에디터 중심의 환경에서 전환했음에도 불구하고,
  어색함 없이 사용할 수 있었습니다. - worktree 생성부터 설정, 에이전트 실행까지가
  하나의 작업으로 끝납니다. 따라서 git worktree를
  알지 못해도 병렬 개발을 시작할 수 있습니다. - 화면 수정 지시를,
  요소를 가리키며 코멘트로 지시할 수 있는 점이 편리했습니다.

Orca란 무엇인가요?

여러 AI 코딩 에이전트를 병렬로 구동하는 데스크톱 애플리케이션입니다. 공식적으로는 **ADE (Agent Development Environment)**라고 불립니다. 직접 작성하기보다는, 에이전트가 작성하게 하고 확인하기 위한 도구입니다.

• 작업별로
  독립된 git worktree를 생성하므로, 에이전트들끼리 파일을 겹치지 않습니다. - Claude Code, Codex, Cursor CLI 등,
  사용하던 CLI 에이전트를 그대로 사용할 수 있습니다. - 터미널, 에디터, diff 뷰, 브라우저가
  하나의 앱에 모여 있습니다. - 오픈 소스(MIT)이며 무료입니다. macOS / Windows / Linux를 지원합니다.

Orca에서는 worktree와 그 안에서 구동되는 에이전트 세트를 **워크스페이스 (workspace)**라고 부릅니다.

git worktree란 무엇인가요?

하나의 리포지토리에서, 다른 브랜치의 작업 디렉토리를 여러 개 만드는 git 기능입니다.

git worktree add ../myapp-feature-a -b feature/a # 생성
git worktree remove ../myapp-feature-a # 삭제

브랜치를 전환하지 않고도 여러 작업을 진행할 수 있기 때문에, 에이전트의 병렬 실행과 궁합이 좋습니다. 다만, 새로운 worktree에는 .env나 vendor/, node_modules/ 등 gitignore 처리된 파일들이 없습니다. 만들 때마다 설치나 DB 준비가 필요하고, 끝나면 정리도 해야 합니다.

설정하기

데모용 프로젝트

Laravel의 React 스타터 키트(Inertia + React)를 사용하여, 작업 목록만 있는 앱을 만들었습니다. 여기에 에이전트로 '기한' 기능을 추가해 나갈 예정입니다.

laravel new orca-demo --react --database=sqlite --pest --npm --no-boost

--no-boost는 Laravel Boost가 생성하는 CLAUDE.md의 영향을 피하고, 순수한 상태로 테스트하기 위함입니다.

설치 및 프로젝트 추가

공식 사이트에서 설치하여 실행하면, 먼저 기본 에이전트를 선택합니다. 이미 설치된 CLI 에이전트는 자동으로 감지됩니다.

다음으로 '프로젝트 추가'를 통해 리포지토리 폴더를 선택합니다.

추가한 폴더는 사이드바에 'Primary'로 표시됩니다.

워크스페이스 생성 시 설정 자동화하기

리포지토리 바로 아래에 두 개의 파일을 놓습니다.

.worktreeinclude에 적은 gitignore 대상 파일은, Primary 폴더에서 새로운 worktree로 복사됩니다 (glob 사용 불가).

.env

orca.yaml의 scripts.setup에는, 생성 시 실행할 명령어를 작성합니다. 중간에 실패하면 그 지점에서 멈춥니다.

setupAgentStartupPolicy: wait-for-setup

은, 세트업이 끝날 때까지 에이전트의 시작을 기다리게 하는 설정입니다. 기본값으로는 기다리지 않기 때문에, 설치 중에 에이전트가 테스트를 실행하다 실패하는 경우가 있습니다.

DB는 SQLite로 하고, worktree마다 별도의 파일에 저장합니다. 한 워크스페이스에서 마이그레이션을 시도해도 다른 곳에 영향을 주지 않습니다.

준비가 되면, 사이드바의 + (⌘N) 에서 워크스페이스를 만듭니다. 이름만 넣고 에이전트를 선택하면 됩니다.

스크립트를 처음 실행할 때는 확인 메시지가 뜹니다. '항상 신뢰'에 체크하면 다음부터는 물어보지 않습니다.

(실행하지 마세요🥺)

나머지는 'Setup' 탭에서 스크립트가 순서대로 실행됩니다. 생성은 백그라운드에서 진행되기 때문에 기다릴 필요가 없습니다.

3개의 워크스페이스를 병렬로 운영하기

업무에서는 다음 3가지 워크스페이스를 항상 열어둡니다. 데모에서도 같은 방식으로 진행할 수 있습니다.

| 역할 | 업무에서의 사용법 | 데모에서의 지시 | :--- |
| 조사/상담 | 현재 작업과 관련 없는 조사나 상담 내용 | "Laravel에서 날짜를 타임존을 포함하여 다룰 때 주의점을 알려줘" |
| ... |
분리해 두면, 구현 세션과 관계없는 이야기가 섞이지 않습니다. 문득 궁금해진 것도, 갑작스러운 리뷰 요청도 구현을 멈추지 않고 다른 워크스페이스에서 받을 수 있습니다.

사이드바에는 각 에이전트가 작업 중인지, 입력 대기 중인지, 완료 상태인지가 표시됩니다. 멈춰있는 세션을 찾아다닐 필요가 없어졌습니다.

구현: Design Mode로 화면 수정 지시하기

구현된 화면은 워크스페이스별 내장 브라우저에서 확인할 수 있습니다. 수정하고 싶은 부분은 Design Mode를 이용해 지시합니다.

• 브라우저 툴바에서 Design Mode를 켜기
• 고치고 싶은 요소를 클릭하기
• 코멘트를 작성하고, '변경' 또는 '질문'을 선택하여 추가하기

데모에서는 카드들끼리 붙어 있는 목록에 '여백이 너무 좁다'라고만 적었습니다.

코멘트는 페이지 위에 쌓이고, '전송'으로 한 번에 전달할 수 있습니다. 클릭한 요소의 HTML, CSS, 스크린샷도 함께 전달됩니다.

에이전트가 gap-0.5를 gap-3로 수정하고 푸시까지 완료했습니다. 장소를 말로 설명할 필요 없이, PR에 리뷰 코멘트를 남기는 느낌으로 지시할 수 있습니다.

리뷰: PR에서 워크스페이스 만들기

리뷰를 요청받으면, 새 워크스페이스의 이름 칸에 PR URL (또는 #2 같은 번호)을 넣습니다. PR 브랜치로부터 워크스페이스가 만들어지므로, 이제 에이전트에게 리뷰만 요청하면 됩니다.

CLI로 만들 경우

orca worktree create --pr 2

은 PR을 연결하는 것만으로 내용물이 origin/main에서 생성됩니다. PR 브랜치에서 만들려면, --base-branch origin/<PR의 브랜치명>도 추가해야 합니다.

분기원으로는 로컬 브랜치도 선택할 수 있으므로, 리뷰 중인 PR 위에 다음 작업을 쌓는(Stacked PRs) 것도 가능합니다.

코드에 대한 지적은 diff 뷰의 Annotate AI Diff에서 반환됩니다. diff 줄의 +부터 코멘트를 달고, Send to agent로 한 번에 보냅니다. Design Mode와 마찬가지로 수정은 한 번으로 끝납니다 (화면은 Docs 참조).

커밋부터 정리까지

커밋, 푸시, PR 생성까지 Orca 안에서 할 수 있습니다. 완료된 워크스페이스는 사이드바에서 삭제하면 브랜치 전체가 사라집니다.

Laravel에서 사용할 때 주의할 점

package.json에 name을 적어두기

package.json에 name이 없으면, npm install 할 때마다 package-lock.json의 name이 worktree 디렉토리 이름으로 덮어쓰여지면서, 만든 직후부터 차이가 발생합니다.

개발 서버 로그인 오버라이딩

여러 워크스페이스에서 composer run dev

실행해도 포트는 자동으로 변경됩니다 (PHP는 8000→8001, Vite는 5173→5174).

다만, cookie는 포트를 구분하지 않기 때문에 로그인이 서로 덮어쓰여집니다. Orca의 내장 브라우저에서도 cookie는 워크스페이스 간에 공유됩니다.

내장 브라우저에서는 워크스페이스별로 브라우저 프로필을 분리하면 해결할 수 있습니다. 평소 사용하는 브라우저라면, wt1.localhost:8000 와 같이 호스트명을 다르게 하여 열면 구분됩니다.

orca.yaml

를 커밋하기 어렵다면

팀에 Orca를 사용하지 않는 사람이 있다면, Settings → Repository에서 자신의 환경에만 설정할 수 있습니다.

node_modules 공유로 생성 속도 높이기

orca.yaml의 worktree.sharedDirectories에 작성된 디렉토리는 복사본이 아닌 링크로 공유됩니다. 생성이 빨라지지만, 브랜치 간 의존성이 다르면 깨질 수 있어 이번에는 사용하지 않았습니다.

worktree:
sharedDirectories:
- node_modules

토큰 소비를 줄이는 요령

병렬로 작업하면 이용 한도 감소 속도도 그만큼 빨라집니다. 제가 의식하고 있는 것은 다음 3가지입니다.

메인 에이전트는 판단에 전념시키고, 작업은 서브 에이전트에게 맡기기

서브 에이전트는 메인과는 다른 컨텍스트에서 작업하며, 결과의 요약만 반환하는 자식 에이전트입니다. 메인의 히스토리가 불필요하게 늘어나는 것을 막고, 작업 측을 가벼운 모델로 사용하면 소비를 줄일 수 있습니다. 예를 들어 메인으로 Fable을 사용할 때는 다음 규칙을 추가했습니다.

메인 세션은 판단에 전념하고, 검증 작업 등은 적절히 Opus나 Sonnet의 서브 에이전트에게 요청해 주세요.

구분이 끝나면 /clear 하기

이전 태스크의 히스토리가 이어지지 않도록 합니다. 경위를 남기고 싶을 때는 /compact로 요약합니다. 역할별로 워크스페이스를 나누는 것도 히스토리를 짧게 유지하는 데 효과적입니다.

사용량을 주기적으로 확인하기

Orca의 상태 표시줄에서 Claude 사용량과 리셋까지 남은 시간을 확인할 수 있습니다.

1개월 사용 후기

좋았던 점

가장 컸던 것은 설정 자동화입니다. git worktree는 전부터 알고 있었지만, 만들 때마다 설치하는 것이 번거로워서 사용하지 않았습니다. 이것이 자동으로 되면서 일상적으로 사용할 수 있게 되었습니다.

아쉬웠던 점

• 기능이 많아 다 따라잡지 못함: CLI에서의 조작, SSH 접속 후 실행, 스마트폰 컴패니언 앱 등은 아직 시도해보지 못했습니다. -
  업데이트가 빠름: 불편한 점이 바로 고쳐지는 반면, 동작 방식 자체가 바뀔 수도 있습니다. 팀으로 도입할 경우 버전을 맞추는 것이 안전합니다. -
  메모리: 상태 표시줄의 메모리 표시(Orca 본체 + 에이전트 + 개발 서버)는 터미널 하나로 약 670MB, 작업 중에는 약 1.7GB였습니다. 사용하지 않는 워크스페이스는 주기적으로 닫고 있습니다.

VS Code + 터미널과의 비교

| VS Code + 터미널 | Orca | |
|---|---|
| worktree 생성/삭제 | 수동으로 git worktree로 진행
| 사이드바에서. 브랜치도 정리됨 |
| 생성 시 설정 | 매번 수동 작업 필요 | orca.yaml로 자동화
| 에이전트 상태 | 터미널을 돌아다니며 확인해야 함 | 한눈에 파악 가능
| 화면 수정 지시 | 말이나 스크린샷으로 설명
| 요소(element)를 지정하여 코멘트로 전달
| 코드 지적 사항 | 지시문에 수동으로 정리해야 함 | diff에 커밋하며 반환
| 에디터 | 확장 기능이 풍부함 | 초안 작성이나 가벼운 수정에는 충분

요약

구현을 AI에게 맡기는 현재의 사용 방식에 Orca는 그대로 잘 맞았습니다. worktree를 강하게 의식하지 않고 병렬화할 수 있다는 점이 가장 큰 가치라고 생각합니다.

추천하는 사람

• Claude Code를 2개 이상 병행 사용하는 사람
• git worktree를 시도하고 싶지만, 수동 관리가 번거로운 사람
• 화면 구현도 직접 하는 사람

아닐 수도 있는 사람

• 에이전트 하나로 충분한 사람
• 현재 에디터의 확장 기능에 강하게 의존하는 사람

우선 본인의 리포지토리를 추가하고 워크스페이스를 2개 만들어 보세요.

참고

함께 읽으면 좋은 글

토론 (Discussion)