클로드 코드 Team 기능 완전 가이드 (총 9편) | 3편 핵심 구성요소 완벽 해설 — 리더, 팀원, Task list, 메일박스

시리즈: 클로드 코드 Team 기능 완전 가이드 (총 9편) | 3편

핵심 구성요소 완벽 해설 — 리더, 팀원, Task list, 메일박스

Agent Teams의 구성요소를 제대로 이해하지 않으면 팀을 만들어도 활용하기 어려워요. 이 글에서는 리더·팀원·Task list·메일박스의 역할부터 표시 모드, Delegate 모드, Plan approval까지 모든 구성요소를 하나씩 해부해 드릴게요.

Summary

• 리더는 팀 생성·작업 분배·결과 종합을 담당하고, 세션당 하나의 팀만 운영 가능해요
• 팀원은 독립 인스턴스로 작동하며 중첩 팀 생성이 불가능해요
• 공유 Task list는 상태(pending/in-progress/completed)와 종속성으로 작업 흐름을 관리해요
• 메일박스의 message(개별)와 broadcast(전체)로 팀원 간 소통이 가능해요

이 글의 대상

• Team의 구성요소를 하나하나 정확히 이해하고 싶은 분
• Team을 실전에서 쓰기 전에 구조를 먼저 파악하려는 분
• Delegate 모드나 Plan approval 같은 고급 기능이 궁금한 분

목차

1. 리더(Lead): 팀의 두뇌
2. 팀원(Teammates): 독립된 실행 유닛
3. 공유 Task list: 작업 흐름의 중심
4. 메일박스: 팀 내 소통 채널
5. 표시 모드: in-process vs split-pane
6. Delegate 모드와 Plan approval

1. 리더(Lead): 팀의 두뇌

리더는 팀을 만들고, 작업을 쪼개서 할당하고, 결과를 모아서 종합하는 역할이에요.

리더가 하는 일을 단계별로 정리하면 이래요:

단계	리더의 역할	설명
1단계	팀 생성	팀원 인스턴스를 스폰(spawn)해요
2단계	작업 분해	큰 목표를 구체적인 작업 단위로 쪼개요
3단계	작업 할당	Task list에 등록하거나 직접 배정해요
4단계	조율	진행 상황 확인, 필요시 방향 조정
5단계	결과 종합	팀원들의 결과를 모아서 최종 답변 생성

그런데 리더에게도 제약이 있어요. 이걸 모르면 실전에서 당황할 수 있으니까 확실히 짚고 넘어갈게요:

• 세션당 하나의 팀만 — 한 리더 세션에서 여러 팀을 동시에 운영할 수 없어요
• 중첩 팀 불가 — 팀 안에 또 다른 팀을 만들 수 없어요. 1단계 구조만 가능해요
• 리더십 이전 불가 — 한번 리더가 되면 다른 팀원에게 리더 역할을 넘길 수 없어요

특히 "중첩 팀 불가"는 중요해요. "팀원 A가 자기 하위에 또 팀을 만들어서..." 같은 건 안 되거든요. 복잡한 구조가 필요하면 리더가 더 많은 팀원을 직접 관리하는 수평적 구조로 가야 해요.

2. 팀원(Teammates): 독립된 실행 유닛

팀원은 완전히 독립된 Claude Code 인스턴스로, 자기만의 컨텍스트 윈도우에서 작업해요.

1편에서도 다뤘지만, 팀원의 독립성은 Team 기능의 핵심이에요. 각 팀원의 특성을 정리하면:

특성	설명
독립 인스턴스	각각 별도의 Claude Code 세션으로 실행돼요
독립 컨텍스트	리더나 다른 팀원의 대화 히스토리를 공유하지 않아요
중첩 불가	팀원이 또 다른 팀을 생성할 수 없어요
파일 시스템 공유	같은 프로젝트 디렉토리에서 작업해요

팀원에게 작업을 줄 때 한 가지 팁이 있어요. 팀원은 리더의 맥락을 모르니까, 작업 지시를 충분히 구체적으로 해야 해요. "이 코드 리뷰해줘"보다는 "이 PR의 인증 관련 코드를 보안 관점에서 리뷰해줘. 특히 토큰 만료 처리와 입력 검증을 중점적으로 봐줘" 같은 식이 좋아요.

팀원 수는 얼마나 하는 게 좋을까요? 공식 문서에서 권장하는 건 팀원당 5~6개 작업이에요. 너무 적으면 팀원을 만든 보람이 없고, 너무 많으면 각 팀원의 컨텍스트가 과부하 걸릴 수 있거든요. 전체 작업이 1520개라면 팀원 34명이 적절하겠죠.

3. 공유 Task list: 작업 흐름의 중심

Task list는 팀 전체가 공유하는 작업 목록으로, 상태 관리와 종속성 설정이 핵심이에요.

Task list의 각 작업은 세 가지 상태를 가져요:

pending → in-progress → completed
(대기)     (진행 중)      (완료)

작동 방식은 간단해요:

1. 리더가 작업을 등록하면 pending 상태가 돼요
2. 팀원이 자기가 할 작업을 골라서 in-progress로 바꿔요 (self-claim)
3. 작업을 마치면 completed로 바꾸고 다음 작업을 찾아요

여기서 강력한 기능이 종속성(dependency) 관리예요. 실제로 이런 설정이 가능해요:

작업	종속성	의미
작업 A: DB 스키마 설계	없음	바로 시작 가능
작업 B: API 엔드포인트 구현	작업 A	A가 끝나야 시작 가능
작업 C: 테스트 코드 작성	작업 B	B가 끝나야 시작 가능
작업 D: 문서화	작업 A	A만 끝나면 B·C와 병렬 가능

이렇게 하면 작업 A가 끝나는 순간, B와 D가 동시에 시작될 수 있어요. C는 B가 끝날 때까지 기다리고요. 리더가 일일이 "이제 이거 해"라고 시키지 않아도, 종속성만 잘 설정해 두면 자동으로 흘러가는 거예요.

File-locking도 중요한 기능이에요. 여러 팀원이 같은 파일을 동시에 수정하면 충돌이 생길 수 있잖아요? Task list에서 특정 작업이 특정 파일을 사용한다고 표시해 두면, 다른 팀원이 그 파일을 건드리는 작업을 동시에 진행하지 않도록 조율할 수 있어요.

4. 메일박스: 팀 내 소통 채널

메일박스는 팀원 간 직접 소통을 가능하게 하는 메시징 시스템이에요.

두 가지 소통 방식이 있어요:

message (개별 메시지)

특정 팀원에게 1:1로 메시지를 보내는 거예요. 주로 이런 상황에서 쓰여요:

• "A야, 네가 분석한 쿼리 성능 데이터 좀 알려줘"
• "B야, 이 파일은 내가 수정 중이니까 좀 있다 봐줘"
• 리더가 특정 팀원에게 추가 지시를 내릴 때

broadcast (전체 메시지)

모든 팀원에게 동시에 메시지를 보내는 거예요. 하지만 주의할 점이 있어요:

• broadcast는 모든 팀원의 컨텍스트 윈도우에 메시지가 추가돼요
• 그만큼 각 팀원의 컨텍스트를 소모하고 비용도 늘어나요
• 공식 문서에서도 "드물게" 사용하라고 권장해요

broadcast를 쓸 만한 상황은 이런 거예요:

• 전체 방향이 바뀌었을 때 ("목표가 변경됐어, 성능보다 보안 우선으로 전환")
• 공통 제약 조건이 추가됐을 때 ("Python 3.9 호환성도 확보해야 해")
• 중요한 발견이 있어서 전원이 알아야 할 때

일상적인 진행 상황 공유에는 broadcast 대신 Task list 상태 업데이트를 활용하는 게 비용 효율적이에요.

5. 표시 모드: in-process vs split-pane

팀원의 작업 상황을 화면에 어떻게 보여줄지를 결정하는 설정이에요.

표시 모드	설명	필요 조건
in-process	리더 세션 안에서 팀원 상태를 표시	추가 설정 불필요
split-pane	각 팀원을 별도 터미널 패널로 표시	tmux 또는 iTerm2 필요

in-process 모드는 별도 설정 없이 바로 쓸 수 있어요. 리더 세션의 화면에서 각 팀원의 진행 상황이 요약되어 표시되거든요. 간단하게 Team을 시작해보고 싶다면 이 모드로 충분해요.

split-pane 모드는 각 팀원에게 별도의 터미널 패널을 할당해서, 실시간으로 각 팀원이 뭘 하고 있는지 눈으로 볼 수 있어요. 마치 모니터 여러 대를 띄워놓고 각 팀원의 작업을 지켜보는 것과 비슷해요. 대신 tmux나 iTerm2 같은 터미널 멀티플렉서가 필요하다는 게 조건이에요.

어떤 걸 고르면 될까요?

• 처음 Team을 써보는 거라면 → in-process부터 시작
• 팀원이 3명 이상이고 실시간 모니터링이 중요하면 → split-pane 추천
• tmux를 이미 쓰고 있다면 → split-pane이 자연스러워요

6. Delegate 모드와 Plan approval

실전에서 유용한 고급 기능 두 가지를 마지막으로 살펴볼게요.

Delegate 모드

리더를 조율 전용으로 제한하는 모드예요. 기본적으로 리더도 직접 코드를 수정하거나 작업을 수행할 수 있는데, Delegate 모드를 켜면 리더는 작업 분배와 결과 종합만 하고 실제 작업은 모두 팀원에게 위임해요.

이게 유용한 상황:

• 작업이 많아서 리더가 직접 일까지 하면 조율이 소홀해질 때
• 리더의 컨텍스트 윈도우를 조율 작업에만 집중시키고 싶을 때
• 명확한 역할 분리가 필요한 대규모 작업에서

Plan approval

위험한 변경이 포함된 작업에서 팀원이 바로 실행하지 않고, 먼저 계획을 제출해서 승인을 받은 후 진행하는 기능이에요.

흐름은 이래요:

팀원이 계획 작성 → 리더(또는 여러분)에게 제출 → 검토 → 승인 → 실행

프로덕션 DB를 건드리거나, 대규모 파일 삭제가 포함된 작업처럼 "실수하면 큰일 나는" 상황에서 안전장치 역할을 해요. 모든 작업에 걸 필요는 없고, 위험도가 높은 특정 작업에만 선택적으로 적용하면 돼요.

핵심 정리

1. 리더: 팀 생성 → 작업 분배 → 조율 → 결과 종합 (세션당 1팀, 중첩·이전 불가)
2. 팀원: 독립 인스턴스 + 독립 컨텍스트, 팀원당 5~6개 작업 권장
3. Task list: pending → in-progress → completed 상태 흐름 + 종속성 + file-locking
4. 메일박스: message(개별)는 자유롭게, broadcast(전체)는 드물게
5. 표시 모드(in-process/split-pane), Delegate 모드, Plan approval로 세밀한 제어 가능

FAQ

Q. 리더가 직접 작업도 하고 조율도 할 수 있나요?

A. 네, 기본적으로 리더는 둘 다 할 수 있어요. 하지만 작업이 복잡해지면 조율에 집중하는 게 나은데, 그때 Delegate 모드를 켜면 리더를 조율 전용으로 제한할 수 있어요.

Q. 팀원끼리 같은 파일을 동시에 수정하면 어떻게 되나요?

A. 충돌이 생길 수 있어요. 그래서 Task list의 file-locking 기능으로 "이 작업은 이 파일을 사용 중"이라고 표시해서 동시 수정을 방지하는 거예요. 작업을 분배할 때 파일 단위로 겹치지 않게 나누는 것도 좋은 방법이에요.

Q. 중첩 팀이 안 된다면 복잡한 프로젝트는 어떻게 하나요?

A. 수평적으로 팀원 수를 늘리는 방식으로 해결해요. 팀원이 5~6명이어도 Task list의 종속성 관리를 잘 설정하면 복잡한 워크플로우를 충분히 소화할 수 있어요. 핵심은 작업 분해를 잘 하는 거예요.

Q. Task list의 종속성을 잘못 설정하면 어떻게 되나요?

A. 순환 종속성(A가 B를 기다리고 B가 A를 기다리는 상황)이 생기면 작업이 진행되지 않아요. 종속성은 항상 한 방향으로 흐르게 설정해야 해요. 만약 실수로 잘못 설정했다면 리더가 Task list를 수정해서 해결할 수 있어요.

Q. Plan approval은 모든 작업에 걸어야 하나요?

A. 아니에요. 모든 작업에 걸면 승인 대기 시간 때문에 Team의 장점인 병렬성이 떨어져요. DB 변경, 대규모 삭제, 프로덕션 배포 같은 고위험 작업에만 선택적으로 적용하는 게 맞아요.

Q. split-pane 모드를 쓰려면 꼭 tmux가 필요한가요?

A. tmux 또는 iTerm2가 필요해요. macOS에서 iTerm2를 쓰고 있다면 바로 사용 가능하고, 그 외 환경에서는 tmux를 설치하면 돼요. 일반 터미널에서는 in-process 모드만 사용할 수 있어요.

Q. 팀원당 5~6개 작업이라는 권장 기준은 왜 그런 거예요?

A. 팀원의 컨텍스트 윈도우 크기 때문이에요. 작업이 너무 많으면 각 작업의 결과와 맥락이 쌓이면서 컨텍스트가 가득 차요. 5~6개면 충분한 깊이로 각 작업을 수행하면서도 컨텍스트가 과부하 되지 않는 균형점이에요.

참고 자료 (References)

데이터 출처

출처	설명	링크
Agent Teams 공식 문서 (KO)	한국어 공식 가이드	Agent Teams KO
Agent Teams 공식 문서 (EN)	영문 공식 가이드	Agent Teams EN

핵심 인용

"여러 Claude Code 인스턴스가 함께 작동하도록 조율"
— Agent Teams 공식 문서

다음 편 예고

[4편] 설정부터 실행까지, Team 기능 실전 가이드

• Team 활성화 방법과 초기 설정
• 표시 모드 제어하는 법
• IDE 연동 패턴과 실전 팁