▲

Agent Teams - Claude Code 세션 팀 오케스트레이션

 (code.claude.com)
7P by GN⁺ 4시간전 | ★ favorite | 댓글 2개
  • 여러 Claude Code 인스턴스를 하나의 팀으로 구성해 병렬로 작업을 분배·조율하는 실험적 기능으로, 리드 세션이 팀원을 생성하고 작업을 할당하며 결과를 종합
  • 기존 서브에이전트와 달리 팀원 간 직접 메시지 교환이 가능하며, 사용자도 리드를 거치지 않고 개별 팀원과 직접 소통 가능
  • 코드 리뷰, 디버깅 가설 병렬 탐색, 프론트엔드·백엔드·테스트 등 교차 레이어 작업에 효과적이며, 순차 작업이나 동일 파일 수정에는 단일 세션이 더 적합
  • 각 팀원이 독립된 컨텍스트 윈도우를 가지므로 토큰 사용량이 크게 증가하며, 팀원 수에 비례해 비용이 확대될 수 있음
  • tmux 또는 iTerm2를 통한 분할 화면 모드를 지원하고, 병렬 탐색과 협업 자동화를 통해 복잡한 개발 작업의 생산성과 품질 향상을 지원

Agent Teams 개요

  • 여러 Claude Code 세션을 하나의 팀 단위로 조정해 병렬로 작업 수행
    • 팀 리드가 작업을 분배하고 결과를 종합
    • 각 팀원은 독립된 컨텍스트 창에서 개별적으로 실행
  • Subagent 와 달리 팀원 간 직접 메시징 가능
  • 실험적 기능으로 기본 비활성화 상태이며, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수 설정으로 활성화

언제 Agents Teams를 사용하면 좋은가

  • 리서치 및 리뷰: 여러 팀원이 문제의 서로 다른 측면을 동시에 조사한 뒤, 결과를 공유하고 상호 검증
  • 새 모듈이나 기능 개발: 팀원 각자가 별도 파일/모듈을 담당해 충돌 없이 병렬 작업
  • 경쟁 가설 기반 디버깅: 서로 다른 가설을 동시에 테스트해 더 빠르게 원인 파악
  • 교차 레이어 조정: 프론트엔드, 백엔드, 테스트 등 레이어별로 팀원을 배치해 동시 변경
  • 순차 작업, 동일 파일 편집, 의존성이 많은 작업에는 단일 세션이나 서브에이전트가 더 효율적

Subagent vs. Agent Team

  • 서브에이전트: 자체 컨텍스트 윈도우를 가지지만 결과를 호출자에게만 반환, 메인 에이전트가 모든 작업 관리, 토큰 비용이 상대적으로 낮음
  • 에이전트 팀: 완전히 독립된 컨텍스트 윈도우, 팀원 간 직접 메시지 교환 가능, 공유 태스크 리스트로 자체 조율, 각 팀원이 별도 Claude 인스턴스이므로 토큰 비용이 높음
  • 결과만 필요한 집중 작업에는 서브에이전트, 팀원 간 논의·협업이 필요한 복잡한 작업에는 에이전트 팀이 적합

첫 에이전트 팀 시작

  • 기본값은 비활성화 상태이며, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정하거나 settings.json에 해당 환경 변수를 추가해 활성화
  • 활성화 후 자연어로 팀 구조와 작업을 설명하면 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.

    • TODO 트래킹용 CLI 도구를 설계하는데 UX, 기술 아키텍처, 반대 의견 역할 세 팀원을 독립적으로 탐색시킨 뒤 결과를 종합하기
    • 이렇게 하면 클로드가 공유 태스크 리스트를 팀원들을 각각 생성한뒤, 각 문제를 탐색하고, 결과를 종합하고, 작업이 완료되면 팀을 정리하려고 시도
  • 리드 터미널에 전체 팀원 목록과 작업 현황이 표시되며, Shift+Up/Down으로 팀원을 선택해 직접 메시지 전송 가능

에이전트 팀 제어

  • 디스플레이 모드 선택

    • In-process 모드: 모든 팀원이 메인 터미널 내에서 실행, Shift+Up/Down으로 팀원 선택 및 메시지 전송, 별도 설정 불필요
    • Split panes 모드: 각 팀원이 별도 패인에 표시, 출력을 동시에 확인 가능, tmux 또는 iTerm2 필요
    • 기본값 "auto"는 tmux 세션 내부에서 실행 중이면 split pane, 아니면 in-process로 동작
    • "tmux" 설정 시 split-pane 모드를 활성화하며 tmux와 iTerm2를 자동 감지
    • settings.json의 teammateMode로 오버라이드하거나, claude --teammate-mode in-process 플래그로 단일 세션 설정 가능

  • 팀원 및 모델 지정

    • Claude가 작업에 따라 팀원 수를 자동 결정하지만, "Create a team with 4 teammates" 같은 명령으로 정확한 수와 모델(예: Sonnet)을 직접 지정 가능

  • 플랜 승인 요구

    • 복잡하거나 위험한 작업 시 팀원에게 읽기 전용 플랜 모드를 적용해, 리드가 승인할 때까지 구현을 차단
    • 팀원이 플랜을 완성하면 리드에 승인 요청을 보내고, 리드가 승인하면 구현 시작, 거부하면 피드백을 반영해 재제출
    • 리드의 판단 기준은 프롬프트에서 조건을 제시해 영향 가능(예: "테스트 커버리지를 포함한 플랜만 승인")

  • 위임(Delegate) 모드

    • 리드가 작업을 직접 구현하는 대신 조율 전용 도구(팀원 스폰, 메시지, 종료, 태스크 관리)만 사용하도록 제한
    • 팀을 시작한 뒤 Shift+Tab을 눌러 위임 모드로 전환

  • 팀원과의 직접 대화

    • 각 팀원은 완전히 독립된 Claude Code 세션이므로, 추가 지시, 후속 질문, 접근법 변경 등을 직접 전달 가능
    • In-process 모드에서는 Shift+Up/Down으로 선택 후 메시지 전송, Enter로 세션 확인, Escape로 현재 턴 중단, Ctrl+T로 태스크 리스트 토글
    • Split-pane 모드에서는 해당 패인을 클릭해 직접 상호작용

  • 태스크 할당 및 클레임

    • 공유 태스크 리스트를 통해 팀 전체 작업을 조율하며, 태스크 상태는 pending, in progress, completed 세 단계
    • 태스크 간 의존성 설정이 가능하며, 미해결 의존성이 있는 태스크는 클레임 불가
    • 리드가 명시적으로 태스크를 할당하거나, 팀원이 완료 후 다음 미할당·미차단 태스크를 자동 클레임
    • 동시에 여러 팀원이 같은 태스크를 클레임하는 것을 방지하기 위해 파일 잠금 사용

  • 팀원 종료 및 팀 정리

    • 리드에 특정 팀원 종료를 요청하면, 팀원이 승인 또는 거부(사유 설명) 가능
    • 팀 정리 시 리드가 공유 팀 리소스를 제거하며, 활성 팀원이 남아있으면 정리 실패하므로 먼저 팀원을 종료해야 함

에이전트 팀의 내부 작동 방식

  • 팀 시작 경로

    • 사용자가 팀 요청: 병렬 작업에 적합한 태스크를 설명하고 명시적으로 에이전트 팀 생성을 요청
    • Claude가 팀 제안: Claude가 작업 특성상 병렬 처리가 유리하다고 판단하면 팀 생성을 제안, 사용자 확인 후 진행
    • 두 경우 모두 사용자 승인 없이 팀이 생성되지 않음

  • 아키텍처 구성 요소

    • Team lead: 메인 Claude Code 세션, 팀 생성·팀원 스폰·작업 조율 담당
    • Teammates: 별도의 Claude Code 인스턴스, 각자 할당된 태스크 수행
    • Task list: 팀원이 클레임하고 완료하는 공유 작업 항목 목록
    • Mailbox: 에이전트 간 통신을 위한 메시징 시스템
    • 태스크 의존성은 자동 관리되어, 한 팀원이 태스크를 완료하면 차단된 태스크가 수동 개입 없이 언블록
    • 팀 설정은 ~/.claude/teams/{team-name}/config.json, 태스크 리스트는 ~/.claude/tasks/{team-name}/에 로컬 저장
    • config에 members 배열이 포함되어 각 팀원의 이름, 에이전트 ID, 에이전트 타입을 기록

  • 권한

    • 팀원은 리드의 권한 설정을 상속받아 시작하며, 리드가 --dangerously-skip-permissions로 실행하면 모든 팀원도 동일하게 적용
    • 스폰 이후 개별 팀원의 모드 변경은 가능하나, 스폰 시점에 팀원별 권한 설정은 불가

  • 컨텍스트와 커뮤니케이션

    • 각 팀원은 독립된 컨텍스트 윈도우를 가지며, 스폰 시 CLAUDE.md, MCP 서버, 스킬 등 일반 세션과 동일한 프로젝트 컨텍스트를 로드
    • 리드의 대화 기록은 팀원에게 전달되지 않으며, 스폰 프롬프트만 전달
    • 자동 메시지 전달: 팀원이 보낸 메시지는 수신자에게 자동 전달, 리드가 폴링할 필요 없음
    • 유휴 알림: 팀원이 작업을 마치고 멈추면 리드에 자동 통지
    • 공유 태스크 리스트: 모든 에이전트가 태스크 상태를 확인하고 가용 작업을 클레임 가능
    • 메시징 방식으로 message(특정 팀원 1명에게)와 broadcast(전체 팀원에게, 비용이 팀 크기에 비례하므로 절제 필요)가 존재

  • 토큰 사용량

    • 에이전트 팀은 단일 세션 대비 토큰 사용량이 크게 증가, 활성 팀원 수에 비례해 확대
    • 리서치, 리뷰, 새 기능 작업에서는 추가 토큰 비용이 일반적으로 타당하나, 루틴 작업에는 단일 세션이 더 비용 효율적

사용 사례

  • 병렬 코드 리뷰

    • 단일 리뷰어는 한 번에 한 유형의 이슈에 집중하는 경향이 있으므로, 리뷰 기준을 보안, 성능, 테스트 커버리지 등 독립 도메인으로 분할
    • 각 리뷰어가 동일 PR에 서로 다른 필터를 적용하고, 리드가 완료 후 전체 결과를 종합

  • 경쟁 가설 기반 조사

    • 단일 에이전트는 하나의 설명을 찾으면 탐색을 중단하는 경향이 있어, 팀원을 명시적으로 적대적 구조로 구성
    • 각 팀원이 자기 가설을 조사하면서 동시에 다른 팀원의 이론을 반증하려 시도하는 과학적 토론 방식
    • 순차 조사에서 발생하는 앵커링 편향을 방지하고, 살아남은 이론이 실제 근본 원인일 가능성을 높임

모범 사례

  • 팀원에게 충분한 컨텍스트를 제공: 프로젝트 컨텍스트는 자동 로드되지만 리드의 대화 기록은 전달되지 않으므로, 스폰 프롬프트에 작업 관련 세부 사항을 포함해야 함
  • 태스크 크기를 적절히 조정: 너무 작으면 조율 오버헤드가 이점을 초과하고, 너무 크면 체크인 없이 오래 작업해 낭비 위험 증가, 함수·테스트 파일·리뷰 등 명확한 결과물을 생산하는 자기 완결 단위가 적합
  • 리드가 팀원 대신 직접 구현을 시작하면 "Wait for your teammates to complete their tasks before proceeding"으로 지시
  • 처음 사용 시에는 코드 작성 없이 경계가 명확한 리서치 및 리뷰 작업(PR 리뷰, 라이브러리 조사, 버그 조사 등)부터 시작
  • 파일 충돌 방지: 두 팀원이 같은 파일을 편집하면 덮어쓰기가 발생하므로, 각 팀원이 서로 다른 파일 집합을 담당하도록 작업 분할
  • 팀원의 진행 상황을 주기적으로 확인하고, 효과가 없는 접근법은 방향을 전환시키며, 결과가 나오는 대로 종합

트러블슈팅

  • 팀원이 나타나지 않는 경우: in-process 모드에서는 Shift+Down으로 활성 팀원 순환, 작업이 팀 구성에 충분히 복잡한지 확인, split pane 요청 시 tmux가 PATH에 설치되었는지 확인, iTerm2의 경우 it2 CLI 설치 및 Python API 활성화 확인
  • 과도한 권한 프롬프트: 팀원의 권한 요청이 리드에 버블업되므로, 팀원 스폰 전 권한 설정에서 공통 작업을 사전 승인
  • 팀원이 오류 후 중단: 해당 팀원 출력을 확인한 뒤 직접 추가 지시를 주거나, 대체 팀원을 스폰해 작업 계속
  • 리드가 작업 완료 전에 종료: 리드에 계속 진행하도록 지시하거나, 위임 전에 팀원 완료를 기다리도록 설정
  • 고아 tmux 세션: 팀 종료 후 tmux 세션이 남아있으면 tmux ls로 확인 후 tmux kill-session -t <session-name>으로 제거

제약 사항

  • In-process 팀원의 세션 복원 불가: /resume과 /rewind가 in-process 팀원을 복원하지 않으며, 복원 후 리드가 존재하지 않는 팀원에 메시지를 보낼 수 있으므로 새 팀원 스폰 필요
  • 태스크 상태 지연: 팀원이 태스크 완료를 표시하지 않아 의존 태스크가 차단될 수 있으며, 수동으로 상태를 업데이트하거나 리드에 팀원 독촉 요청
  • 종료 지연: 팀원이 현재 요청이나 도구 호출을 마친 후에야 종료
  • 세션당 하나의 팀만 가능: 새 팀을 시작하려면 현재 팀을 먼저 정리해야 함
  • 중첩 팀 불가: 팀원은 자체 팀이나 팀원을 스폰할 수 없고, 리드만 팀 관리 가능
  • 리드 고정: 팀을 생성한 세션이 해당 팀의 영구 리드이며, 팀원을 리드로 승격하거나 리더십 이전 불가
  • 스폰 시 권한 일괄 설정: 모든 팀원이 리드의 권한 모드로 시작하며, 스폰 시점에 팀원별 권한 설정 불가
  • Split pane은 tmux 또는 iTerm2 필요: VS Code 통합 터미널, Windows Terminal, Ghostty에서는 split-pane 모드 미지원
▲
kuthia 28분전  [-]

멀티 에이전트 오케스트레이션을 위해 컨텍스트 압축 과정에서 의미론적인 결과를 어떻게 보존하느냐가 중요해지겠네요. 인지과학 같네요.

답변달기
▲
GN⁺ 4시간전  [-]
Hacker News 의견들

  • 지난 1년간의 혁신이 주로 엔지니어링 중심으로 흘러온 게 흥미로움
    MCP, agent, skill 등 새로운 개념들이 쏟아졌지만, 여전히 환각·부정확성·문맥 붕괴 같은 근본 문제는 해결되지 않았음
    이런 문제는 단순한 엔지니어링이 아니라 기초 연구로만 풀릴 것 같음
    지금의 개선과 발표들은 투자자들의 기대를 유지하기 위한 하이프 사이클의 일부처럼 느껴짐
    솔직히 AI라는 내러티브가 지쳐서, 이 기술이 실제로 어디에 유용한지 명확해지는 시점으로 빨리 넘어가고 싶음

  • 이런 기능이 멋지긴 하지만, 하루 종일 agent를 돌릴 수 있는 사람이 얼마나 될까 하는 의문이 있음
    Cursor를 쓰면서 토큰 소모량이 너무 커서 Ultra로 업그레이드했는데, 사용량이 비례하지 않는 느낌임
    다행히 오픈소스 LLM 진영이 빠르게 따라오고 있어서 희망적임

    • 나는 Claude Max의 월 200회 한도도 다 못 씀. 매일 코딩하고 꽤 무거운 작업을 하는데도 그렇음
    • 이런 건 사실상 실험 단계라, Gas Town처럼 실패할 수도 있음
    • 많은 회사가 연봉 15만 달러짜리 주니어 엔지니어를 고용할 수 있음. AI 구독료가 그보다 비싸다면 문제임
      게다가 지금 얘기하는 건 Cursor가 아니라 Claude Code임. 차라리 Claude Max를 써보길 권함
    • 이런 걸 하루 종일 돌릴 수 있는 건 VC 자금 받은 2인 스타트업 정도일 것 같음
    • Claude Code Max는 토큰 단가 대비 30배 가치가 있어서, 다 못 쓰면 본인 책임임. 전기요금보다 쌀지도 모름

  • Steve Yegge가 예전에 Anthropic 같은 회사에 agent orchestrator 아이디어를 제안했었음
    (Welcome to Gas Town)
    Anthropic이 이제 Agent Teams를 내놓은 걸 보면, 이미 그때부터 준비했거나 같은 결론에 도달한 듯함
    어쨌든 Steve의 비전이 검증된 셈이라 흥미로움. 곧 “폴캣 길들이기” 시즌이 올지도 모름

    • 나도 GasTown이나 Beeds를 몰랐지만 비슷한 걸 만들었음. 너무 자연스러운 다음 단계였음
      claude-code-orchestrator
    • 나도 GasTown 열풍 전에 간단한 agent 팀 구조를 만들어봤음. 여러 Claude 인스턴스를 tmux 세션으로 돌리고, .claude.lock으로 동기화했음
      꽤 잘 돌아갔지만, 아직은 효율적이지 않음. 스펙 작성 속도와 QA 품질이 병목임
    • 사실 이런 구조는 actor 프레임워크에서 이미 존재하던 개념임. Akka 같은 시스템과 비교하면 새로울 게 없음
      LLM provider들이 이제야 이런 걸 배우는 걸 보면, 실시간으로 성장 중이라는 생각이 듦
      Kubernetes for agents라는 말도 과장이 아님. 나도 로컬에서 그렇게 연결해 씀
    • Anthropic 엔지니어들이 이런 아이디어를 몰랐을 리 없다고 생각함. ChatGPT 초창기부터 이런 얘기 많았음
    • 사실 이런 multi-agent 시스템은 2023년부터 arxiv와 GitHub에 많았음
      그때는 모델이 덜 똑똑하고 context window가 작았을 뿐, 지금은 충분히 가능해진 것뿐임

  • 나는 여러 Claude Code 인스턴스를 tmux 기반 CLI agent로 돌려 협업시키는 워크플로를 써왔음
    이번 orchestration 기능은 공통 task list를 공유하고 메인 agent가 조율해주기 때문에 훨씬 유용함
    tmux-cli 도구로 agent 간 협업을 자동화할 수 있음

  • 이런 기능이 언젠가 기본 내장될 게 뻔해서 지금까지 배우지 않았는데, 이제는 써볼 시점인 듯함

  • 내 $20/월 구독이 10분도 못 버틸 것 같다는 걱정이 있음

    • 개인이 직접 결제한다면 Kimi나 GLM을 쓰는 게 더 합리적임
    • 나도 같은 생각임. 이런 구조가 실제로 가치를 낼 수 있을지 의문임
    • 특정 작업에서는 Haiku가 꽤 좋은 결과를 줬음

  • 이건 Gas Town과 비슷해 보임

    • 프로젝트가 너무 기괴하거나 장난스럽게 가면, 결국 덜 유치한 클론이 나와서 이길 가능성이 큼
    • 그런데 폴캣은 어디 갔는지, 시장의 유머 감각이 궁금함
    • Gas Town이 뭔지는 모르지만, 나는 이미 Claude Code Agent Teams와 비슷한 구조를 써왔음
      메인 대화에서 하위 agent를 생성해 작업을 분리하면 문맥 손실 없이 오래 일할 수 있음
    • 디자인이 더 단순해 보임. 리더 agent 하나와 여러 worker 구조로, Gas Town의 복잡한 역할 체계보다 깔끔함
    • 하지만 폴캣이 없다는 점은 아쉬움

  • 나는 Claude Code를 대형 작업에 독립적으로 맡길 수 없음
    코드 품질을 유지하려면 설계 과정에 직접 개입해야 함
    agent 팀은 오히려 리뷰와 리팩터링 부담만 늘릴 것 같음

    • 코드베이스 구조와 패턴 사용 규칙을 skill로 인코딩하면, sub-agent가 이를 감독하도록 할 수 있음
      이런 식으로 계획·설계·QA·리뷰 agent를 나눠 협업시키는 게 바로 이 기능의 본질임
    • Claude 내에서 적대적 모델을 만들어 품질을 높이는 방법도 있음. 한 agent가 수정하고, 다른 agent가 검증하는 식임
    • 인간도 큰 작업은 쪼개서 처리하듯, Claude에게 계획과 테스트 기준을 세우게 하면 효율적임
    • 실제로 3~4번 중 한 번은 튜닝이나 중단이 필요함. 숙련된 사람만 그걸 인지함
    • LLM의 작업 분할과 결과 결합에 대한 연구도 진행 중임
      관련 논문

  • 나는 Opus를 메인으로, 하위 agent는 Gemini나 Codex로 돌리는 멀티 LLM 오케스트레이션을 찾고 있음

    • 이런 구조를 지원하는 도구로 Coder-Codex-Gemini, ccg-workflow, claude_code_bridge가 있음
      모두 중국 개발자가 만든 프로젝트지만, 써본 결과 꽤 훌륭했음
    • AgentWorkforce/relay를 쓰면 원하는 LLM을 리드/오케스트레이터로 지정할 수 있음
      관련 경험을 트위터 글에 정리했음
    • 나는 Opus로 코딩하고 Codex로 리뷰함. 각 작업마다 review skill을 호출해 Codex를 실행함
      review skill 코드, Greptile PR 분석기도 함께 씀
    • 앞으로 Cursor가 이런 멀티 모델 협업 기능을 지원하면 정말 유용할 것 같음
    • Pied-Piper라는 예시처럼,
      GPT-5.2 Codex Max로 계획, Opus 4.5로 구현, Gemini로 리뷰를 맡기는 구조도 가능함

  • 나는 Beads의 대안을 직접 만들다가, 결국 비슷한 구조로 GitHub 프로젝트와 동기화되는 agent 시스템을 완성했음
    곧 오픈소스로 공개할 예정이며, 티켓 시스템과 연동되는 게 장기적으로 더 유용하다고 생각함
    agent에 종속되지 않는 agnostic한 대안이 많아지는 게 바람직함

답변달기