Orca orchestration 사용법: coordinator와 worker 연결하기

Orca에서 Codex와 Claude Code를 각각 실행하는 것만으로도 병렬 작업은 할 수 있습니다. 하지만 사람이 모든 worktree를 만들고, 프롬프트를 복사하고, 완료 여부를 하나씩 확인해야 합니다.

Orca orchestration은 이 관리 역할을 coordinator 에이전트에게 맡길 때 사용합니다. coordinator는 큰 목표를 Task로 나누고, 각 Task를 별도의 worker에 연결하며, 질문이나 완료 보고를 하나의 Run 안에서 추적합니다.

이 글에서는 최신 Orca CLI를 기준으로 orchestration 스킬을 준비하고, coordinator가 Codex worker 하나를 감독하는 최소 실습부터 병렬 worker, 작업 의존성, 질문과 응답까지 단계별로 살펴봅니다.

Orca 설치와 일반적인 worktree 사용이 처음이라면 Orca 설치 방법과 기본 설정, Orca에서 Codex·Claude Code 병렬 실행하기를 먼저 확인해 주세요.

먼저 구분해야 할 세 가지 방식

병렬 실행, handoff와 orchestration은 비슷해 보이지만 작업의 소유권과 완료 확인 방식이 다릅니다.

방식	작업을 나누는 사람	기존 에이전트가 결과를 기다리는가	적합한 상황
수동 병렬 실행	사용자	사용자가 직접 확인	같은 문제의 여러 구현 비교
handoff	사용자 또는 기존 에이전트	아니요	다른 에이전트에게 작업 소유권을 완전히 넘길 때
supervised orchestration	coordinator 에이전트	예	여러 Task, 완료 추적, 질문·응답과 의존성 관리

예를 들어 “새 worktree에서 Codex가 이 작업을 이어서 맡아줘”라는 요청은 보통 handoff입니다. 반면 “두 worker에게 나눠 맡기고, 완료를 기다린 뒤 결과를 종합해줘”라는 요청은 orchestration에 가깝습니다.

단순 handoff에 orchestration Task를 만들면 원래 에이전트가 계속 결과를 기다려야 하는 불필요한 생명주기가 생깁니다. 반대로 완료 결과를 종합해야 하는 작업을 단순 터미널 전송으로 처리하면 누가 어떤 Task를 맡았고 끝났는지 추적하기 어렵습니다.

Run, Task, Dispatch, worker 이해하기

Orca orchestration에는 네 가지 핵심 개념이 있습니다.

Run: 전체 목표와 coordinator의 받은 편지함
├─ Task A: 구현할 작업 단위
│  └─ Dispatch A: Task A를 Codex worker에게 배정한 한 번의 시도
└─ Task B: 검토할 작업 단위
   └─ Dispatch B: Task B를 Claude Code worker에게 배정한 한 번의 시도

Run은 전체 협업의 범위와 메시지함입니다. worker를 자동으로 배치하는 스케줄러는 아닙니다.
Task는 완료 조건을 가진 작업 항목입니다. 다른 Task와의 의존성도 지정할 수 있습니다.
Dispatch는 특정 Task를 특정 worker 터미널에 배정한 한 번의 실행 기록입니다.
worker는 실제 코드를 읽고 수정하거나 검토하는 Codex, Claude Code 등의 에이전트입니다.

coordinator는 worker를 직접 선택하고 worktree 위치도 정합니다. Orca가 수정 파일의 충돌 가능성을 판단하거나 적절한 에이전트를 자동 선택해주지는 않습니다.

시작 전 준비

1. Orca runtime 확인하기

orca orchestration 명령은 실행 중인 Orca runtime에 요청을 보냅니다. Orca 앱을 열고 상태를 확인합니다.

Orca runtime 시작과 상태 확인

orca open

orca status --json

Linux 패키지에서 실행 파일 이름이 orca-ide라면 이 글의 orca를 orca-ide로 바꿔 입력합니다.

2. Experimental 기능 켜기

Orca의 Settings → Experimental에서 orchestration 기능을 활성화합니다. 이 설정이 꺼져 있으면 CLI가 설치되어 있어도 Run이나 Task를 만들 수 없습니다.

3. orchestration 스킬 설치하기

스킬은 에이전트에게 현재 Orca 버전에 맞는 명령과 협업 규칙을 알려줍니다. orca-cli와 orchestration을 함께 설치합니다.

Orca 스킬 설치

orca skills install --skill orca-cli --skill orchestration

기본 설치 범위는 전역입니다. 현재 프로젝트에만 설치하려면 --local을 추가하고, 특정 에이전트만 대상으로 삼으려면 다음처럼 지정합니다.

Codex와 Claude Code에만 프로젝트 로컬 설치

orca skills install --skill orca-cli --skill orchestration --agent claude-code,codex --local

설치 후 실제 작업을 시작하기 전에는 Orca 앱 버전과 함께 제공된 최신 가이드를 불러오는 편이 안전합니다.

현재 버전의 전체 orchestration 가이드 확인

orca skills get orchestration --full

Orca는 빠르게 업데이트되며 명령 계약도 바뀔 수 있습니다. 에이전트가 과거 예시를 기억해 실행하게 두기보다, 이 명령으로 현재 가이드를 먼저 읽도록 요청하세요.

4. coordinator 터미널 정하기

Orca 안에서 Codex나 Claude Code 터미널 하나를 열고 coordinator 역할을 맡깁니다. 이후의 run-create, task-create, check 명령은 이 coordinator 터미널에서 실행하는 것이 가장 단순합니다.

Orca orchestration 스킬을 사용해 이 작업을 감독해주세요. 먼저 orca skills get orchestration --full로 현재 가이드를 확인하고, Run과 Task를 만든 뒤 worker를 배정하세요. 모든 worker_done 또는 escalation을 확인할 때까지 기다리고, 결과를 검토해 최종 요약을 작성해주세요.

Coordinator prompt

Orca 밖의 일반 셸에서도 --from <terminal-handle>을 명시해 일부 명령을 실행할 수 있지만, 처음에는 활성 coordinator 터미널 안에서 시작하는 편이 오류가 적습니다.

최소 실습: Codex worker 하나 감독하기

예시는 현재 프로젝트의 로그인 중복 제출 문제를 Codex worker에게 맡기는 흐름입니다. 명령 결과는 --json으로 받고, 다음 명령에 필요한 ID를 복사해 사용합니다.

1. Run 만들기

Run은 전체 목표와 coordinator의 메시지함을 만듭니다. 하나의 협업 흐름에서 처음 한 번만 생성합니다.

Run 생성

orca orchestration run-create --objective "로그인 중복 제출 문제를 수정하고 검증한다" --json

run-create는 새 Run을 만들고 현재 coordinator 터미널에 연결합니다. Run 자체가 worker를 실행하거나 작업을 자동 분배하지는 않습니다.

2. Task 만들기

worker가 판단할 수 있도록 작업 범위, 완료 조건과 검증 방법을 --spec에 함께 적습니다.

Task 생성

orca orchestration task-create \
  --task-title "로그인 중복 제출 수정" \
  --spec "로그인 폼의 중복 제출 원인을 찾아 수정한다. 요청 중에는 버튼을 비활성화하고 기존 UI를 유지한다. 관련 테스트를 실행한 뒤 수정 파일과 검증 결과를 보고한다." \
  --json

반환된 JSON에서 Task ID를 확인합니다. 아래 예시의 <task_id>를 실제 값으로 바꿉니다.

3. worker 시작하기

Task를 Codex worker와 새 child worktree에 연결합니다.

새 worktree에서 Codex worker 시작

orca orchestration worker-start \
  --task <task_id> \
  --worktree new-child \
  --name fix-login-submit \
  --agent codex \
  --setup run \
  --json

worker-start는 새 worktree와 에이전트 터미널을 만들고, Task 설명과 완료 보고 규칙을 worker에게 주입합니다. 반환값이 ready라면 작업을 받을 준비가 된 것입니다. 저장소 setup이 running으로 보이는 것은 setup을 에이전트와 동시에 실행하도록 구성한 프로젝트에서는 정상일 수 있습니다.

새 worktree가 필요 없고 현재 worktree의 별도 터미널에서 읽기 전용 조사를 맡기고 싶다면 --worktree current를 사용할 수 있습니다. 같은 파일을 수정하는 worker 여러 개를 current에 함께 실행하면 변경이 섞일 수 있으므로 구현 작업에는 별도 worktree를 권합니다.

4. 질문·완료 메시지 기다리기

coordinator는 짧은 주기로 터미널을 계속 읽는 대신 orchestration 메시지를 기다립니다.

worker의 질문·완료·에스컬레이션 대기

orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json

15분 안에 메시지가 없어서 timeout이 발생해도 worker 실패를 뜻하지는 않습니다. 코딩 작업이 계속 진행 중일 수 있으므로 worker 상태와 터미널이 살아 있는지 확인하고 다시 기다립니다.

메시지 묶음에는 delivery_id가 포함됩니다. Orca는 이 묶음을 확인 처리하기 전까지 같은 내용을 다시 반환하므로, 모든 메시지를 읽고 필요한 응답과 정리를 마친 뒤 acknowledge해야 합니다.

5. worker 결과 확인하고 정리하기

worker_done을 받으면 먼저 결과와 diff, 테스트를 검토합니다. 별도의 후속 Task에 같은 터미널을 바로 재사용하지 않는다면 완료된 worker를 release합니다.

완료된 worker 터미널 정리

orca orchestration worker-release --dispatch <dispatch_id> --json

worker-release는 완료되었거나 실패로 확정된 supervised worker의 에이전트 터미널만 정리합니다. 기록된 출력은 이후에도 확인할 수 있습니다. timeout, heartbeat, 질문 또는 단순한 TUI 유휴 상태만 보고 실행해서는 안 됩니다.

메시지를 모두 처리하고 release 여부까지 결정했다면 기존 Delivery를 acknowledge하면서 다음 메시지를 기다릴 수 있습니다.

메시지 확인 처리 후 계속 대기

orca orchestration check --ack <delivery_id> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

필요한 모든 Dispatch가 worker_done 또는 명확한 실패 상태로 끝날 때까지 이 과정을 반복합니다.

두 worker를 병렬로 실행하기

서로 독립적인 Task라면 Task를 모두 먼저 만든 뒤 worker를 연속으로 시작하고, 그다음 완료 메시지를 기다립니다.

독립 Task 두 개 생성

orca orchestration task-create --task-title "API 수정" --spec "로그인 API의 중복 요청 방지 로직을 구현하고 테스트한다." --json

orca orchestration task-create --task-title "UI 테스트 보강" --spec "로그인 폼의 중복 제출을 재현하는 테스트와 접근성 검사를 보강한다." --json

독립 작업을 현재 feature worktree의 하위 작업으로 진행한다면 서로 다른 child worktree에 배치할 수 있습니다.

Codex와 Claude Code worker 병렬 시작

orca orchestration worker-start --task <api_task_id> --worktree new-child --name login-api --agent codex --setup run --json

orca orchestration worker-start --task <test_task_id> --worktree new-child --name login-tests --agent claude --setup run --json

두 Task가 같은 파일을 수정할 가능성이 높다면 무리하게 병렬화하지 마세요. 파일 소유권을 나누거나, 구현 완료 후 검토 Task를 시작하는 의존 관계로 바꾸는 편이 안전합니다.

완전히 독립된 repo-wide 작업이라면 active worktree의 자식으로 만들기보다 new-top-level과 명시적인 저장소 selector를 사용합니다. 먼저 orca repo list --json으로 정확한 selector를 확인합니다.

독립된 top-level worktree에 worker 배치

orca orchestration worker-start \
  --task <task_id> \
  --worktree new-top-level \
  --repo name:<repo_name> \
  --base-branch main \
  --name independent-audit \
  --agent codex \
  --setup run \
  --json

Task 의존성으로 실행 순서 정하기

테스트나 리뷰가 구현 결과에 의존한다면 두 Task를 동시에 시작하면 안 됩니다. 먼저 구현 Task를 만들고, 반환된 ID를 리뷰 Task의 --deps에 넣습니다.

구현 완료 후 실행 가능한 리뷰 Task 만들기

orca orchestration task-create \
  --task-title "구현 결과 리뷰" \
  --spec "구현 diff를 검토하고 회귀 위험과 누락된 테스트를 보고한다. 코드는 수정하지 않는다." \
  --deps '["<implementation_task_id>"]' \
  --json

의존 Task가 끝나기 전에는 리뷰 Task가 대기 상태입니다. 실행 가능한 Task만 확인하려면 다음 명령을 사용합니다.

실행 가능한 Task 확인

orca orchestration task-list --ready --brief --json

선행 Task가 완료된 뒤 리뷰 Task를 새 worker에 배정합니다. Orca는 Task 의존성을 기록하지만, 어느 worktree의 변경을 어떤 방법으로 리뷰 worker에게 전달할지는 coordinator가 설계해야 합니다. 같은 worker 터미널을 후속 Task에 재사용하거나, 커밋·브랜치·diff 경로를 Task 설명에 명확히 적으세요.

worker가 질문하면 답하는 방법

worker는 요구사항이 불분명하거나 사람의 결정이 필요할 때 coordinator에게 질문할 수 있습니다.

worker가 선택지를 포함해 질문

orca orchestration ask --question "기존 API 응답 형식을 유지할까요?" --options "유지,변경" --timeout-ms 600000 --json

coordinator의 check에는 question 메시지와 message ID가 도착합니다. 내용을 확인한 뒤 답합니다.

coordinator가 worker 질문에 답하기

orca orchestration reply --id <message_id> --body "기존 응답 형식을 유지하세요." --json

질문의 대기 시간이 끝나도 질문 자체가 사라지는 것은 아닙니다. worker는 같은 질문을 새로 만들지 말고 기존 message ID로 대기를 이어갑니다.

기존 질문 응답 계속 기다리기

orca orchestration ask --resume <message_id> --timeout-ms 600000 --json

Task DAG의 진행 여부를 coordinator가 사람에게 결정받아야 한다면 별도의 decision gate를 사용할 수 있습니다. 일반적인 worker 질문에는 ask와 reply를 사용하고, Task 자체를 막는 승인 단계에만 gate를 사용합니다.

실행 중인 worker에 후속 지시 보내기

supervised worker에는 일시적인 터미널 handle보다 Dispatch 주소로 메시지를 보내는 편이 안전합니다.

특정 worker Dispatch에 후속 지시

orca orchestration send \
  --to dispatch:<dispatch_id> \
  --subject "검증 범위 추가" \
  --body "모바일 뷰포트에서 중복 제출이 재현되는지도 확인해주세요." \
  --json

이 메시지는 구조화된 inbox mail입니다. 이미 실행 중인 TUI 입력창에 문자를 강제로 넣는 명령과는 다릅니다. worker가 orchestration 메시지를 확인할 수 있도록 처음부터 스킬과 Dispatch 규칙을 적용해야 합니다.

worker의 최근 출력이 필요하면 전체 터미널을 무제한으로 읽기보다 bounded output을 요청합니다.

worker 상태와 최근 출력 확인

orca orchestration worker-show --dispatch <dispatch_id> --json

orca orchestration worker-read --dispatch <dispatch_id> --limit 50 --json

원격 Orca Server의 worker 사용하기

연결된 다른 Orca Server에서 worker를 실행하려면 처음 시작할 때만 --on <saved-environment>을 붙입니다. Run과 Task는 coordinator가 있는 현재 서버에 남고, 이후 상태 확인과 메시지는 Dispatch ID로 라우팅됩니다.

Windows Orca Server에서 Codex worker 시작

orca orchestration worker-start \
  --task <task_id> \
  --on windows \
  --worktree new-top-level \
  --repo name:<remote_repo_name> \
  --name windows-test \
  --agent codex \
  --setup run \
  --json

원격 서버에서는 current와 new-child가 어느 머신의 작업 공간인지 모호하므로 사용할 수 없습니다. 원격 저장소 selector를 직접 확인하고 new-top-level 또는 정확한 기존 worktree selector를 사용해야 합니다.

자주 생기는 문제

runtime이 실행 중이 아니라고 나올 때

orca status --json에서 runtime이 not_running 또는 reachable: false라면 먼저 orca open으로 앱을 실행합니다. headless 서버에서는 orca serve 설정이 필요합니다.

coordinator identity를 찾지 못할 때

run-create와 후속 명령을 Orca가 관리하는 coordinator 에이전트 터미널에서 실행했는지 확인합니다. 외부 셸에서 실행한다면 명시적인 --from <handle>이 필요할 수 있습니다.

Task가 실행 가능한 상태로 바뀌지 않을 때

orca orchestration task-list --json으로 상태와 의존성을 확인합니다. 선행 Task가 worker_done으로 완료되지 않았거나, 실패·blocked 상태일 수 있습니다.

check가 timeout으로 끝날 때

timeout은 확인 시점에 새 메시지가 없다는 뜻이지 worker 실패가 아닙니다. worker-show나 제한된 worker-read로 상태를 확인한 뒤 다시 rolling wait를 실행합니다.

worker 시작 결과가 불확실할 때

같은 명령을 바로 반복하면 중복 worker가 생길 수 있습니다. 반환된 JSON의 stage, effects, residualResources와 recovery 안내를 먼저 확인하고, 요청 ID가 있다면 현재 가이드의 request-show와 --retry-request 절차를 따릅니다.

예전 예제의 명령이 작동하지 않을 때

orchestration run, run-stop, coordinator-start, coordinator-stop은 현재 자동 스케줄러 명령이 아닙니다. 최신 방식에서는 lightweight Run을 만들고 worker-start로 worker를 명시적으로 배치합니다. orca skills get orchestration --full의 현재 계약을 기준으로 수정하세요.

안전하게 사용하는 체크리스트

수정 파일이 겹치는 worker는 같은 worktree에 동시에 배치하지 않습니다.
Task에는 작업 범위, 완료 조건, 금지 행동과 검증 방법을 함께 적습니다.
worker_done 보고만 믿지 말고 diff와 테스트 결과를 coordinator 또는 사용자가 검토합니다.
check의 Delivery는 모든 메시지를 처리한 뒤 acknowledge합니다.
timeout이나 heartbeat를 실패로 간주해 worker를 강제 종료하지 않습니다.
완료·실패가 확정된 supervised worker만 worker-release로 정리합니다.
worktree는 코드 변경을 나누지만 운영체제 권한을 격리하는 보안 샌드박스는 아니라는 점을 기억합니다.
운영 비밀, 실제 고객 데이터와 배포 권한은 필요한 worker에만 최소 범위로 제공합니다.

자주 묻는 질문

Orca orchestration이 알아서 Task를 나누나요?

Orca runtime은 Run, Task, Dispatch와 메시지 상태를 관리하지만 작업 내용을 스스로 분해하는 스케줄러는 아닙니다. coordinator 에이전트가 목표를 해석해 Task를 만들고 적절한 worker와 worktree를 선택합니다.

orchestration 스킬만 설치하면 바로 작동하나요?

스킬은 에이전트가 올바른 CLI 계약을 읽고 따르게 해주는 지침입니다. 실제 orchestration은 실행 중인 Orca runtime과 Experimental 설정이 필요합니다. 사용할 Codex·Claude Code 등의 CLI도 각각 설치하고 로그인해야 합니다.

coordinator와 worker는 같은 AI여도 되나요?

가능합니다. Codex가 coordinator이면서 별도의 Codex worker를 실행할 수도 있고, Claude Code가 coordinator로 Codex worker를 감독할 수도 있습니다. 역할, 작업 범위와 worktree가 분리되어 있는지가 더 중요합니다.

worker가 다시 worker를 만들 수 있나요?

기본 nested worker depth는 1이어서 coordinator가 만든 worker는 하위 worker를 다시 Dispatch할 수 없습니다. 더 깊은 구조가 꼭 필요하다면 Settings → Orchestration → Nested worker depth에서 제한을 조정할 수 있지만, 구조가 깊어질수록 상태 추적과 충돌 관리도 어려워집니다.

worker 완료 후 Task 상태를 직접 completed로 바꿔야 하나요?

정상적인 worker_done 보고가 현재 Task와 Dispatch에 연결되면 Orca가 완료 상태를 자동 반영합니다. 일반 흐름에서 다시 task-update --status completed를 실행할 필요는 없습니다. 수동 상태 변경은 복구나 명시적인 override에만 사용합니다.

일반 Orca 병렬 실행부터 익혀야 하나요?

권장합니다. worktree, 에이전트 터미널, diff와 브랜치 관계를 이해해야 coordinator가 잘못된 위치에 worker를 배치했을 때 발견할 수 있습니다. 처음에는 worker 하나를 감독하는 최소 흐름으로 시작한 뒤 독립 Task 두 개로 확장하세요.