Orca 활용편 — 처음부터 끝까지 따라 하기
완전 가이드가 “이 기능은 무엇인가”를 설명하는 사전이라면, 활용편은 “이 일을 하려면 무엇을 어떤 순서로 누르나”를 보여 주는 따라 하기 문서입니다. 시나리오마다 준비물 → 단계 → 막혔을 때 순서이고, 더 알고 싶은 단계는 가이드의 해당 소절로 바로 이동합니다.
- 1. 설치부터 첫 결과까지 — Orca를 처음 켜는 사람
- 2. 같은 일을 에이전트 셋에게 시켜 더 나은 답 고르기 — 결과 비교를 연습한 뒤 선택
- 3. 코드를 몰라도 결과 검토하기 — 개발자가 아닌 사람, 검토가 부담스러운 사람
- 4. 퇴근 후 폰으로 이어서 지시하기 — 자리를 비워도 일을 이어가고 싶을 때
- 5. 매일 아침 정리 작업을 자동으로 맡기기 — 반복 업무를 맡기고 싶을 때
- 6. 코드 없이 안내문 하나 완성하기 — 문서를 만들고 고치는 기본 실습
- 7. 어제 하던 일을 찾아 이어 하기 — 워크트리와 이전 대화 찾기
- 8. 결과가 틀리거나 작업이 막혔을 때 다시 진행하기 — 문제 설명·재요청·재확인 연습
- 9. 원격 서버에서 작업하기 — 노트북 대신 더 힘센 SSH 서버에 맡기고 싶을 때
- 10. 이슈에서 바로 작업 시작하기 — 팀이 Jira·Linear로 할 일을 관리할 때
시작 전 준비 → 1 첫 결과 → 6 문서 완성 → 3 결과 검토 → 7 이어 하기 → 8 막힘 해결 순으로 진행하세요. 번호는 각 실습을 찾기 위한 이름이며, 반드시 번호순으로 읽을 필요는 없습니다.
기본 실습을 마치면 2 여러 결과 비교·4 모바일·5 자동화 중 필요한 것을 고릅니다. 팀 환경에 따라 9 원격 서버·10 이슈 연동을 더합니다.
시작 전 준비 — 두 가지를 먼저 확인하세요
이 활용편은 Orca 안에서 일을 맡기고 결과를 확인하는 연습입니다. 에이전트와 저장소 준비가 처음이라면 아래 요청 문장을 설치를 도와줄 동료에게 보여 주세요. 준비가 끝나면 코드를 읽지 않아도 문서 실습부터 결과를 확인할 수 있습니다.
- 사용할 에이전트 하나 정하기Claude Code·Codex 등 설치와 로그인을 마친 에이전트가 필요합니다. 구독·인증은 에이전트 쪽에서 준비합니다. 지원 목록에서 사용할 에이전트를 확인하고, 일반 터미널에서 실행해 간단한 질문에 답하는지 확인하세요. 모르면 아래 도움 요청을 사용합니다.
- 연습할 git 저장소 폴더 확보하기저장소는 파일의 변경 이력을 관리하는 프로젝트 폴더입니다. 평소 쓰는 아무 폴더를 고르는 대신, 연습해도 되는 저장소의 내 컴퓨터 경로를 확인하세요. 준비 방법은 시나리오 1 준비물을 함께 봅니다.
“Orca로 문서 수정 연습을 하려 합니다. 사용할 에이전트 하나를 설치하고 로그인한 뒤 간단한 질문에 답하는지 확인해 주세요. 연습용 git 저장소도 내 컴퓨터에 준비하고 폴더 위치를 알려 주세요. PR(변경 검토 요청서) 제출까지 연습한다면 저장소 연동과 업로드 권한도 확인해 주세요.”
한 단계씩 읽는 방법
각 단계에서 무엇을 누르거나 입력하는지 읽고, 직접 해 본 뒤 안내된 결과가 보이는지 확인하세요. 결과가 다르면 다음으로 넘어가기 전에 ‘막히면’을 봅니다. 그림은 클릭 위치를 설명하는 예시이며 실제 앱의 버튼이 아닙니다.
- 로그인된 에이전트와 연습 저장소를 먼저 준비합니다.
- 기본 실습은 1 → 6 → 3 → 7 → 8, 선택 실습은 2·4·5입니다.
- 각 단계는 읽기 → 앱에서 실행 → 결과 확인 순서로 진행합니다.
출처: onorca.dev/docs — install, first-session, agents/supported. 학습 순서와 도움 요청 문장은 이 활용편의 실습 안내입니다.
설치부터 첫 결과까지
Orca를 처음 깔고, AI 에이전트에게 일 하나를 시켜 결과를 눈으로 확인한 뒤 깔끔하게 남길지 정하기까지 따라 하는 순서입니다. 에이전트와 저장소를 준비한 뒤 시작합니다.
- Orca를 설치하고 내 프로젝트 폴더(저장소)를 등록합니다.
- 워크트리(작업 하나만을 위한 별도 작업 폴더 — 다른 작업과 파일을 나눠 쓰는 연습장)를 만들고 에이전트에게 일을 시킵니다.
- 결과를 문서·채팅·내장 브라우저로 확인하고, 남겨 둘지 정리할지 결정합니다.
예상 소요 시간: 준비물을 갖춘 뒤 Orca 설치 포함 20~30분(에이전트 작업 시간은 일의 크기에 따라 다름)
준비물 — 시작 전에 갖출 두 가지
- AI 코딩 에이전트 1개 설치·로그인(구독). Orca는 AI 모델을 주지 않고, 내가 쓰는 에이전트(Claude Code, Codex, Cursor CLI 등)를 대신 실행해 주는 ADE(에이전트용 개발 환경)입니다. 에이전트 구독은 직접 준비하고, 아무 터미널에서 한 번 로그인해 두면 Orca가 그 로그인 정보를 넘겨받아 씁니다. → 지원 에이전트 목록
- git 저장소 폴더 1개. Orca의 워크트리는 모두 진짜 git 워크트리라서, 등록할 폴더는 git(파일의 변경 이력을 기록하는 도구)으로 관리되는 폴더(저장소)여야 합니다. 없다면 팀의 개발자에게 쓸 저장소를 받아 내 컴퓨터에 복사해 두는 방법(clone)을 물어보세요. → 첫 3-에이전트 세션(준비물 포함)
에이전트에게 로그인할 수 있고, 등록할 저장소 폴더가 내 컴퓨터 어디에 있는지 알아야 합니다. 아직 준비하지 못했다면 다음 문장을 개발자 동료에게 보여 주세요.
“Orca에서 문서 수정 연습을 하려고 합니다. 사용할 에이전트의 설치·로그인을 도와주시고, 연습해도 되는 git 저장소를 제 컴퓨터에 준비해 주세요. 등록할 폴더 위치도 알려 주세요.”
에이전트별 준비는 지원 에이전트 안내를 참고합니다. 문서 한 곳을 고치는 실습을 먼저 하고 싶다면 시나리오 6을 선택하세요.
따라 하기
1단계 · Orca 설치하고 처음 열기
- 설치 파일 받기공식 설치 안내에서 내 컴퓨터에 맞는 것을 받습니다 — macOS(Apple Silicon·Intel), Windows(설치 프로그램), Linux(AppImage·.deb·.rpm). macOS에서 Homebrew를 쓴다면
brew install --cask stablyai/orca/orca한 줄로도 됩니다. - 처음 실행macOS는 “정말 열까요?”를 한 번 물을 수 있습니다 — 정상이니 확인을 누릅니다.
- 권한·가져오기 질문에 답하기저장소를 추가할 수 있게 홈 폴더(내 계정의 개인 파일이 있는 기본 폴더) 접근을 허락합니다. 기존 에이전트·터미널 설정(
~/.claude·~/.codex·Ghostty)이 있으면 가져올지도 묻습니다. 이미 쓰던 설정을 이어 쓰고 싶을 때 가져옵니다. - 빈 시작 화면 도착여기서 첫 저장소를 추가합니다.
2단계 · 저장소 추가 — Add Repo
- 사이드바의 Add Repo(저장소 추가) 누르기내 컴퓨터의 프로젝트 폴더를 고릅니다.
- 기준 브랜치 확인Orca가 그 폴더의 기본 브랜치를 기준 브랜치(base ref — 보통 서버에 있는 원본 줄기
origin/main)로 잡습니다. 처음에는 그대로 두면 됩니다.
3단계 · 워크트리 만들기 — 저장소 이름 옆 +
- 저장소 이름 옆 + 누르기새 워크트리 창이 열립니다. 화면에 Workspace(워크스페이스 — 워크트리와 같은 것)라고 나와도 같은 뜻입니다.
- 작업 이름 적기예:
readme-install. 비워 두면 Orca가 해양 생물 이름을 붙여 줍니다. - 출발점은 그대로출발점(start-from ref — 새 워크트리가 갈라져 나오는 지점)은 보통 기준 브랜치 그대로 둡니다.
- 에이전트 고르기 → 만들기기본 에이전트가 미리 골라져 있습니다(바꾸려면 Settings → Agents). 만들기를 누르면 창이 바로 닫히고, 사이드바에 진행 표시가 뜬 뒤 준비가 끝나면 에이전트가 첫 탭으로 열립니다.
4단계 · 에이전트에게 일 시키기
열린 에이전트 탭에 부탁(프롬프트)을 적고 Enter를 누릅니다. 좋은 프롬프트는 무엇을 · 어디까지 · 끝나면 어떻게 알려 줄지 세 가지를 담습니다.
“README에 ‘설치 방법’ 절을 추가해 줘. 다른 파일은 건드리지 마. 끝나면 무엇을 바꿨는지 쉬운 말로 3줄로 알려 줘.”
“첫 화면 제목 글자를 지금보다 크게 해 줘. 끝나면 앱을 실행하고, 브라우저에서 열 주소를 알려 줘.”
“코드는 바꾸지 말고, 이 프로젝트가 무엇을 하는 프로그램인지 사무직 동료에게 설명하듯 알려 줘.”
5단계 · 결과 확인 — 채팅과 내장 브라우저
- 채팅에서 답 읽기초록으로 바뀌면 탭에 들어가 에이전트의 마지막 답(무엇을 바꿨는지)을 읽습니다. 터미널 대신 대화창 모양으로 보고 싶다면 Settings → Chat UI(또는 Settings → Agents)에서 그 에이전트를 Chat으로 바꿉니다(지원 에이전트만, 새 대화부터 적용).
- 화면 수정 부탁을 골랐다면 내장 브라우저로 보기워크트리마다 자기 브라우저가 있습니다. 에이전트가 알려 준 주소 링크를 누르면 그 옆 창에 열리고, 직접 열려면 Cmd+T(macOS)로 이 워크트리 전용 새 탭을 엽니다.
- 마음에 안 들면 다시 부탁같은 탭에 “제목이 너무 커, 조금만 줄여 줘”처럼 이어서 적습니다. 줄 단위로 꼼꼼히 보고 싶다면 시나리오 3으로.
| 고른 부탁 | 여기까지 확인하면 이 단계 완료 |
|---|---|
| ① 문서 고치기 | 에이전트에게 “수정한 README를 열어 볼 위치와 추가한 내용을 알려 줘”라고 요청합니다. 해당 파일을 열어 설치 방법 절이 있는지 확인합니다. 문서 실습에서 더 자세히 따라 할 수 있습니다. |
| ② 화면 고치기 | 알려 준 주소로 화면이 열리고 제목이 원하는 크기로 보이는지 확인합니다. 주소가 없거나 열리지 않으면 에이전트에게 실행 여부와 오류를 확인해 달라고 합니다. |
| ③ 먼저 묻기 | 프로젝트가 하는 일을 내 말로 한 문장 설명할 수 있으면 완료입니다. 파일 변경이나 브라우저 주소가 없어도 됩니다. |
위 브라우저 절차와 아래 그림은 예시 ②에 해당합니다. 작업이 끝났다는 표시와 결과가 맞다는 판단은 구분해서 확인하세요.
6단계 · 정리 — 남길지, 지울지
문서 완성·결과 검토·이어 하기 실습에 같은 워크트리를 사용합니다. 지금은 그대로 남겨 두고 시나리오 6으로 이동하세요. 아래 삭제 방법은 모든 연습을 끝내고 더 이상 필요 없는 작업에만 사용합니다.
- 남길 결과라면 먼저 보관 방법 정하기워크트리를 지우면 그 폴더와 브랜치가 함께 사라집니다. 결과를 이력에 남기려면 먼저 커밋합니다. 서버에 보낼 필요가 있을 때는 push·PR까지 진행합니다(시나리오 3). 커밋만 해도 이력은 생기지만 워크트리를 삭제해도 보존된다는 뜻은 아닙니다. 보존 방법이 확실하지 않으면 삭제하지 말고 그대로 둡니다.
- 필요 없어진 작업만: 사이드바에서 워크트리 오른쪽 클릭 → 삭제확인 창이 뜨고, 확인하면 워크트리와 브랜치가 함께 지워집니다. 키보드로는 워크트리 위에 마우스를 올리고 Cmd+Shift+Backspace / Ctrl+Shift+Backspace.
- 잠시 멈춰 두기만 하려면같은 메뉴의 보관(archive)·재우기(sleep)를 씁니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 에이전트가 시작되지 않음 | Orca 밖 일반 터미널에서 그 에이전트를 실행해 봅니다. 거기서도 안 되면 에이전트 설치·로그인 문제입니다. Orca에서만 안 되면 Settings → Agents에서 Orca가 그 프로그램을 찾는지(PATH) 확인하고, 탭의 Restart(다시 시작) 칩을 눌러 봅니다. |
| 워크트리 만들기가 실패함 | 출발점이 아직 내려받아지지 않았을 수 있습니다 — 저장소에서 터미널을 열고 git fetch origin. 같은 브랜치의 워크트리가 이미 있으면 그것을 지우거나 다른 이름을 씁니다. 실패 패널의 Retry로 다시 시도할 수 있습니다. |
| macOS가 처음 열 때 확인을 요구함 | 정상입니다(서명·공증된 앱이어도 처음엔 물을 수 있음). 확인 후 엽니다. |
| 컴퓨터가 느려짐 | 안 쓰는 워크트리를 닫고, 필요 없는 브라우저 탭을 닫습니다(브라우저 탭이 많은 분할 화면이 메모리를 가장 많이 씁니다). |
더 많은 문제: 문제 해결
- 준비물은 둘: 로그인해 둔 에이전트 1개, git 저장소 폴더 1개.
- 설치 → Add Repo → 저장소 옆 +로 워크트리 → 프롬프트(무엇을·어디까지·어떻게 알려 줄지).
- 초록이 되면 답을 읽고, 고른 부탁에 맞게 문서·화면·설명 내용을 직접 확인합니다.
- 남길 결과는 먼저 저장하고 보관 방법을 확인합니다(시나리오 3). 확실하지 않으면 그대로 두고, 필요 없는 연습 작업만 오른쪽 클릭 → 삭제합니다.
출처: onorca.dev/docs — install, first-session, agents/supported, agents/native-chat, model/worktrees, model/agents-sessions, browser/overview, troubleshooting · Orca 완전 가이드 1·2·3·4장
같은 일을 에이전트 셋에게 시켜 더 나은 답 고르기
한 번 시켜서 마음에 안 들면 다시 시키는 대신, 처음부터 셋에게 동시에 시키고 결과를 비교해 가장 나은 것을 고릅니다. 서버로 보낼 준비가 됐다면 고른 결과만 PR로 제출합니다. 공식 문서가 Orca의 “필살기”라고 부르는 방법입니다.
- 같은 출발점에서 워크트리 3개를 만들고, 같은 프롬프트로 에이전트 셋을 동시에 돌립니다.
- 화면을 나눠 셋을 한꺼번에 지켜봅니다.
- 결과 화면·검사·설명으로 더 나은 결과를 고릅니다. 필요하면 PR로 제출하고 나머지를 정리합니다.
예상 소요 시간: 준비 10분 + 에이전트 작업 시간 + 비교·정리 15~20분
준비물을 확인하고 같은 출발점으로 세 작업 만들기부터 진행합니다. 비교할 때는 같은 동작을 직접 해 보고, 제출·삭제는 보관 방법을 정한 뒤 선택합니다.
준비물
- 시나리오 1을 한 번 끝내 본 경험(저장소가 이미 Orca에 등록돼 있음).
- 에이전트 셋 — 서로 다른 에이전트(예: Claude Code, Codex, Cursor CLI)를 쓰려면 각각 설치·로그인이 필요합니다. 하나뿐이라면 같은 에이전트를 세 번 띄워도 셋이 따로 일합니다.
- 셋에게 똑같이 줄 프롬프트 하나(메모장에 미리 써 두면 붙여 넣기 편합니다).
- PR로 제출하려면 서버 저장소에 변경을 올릴 권한과 서비스 연결이 필요합니다. 저장소에 맞는 서비스를 Settings → Integrations(설정 → 연동)에서 연결합니다. 준비되지 않았다면 이번에는 비교와 로컬 커밋까지만 마쳐도 됩니다.
따라 하기
1단계 · 같은 출발점에서 워크트리 3개 만들기
아래 에이전트 이름은 예시입니다. 하나만 설치했다면 세 번 모두 그 에이전트를 선택합니다. 같은 저장소에서 만들고 출발점 이름도 셋이 같은지 확인하세요.
- 저장소 옆 + → 이름
fix-bug→ 에이전트 Claude Code출발점(start-from ref — 새 워크트리가 갈라져 나오는 지점)은 기본값 그대로. - 한 번 더:
fix-bug-2→ Codex출발점은 반드시 같게 둡니다. 출발점이 다르면 공정한 비교가 아닙니다. - 한 번 더:
fix-bug-3→ Cursor CLI만들기를 누르면 창이 바로 닫히고 준비는 뒤에서 진행되니, 기다리지 말고 연달아 만들어도 됩니다.
2단계 · 같은 프롬프트를 세 곳에 붙여 넣기
세 탭에 글자 하나 다르지 않게 같은 프롬프트를 넣습니다. 비교하기 쉽도록 마지막에 보고 방식을 정해 두는 것이 요령입니다.
“로그인 버튼을 두 번 누르면 오류가 나는 문제를 고쳐 줘. 꼭 필요한 파일만 바꿔. 끝나면 ① 원인 ② 바꾼 파일 목록 ③ 테스트를 돌려 통과했는지를 쉬운 말로 알려 줘.”
3단계 · 화면을 셋으로 나눠 지켜보기
- 탭을 창 가장자리로 끌어 놓기오른쪽 가장자리에 놓으면 좌우로, 아래쪽 가장자리에 놓으면 위아래로 나뉩니다. 나눈 칸 안을 또 나눌 수 있습니다.
- 상태 표시만 훑어보기회전 원=작업 중, 주황 ?=나를 기다림(먼저 가서 답해 주기), 초록=끝남, 빨강=막힘·실패.
- 워크트리가 많아지면Cmd+J(macOS)로 이동 팔레트(Jump Palette)를 열고 이름 일부를 쳐서 Enter로 이동, Shift+Enter로 분할 화면에 엽니다.
4단계 · 코드를 몰라도 되는 4가지 비교 기준
셋 다 초록이 되면 아래 기준으로 표를 채워 봅니다. 답이 같거나 다른지는 질문할 곳을 찾는 참고 자료입니다. 같은 답이어도 직접 결과를 확인해야 합니다.
| 기준 | 어디서 보나 | 좋은 신호 |
|---|---|---|
| ① 결과 화면 | 워크트리마다 따로 있는 내장 브라우저(탭이 워크트리별로 분리됨) | 부탁한 대로 보이고, 다른 곳이 깨지지 않음 |
| ② 검사 통과 | 에이전트 답의 “테스트 결과” 부분. PR을 낸 뒤라면 GitHub 검사가 실패할 때 워크트리에 빨간 칩이 뜸 | 어떤 검사를 실행했고 통과했는지 알 수 있음. 미실행·실행 불가는 “통과”와 구분 |
| ③ 바뀐 파일 수 | 사이드바의 Source Control(소스 관리) 패널과 diff(변경 내용) 화면의 파일 목록. 위쪽 +/− 칩은 파일 수가 아니라 추가·삭제한 줄 수 | 꼭 필요한 만큼만 바뀜 — 작을수록 검토가 쉬움. 개수가 적다는 이유만으로 정답은 아님 |
| ④ 설명 요청 | 각 탭에 “무엇을 왜 바꿨는지 쉬운 말로 설명해 줘” | 설명이 명확하고 부탁 범위를 벗어나지 않음 |
- 각 에이전트에게 “이 워크트리의 앱을 실행하고 확인할 주소와 절차를 알려 줘”라고 요청합니다. 문서 작업이라면 각 결과 파일을 엽니다.
- 세 결과에 같은 동작을 반복합니다. 위 로그인 예시라면 같은 조건에서 버튼을 두 번 눌러 오류가 다시 나는지 확인합니다.
- 요청한 문제와 가까운 다른 동작도 확인합니다. 판단이 안 되면 “직접 확인할 항목과 기대 결과를 알려 줘”라고 요청하거나 동료에게 검토를 부탁합니다.
5단계 · 고른 결과를 다듬고 저장하기 — 필요하면 PR
사이드바에서 고른 워크트리를 선택한 뒤 Source Control(소스 관리) 패널을 찾습니다. 현재 브랜치 이름이 고른 작업 이름과 같은지 확인합니다. 패널을 찾기 어렵다면 시나리오 3의 진입 안내부터 보세요. 서버 연결이 준비되지 않았다면 Commit까지 마치고 워크트리를 남겨 둡니다. 아래 Push·PR은 준비된 경우에 이어서 합니다.
- 승자 diff에 코멘트(Annotate AI Diff)아쉬운 줄에 코멘트를 달고 Send to agent로 한 번에 보내 다듬게 합니다(방법은 시나리오 3).
- 커밋 → PushSource Control 패널 아래쪽의 주 버튼이 상황에 맞게 바뀝니다: Stage Files → Commit → Push. 커밋(지금 변경을 이력에 한 번 저장하기) 메시지는 Generate with AI로 초안을 받아도 됩니다. 메시지를 읽어 보고 저장합니다. Push는 저장한 이력을 서버로 올리는 동작입니다.
- PR 만들기Push 뒤 같은 패널의 리뷰 만들기 동작(Create PR)으로 PR(내 변경을 원본에 합쳐 달라는 요청서)을 엽니다. 기준 브랜치·제목·설명·초안(Draft) 여부를 확인하고 제출합니다.
6단계 · 나머지 둘 정리하기
- 둘을 함께 고르기사이드바에서 Cmd(Windows·Linux는 Ctrl)을 누른 채 두 워크트리를 클릭합니다.
- 오른쪽 클릭 → 삭제골라 둔 모두에 적용됩니다. 확인하면 워크트리와 브랜치가 함께 지워집니다.
- “Review N Branches” 알림이 뜨면합쳐지지 않은 커밋이 있을 수 있어 git이 브랜치를 남겨 둔 것입니다. 알림을 열어 확인한 뒤 정리합니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 셋 중 하나만 시작되지 않음 | 그 에이전트를 Orca 밖 일반 터미널에서 실행해 로그인 상태를 확인하고, 탭의 Restart(다시 시작) 칩을 누릅니다. |
| 한 칸이 주황 ?에서 멈춤 | 허락이나 질문을 기다리는 중입니다. 그 칸에 들어가 답해 주면 다시 일합니다. |
| Push가 안 되거나 “뒤처짐” 경고 | Orca는 몰래 강제로 덮어쓰지(force-push) 않습니다. 패널의 Pull/Sync로 먼저 최신 내용을 받습니다. |
| 컴퓨터가 느려짐 | 에이전트 셋과 브라우저 탭 여러 개는 메모리를 많이 씁니다. 비교가 끝난 브라우저 탭과 워크트리는 바로 닫습니다. |
- 같은 출발점에서 워크트리 3개 → 에이전트 셋 → 같은 프롬프트.
- 탭을 창 가장자리로 끌어 화면을 나누고, 상태 표시로 진행을 봅니다.
- 결과 화면 · 검사 결과 · 바뀐 파일 수 · 설명을 함께 봅니다. 답이 같아도 같은 동작을 직접 확인합니다.
- 고른 결과를 커밋으로 저장하고, 필요하면 push·PR로 보냅니다. 나머지는 보관할 내용이 없는지 확인한 뒤 Cmd / Ctrl+클릭으로 함께 골라 삭제합니다.
출처: onorca.dev/docs — recipes/parallel-agents, first-session, model/tabs-panes-splits, model/agents-sessions, recipes/jump-worktrees, model/worktrees, review/commit-push, review/github, troubleshooting · Orca 완전 가이드 1·2·6장
코드를 몰라도 결과 검토하기
에이전트가 바꾼 내용을 “읽을 줄 몰라서” 그냥 내보내지 않도록, 모르는 줄은 에이전트에게 설명을 시키고 화면에서 직접 짚어 고치게 하는 순서입니다.
- 바뀐 파일 목록과 diff(바뀌기 전과 후를 나란히 비교한 화면)의 색을 읽습니다.
- 모르는 줄에 질문 코멘트를 달고, 여러 코멘트를 한 번에 에이전트에게 보냅니다.
- 디자인 모드로 화면 속 요소를 클릭해 “여기를 고쳐 줘”라고 지적합니다.
- 만족하면 커밋·PR을 내거나 개발자 동료에게 넘깁니다.
예상 소요 시간: 15~20분(코멘트 수와 에이전트 수정 시간에 따라 다름)
준비물을 확인한 뒤 파일 목록 → 질문 → 답 확인 순서로 진행합니다. 웹 화면이 없다면 디자인 모드는 건너뜁니다. 모르는 변경은 질문을 남기고 동료와 함께 판단해도 됩니다.
준비물
- 에이전트가 일을 마친(초록 표시) 워크트리 1개 — 시나리오 1이나 시나리오 2의 결과.
- 화면이 있는 프로젝트라면 에이전트가 알려 준 실행 주소(디자인 모드 단계에서 씀). 문서만 고쳤다면 5단계는 건너뜁니다.
- PR로 제출할 때만 서버 저장소에 올릴 권한과 서비스 연결이 필요합니다. Settings → Integrations(설정 → 연동)에서 저장소에 맞는 서비스를 연결합니다. 이번에는 로컬 커밋까지만 진행해도 됩니다.
따라 하기
1단계 · 바뀐 파일 목록 보기
- 워크트리의 diff 화면 열기워크트리마다 출발점 대비 diff가 내장돼 있습니다. 모든 바뀐 파일을 한 화면에 이어 보여 주고(combined diff), 옆에 접고 펼 수 있는 파일 목록이 붙습니다.
- 파일 이름부터 훑기부탁과 상관없어 보이는 파일이 바뀌었다면 그것부터 질문 대상입니다. j / k로 다음·이전 파일로 넘어갑니다.
- 웹 화면(HTML) 파일이라면파일 옆 눈 모양(Open Preview to the Side)을 누르면 바뀐 화면을 옆 브라우저 칸에서 바로 볼 수 있습니다.
2단계 · diff 색 읽기
원고 교정과 같습니다. 초록 줄은 새로 쓴 부분, 빨간 줄은 지운 부분, 색 없는 줄은 위치를 알려 주는 주변 내용입니다. 한 번에 바뀐 줄 묶음(hunk)마다 세 가지를 묻습니다: 꼭 필요한 변경인가? 최소한인가? 파일의 나머지와 어울리나? 답을 판단하기 어렵다면 다음 단계에서 “이 변경이 제 부탁과 어떤 관계인지, 빼면 어떤 문제가 생기는지 설명해 줘”라고 묻습니다. 설명이 이해되지 않으면 해결로 표시하지 말고 동료에게 검토를 부탁합니다.
3단계 · 모르는 줄에 “쉬운 말로 설명해 줘” 코멘트
- 줄 위에 마우스 올리기 → 왼쪽 여백의 + 누르기또는 그 줄에 커서를 두고 c. 여러 줄은 끌어서 고르거나 Shift를 누른 채 범위를 늘립니다.
- 질문이나 요청을 문장으로 적기예: “이 줄이 무슨 일을 하는지 쉬운 말로 설명해 줘.” / “이 파일은 왜 바꿨어? 꼭 필요 없으면 되돌려 줘.” 완전한 문장일수록 잘 통합니다.
- 저장Enter 또는 Cmd/Ctrl+Enter로 저장, Shift+Enter는 줄바꿈, Esc는 취소. 코멘트는 그 줄에 붙어 있어서, 내용이 밀려도 줄을 따라갑니다.
4단계 · 코멘트를 묶어서 보내기 (Annotate AI Diff)
- diff 위쪽의 Send to agent 누르기끝까지 다 본 뒤에 누릅니다. Orca가 모든 코멘트를 줄 위치와 함께 프롬프트 하나로 묶습니다.
- Send notes to 메뉴에서 받을 에이전트 고르기그 워크트리의 에이전트를 고르거나, 같은 메뉴에서 새 에이전트를 시작합니다.
- 답 읽고 다시 보기에이전트가 설명하거나 고친 뒤 diff를 다시 엽니다. 코멘트가 그대로 붙어 있으니 해결된 것은 Resolve(해결)로 접고, 남은 것은 후속 코멘트를 답니다. 해결 안 된 코멘트는 다음 Send에 함께 갑니다.
5단계 · 디자인 모드로 화면에서 직접 지적하기
웹 화면을 고친 경우에만 진행합니다. 문서·설명만 검토한다면 6단계로 넘어가세요. 주소가 없다면 에이전트에게 “실행한 화면을 확인할 주소와 확인 방법을 알려 줘”라고 요청합니다.
- 워크트리의 브라우저 칸에서 문제 페이지 열기에이전트가 알려 준 주소로 이동합니다.
- 도구 막대의 Design Mode(디자인 모드) 켜기마우스가 고르기 도구로 바뀌고, 올린 곳의 요소가 강조됩니다.
- 이상한 요소 클릭 → 원하는 것 적기그 요소의 HTML, 색·글꼴·여백 같은 스타일, 잘라 낸 스크린숏이 첨부물 하나로 에이전트 채팅에 들어갑니다. 예: “이 여백이 너무 좁아, 위 카드들과 맞춰 줘.”
- 여러 곳을 모아 보내도 됨주석 모음(annotation tray)에 메모 여러 개를 쌓았다가 Send로 한 번에 보냅니다. 보낸 메모는 화면에서 자동으로 지워집니다.
- 확인에이전트가 고치면 화면이 새로 고쳐집니다. 다시 클릭해 보고, 아직 틀리면 반복합니다.
6단계 · 확인한 결과를 저장하고, 필요하면 PR로 보내기
요청한 결과를 직접 확인했고, 설명이 필요한 코멘트가 모두 해결됐는지 봅니다. Commit까지만 해도 로컬 이력 저장은 완료입니다. 서버에 보낼 준비가 됐을 때 Push·Create PR로 이어 갑니다. 커밋 후에도 워크트리 삭제는 별도 판단이므로 보존 방법이 확실하지 않으면 그대로 둡니다.
- 사이드바의 Source Control 패널에서 Stage Files → CommitStage Files는 바뀐 파일을 이번 저장에 포함하는 동작입니다. 커밋(지금 상태를 이력에 한 번 저장하기) 메시지는 직접 쓰거나 Generate with AI로 초안을 받습니다. 단축키 Cmd+Enter / Ctrl+Enter.
- Pushpush(내 컴퓨터의 커밋을 서버로 올리기)하면 브랜치가 서버(origin)에 올라갑니다.
- Create PR리뷰 만들기 창에서 Generate pull request details with AI로 제목·설명 초안을 받고, 기준 브랜치·제목·설명을 확인해 제출합니다.
- 확신이 없으면 동료에게PR을 초안(Draft — 아직 검토 중임을 표시하는 상태)으로 만들어 개발자 동료에게 검토를 부탁합니다. 내가 남긴 코멘트와 에이전트의 설명을 함께 전하면 동료의 시간이 줄어듭니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| diff가 이상하거나 멈춘 것 같음 | diff 도구 막대의 새로 고침 아이콘을 눌러 워크트리를 다시 읽게 합니다. |
| 커밋이 실패함(검사 스크립트 거부) | 실패 내용의 Fix with AI를 누르면 기본 에이전트가 오류 내용을 받아 고칩니다(검사를 건너뛰라고 시키지는 않음). |
| Send to agent 단축키가 안 먹힘 | 기본 단축키가 없습니다. Settings → Shortcuts에서 Send Review Notes to Agent에 직접 지정합니다. |
| 디자인 모드 첨부물에 원본 파일·줄 위치가 없음 | 원본 파일·줄 위치는 개발 모드 소스 맵(source map)이 있을 때만 함께 담깁니다. 없어도 HTML·스타일·스크린숏은 담기므로, 필요하면 어느 화면인지 문장으로 덧붙입니다. |
- diff는 파일 목록부터: 부탁과 상관없는 파일이 바뀌었으면 먼저 묻습니다.
- 초록=새로 쓴 줄, 빨강=지운 줄. 모르는 줄은 + 또는 c로 “쉬운 말로 설명해 줘”.
- 코멘트는 모아서 Send to agent로 한 번에 — 해결되면 Resolve, 남은 건 다음 묶음에.
- 화면 문제는 Design Mode로 요소를 클릭해 바로 지적합니다.
- 검토를 마치면 Commit으로 저장합니다. 서버에 보낼 때는 Push → Create PR, 확신이 없으면 초안 PR로 동료에게 검토를 부탁합니다.
출처: onorca.dev/docs — recipes/review-ai-diff, review/diff-viewer, review/annotate-ai-diff, review/attribution, browser/design-mode, recipes/design-mode-fix, review/commit-push, review/github, troubleshooting · Orca 완전 가이드 4·6장
퇴근 후 폰으로 이어서 지시하기
회사 컴퓨터에서 에이전트에게 일을 맡겨 두고 퇴근한 뒤, 휴대폰으로 진행 상황을 보고 “계속해”, “이렇게 바꿔 줘” 같은 답을 보내는 방법입니다. 일은 계속 컴퓨터에서 돌고, 폰은 리모컨 역할만 합니다.
- 폰에 Orca 앱을 깔고 내 컴퓨터의 Orca와 한 번만 짝짓기(페어링)
- 에이전트가 나를 기다리면 폰으로 알림 받기
- 폰에서 답하고, 새 지시를 보내고, 결과 확인하기
- 다음 날 컴퓨터 앞에서 그대로 이어 가기
예상 소요 시간: 처음 설정 15~20분 · 이후 폰으로 답하기는 한 번에 1~2분
준비물
- 계속 켜져 있는 Orca 하나① 회사·집 컴퓨터의 Orca 데스크톱 앱을 닫지 않고 둡니다. 또는 ② 창 없이 도는 원격 Orca 서버(다른 컴퓨터에서 Orca를 계속 돌려 두는 방식)를 씁니다.
- 휴대폰iPhone(App Store) 또는 Android(APK 파일 설치). 폰 앱은 베타입니다.
- Relay를 쓴다면 같은 Orca 계정페어링(폰과 컴퓨터를한 번 짝지어 서로 알아보게 하는 일)에 Relay를 사용할 때는 두 기기에 같은 Orca 계정으로 로그인합니다. LAN으로 직접 연결하는 방식은 Relay 로그인이 필요하지 않지만, 연결할 컴퓨터의 주소가 필요합니다.
- 둘이 만날 길처음에는 Orca Relay(Orca가 중간에서 전달해 주는 중계소)를 권합니다. 같은 공유기(LAN)나 Tailscale(내 기기끼리만 쓰는 사설 네트워크 앱)로 직접 연결하는 방법도 있습니다. 퇴근 후 다른 장소에서 쓸 예정이라면 회사 공유기 안에서만 연결되는 LAN 주소에 의존하지 마세요.
데스크톱 앱을 켜 둔 채 Relay로 연결 → 폰에서 기존 대화에 한 번 답하기 → 컴퓨터에서 그 답 확인까지 먼저 해 봅니다. 원격 서버·새 작업 만들기는 그다음에 살펴보세요. 먼저 시나리오 1에서 에이전트 대화 하나를 준비해 두면 좋습니다.
따라 하기
App Store에서 Orca 모바일 앱을 설치합니다.
- Chrome 같은 일반 브라우저로 Orca 다운로드 페이지 열기 → Android 선택Discord·GitHub 앱 안에서 링크가 열렸다면 “브라우저에서 열기”로 바꿉니다.
- 다운로드가 끝나면 app-release.apk 누르기브라우저의 다운로드 목록이나 Files → Downloads에서 찾습니다.
- 설치 안내 따르기“알 수 없는 앱 설치” 허용을 묻으면 그 브라우저나 Files 앱에만 허용하고, 설치 후 다시 끕니다.
자세히: Android 설치
컴퓨터의 Orca에서 계정 / 상태 메뉴를 열고 휴대폰 연결(페어링) 항목을 찾습니다. 메뉴 이름은 버전에 따라 다를 수 있으므로, 아래 그림의 문구가 아니라 일회용 코드가 나오는지를 확인합니다. 화면에 한 번만 쓰는 페어링 코드가 뜹니다. 코드는 몇 분 뒤 만료되니 바로 다음 단계로 넘어가세요.
내 계정 · 사용량 …
휴대폰 연결 항목 ← 위치를 설명하는 예시 (실제 버튼 이름이 아님)
일회용 페어링 코드: ●●●●-●●●● (몇 분 뒤 만료)
창 없는 서버로 연결하는 경우
서버 터미널에서 orca serve --pairing-address <서버 주소> --mobile-pairing을 실행하면 폰용 QR 코드와 링크가 나옵니다. 폰은 서버와 같은 Tailscale 망에 있어야 합니다. → 가이드: 서버에서 모바일 연결
- 폰 앱에서 Pair 선택컴퓨터 쪽 딥 링크(누르면 앱의 그 화면으로 바로 가는 링크)를 눌러 페어링 화면으로 바로 가도 됩니다.
- 코드 붙여넣기(서버라면 QR 스캔)
- 연결 방법 고르기: 가능하면 Orca RelayRelay를 쓸 때만 로그인이 필요합니다. 같은 공유기(LAN)로 빠르게 가고 싶으면 로컬 주소 선택을 펼칩니다. LAN만으로 연결할 때는 주소가 꼭 필요합니다.
페어링 코드 [ ●●●●-●●●● ]
Orca Relay 로컬 주소(선택)
Pair
성공하면 폰의 호스트(연결할 컴퓨터) 목록에 컴퓨터 이름과 운영체제가 보입니다. 이후에는 다시 짝지을 필요 없이 자동으로 다시 연결됩니다. → 가이드: 페어링하기
폰에서 알림을 받을 수 있도록 휴대폰의 Orca 알림 허용 상태를 확인합니다. 에이전트가 일을 마치면 폰에도 알림이 옵니다. 먼저 짧은 일을 하나 맡기고 폰에서 알림과 해당 대화를 열 수 있는지 시험하세요. 알림이 오지 않더라도 호스트 목록에서 직접 대화를 열어 확인할 수 있습니다.
알림 종류와 버전별 선택
기존 1.4.246 안내에는 폰에서 “응답 필요” 알림만 받는 선택과 컴퓨터에서 “응답 필요”·“완료” 알림을 따로 조정하는 기능이 소개되어 있습니다. 현재 버전의 화면에서 해당 선택이 제공되는지 확인하세요.
? 응답 필요 feature-login · Claude가 권한을 묻고 있습니다
✓ 완료 알림은 받지 않음(“응답 필요만” 선택 시)
호스트 목록에서 워크트리(에이전트 한 명이 일하는 독립된 작업 공간)를 열면 상태가 보입니다. 주황 ?가 붙은 곳이 나를 기다리는 에이전트입니다.
- Chat UI로 보기 — Claude·Codex 등 지원 에이전트는 터미널 대신 읽기 쉬운 대화 화면으로 열 수 있습니다. 폰 기본값은 Settings → Chat UI → Open sessions in Chat UI, 탭 하나만 바꾸려면 세션 탭을 길게 누릅니다.
- 새 일 맡기기 — 폰에서 워크스페이스(워크트리)를 새로 만들거나 기존 워크트리에 에이전트를 시작할 수 있습니다. 그 탭은 컴퓨터에도 바로 나타납니다.
- 자주 쓰는 지시 — 컴퓨터에 저장해 둔 Quick Commands(저장된 명령·프롬프트)를 폰에서도 그대로 씁니다.
여기까지 확인: 이미 열어 둔 대화에 “지금까지 한 일을 한 문장으로 알려 줘”를 보내고, 답이 오는지 봅니다. 컴퓨터에서도 같은 대화와 답이 보이면 원격으로 이어서 지시할 준비가 된 것입니다.
에이전트가 끝났으면(초록) 무엇을 했는지 폰에서 확인합니다. 폰 앱은 편집기가 아니라 확인과 작은 후속 조치용입니다.
대화 / 터미널 기록 — 에이전트가 한 일과 물어본 것을 읽음
파일 트리 — 바뀐 파일을 바로 열어 봄
브랜치 아이콘 → Source Control: 바뀐 파일 목록 · diff(바뀐 부분만 보여 주는 화면) · 커밋
급하지 않으면 커밋(변경을 저장 지점으로 남기기)은 다음 날 컴퓨터에서 꼼꼼히 보고 해도 됩니다. → 가이드: 폰의 Source Control
폰에서 한 일은 처음부터 컴퓨터에서 일어난 일입니다. 아침에 컴퓨터 앞에 앉으면 어젯밤 대화, 폰에서 시작한 에이전트 탭이 그대로 있습니다. 따로 옮기거나 동기화할 것이 없습니다.
검토 방법: 가이드 6장 Diff viewer
- 페어링 코드나 서버 접속 링크를 가진 사람은 내 Orca를 조종할 수 있습니다. 메신저 단체방·이슈 댓글에 붙여 넣지 마세요.
- 원격 서버 링크를 잘못 보냈다면 서버의 Settings → Remote Orca Servers → Shared Server Access에서 휴지통 버튼으로 그 권한을 취소하고 새 링크를 만듭니다. → 가이드: 접근과 보안
- Orca 포트를 인터넷에 그대로 열지 말고 Relay·Tailscale·믿을 수 있는 LAN을 씁니다.
- Android에서 “알 수 없는 앱 설치” 허용은 설치가 끝나면 다시 끕니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 페어링이 실패함 | Relay를 사용한다면 폰과 컴퓨터가 같은 Orca 계정인지 확인. 코드는 몇 분 뒤 만료되니 새 코드를 만들어 다시 시도. |
| 폰이 컴퓨터에 닿지 않음 | 컴퓨터의 Orca 앱을 닫았는지 확인 — 닫으면 연결이 끊기고, 다시 열면 폰이 자동으로 재연결됩니다. LAN·Tailscale 등 둘이 같은 길에 있는지 확인. 폰 연결이 끊겼다고 백그라운드 에이전트도 즉시 끝났다는 뜻은 아닙니다. 앱 종료와 컴퓨터 종료의 차이는 시나리오 7에서 확인합니다. |
| Authentication failed / pairing invalid | 배너의 Retry를 먼저 누르고, 계속되면 컴퓨터에서 다시 페어링하거나 호스트를 지우고 새로 짝짓기. |
| Update Orca Mobile / Update Orca on your computer | 폰 앱이나 컴퓨터 Orca 중 오래된 쪽을 업데이트한 뒤 연결을 새로 고침. 그래도 남으면 호스트를 지우고 다시 페어링. |
연결 문제를 차례대로 확인하려면 시나리오 8: 막혔을 때 복구하기. 더 많은 경우: 가이드: 모바일 문제 해결 · Samsung Galaxy에서 Auto Blocker가 설치를 막으면 잠시 끄고 설치 후 다시 켭니다(Play Protect는 끄지 않음).
- 컴퓨터의 Orca(또는 원격 Orca 서버)를 켜 두고, 폰은 리모컨으로 씁니다.
- 폰 앱 설치 → 컴퓨터에서 페어링 코드 → 폰에서 Pair(가능하면 Relay) — 한 번만 하면 됩니다.
- 폰으로 시험 메시지를 보내고 컴퓨터에 같은 답이 보이는지 확인합니다. 주황 ?가 보이면 기다리는 질문을 읽고 답합니다.
- 결과는 폰에서 훑어보고, 꼼꼼한 검토·커밋은 다음 날 컴퓨터에서 — 기록은 모두 컴퓨터에 그대로 있습니다.
- 페어링 코드·접속 링크는 비밀번호처럼 다룹니다.
출처: onorca.dev/docs — Mobile companion, Install Orca Mobile on Android, Remote Orca Servers, Notifications & Inbox, Changelog 1.4.246(2026-11-04에 읽음). 가이드 8장 모바일·1장 알림.
매일 아침 정리 작업을 자동으로 맡기기
“매일 아침 9시에 새 이슈를 분류해서 요약해 줘”처럼 반복되는 부탁을 한 번 등록해 두면, Orca가 정해진 시간에 에이전트를 깨워 일을 시킵니다. 한 번 시험해 대상과 결과를 확인한 뒤 예약을 켭니다. 실행할 컴퓨터의 Orca와 에이전트가 준비되어 있어야 합니다.
- 예약 자동화가 무엇인지 알고, 맡길 일을 프롬프트로 적기
- 데스크톱 Automations 화면 또는 CLI로 꺼진 상태의 자동화 만들기
- 한 번 직접 실행해 대화나 실행 기록에서 결과를 확인하기(할 일이 없는 날 건너뛰기는 선택)
- 마지막으로 켜서 매일 돌게 하기
예상 소요 시간: 처음 만들고 시험하기 20~30분 · 이후 매일 아침 결과 읽기 5분
문서 점검 프롬프트 → 꺼진 자동화 1개 → 수동 실행 → 결과 확인 → 예약 켜기 순서로 진행합니다. 화면에서 만들더라도 아래 수동 실행·켜기는 CLI(터미널에 적는 명령)로 이어집니다. 3단계 사전 점검은 건너뛰어도 됩니다. 아직 파일 확인이 익숙하지 않다면 시나리오 6: 문서 실습부터 해 보세요.
준비물
- Orca 데스크톱과 문서가 있는 프로젝트 하나자동화가 일할 저장소가 Orca에 추가되어 있어야 합니다. 이 실습은
--repo로 저장소를 대상으로 삼으므로, 기준 브랜치에 이미 들어 있는 문서 폴더를 사용합니다.docs가 없다면 실제 문서 폴더 이름으로 바꿉니다. 시나리오 6의 연습 워크트리에만 만든 미커밋 파일은 이 자동화에 그대로 보인다고 가정하면 안 됩니다. 그 파일을 대상으로 하려면 아래 개발자용 참고의--workspace방식을 별도로 선택해야 합니다. - 로그인된 에이전트Claude Code나 Codex 등. 자동화가 다른 호스트(원격 Orca 서버)에서 돈다면 그 컴퓨터에 설치·로그인되어 있어야 합니다.
- 명령을 입력할 터미널과 orca 명령이 실습의 실행·켜기 단계에서 씁니다. 에이전트 대화 입력칸이 아니라 컴퓨터의 터미널 앱(macOS의 Terminal, Windows의 PowerShell 등)에서 입력합니다. Orca의 Settings → General → Orca CLI(설정 → 일반 → Orca 명령)에서 등록한 뒤 터미널을 새로 열고
orca status --json을 실행하세요. 앱 상태가 출력되면 준비된 것입니다. 명령을 찾을 수 없으면 CLI 설치를 먼저 확인합니다. - 예약 시간에 실행할 컴퓨터자동화가 저장된 컴퓨터에서 실행하므로 그 컴퓨터의 Orca와 에이전트를 사용할 수 있어야 합니다. 처음에는 현재 컴퓨터를 대상으로 시험합니다.
- 맡길 일 한 줄아래 프롬프트 예시를 참고하세요.
| 시작 전 확인 | 해 볼 것 | 준비된 상태 |
|---|---|---|
| Orca 명령 연결 | 터미널에서 orca status --json | 현재 Orca 상태가 출력됨 |
| 점검할 문서 | 기준 브랜치의 실제 문서 폴더 확인 | 점검할 파일이 있고, 프롬프트에 같은 폴더 이름을 적음 |
| 실행할 에이전트 | 현재 컴퓨터에서 로그인된 에이전트 확인 | 예제의 codex를 그대로 쓸지 claude 등으로 바꿀지 정함 |
따라 하기
매일 같은 말로 시켜도 되는 일이 좋습니다. 처음엔 “고치지 말고 보고만” 하게 하면 안전합니다.
지난 24시간 동안 새로 열린 이슈를 버그 / 기능 요청 / 질문으로 나눠 표로 요약해 줘. 막힌 일(blocker)은 맨 위에. 코드는 고치지 마.
docs 폴더에서 깨진 링크와 날짜가 오래된 문서를 찾아 목록으로 보고해 줘. 파일은 고치지 말고 고칠 방법만 제안해.
어제 들어온 변경을 팀원이 읽기 쉽게 다섯 줄 이내로 요약해 줘.
처음 따라 할 때는 ② 문서 정리 점검을 사용하세요. docs 폴더가 없다면 프로젝트의 실제 문서 폴더 이름으로 바꿉니다. 아래 예제 명령도 같은 요청을 사용합니다.
이슈(버그·요청을 적어 둔 서비스의 작업 항목)를 읽으려면 에이전트가 GitHub 같은 서비스에 접근할 수 있는 환경이어야 합니다(예: gh 로그인).
프롬프트를 다듬는 동안 엉뚱한 시간에 돌지 않도록 꺼 둔 채로 만듭니다.
- Orca 데스크톱의 Automations 화면 열기이 컴퓨터와 연결된 Orca 호스트의 자동화가 한 표에 보입니다.
- 새 자동화를 만들고 Create on에서 호스트 고르기어느 컴퓨터에 저장·예약할지 먼저 고르고, 그다음 그 호스트의 프로젝트를 고릅니다.
- 이름·프롬프트·에이전트·일정 채우기현재 버전에서 실행 방식 선택이 보이면 Chat(대화) 또는 Terminal(터미널)을 고릅니다. 기존 1.4.246 안내의 Chat은 결과를 대화로 읽는 방식입니다. 이 선택이 없어도 아래 실행 기록으로 확인을 이어갈 수 있습니다.
- 꺼진(Paused) 상태로 저장목록의 Filters에서 Enabled / Paused로 상태를 구분해 볼 수 있습니다.
Create on: 이 컴퓨터 → 프로젝트: my-repo
이름: Weekday triage · 일정: 평일 09:00 · 에이전트: codex(설치된 에이전트로 변경)
실행 방식: Chat Terminal
Advanced → Extra agent arguments (모델·effort만, 선택)
화면 흉내는 예시이며 실제 배치는 버전마다 다를 수 있습니다.
orca automations create \
--name "Weekday triage" \
--trigger weekdays \
--time 09:00 \
--prompt "docs 폴더에서 깨진 링크와 날짜가 오래된 문서를 찾아 목록으로 보고해 줘. 파일은 고치지 말고 고칠 방법만 제안해." \
--provider codex \
--repo my-repo \
--disabled \
--json
| 예제 값 | 내 값으로 바꿀 내용 |
|---|---|
my-repo | Orca에 등록한 저장소 이름 |
codex | 로그인된 에이전트(Claude Code는 claude) |
docs | 기준 브랜치에 있는 실제 문서 폴더 이름 |
위 여러 줄 명령은 macOS·Linux 셸 기준입니다. 값을 바꾼 명령 전체를 붙여 넣고 Enter를 누릅니다. Windows PowerShell에서는 아래 한 줄 형식을 사용하세요.
Windows PowerShell용 한 줄 명령
orca automations create --name "Weekday triage" --trigger weekdays --time 09:00 --prompt "docs 폴더에서 깨진 링크와 날짜가 오래된 문서를 찾아 목록으로 보고해 줘. 파일은 고치지 말고 고칠 방법만 제안해." --provider codex --repo my-repo --disabled --json원래 이슈 분류 예시를 쓰려면 프롬프트를 “새 이슈를 분류하고 막힌 일을 요약해 줘”로 바꿀 수 있습니다. 해당 서비스 접근 준비를 먼저 마칩니다.
일정 옵션과 예제 명령 읽는 법
--trigger일정:hourly(매시간)·daily(매일)·weekdays(평일)·weekly(매주), 또는 cron 식(분·시·요일 등으로 예약 시각을 적는 표기)--disabled꺼진 상태로 만들기 — 처음엔 꼭 붙입니다- 결과의 자동화 id를 메모해 둡니다(다음 단계에서 씀).
화면과 CLI 중 한 가지 방법으로만 만듭니다. 이어서 터미널에서 orca automations list --json을 실행하고, 방금 만든 이름과 저장소가 맞는 항목의 ID를 찾습니다. 아래 모든 <automationId>는 그 ID로 바꾸며 꺾쇠는 남기지 않습니다. 예를 들어 ID가 abc123이면 orca automations show abc123 --json입니다. show 결과에서 대상·프롬프트·일정·꺼짐 상태를 확인한 뒤 계속하세요. 같은 이름의 다른 자동화와 혼동되면 먼저 이름을 구분하세요.
옵션 전체: 가이드: 예약 자동화
첫 실습에서는 다음 단계로 넘어가세요. 자동화 한 개를 끝까지 시험한 뒤, 필요할 때 이 선택 기능을 추가합니다.
사전 점검 원리와 별도 PR 검토 예제
새 이슈가 하나도 없는데 에이전트를 부르면 시간과 사용량만 듭니다. --precheck에 가벼운 셸 명령(터미널에서 실행하는 한 줄 명령)을 넣으면, 그 명령이 실패(0이 아닌 종료 코드)할 때 그 회차는 건너뜀으로 기록됩니다.
orca automations create \
--name "PR review" \
--trigger hourly \
--precheck "gh pr list --json number -q .[0].number" \
--prompt "Review requested PRs" \
--provider codex \
--repo my-repo \
--disabled \
--json
위는 별도 자동화 한 개를 새로 만드는 원문 예시(요청된 PR 검토)입니다. 앞에서 만든 아침 정리 자동화의 ID가 바뀌는 것이 아닙니다. PR(변경 사항의 검토·병합 요청) 예제를 실행하려면 GitHub 명령 도구인 gh 로그인도 필요합니다. 아침 이슈 정리라면 “새 이슈가 없으면 실패하는 명령”을 넣으면 됩니다. 명령이 늘 실패하면 매번 건너뛰므로 결과를 확인하세요. “할 일 없음”과 연결·로그인 오류를 같은 것으로 판단하지 않도록, 명령 자체의 출력도 확인합니다. 출력이 비어 있는 것과 실패한 것은 다릅니다. 위 PR 예제도 목록이 비었다는 이유만으로 실패한다고 가정하지 마세요. 실제 종료 결과가 0이 아닌지 확인하고, “할 일 없음”을 그 결과로 돌려주는 점검 명령을 사용해야 건너뜁니다.
내일 아침까지 기다리지 말고 지금 한 번 돌려 프롬프트와 대상이 맞는지 봅니다. 꺼진 자동화도 수동 실행은 됩니다. 2단계에서 기록한 같은 ID를 아래 두 줄에 각각 넣고, 터미널에서 첫 줄부터 실행합니다. 두 번째 줄은 실행 기록을 읽는 명령입니다.
orca automations run <automationId> --json
orca automations runs --id <automationId> --json
방금 · 수동 실행 · 실행 중
어제 · 실패(워크스페이스를 열기 전) Rerun
확인할 결과: 새 수동 실행이 기록되고, 실행 결과에서 부탁한 문서 점검 내용이 나오는지 봅니다. 아직 실행 중이면 잠시 뒤 두 번째 명령을 다시 실행하세요. 상태가 성공이어도 결과 내용이 다른 프로젝트라면 예약을 켜지 말고 대상부터 고칩니다.
워크트리를 열거나 대상에 다시 연결하기 전에 실패한 실행은, Orca에서 그 실행을 열고 Rerun을 누르면 같은 자동화의 새 수동 실행이 대기열에 들어갑니다.
Orca의 Automations 목록에서 만든 자동화를 열면 Overview(개요)와 Runs(실행 기록)가 있습니다. Runs에서 방금 실행한 회차를 엽니다. 문서 목록·제안이 실제로 출력되었는지, 파일을 고치지 말라는 부탁을 지켰는지 확인합니다. Chat으로 실행한 자동화는 녹화된 대화로 결과를 볼 수 있고, 터미널로 실행한 경우에는 실행 기록과 해당 터미널 내용을 확인합니다. Chat 제공 여부와 화면 배치는 현재 버전에서 확인하세요(기존 1.4.246 안내: Automations in Chat).
이슈 분류를 맡겼을 때의 결과 예시
자동화: “새 이슈를 분류하고 요약해 줘” → 에이전트: “새 이슈 7건 · 버그 3 / 기능 요청 2 / 질문 2 · 막힌 일: #128 로그인 오류”. 숫자와 이슈 번호는 설명용 예시입니다.
Chat 화면 읽는 법: 가이드 3장 Chat · 최근 변경: 1.4.246
대상·프롬프트·실행 결과가 맞으면 예약을 켭니다. 아래 명령의 ID도 처음 기록한 ID로 바꿉니다. 그다음 orca automations show <automationId> --json으로 같은 자동화가 켜진 상태인지 다시 확인하세요.
orca automations edit <automationId> --enabled --json
Weekday triage · Host: 이 컴퓨터 · 지난 실행: 성공 · Paused → Enabled
실습 완료: 자동화 1개가 켜져 있고, 그 자동화에 성공한 수동 실행 기록과 읽을 수 있는 결과가 남아 있으면 끝입니다. 다음 예약 때 같은 결과가 생기는지도 확인하세요.
edit로 이름·프롬프트·에이전트·대상·일정·켜짐 상태를 나중에 바꿀 수 있고, remove는 자동화와 실행 기록을 지웁니다. 데스크톱 목록은 Filters(Host, Enabled/Paused, 지난 실행 결과, Agents)와 검색으로 좁혀 봅니다.
더 알아 두면 좋은 옵션 (필요할 때만)
--timezone <tz>— 특정 시간대(예: Asia/Seoul)를 따르게 함.--workspace <selector>— 새 작업 대신 기존 워크트리 안에서 실행.--repo와 둘 다 빼면 지금 셸 위치의 워크트리를 씀.--reuse-session— 기존 워크트리 대상일 때 지난 자동화 터미널에서 이어서 실행. 되돌리기는edit … --fresh-session.--extra-agent-args="--model opus"— 회차마다 모델·effort만 바꿈(Claude는--add-dir도). 권한·설정·프롬프트·세션 옵션은 거부되며--reuse-session과 함께 못 씀.edit <id> --missed-run-grace-minutes 30— 놓친 예약 실행을 얼마 동안까지 봐줄지.--project <projectId> --host <hostId>— 특정 호스트의 프로젝트 설정에서 실행.
예약을 계속 돌리기 전에 자동화를 꺼진(Paused) 상태로 돌립니다. CLI에서는 먼저 orca automations edit --help로 현재 버전의 끄기 옵션을 확인하고, 처음 기록한 자동화 ID에 그 옵션을 적용합니다. 다시 orca automations show <automationId> --json을 실행해 꺼짐 상태인지 확인하세요. 프롬프트·대상을 고친 뒤 수동 실행부터 다시 확인하세요. 시나리오 8: 막혔을 때 복구하기도 참고할 수 있습니다.
막히면
| 증상 | 해 볼 것 |
|---|---|
| 매번 “건너뜀”만 기록됨 | 사전 점검 명령이 늘 실패하고 있을 수 있습니다. 그 명령을 터미널에서 직접 실행해 성공하는지 보고, 필요하면 edit로 고칩니다. |
| 실행이 시작도 못 하고 실패 | 워크트리를 열기 전에 실패했다면 그 실행을 열고 Rerun. 대상(--repo/--workspace)이 맞는지 show로 확인. |
| Create on에서 호스트가 회색(Update server) | 그 호스트의 Orca 서버가 오래되었습니다. 그 컴퓨터의 Orca를 업데이트합니다. |
| 원격 호스트에서 에이전트를 못 찾음 | 원격 실행은 그 서버의 설치·로그인 정보를 씁니다. 서버 컴퓨터에 에이전트 CLI를 설치하고 로그인합니다. → 가이드: 원격 서버 문제 해결 |
- 예약 자동화 = 정해진 시간에 Orca가 에이전트에게 프롬프트를 건네는 기능.
- 순서: 프롬프트 적기 → 꺼진 채 만들기(화면 또는
--disabled) → 한 번 수동 실행 → 결과 확인 → 켜기. - 같은 자동화 ID로 만들기 이후의 조회·실행·켜기를 이어갑니다. 사전 점검은 필요할 때 추가하는 선택 기능입니다.
- Runs에서 회차를 열어 결과를 읽습니다. Chat이면 대화로, 터미널 실행이면 실행 기록과 터미널 내용으로 확인합니다.
- 처음엔 “고치지 말고 보고만” 하는 프롬프트로 시작합니다.
출처: onorca.dev/docs — Scheduled automations(CLI), Remote Orca Servers, Changelog 1.4.246(2026-11-04에 읽음). 가이드 7장 예약 자동화. 프롬프트·화면 속 이름(Weekday triage, my-repo, 이슈 번호)은 예시입니다.
코드 없이 안내문 하나 완성하기
실제로 읽을 수 있는 안내문 파일을 만들어 봅니다. 초안이 나왔다는 답에서 끝내지 않고, 파일을 열어 읽고 고칠 곳을 전달한 뒤 최종 내용을 확인합니다.
- 제공한 자료만으로 안내문 초안을 만듭니다.
- 문서 파일을 열어 읽고, 구체적인 수정 요청을 보냅니다.
- 자동 저장과 커밋의 차이를 알고 결과를 남깁니다.
예상 소요 시간: 20~30분
준비물과 완료 기준
- 시나리오 1의 저장소 등록·워크트리 생성을 마친 상태와 로그인된 에이전트 1개. 워크트리는 작업별로 나눈 별도 작업 폴더입니다.
- 연습용 워크트리 이름은
onboarding-guide로 합니다. 이미 다른 이름으로 만들었다면 그 이름을 계속 쓰면 됩니다. - 이번 자료는 아래의 가상 연습 자료를 사용합니다. 실제 회사의 계정·주소·정책을 넣을 필요가 없습니다.
docs/welcome-practice.md 파일을 직접 열어 제목·첫날 할 일·문의 방법을 읽을 수 있고, 제공하지 않은 정보가 만들어지지 않았으며, 수정 요청이 반영되면 완료입니다. 앱 실행이나 웹 주소는 필요하지 않습니다.
따라 하기
1단계 · 자료와 만들 파일을 정하기
연습 워크트리에서 에이전트 탭을 열고 아래 내용을 그대로 보냅니다. .md는 제목·목록 등을 적는 문서 파일의 확장자입니다.
가상 회사의 신규 입사자 안내문을 docs/welcome-practice.md에 만들어 줘.
자료: 첫날 오전 10시에 온라인 오리엔테이션이 있다.
첫날 할 일: 소개 글 읽기, 일정 확인, 궁금한 점 적기.
문의 방법: 담당자에게 질문 목록을 전달한다.
담당자 이름, 접속 주소, 계정 발급 절차는 아직 정해지지 않았다.
문서 구성: 제목, 첫날 할 일, 문의 방법, 확인이 필요한 정보.
제공하지 않은 사실은 만들지 말고 '확인 필요'라고 적어 줘.
이 파일만 만들고, 기존 파일이 있으면 덮어쓰기 전에 물어봐.
끝나면 파일 경로와 바꾼 내용을 쉬운 말로 알려 줘.
확인: 에이전트가 자료를 받았고 작업 중 표시가 보이면 기다립니다. 질문이 오면 내용을 읽고 답합니다. 완료 답변에 파일 경로가 있어야 합니다.
2단계 · 완성된 초안 파일 열기
- 워크트리의 탭 줄에서 + 누르기검색 칸에
welcome-practice.md를 입력합니다. 파일 이름과 경로가docs/welcome-practice.md인 결과를 선택합니다. 왼쪽 파일 탐색기에서 docs 폴더를 펼쳐 같은 파일을 열어도 됩니다. - 제목과 목록 읽기Markdown 문서는 기본적으로 읽고 편집하기 쉬운 문서 화면으로 열립니다. 제목·첫날 할 일·문의 방법·확인 필요 항목이 있는지 봅니다.
확인: 채팅의 설명뿐 아니라 실제 파일 안에 안내문이 보입니다. 파일이 없다면 아래 ‘막히면’을 확인합니다.
3단계 · 고칠 점을 한 번에 전달하기
예시로 아래 부탁을 같은 에이전트 탭에 보냅니다. 실제 회사 자료를 추가하지 않고, 문장의 모양을 바꾸는 연습입니다.
docs/welcome-practice.md를 수정해 줘.
첫날 할 일은 체크 목록으로 바꾸고, 각 항목은 한 문장으로 짧게 써 줘.
'확인 필요'에는 담당자 이름, 접속 주소, 계정 발급 절차를 모두 남겨 줘.
시간은 오전 10시 그대로 유지하고, 다른 파일은 바꾸지 마.
끝나면 바뀐 항목을 알려 줘.
확인: 작업 완료 후 같은 파일을 다시 읽습니다. 목록 모양은 바뀌고 오전 10시와 세 가지 미정 항목은 남아 있어야 합니다. 잘못 바뀐 것이 있으면 원래 값과 원하는 값을 함께 적어 다시 요청합니다.
참고: 문서 화면에서 검토 메모 남기기
문서의 글을 선택하면 원문 위치에 연결된 검토 메모를 남길 수 있습니다. Add Review Note(검토 메모 추가)의 기본 단축키는 Cmd+Shift+A / Ctrl+Shift+A이며 Settings → Shortcuts에서 바꿀 수 있습니다. 이 실습은 채팅으로 요청해도 완료할 수 있습니다. 메모를 적는 것과 에이전트에게 수정 요청을 보내는 것은 구분하세요.
4단계 · 자료와 나란히 최종 확인하기
신규 입사자 첫날 안내
첫날 오전 10시에 온라인 오리엔테이션이 있습니다.
첫날 할 일
- ☐ 소개 글을 읽습니다.
- ☐ 일정을 확인합니다.
- ☐ 궁금한 점을 적습니다.
문의 방법
적어 둔 질문 목록을 담당자에게 전달합니다.
확인 필요
담당자 이름 · 접속 주소 · 계정 발급 절차
위는 제공한 자료로 만든 완성 예시입니다. 제목이나 문장이 똑같을 필요는 없습니다. 오전 10시, 첫날 할 일 세 가지, 문의 방법, 확인 필요 항목 세 가지가 빠짐없이 있고 새 사실이 생기지 않았는지 대조하세요.
- 1단계의 자료와 문서 비교시간은 오전 10시인지, 첫날 할 일 세 가지가 모두 있는지, 담당자 이름이나 접속 주소가 지어내어지지 않았는지 확인합니다.
- 읽는 사람 입장에서 확인처음 읽는 사람이 무엇을 해야 하는지 알 수 있나요? 모르겠는 문장이 있다면 그 문장을 복사해 “이 문장을 더 쉽게 바꿔 줘”라고 요청합니다.
- 바뀐 파일 범위 확인에이전트에게 바뀐 파일 목록을 요청하고 시나리오 3의 변경 목록과 비교합니다. 부탁한 파일 외 변경이 있다면 이유를 묻습니다.
확인: 자료와 다른 부분이 없고, 다른 파일 변경이 있다면 그 이유까지 확인한 상태입니다.
5단계 · 파일 위치를 남기고 마무리하기
에이전트에게 “최종 파일 경로와 남은 확인 필요 항목을 알려 줘”라고 보냅니다. 파일 위치를 메모하고, 다음에 이어 쓸 워크트리는 삭제하지 않습니다.
에디터는 짧은 대기나 다른 곳을 누를 때 파일을 자동 저장합니다. 자동 저장은 파일을 디스크에 쓰는 일이고, 커밋은 그 상태를 변경 이력에 남기는 일입니다. 이력까지 남기려면 시나리오 3의 로컬 커밋 절차로 이어갑니다. PR 제출이나 공개 링크 생성은 이번 완료 조건이 아닙니다.
확인: 파일을 닫았다가 같은 경로로 다시 열어 최종 내용이 보이면 파일 확인은 끝입니다. 다음에 찾는 방법은 시나리오 7에서 연습합니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 파일이 검색되지 않음 | 지금 선택한 워크트리가 에이전트가 작업한 곳인지 확인합니다. 에이전트에게 “파일을 실제로 만들었는지와 정확한 경로를 확인해 줘”라고 요청하고 그 경로를 다시 검색합니다. |
| 기호가 섞인 원문 화면으로 열림 | 큰 문서나 문서 편집기에서 안전하게 보존할 수 없는 형식은 원문 에디터로 열릴 수 있습니다. 파일이 사라진 것은 아닙니다. Markdown 보기 방식은 문서 에디터 안내를 확인합니다. |
| 에디터에 외부 변경 안내가 뜸 | 에이전트와 직접 편집이 겹쳤을 수 있습니다. 바로 덮어쓰지 말고 안내의 비교 기능으로 두 내용을 확인합니다. 어느 쪽을 남길지 모르겠으면 편집을 멈추고 도움을 요청합니다. |
| 자료에 없는 내용이 들어감 | 문장과 이유를 구체적으로 적습니다. 예: “접속 주소는 제공하지 않았으니 삭제하고 확인 필요로 바꿔 줘.” 수정 후 파일에서 다시 확인합니다. |
선택: 완성된 Markdown 문서를 공개 링크로 공유하기
문서 헤더의 Share as artifact는 로그인된 Orca 계정으로 공개 보기 링크를 만듭니다. 먼저 Settings → Artifacts → Allow publishing public artifact links를 켜야 하며 기본값은 꺼짐입니다. 파일 한도는 10 MiB입니다. 공개해도 되는 내용인지 확인한 문서에만 사용하세요. 같은 문서를 다시 게시하면 매핑이 남아 있을 때 같은 링크가 갱신되고, 사이드바 Artifacts에서 링크를 관리·삭제할 수 있습니다. 자세히: 아티팩트로 공유.
- 자료·파일 경로·바꿀 범위를 정해 초안을 요청합니다.
- 답변만 믿지 않고 실제 파일을 열어 읽습니다.
- 원하는 수정과 유지할 사실을 함께 적고 다시 확인합니다.
- 파일 위치를 남깁니다. 자동 저장과 커밋은 다릅니다.
출처: 로컬 공식 문서 수집본 editing/markdown, editing/file-explorer, editing/monaco, model/quick-open. 가이드 5장 문서 편집. 회사·파일 이름·안내문 자료·프롬프트는 연습용 예시입니다.
어제 하던 일을 찾아 이어 하기
작업 이름을 기억해 두고 다음 날 같은 파일과 대화를 찾아봅니다. 이미 열려 있는 에이전트에게 이어서 말하는 경우와, 기록에서 지난 대화를 다시 여는 경우를 구분합니다.
- 워크트리와 탭을 찾아 지난 작업 내용을 확인합니다.
- 필요할 때 Session History에서 대화를 찾아 재개합니다.
- 앱 복원과 파일 변경 이력 복구가 다르다는 것을 이해합니다.
예상 소요 시간: 10~15분
준비물과 완료 기준
- 시나리오 6의 안내문 또는 시나리오 1에서 작업한 워크트리 1개. 이번에는 삭제하지 않은 것을 사용합니다.
- 작업 이름·파일 경로·무슨 일을 했는지를 적은 메모. 예:
onboarding-guide / docs/welcome-practice.md / 첫날 안내문. - 같은 컴퓨터에서 실행 가능한 로그인된 에이전트. 기록 재개 실습은 기록이 남는 지원 에이전트를 사용합니다.
이전 작업의 이름과 파일 내용을 확인한 뒤, 같은 작업 맥락으로 후속 요청 한 번을 보내고 그 결과를 확인하면 완료입니다. 살아 있는 탭에서 이어 할 수 있다면 기록에서 다시 열 필요가 없습니다.
따라 하기
1단계 · 끝난 일과 다음 할 일 적어 두기
이전 작업의 에이전트 탭에 아래 문장을 보냅니다. 이미 작업을 닫았다면 기억나는 범위만 메모하고 다음 단계로 갑니다.
지금 파일은 더 바꾸지 말고, 다음에 이어 할 수 있게 정리해 줘.
1. 이 워크트리에서 끝낸 일
2. 바뀐 파일 경로
3. 아직 확인하지 못한 점
4. 다음에 할 일 한 가지답변에서 작업 이름과 파일 경로를 메모합니다. 워크트리는 삭제하지 않고 남겨 둡니다. 확인: 다음에 찾을 이름과 다음 할 일이 한 줄 이상 적혀 있습니다.
2단계 · Orca를 열고 같은 워크트리 찾기
- Orca 열기이미 켜져 있다면 그대로 진행합니다. 다시 실행한 경우 열려 있던 워크트리·탭·분할 화면과 마지막 저장된 터미널 기록이 복원됩니다.
- 사이드바에서 메모한 이름 선택등록된 저장소 아래에서 작업 이름을 찾아 누릅니다. 이름이 비슷하면 파일 경로와 마지막 대화도 함께 확인합니다.
- 파일을 열어 내용 확인탭 줄의 + 검색 칸에 메모한 파일 이름을 입력해 엽니다. 예시 안내문이라면 오전 10시와 확인 필요 항목이 그대로 있는지 읽습니다.
확인: 지난 작업의 파일이 맞습니다. 창이 복원되어도 이전 파일 상태로 되돌아간 것은 아닙니다.
작업이 많다면: 빠른 이동
Cmd+J(macOS)로 Jump Palette를 열고 저장소나 워크트리 이름을 입력하면 작업과 탭을 찾을 수 있습니다. Shift+Enter로 작업을 분할 화면에 열 수 있습니다. 단축키는 Settings → Shortcuts에서 바꿀 수 있습니다. 빠른 이동 안내.
3단계 · 열린 에이전트 탭부터 확인하기
지난 대화가 열린 에이전트 탭을 누릅니다. 회전 원이면 작업 중이므로 먼저 진행 내용을 읽고, 주황 물음표라면 질문에 답합니다. 초록이나 회색이라면 마지막 답과 남은 일을 확인합니다.
입력을 받는 같은 대화가 살아 있으면 기록에서 새로 재개하지 말고 그 탭에서 5단계로 이어갑니다. 탭의 Restart(다시 시작)는 종료된 에이전트를 같은 작업 폴더에서 다시 실행하는 동작입니다. 지난 대화의 내용까지 이어야 한다면 4단계의 기록 재개 방법을 확인하세요.
확인: 지금 이어 말할 탭이 있는지, 기록을 찾아야 하는지 구분했습니다.
4단계 · 대화가 없으면 기록에서 찾아 재개하기
- 오른쪽 사이드바의 Agents 탭 열기패널 제목이 Agent Session History(에이전트 대화 기록)인지 확인합니다.
- 검색 칸에 작업 이름이나 이전 부탁의 단어 입력현재 작업만 보려면 Workspace, 프로젝트 전체는 Project, 이 컴퓨터의 전체 기록은 All 범위를 선택합니다. 찾지 못하면 Project 또는 All로 넓혀 봅니다.
- 결과 행을 눌러 상세 내용 확인작업 폴더·브랜치·첫 부탁·최근 대화를 읽고 찾던 작업인지 대조합니다.
- 해당 기록의 Resume 선택지원되는 기록은 원래 작업 폴더와 세션으로 새 터미널을 열어 대화를 재개합니다. 이미 같은 작업이 다른 탭에서 진행 중인지 먼저 확인합니다.
확인: 열린 탭의 최근 대화와 작업 폴더가 메모와 일치합니다. 일치하지 않으면 새 지시를 보내기 전에 작업 선택을 다시 확인합니다.
Chat UI로 재개하거나 원격 기록을 보는 경우
대상 기록이 지원하면 Resume in New Native Chat으로 지난 대화를 보여 주는 새 채팅 탭을 열 수 있습니다. Claude는 원래 워크트리에서 재개해야 하며, Codex는 다른 워크트리에서도 재개할 수 있습니다. 구조화된 채팅으로 예약된 대화는 터미널 Resume를 더 이상 제공하지 않습니다. 원격 워크트리에서도 기록을 볼 수 있지만 패널의 Resume 실행은 로컬 워크트리에서만 가능합니다. 원격 재개가 필요하면 기록과 재개 제약을 먼저 확인하세요.
5단계 · 현재 상태를 확인한 뒤 작은 일 하나 이어 하기
안내문 실습을 이어 한다면 아래처럼 확인과 수정 요청을 나누어 보냅니다. 다른 실습을 했다면 파일 경로와 확인할 내용을 실제 작업에 맞게 바꿉니다.
먼저 docs/welcome-practice.md의 현재 내용을 읽어 줘.
지난 대화와 달라진 점, 남은 확인 필요 항목을 설명해 줘.
아직 파일은 바꾸지 마.답변을 읽고 맞는 작업임을 확인한 뒤 “제목 아래에 이 문서의 목적을 한 문장으로 추가해 줘. 기존 시간과 확인 필요 항목은 유지해 줘”라고 요청합니다.
확인: 파일을 다시 열어 요청한 한 문장만 추가되었는지 읽습니다. 끝낸 일·다음 할 일을 다시 메모하면 다음 재개 준비도 끝입니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 기록이 검색되지 않음 | 범위를 All로 넓히고 검색 단어를 줄입니다. 패널의 Refresh Session History로 다시 읽고, 보기 옵션에서 해당 에이전트가 선택됐는지 확인합니다. 기록을 남기지 않는 도구라면 나타나지 않을 수 있습니다. |
| Resume를 누를 수 없음 | 로컬 워크트리를 선택했는지 확인하고 패널에 표시된 이유를 읽습니다. 기록 파일이나 원래 폴더가 없으면 먼저 경로를 확인합니다. 작업 폴더가 사라진 상태에서 재개로 파일이 복구되지는 않습니다. |
| 컴퓨터를 재시작한 뒤 화면만 돌아옴 | 컴퓨터 재시작은 실행 중이던 에이전트를 끝냅니다. 화면·기록이 돌아와도 작업이 계속 실행 중이라는 뜻은 아닙니다. 지원 기록에서 재개한 뒤 현재 파일 상태부터 확인합니다. |
| 잘못된 작업을 연 것 같음 | 수정 요청을 보내지 말고 파일 경로와 최근 부탁을 대조합니다. 맞는 작업을 찾을 때까지 읽기 전용 확인만 합니다. |
Orca 앱을 끝내도 백그라운드 실행 관리 프로그램이 살아 있으면 에이전트는 계속 일하고, 앱을 다시 열 때 같은 프로세스에 연결됩니다. 컴퓨터 재부팅·전원 꺼짐이나 실행 관리 프로그램 종료는 에이전트를 끝냅니다. 레이아웃 복원과 기록 재개는 삭제된 파일 복구나 git 변경 되돌리기를 대신하지 않습니다.
- 작업 이름·파일 경로·다음 할 일을 메모합니다.
- 다시 열면 같은 워크트리와 실제 파일부터 확인합니다.
- 살아 있는 대화에서는 그대로 이어 말하고, 없으면 기록을 찾아 재개합니다.
- 새 요청 전에 현재 상태를 확인합니다. 화면 복원은 파일 복구가 아닙니다.
출처: 로컬 공식 문서 수집본 model/session-restore, agents/session-history, model/quick-open, model/agents-sessions. 가이드 2장 세션 복원·3장 기록. 작업 이름·파일 경로·프롬프트는 연습용 예시입니다.
결과가 틀렸거나 작업이 막혔을 때 다시 진행하기
“안 돼요”에서 멈추지 않고, 기대한 결과와 실제 결과를 나누어 전달해 봅니다. 상태 표시를 먼저 읽고, 수정 요청 후에는 같은 방법으로 다시 확인합니다.
- 기대와 실제 차이를 관찰 가능한 말로 설명합니다.
- 응답 대기·작업 실패·결과 오류를 구분합니다.
- 재시도 후 직접 확인하고, 어려우면 필요한 정보를 모아 도움을 요청합니다.
예상 소요 시간: 15~20분
준비물을 확인한 뒤 따라 하기를 진행하세요. 막히면 막히면에서 같은 증상을 찾습니다. 기본 실습은 시나리오 6의 안내문 제목 한 줄을 고치는 것입니다. 웹 버튼 예시는 선택 참고입니다. 계정·파일 삭제·설정 초기화는 필요하지 않습니다.
준비물과 완료 기준
- 기본 경로: 시나리오 6에서 만든
docs/welcome-practice.md와 같은 워크트리의 에이전트 탭을 사용합니다. - 확인할 대상은 안내문의 맨 위 제목입니다. 실제 오류가 없어도 제목을 “신규 입사자 첫날 안내”로 맞추는 작은 수정 과제로 연습할 수 있습니다. 이미 같은 제목이라면 원하는 제목을 “신규 입사자 첫날 체크리스트”로 정해 아래 양식의 기대한 것도 바꿉니다.
- 기대한 문구와 실제 보이는 문구를 적을 메모. 실습을 위해 일부러 프로그램을 고장 낼 필요가 없습니다.
같은 파일 또는 같은 화면에서 기대한 문구가 보이고, 유지하기로 한 내용도 남아 있는지 직접 확인하면 완료입니다. 해결하지 못한 경우에는 재현 방법과 오류 문구를 모아 도움 요청까지 작성합니다.
따라 하기
1단계 · 먼저 에이전트 상태 읽기
| 표시 | 지금 할 일 |
|---|---|
| 회전 원 · 작업 중 | 탭에 들어가 최근 진행 내용을 읽습니다. 작업이 진행 중인지 확인하고 중복된 수정 요청을 보내지 않습니다. |
| 주황 ? · 나를 기다림 | 탭의 질문을 읽고 답합니다. 허락 요청이라면 무엇을 하려는지 이해한 뒤 결정합니다. |
| 초록 · 완료 | 이제 실제 파일이나 화면을 확인합니다. 완료 표시는 결과가 정확하다는 보증이 아닙니다. |
| 빨강 · 막힘·실패 | 최근 오류 문구를 메모하고 아래 문제 해결 표의 같은 증상을 확인합니다. |
| 회색 · 쉬는 중 | 오래 조용한 상태입니다. 마지막 답을 읽어 작업 결과나 다음 질문이 있는지 확인합니다. |
확인: 질문에 답해야 하는 상황인지, 결과를 고쳐야 하는 상황인지 구분했습니다.
2단계 · 기대한 것과 보이는 것을 적기
기본 실습: 탭 줄의 +에서 welcome-practice.md를 검색해 열고 맨 위 제목을 읽습니다. 아래 양식의 대괄호 부분은 지금 파일에서 본 제목으로 바꿉니다. 대괄호까지 그대로 보내지 않습니다.
대상: docs/welcome-practice.md의 맨 위 제목
기대한 것: 신규 입사자 첫날 안내
실제로 보이는 것: [지금 파일의 제목을 그대로 복사]
확인 방법: 파일을 열고 첫 번째 제목을 읽음
그대로 유지할 것: 오전 10시와 확인 필요 항목 세 가지선택: 문서 대신 웹 버튼 오류로 연습한다면
이 경로는 시나리오 1에서 웹 앱을 실행해 주소를 받은 독자용입니다. 문서 실습과 둘 다 할 필요는 없습니다. 에이전트가 알려 준 실행 주소를 열고, 위 양식을 다음처럼 바꿉니다.
대상: [실제로 연 페이지 주소]의 신청 버튼
기대한 것: 신청하기
실제로 보이는 것: 제출
확인 방법: 페이지를 열고 같은 버튼의 문구를 읽음
그대로 유지할 것: 버튼 위치와 다른 화면 문구주소와 문구는 자기 화면에 맞게 바꿉니다. 클릭 오류라면 어떤 순서로 눌렀을 때 어떤 오류가 나오는지도 적습니다. 이후 단계의 “파일 확인” 대신 같은 페이지와 버튼을 확인하면 됩니다.
확인: 다른 사람이 같은 파일이나 화면을 열어 차이를 확인할 수 있을 만큼 대상과 행동이 구체적입니다.
3단계 · 확인부터 요청하고 수정 범위 정하기
같은 에이전트 탭에 2단계 메모를 붙이고 아래처럼 요청합니다.
위 메모의 대상 파일을 읽고, 기대와 실제가 왜 다른지 먼저 확인해 줘.
아직 파일을 바꾸지 말고 원인과 고칠 범위를 쉬운 말로 설명해 줘.
확인할 수 없는 내용은 추측하지 말고 물어봐.답변의 대상이 내가 확인한 파일·화면과 같은지 읽습니다. 범위가 맞으면 “그 범위로 수정해 줘. 유지할 내용은 바꾸지 말고, 끝나면 바뀐 파일과 다시 확인할 방법을 알려 줘”라고 보냅니다. 설명이 이해되지 않으면 그 부분을 짚어 다시 물어봅니다.
확인: 무엇을 바꿀지 알고 수정 요청을 보냈습니다. 여러 파일 변경을 제안했다면 각 파일이 필요한 이유를 먼저 확인합니다.
4단계 · 같은 확인 방법으로 다시 보기
- 완료 답변 읽기바뀐 파일 경로와 에이전트가 실행한 검사를 확인합니다. 검사를 하지 못했다고 하면 통과한 것으로 간주하지 않습니다.
- 2단계와 똑같이 확인문서는 같은 파일의 첫 제목을 다시 읽습니다. 웹은 같은 주소에서 같은 버튼을 확인합니다. 동작 오류라면 기록해 둔 입력과 클릭 순서를 반복합니다.
- 유지할 내용도 확인안내문의 오전 10시·미정 항목이 그대로 있는지 봅니다. 아직 다르다면 새로 관찰한 결과를 2단계 양식에 적어 다시 요청합니다.
확인: 에이전트의 “고쳤다”는 답뿐 아니라 내가 직접 확인한 결과가 기대와 일치합니다.
5단계 · 어려우면 정보 모아 도움 요청하기
계속 실패하거나 설명을 이해하기 어렵다면 같은 요청을 반복하기보다 아래 내용을 정리합니다. 에이전트에게 정리를 부탁하되 파일을 더 바꾸지 않도록 말합니다.
지금은 더 수정하지 말고 도움 요청용으로 정리해 줘.
- 저장소와 워크트리 이름
- 문제가 나는 파일 경로 또는 페이지 주소
- 재현 순서, 기대 결과, 실제 결과
- 오류 문구, 이미 시도한 방법, 현재 남은 문제
- 바뀐 파일 목록과 추가로 필요한 정보
암호, 토큰, 개인 정보는 포함하지 마.내가 본 내용과 맞는지 읽고 동료에게 전달합니다. Orca 자체 문제라면 Help → Send Feedback(도움말 → 의견 보내기)에서 설명과 스크린숏을 붙일 수 있습니다. 재현이 어려워 로그가 필요하면 Help → Open Logs로 위치를 열 수 있습니다. 첨부 전 계정·프로젝트의 민감한 정보가 들어 있는지 확인합니다.
확인: 해결했다면 재확인 결과를, 미해결이면 도움받을 사람이 재현할 수 있는 설명을 남겼습니다. 파일 변경을 남기는 방법은 시나리오 3으로 이어갑니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| 에이전트 탭이 종료되고 Restart가 보임 | Restart는 같은 작업 폴더에서 에이전트를 다시 실행합니다. 지난 대화까지 이어야 한다면 시나리오 7의 Session History 재개를 확인합니다. 다시 열린 뒤 현재 파일 상태부터 읽게 합니다. |
| 에이전트가 시작되지 않음 | Settings → Agents에서 해당 에이전트가 보이는지 확인합니다. 설치·로그인 점검은 아래 참고를 따릅니다. 오류 내용을 복사하고 모르는 설정을 임의로 바꾸지 않습니다. |
| diff의 내용이 실제 파일과 달라 보임 | diff 도구 막대의 새로 고침 아이콘을 누릅니다. 다시 읽은 변경 화면과 실제 파일을 비교합니다. |
| 브라우저에서 앱이 열리지 않음 | 에이전트에게 “앱이 실행 중인지 확인하고, 이 워크트리의 정확한 접속 주소와 실행 오류를 알려 줘”라고 요청합니다. 예시 주소를 내 프로젝트 주소로 간주하지 않습니다. |
| 로그인·권한 때문에 진행 불가 | 어느 서비스의 어떤 권한이 필요한지 설명을 요청합니다. 로그인 정보 자체를 채팅에 보내지 말고 해당 도구의 로그인 절차로 처리합니다. 권한이 없으면 관리자나 동료에게 오류 설명과 필요한 권한을 전달합니다. |
참고: Orca 밖에서도 에이전트가 실행되는지 점검하기
공식 문제 해결 순서는 일반 터미널에서 같은 에이전트를 실행해 보는 것입니다. Claude Code면 claude, Codex면 codex를 실행합니다. Orca 밖에서도 실패하면 에이전트 설치·로그인을 먼저 점검하고, 밖에서는 되는데 Orca에서만 실패하면 Settings → Agents에서 프로그램을 찾는 경로(PATH)를 확인합니다. 터미널 사용이 익숙하지 않다면 동료에게 위 오류 정리를 전달해 함께 확인하세요. 에이전트별 준비: 지원 에이전트.
- 작업 중·응답 대기·실패·완료를 먼저 구분합니다.
- “안 됨” 대신 대상·기대·실제·재현 순서를 적습니다.
- 작게 수정한 뒤 같은 방법으로 직접 확인합니다.
- 어려우면 바뀐 파일과 오류를 정리해 도움을 요청합니다.
출처: 로컬 공식 문서 수집본 model/agents-sessions, troubleshooting, agents/session-history, editing/file-explorer, model/quick-open, agents/claude-code, agents/codex. 가이드 1장 문제 해결. 제목·버튼 문구·파일 경로·프롬프트는 연습용 예시입니다.
원격 서버에서 작업하기 — 내 노트북 대신 SSH 서버에 맡기기
빌드가 오래 걸리거나 더 힘센 컴퓨터가 필요할 때, 에이전트를 SSH(다른 컴퓨터에 안전하게 접속하는 방법) 서버에서 돌립니다. 편집기와 변경 비교는 내 노트북 화면에 그대로 있고, 실제 작업은 서버에서 일어납니다.
- Orca에 SSH 접속 대상을 추가하고 연결을 시험합니다.
- 워크트리를 내 노트북(Local)이 아닌 서버에 만들고 에이전트를 맡깁니다.
- 연결이 끊겼을 때 무슨 일이 일어나는지 이해하고 상태 표시를 읽습니다.
예상 소요 시간: 20~30분 (서버 접속 정보가 준비된 경우)
준비물과 완료 기준
- SSH로 접속할 수 있는 서버 1대의 정보: 주소(host), 사용자 이름(user), 포트(port), 필요하면 키 파일(identity file). 이미
~/.ssh/config에 적어 둔 서버라면 거기서 불러올 수 있습니다. - 저장소로 작업한다면 서버에 git이 설치되어 있어야 합니다.
- 시나리오 1을 마쳐 워크트리 만들기와 에이전트 실행에 익숙한 상태.
서버를 대상으로 만든 워크트리에서 에이전트에게 작은 부탁 하나를 맡기고, 내 노트북의 변경 비교 화면에서 결과를 확인하면 완료입니다.
따라 하기
1단계 · SSH 대상 추가하기
- Settings → SSH 열기설정(Settings)의 SSH 화면입니다.
- Add Target 누르기접속 정보를 넣는 창이 열립니다.
- host · user · port · 키 파일 입력또는 같은 창에서 OpenSSH config 선택기를 열어
~/.ssh/config의 서버 하나를 고르면 칸이 채워집니다. 이미 Orca에 저장된 서버에는 In Orca 표시가 붙습니다. - Test로 연결 시험 → Save키에 암호(passphrase)가 걸려 있으면 처음에 한 번 물어봅니다.
확인: Test가 성공하고 목록에 서버가 저장되었습니다. 입력하다가 창 밖을 실수로 눌러도 입력 내용은 사라지지 않습니다. 버리려면 Escape·Cancel·×를 누릅니다.
2단계 · 처음 접속할 때 서버 지문 확인하기
기본 설정에서는 처음 접속하는 서버의 지문(서버가 진짜 그 서버인지 확인하는 고유 값)을 보여 주고 기억합니다. 다음부터는 기억한 지문과 같으면 조용히 접속합니다.
지문이 바뀌었다면 Orca는 암호나 키 암호를 묻기 전에 접속을 거부합니다. 서버를 일부러 새로 만든 경우에만 새 지문을 확인한 뒤 오류 안내의 복구 방법을 따릅니다.
확인: 지문 경고 없이 접속되었거나, 처음 접속이라 지문을 확인했습니다.
3단계 · 서버에 워크트리 만들기
- 저장소를 Orca에 추가할 때 위치를 SSH 대상으로 선택저장소가 아니라 서버의 아무 폴더를 파일 선택기에서 바로 열 수도 있습니다.
- 워크트리를 만들 때 Local 대신 SSH 대상 선택Orca가 서버에서
git worktree add를 실행해 워크트리를 만듭니다.
확인: 사이드바의 워크트리에 SSH 상태 표시(칩)가 보입니다. 초록이면 연결된 상태입니다.
4단계 · 에이전트에게 맡기고 결과 확인하기
서버 워크트리에서 평소처럼 에이전트를 실행하고 작은 부탁을 보냅니다. 에이전트는 내 노트북이 아니라 서버에서 실행됩니다.
이 저장소의 README를 읽고, 처음 보는 사람이 알아야 할 점을 세 줄로 정리해 줘.
파일은 아직 바꾸지 마.파일을 바로 고쳐도 저장은 서버의 파일에 반영됩니다. 변경 비교 확인·커밋·푸시는 시나리오 3처럼 내 노트북 화면에서 평소대로 합니다.
확인: 에이전트 답을 받았고, 파일을 바꿨다면 변경 비교 화면에서 그 내용을 볼 수 있습니다.
5단계 · 연결이 끊겨도 당황하지 않기
노트북이 잠들거나 Wi-Fi가 끊겨도 서버의 에이전트는 계속 일합니다. Orca가 다시 연결되면 터미널을 다시 붙여 줍니다. 끊긴 동안 입력한 키는 연결이 돌아오면 순서대로 한 번씩 전달됩니다.
확인: 상태 칩이 초록으로 돌아오고 에이전트 탭의 진행 내용이 이어져 있습니다.
프록시·점프 호스트·다단계 인증이 필요한 서버
Settings → SSH에서 대상을 편집하고 Advanced Connection을 펼치면 프록시, 점프 호스트, 연결 재사용 설정을 바꿀 수 있습니다. 인증 코드(MFA)를 묻는 서버는 Orca가 질문을 그대로 보여 주고 답을 전달합니다. 키 암호는 Orca를 켜 둔 동안 메모리에 보관되고 Orca를 닫으면 지워집니다. 자세한 내용은 고급 연결 옵션과 인증.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| Test가 실패함 | host·user·port·키 파일을 다시 확인합니다. 저장소 작업이라면 서버에 git이 설치되어 있는지 서버 관리자에게 확인합니다. |
| 서버 지문이 달라 접속이 거부됨 | 서버를 일부러 새로 만든 경우가 아니라면 접속하지 말고 서버 관리자에게 알립니다. 새로 만든 서버라면 새 지문을 확인한 뒤 오류에 나온 복구 방법(known_hosts 불일치면 안내된 ssh-keygen -R 명령)을 따릅니다. |
| 처음 연결에서 서버 준비가 실패함 | 첫 연결 때 Orca는 서버에 자기 실행 환경(관리형 Orca 서버)을 설치합니다. 지원하지 않는 OS·CPU, 실행이 막힌 홈 폴더, 포트 전달을 거부하는 SSH 서버면 실패합니다. 오류에 적힌 이유를 읽고 Settings → SSH Hosts에서도 확인합니다. 다운로드가 막혀 있으면 오류의 Use a Node.js mirror…를 사용할 수 있습니다. |
| 서버에서 띄운 웹 화면을 내 브라우저로 보고 싶음 | 오른쪽 사이드바의 Ports 탭(Cmd+Shift+I, macOS)에서 서버가 열어 둔 포트를 찾아 한 번 눌러 내 쪽으로 연결합니다. |
| Orca를 켤 때마다 서버에 자동으로 붙는 게 싫음 | 그 서버를 편집해 Advanced → Reconnect on launch를 끕니다. 끄면 Connect를 누를 때까지 연결하지 않습니다. |
Orca 데스크톱 앱을 닫아도 서버의 터미널 세션은 서버 쪽에서 계속 살아 있습니다. 앱을 다시 열고 서버에 다시 연결하면 탭과 터미널 기록이 그대로 돌아옵니다.
- Settings → SSH에서 서버를 추가하고 Test로 시험합니다.
- 워크트리를 만들 때 Local 대신 SSH 대상을 고르면 워크트리와 에이전트가 서버에서 돌아갑니다.
- 변경 비교·커밋·푸시는 내 노트북 화면에서 평소대로 합니다.
- 끊겨도 서버의 에이전트는 계속 일하고, 다시 연결되면 이어집니다. 상태 칩 색으로 확인합니다.
출처: 로컬 공식 문서 수집본 ssh, recipes/remote-worktrees. 가이드 8장 SSH 대상 추가·SSH 대상 사용·연결 상태. 프롬프트는 연습용 예시입니다.
이슈에서 바로 작업 시작하기 — Jira · Linear 이슈로 워크트리 만들기
팀이 할 일을 Jira나 Linear 같은 이슈(할 일 카드)로 관리한다면, Orca 안에서 그 카드를 찾아 바로 워크트리를 만들 수 있습니다. 작업과 카드가 서로 연결되어 무엇 때문에 한 일인지 잃어버리지 않습니다.
- Jira 또는 Linear를 Orca에 연결합니다.
- Tasks 화면에서 이슈를 찾고, 그 이슈로 워크트리를 만들어 에이전트에게 맡깁니다.
- 이슈 상태를 Orca 안에서 바꾸고, 끝나면 PR까지 엽니다.
예상 소요 시간: 15~25분 (토큰 발급 포함)
준비물과 완료 기준
- 팀이 쓰는 이슈 도구 계정 하나와 연결용 토큰(비밀번호 대신 쓰는 접속 열쇠).
- Linear: Linear → Settings → API에서 만든 개인 API 토큰.
- Jira Cloud: 사이트 주소(예:
https://example.atlassian.net), Atlassian 이메일, id.atlassian.com → Security → API tokens에서 만든 API 토큰. - Jira 자체 설치(Server / Data Center): Jira 주소와 개인 액세스 토큰(또는 오래된 버전이면 사용자 이름·암호).
- 연습해도 되는 작은 이슈 1개. 없으면 연습용으로 하나 만듭니다.
- 시나리오 1을 마쳐 워크트리와 에이전트에 익숙한 상태.
이슈에서 만든 워크트리 카드에 이슈가 연결되어 보이고, 에이전트 결과를 확인한 뒤 이슈 상태를 한 번 바꾸면 완료입니다. PR까지 여는 것은 저장소 권한이 있을 때만 합니다.
따라 하기
1단계 · 이슈 도구 연결하기
- 사이드바의 Tasks 열기 → 소스 선택에서 JiraJira는 연결 전에도 GitHub·Linear 옆에 보입니다.
- Connect Jira 누르기Connect Jira site 창이 열립니다.
- Cloud 또는 Self-hosted 선택 후 정보 입력Cloud: 사이트 주소·Atlassian 이메일·API 토큰. Self-hosted: Jira 주소와 인증 방식(개인 액세스 토큰 권장).
- ConnectOrca가 정보를 확인하고 사이트를 불러옵니다. 사이트를 여러 개 연결할 수도 있습니다.
- Settings → Integrations → Linear 열기설정의 연동(Integrations) 화면입니다.
- 개인 API 토큰 붙여 넣기Linear → Settings → API에서 만든 토큰입니다.
- 보고 싶은 팀 선택선택한 팀의 이슈가 Tasks에 나타납니다.
확인: Tasks 화면에 내 이슈 목록이 보입니다. GitHub·Linear·Jira를 켜 두면 한 목록에 함께 보입니다.
2단계 · 연습할 이슈 찾기
Tasks의 검색 칸에 단어를 입력합니다. Jira는 JQL(Jira 전용 검색 문법)을 몰라도 평범한 단어로 찾을 수 있고, ABC-1처럼 이슈 번호 모양으로 입력하면 그 이슈를 먼저 찾습니다.
이슈를 열면 옆 창에 설명·댓글·담당자 등이 보입니다. 맡길 일이 분명한지 읽어 봅니다.
확인: 연습할 이슈 하나를 골라 내용을 읽었습니다.
3단계 · 이슈로 워크트리 만들기
이슈에서 워크트리를 만들면 Orca가 작업 이름을 미리 채우고 이슈를 연결합니다.
- Linear: 워크트리 만들기 창(workspace composer)이 열리고, 이슈 ID가 연결됩니다. Linear가 그 이슈의 브랜치 이름을 알려 주면 그 이름을 그대로 씁니다.
- Jira: 작업 이름이 미리 채워지고 이슈가 연결됩니다. Create workspace 창의 이름 칸에 Jira 이슈 주소(
https://…/browse/ABC-123)를 붙여 넣거나, 칸을 Jira 검색으로 바꿔 이슈를 골라도 됩니다.
확인: 새 워크트리 카드에 이슈 번호와 제목이 보입니다(Jira는 View on Jira 링크).
4단계 · 에이전트에게 이슈 내용으로 맡기기
새 워크트리에서 에이전트를 실행하고 이슈 내용을 바탕으로 부탁합니다. 처음에는 계획부터 받습니다.
이 워크트리는 이슈 ABC-123 작업이야. 이슈 내용을 바탕으로
1. 무엇을 바꿔야 하는지
2. 어느 파일을 볼 건지
를 먼저 정리해 줘. 파일은 아직 바꾸지 마.Linear 이슈에서 에이전트를 실행하면 이슈 설명·댓글·하위 이슈에 들어 있는 이미지도 함께 전달되어, 화면 캡처를 따로 붙여 넣지 않아도 됩니다.
확인: 에이전트의 계획이 이슈 내용과 맞습니다. 맞으면 진행을 부탁하고, 시나리오 3처럼 결과를 검토합니다.
5단계 · 이슈 상태 바꾸고 PR 열기
- 이슈 상세 화면에서 상태 바꾸기Jira는 가능한 전환(transition)으로 상태·우선순위·담당자를 바꾸고 댓글을 남길 수 있습니다. Linear는 상태·담당자·우선순위·라벨·추정치를 바꿉니다.
- 결과를 커밋·푸시하고 Source Control에서 Create PR저장소 권한이 있을 때만 합니다. 열린 PR은 워크트리에 연결되어 리뷰 상태가 함께 보입니다. 자세한 순서는 커밋 · 푸시 · PR 만들기.
확인: 이슈 상태가 바뀌었고, PR을 열었다면 워크트리 옆에 PR 상태가 보입니다.
막히면
| 증상 | 해 볼 것과 확인 기준 |
|---|---|
| Jira 검색이 이상한 결과를 줌 | JQL처럼 보이는 검색을 Jira가 거절하면 Orca는 대신 글자 검색 결과를 보여 주고, 거절 이유는 Details 뒤에 둡니다. 평범한 단어나 이슈 번호로 다시 찾습니다. |
| 이미 작업 중인 이슈인지 모르겠음 | Linear 목록의 Has Workspace 보기를 켜면 이미 워크트리가 연결된 이슈만 보입니다. 그 행을 누르면 연결된 작업이 열립니다. |
| 워크트리에 다른 이슈를 연결하고 싶음 | 워크트리 카드의 Edit Worktree Details에서 Issue 칸을 바꿉니다. GitHub와 Linear는 이 칸 하나를 같이 쓰므로, 새로 저장하면 이전 연결이 바뀝니다. |
| 워크트리를 만들었는데 Linear 상태가 안 바뀜 | 워크트리를 만들 때 Linear 이슈를 "In Progress"로 옮기는 기능은 팀마다 따로 켜야 합니다. 꺼져 있으면 5단계처럼 직접 바꿉니다. |
| Jira를 쓰지 않는데 목록에 보임 | Settings → Tasks에서 소스 선택 목록에서 숨길 수 있습니다. |
Orca는 저장소마다 마지막에 쓴 이슈 소스(GitHub·Linear·Jira)를 기억해, 다음에 열 때 그 소스를 먼저 보여 줍니다.
- Jira는 Tasks → Connect Jira, Linear는 Settings → Integrations에서 토큰으로 연결합니다.
- 이슈에서 워크트리를 만들면 이름이 채워지고 이슈가 연결됩니다.
- 에이전트에게는 계획부터 받고, 결과를 검토한 뒤 진행합니다.
- 이슈 상태는 Orca 안에서 바꾸고, 권한이 있으면 Create PR로 PR을 엽니다.
출처: 로컬 공식 문서 수집본 review/jira, review/linear, review/github. 가이드 6장 Jira 연동·Linear 연동·호스팅 리뷰. 이슈 번호·제목·프롬프트는 연습용 예시입니다.