Sharkly가 머지 충돌 없이 에이전트를 병렬로 실행하는 방법

같은 체크아웃에서 코딩 에이전트 두 개를 돌려 보면, 한 시간 안에 그 실패 모드를 직접 겪게 된다. 한 에이전트가 편집 중인데 다른 에이전트가 브랜치를 전환한다. 스테이징된 변경 사항이 자기 것이 아닌 커밋에 섞여 사라진다. 다른 에이전트가 절반만 고쳐 놓은 파일을 기준으로 테스트가 통과한다. 이 중 어느 것도 모델의 잘못이 아니다. git 워킹 트리는 공유 가변 상태이고, 조율 없이 공유 상태를 변경하는 두 프로세스는 결국 그것을 망가뜨리게 되어 있다.

표준 해법은 잘 알려져 있다. 각 에이전트에 자체 워킹 트리를 주는 것이다. Git worktree를 쓰면 하나의 저장소가 여러 개의 체크아웃 디렉터리를 동시에 제공할 수 있어서, 병렬 브랜치가 디스크상의 같은 파일을 건드리는 일이 없다. 많은 팀이 이를 직접 스크립트로 처리하는데, AI 코딩 에이전트와 함께 git worktree 활용하기 가이드에서 바로 그 DIY 설정을 다룬다.

이 글은 다른 경로에 관한 이야기다. 격리, 디렉터리 준비, 동시성 상한, 정리를 셸 스크립트가 아니라 플랫폼이 처리하면 어떻게 되는지를 살펴본다.

TL;DR

Sharkly는 연결된 Computer에서 모든 Task 실행에 자체 격리된 디렉터리를 부여하는 방식으로 병합 충돌 없이 AI 에이전트를 병렬로 실행한다. 해당 Computer의 로컬 서비스가 대기열에 들어온 각 실행을 받아서, 태스크 디렉터리를 준비하고(저장소 기반 작업이라면 실행마다 별도의 git worktree를 생성), 선택된 Runtime을 시작한 뒤 진행 상황, 추적 이벤트, 결과를 Task로 스트리밍한다. Agent와 Computer의 동시성 한도가 동시에 실행되는 개수를 제한하며, 아무것도 스스로 병합되지 않는다. 결과는 Task로 돌아가고, 사람이 변경 사항을 검토한 뒤 병합과 릴리스 단계를 결정한다. 에이전트는 워킹 트리를 공유하지 않으므로 병렬 Task가 서로의 변경 사항을 덮어쓸 수 없다.

Sharkly가 막고자 하는 실패 모드

에이전트가 하나의 체크아웃을 공유할 때 무엇이 잘못되는지 정확히 짚고 넘어갈 필요가 있다. 각 증상이 수정 사항의 한 조각에 대응하기 때문이다.

브랜치 상태는 워킹 트리 단위로 전역이기 때문에, 에이전트 A가 자기 브랜치를 체크아웃하는 순간 실행 중인 에이전트 B의 파일이 그 아래에서 바뀌어 버린다. 인덱스도 전역이라 git add와 git commit이 서로 다른 태스크의 작업을 뒤섞는다. 추적되지 않는 상태도 충돌한다. 한 실행의 빌드 산출물과 의존성 설치가 다른 실행의 테스트 결과를 오염시킨다. 게다가 정리 부채가 쌓인다. 앞의 세 가지 문제를 피하려고 임시로 만든 저장소 복사본은 누군가 그 존재를 기억해 낼 때까지 디스크에 남아 있기 때문이다.

공유 디렉터리 하나로는 언제나 에이전트 하나만 안전하게 실행할 수 있다. tmux 패널과 규율로 이 문제를 버티고 있다면, 여러 Claude Code 에이전트를 병렬로 실행하기 글에서 그 한계가 왜 이렇게 빨리 찾아오는지 다룬다.

실행 스택: Agent, Computer, Runtime, Task

Sharkly는 Claude Code나 Codex 같은 실행 도구를 대체하지 않는다. 팀이 이미 쓰고 있는 도구 주위에 공유 Task, Computer, 컨텍스트, 제어, 리뷰 계층을 더한다. 이런 계층적 위치가 병렬 실행의 작동 방식을 결정한다. Sharkly의 역할은 코드를 작성하는 것이 아니라 실행을 조율하는 것이기 때문이다.

네 가지 역할이 작업을 나눠 맡고, 각각 정확히 하나의 임무를 갖는다.

• Agent는 작업을 어떻게 처리할지 정의한다. 지침, Skills, 저장소, 실행 설정이 여기에 속한다. Agent는 실행 호스트가 아니다.
• Computer는 호스트와 로컬 리소스를 제공한다. 로컬 머신, 원격 서버, 컨테이너 또는 지원되는 클라우드 호스트가 될 수 있다. 연결 방법은 자매 글인 Sharkly의 Computer에서 다룬다.
• Runtime은 실제 에이전트 세션을 수행한다. 해당 Computer에 설치된 구체적인 도구로, Claude Code, Codex, Gemini CLI 같은 것이다.
• Task는 팀을 위한 공유 기록으로 남는다. 목표, 상태, 논의, 실행 추적, 결과가 여기에 담긴다.

이들을 하나로 묶는 것은 Computer에서 돌아가는 작은 로컬 서비스다. 이 서비스는 Computer를 등록하고, 설치된 Runtime을 감지하고, 대기열에 들어온 실행을 받아서, 실행마다 태스크 디렉터리를 준비하고, Runtime을 시작한 뒤 결과를 다시 보고한다. 서버로 연결을 시작하는 쪽이 바로 이 서비스이므로, 일반적인 구성에서는 인바운드 포트가 필요 없다.

이런 분리가 있기에 병렬 실행을 감당할 수 있다. 작업 디렉터리를 Agent가 고르는 것이 아니라 로컬 서비스가 실행마다 준비하기 때문에, 같은 Computer에서 같은 저장소를 대상으로 지정된 두 Agent가 서로의 파일을 전혀 보지 않고 작업할 수 있다. Agent 구성 방법은 Sharkly의 Agent를 참고하자.

실행이 시작되면 벌어지는 일

Task를 Agent에 할당하고 Backlog에서 꺼내면, Sharkly는 실행 준비 상태를 확인하고, 실행 가능한 작업을 대기열에 넣은 뒤 선택된 Computer로 디스패치한다. 그다음부터는 로컬 서비스가 맡는다. Runtime이 시작되기 전에 동시성 여력을 기다려야 할 수도 있고, 격리된 임시 디렉터리를 준비하거나 비어 있는 지정 디렉터리를 기다려야 할 수도 있으며, 설정된 저장소를 가져오고, 허용된 환경 변수를 적용하고, Runtime 호출을 구성해야 할 수도 있다.

그제야 Runtime이 시작된다. 실행은 명시적인 상태를 거쳐 간다. Queued, Dispatched, Waiting for local directory, Running을 지나 마지막으로 Completed, Failed, Canceled 중 하나가 된다. 이 상태들은 Task의 실행 로그에 나타나므로, “왜 아직 아무 일도 안 일어나지?”라는 질문에 추측 대신 확인 가능한 답이 생긴다. 동시성 한도가 꽉 차서 Queued에 머무는 실행과, 로컬 디렉터리를 기다리느라 Waiting for local directory에 머무는 실행은 서로 다르게 보인다. 그 차이가 어떤 손잡이를 돌려야 하는지 알려 준다.

없는 것에도 주목하자. 어느 시점에도 Agent가 어디서 실행할지 결정하지 않는다. Agent는 지침을 가져오고, 인프라가 격리를 가져온다.

격리된 worktree: Temporary 모드의 동작 방식

Agent는 두 가지 작업 디렉터리 모드를 지원하며, 병렬 작업을 위해 만들어진 모드가 Temporary 모드다. 각 Task는 격리된 디렉터리를 받고, 저장소 기반 작업이라면 로컬 서비스가 캐시된 저장소 데이터를 이용해 실행마다 별도의 git worktree를 준비할 수 있다.

이 한 문장에 충돌 방지에 관한 모든 이야기가 담겨 있다. worktree는 기본 저장소 객체는 공유하면서 각 실행에 자체 체크아웃 디렉터리와 자체 브랜치 상태를 제공한다. 앞서 본 네 가지 실패 모드는 구조적으로 사라진다. 공유 브랜치 포인터도, 공유 인덱스도, 공유 빌드 산출물도 없고, 플랫폼이 나중에 정리할 수 있는 디렉터리만 남는다. worktree는 새로 클론하는 대신 캐시된 데이터에서 만들어지므로 시작 비용도 합리적으로 유지되지만, 저장소를 새로 고치려면 실행 중에 네트워크 접근이 필요할 수 있다.

문서는 이 모드를 언제 써야 하는지 분명히 밝히고 있다. Temporary 모드는 병렬 코드 변경과, 여러 Task가 동시에 같은 코드베이스를 수정할 수 있는 모든 상황에 권장된다.

한 가지 경계는 분명히 해 둘 만하다. 격리는 워킹 트리 충돌을 막을 뿐, 의미적 충돌까지 막아 주지는 않는다. 두 Task가 같은 함수를 각자 다시 작성하면 두 실행 모두 자기 worktree에서 깔끔하게 끝나지만, 겹치는 부분은 결국 사람이 리뷰 단계에서 조정해야 한다. 이 문제의 해법은 같은 오후에 같은 코드를 겨냥하지 않도록 Task 범위를 잡는 것이다. 인프라가 아니라 기획의 결정이다.

격리가 오히려 잘못된 선택일 때: Specified 모드

두 번째 모드가 존재하는 이유는 실행마다 새 디렉터리를 만드는 것이 공짜가 아니기 때문이다. Specified 모드에서 Agent는 풀에 설정된 하나의 절대 로컬 디렉터리 안에서 실행되며, 그곳에 이미 있는 저장소, 의존성, 캐시를 재사용한다. 이 모드는 로컬 Computer에서만 사용할 수 있다.

이 맞바꿈에는 확실한 결과가 따른다. 지정 디렉터리는 한 번에 하나의 실행만 처리하며, 설정된 디렉터리가 모두 사용 중이면 다음 실행은 기다린다. Specified 모드에서 여러 Task를 동시에 실행해야 하는 Agent는 풀에 여러 디렉터리를 두어야 한다.

격리는 준비 비용을 치르고 안전을 얻고, 재사용은 직렬화 비용을 치르고 속도를 얻는다. Sharkly는 이를 Agent별로 명시적으로 선택하게 하는데, 이는 망가진 워킹 트리에서 뒤늦게 그 맞바꿈을 발견하는 것보다 훨씬 낫다.

동시성 한도: 병렬이되, 한계 안에서

무제한 병렬성은 그 자체로 실패 모드다. 모든 동시 실행은 CPU, 메모리, 디스크, 모델 제공자 용량, 저장소 대역폭을 소비한다. 노트북 한 대에서 여덟 개의 에이전트가 서로 뒤엉키면, 세 개가 여유 있게 도는 것보다 결과가 나쁘다.

Sharkly는 두 수준에서 동시성을 제한한다. Computer는 호스트로서 자체 태스크 동시성 한도를 갖고, 각 Agent는 병렬 실행 Task 최대 개수와 Task별 타임아웃을 갖는다. 기본값은 보수적이다. Temporary 모드의 Agent는 Computer 한도의 50퍼센트를 받고, Specified 모드의 Agent는 설정된 디렉터리 수만큼 슬롯을 받는다. 디렉터리 수보다 높게 설정하면 제품이 태스크 간 쓰기 충돌이 발생할 수 있다고 경고한다. 그 경고는 이 글의 논지를 대화 상자 하나에 압축해 놓은 셈이다.

한도를 올리는 것에 관한 문서의 조언은 신중한 쪽이다. 현재 Computer와 Runtime이 기존 워크로드를 안정적으로 감당한 뒤에만 동시성을 높이라는 것이다.

진행 상황 스트리밍과 병합 전 리뷰

격리가 곧 보이지 않음까지 뜻한다면 그것은 오히려 부담이 된다. 숨겨진 디렉터리 다섯 개에서 도는 에이전트 다섯 개는 작업이 개인 터미널 속으로 사라지는 바로 그 방식이다. 그래서 실행이 만들어 내는 모든 것이 공유 기록으로 되돌아간다.

실행이 진행되는 동안 Task는 실행 상태를 보여 준다. Activity에는 댓글과 태스크 변경 사항이 타임라인으로 담기고, 실행 로그에는 실행 시작과 종료 시점, 도구 호출과 Runtime 이벤트, 트리거 출처, 실패 세부 정보가 기록되며, Agent의 보고서는 실행 추적과 연결된 댓글로 저장된다. 파일 편집이 아무도 열어 보지 않은 디렉터리에서 일어났더라도, 컨텍스트와 진행 상황, 블로커, 결과는 요청부터 릴리스까지 계속 눈에 보인다.

그다음 관문이 있다. 여기서는 아무것도 스스로 병합되지 않는다. Agent는 조사하고 실행하고 테스트하고 보고한다. 사람은 방향을 정하고 권한을 부여하고 결과를 받아들인다. 실행이 완료되면 Agent는 Task를 사람의 리뷰를 기다리는 상태로 남겨 둘 수 있고, 이는 담당자의 Inbox에 나타난다. 격리된 worktree는 병렬 실행을 안전하게 만들고, 리뷰 관문은 그것을 신뢰할 수 있게 만든다.

순환을 완성하는 조각이 하나 더 있다. 바로 정리다. Agent 실행은 Computer에 작업 디렉터리와 산출물을 남기는데, 설정 가능한 정리 기능이 보존 기간이 지난 완료된 실행을 회수하며, 최소 여유 공간 임계값이 안전장치로 동작한다. 실행 중이거나 대기 중인 작업, 고정된 실행, 아직 조사가 필요한 실패한 실행은 절대 건드리지 않는다. DIY 구성이 디스크가 꽉 찰 때까지 확실하게 잊고 지내는 바로 그 잔무다.

Sharkly가 자동화하는 것과 DIY 설정

DIY worktree 가이드를 읽었다면 대응 관계는 명확하다. 에이전트마다 스크립트로 짜 넣던 git worktree add는 로컬 서비스가 실행마다 격리된 디렉터리를 준비하는 일이 된다. “에이전트가 몇 개면 너무 많은가”라는 판단은, 안전하지 않은 설정에 경고를 띄우는 명시적 동시성 한도가 된다. 잊어버리게 되는 git worktree prune은 보존 기간 기반 정리가 된다. 그리고 어떤 스크립트도 제공해 주지 않는 부분, 즉 어느 실행이 무엇을 했고 사람이 그것을 승인했는지에 대한 공유 기록은 Task 자체다.

여기에도 정직한 결정 기준이 적용된다. 머신 한 대에서 에이전트 두 개를 돌리는 1인 개발자라면 플랫폼이 필요 없을 수도 있다. worktree 스크립트와 규율만으로도 꽤 멀리 갈 수 있다. 조율에 드는 비용이 타이핑 비용보다 커질 때 Sharkly를 찾으면 된다. 여러 사람이 작업을 할당하고, Computer가 여러 대이고, 실행에 대기열과 리뷰가 필요할 때다. 어느 쪽이든 이미 쓰고 있는 Runtime은 그대로 유지된다. 모델 사용은 해당 도구에 설정한 구독이나 API 키를 통해 계속 이어진다.

시작은 의도적으로 작게 설계되어 있다. Computer 하나를 연결하고, Temporary 모드로 Agent 하나를 만들고, 위험도가 낮은 Task 하나를 할당해 보자. 시작 가이드가 첫 루프를 약 10분에 걸쳐 안내하고, Sharkly 문서가 각 개념을 깊이 있게 다루며, Sharkly란 무엇인가에서 실행을 둘러싼 플랫폼 전반을 채워 준다.

FAQ

Sharkly는 병렬 에이전트 간의 병합 충돌을 어떻게 방지하나요?

각 Task 실행은 Computer에서 자체 격리된 디렉터리를 받고, 저장소 기반 실행은 로컬 서비스가 준비한 별도의 git worktree를 각각 받을 수 있습니다. Agent는 체크아웃이나 인덱스, 추적되지 않는 파일을 공유하지 않으므로 동시 실행이 서로의 작업 중인 내용을 덮어쓸 수 없습니다. 두 Task가 의도적으로 같은 코드를 변경해 겹치는 경우에는 리뷰 시점에 사람이 조정합니다.

Sharkly를 쓰려면 git worktree를 직접 설정해야 하나요?

아니요. Temporary 모드에서는 로컬 서비스가 모든 실행에 대해 태스크 디렉터리를 준비하며, 저장소 기반 작업에는 worktree도 포함됩니다. 모드는 Agent에 한 번만 설정하면 되고, 실행마다 스크립트로 넣어야 할 worktree 명령은 없습니다. 내부 동작이 궁금하다면 git worktree 문서를 참고하세요.

Computer 하나에서 몇 개의 에이전트를 병렬로 실행할 수 있나요?

Computer에는 자체 태스크 동시성 한도가 있고, 각 Agent에는 병렬 실행 Task 최대 개수가 있습니다. 기본적으로 Temporary 모드의 Agent는 Computer 한도의 50퍼센트를, Specified 모드의 Agent는 설정된 디렉터리당 슬롯 하나를 받습니다. 한도를 넘는 실행은 대기열에서 기다립니다.

Sharkly가 에이전트의 변경 사항을 자동으로 병합하나요?

아니요. 실행 결과와 근거, 추적은 Task로 돌아오고, 무엇이 배포되기 전에 사람이 변경 요약을 검토합니다. 검토자는 승인하거나 변경을 요청하거나, 병합 및 릴리스 단계를 결정합니다. 자동화는 팀의 판단이 필요한 지점에서 멈춥니다.

격리된 worktree 대신 Specified 모드는 언제 써야 하나요?

실행마다 새 디렉터리를 준비하는 비용이 정말 클 때 쓰면 됩니다. 아주 큰 저장소, 생성 비용이 큰 상태나 캐시, 하나의 로컬 경로에 묶인 도구가 그런 경우입니다. 다만 지정 디렉터리 하나는 한 번에 하나의 실행만 처리한다는 점을 받아들여야 합니다. 그 밖의 경우에는 Temporary 모드가 권장 기본값입니다.