스크린샷은 봤을 것이다. 5개, 10개, 15개의 Claude Code 에이전트가 tmux에서 실행되며 각각 같은 코드베이스의 다른 부분을 작업하고 있다. 생산적으로 보인다. 흥미진진해 보인다. 그리고 직접 재현해 보려 했다면, 보이는 것보다 훨씬 어렵다는 걸 알 것이다.
Claude Code 에이전트 하나를 실행하는 건 간단하다. 작업을 주면 코드를 작성하고, 리뷰하면 된다. 두 개는 관리할 만하지만 새로운 문제가 생긴다: 서로의 변경 사항을 밟을 수 있다. 다섯 개에는 시스템이 필요하다. 시스템 없이 열 개는 월 요금이 붙는 혼돈이다.
이 가이드는 그 시스템에 대한 것이다. 멀티 에이전트 아키텍처의 이론이 아니다. 실제 코드베이스에서 여러 Claude Code 에이전트를 모든 것이 무너지지 않게 실행하는 실질적인 워크플로우다.
왜 에이전트 하나로는 부족한가
단일 Claude Code 에이전트는 놀라울 정도로 많은 작업을 처리할 수 있다. 하지만 순차적이다. 백엔드 엔드포인트를 구현하는 동안 프론트엔드는 멈춰 있다. 테스트를 작성하는 동안 문서화는 뒤처진다. 빌드 실패를 디버깅하는 동안 새로운 기능 세 개가 대기열에서 기다린다.
소프트웨어 작업의 대부분이 병렬화 가능하다는 걸 깨달으면 계산이 달라진다. 프론트엔드 컴포넌트와 백엔드 API 엔드포인트는 파일을 공유하지 않는다. 테스트 스위트와 문서 업데이트는 다른 디렉토리를 건드린다. 아키텍처 리뷰와 버그 수정은 완전히 다른 시간 척도에서 작동한다.
싱글 에이전트 개발의 병목은 에이전트의 속도가 아니다. 파이프라인의 깊이다. 에이전트 하나는 한 번에 하나만 진행할 수 있다. 여러 에이전트는 여러 작업이 동시에 진행되며, 이것이 한 명의 개발자가 하루에 출하할 수 있는 것을 바꾼다.
작업 분할 전략
두 번째 tmux 패널을 열기 전에 작업을 어떻게 나눌지 결정해야 한다. 실전에서 검증된 세 가지 패턴이 있다.
컴포넌트별 분할
가장 단순한 접근법. 에이전트 A는 components/를, 에이전트 B는 server/를, 에이전트 C는 lib/를 소유한다. 각 에이전트는 자기 영역에서 작업하며 밖의 파일은 절대 건드리지 않는다.
코드베이스에 명확한 아키텍처 경계가 있을 때 잘 작동한다. 별개의 프론트엔드 컴포넌트, 백엔드 액션, 공유 라이브러리가 있는 Next.js 앱은 자연스럽게 이 선을 따라 분할된다.
한계: 횡단적 작업. UI, API, 데이터 레이어 모두에 변경이 필요한 기능은 단일 에이전트의 영역에 깔끔하게 들어맞지 않는다. 기능을 컴포넌트 범위의 하위 작업으로 분해하고 순서를 정하여 해결한다.
역할별 분할
코드 위치 대신 기능으로 나눈다. 한 에이전트가 코드를 작성한다. 다른 하나가 테스트를 작성한다. 세 번째가 문서화를 담당한다. 네 번째가 코드 리뷰를 한다.
인간 팀의 작업 방식을 반영하며 더 높은 품질의 결과물을 만든다. 테스트 에이전트는 코드가 얼마나 작성하기 쉬웠는지 모른다(신경 쓰지도 않는다). 스펙에 대해 테스트하지, 작성자의 가정에 대해 테스트하지 않는다.
트레이드오프는 더 많은 조율 오버헤드다. 테스트 에이전트는 구현 에이전트가 먼저 끝나야 한다. 문서 에이전트는 둘 다 필요하다. 병렬 워커가 아닌 파이프라인을 관리하는 것이다.
라이프사이클 단계별 분할
역할 분할의 더 정교한 버전. 한 에이전트가 브레인스토밍과 계획을 한다. 다른 하나가 구현한다. 세 번째가 검증한다. 작업이 단계를 통해 흐르며, 각 에이전트는 해당 단계에 특화되어 있다.
이것이 Beadbox에서 사용하는 패턴이다. 아키텍트 에이전트가 설계하고, 엔지니어링 에이전트가 구현하고, QA 에이전트가 독립적으로 검증한다. 같은 작업이 여러 전문가를 거치며, 각각이 제너럴리스트 에이전트가 놓치는 품질 레이어를 추가한다. 전체 셋업에 대해서는 13개의 AI 에이전트로 소프트웨어를 출하한다에 작성했다.
올바른 전략은 프로젝트에 달려 있다. 파일 경계가 명확한 작은 프로젝트는 컴포넌트 분할이 좋다. 품질이 중요한 큰 프로젝트는 역할이나 라이프사이클 분할의 혜택을 받는다. 대부분의 팀은 하이브리드로 귀결된다.
CLAUDE.md 아이덴티티 패턴
여기서 이론이 구현을 만난다. 각 Claude Code 에이전트는 자체 CLAUDE.md 파일을 받으며, 이 파일이 멀티 에이전트 시스템 전체에서 가장 중요한 요소다.
CLAUDE.md는 네 가지를 정의한다:
- 에이전트가 무엇인지. 역할, 전문 분야, 도메인.
- 무엇을 소유하는지. 제어하는 파일, 디렉토리 또는 책임 범위.
- 무엇을 건드리면 안 되는지. 충돌을 방지하는 명시적 경계.
- 어떻게 통신하는지. 작업 보고 및 다른 에이전트와의 조율 프로토콜.
실제 예시. 상호보완적 스코프를 가진 두 Claude Code 에이전트:
# CLAUDE.md for Agent: frontend-eng
## Identity
Frontend engineer. You implement UI components, pages, and client-side
logic. You own everything under components/, app/, and hooks/.
## File Ownership
- components/** (you own these)
- app/** (you own these)
- hooks/** (you own these)
- lib/utils.ts (shared, read-only for you)
- server/** (DO NOT MODIFY — owned by backend-eng)
## Communication
When you need a backend change, create a task describing what API
you need. Do not implement it yourself.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
# CLAUDE.md for Agent: backend-eng
## Identity
Backend engineer. You implement server actions, API routes, and
data layer logic. You own everything under server/, actions/, and lib/.
## File Ownership
- server/** (you own these)
- actions/** (you own these)
- lib/** (you own these, except utils.ts is shared)
- components/** (DO NOT MODIFY — owned by frontend-eng)
- app/** (DO NOT MODIFY — owned by frontend-eng)
## Communication
When you change a data type in lib/types.ts, notify frontend-eng
by commenting on the relevant task.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
명시적인 "DO NOT MODIFY" 라인에 주목하라. 이것 없이는 에이전트가 표류한다. 소유하지 않은 파일의 오타를 수정하여 "도움"을 주려는 기회를 보고, 갑자기 머지 충돌이 생긴다. 더 나쁜 경우, 다른 에이전트가 의존하고 있던 코드를 조용히 리팩토링한다.
아이덴티티 섹션은 장식이 아니다. Claude Code는 세션 시작 시 CLAUDE.md를 읽고 행동 범위를 정하는 데 사용한다. "프론트엔드 엔지니어"라고 말해진 에이전트는 자연스럽게 백엔드 변경을 거부한다. 특정 디렉토리를 소유한다고 말해진 에이전트는 그 외의 파일을 수정하기 전에 물어본다.
머지 충돌 회피
위의 CLAUDE.md 예시에서 보여준 파일 수준 소유권이 첫 번째 방어선이다. 하지만 유일한 것은 아니다.
자주 커밋하고 푸시하라. 45분간 커밋 없이 작업하는 에이전트는 머지 충돌 시한폭탄을 만들고 있다. 에이전트에게(CLAUDE.md에서) 각 논리적 작업 단위를 완료할 때마다 커밋하도록 지시하라.
새 작업 전에 풀하라. 각 에이전트는 새 작업을 시작하기 전에 git pull --rebase를 실행해야 한다. CLAUDE.md의 시작 프로토콜에 추가하면 사소하게 적용할 수 있다.
횡단적 작업에는 피처 플래그를 사용하라. 두 에이전트가 같은 파일을 수정해야 할 때, 더 안전한 접근법은 한 에이전트가 인터페이스나 플래그를 만들고 커밋, 푸시한 후, 두 번째 에이전트가 풀해서 그 위에 빌드하는 것이다. 대안이 머지 악몽이라면 순차가 병렬을 이긴다.
위험한 작업에는 별도 브랜치. 에이전트가 실험적인 것을 하고 있다면 전용 브랜치를 주라. 아키텍처 스파이크나 반영되지 않을 수 있는 리팩토링 작업에 특히 유용하다.
실전에서, 파일 소유권 규칙과 빈번한 커밋의 조합이 머지 충돌의 90%를 제거한다. 나머지 10%는 types.ts나 package.json 같은 공유 파일에서 발생하며, 대체로 해결이 간단하다.
에이전트 간 통신
Claude Code 에이전트는 직접 대화할 수 없다. 공유 메모리도, 메시지 버스도, 실시간 채널도 없다. 이것은 사실 좋은 것이다. 에이전트 간 직접 통신은 결합, 레이스 컨디션, 디버깅 악몽을 만든다.
대신 통신은 아티팩트를 통해 이루어진다. 세 가지 패턴이 작동한다:
작업 코멘트
가장 신뢰할 수 있는 패턴. 에이전트 A가 작업을 완료하고 공유 작업에 코멘트한다: "DONE: /api/users 엔드포인트 구현. JSON 반환. 스키마는 lib/types.ts에 있음." 에이전트 B가 작업 코멘트를 읽고 무엇이 사용 가능한지 정확히 파악한다.
상태 업데이트
각 작업에는 상태가 있다: open, in_progress, done, blocked. 에이전트 A가 선행 작업을 done으로 표시하면, 에이전트 B(또는 당신, 또는 코디네이터)는 의존 작업을 시작할 수 있다는 걸 안다.
파일 변경
가장 단순한 형태. 에이전트 A가 TypeScript 인터페이스를 lib/types.ts에 작성하고 커밋한다. 에이전트 B가 풀하고 새로운 타입을 본다. 코드 자체가 메시지이므로 명시적 통신이 필요 없다.
작동하지 않는 것: 에이전트 간 실시간 메시지 전달 시스템을 구축하려는 시도. 에이전트 A가 에이전트 B의 출력을 기다려야 한다면, 동기 호출이 아닌 작업 간 의존성으로 모델링하라.
디스패치 루프
누군가가 지휘해야 한다. 멀티 에이전트 Claude Code 셋업에는 두 가지 옵션이 있다: 수동으로 하거나, 코디네이터 에이전트를 지정하거나.
수동 디스패치
작업 목록을 관리한다. 에이전트에게 작업을 할당한다. 진행 상황을 확인한다. 블로커를 처리한다. 이것은 약 5개 에이전트까지 작동하며, 그 이후에는 조율 오버헤드가 생산성 향상을 잠식하기 시작한다.
전형적인 수동 디스패치 사이클:
- 아침: 진행 중, 블로킹 중, 작업 준비 완료 상태 확인
- 할당: 각 에이전트에게 컨텍스트와 함께 다음 작업 전송
- 모니터링: 10-15분마다 에이전트 출력에서 막힌 징후 확인
- 해소: 에이전트가 문제에 부딪히면 개입하거나 재할당
- 마감: 하루 끝에 출하된 것 확인하고 내일 작업 계획
tmux에서 이것은 패널을 돌아다니며 최근 출력을 읽고 각 에이전트가 다음에 무엇이 필요한지 판단하는 모습이다. gp(에이전트를 중단시키지 않고 최근 출력 엿보기) 같은 도구가 도움이 되지만, 여전히 당신이 병목이다.
코디네이터 에이전트
하나의 Claude Code 에이전트를 다른 에이전트에 작업을 디스패치하는 전담으로 둔다. 이 에이전트는 코드를 작성하지 않는다. 작업 백로그를 읽고, 가용 에이전트에게 작업을 할당하고, 진행 상황을 확인하고, 디스패치 루프를 프로그래밍적으로 처리한다.
이것이 우리가 사용하는 패턴이다. "super" 에이전트가 순찰 루프를 실행한다: 몇 분마다 각 활성 에이전트를 확인하고, 작업 상태를 체크하고, 블로커를 식별하고, 에이전트가 유휴 상태가 되면 새 작업을 디스패치한다. 인간(나)이 우선순위 결정을 내리고 모호한 상황을 해결한다. Super가 로지스틱스를 처리한다.
코디네이터 에이전트에는 자체 CLAUDE.md가 필요하다:
# CLAUDE.md for Agent: super
## Identity
Dispatch coordinator. You assign work to agents, monitor progress,
and ensure the pipeline keeps moving. You do NOT write code.
## Responsibilities
- Maintain awareness of all active tasks and their statuses
- Assign ready tasks to idle agents
- Monitor agent progress every 5-10 minutes
- Escalate blockers to the human when agents can't self-resolve
- Verify agents follow the protocol: plan before code, test before done
## Communication
- To assign work: message the agent with task ID and priority
- To check progress: peek at agent's recent output
- To escalate: message the human with context and options
코디네이터 패턴은 수동 디스패치보다 훨씬 잘 확장된다. 10개 이상의 에이전트에서 수동 조율은 풀타임 직업이다. 코디네이터 에이전트가 일상적인 로지스틱스를 처리하고 인간 판단이 필요한 결정만 에스컬레이트한다.
멀티 에이전트 작업을 위한 tmux 레이아웃
물리적 레이아웃은 생각보다 중요하다. 여러 Claude Code 에이전트를 실행하기 위한 tmux 설정:
# Create a new tmux session
tmux new-session -s agents -n super
# Split into panes for each agent
tmux split-window -h -t agents:super
tmux split-window -v -t agents:super.1
# Or create named windows (easier to manage at scale)
tmux new-window -t agents -n eng1
tmux new-window -t agents -n eng2
tmux new-window -t agents -n qa1
tmux new-window -t agents -n frontend
tmux new-window -t agents -n backend
이름 있는 윈도우는 4개 에이전트를 넘으면 분할 패널을 이긴다. 한 화면에서 5개 패널을 읽을 수 없지만, 이름 있는 윈도우 사이를 빠르게 전환할 수 있다. 네이밍 컨벤션도 중요하다. eng1, eng2, qa1은 즉시 스캔 가능하다. agent-1, agent-2, agent-3은 아무것도 알려주지 않는다.
각 에이전트를 자체 작업 디렉토리와 자체 CLAUDE.md로 시작한다:
# In the eng1 window
cd ~/project
claude --claude-md ./agents/eng1/CLAUDE.md
# In the qa1 window
cd ~/project
claude --claude-md ./agents/qa1/CLAUDE.md
실용적인 팁: 단순한 셸인 "대시보드" 윈도우를 유지하라. git log --oneline -10 실행, 작업 상태 확인, 에이전트의 작업을 방해하지 않고 관찰하는 데 사용한다. 이것이 커맨드 센터가 된다.
잘못될 때
멀티 에이전트 워크플로우는 예측 가능한 방식으로 실패한다. 실패 모드를 아는 것이 어렵게 배우는 것을 피하게 해준다.
두 에이전트가 같은 파일을 편집한다. 보통 CLAUDE.md의 파일 소유권이 충분히 구체적이지 않았기 때문이다. lib/utils.ts는 전형적인 충돌 자석이다. 해결책: 공유 유틸리티 파일을 특정 에이전트에게 할당하거나, 모두에게 읽기 전용으로 만들고 단일 소유자를 통해 변경을 라우팅한다.
에이전트가 침묵한다. 레이트 리밋, 에러 루프, 또는 깊은 추론 체인에 갇혔다. 출력을 확인하라. 같은 실패하는 명령을 반복 시도하고 있다면, 세션을 종료하고 더 명확한 지시로 재시작하라. 주기적 헬스 체크(10-15분마다)가 한 시간을 낭비하기 전에 이를 잡아낸다.
컨텍스트 윈도우가 가득 찬다. 장시간 실행 에이전트는 컨텍스트를 축적하고 성능이 저하되기 시작한다. 각 에이전트의 CLAUDE.md에 이를 위한 프로토콜을 포함해야 한다: "90분 이상 작업했다면 상태를 저장하고 새 세션을 요청하라." 실전에서는 에이전트가 작업을 커밋하고 중단 지점을 기록하며, 새로운 Claude Code 세션이 해당 커밋에서 이어받는 것을 의미한다.
작업이 스펙에서 이탈한다. 에이전트가 기술적으로는 작동하지만 요구 사항과 일치하지 않는 것을 만든다. 해결책은 코드 전 계획 패턴: 코드를 작성하기 전에 에이전트가 구현 계획을 코멘트한다. 60초 안에 계획을 리뷰하고 500줄 diff가 되기 전에 오해를 잡아낸다.
파이프라인이 정체된다. 에이전트 B가 에이전트 A를 기다리는데, 에이전트 A는 당신의 결정을 기다리고 있다. 그동안 에이전트 C는 30분 전에 작업을 끝내고 유휴 상태다. 이것은 기술적 문제가 아니라 조율 실패다. 코디네이터 에이전트(또는 당신)가 블로커를 모니터링하고 유휴 에이전트를 재할당하여 파이프라인을 계속 움직여야 한다.
Beads로 이것을 어떻게 해결했는가
위의 모든 것은 포스트잇과 선의로 작동한다. 하지만 5개 에이전트 정도에서 비공식적 접근이 금이 가기 시작한다. 에이전트 C가 무엇을 작업하고 있었는지 잊는다. 어떤 작업이 블로킹되어 있는지 추적을 잃는다. 에이전트 B가 필요한 API 엔드포인트가 완료된 건지 막 시작한 건지 기억나지 않는다.
이것이 beads가 해결하는 문제다. Beads는 오픈소스, 로컬 퍼스트 이슈 트래커다. 각 작업은 고유 ID, 상태, 설명, 수락 기준, 의존성, 코멘트 스레드를 가진 "bead"다. 모두 bd라는 CLI를 통해 접근 가능하며, Claude Code 에이전트가 터미널을 떠나지 않고 읽고 쓸 수 있다는 의미다.
beads를 사용한 디스패치 루프의 모습:
# See what's ready for work
bd list --status open
# Assign a task to an agent
bd update bb-a1b2 --claim --actor eng1
# Agent reads its assignment
bd show bb-a1b2
# Agent comments its plan before coding
bd comments add bb-a1b2 --author eng1 "PLAN:
1. Add endpoint at /api/users
2. Define UserResponse type in lib/types.ts
3. Write integration test
Files: server/api/users.ts (new), lib/types.ts (modify)
Test: curl localhost:3000/api/users returns 200 with JSON array"
# Agent finishes and comments what it did
bd comments add bb-a1b2 --author eng1 "DONE: /api/users endpoint live.
Returns paginated JSON. Added UserResponse type.
Verification:
1. curl http://localhost:3000/api/users → 200, JSON array
2. curl http://localhost:3000/api/users?page=2 → 200, second page
3. pnpm test → all passing
Commit: 8f3c2a1"
# Agent marks the task done
bd update bb-a1b2 --status closed
모든 에이전트가 이 프로토콜을 따른다: 클레임, 계획, 구현, DONE 코멘트, 상태 업데이트. 각 bead의 코멘트 스레드가 무엇이 일어났는지, 왜, 어떻게 검증하는지의 완전한 감사 기록이 된다.
의존성이 충돌하는 작업을 방지한다:
# Create a task that depends on another
bd create --title "Build user list component" \
--deps bb-a1b2 \
--description "Frontend component that calls /api/users. Blocked until API is live."
의존 작업은 bb-a1b2가 완료될 때까지 블로킹 상태로 남는다. 어떤 에이전트도 성급하게 가져가지 않는다. 아직 존재하지 않는 API의 프론트엔드를 만들며 시간을 낭비하는 사람은 없다.
bd list 명령으로 전체 파이프라인의 스냅샷을 얻는다:
bd list --status in_progress
# Shows what every agent is actively working on
bd blocked
# 미완료 의존성을 기다리는 작업 표시
bd list --status open --priority p1
# Shows the highest-priority work that's ready to start
이것이 머릿속에 유지하던 멘탈 모델을 대체한다. 모든 작업의 상태, 각 에이전트의 현재 작업, 모든 의존성 체인, 전부 커맨드라인에서 쿼리 가능하다.
가시성 확장
CLI는 작동한다. 하지만 규모에서는 터미널에서 bd list를 실행해 흡수할 수 있는 양에 한계가 있다. 8개의 에이전트가 3개의 에픽에서 17개의 미완료 작업과 12개의 의존성을 작업하고 있을 때, 작업의 목록이 아니라 작업의 형태를 봐야 한다.
이것이 Beadbox를 만들어 채우려 한 갭이다. Beadbox는 beads 위에 위치하는 실시간 대시보드로 다음을 보여준다:
- 에픽 트리와 프로그레스 바로, 각 기능이 모든 하위 작업에 걸쳐 어떻게 진행되고 있는지 확인
- 의존성 그래프로, 파이프라인을 정체시키기 전에 블로킹된 작업을 표면화
- 에이전트 활동으로, 어떤 에이전트가 무엇을 작업하는지, 계획과 완료 코멘트가 컨텍스트 내에서 표시
- 실시간 업데이트: 대시보드가 beads 데이터베이스를 감시하고 에이전트가 작업 상태를 업데이트하면 자동 갱신
Beadbox는 CLI를 대체하지 않는다. 에이전트는 여전히 bd를 통해 beads에 읽고 쓴다. Beadbox는 전체 그림을 제공하여 판단 결정을 내릴 수 있게 한다: 어떤 에픽이 뒤처지고 있는지, 어떤 에이전트가 도움이 필요한지, 어디에 병목이 형성되고 있는지.
베타 기간 동안 무료다. 이런 워크플로우를 구축하고 있다면, GitHub에서 Beadbox에 스타를 달아 달라.
시작하기
13개의 에이전트가 없어도 혜택을 받을 수 있다. 최소 실행 가능 셋업:
- 두 개의 Claude Code 에이전트를 별도의 tmux 윈도우에서, 각각 파일 소유권 경계를 정의하는 자체 CLAUDE.md와 함께.
- 작업 목록 (이 규모에서는 텍스트 파일도 가능) 두 에이전트 모두 무엇을 작업하고 있고 다음은 무엇인지 알 수 있도록.
- 커밋 프로토콜: 두 에이전트 모두 자주 커밋하고 새 작업 전에 풀한다.
그것이 자연스러워지면, 테스트나 문서화를 위한 세 번째 에이전트를 추가한다. 그다음 코디네이터 에이전트를 고려한다. 그다음 beads를 도입하여 구조화된 작업 트래킹을 한다. 조율의 고통이 증가할 때 시스템을 확장하라. 그 전이 아니라.
어려운 것은 도구가 아니다. 사고방식의 전환이다: "AI 어시스턴트를 사용하고 있다"에서 "팀을 운영하고 있다"로. CLAUDE.md 파일, 디스패치 프로토콜, 소유권 경계: 이것들은 설정 파일이 아니라 관리 관행이다. 팀 구성원이 API 호출로 실행되더라도 조직을 구축하고 있는 것이다.
두 개의 에이전트와 명확한 경계로 시작하라. 나머지는 모두 거기서 따라온다.
