Claude Code 에이전트 팀 — 여러 AI가 협업하는 새로운 방식

에이전트 팀이란

Claude Code에는 하나의 세션 안에서 서브태스크를 처리하는 Subagent가 이미 있다. 그런데 최근 실험적 기능으로 **에이전트 팀(Agent Teams)**이 추가됐다. 핵심 차이는 이렇다:

하나의 Claude가 여러 Claude를 생성하고, 각자 독립적인 컨텍스트 윈도우에서 작업하면서 서로 직접 대화할 수 있다.

리더 세션이 팀을 만들고, 팀원들을 생성하고, 작업을 조율한다. 각 팀원은 완전히 독립적인 Claude Code 인스턴스다. Subagent와 달리 팀원끼리 리더를 거치지 않고 직접 메시지를 주고받을 수 있다.

Subagent vs 에이전트 팀

어떤 걸 써야 할지 고민된다면 이 표를 참고하면 된다:

간단히 말하면: 워커가 결과만 돌려주면 되면 Subagent, 워커끼리 토론하고 서로 도전해야 하면 에이전트 팀이다.

활성화 방법

에이전트 팀은 기본적으로 비활성화되어 있다. settings.json에 환경 변수를 추가해서 켤 수 있다:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

팀 시작하기

활성화한 뒤에는 자연어로 팀 구성을 요청하면 된다. Claude가 알아서 팀을 만들고 팀원을 생성한다.

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles:
one teammate on UX, one on technical architecture, one playing devil's advocate.

이렇게 하면 세 명의 팀원이 각각 UX, 기술 아키텍처, 반론 역할로 독립 작동한다. 리더가 결과를 종합해서 정리까지 해준다.

표시 모드

팀원들의 작업을 보는 방식은 두 가지다:

In-process 모드 (기본)

모든 팀원이 메인 터미널 안에서 실행된다. 추가 설정이 필요 없다.

• Shift+Up/Down: 팀원 선택
• Enter: 선택한 팀원의 세션 보기
• Escape: 현재 턴 중단
• Ctrl+T: 작업 목록 토글

분할 창 모드

각 팀원이 자기 창을 가진다. 모든 팀원의 출력을 한눈에 볼 수 있다. tmux 또는 iTerm2가 필요하다.

{
  "teammateMode": "tmux"
}

단일 세션에서만 적용하려면 플래그로 전달할 수도 있다:

claude --teammate-mode in-process

기본값은 "auto"로, tmux 세션 안에서 실행 중이면 분할 창, 아니면 in-process를 사용한다.

팀 제어

팀원 및 모델 지정

팀원 수와 사용할 모델을 직접 지정할 수 있다:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

계획 승인 요구

위험한 작업이라면 팀원이 먼저 계획을 세우고, 리더가 승인한 뒤에야 실행하도록 할 수 있다:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

팀원이 계획을 마치면 리더에게 승인 요청을 보낸다. 리더가 거부하면 피드백에 따라 수정 후 재제출한다.

위임 모드

리더가 직접 코드를 건드리지 않고 조율에만 집중하게 만드는 모드다. Shift+Tab으로 토글한다.

위임 모드에서 리더가 할 수 있는 건 네 가지뿐이다:

• 팀원 생성
• 메시지 전송
• 팀원 종료
• 작업 관리

작업 할당

공유 작업 목록이 팀 전체의 작업을 조율한다. 두 가지 방식이 있다:

• 리더 할당: 어떤 작업을 어떤 팀원에게 줄지 직접 지정
• 자체 청구: 팀원이 작업을 마치면 다음 미할당 작업을 알아서 가져감

작업 상태는 세 가지다: 대기 중 → 진행 중 → 완료됨. 종속성도 지원해서, 선행 작업이 끝나야 후속 작업이 풀린다.

가장 효과적인 사용 사례

에이전트 팀은 병렬 탐색이 가치를 더하는 작업에 가장 잘 맞는다:

• 연구/검토: 여러 팀원이 문제의 다른 측면을 동시에 조사
• 새 모듈 개발: 팀원들이 각각 별도 부분을 소유
• 경쟁 가설 디버깅: 다른 이론을 병렬로 테스트하고 서로 반박
• 교차 계층 조율: 프론트/백/테스트를 각각 다른 팀원이 담당

병렬 코드 리뷰

단일 검토자는 한 가지 유형의 문제에 치우치기 쉽다. 검토 관점을 분리하면 모든 측면이 동시에 철저한 검토를 받는다:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

경쟁 가설 디버깅

근본 원인이 불명확할 때 단일 에이전트는 하나의 설명을 찾고 멈추는 경향이 있다. 여러 조사자가 적극적으로 서로의 이론을 반박하게 만들면, 살아남는 이론이 실제 원인일 가능성이 훨씬 높아진다:

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk
to each other to try to disprove each other's theories, like a scientific
debate.

아키텍처

에이전트 팀은 네 가지 구성 요소로 이루어진다:

팀 데이터는 로컬에 저장된다:

• 팀 구성: ~/.claude/teams/{team-name}/config.json
• 작업 목록: ~/.claude/tasks/{team-name}/

팀원들은 생성될 때 프로젝트 컨텍스트(CLAUDE.md, MCP servers, skills)를 로드한다. 리더의 대화 기록은 전달되지 않으므로, 생성 프롬프트에 필요한 컨텍스트를 충분히 넣어야 한다.

모범 사례

충분한 컨텍스트 제공

팀원은 리더의 대화 기록을 받지 않는다. 생성 프롬프트에 작업에 필요한 세부 사항을 명시적으로 포함해야 한다:

Spawn a security reviewer teammate with the prompt: "Review the authentication
module at src/auth/ for security vulnerabilities. Focus on token handling,
session management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

적절한 작업 크기

• 너무 작으면: 조율 오버헤드가 이점을 초과
• 너무 크면: 팀원이 체크인 없이 너무 오래 작동, 낭비 위험 증가
• 적절한 크기: 명확한 결과물이 있는 자체 포함 단위 (함수, 테스트 파일, 리뷰)

팀원당 5~6개 작업을 유지하면 모두가 생산적이고, 막히면 리더가 재할당할 수 있다.

파일 충돌 방지

두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생한다. 각 팀원이 다른 파일 집합을 소유하도록 작업을 분해하는 게 중요하다.

연구/검토부터 시작

에이전트 팀이 처음이라면 코드 작성보다는 PR 리뷰, 라이브러리 조사, 버그 탐색 같은 읽기 위주 작업부터 시작하는 게 좋다. 병렬 구현의 조율 문제 없이 가치를 체감할 수 있다.

알려진 제한 사항

아직 실험적 기능이라 몇 가지 제한이 있다:

• 세션 재개 불가: /resume, /rewind가 in-process 팀원을 복원하지 않음
• 작업 상태 지연: 팀원이 작업 완료를 표시하지 못해 종속 작업이 막히는 경우 있음
• 세션당 하나의 팀: 새 팀을 시작하려면 현재 팀을 먼저 정리해야 함
• 중첩 불가: 팀원이 자기 팀을 만들 수 없음
• 리더 고정: 팀을 만든 세션이 끝까지 리더, 이전 불가
• 분할 창 제한: tmux 또는 iTerm2 필요, VS Code 터미널이나 Ghostty에서는 미지원

팀 종료와 정리

팀원 종료는 리더에게 요청한다:

Ask the researcher teammate to shut down

모든 팀원이 종료된 후 팀 정리:

Clean up the team

항상 리더를 통해 정리해야 한다. 팀원이 직접 정리하면 리소스가 불일치 상태로 남을 수 있다.

정리

에이전트 팀은 단일 세션의 한계를 넘어서는 복잡한 작업에 유용하다. 토큰 비용이 높고 아직 실험적이지만, 병렬 리뷰나 다관점 탐색 같은 작업에서는 확실한 가치가 있다.

핵심을 다시 정리하면:

• 워커가 결과만 돌려주면 되면 → Subagent
• 워커끼리 토론하고 협업해야 하면 → 에이전트 팀
• 처음이라면 코드 작성보다 리뷰/연구부터 시작
• 파일 충돌 방지가 가장 중요한 운영 원칙