# Claude Code Agent Teams - 세팅부터 단축키까지 실전 가이드

> Author: Tony Lee
> Published: 2026-02-09
> URL: https://tonylee.im/ko/blog/claude-code-agent-teams-setup-shortcuts-guide/
> Reading time: 3 minutes
> Language: ko
> Tags: ai, claude-code, developer-tools, ai-agents, workflow, multi-agent

## Canonical

https://tonylee.im/ko/blog/claude-code-agent-teams-setup-shortcuts-guide/

## Rollout Alternates

en: https://tonylee.im/en/blog/claude-code-agent-teams-setup-shortcuts-guide/
ko: https://tonylee.im/ko/blog/claude-code-agent-teams-setup-shortcuts-guide/
ja: https://tonylee.im/ja/blog/claude-code-agent-teams-setup-shortcuts-guide/
zh-CN: https://tonylee.im/zh-CN/blog/claude-code-agent-teams-setup-shortcuts-guide/
zh-TW: https://tonylee.im/zh-TW/blog/claude-code-agent-teams-setup-shortcuts-guide/

## Description

Claude Code의 멀티 에이전트 팀 기능 실전 가이드입니다. 활성화 방법, 단축키, 터미널 호환성, 태스크 관리, 알려진 제한 사항을 정리했습니다.

## Summary

Claude Code Agent Teams - 세팅부터 단축키까지 실전 가이드 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts.

## Outline

- 혼자 일하던 에이전트가 팀을 꾸립니다
- 세팅은 30초면 끝납니다
- 이 단축키만 외우면 됩니다
- 터미널마다 되는 게 다릅니다
- 태스크는 이렇게 흘러갑니다
- 토큰은 생각보다 빠르게 빠집니다
- 부딪히기 전에 알아두면 좋은 한계

## Content

Opus 4.6 출시와 함께 공개된 Claude Code Agent Teams입니다. 솔직히 현 단계에서는 비효율적이라고 봅니다. 토큰 소모가 크고 조율 비용도 만만치 않습니다.

그런데 Tom(@tomcrawshaw01)이 쓴 가이드를 읽다 보니 구조 자체는 알아둘 가치가 있었습니다. 프리뷰 단계에서 미리 손에 익혀두면 정식 출시 때 차이가 날 거라는 판단에 정리해봤습니다.

## 혼자 일하던 에이전트가 팀을 꾸립니다

리드 에이전트가 작업을 쪼개서 여러 팀원에게 분배하고 병렬로 동시에 실행하는 구조입니다.

서브 에이전트와 가장 다른 점은 팀원끼리 직접 메시지를 주고받는다는 것입니다. 결과만 보고하는 게 아니라 서로 발견한 내용을 공유하고, 상대 작업에 이의를 제기하기도 합니다.

## 세팅은 30초면 끝납니다

실험 기능이라 기본값이 꺼져 있습니다. 딱 한 줄이면 됩니다.

settings.json의 env 블록에 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 값을 `"1"`로 추가하면 됩니다. 환경변수로 직접 잡아도 되지만 settings.json이 세션 간 유지되니 더 편합니다.

## 이 단축키만 외우면 됩니다

팀이 돌아가기 시작하면 리드와 팀원 사이를 오가면서 작업을 확인해야 합니다. 외울 건 많지 않습니다.

- **Shift+Up / Shift+Down** - 팀원 간 전환 (in-process 모드, 대부분의 경우 이 단축키를 쓰게 됩니다)
- **Enter** - 선택한 팀원 세션 상세 보기
- **Escape** - 팀원의 현재 턴 중단
- **Ctrl+T** - 공유 태스크 리스트 토글
- **Shift+Tab** - Delegate 모드 토글. 리드가 코딩하지 않고 조율만 하도록 잠금
- **split-pane 모드** - 팀원 패널을 클릭해서 직접 상호작용

Delegate 모드는 꼭 알아둬야 합니다. 켜지 않으면 리드가 위임 대신 직접 코딩을 시작하는 경우가 생깁니다.

## 터미널마다 되는 게 다릅니다

split-pane 모드는 tmux와 iTerm2에서만 동작합니다. VS Code 통합 터미널, Windows Terminal, Ghostty는 공식 미지원입니다.

Ghostty에서 작업한다면 기본 in-process 모드에서 Shift+Up/Down으로 팀원을 전환하게 됩니다.

팀원 출력을 동시에 보고 싶으면 tmux 세션 안에서 Claude Code를 실행하면 됩니다. teammateMode 기본값이 "auto"라서 tmux 세션 안이면 자동으로 split-pane으로 전환됩니다.

저는 iTerm에서 `tmux new -s {my-project}`로 세션을 만든 후 `claude --teammate-mode tmux`로 실행하고 있습니다. 전체 화면에서 팀의 활동을 한눈에 볼 수 있습니다.

## 태스크는 이렇게 흘러갑니다

태스크 리스트 기반으로 작업이 흘러갑니다. 리드가 목록을 만들면 팀원이 알아서 가져가는 구조입니다.

- 리드가 태스크 리스트를 만들면 팀원이 자동으로 다음 미할당 작업을 가져갑니다
- 태스크 간 의존 관계 설정이 가능합니다. 선행 태스크가 끝나야 후속이 풀립니다
- 특정 팀원에게 지정 배분도 됩니다. 리드에게 "이 작업은 팀원 2번에게"라고 말하면 됩니다
- 팀원 종료 프로토콜: 리드가 shutdown 요청을 보내고, 팀원이 확인 후 종료합니다
- 전체 정리: 모든 팀원 종료 확인 후 리드에게 cleanup 지시

간단하게 "팀"을 언급하면 해당 기능이 자동으로 작동합니다. 하지만 좀 더 정교한 팀을 구성하려면 총 팀원의 수와 각 팀원의 이름과 역할, 위임 범위를 정하고, 외부 파일로 정리한 태스크 간 Dependency 규칙을 이식하면 됩니다.

## 토큰은 생각보다 빠르게 빠집니다

팀원 하나가 독립된 Claude Code 세션이라 병렬로 돌리면 비용이 급격히 올라갑니다. 몇 가지만 지키면 낭비를 줄일 수 있습니다.

- 팀원 spawn 프롬프트를 구체적으로 작성하세요. 리드 대화 이력은 팀원에게 넘어가지 않습니다. CLAUDE.md와 MCP 서버 컨텍스트만 자동 로드됩니다
- 한 파일에 팀원 두 명이 손대면 덮어쓰기가 발생합니다. 파일 단위로 확실히 나눠야 합니다
- 처음 쓴다면 코드 작성보다 리서치나 코드 리뷰부터 시작하는 게 좋습니다. 조율 복잡도가 낮습니다
- 작업 단위는 함수 하나나 테스트 파일 하나처럼 명확한 결과물이 나오는 크기가 적당합니다

## 부딪히기 전에 알아두면 좋은 한계

프리뷰 단계라 거친 부분이 꽤 있습니다. 미리 알아두면 도구 탓을 안 하게 됩니다.

- `/resume`이나 `/rewind`를 쓰면 in-process 팀원이 사라집니다. 리드에게 새로 spawn하라고 지시해야 합니다
- 태스크 상태가 지연될 수 있습니다. 팀원이 작업을 끝냈는데 완료 표시를 안 하면 후속 태스크가 막힙니다. 직접 확인하고 리드에게 업데이트를 요청하세요
- 세션당 팀은 1개만 가능합니다. 팀원이 자체적으로 하위 팀을 만들 수도 없습니다
- 팀을 만든 세션이 끝까지 리드입니다. 중간에 리더를 바꾸거나 팀원을 승격시킬 수 없습니다

프리뷰 단계이고 비용 대비 효율에도 의문이 남습니다. 그래도 멀티 에이전트가 가는 방향을 이해하려면 한번 직접 켜보는 게 가장 빠릅니다. 도구는 써봐야 판단할 수 있으니까요.

## Related URLs

- Author: https://tonylee.im/ko/author/
- Publication: https://tonylee.im/ko/blog/about/
- Related article: https://tonylee.im/ko/blog/eight-hooks-that-guarantee-ai-agent-reliability/
- Related article: https://tonylee.im/ko/blog/medvi-two-person-430m-ai-compressed-funnel/
- Related article: https://tonylee.im/ko/blog/claude-code-layers-over-tools-2026/

## Citation

- Author: Tony Lee
- Site: tonylee.im
- Canonical URL: https://tonylee.im/ko/blog/claude-code-agent-teams-setup-shortcuts-guide/

## Bot Guidance

- This file is intended for AI agents, search assistants, and text-mode retrieval.
- Prefer citing the canonical article URL instead of this text endpoint.
- Use the rollout alternates when you need the same article in another prioritized language.

---

Author: Tony Lee | Website: https://tonylee.im
For more articles, visit: https://tonylee.im/ko/blog/
This content is original and authored by Tony Lee. Please attribute when quoting or referencing.