Orca, 왼쪽에 파일 목록이 없어서 당황하셨나요? — 초보가 정리한 적응 노트

소개

저는 부동산 매물 브리핑과 건축물대장 분석을 하는 공인중개사입니다. 코드를 업으로 쓰는 사람은 아니지만, AI에게 일을 시켜 자료를 만드는 쪽으로는 어느정도 들어와 있습니다.

이번에 24기 「구독 비용이 부담스러운 AI 파워유저를 위한, Orca로 멀티에이전트 오케스트레이션 시스템 만들기」 수업을 신청했고, 오늘부터 스터디에 참여합니다. 사전 학습 삼아 Orca를 깔았는데 — 첫 화면에서 한참을 멍하게 있었습니다.

왼쪽에 파일 목록이 있어야 할 자리에 처음 보는 이름들이 늘어서 있었고, 공식 문서는 영어인 데다 "이미 아는 사람"을 전제로 쓰여 있었습니다. VS Code를 쓰던 감각이 전혀 통하지 않았습니다.

내가 막힌 지점을 그대로 정리하면, 나 같은 사람에게도 쓸모가 있지 않을까?

그래서 "처음 여는 사람이 30분 안에 '아, 이런 도구구나'를 잡을 수 있는 한 장"을 만들기로 했습니다. 측정 포인트는 하나였습니다 — 설명을 읽고 바로 따라 할 수 있는가. 그러려면 화면에 적힌 숫자와 단축키가 전부 실제와 맞아야 했습니다.

결과물은 9개 섹션짜리 단일 HTML 페이지이고, 지금 누구나 열어볼 수 있게 배포돼 있습니다 → https://shinhwa-orca-guide.vercel.app (왕초보가 만든 Orca Onboarding Guide)

진행 방법

Orca 안에서 Claude Code를 띄워 작업했습니다. 재미있는 건 Orca 가이드를 Orca로 만들었다는 점입니다. 중간부터는 Orca 자체 CLI로 결과물을 검증하기까지 했습니다.

Step 1. 설치물을 뜯어 사실만 모았다

처음엔 "AI가 아는 Orca"를 쓰게 두면 안 된다고 생각했습니다. 버전마다 다른 단축키를 틀리게 적으면 가이드의 존재 이유가 사라지니까요. 그래서 설치 폴더를 직접 뜯었습니다.

# Orca 설치 경로
cd /c/Users/pc/AppData/Local/Programs/orca/resources

# 온보딩 투어가 내세우는 기능 목록
for f in onboarding/feature-wall/*.recorded-at.json; do
  grep -o '"sourceGif": "[^"]*"' $f
done

# 번들에 들어 있는 스킬 목록
grep -o '"name": "[^"]*"' skills/current-manifest.json | sort -u

단축키는 app.asar(Electron 번들) 안에 테이블로 들어 있어서 정규식으로 긁었습니다.

import re
data = open('app.asar','rb').read()
pat = re.compile(
  rb'\{id:"([a-zA-Z][a-zA-Z.]*)",title:"([^"]{2,60})",group:"([^"]{2,30})",scope:"[^"]*",'
  rb'(?:conflictGroup:"[^"]*",)?'
  rb'searchKeywords:\[[^\]]*\],defaultBindings:(\w+\(\[[^\]]*\]\)|\{(?:[^{}]|\{[^{}]*\})*\})')
# → 88개 명령 추출

여기서 첫 시행착오를 겪었습니다. 9월에 뽑은 정규식을 10월에 그대로 돌렸더니 "단축키 60여 개가 바뀌었다"는 결과가 나왔습니다. 확인해 보니 번들이 재빌드되면서 minify된 헬퍼 함수명이 M([...]) → J([...])로 바뀐 것이었습니다. 실제 변경이 아니라 제 파싱이 깨진 것이었죠. 함수명을 와일드카드(\w+)로 바꾸고, 알려진 값(worktree.palette = Ctrl+Shift+J)으로 검산한 뒤에야 믿을 수 있는 결과가 나왔습니다.

Step 2. Claude Code로 페이지를 만들었다

Orca의 워크트리 터미널에서 Claude Code를 띄우고 작업했습니다. 제가 실제로 넣은 지시는 이런 형태였습니다.

이제 막 orca를 설치했어. orca ide에 대해 잘 적응하고
잘 사용할 수 있도록 설명하는 랜딩 페이지를 만들어 줘.
디자인 스타일은 가장 핫한 스타일로 적용해 줘.

의존성 없는 단일 HTML 한 파일로 만들었습니다. 라이트/다크 테마 토글, 체크 상태가 브라우저에 저장되는 체크리스트, 검색·필터가 되는 단축키 치트시트까지 넣었습니다.

Step 3. Vercel에 배포했다

npx --yes vercel@latest --token <토큰> --scope <팀> --yes --prod

두 번째 시행착오. 기존에 쓰던 매물 브리핑 프로젝트를 덮어쓰면 의뢰인에게 보낸 링크가 바뀝니다. 그래서 새 프로젝트로 올렸는데, 짧은 이름(orca-guide)은 이미 선점돼 있어 도메인을 못 받았습니다. 접두사를 붙여 해결했습니다.

세 번째 시행착오. 배포했는데 방문자에게 Vercel 로그인 화면이 떴습니다. 새 프로젝트는 Deployment Protection이 기본으로 켜집니다.

curl -X PATCH -H "Authorization: Bearer <토큰>" -H "Content-Type: application/json" \
  -d '{"ssoProtection":null}' \
  "https://api.vercel.com/v9/projects/<projectId>?teamId=<teamId>"

확인은 curl -s -L <url> | grep -o '<title>[^<]*' — Login – Vercel이 나오면 아직 막힌 겁니다.

Step 4. 공식 문서와 대조했다 — 여기서 오류 3건이 나왔다

며칠 뒤 "공식 문서도 충분히 검토하고 진행한 게 맞나?"라는 질문을 받고 아차 싶었습니다. 저는 설치물만 뜯었지 onorca.dev/docs를 읽지 않았습니다.

읽고 나니 라이브 페이지에 나가 있던 사실 오류가 3건 드러났습니다.

마지막 항목이 가장 뼈아팠습니다. 공식 온보딩의 이름이 아예 "Your first 3-agent session"입니다. Claude Code·Codex·Cursor CLI에 똑같은 프롬프트를 던지고, 탭을 화면 가장자리로 끌어 셋을 나란히 놓고, 세 diff를 비교해 이긴 것만 커밋하는 흐름입니다. 제 가이드는 이 핵심을 놓치고 있었습니다.

그리고 orca CLI와 오케스트레이션을 한 줄로 축소해 놨던 것도 바로잡았습니다. 실제로는 이만큼입니다.

orca worktree create / ps / rm        # 워크트리를 스크립트로 관리
orca terminal send / read / wait      # 에이전트 터미널에 프롬프트 밀어넣기
orca goto / snapshot / click / fill   # 내장 브라우저 조작
orca automations                      # 예약 반복 작업
orca artifacts share                  # 결과물을 공개 링크로

오케스트레이션은 한 단계 더 위입니다 — 코디네이터 에이전트가 워커 에이전트들을 지휘하고, 워커가 막히면 로컬에서 멋대로 결정하지 않고 코디네이터에게 블로킹 질문을 던집니다.

orca orchestration run-create --objective "deploy service"
orca orchestration worker-start --spec "build container" --agent codex
orca orchestration worker-start --spec "run tests"       --agent claude
orca orchestration check --wait --types "worker_done,question"
orca orchestration reply --id <msg_id> --body "approve deployment"

Step 5. 눈으로 확인하려다 세 번 막혔다 — 그래서 폴백 체인을 만들었다

만든 페이지가 실제로 어떻게 보이는지 확인하려는데, Claude in Chrome 확장이 세션마다 연결이 끊겼습니다. 저는 "확장이 안 붙어서 확인을 못 했습니다"라고 세 번이나 보고하고 멈췄습니다.

"뭘 할 때 안 되는 이유를 찾지 말고, 되는 이유를 찾아서 적극적으로 해결하자."

이 말을 듣고 수단을 전부 뒤졌더니 — Orca 자체에 답이 있었습니다. 제가 가이드에 써놓고도 정작 안 쓴 기능이었습니다.

ALT

다양한 종류의 한국어 목록

ORCA="/c/Users/pc/AppData/Local/Programs/orca/resources/bin/orca.exe"

# 1순위 — Orca 내장 브라우저
"$ORCA" tab create --url "https://shinhwa-orca-guide.vercel.app"
"$ORCA" tab switch --page <PAGE_ID>      # ★ 캡처 전 반드시 실행
"$ORCA" screenshot --page <PAGE_ID> --format png --json

# 최종 보루 — computer use (어떤 창이든 캡처)
"$ORCA" computer list-windows --app chrome
"$ORCA" computer get-app-state --app chrome --window-id <ID> --restore-window --json

가장 큰 발견은 orca tab switch였습니다. screenshot이 runtime_unavailable로 실패해도, 탭을 포그라운드로 꺼내면 바로 살아납니다. Aside에는 없는 복구 수단입니다.

그리고 computer use는 브라우저 자동화가 아니라 화면 자체를 보는 것이라 원리적으로 막히지 않습니다. 이걸로 제 Chrome 창을 캡처해 보니 사용자가 캐시된 구버전을 보고 있다는 것까지 발견했습니다.

네 경로를 순서대로 시도하는 스크립트로 묶어 두었습니다.

bash ~/.claude/scripts/webshot.sh <url> [출력경로] [--app chrome]
# → OK via orca-browser -> C:\...\shot.png (260457 bytes)

Step 6. 모바일은 iframe으로 검증했다

Aside·Orca 어느 쪽 CLI에도 뷰포트 변경 기능이 없었습니다. 그래서 페이지 안에 같은 출처 iframe을 360px·390px로 띄워 실제 미디어쿼리를 작동시키고, 그 안을 측정했습니다.

const f = document.createElement('iframe');
f.style.cssText = 'width:390px;height:860px';
f.src = location.origin + location.pathname;
document.body.appendChild(f);
// → f.contentDocument 를 측정: documentElement.scrollWidth - 390 으로 가로 넘침 판정

측정으로 360px에서 가로 스크롤 15px을 잡았습니다. 원인은 CSS 1fr의 하한이 min-content라는 점이었습니다 — 카드 안의 줄바꿈 안 되는 긴 경로(C:\Users\pc\orca\projects\orca_study)가 카드를 화면 밖으로 밀어낸 것이었죠. minmax(0, 1fr)로 해결했습니다.

그런데 측정만으로는 못 잡는 버그가 있었습니다. iframe을 화면에 보이게 띄워 스크린샷을 찍어 보니, 모바일 상단에서 브랜드명이 "적응 / 가이 / 드" 세 줄로 쪼개지고 로고 원이 타원으로 찌그러져 있었습니다. flex 압축에 의한 줄바꿈은 overflow가 아니라 "정상 레이아웃"이라 수치로는 드러나지 않습니다. 눈으로 봐야 하는 이유가 이것이었습니다.

결과와 배운 점

산출물

배운 점 네 가지

① 설치물 역추출은 "버전 정확도", 공식 문서는 "개념·범위"에 강하다 — 둘 다 필요하다. 번들만 뜯으면 앱에 구현된 것은 정확하지만 제품이 스스로를 어떻게 규정하는지가 통째로 빠집니다. 저는 그래서 Orca를 IDE라 불렀습니다. 반대로 공식 문서만 읽으면 내 설치본의 실제 단축키는 알 수 없습니다. 순서는 공식 문서 먼저, 번들로 보강이 맞습니다.

② 문서를 쓰는 것과 써보는 것은 다르다. 저는 orca CLI의 브라우저 기능을 가이드에 적어놓고도, 정작 화면 확인이 막혔을 때 그걸 쓸 생각을 못 했습니다. 남이 짚어준 뒤에야 썼습니다. 써본 것만 진짜 아는 것입니다.

③ "안 되는 이유"를 보고하는 건 일을 멈추는 것이다. 같은 보고를 세 번 했는데, 그동안 더 나은 수단이 내내 있었습니다. 지금은 폴백 체인을 스크립트로 박아 두어 막히면 자동으로 다음 수단으로 넘어갑니다.

④ 수치 검증과 시각 검증은 잡는 버그가 다르다. 가로 스크롤·텍스트 잘림·터치 타깃은 측정으로 잡힙니다. 하지만 flex 압축으로 글자가 쪼개지는 건 "정상 레이아웃"이라 수치에 안 걸립니다. 둘 다 돌려야 합니다.

시행착오 — 솔직한 메모

• 번들 파싱 정규식이 빌드마다 깨진다 → minify된 헬퍼 함수명(M → J → i)을 \w+로 와일드카드 처리. 추출 후 알려진 값으로 반드시 검산.

• Vercel 새 프로젝트는 로그인 벽이 기본 ON → 배포 직후 ssoProtection: null PATCH. <title>이 Login – Vercel이면 아직 막힌 상태.

• 임시 폴더에서 배포하면 폴더명으로 새 프로젝트가 생긴다 → vercel link --project <이름> --yes를 먼저 실행. 저는 엉뚱한 프로젝트를 하나 만들었다가 지웠습니다.

• 한글 + monospace 폰트 = 글자 깨짐 → 이 글의 다이어그램도 처음엔 한글이 깨졌습니다. 박스 본문은 sans-serif, 명령어만 monospace로 분리.

• 🍳 같은 이모지는 Windows에서 엉뚱하게 렌더링된다 → 가이드의 비유 라벨은 텍스트(비유 ·)로 바꿨습니다.

• 스크린샷이 실패하면 포그라운드 문제일 때가 많다 → orca tab switch / --restore-window를 먼저.

도움이 필요한 부분

가이드는 "3-에이전트 경주"를 권하는데, 정작 저는 아직 안 해봤습니다. orca/workspaces 폴더가 비어 있습니다. 오케스트레이션도 문서 기반 설명만 적었지 코디네이터/워커를 띄워본 적이 없습니다.

• 같은 과제를 Claude Code·Codex·Cursor CLI에 던졌을 때, 실제로 결과 차이가 유의미한가요? 어떤 종류의 과제에서 가장 크게 갈리는지 궁금합니다.

• 오케스트레이션의 디시전 게이트를 실무에서 어떤 단위로 거시나요? 과제당? 단계당?

• 구독 비용 관점에서, 여러 에이전트를 병렬로 돌릴 때 레이트리밋 관리를 어떻게들 하시는지 듣고 싶습니다.

앞으로의 계획

1. 수업에서 배운 걸로 가이드를 채운다. 지금 빠져 있는 세션 복원·하이버네이션·사용량 추적·에이전트 훅·Recipes·Design Mode를 실제로 써보고 추가하겠습니다.

2. 제 업무에 대입한다. 매물 브리핑 자료를 워크트리 3개에서 동시에 뽑아 비교하고, orca automations로 주간 시세 리포트를 예약 실행해 볼 생각입니다.

3. 가이드는 계속 살려 둡니다. 푸터에 변경 이력을 두었고, Orca가 업데이트될 때마다 번들을 다시 파싱해 단축키·기능을 갱신합니다. 실제로 9/19 빌드 → 10/1 빌드 사이에 퀵 커맨드가 신설되고 명령이 84→88개로 늘어난 걸 반영했습니다.

제가 얻은 가장 큰 배움은 이것입니다 — 도구를 이해하는 가장 빠른 길은, 그 도구로 그 도구의 설명서를 만들어 보는 것이었습니다.

같은 지점에서 막히신 분께 도움이 되면 좋겠습니다. 틀린 내용이나 보탤 점 있으면 편하게 알려주세요.

→ https://shinhwa-orca-guide.vercel.app

ALT

범고래

도움 받은 글

• Orca 공식 문서(https://onorca.dev/docs) — Start Here / The Orca Model / Working with Agents / CLI & Automation 등. 특히 "Your first 3-agent session"이 제 가이드의 뼈대를 바꿨습니다.

• stablyai/orca GitHub(https://github.com/stablyai/orca) — 설치 파일과 skill-guides/orchestration.md. 오케스트레이션 예시 명령은 여기서 인용했습니다.

• 24기 수업 페이지(https://www.gpters.org/ai-study-list/post/gudog-biyongi-budamseureoun-ai-paweoyujeoreul-wihan-orcaro-meoltieijeonteu-YSkfjHPyC0Z3yUc) — 김진형 님. 이 수업을 신청한 게 이 작업의 출발점이었습니다.😀