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

에이전트 팀이란

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

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

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

Subagent vs 에이전트 팀

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

	Subagent	에이전트 팀
컨텍스트	자체 윈도우, 결과만 호출자에게 반환	자체 윈도우, 완전히 독립
통신	메인 에이전트에게만 보고	팀원끼리 직접 메시지 전송
조율	메인 에이전트가 관리	공유 작업 목록으로 자체 조율
최적 용도	결과만 중요한 집중 작업	논의와 협업이 필요한 복잡한 작업
토큰 비용	낮음 (결과가 요약돼서 반환)	높음 (팀원마다 별도 인스턴스)

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

활성화 방법

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

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가 필요하다.

settings.json

{
  "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.

실전 사례 — 10만 줄 C 컴파일러 구축

에이전트 팀이 실제로 얼마나 큰 프로젝트를 감당할 수 있을까? Anthropic이 직접 보여준 사례가 있다. 16개의 병렬 Claude 인스턴스로 Rust 기반 C 컴파일러를 만들었다. Linux 6.9 커널을 x86, ARM, RISC-V 세 아키텍처에서 컴파일할 수 있고, GCC torture test suite 99% 통과율을 달성한 프로젝트다.

비유하면 16명의 개발자가 하나의 Git 저장소를 공유하면서, 각자 Docker 컨테이너 안에서 독립적으로 코드를 짜고, 완성되면 push하는 구조다.

항목	수치
총 코드량	약 100,000줄 (Rust)
병렬 인스턴스	16개 (Opus 4.6)
총 세션 수	약 2,000회
입력 토큰	20억 토큰
출력 토큰	1.4억 토큰
총 비용	약 $20,000
컴파일 가능 대상	Linux 6.9, QEMU, FFmpeg, SQLite, PostgreSQL, Redis, Doom

동기화 방식

16개 에이전트가 같은 파일을 건드리면 충돌이 난다. 이 문제를 파일 기반 잠금으로 해결했다:

에이전트가 current_tasks/ 디렉토리에 텍스트 파일을 생성해서 작업을 "잠금"
작업 완료 후 upstream pull → merge → push → 잠금 해제
무한 루프가 새 컨테이너에서 다음 세션을 자동 실행

에이전트 실행 루프

while true; do
  COMMIT=$(git rev-parse --short=6 HEAD)
  LOGFILE="agent_logs/agent_${COMMIT}.log"
  claude --dangerously-skip-permissions \
         -p "$(cat AGENT_PROMPT.md)" \
         --model claude-opus-4-6 &> "$LOGFILE"
done

에이전트 역할 분리

모든 에이전트가 같은 일을 한 게 아니다. 역할을 나눴다:

역할	담당
코어 컴파일러 개발	주요 기능 구현 (대부분)
코드 중복 제거	반복 패턴 추출, 리팩토링
컴파일러 성능 최적화	컴파일 속도 개선
출력 코드 효율화	생성되는 바이너리 품질 개선
Rust 코드 품질 리뷰	아키텍처, 코드 스타일 검토
문서 유지보수	실패한 접근법, 남은 작업 기록

핵심 교훈

이 프로젝트에서 얻은 교훈 중 가장 중요한 것은 **"테스트 검증기가 거의 완벽해야 한다"**는 점이다. GCC를 오라클(정답 기준)로 사용해서, 같은 코드를 GCC와 Claude의 컴파일러로 각각 컴파일한 뒤 결과를 비교했다. 테스트가 부정확하면 에이전트가 엉뚱한 문제를 풀게 된다.

또 하나는 에이전트의 시간 감각 부재다. 에이전트는 "이 작업을 10분째 하고 있다"는 걸 모른다. 그래서 전체 테스트의 1%나 10%만 무작위로 돌리는 --fast 옵션을 만들어서, 에이전트가 빠른 피드백을 받을 수 있게 했다.

아키텍처

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

구성 요소	역할
팀 리더	팀 생성, 팀원 생성, 작업 조율하는 메인 세션
팀원	할당된 작업에서 각각 독립 작동하는 Claude Code 인스턴스
작업 목록	팀원들이 청구하고 완료하는 공유 작업 항목
메일박스	에이전트 간 통신을 위한 메시징 시스템

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

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

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

훅(Hooks)으로 품질 관리

에이전트 팀에는 전용 훅 두 가지가 있다. 팀원이 작업을 대충 끝내고 넘어가는 걸 자동으로 잡아주는 안전장치다.

TeammateIdle

팀원이 작업을 마치고 "쉬려고 할 때" 실행된다. exit code 2를 반환하면 팀원이 멈추지 않고 계속 일한다.

hooks/teammate-idle-check.sh

#!/bin/bash
if [ ! -f "./dist/output.js" ]; then
  echo "빌드 결과물이 없다. 빌드를 먼저 완료해라." >&2
  exit 2
fi
exit 0

빌드 결과물이 없으면 팀원이 idle 상태로 전환되지 않고, stderr 메시지를 피드백으로 받아서 빌드를 마저 수행한다.

TaskCompleted

작업이 "완료됨"으로 표시될 때 실행된다. 마찬가지로 exit code 2를 반환하면 완료를 막고 피드백을 전달한다.

hooks/task-completed-check.sh

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
 
if ! npm test 2>&1; then
  echo "테스트가 실패한다. 수정 후 다시 완료 처리해라: $TASK_SUBJECT" >&2
  exit 2
fi
exit 0

비유하면 코드 리뷰에서 "LGTM" 없이는 머지를 못하게 막는 것과 같다. 테스트가 통과하지 않으면 작업 완료 자체가 거부된다.

두 훅 모두 matcher를 지원하지 않아서, 한 번 설정하면 모든 팀원/작업에 일괄 적용된다.

토큰 비용과 관리

에이전트 팀은 일반 세션 대비 약 7배의 토큰을 소비한다. 팀원마다 독립 컨텍스트 윈도우를 유지하고, 메시지 교환에도 토큰이 들기 때문이다.

시나리오	일일 예상 비용
단일 세션 개발	~$6/일
팀원 2~3명 리뷰 작업	~~$20~~40/일
팀원 4~5명 병렬 구현	~~$50~~100/일

비용 관리 팁:

팀원 모델로 Sonnet 사용: Opus 대비 비용이 크게 낮으면서 코딩 능력은 충분하다
팀 규모를 최소화: 3명이면 되는 작업에 5명을 투입하면 토큰만 낭비된다
생성 프롬프트를 간결하게: 불필요한 배경 설명은 줄이고 핵심 지시만 전달한다
작업이 끝나면 팀을 정리: 활성 상태의 팀원은 idle 상태에서도 토큰을 소비한다

토큰 비용이 부담스럽다면, 처음에는 팀원 2명 + Sonnet 조합으로 리뷰/조사 작업부터 시작하는 게 현실적이다.

모범 사례

충분한 컨텍스트 제공

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

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

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

정리

에이전트 팀은 단일 세션의 한계를 넘어서는 복잡한 작업에 유용하다. Anthropic은 이 구조로 10만 줄짜리 C 컴파일러를 $20,000에 만들었고, 토큰 비용은 일반 세션의 약 7배지만, 병렬 작업이 주는 속도와 품질 이점은 충분히 그만한 가치가 있다.

핵심을 다시 정리하면:

워커가 결과만 돌려주면 되면 → Subagent
워커끼리 토론하고 협업해야 하면 → 에이전트 팀
처음이라면 팀원 2명 + Sonnet으로 리뷰/연구부터 시작
파일 충돌 방지가 가장 중요한 운영 원칙
훅으로 "테스트 통과 전 완료 금지" 같은 품질 게이트를 자동화할 수 있다
비용 관리: 팀 규모를 최소화하고, 작업이 끝나면 반드시 정리

참고:

Agent Teams 공식 문서: https://code.claude.com/docs/en/agent-teams
Building a C compiler with a team of parallel Claudes: https://www.anthropic.com/engineering/building-c-compiler