TL;DR: 여러 Claude Code 에이전트를 병렬로 실행하려면 각 세션에 전용 git worktree를 할당하고(플래그 하나인 claude -w <name>로 가능), 직접 확인하지 않는 세션은 claude --bg를 통해 백그라운드로 보낸 다음, 에이전트가 작업을 마치기 전에 병합(merge) 순서를 정해 두어야 합니다. 격리된 브랜치라 해도 최종 반영 시 충돌이 일어날 수 있기 때문입니다. 두 세션이 체크아웃 하나를 공유하면, 한 에이전트의 커밋에 다른 에이전트가 작성 중이던 미완성 코드가 섞여 들어가는 불상사가 발생합니다. 이 가이드는 이미 Claude Code를 사용 중이며 2~5개의 세션을 동시에 실행하고 싶은 개발자를 위한 글입니다.
시작은 보통 두 번째 터미널입니다. 첫 번째 터미널에서 Claude Code가 인증 모듈을 리팩터링하고 있기에, 또 다른 창을 열어 새 세션에 간헐적으로 실패하는 날짜 테스트(flaky test) 수정을 맡깁니다. 그러다 문서를 작성하려고 세 번째 터미널을 열죠. 20분 뒤, 세 개의 세션이 하나의 작업 디렉터리에 동시에 변경 사항을 쏟아내고, git status에는 수정을 요청한 기억도 없는 파일들이 나열되며, 도대체 어떤 세션이 config.ts를 건드렸는지 아무도 알 수 없게 됩니다.
여러 Claude Code 에이전트를 실행하는 것 자체는 간단합니다. 터미널을 더 열기만 하면 되니까요. 하지만 세션들이 서로의 작업을 망치지 않게 하려면 세 가지를 결정해야 합니다. 각 세션의 파일을 어디에 둘 것인지, 화면으로 보고 있지 않은 세션을 어떻게 추적할 것인지, 그리고 각 브랜치를 어떤 순서로 반영할 것인지입니다. 이 글에서는 Claude Code의 내장 명령어와 함께 토이 저장소에서 직접 재현해 본 두 가지 실패 사례를 통해 이 세 가지 문제를 모두 다룹니다. worktree 개념이 생소하다면 AI 코딩 에이전트와 git worktree 활용 가이드나 git worktree 공식 문서를 먼저 읽어보시길 권합니다.
여러 Claude Code 에이전트가 공유 체크아웃을 망가뜨리는 이유
여러 Claude Code 에이전트를 병렬로 실행한다는 것은 동일한 저장소에서 두 개 이상의 세션이 각자의 작업과 독립된 컨텍스트 창을 갖고 동시에 작업함을 의미합니다. 이 세션들은 서로의 존재를 알지 못합니다. 각자 혼자 작업하는 것처럼 파일을 읽고, 수정하고, 테스트를 실행하며, 커밋합니다.
하지만 체크아웃은 단 하나의 작업 디렉터리, 하나의 인덱스(index), 하나의 HEAD만 가지고 있기 때문에 ‘혼자 있는 것처럼’ 행동하는 방식은 금세 파탄이 납니다. 저희는 에이전트 역할을 하는 두 개의 셸 스크립트를 사용해 토이 Python 저장소에서 가장 흔히 일어나는 실패 상황을 재현해 보았습니다. 에이전트 B가 작성 중이던 truncate() 함수를 textutils.py에 저장해 둔 상태입니다. 이때 에이전트 A가 다른 파일에서 자신의 작업을 마치고, 수많은 프롬프트가 지시하는 방식대로 git add -A && git commit을 실행합니다.
$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
slug.py | 2 ++
textutils.py | 4 ++++
2 files changed, 6 insertions(+)
$ python3 -m pytest -q
1 error in 0.09s
에이전트 A의 커밋에 에이전트 B의 미완성 함수가 포함되어 버렸고, 그 결과 테스트 스위트의 import 단계부터 오류가 발생합니다. 코드가 덮어쓰여진 것은 아닙니다. 인덱스를 공유하고 있었기 때문에 B의 작업 중인 변경 사항까지 A의 커밋에 쓸려 들어간 것이며, 커밋 히스토리에는 에이전트 A가 고장 난 코드를 작성한 것으로 남게 되었습니다. 동일한 파일을 수정할 때 발생하는 문제는 두 코딩 에이전트가 같은 파일을 수정하면 일어나는 일에서 다루고 있습니다.
각 세션마다 워크트리를 하나씩 할당하여 여러 Claude Code 에이전트 실행하기
해결책은 세션당 하나의 작업 디렉터리를 두는 것이며, Claude Code는 이를 플래그 형태로 자체 제공합니다.
# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux # opens the session in its own tmux or iTerm2 pane
# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"
worktree 공식 문서에 따르면, claude -w <name>는 worktree-<name>이라는 새 브랜치를 만들어 .claude/worktrees/<name>/ 경로에 워크트리를 생성합니다. 다른 이름을 지정해 두 번째 터미널을 열면 격리된 두 번째 세션이 구성됩니다. 직접 실행해 보았을 때, git은 새 워크트리를 locked 상태로 표시하여 실행 중인 세션 도중에 git worktree prune으로 인해 워크트리가 삭제되지 않도록 방지해 주었습니다. 에이전트 뷰(Agent View) 페이지에 따르면, --bg 또는 /bg로 시작된 백그라운드 세션 역시 무언가를 수정하기 전에 .claude/worktrees/ 아래의 전용 워크트리로 이동합니다.
불필요한 시간 낭비를 막아주는 세 가지 설정 팁이 있습니다.
- 폴더를 ignore 처리하세요. 워크트리가 저장소 내부에 생성되기 때문에, 공식 문서의 권장대로
.gitignore에.claude/worktrees/를 추가하지 않으면 메인 체크아웃의git status에서.claude/가 추적되지 않는 파일(untracked)로 표시됩니다. - 완전히 새로운 체크아웃 상태임을 염두에 두세요. 새로 생성된 워크트리에는
node_modules, 가상환경(virtualenv),.env가 존재하지 않습니다..env처럼 복사해야 하는 gitignore 대상 파일들을.worktreeinclude파일에 명시해 두고, 각 워크트리마다 의존성 설치 과정을 고려해야 합니다. - 헤드리스 실행은 직접 정리하세요. 대화형 세션은 종료 시 워크트리를 삭제할지 묻습니다. 반면
claude -p로 시작된 실행은 자동으로 정리되지 않으므로,git worktree unlock을 실행한 후git worktree remove로 직접 삭제해야 합니다.
백그라운드 세션은 셸에서 관리합니다. 아래 설명은 2.1.283 버전의 claude --help를 기준으로 작성되었습니다.
| 명령어 | 역할 |
|---|---|
claude --bg "<task>" |
세션을 백그라운드에서 시작하고 즉시 반환하며 ID를 출력합니다. |
claude agents |
실행 중인 세션 목록인 에이전트 뷰를 엽니다(스크립트용 플래그: --json). |
claude logs <id> |
백그라운드 세션의 최근 터미널 출력을 출력합니다. |
claude attach <id> |
현재 터미널에서 백그라운드 세션을 엽니다. |
claude stop <id> |
세션을 중지합니다. 대화 내용은 유지되며 claude attach <id>로 다시 열 수 있습니다. |
--bg는 -p와 함께 사용할 수 없습니다. 스크립트를 통한 대규모 병렬 실행(fan-out)의 경우, Anthropic의 Claude Code 활용 모범 사례 가이드에서 --allowedTools 및 --permission-mode dontAsk 옵션과 함께 claude -p를 사용하는 셸 루프 예시를 확인할 수 있습니다. 이때 -w를 함께 지정해야 각 실행마다 고유한 디렉터리를 가질 수 있습니다.
격리된 Claude Code 에이전트도 병합 시점에는 충돌할 수 있습니다
워크트리는 작업 도중 세션들이 서로의 발을 밟는 일은 막아주지만, 두 작업의 호환성까지 보장해주지는 않습니다. 두 개의 워크트리 브랜치에서 각각 textutils.py 파일 끝에 함수 하나를 추가하도록 동일한 성격의 변경 작업을 진행한 뒤 둘 다 병합해 보았습니다.
$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.
어느 에이전트도 잘못한 것은 없습니다. 둘 다 동일한 위치에 코드를 추가했고, git은 어떤 순서로 합쳐야 할지 스스로 판단할 수 없을 뿐입니다. 4~5개의 세션이 돌아가는 실제 코드베이스에서는 여러 작업이 공통으로 수정하는 파일(라우트 테이블, __init__.py export, 변경 이력(changelog), 락파일(lockfile) 등)에서 이런 일이 일상적으로 발생합니다. 공유 체크아웃과의 차이점이라면, 이제는 충돌이 명확하고 즉각적으로 드러나며 어느 작업 때문인지 원인을 추적할 수 있다는 것입니다. 다음 세 가지 습관을 들이면 충돌을 최소화할 수 있습니다.
- 기능 단위가 아니라 파일 단위로 작업을 분리하세요. 라우터 수정이 동시에 필요한 두 작업이라면, 하나의 작업으로 묶거나 순차적으로 실행해야 합니다.
- 병합 순서를 정해두고 나머지는 리베이스하세요. 첫 번째 브랜치를 병합(land)한 뒤, 다음 세션에
main브랜치를 기반으로 리베이스(rebase)하고 테스트를 다시 실행하도록 지시한 후 리뷰를 진행하세요. 코드를 작성한 세션이 충돌을 해결할 맥락을 가장 잘 알고 있습니다. - 워크트리 이름은 작업 내용에 맞게 지으세요. 한 시간 뒤
git worktree list를 확인할 때,claude -w agent2보다는claude -w fix-date-test가 훨씬 알아보기 쉽습니다.
실제 한계는 대개 git이 아니라 5개의 diff를 검토해야 하는 사람에게서 발생합니다. 병렬 에이전트에서 사람이 병목이 되는 이유와 리뷰 설계법에서 이러한 검토 대기열의 적정 규모를 산정하는 방법을 다룹니다.
서브에이전트, 에이전트 팀, 별도 세션: 어떤 방식을 선택해야 할까
이제 Claude Code는 작업을 병렬로 실행하는 여러 방식을 제공하며, 병렬 에이전트 개요에 각 방식이 정리되어 있습니다. 이 방식들은 서로 대체 가능한 것이 아닙니다. 가장 중요한 핵심 기준은 바로 격리(isolation) 수준입니다.
| 방식 | 실행 형태 | 파일 격리 | 권장 사용 사례 |
|---|---|---|---|
| Subagents | 단일 세션 내의 헬퍼 에이전트, 각자 독립된 컨텍스트 창 보유 | 서브에이전트가 isolation: worktree를 설정하지 않는 한 체크아웃 공유 |
한 작업에서 부가적인 조사, 코드 리뷰, 또는 병렬 읽기 작업이 필요할 때 |
/batch |
하나의 변경 작업을 5~30개의 서브에이전트로 분할 | 서브에이전트당 워크트리 하나 | 수많은 파일에 걸쳐 대규모의 기계적인 변경을 적용할 때 |
| Agent teams | 작업 목록을 공유하고 서로 메시지를 주고받는 리드 세션 및 팀원들 | 없음: 문서에서는 작업을 명확히 분할할 것을 권장 | 팀원 간에 작업 도중 소통이 필요할 때(실험적 기능, 기본적으로 비활성화됨) |
Separate sessions (-w, --bg, Desktop) |
독립된 세션들 | 세션당 워크트리 하나 | 하나씩 검토할 독립적인 작업들 |
Cloud sessions (claude --cloud) |
푸시된 브랜치를 클론하는 격리된 VM 내 세션 | 세션당 VM 하나 | 로컬 노트북 자원을 점유하지 않아야 하는 작업 |
독립적인 작업에는 워크트리를 활용한 별도 세션을 사용하세요. 작업 간 상호 의존성이 있어 팀원 간 협의가 필요할 때는 에이전트 팀을 사용하되, 각 팀원에게 서로 다른 파일을 할당해야 합니다. 에이전트 팀 설명 페이지에서도 “두 팀원이 동일한 파일을 수정하면 덮어쓰기가 발생한다”고 직설적으로 경고하고 있습니다. 어떤 방식을 선택하든 사용량 한도는 공유됩니다. 에이전트 뷰 문서에서도 “10개의 에이전트를 병렬로 실행하면 1개를 실행할 때보다 할당량이 약 10배 빠르게 소진된다”고 명확히 밝히고 있습니다.
여러 Claude Code 에이전트를 실행할 때 Sharkly가 필요한 이유
자신의 노트북에서 2~3개의 세션을 돌리며 모든 diff를 직접 검토하는 수준이라면 위에서 설명한 명령어만으로도 충분하며, Sharkly가 굳이 필요하지 않을 수 있습니다. 하지만 여러 사람이 세션을 실행하거나, “어떤 세션에서 날짜 테스트를 수정하고 있지?”라는 질문에 답하는 데 걸리는 시간이 버그를 고치는 시간보다 더 오래 걸리기 시작한다면 상황은 달라집니다.
여러분은 이미 코딩 에이전트를 보유하고 있습니다. Sharkly는 이들을 하나의 팀으로 만들어 줍니다. 각 작업 단위는 하나의 Task가 됩니다. 이를 컴퓨터 중 하나에서 Claude Code 런타임으로 실행되는 Agent에 할당하면, 담당자(Assignee)를 지정하는 즉시 실행이 시작됩니다. 기본 작업 디렉터리 설정인 Create temporary directory를 사용하면 각 Task마다 고유한 디렉터리가 부여되며, 저장소 기반 실행에는 격리된 git worktree가 생성됩니다. 사용자가 직접 워크트리 이름을 일일이 붙이지 않아도 claude -w와 동일한 수준의 격리가 이루어지는 것입니다. 에이전트가 로컬 컴퓨터에 이미 마련된 환경을 재사용해야 하는 경우, Run in isolated worktrees 설정을 통해 각 Task의 결과물이 전용 agent/<agent>/<task> 브랜치에 반영됩니다. 또한 Agent의 Max concurrency (assigned tasks) 설정을 통해 동시에 실행되는 작업 수를 제한할 수 있는데, 이는 앞서 언급한 검토 한계를 팀 전체가 명확히 인지할 수 있도록 명문화하는 역할을 합니다.
진행 상황, 실행 기록, 결과물은 해당 Task로 다시 전달되며, 사람의 개입이 필요한 항목은 수신함(Inbox)으로 들어옵니다. 코드가 자동으로 병합되는 일은 결코 없습니다. 사람이 직접 워크트리의 변경 사항을 검토하여 유지, 병합 또는 폐기한 뒤 Task를 완료(Done) 상태로 변경합니다. Sharkly는 토큰을 판매하지 않으므로, 실행 비용은 사용자의 기존 Claude Code 플랜에 청구됩니다. 설정 방법은 Agents 기능 페이지에서 확인할 수 있으며, 실행 방식에 관한 자세한 내용은 Sharkly의 에이전트 병렬 실행 원리를 참조하세요.
터미널 3개를 넘어 여러 세션을 운영하면서 모든 Claude Code 세션의 결과물을 검토자가 한자리에서 차례대로 확인할 수 있는 환경이 필요하다면, 바로 그 지점이 Sharkly가 해결하고자 하는 문제입니다.
자주 묻는 질문 (FAQ)
Claude Code 에이전트는 한 번에 몇 개까지 실행할 수 있나요? 공식 문서상 별도 세션의 개수에는 제한이 없습니다. 서브에이전트는 기본적으로 최대 20개까지 동시 실행되며, 에이전트 팀 페이지에서는 3~5명의 팀원으로 시작할 것을 권장합니다. 실제 한계는 요금제의 사용량 한도, 노트북의 CPU 및 메모리 사양, 그리고 하루에 검토할 수 있는 결과물의 양에 의해 결정됩니다. 여섯 번째 세션을 추가하기 전에 리뷰 처리 용량 계산법을 미리 따져보는 것이 좋습니다.
병렬로 실행되는 Claude Code 세션들은 사용량 한도를 공유하나요? 네, 그렇습니다. Pro 및 Max 플랜의 경우 Claude와 Claude Code 간에 사용량 한도가 공유되며, 5시간 단위 제한 및 주간 제한이 적용되어 모든 병렬 세션이 동일한 할당량을 공유합니다. ANTHROPIC_API_KEY가 설정된 경우에는 Claude Code 사용량이 API 요금으로 청구됩니다.
claude --worktree를 실행하면 .env와 의존성 패키지도 복사되나요? 아닙니다. 각 워크트리는 새로운 체크아웃 상태로 생성됩니다. .env처럼 필요한 gitignore 대상 파일들을 .worktreeinclude에 추가하고, 각 워크트리에서 의존성 설치 단계를 직접 실행해야 합니다.
동일한 저장소에서 Claude Code와 Codex를 병렬로 실행할 수 있나요? 네, 가능합니다. 세션당 하나의 워크트리를 사용하고 병합 순서를 지킨다는 동일한 원칙이 적용됩니다. 작업 라우팅에 관한 자세한 내용은 단일 코드베이스에서 Claude Code와 Codex를 함께 실행하는 방법 가이드를 확인하세요.
