Claude Code: "에이전트 팀" 오케스트레이션 가이드

💡 한줄 요약: Claude Code에 실험적 기능으로 '에이전트 팀(Agent Teams)'이 추가되었습니다. 이제 메인 리드 에이전트가 여러 서브 에이전트를 생성, 작업 할당, 조율하며 복잡한 병렬 작업을 수행할 수 있습니다. tmux와 연동하면 한 화면에서 팀 전체를 관제할 수 있습니다.

배경

Claude Opus 4.6과 함께 공개된 Claude Code의 '에이전트 팀' 기능에 대한 공식 문서가 업데이트되었습니다. 이전의 'Subagents'가 메인 세션 내에서 종속적으로 동작했다면, 'Agent Teams'는 각자 독립적인 컨텍스트를 가진 "동료"들이 서로 소통하며 문제를 해결하는 구조입니다.

특히, 리드 에이전트(Lead)가 전체를 조율하고, 팀원들(Teammates)이 각자 맡은 역할을 수행하는 모습은 마치 PM과 개발팀이 협업하는 과정과 흡사합니다.

📌 핵심 정리

• 독립적 컨텍스트: 각 팀원은 별도의 컨텍스트 윈도우를 가지며 독립적으로 사고합니다. (토큰 비용 증가 주의)
• 동료 간 직접 소통: 리드를 거치지 않고 팀원끼리 정보를 교환하고 토론할 수 있습니다.
• 디스플레이 모드:
  • In-process: 하나의 터미널에서 Shift+Up/Down으로 전환 (기본)
  • Split panes: tmux나 iTerm2를 활용해 화면을 분할하여 모든 에이전트의 작업을 동시에 모니터링
• 활성화 방법: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경 변수 설정 필요
• 주요 유스케이스:
  • 다각도 코드 리뷰 (보안/성능/테스트 담당 분리)
  • 경쟁 가설 디버깅 (서로 다른 원인 가설을 세우고 논쟁하며 검증)

MAX5의 생각 🎯

👨‍💻 바이브 코딩 레시피

가장 흥미로운 부분은 "경쟁 가설 디버깅(Debugging with competing hypotheses)" 패턴입니다. 해결되지 않는 버그가 있을 때, 에이전트들을 싸우게(?) 만들어보세요.

1. 설정 활성화 (~/.claude/settings.json 또는 환경변수)

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "teammateMode": "tmux" // tmux 사용 시 추천
}

2. 프롬프트 예시

# 버그 리포트와 함께 실행
이 버그의 원인을 찾지 못하겠어. 3명의 에이전트 팀을 꾸려서 경쟁적으로 원인을 파악해줘.
- 에이전트 A: 네트워크/API 이슈라고 가정하고 분석
- 에이전트 B: 데이터베이스/캐싱 이슈라고 가정하고 분석
- 에이전트 C: 프론트엔드 상태 관리 이슈라고 가정하고 분석
서로의 가설을 반박하면서 진짜 원인이 무엇인지 토론하고 결론을 내려줘.

이렇게 하면 한 명의 에이전트가 편향된 시각으로 삽질하는 것을 막고, 집단 지성을 통해 훨씬 빠르게 문제의 핵심에 도달할 수 있습니다.

💸 사이드 프로젝트 아이디어

"AI 코드 리뷰어 팀 플러그인" 개발자가 PR을 올리면 자동으로 Claude Code Agent Team을 띄워주는 워크플로우 툴입니다.

• 구조: GitHub Action으로 트리거 → Claude Code 실행
• 역할 분담:
  • 🕵️ 보안관: SQL Injection, XSS 등 보안 취약점만 집중 점검
  • 🏎️ 레이서: N+1 문제, 비효율적 알고리즘 등 성능 점검
  • 📝 작가: 변수명, 주석, 문서화 상태 점검
• 결과: 각 담당자가 남긴 코멘트를 종합하여 PR 리뷰 코멘트로 등록