Claude Code 에이전트 팀 운영 가이드: iTerm2와 tmux로 AI 개발팀 만들기
Claude Code를 쓰면서 한 가지 아쉬운 점이 있었습니다. 아무리 빨라도 결국 하나의 작업을 순차적으로 처리한다는 것입니다. 프론트엔드 컴포넌트를 만들고, API를 짜고, 테스트를 작성하는 걸 한 세션에서 차례로 하면 생각보다 시간이 걸립니다. "이걸 동시에 돌리면 안 되나?"라는 생각이 자연스럽게 듭니다.
됩니다. Claude Code에는 에이전트 팀(Agent Teams)이라는 기능이 있습니다. 여러 Claude Code 인스턴스를 동시에 띄워서 각각 다른 작업을 맡기는 방식인데, 한 에이전트는 프론트엔드를, 다른 에이전트는 백엔드를, 또 다른 에이전트는 테스트를 담당하고요. 이 에이전트들이 서로 메시지를 주고받으며 협업합니다.
이 글에서는 iTerm2와 tmux를 사용해서 Claude Code 에이전트 팀을 처음부터 끝까지 설정하고 운영하는 방법을 설명합니다. macOS 환경에서 iTerm2를 쓰고 있다면, 이 글을 따라하는 것만으로 멀티 에이전트 개발 환경을 구축할 수 있습니다.
에이전트 팀이 뭔가요
먼저 에이전트 팀이 기존의 서브에이전트(Subagent)와 어떻게 다른지 짚어보겠습니다.
서브에이전트는 메인 Claude Code가 내부적으로 하위 에이전트를 호출하는 방식입니다. Agent 도구를 쓰면 메인 세션 안에서 서브프로세스가 뜨고, 작업을 마치면 결과를 메인에 돌려주죠. 메인이 시키는 일을 하고 보고하는 구조라서, 서브에이전트끼리는 서로 대화하지 못합니다.
에이전트 팀은 다릅니다. 팀 리드(Team Lead) 한 명과 여러 동료(Teammate)로 구성되는데, 핵심 차이가 두 가지 있습니다.
첫째, 동료끼리 직접 통신할 수 있습니다. 메일박스(Mailbox) 시스템을 통해 동료 A가 동료 B에게 메시지를 보내고, 동료 B가 응답하는 구조입니다. 리드를 거치지 않아도 되고요. 메일박스는 파일 기반의 비동기 메시지 큐인데, 동료가 다른 동료에게 메시지를 보내면 해당 동료의 메일박스에 쌓이고, 동료는 작업 턴이 돌아올 때마다 자신의 메일박스를 확인합니다. "frontend 동료가 API 스펙이 필요해서 backend 동료에게 요청하면, backend 동료가 다음 턴에서 메일박스를 확인하고 응답하는 방식"이라고 이해하면 됩니다.
둘째, 공유 태스크 목록(Shared Task List)이 있습니다. 팀 전체가 하나의 태스크 목록을 공유하고, 각 동료가 자기 작업을 가져가서 처리하는 거죠. 리드가 모든 작업을 일일이 배분할 필요가 없습니다. 리드가 태스크 목록에 작업을 등록하면, 유휴 상태의 동료가 자동으로 다음 작업을 가져갑니다. 공식 문서에 따르면 TeammateIdle 훅(동료가 작업을 마치고 대기 상태가 되었을 때)과 TaskCompleted 훅(특정 태스크가 완료되었을 때)으로 작업 흐름을 자동화할 수도 있고요. 팀 운영에 익숙해지면 이런 훅을 써서 "shared 팀원의 타입 정의 완료 시 자동으로 frontend와 backend에 알림"같은 워크플로를 구성할 수 있습니다.
하나 더 짚을 게 있습니다. 에이전트 팀과 별도로, .claude/agents/ 디렉토리에 마크다운 파일로 커스텀 서브에이전트를 정의할 수 있습니다. 서브에이전트는 에이전트 팀의 동료와 달리 메인 세션 안에서 호출되는 하위 프로세스인데, 두 기능을 조합할 수도 있습니다. 예를 들어 에이전트 팀의 동료에게 특정 서브에이전트 역할을 지정하거나, 서브에이전트에 isolation: worktree 설정을 추가해서 독립된 워크트리에서 실행되게 할 수 있죠. 이 글에서는 에이전트 팀에 집중하겠지만, 프로젝트가 커지면 서브에이전트 조합도 한번 살펴보시기 바랍니다.
다음 그림은 서브에이전트와 에이전트 팀의 구조적 차이를 보여줍니다. 서브에이전트는 메인에서 하위로만 통신하는 일방향 구조이고, 에이전트 팀은 동료끼리 직접 소통하며 공유 작업 목록을 활용하는 양방향 구조입니다.
서브에이전트 방식에서는 하위 에이전트 A, B, C가 서로 대화할 수 없고, 메인을 통해서만 결과를 주고받습니다. 반면 에이전트 팀 방식에서는 동료 A, B, C가 메일박스를 통해 직접 메시지를 교환하고, 공유 작업 목록에서 각자 할 일을 가져갑니다. 팀 리드가 전체를 조율하되, 리드를 거치지 않는 동료 간 직접 통신이 가능한 점이 결정적 차이입니다.
현재 에이전트 팀은 실험적(Experimental) 기능입니다. 정식 출시 전이라 설정을 직접 활성화해야 합니다.
사전 준비: 무엇을 설치해야 하나
에이전트 팀을 운영하려면 몇 가지 도구가 필요합니다. 하나씩 설치하겠습니다.
Claude Code 설치 확인
먼저 Claude Code가 설치되어 있는지 확인합니다.
claude --version
설치되어 있지 않다면 npm으로 설치합니다.
npm install -g @anthropic-ai/claude-code
iTerm2 설치
macOS 기본 터미널(Terminal.app)로도 tmux를 쓸 수 있지만, iTerm2를 권장합니다. tmux 통합 기능이 있어서 tmux 패인을 네이티브 macOS 탭과 분할 화면으로 보여주거든요. 훨씬 편합니다.
iTerm2 최신 버전은 3.6.8(2026년 2월 26일 출시)입니다. macOS 12.4 이상이 필요합니다.
설치 방법 1: 공식 사이트에서 다운로드
iTerm2 공식 사이트(https://iterm2.com)에서 다운로드 버튼을 클릭하면 zip 파일이 받아집니다. 압축을 풀고 iTerm.app을 Applications 폴더로 옮기면 됩니다.
설치 방법 2: Homebrew로 설치
brew install --cask iterm2
설치 후 iTerm2를 실행합니다.
tmux 설치
tmux는 터미널 멀티플렉서입니다. 하나의 터미널 창 안에서 여러 세션을 만들고, 각 세션을 분할해서 쓸 수 있게 해줍니다. Claude Code 에이전트 팀의 split-pane 모드는 tmux 위에서 동작합니다.
brew install tmux
설치 확인을 합니다.
tmux -V
tmux 3.5a 같은 버전 정보가 나오면 정상입니다.
it2 CLI 설치 (iTerm2 split-pane 모드용)
에이전트 팀을 iTerm2의 네이티브 분할 화면으로 보려면 it2 CLI가 필요합니다. it2는 iTerm2의 Python API를 명령줄에서 제어하는 도구입니다. Python 3가 설치되어 있어야 하며, 설치되어 있지 않다면 brew install python3으로 먼저 설치합니다.
pip install it2
또는 uv를 사용한다면 이렇게 합니다.
uv tool install it2
it2가 제대로 작동하려면 iTerm2에서 Python API를 활성화해야 합니다.
- iTerm2를 실행합니다.
- 상단 메뉴에서 Settings (또는 Cmd-,)를 엽니다.
- General 탭을 클릭합니다.
- Magic 섹션을 찾습니다.
- Enable Python API 체크박스를 활성화합니다.
이 설정은 iTerm2를 재시작해야 반영됩니다.
iTerm2 기본 조작법
에이전트 팀이 자동으로 화면을 분할하지만, 수동으로 조작할 줄 알아야 문제가 생겼을 때 대처할 수 있습니다. 핵심 단축키만 정리하겠습니다.
화면 분할은 Cmd-D(좌우 분할)와 Cmd-Shift-D(상하 분할) 두 가지입니다. 분할된 패인 사이를 이동할 때는 Cmd-Opt-방향키를 쓰고, 특정 패인을 전체 화면으로 최대화하려면 Cmd-Shift-Enter를 누릅니다. 에이전트 팀 운영 중 특정 에이전트의 출력을 자세히 보고 싶을 때 유용합니다. 다시 Cmd-Shift-Enter를 누르면 원래 분할 상태로 돌아옵니다. 탭 관리는 Cmd-T(새 탭), Cmd-숫자(탭 전환), Cmd-W(탭 닫기)입니다.
tmux 기본 사용법
tmux를 처음 접하는 분을 위해 에이전트 팀 운영에 필요한 핵심만 정리합니다. tmux는 세션(Session), 윈도우(Window), 패인(Pane) 세 계층으로 구성됩니다. 세션은 가장 바깥 단위로 터미널을 닫아도 살아 있고, 윈도우는 세션 안의 탭, 패인은 윈도우 안에서 분할된 영역입니다. 에이전트 팀에서는 각 패인이 하나의 Claude Code 인스턴스를 실행합니다.
에이전트 팀에 필요한 핵심 명령어 5가지
tmux의 모든 명령은 접두사 키 Ctrl-B를 먼저 누른 뒤 실행합니다.
# 1. 세션 시작 (에이전트 팀용 세션 생성) tmux new-session -s my-agents # 2. 세션에서 나가기 (Ctrl-B d) - 세션은 유지됨 # 3. 세션 다시 연결 (나갔다가 돌아올 때) tmux attach -t my-agents # 4. 패인 이동: Ctrl-B 방향키 # 5. 현재 패인 최대화/복원: Ctrl-B z
화면 분할(Ctrl-B %, Ctrl-B ")과 윈도우 관리(Ctrl-B c, Ctrl-B n)도 있지만, 에이전트 팀의 split-pane 모드가 자동으로 패인을 생성하므로 직접 분할할 일은 많지 않습니다.
권장 설정 파일
~/.tmux.conf 파일을 만들어 에이전트 팀 운영에 최적화된 설정을 적용합니다. 각 줄의 주석에 설정 이유를 적어두었습니다.
cat << 'EOF' > ~/.tmux.conf set -g mouse on # 마우스로 패인 클릭 이동, 스크롤 set -g history-limit 50000 # 에이전트 출력이 많으므로 버퍼 넉넉히 set -g base-index 1 # 윈도우 번호 1부터 시작 setw -g pane-base-index 1 # 패인 번호 1부터 시작 set -sg escape-time 0 # 에스케이프 키 지연 제거 set -g default-terminal "tmux-256color" set -ag terminal-overrides ",xterm-256color:RGB" bind C-x setw synchronize-panes # Ctrl-B Ctrl-X로 동기 입력 토글 set-option -ag status-right '#{?pane_synchronized, #[bg=red]SYNC#[default],}' bind % split-window -h -c "#{pane_current_path}" bind '"' split-window -v -c "#{pane_current_path}" EOF
설정 적용은 tmux source-file ~/.tmux.conf 명령으로 합니다. 이미 tmux 세션이 실행 중이라면 즉시 반영되고, 세션이 없다면 다음 시작 시 자동 적용됩니다.
iTerm2의 tmux 통합 모드
iTerm2에는 tmux 통합 모드라는 기능이 있습니다. 보통 tmux를 쓰면 tmux 자체의 UI를 사용해야 합니다. 접두사 키(Ctrl-B)를 누르고, tmux의 상태 표시줄을 보며 작업하죠. 하지만 tmux 통합 모드를 켜면 tmux 세션이 iTerm2의 네이티브 탭과 분할 화면으로 표시됩니다.
tmux 통합 모드 시작
iTerm2에서 다음 명령을 실행합니다.
tmux -CC
이게 전부입니다. -CC 플래그가 tmux의 컨트롤 모드(Control Mode)를 활성화합니다. 실행하면 iTerm2가 tmux 세션을 감지하고, 새 창이 뜹니다. 이 창에서 하는 모든 탭 생성, 화면 분할이 tmux 세션과 동기화됩니다.
다음은 실제로 tmux -CC를 실행한 화면입니다. 왼쪽 원래 창에 Command Menu가 표시되고, 오른쪽에 tmux 통합 모드의 새 창이 열립니다. 새 창에서 Cmd-D로 분할하면 tmux 패인이 iTerm2 네이티브 분할 화면으로 표시됩니다.
원래 창의 Command Menu에서 esc를 누르면 tmux 세션에서 깔끔하게 분리(detach)되고, 새 창에서의 분할 상태는 tmux 세션에 보존됩니다. 에이전트 팀을 운영할 때는 이 새 창에서 Claude Code를 시작하면 됩니다. teammateMode가 "tmux"로 설정되어 있으면 Claude Code가 알아서 tmux 패인을 생성하고, tmux 통합 모드 덕분에 iTerm2 네이티브 분할 화면으로 자동 표시됩니다. 직접 Cmd-D로 분할할 필요 없이 동료 수만큼 자동으로 분할되는 것입니다.
기존 tmux 세션에 연결하려면 이렇게 합니다.
tmux -CC attach
tmux 통합 모드의 장점
tmux 통합 모드에서는 tmux의 접두사 키(Ctrl-B)를 쓸 필요가 없습니다. iTerm2의 네이티브 단축키를 그대로 쓰면 됩니다.
Cmd-D: 수직 분할 (tmux의Ctrl-B %와 동일)Cmd-Shift-D: 수평 분할 (tmux의Ctrl-B "와 동일)Cmd-T: 새 탭 (tmux의 새 윈도우)Cmd-W: 탭 닫기
마우스 스크롤, 트랙패드 제스처, Cmd-F 검색까지 모두 네이티브로 동작합니다. tmux의 기능은 그대로 유지하면서 macOS답게 쓸 수 있는 셈입니다.
원격 서버에서도 사용 가능
원격 서버에서도 쓸 수 있다는 게 또 다른 장점입니다.
ssh my-server -t tmux -CC new-session -A -s main
원격 서버의 tmux 세션이 로컬 iTerm2의 네이티브 탭/패인으로 표시됩니다. SSH 연결이 끊어져도 tmux 세션은 서버에서 계속 실행되고요.
에이전트 팀 활성화하기
이제 본격적으로 Claude Code 에이전트 팀을 활성화합니다.
settings.json 설정
Claude Code의 설정 파일에 에이전트 팀 기능을 활성화하는 환경 변수를 추가합니다. 설정 파일은 두 군데에 있을 수 있습니다.
사용자 전역 설정 (모든 프로젝트에 적용)
# 설정 파일 위치 ~/.claude/settings.json
프로젝트별 설정 (해당 프로젝트에만 적용)
# 프로젝트 루트 .claude/settings.json
어느 쪽이든 다음 내용을 추가합니다.
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
이것만으로 에이전트 팀 기능이 활성화됩니다.
팀원 모드 설정
에이전트 팀은 두 가지 모드로 동작합니다. 어떤 모드를 선택할지는 환경과 목적에 따라 달라집니다.
in-process 모드에서는 모든 동료가 하나의 터미널 안에서 실행됩니다. 화면 분할 없이 Shift-Down 키로 동료 사이를 전환하는 방식이죠. tmux가 설치되지 않은 환경에서도 동작하므로, tmux 설정이 어렵거나 원격 서버에서 간단히 팀을 구성할 때 적합합니다. 다만 한 번에 한 동료의 출력만 볼 수 있어서 여러 에이전트의 진행 상황을 동시에 파악하기 어렵습니다. 세션을 재개하면 in-process 동료가 복원되지 않는다는 한계도 있고요. 작업 도중 세션이 끊기면 동료를 다시 생성해야 합니다.
split-pane 모드에서는 각 동료가 별도의 tmux 패인 또는 iTerm2 패인에서 실행됩니다. 각 에이전트의 작업 상황을 동시에 한눈에 볼 수 있고, 특정 패인만 최대화해서 자세히 확인할 수도 있습니다. tmux의 세션 지속성 덕분에 터미널을 닫았다가 다시 연결해도 화면 구성이 유지되고요. 이 글에서는 split-pane 모드를 권장합니다.
split-pane 모드를 사용하려면 settings.json에 다음을 추가합니다.
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, "teammateMode": "tmux" }
teammateMode를 "tmux"로 설정하면 tmux의 화면 분할을 사용합니다. iTerm2의 tmux 통합 모드(tmux -CC)에서 실행하면 iTerm2 네이티브 패인으로 표시됩니다.
CLI 플래그로 모드 지정
settings.json을 수정하지 않고 실행 시 모드를 지정할 수도 있습니다.
# in-process 모드 claude --teammate-mode in-process # tmux split-pane 모드 claude --teammate-mode tmux
첫 번째 에이전트 팀 만들기
설정이 끝났으니 실제로 에이전트 팀을 만들어 보겠습니다.
단계 1: tmux 세션 시작
iTerm2를 열고 tmux 통합 모드로 시작합니다.
tmux -CC new-session -s agent-team
새 iTerm2 창이 열립니다. 이 창에서 Claude Code를 시작합니다.
단계 2: Claude Code 시작
claude
Claude Code가 시작되면 에이전트 팀을 만들어 달라고 요청합니다.
단계 3: 팀 생성 요청
Claude Code 프롬프트에서 다음과 같이 입력합니다.
3명의 팀원으로 팀을 구성해 주세요. - frontend: React 컴포넌트 개발 담당 - backend: API 엔드포인트 개발 담당 - tester: 테스트 코드 작성 담당
Claude Code(팀 리드)가 3명의 동료를 생성합니다. split-pane 모드라면 iTerm2 화면이 자동으로 4개로 분할됩니다. 리드 1개 + 동료 3개입니다.
팀이 생성되면 화면은 다음과 같은 레이아웃으로 분할됩니다.
+---------------------------+---------------------------+ | | | | 리드 (Team Lead) | frontend 동료 | | 전체 작업 조율 | React 컴포넌트 작업 | | | | +---------------------------+---------------------------+ | | | | backend 동료 | tester 동료 | | API 엔드포인트 작업 | 대기 → 테스트 작성 | | | | +---------------------------+---------------------------+
각 패인의 상단에는 동료 이름이 표시됩니다. 동료가 작업을 시작하면 파일 읽기, 코드 작성, 도구 호출 로그가 실시간으로 스크롤됩니다. 리드 패인에서는 작업 배분 상황과 동료 간 메시지 교환 내역이 표시됩니다. 특정 동료의 작업을 자세히 보려면 해당 패인을 클릭한 뒤 Cmd-Shift-Enter로 최대화하면 됩니다. tester 동료처럼 다른 동료의 작업 완료를 기다리는 경우, 패인에 "대기 중" 상태가 표시되다가 의존 작업이 끝나면 자동으로 작업을 시작합니다.
단계 4: 작업 지시
팀이 구성되면 리드에게 작업을 지시합니다.
사용자 프로필 페이지를 만들어 주세요. - frontend 팀원: UserProfile 컴포넌트를 만들어 주세요. 이름, 이메일, 프로필 사진을 표시합니다. - backend 팀원: /api/users/:id 엔드포인트를 만들어 주세요. GET으로 사용자 정보를 반환합니다. - tester 팀원: frontend와 backend가 완료되면 통합 테스트를 작성해 주세요.
리드가 각 동료에게 작업을 배분하고, 동료들이 독립적으로 작업을 진행합니다. 테스터는 다른 동료의 작업이 끝나길 기다렸다가 테스트를 작성합니다.
단계 5: 팀 정리
작업이 끝나면 팀을 정리합니다.
팀을 정리해 주세요.
리드가 모든 동료를 순서대로 종료합니다. 동료가 먼저 종료된 후 리드가 종료됩니다.
동료별 모델 지정하기
동료마다 다른 모델을 지정할 수도 있습니다. 비용이 많이 드는 작업에는 Opus를, 단순 작업에는 Sonnet을 배정하면 비용을 절약할 수 있거든요.
4명의 팀원으로 팀을 구성해 주세요. - architect: 아키텍처 설계 담당. Opus 모델을 사용해 주세요. - frontend: UI 컴포넌트 개발 담당. Sonnet 모델을 사용해 주세요. - backend: API 개발 담당. Sonnet 모델을 사용해 주세요. - reviewer: 코드 리뷰 담당. Opus 모델을 사용해 주세요.
판단이 중요한 작업(아키텍처 설계, 코드 리뷰)에 Opus를, 구현 작업에 Sonnet을 배정하는 게 비용 면에서 효율적입니다.
계획 승인 워크플로
에이전트가 바로 코드를 작성하는 것이 불안하다면, 계획 승인 워크플로를 사용할 수 있습니다.
architect 팀원을 만들어 주세요. 이 팀원은 코드 변경 전에 반드시 계획을 세우고, 내 승인을 받은 후에만 변경을 진행해야 합니다.
이렇게 하면 architect 동료는 코드를 바로 수정하지 않고, 먼저 계획을 리드에게 보고합니다. 리드가 사용자에게 계획을 보여주고, 승인하면 그때 실행합니다.
incident.io 팀이 이 패턴을 씁니다. Plan Mode에서 먼저 계획을 세우고, 검토한 뒤 실행하는 방식으로 무단 변경 위험을 줄였다고 하고요.
수동으로 에이전트 팀 구성하기: tmux 직접 제어
에이전트 팀 기능을 쓰지 않고, tmux와 Claude Code를 직접 조합해서 멀티 에이전트 환경을 구성할 수도 있습니다. 에이전트 팀 기능이 실험적이라 불안하거나, 더 세밀한 제어가 필요할 때 유용합니다.
시나리오: 3개 에이전트 병렬 실행
프로젝트의 세 영역을 각각 다른 Claude Code 인스턴스에 맡기겠습니다.
단계 1: tmux 세션 시작
tmux new-session -s dev-team
단계 2: 패인 분할
# 수직 분할 (좌우) # Ctrl-B % # 오른쪽 패인을 다시 수평 분할 (상하) # Ctrl-B "
이제 3개의 패인이 있습니다. 왼쪽 하나, 오른쪽 상하 두 개입니다.
단계 3: 각 패인에서 Claude Code 시작
첫 번째 패인(왼쪽)에서 프론트엔드 작업을 시작합니다.
claude -p "src/components 디렉토리의 UserProfile 컴포넌트를 만들어 주세요. 이름, 이메일, 프로필 사진을 표시하는 React 컴포넌트입니다." \ --allowedTools "Read,Write,Edit,Glob,Grep"
Ctrl-B 방향키로 두 번째 패인(오른쪽 위)으로 이동합니다.
claude -p "src/api/users.ts에 GET /api/users/:id 엔드포인트를 만들어 주세요. 데이터베이스에서 사용자 정보를 조회해서 반환합니다." \ --allowedTools "Read,Write,Edit,Glob,Grep,Bash"
Ctrl-B 방향키로 세 번째 패인(오른쪽 아래)으로 이동합니다.
claude -p "src/tests 디렉토리에 UserProfile 컴포넌트와 users API의 통합 테스트를 작성해 주세요." \ --allowedTools "Read,Write,Edit,Glob,Grep,Bash"
세 에이전트가 동시에 작업을 진행합니다.
synchronize-panes로 동시 명령 전송
여러 패인에 같은 명령을 동시에 보내야 할 때가 있습니다. 예를 들어 모든 에이전트를 동시에 시작하거나, 모든 에이전트에게 같은 환경 변수를 설정할 때입니다.
tmux의 synchronize-panes 기능을 사용합니다.
Ctrl-B :setw synchronize-panes on
이제 어느 패인에서 입력하든 모든 패인에 동시에 전달됩니다. 작업이 끝나면 반드시 꺼야 합니다.
Ctrl-B :setw synchronize-panes off
앞서 .tmux.conf에 bind C-x setw synchronize-panes 설정을 넣었다면, Ctrl-B Ctrl-X로 토글할 수 있습니다.
Git 워크트리로 충돌 없이 병렬 작업하기
여러 에이전트가 같은 디렉토리에서 동시에 파일을 수정하면 충돌이 발생합니다. 이를 방지하는 가장 확실한 방법이 Git 워크트리(worktree)입니다.
Git 워크트리란
Git 워크트리는 하나의 저장소에서 여러 작업 디렉토리를 만드는 기능입니다. 각 워크트리는 별도의 브랜치를 체크아웃하고, 독립적으로 파일을 수정할 수 있습니다. 하지만 Git 이력은 공유합니다.
Claude Code의 --worktree 플래그
Claude Code에는 워크트리를 자동으로 생성하는 --worktree 플래그가 있습니다.
# 첫 번째 터미널/패인 claude --worktree feature-auth # 두 번째 터미널/패인 claude --worktree feature-profile # 세 번째 터미널/패인 claude --worktree bugfix-login
각 Claude Code 인스턴스가 독립된 워크트리에서 실행됩니다. 워크트리는 <프로젝트>/.claude/worktrees/<이름> 경로에 생성되고, 브랜치명은 worktree-<이름>이 됩니다.
작업이 끝나면 변경사항이 없는 워크트리는 자동으로 삭제됩니다. 변경사항이 있으면 보존할지 삭제할지 묻습니다.
수동 워크트리 생성
Claude Code의 --worktree 대신 Git 워크트리를 직접 만들 수도 있습니다.
# 워크트리 생성 git worktree add ../my-project-auth -b feature/auth git worktree add ../my-project-profile -b feature/profile git worktree add ../my-project-bugfix -b bugfix/login # 각 워크트리에서 Claude Code 시작 cd ../my-project-auth && claude cd ../my-project-profile && claude cd ../my-project-bugfix && claude
수동으로 만든 워크트리는 의존성을 별도로 설치해야 합니다.
cd ../my-project-auth && npm install cd ../my-project-profile && npm install
워크트리 정리
작업이 끝난 워크트리는 정리합니다.
# 워크트리 목록 확인 git worktree list # 워크트리 제거 git worktree remove ../my-project-auth
실전 시나리오: Todo 앱 병렬 개발
지금까지 배운 것을 종합해서, 실제 프로젝트를 에이전트 팀으로 개발하는 전체 과정을 보겠습니다.
프로젝트 구조
간단한 Todo 앱을 만듭니다. React 프론트엔드 + Express 백엔드 구성입니다.
단계 1: 프로젝트 초기화
mkdir todo-app && cd todo-app npm init -y git init
단계 2: CLAUDE.md 작성
프로젝트 루트에 CLAUDE.md를 작성합니다. 모든 에이전트가 이 파일을 읽고 프로젝트 컨텍스트를 파악합니다.
# Todo App React + Express로 구성된 Todo 애플리케이션입니다. ## 기술 스택 - Frontend: React 18, TypeScript, Tailwind CSS - Backend: Express, TypeScript, SQLite - Test: Vitest, Testing Library ## 디렉토리 구조 - src/client/ - React 프론트엔드 - src/server/ - Express 백엔드 - src/shared/ - 공유 타입 정의 - src/tests/ - 테스트 코드 ## 규칙 - 모든 코드는 TypeScript로 작성합니다. - API 응답은 src/shared/types.ts의 타입을 사용합니다. - 컴포넌트는 함수형으로 작성합니다.
단계 3: 에이전트 팀 설정
.claude/settings.json을 만듭니다.
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, "teammateMode": "tmux" }
단계 4: tmux에서 에이전트 팀 시작
# iTerm2에서 tmux 통합 모드 시작 tmux -CC new-session -s todo-team # Claude Code 시작 claude
단계 5: 팀 구성 및 작업 지시
Claude Code에서 다음과 같이 입력합니다.
Todo 앱을 만들겠습니다. 3명의 팀원을 구성해 주세요. 1. shared 팀원 (Sonnet): 먼저 src/shared/types.ts에 Todo 타입을 정의해 주세요. - Todo: { id: string, title: string, completed: boolean, createdAt: string } - CreateTodoInput: { title: string } - UpdateTodoInput: { title?: string, completed?: boolean } 2. backend 팀원 (Sonnet): shared 팀원이 타입 정의를 마치면, src/server/에 Express API를 만들어 주세요. - GET /api/todos - 전체 목록 - POST /api/todos - 새 Todo 생성 - PATCH /api/todos/:id - Todo 수정 - DELETE /api/todos/:id - Todo 삭제 - SQLite를 사용합니다. 3. frontend 팀원 (Sonnet): shared 팀원이 타입 정의를 마치면, src/client/에 React UI를 만들어 주세요. - TodoList 컴포넌트: Todo 목록 표시 - TodoItem 컴포넌트: 개별 Todo (체크박스, 삭제 버튼) - AddTodo 컴포넌트: 새 Todo 입력 폼 - Tailwind CSS로 스타일링합니다.
다음 그림은 이 작업의 전체 흐름을 보여줍니다. shared 담당이 먼저 타입을 정의하고, 그 결과가 backend과 frontend에 동시에 전달되어 병렬로 작업이 진행됩니다.
리드가 작업을 조율합니다. shared 팀원이 먼저 타입을 정의하고, 그 결과를 backend와 frontend 팀원에게 전달하죠. backend와 frontend는 동시에 작업합니다.
작업 진행 확인
iTerm2 화면에서 4개 패인이 동시에 작업하는 모습을 볼 수 있습니다. 먼저 shared 패인에서 타입 정의 파일이 생성되고, 완료되면 backend와 frontend 패인이 동시에 활성화되어 파일을 생성하기 시작합니다. 특정 패인을 자세히 보려면 Cmd-Shift-Enter로 해당 패인을 최대화합니다.
예상 결과물
팀 작업이 완료되면 다음과 같은 파일 구조가 생성됩니다.
todo-app/ src/ shared/ types.ts # Todo, CreateTodoInput, UpdateTodoInput 타입 server/ index.ts # Express 서버 진입점 routes/ todos.ts # CRUD API 라우트 db/ sqlite.ts # SQLite 연결 및 초기화 client/ App.tsx # 메인 앱 컴포넌트 components/ TodoList.tsx # Todo 목록 표시 TodoItem.tsx # 개별 Todo (체크박스, 삭제) AddTodo.tsx # 새 Todo 입력 폼 tests/ todos.test.ts # API 통합 테스트 TodoList.test.tsx # 컴포넌트 테스트 package.json tsconfig.json CLAUDE.md
실전에서 주의할 점이 있습니다. 타입 정의가 완료되기 전에 frontend나 backend 동료가 먼저 작업을 시작하면 타입 임포트 에러가 발생합니다. 방지하려면 위 프롬프트처럼 "shared 팀원이 타입 정의를 마치면"이라는 순서 조건을 명시해야 합니다. 리드가 이 순서를 인식하고 shared 팀원의 작업 완료를 기다린 뒤 나머지 팀원에게 작업을 전달하거든요.
incident.io 사례를 참고하면, 이 정도 규모의 작업(3~4개 에이전트, CRUD 앱 생성)은 약 10~15분 안에 완료됩니다. 순차적으로 한 에이전트에게 모든 작업을 맡기면 30분 이상 걸릴 수 있는 분량입니다.
claude-squad: 더 편한 멀티 에이전트 관리
에이전트 팀과 claude-squad는 용도가 다릅니다. 에이전트 팀은 동료끼리 메시지를 주고받으며 협업하는 구조이고, claude-squad는 각 세션이 완전히 독립적으로 동작하죠. 에이전트 간 조율이 필요한 작업(예: 타입 정의 완료 후 프론트엔드 시작)에는 에이전트 팀을, 서로 관련 없는 작업을 병렬로 돌릴 때(예: 서로 다른 버그 수정 3건)는 claude-squad를 선택하면 됩니다.
claude-squad는 여러 Claude Code 세션을 하나의 TUI(Terminal UI)에서 관리하는 오픈소스 도구입니다. 각 세션을 격리된 Git 워크스페이스에서 실행하기 때문에 세션 간 파일 충돌 없이 독립적으로 작업할 수 있습니다.
설치
brew install claude-squad
편의를 위해 단축 명령을 만듭니다.
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"
사용법
cs
실행하면 TUI가 뜹니다. 주요 단축키는 다음과 같습니다.
n: 새 Claude Code 세션 생성Enter: 선택한 세션에 접속s: 현재 세션의 변경사항을 Git 커밋/푸시r: 일시 중지된 세션 재개d: 세션 삭제
Claude Code 외에 Aider, Codex 같은 다른 AI 도구의 세션도 함께 관리할 수 있다는 점도 장점이고요.
비용과 성능
멀티 에이전트를 돌리면 당연히 비용이 늘어납니다. 참고할 만한 실측 데이터가 있습니다.
incident.io 팀의 사례에 따르면, 4~5개 에이전트를 병렬로 실행했을 때 하나의 UI 컴포넌트 개발에 약 10분이 걸렸습니다. 기존에 2시간으로 예상했던 작업입니다. Makefile 최적화 작업에서는 18% 성능 향상을 달성했고, 비용은 약 8달러였습니다.
에이전트 수를 늘린다고 무조건 빨라지지는 않습니다. 실전에서는 3~5개가 적정이라는 의견이 많고, 그 이상 늘리면 에이전트 간 충돌과 조율 비용이 커져서 오히려 느려질 수 있습니다.
비용을 줄이려면 동료별로 모델을 다르게 지정하는 게 좋습니다. 판단이 중요한 역할(아키텍트, 리뷰어)에는 Opus를, 구현 위주 역할에는 Sonnet을 배정하면 꽤 차이가 납니다.
안전하게 운영하기
멀티 에이전트 환경에서는 안전 수칙이 더 중요합니다. 여러 에이전트가 동시에 파일을 수정하고 명령을 실행하기 때문입니다.
--dangerously-skip-permissions 사용 시 주의
이 플래그는 모든 권한 확인을 건너뜁니다. 에이전트가 파일 수정, 명령 실행, 네트워크 접근 등을 승인 없이 자동으로 수행합니다. 에이전트 팀 리드가 이 플래그로 시작하면 모든 동료도 같은 권한을 상속합니다.
편리하지만 위험합니다. eesel AI의 조사에 따르면, 이 플래그를 사용한 개발자 중 32%가 의도하지 않은 파일 수정을, 9%가 데이터 손실을 경험했다고 합니다.
안전하게 쓰려면 몇 가지 원칙이 있습니다.
- 프로덕션 코드베이스에서는 사용하지 않습니다.
- 반드시 Git으로 버전 관리 중인 프로젝트에서만 사용합니다.
- 가능하면 Docker 컨테이너 안에서 실행합니다.
- 중요한 작업 전에
git stash또는 브랜치를 분리합니다.
Git 워크트리 사용 권장
여러 에이전트가 같은 디렉토리에서 작업하면 파일 충돌이 일어납니다. 반드시 워크트리나 에이전트 팀의 격리 기능을 사용해서 각 에이전트의 작업 영역을 분리해 주세요.
정기적 커밋
에이전트가 작업하는 동안 정기적으로 커밋하는 습관을 들여야 합니다. 뭔가 잘못됐을 때 되돌릴 수 있어야 하거든요.
트러블슈팅
에이전트 팀을 처음 설정할 때 흔히 겪는 문제와 해결 방법입니다.
동료가 화면에 표시되지 않을 때
tmux가 PATH에 있는지 확인합니다.
which tmux
결과가 나오지 않으면 tmux가 설치되지 않았거나 PATH에 없는 것입니다. brew install tmux로 설치합니다.
iTerm2 split-pane이 동작하지 않을 때
- it2 CLI가 설치되어 있는지 확인합니다.
pip install it2 - iTerm2에서 Python API가 활성화되어 있는지 확인합니다. Settings > General > Magic > Enable Python API
- iTerm2를 재시작합니다.
tmux -CC 실행 시 에러가 날 때
기존 tmux 세션과 충돌할 수 있습니다. 기존 세션을 정리합니다.
tmux ls tmux kill-server tmux -CC
에이전트 간 파일 충돌이 발생할 때
에이전트들이 같은 파일을 동시에 수정하면 충돌이 발생합니다. 해결 방법은 다음과 같습니다.
- 각 에이전트에게 서로 다른 파일/디렉토리를 담당하도록 명확히 지시합니다.
- Git 워크트리를 사용해서 물리적으로 작업 영역을 분리합니다.
- 공유 파일(타입 정의 등)은 한 에이전트가 먼저 작성하고, 나머지가 그 후에 작업하도록 순서를 정합니다.
마무리
에이전트 팀은 Claude Code로 작업을 병렬화하는 방법입니다. incident.io 사례에서 2시간 예상 작업이 10분으로 줄어든 것은 순차 작업이 병렬로 전환되었기 때문이죠. 에이전트 수를 늘리는 것보다 각 에이전트의 작업 영역을 명확히 분리하고 파일 충돌을 방지하는 게 더 중요합니다.
아직 실험적 기능이라는 점은 기억해야 합니다. 세션 재개 시 in-process 동료가 복원되지 않고, 중첩 팀은 지원되지 않습니다. 그래도 tmux와 iTerm2를 조합하면 충분히 안정적인 멀티 에이전트 환경을 만들 수 있습니다.
이 글의 핵심을 세 줄로 정리합니다.
brew install tmux+ settings.json 설정으로 시작하되, 에이전트 간 파일 충돌 방지가 운영의 핵심입니다. 워크트리나 디렉토리 분리를 반드시 적용합니다.tmux -CC로 iTerm2 통합 모드를 쓰면 네이티브 macOS 경험을 유지하면서 tmux의 세션 관리 기능을 누릴 수 있습니다.- 에이전트 수는 3~5개가 적절합니다. 그 이상은 조율 비용이 커져서 오히려 느려집니다.
직접 따라해 보시기 바랍니다. 한번 세팅해두면 순차 작업으로 돌아가기 싫어질 겁니다.
참고 자료
- Claude Code Agent Teams 공식 문서: https://code.claude.com/docs/en/agent-teams
- Claude Code Subagents 공식 문서: https://code.claude.com/docs/en/sub-agents
- Claude Code Headless Mode 공식 문서: https://code.claude.com/docs/en/headless
- Claude Code Git Worktrees 공식 문서: https://code.claude.com/docs/en/common-workflows
- iTerm2 공식 문서: https://iterm2.com/documentation-one-page.html
- iTerm2 tmux Integration: https://iterm2.com/documentation-tmux-integration.html
- incident.io 사례: https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees
- claude-squad GitHub: https://github.com/smtg-ai/claude-squad
댓글
댓글을 작성하려면 이 필요합니다.