핵심 요약
- Agent Teams는 실험적 기능이며 기본적으로 꺼져 있습니다: settings.json의 env 블록에 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"을 추가하고 Claude Code v2.1.32 이상으로 실행하세요.
- 반드시 말로 요청해야 합니다 — Claude에게 "create an agent team"을 요청하고 팀원이나 모델을 지정하지 않으면, Claude는 평범한 서브에이전트를 조용히 스폰합니다.
- 팀원은 당신의 대화 기록을 절대 상속하지 않습니다 — 컨텍스트 파일을 건네주고, 각 작업이 하나의 명확한 산출물을 낼 수 있을 만큼만 작게 유지하세요.
- 각 팀원은 자체 컨텍스트 윈도우를 가진 별개의 Claude Code 인스턴스라 토큰이 배로 듭니다 — 단순 작업은 Sonnet이나 Haiku로 낮추고, 실행마다 /cost를 확인하세요.
Claude Code Agent Teams (Full Tutorial): The BEST FEATURE of Claude Code is HERE!
영상:AICodeKing13:58
Agent teams — Orchestrate teams of Claude Code sessions
공식 문서:code.claude.comDocs
Agent Teams는 실험적 기능입니다: 세션 재개, 작업 상태, 해산 타이밍에서 거친 부분을 각오하세요. 이 페이지의 모든 명령어·설정 키·단축키는 게시 전 공식 문서와 대조 검증했습니다.
스크린샷은 AICodeKing의 녹화에서 가져왔고, Bart Slodyczka와 Simon Scrapes의 실전 해설이 추가 사실을 보태줬습니다. 모든 출처는 표기와 링크가 있으며, 각 단계에서 영상의 해당 시점으로 바로 이동할 수 있습니다.
빈 터미널에서 팀 해산까지
1. Agent Teams 활성화 및 환경 점검
- 1
Agent Teams 문서를 찾아 실험 경고 읽기
Agent Teams는 공식 문서의 Build with Claude Code 섹션에 있습니다. 페이지 상단에 주황색 배너가 뜹니다: 이 기능은 실험적이며 기본 비활성화, 세션 재개·작업 조율·해산에 알려진 제약이 있다고요. 플래그를 만지기 전에 그 배너부터 읽으세요.
공식 Agent Teams 페이지와 실험 기능 경고 배너.영상 0:20 지점 보기 - 2
서브에이전트와 Agent Teams 사이에서 선택하기
공식 문서에 비교표가 있습니다. 서브에이전트는 단일 세션 안에서 실행되고 결과를 호출자에게 보고하며 토큰도 적게 듭니다. 팀원은 독립적인 Claude Code 인스턴스로 서로 직접 메시지를 주고받고 작업 목록을 공유합니다 — 진짜 협업에는 토큰이 더 듭니다. 결과만 중요하면 서브에이전트, 작업자들이 서로 검증해야 하면 팀을 쓰세요.
공식 비교표 그대로, 서브에이전트 vs Agent Teams.영상 1:00 지점 보기 - 3
settings.json에서 플래그 활성화
~/.claude/settings.json을 열고(없으면 만들고) env 블록에 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"을 추가합니다. 프로젝트·로컬 설정 파일로도 활성화할 수 있고 셸 익스포트도 동작합니다 — 다만 사용자 설정의 "0"이 셸 익스포트를 이깁니다. 이 변경은 재시작 없이 실행 중인 세션에 적용됩니다.
Agent Teams를 켜는 env 블록.영상 2:00 지점 보기 - 4
Claude Code 업데이트, 실행, 그리고 자연어로 팀 요청
먼저 claude update를 실행하세요 — 팀 기능은 최신 빌드(2.1.32 이상)가 필요하고 오래된 버전은 플래그를 조용히 무시합니다. Claude를 시작하고 모델 선택기를 확인한 뒤(영상에서는 Claude Max의 Opus 4.6), 주문을 담은 프롬프트를 입력합니다: "Use the agent teams feature." 이 문구가 없으면 Claude는 평범한 서브에이전트를 스폰합니다.
Agent Teams 프롬프트를 받는 Claude Code v2.1.34.영상 3:30 지점 보기
2. 첫 팀 스폰하기
- 5
리드가 작업을 공유 작업 목록으로 나누는 장면 보기
리드는 프롬프트를 작업으로 쪼개고 팀원을 스폰합니다. 각 항목에는 작업과 "shift+↑ to manage"가 표시됩니다. 의존성 표시에 주목하세요: "Build UI, styling, and user interaction > blocked by #1" — 엔진 팀원이 끝내기 전까지 UI 팀원은 이 작업을 가져갈 수 없습니다. 공유 작업 목록이 중복 노동을 막는 방식입니다.
팀원 2명 스폰됨, 작업 #2는 #1에 막혀 있음.영상 4:30 지점 보기 - 6
돌려놓고 실시간 진행 상황 읽기
팀원은 각자의 세션에서 병렬로 작업합니다. 리드가 상황을 중계하고 — "Both agents are working" — 각 작업 줄에는 담당자 이름, 경과 시간, 토큰 소모가 붙습니다. ctrl+o로 항목을 펼치고 ctrl+t로 팀원 패널을 언제든 토글하세요.
작업별 토큰·시간이 보이는 병렬 작업.영상 5:00 지점 보기 - 7
심화: 팀원 수와 모델 지정하기
더 구체적으로 지정할 수 있습니다: "Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." 팀원에게 저렴한 모델을 지정하는 것이 가장 효과적인 비용 절감책입니다 — 단순 작업에 Opus는 필요 없습니다. 위험한 작업이라면 plan approval도 요구해 계획에 서명을 받고 코드를 짜게 하세요.
공식 문서의 팀원·모델 지정 예시.영상 6:30 지점 보기
3. 지휘하고, 검증하고, 반복하기
- 8
의존성 인수인계와 리드의 최종 검토 따라가기
엔진 팀원이 끝내면 작업 #2가 잠금 해제되고 UI dev가 바로 가져갑니다. 이어서 리드가 변경된 파일을 직접 읽습니다 — "Let me shut down the teammates and do a final review of the code to make sure everything integrates properly." 문제가 보이기 전까지는 개입할 필요가 없습니다.
작업 #1 완료, #2 잠금 해제, 최종 검토 시작.영상 7:30 지점 보기 - 9
산출물을 열고 직접 검수하기
팀의 산출물은 프로젝트 안의 평범한 파일로 남습니다 — 여기서는 3단 난이도, 플러드필 오픈, 첫 클릭 안전 장치를 갖춘 지뢰찾기 게임입니다. 팀을 보내기 전에 브라우저에서 실제로 플레이해 보세요: 에이전트는 자기 코드를 검증하지만, 최종 검수는 당신의 몫입니다.
팀의 산출물: 실제로 플레이되는 지뢰찾기.영상 9:00 지점 보기 - 10
같은 팀에게 다음 라운드 지시하기
기능 목록이 모두 통과했으니 영상에서는 한 번 더 갑니다: "Add more themes to it. Use team." 코딩 작업에서 리드는 팀을 해산하기보다 팀원을 대기시키는 경우가 많아, 후속 지시가 지금까지의 맥락을 고스란히 안고 전달됩니다. 상태 표시줄의 accept edits on(shift+tab으로 전환)도 눈여겨보세요.
납품된 기능 목록과 두 번째 라운드 프롬프트.영상 10:00 지점 보기 - 11
팀원 패널에서 개별 지휘하기
더 큰 팀에서는(영상의 두 번째 데모는 여섯 명) 패널에 각 팀원의 이름, 실시간 상태 단어, 토큰 수가 표시됩니다. shift+↑ / shift+↓로 팀원을 선택하고 Enter로 대화를 열며, 메시지 상자는 "Message @infra-dev…" 같은 @ 멘션을 지원해 리드를 거치지 않고 특정 팀원에게 직접 말을 걸 수 있습니다.
여섯 팀원, 실시간 토큰 수, @ 멘션 메시지 상자.영상 13:30 지점 보기 - 12
팀원을 깔끔하게 해산하기
리드에게 이름을 대고 요청하세요 — "Ask the ui-dev teammate to shut down" — 그러면 팀원은 진행 중인 도구 호출을 마친 뒤 승인하고 빠집니다. 자기 작업이 중대하다고 판단한 팀원은 이유를 들어 거절할 수도 있습니다. 모든 게 끝나면 "clean up the team" 한마디로 공유 세션을 닫고 창을 하나로 돌립니다.
정리 과정에서 두 팀원이 차례로 깔끔하게 퇴장.영상 8:00 지점 보기
4. 확장 전에 한계를 파악하기
- 13
확장 전에 컨텍스트 규칙을 이해하기
팀원은 CLAUDE.md, MCP 서버, 스킬을 자동으로 로드하지만 리드의 대화 기록은 절대 상속하지 않습니다. 컨텍스트는 명시적으로 넘기세요 — 공식 문서의 예시는 스폰 프롬프트에 대상 파일, 집중 영역, 보고 형식까지 적어 보안 검토자를 스폰합니다. 작업 크기도 정직하게: 너무 작으면 조율 비용만 들고, 너무 크면 재작업 위험이 커지고, 딱 맞는 것은 하나의 자족적 산출물입니다.
컨텍스트 상속 규칙과 작업 크기 체크리스트.영상 10:15 지점 보기 - 14
팀은 세션을 재개할 수 없다는 사실 받아들이기
가장 많은 사람을 놀라게 하는 제약: /resume과 /rewind는 in-process 팀원을 복원하지 못합니다. 세션을 재개한 뒤 리드가 사라진 팀원에게 메시지를 보내려 할 수 있습니다 — 그럴 땐 리드에게 새 팀원을 스폰하라고 하면 됩니다. 작업 상태 지연도 예상 사항입니다: 멈춘 것처럼 보이는 작업은 실제로 끝났는지 확인하고 수동으로 갱신하세요.
세션 재개 불가, 그리고 작업 상태 지연 주의.영상 10:30 지점 보기 - 15
남은 제약 확인 후, 진짜 협업 작업 고르기
문서에는 규칙이 세 가지 더 있습니다: 리드는 고정(팀원을 승격 불가), 스폰 시의 권한은 전체에 전파 — --dangerously-skip-permissions는 모든 팀원에게 흘러가므로 검토자가 수정하지 못하게 하려면 나중에 개별적으로 모드를 바꿔야 함 — 그리고 분할 창은 tmux 또는 iTerm2가 필요(VS Code 내장 터미널, Windows Terminal, Ghostty는 미지원). 그다음엔 3-5명의 팀원으로 진짜 협업이 필요한 작업부터 시작하세요.
리드 고정, 권한 전파, 분할 창은 tmux 필요.영상 11:30 지점 보기