📌 IN THIS ISSUE
Agent Teams는 Claude Code의 실험적 멀티 에이전트 시스템입니다. 한 명의 클로드가 모든 일을 처리하는 대신, 여러 인스턴스가 동시에 협업하면서 서로 메시지 주고받고 공유 작업 목록을 관리합니다. 이 글은 활성화 방법 → 첫 팀 만들기 → 실전 운영까지 손 잡고 안내합니다.
안녕하세요, 봄내AI해적단 선장 이장환입니다. 시리즈 네 번째 글이에요.
지금까지 우리는 한 명의 Claude를 잘 쓰는 법을 배웠습니다. 그런데 이런 상황 한 번쯤 겪어보셨죠?
가능합니다. Agent Teams를 쓰면 말이죠.
이건 단순히 여러 클로드를 띄우는 게 아니에요. 한 명이 팀 리더가 되고, 나머지는 팀원으로 일하면서, 공유 작업 목록을 통해 자율적으로 협업하는 시스템입니다. 토론도 하고, 서로 가설을 반박도 하고, 작업을 나눠 가지기도 합니다. 진짜 개발팀처럼.
⊙ 시작 전 안내
이 가이드는 10개 챕터로 구성됩니다. 실험적 기능이라 약간의 인내심이 필요하지만, 한 번 익히면 작업 속도가 차원이 달라집니다.
Agent Teams란 정확히 무엇인가?
공식 문서의 정의를 옮겨오면:
핵심 특징을 4가지로 정리하면:
👑 Lead-Teammate 구조
한 세션이 팀 리더(lead)가 되어 작업 분해, 할당, 결과 종합. 나머지는 팀원(teammates)로 일함.
📋 공유 작업 목록
모든 팀원이 동일한 task list 보고 쓸 수 있음. 칸반 보드처럼 작업 가져가고 완료 표시.
💬 팀원 간 직접 메시지
리더 통하지 않고 팀원끼리 직접 대화. 가설 반박, 정보 공유, 협의 모두 가능.
🔍 직접 개입 가능
사용자가 개별 팀원과 직접 대화 가능. Shift+Down으로 팀원 전환 후 추가 지시 가능.
⚠️ 실험적 기능 안내 · Agent Teams는 현재 기본 비활성이며, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수로 활성화해야 합니다. Claude Code v2.1.32 이상 필수.
Subagents와 뭐가 다른가?
"잠깐, Subagents도 멀티 에이전트 아닌가요?" 맞습니다. 그런데 결정적으로 다른 게 있어요. 통신 구조입니다.
Subagents
- 메인 에이전트가 모든 통신을 통제
- 서브에이전트끼리 대화 불가
- 작업 결과만 보고하고 종료
- 토큰 비용 낮음
Agent Teams
- 공유 작업 목록으로 자율 조정
- 팀원끼리 직접 메시지 가능
- 가설 반박, 협의, 토론 가능
- 토큰 비용 3-4배 높음
💡 한 줄 결론 · "작업 결과만 받으면 되는 경우"는 Subagents, "팀원들이 서로 정보 주고받고 협업해야 하는 경우"는 Agent Teams.
구체적인 선택 기준은 다음과 같습니다.
활성화 — 환경변수 한 줄.
실험적 기능이라 기본 비활성입니다. 켜는 방법은 두 가지인데, 두 번째(settings.json)를 추천합니다.
방법 A · 셸 환경변수
터미널에서 일시적으로 켜고 싶다면:
└ 터미널 닫으면 사라집니다. 매번 켜기 귀찮으면 ~/.zshrc 또는 ~/.bashrc에 추가하면 영구.
방법 B · settings.json (추천)
이 방법이 가장 깔끔합니다. Claude Code 설정 파일에 박제하면 매번 신경 안 써도 됩니다.
파일 열기
설정 파일은 두 군데 중 하나에 있습니다:
~/.claude/settings.json
# 프로젝트 (이 프로젝트에만 적용)
.claude/settings.json
env 키 추가
파일에 다음 내용을 넣습니다. 기존에 다른 설정이 있다면 env 키만 병합:
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Claude Code 재시작 후 확인
저장 후 claude 재시작. 그리고 다음을 입력해서 켜졌는지 확인:
클로드가 "네, 사용 가능합니다"라고 답하면 OK.
✓ 시스템 요구사항
claude --version으로 버전 확인 가능. 낮으면 npm update -g @anthropic-ai/claude-code 또는 네이티브 인스톨러 재실행.
첫 팀 만들기 — 5분 코스.
설정이 끝났으니 진짜로 팀을 만들어봅시다. 자연어로 부탁하는 게 전부입니다. 별도 명령이나 설정 파일 없어요.
프로젝트 폴더에서 Claude Code 실행
$ claude
팀 생성 요청
자연어로 팀의 구조와 작업을 설명합니다. 공식 문서의 예시를 그대로 따라가봅시다:
└ Claude가 자동으로 팀 구성을 결정하거나, 만들기 전에 확인을 요청합니다.
팀이 자동으로 구성됨
다음 일들이 자동으로 일어납니다:
✓ 3명의 teammate 인스턴스 spawn
✓ 각 teammate에게 역할 + 컨텍스트 전달
✓ 리더 터미널에 팀원 목록 표시
✓ 팀원들 동시에 작업 시작
팀원과 대화 / 모니터링
기본 모드(in-process)에서는 리더 터미널 한 곳에서 모든 팀원과 상호작용합니다.
작업 완료 후 팀 정리
팀 작업이 끝나면 리더에게 정리를 요청합니다:
└ 반드시 리더에게 요청해야 합니다. 팀원에게 시키면 컨텍스트가 꼬여서 리소스가 깔끔히 안 비워집니다.
디스플레이 모드 — In-process vs Split panes.
팀을 만들면 화면 표시 방식이 두 가지 있습니다. 각각 어울리는 상황이 달라요.
📺 In-process 모드
모든 팀원이 하나의 메인 터미널 안에서 돌아갑니다. Shift+Down으로 팀원을 순회하며 메시지 전송.
│ 👑 Lead Agent │
│ > 작업 진행 중... │
│ │
│ ▸ M-1 (UX) [idle] │
│ ▸ M-2 (Arch) [working]│
│ ▸ M-3 (Devil) [working]│
└─────────────────────────┘
- 설정 필요 없음, 어디서나 동작
- 한 화면에서 전체 흐름 파악
- 팀원 출력이 섞이면 혼란
- 여러 팀원 동시에 안 보임
🪟 Split panes 모드
각 팀원이 독립된 창(pane)에서 동작. tmux 또는 iTerm2 필요.
│ 👑 Lead │ M-1 UX │
│ │ │
│ Working..│ Working..│
├──────────┼──────────┤
│ M-2 Arch │ M-3 DA │
│ │ │
│ Working..│ Idle │
└──────────┴──────────┘
- 모든 팀원 작업을 동시에 관찰
- 특정 팀원 클릭만으로 대화
- tmux/iTerm2 설치 필요
- Windows Terminal / VS Code 통합 터미널 미지원
모드 강제 설정하기
기본값은 "auto" — tmux 안에서 띄우면 split panes, 아니면 in-process로 자동 결정됩니다. 강제로 고정하려면 ~/.claude/settings.json에 추가:
"teammateMode": "in-process" // 또는 "tmux", "auto"
}
한 세션만 임시로 바꾸려면:
💡 tmux 설치하기 (macOS)
Linux는 apt install tmux 또는 dnf install tmux. Windows의 경우 split panes 지원 안 됨, in-process 모드로 가야 함.
팀 컨트롤 — 5가지 핵심 기술.
팀을 만들었으면 이제 잘 굴려야겠죠. 5가지만 익히면 됩니다.
팀원 수와 모델 지정
기본적으로 클로드가 작업 난이도에 따라 알아서 팀원 수를 정합니다. 명시적으로 지정하려면:
모델 주의사항: 팀원들은 기본적으로 리더의 /model 설정을 상속하지 않습니다. /config에서 "Default teammate model" 따로 설정 가능.
Plan 승인 강제
위험한 작업이라면, 팀원이 계획 단계에서 멈추고 리더 승인을 받게 만들 수 있습니다:
팀원이 plan을 제출하면 리더가 검토하고 승인 또는 피드백과 함께 거절. 거절되면 팀원이 plan을 수정해서 재제출.
팀원과 직접 대화
각 팀원은 독립된 Claude Code 세션입니다. 리더 거치지 않고 직접 메시지 보낼 수 있어요.
Shift+Down으로 팀원 순회 → 메시지 입력 → 전송
팀원의 pane을 클릭하면 그 세션과 직접 대화 시작
작업 할당과 자가 클레임
공유 작업 목록의 작업은 3가지 상태: pending → in progress → completed. 작업에는 의존성도 설정 가능 (선행 작업 완료 전까지 클레임 불가).
"이 작업은 backend-agent에게, 저 작업은 frontend-agent에게 줘"
현재 작업 끝낸 팀원이 알아서 다음 가능한 작업 가져감 (race condition은 파일 락으로 방지)
팀원 종료 / 팀 정리
아키텍처 깊게 보기.
겉으로 보면 "여러 클로드가 같이 일한다"지만, 내부 아키텍처를 알아두면 디버깅과 최적화에 큰 도움이 됩니다.
팀의 4가지 구성 요소
저장 위치
팀과 작업 목록은 로컬에 저장됩니다:
~/.claude/teams/{team-name}/config.json
# 작업 목록
~/.claude/tasks/{team-name}/
컨텍스트와 통신 메커니즘
각 팀원은 자신만의 컨텍스트 윈도우를 가집니다. spawn될 때:
- 일반 세션처럼 CLAUDE.md, MCP 서버, Skills를 자동 로드
- 리더의 spawn 프롬프트를 받음 (어떤 역할인지)
- 리더의 대화 히스토리는 상속받지 않음 — 필요하면 spawn 프롬프트에 명시
- 완료/멈춤 시 리더에게 자동 알림
- 이름으로 다른 팀원에게 직접 메시지 전송
Subagent 정의를 팀원 역할로 재사용
이미 만들어둔 Subagent가 있다면, 팀원 역할로 그대로 가져올 수 있어요. 예를 들어 .claude/agents/security-reviewer.md에 정의한 보안 리뷰어를:
팀원은 그 정의의 tools 화이트리스트와 model을 따르고, 정의의 본문이 팀원의 시스템 프롬프트에 추가됩니다. "한 번 정의, 두 곳에서 활용" 패턴이에요.
실전 사용 케이스 3종.
이론은 충분합니다. 진짜로 효과 보는 케이스 세 가지. 그대로 복붙해서 쓰셔도 돼요.
베스트 프랙티스 6가지.
충분한 컨텍스트 제공
팀원은 리더의 대화 히스토리를 상속받지 않아요. spawn 프롬프트에 작업별 디테일을 명시: 어떤 파일을, 어떤 관점으로, 어떤 형식으로 보고할지.
팀 크기는 3-5명으로 시작
토큰 비용 선형 증가, 협조 오버헤드도 증가, 일정 수 이상은 수익체감. 5-6개 task를 한 팀원이 맡는 정도가 효율적.
작업 크기 적정선
너무 작으면 협조 오버헤드가 이득 초과. 너무 크면 체크인 없이 헛수고 위험. 적정선: "한 함수, 한 테스트 파일, 한 리뷰" 같은 자체완결 단위.
리서치/리뷰부터 시작
처음이라면 코드 안 쓰는 작업부터 시도. PR 리뷰, 라이브러리 조사, 버그 분석 같은 거. 병렬 탐색의 진가를 코드 충돌 걱정 없이 체감.
파일 충돌 회피
두 팀원이 같은 파일 편집하면 한 쪽이 덮어씁니다. 각 팀원이 다른 파일/디렉토리를 소유하도록 작업 분배. CLAUDE.md에 영역 못 박아두기.
모니터링하고 조정
방치하지 마세요. 진행 상황 체크인, 잘못된 방향 조정, 발견사항 종합. "리더가 일하기 시작하면 멈추라"고 지시 — 위임이 아니라 직접 처리하기 시작하면 비효율.
한계점 & 트러블슈팅.
실험적 기능이라 알아둘 한계점들이 꽤 있습니다. 미리 알면 안 당황해요.
현재 한계점
자주 만나는 문제 해결
💰 토큰 비용 주의
Agent Teams는 단일 세션 대비 3-4배 토큰을 씁니다. 각 팀원이 독립 컨텍스트를 가지니까요. 리서치, 리뷰, 새 기능 작업엔 그만한 값어치가 있지만, 단순 작업엔 오버킬입니다. Pro 플랜은 하루 2-3 task, Max 플랜은 5시간에 8-10 task 정도가 현실적.
정리 — 5단계 요약
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 settings.json에 추가🏴☠️ 봄내AI해적단 멘티들에게
실험적 기능이라 약간 손이 가지만, 한 번 익히면 "한 명의 클로드가 한계"인 작업들에 새로운 길이 열립니다.
처음엔 CASE 01(병렬 코드 리뷰)부터 해보세요. 본인이 최근 작업한 PR이나 코드에 대해 3명의 리뷰어를 만들어 보안/성능/테스트 관점으로 리뷰시키는 거. 코드 안 건드리니 위험도 낮고, 효과는 즉시 체감됩니다.
결과 단톡방 공유 부탁드려요. 다음 모임 때 직접 시연도 해보겠습니다.
→ 다음 회차 예고
MCP (Model Context Protocol) 입문 · Claude Code를 본인의 Notion, Slack, GitHub, Supabase 등과 연결해서 진짜 자동화 동료로 만드는 법. 그 다음엔 Agent Teams + MCP 결합 워크플로우로 n8n과 같은 자동화 파이프라인을 더 강력하게 만드는 패턴까지.
Issue №4 · Claude Code Agent Teams
이장환 · 봄내AI해적단 선장 · 춘천 · 2026