Claude Code와 Codex를 터미널 두 개에서 실행하면 각 세션이 어느 브랜치와 파일을 수정하는지 확인해야 한다. 두 에이전트가 같은 작업 디렉터리를 사용하면 한쪽의 미완성 변경이 다른 쪽 테스트에 들어간다. 브랜치를 전환하는 순간 수정 파일이 섞일 수도 있다.
Orca를 설치한 목적은 병렬 에이전트의 작업 공간과 diff를 한 화면에서 확인하는 데 있었다. Orca는 여러 CLI 에이전트를 각 Git worktree에서 실행하고 터미널, 브랜치, 변경 상태를 묶어 보여 준다. 회사 PC에서 Claude Code와 Codex가 독립된 worktree를 사용하는 것까지 확인했다.
공식 저장소는 Orca가 터미널에서 실행되는 CLI 에이전트를 지원한다고 설명한다. parallel worktree와 diff 주석, 작업 상태 추적이 주요 기능이다. 도구가 분리된 폴더를 만들어도 병렬화할 업무와 병합 순서는 사용자가 설계해야 한다.
worktree가 분리하는 상태
Git worktree는 하나의 저장소 객체를 공유하면서 별도 작업 디렉터리와 인덱스를 만든다. 기능 구현과 검토가 각 브랜치에서 진행될 수 있다.
git worktree add ../project-review -b review/agent-output
git worktree list
에이전트 A가 feature/auth 브랜치의 파일을 수정해도 에이전트 B의 review/auth 작업 디렉터리는 바뀌지 않는다. B는 기준 브랜치에서 테스트를 조사하거나 A가 만든 커밋을 선택해 검토할 수 있다.
worktree는 다음 항목을 분리한다.
- 작업 파일과 Git 인덱스
- 현재 체크아웃한 브랜치
- 에이전트가 만든 unstaged 변경
- 해당 폴더에서 생성한 빌드 결과
Git 객체와 저장소 설정은 공유한다. 한 worktree에서 만든 커밋은 다른 worktree에서도 볼 수 있다. 공통 remote와 hook, Git 설정이 영향을 줄 수 있으므로 완전한 보안 격리로 보면 안 된다.
작업을 열기 전에 소유권을 적는다
Orca에서 새 worktree를 만들기 전 작업 카드에 수정 범위를 적는다.
목표: 로그인 만료 시 작성 중인 폼을 보존한다
수정 허용: app/login/**, tests/login/**
읽기 전용: lib/session/**
수정 금지: migrations/**, deployment/**
완료 검사: typecheck, login tests, production build
병합 순서: session 계약 확인 후 UI 변경
승인자: ck
파일 소유권은 에이전트의 물리적 접근을 막지 않는다. diff에서 작업 범위를 벗어난 변경을 찾는 판정 기준이다. 공유 타입을 바꿔야 한다면 에이전트가 작업을 멈추고 이유와 영향 파일을 보고하게 한다.
두 카드가 같은 공통 파일을 수정하면 병렬 작업으로 열지 않는다. 인터페이스를 먼저 결정하고 별도 커밋으로 합친 뒤 각 작업을 시작한다. 작업 도중 공통 계약이 바뀌면 다른 세션을 중지하고 기준 브랜치를 갱신한다.
파일 충돌과 설계 충돌은 다르다
worktree는 같은 파일을 동시에 덮어쓰는 일을 막는다. 논리 충돌은 남는다. 한 에이전트가 User 타입에 필드를 추가하고 다른 에이전트가 기존 타입을 전제로 API 응답을 만들 수 있다. Git이 두 변경을 자동 병합해도 런타임 동작은 깨질 수 있다.
병렬 실행 전에 다음 계약을 고정한다.
- 공유 타입과 API 요청·응답
- 데이터베이스 마이그레이션 순서
- 오류 코드와 재시도 정책
- 환경 변수와 기본값
- 테스트 fixture와 기준 출력
- 병합 순서와 최종 결정자
설계 충돌은 diff 크기로 찾기 어렵다. 두 브랜치를 합친 뒤 전체 타입 검사와 통합 테스트를 실행해야 한다. 개별 worktree의 성공 로그가 합쳐진 시스템의 성공을 보장하지 않는다.
의존성과 캐시 비용을 계산한다
Git 객체를 공유해도 각 작업 디렉터리는 소스 파일을 가진다. Node 프로젝트에서 worktree마다 node_modules와 .next, 테스트 캐시를 만들면 디스크 사용량이 늘어난다. 설치 시간과 빌드 자원도 동시에 사용한다.
작업을 열기 전에 다음 값을 확인한다.
git worktree list
du -sh ../project-*
패키지 매니저가 안전하게 지원하는 공유 캐시를 사용할 수 있지만 worktree 사이에 빌드 출력 폴더를 임의로 공유하지 않는다. 한 세션의 생성물이 다른 브랜치 테스트에 들어가면 결과를 믿기 어렵다.
동시 빌드 수는 CPU와 메모리에 맞춘다. 여러 에이전트가 같은 테스트 데이터베이스와 포트를 사용하지 않도록 인스턴스 이름과 포트를 나눈다. 외부 API 호출은 비용 상한과 rate limit도 고려한다.
비밀 값은 worktree와 함께 복사하지 않는다
새 작업 폴더에서 에이전트를 실행하려고 .env.local을 복사하기 쉽다. 파일 안에 운영 키와 서비스 역할 토큰이 있으면 각 세션이 같은 권한을 갖는다.
검토 전용 worktree에는 테스트용 자격증명만 둔다. 외부 쓰기가 필요 없는 작업은 네트워크와 비밀 값 없이 실행한다. 운영 환경 변수는 Git에 넣지 않고, 로그와 프롬프트에도 출력하지 않는다.
에이전트가 git status와 git diff를 보여 줄 때 untracked 비밀 파일의 내용을 읽지 않게 한다. 백업 도구도 .env* 제외 규칙을 확인한다. worktree 삭제 전에 로컬 자격증명과 생성 파일이 남는지 살핀다.
Orca에서 확인하기 쉬웠던 부분
에이전트별 터미널과 worktree 상태를 한 화면에서 보면 현재 작업자를 찾는 시간이 줄었다. 공식 저장소가 설명하는 diff 주석 기능은 특정 줄에 검토 의견을 남기고 해당 에이전트에 다시 전달하는 데 맞는다.
나는 상태를 다음 순서로 본다.
- 에이전트가 어떤 목표와 브랜치에서 시작했는지 확인한다.
- 실행 중인 명령과 수정 파일을 본다.
- 완료 보고 뒤 전체 diff와 untracked 파일을 읽는다.
- 검사 로그가 현재 커밋에서 실행됐는지 확인한다.
- 병합 전에 별도 검토 세션의 발견 사항을 처리한다.
한 화면에 많은 에이전트를 추가할 수 있어도 내가 검토할 수 있는 diff 수는 제한돼 있다. 작업 카드가 대기 상태로 쌓이면 새 에이전트를 시작하지 않는다. 완료된 작업의 검토와 병합이 병목이면 실행 수를 줄인다.
구현과 조사에 다른 권한을 준다
첫 시험에서는 기능 구현, 회귀 조사, 문서 검토를 분리할 수 있다.
| worktree | 작업 | 쓰기 범위 | 결과 |
|---|---|---|---|
| feature | 기능 구현 | 지정한 소스와 테스트 | 커밋과 검사 로그 |
| regression | 테스트와 회귀 경로 조사 | 테스트 초안 또는 읽기 전용 | 발견 사항 문서 |
| docs-review | 문서와 마이그레이션 검토 | 문서만 | 절차와 위험 목록 |
공유 코드는 feature 작업만 수정한다. regression 세션은 테스트 초안을 별도 커밋으로 만들 수 있지만 제품 코드를 고치지 않는다. docs-review는 외부 데이터베이스에 마이그레이션을 적용하지 않고 dry-run 절차를 검토한다.
역할별 권한을 나누면 에이전트의 결과를 합칠 방법도 분명해진다. 기능 커밋을 먼저 검토하고 회귀 테스트를 적용한 뒤 문서를 갱신한다. 세 작업을 동시에 끝내는 것보다 증거를 순서대로 합치는 데 초점을 둔다.
병합은 새 검증 단계다
각 worktree에서 검사를 통과했어도 기준 브랜치에 합친 뒤 다시 실행한다.
git diff --check
npm run typecheck
npm test
npm run build
병합 diff에는 개별 브랜치에서 보이지 않던 충돌 해결 코드가 들어갈 수 있다. 데이터베이스 마이그레이션과 외부 배포는 로컬 검사가 끝난 뒤 별도 승인으로 진행한다.
문제가 생기면 어느 커밋이 원인인지 좁힐 수 있도록 작업별 커밋을 유지한다. 여러 에이전트의 변경을 한 커밋으로 섞지 않는다. 롤백할 때 기능과 문서, 테스트의 의존 관계도 확인한다.
작업이 끝나면 worktree를 정리한다
병합과 검증이 끝난 worktree는 변경 상태를 확인한 뒤 제거한다.
git status --short
git worktree list
git worktree remove ../project-review
git worktree prune
uncommitted 파일이 있으면 제거 전에 필요한 결과인지 판단한다. 강제 삭제 옵션을 습관적으로 사용하지 않는다. 브랜치 삭제도 병합과 백업을 확인한 뒤 별도로 진행한다.
정리 기록에는 worktree 경로와 브랜치, 병합 커밋, 보관한 artifact를 남긴다. 사용하지 않는 의존성과 비밀 파일이 로컬에 오래 남는 일을 줄일 수 있다.
Orca는 병렬 에이전트의 터미널과 diff, worktree 상태를 한곳에 모아 준다. 파일 공간이 분리돼도 작업 의존성과 설계 결정, 검토 책임은 사용자에게 남는다. 나는 동시 실행 수를 늘리기 전에 작업 카드와 파일 소유권, 병합 게이트를 먼저 준비한다.