Claude Code 스웜(Swarms) — 에이전트 팀 기능 정식 공개

Claude Code에 에이전트 팀 기능(스웜)이 추가됐다. 하나의 에이전트가 작업을 순차적으로 처리하는 대신, 리드 에이전트가 여러 팀원에게 작업을 위임해 리서치·디버깅·빌드를 병렬로 수행하고, 팀원끼리 서로 조율까지 한다. settings.json에서 에이전트 팀을 활성화하면 바로 사용해볼 수 있다. Conductor, Gas Town 등으로 멀티 에이전트 오케스트레이션을 직접 구성해봤다면, 이번 소식이 반가울 것이다.

커뮤니티에서는 이런 패턴을 스웜(Swarm)이라 불러왔다. 각자 전문 역할을 맡은 AI 에이전트들이 팀을 이루어 구조화된 커뮤니케이션으로 병렬 작업을 수행하는 방식이다. 처음에는 개발자들이 Claude Code 바이너리에서 피처 플래그된 기능을 발견하고, 서브에이전트와 bash 스크립트로 우회하며 비슷한 구조를 만들어 썼다. 이제 이것이 정식 기능이 됐다. TeammateTool, 인박스 기반 커뮤니케이션, tmux 분할 패널까지 모두 갖추어져 있다.

이 기능이 중요한 이유는 대다수가 써온 단일 에이전트 모델과는 근본적으로 다른 아키텍처이기 때문이다. 컨덕터에서 오케스트레이터로의 전환을 주시해왔거나, 병렬 에이전트 워크플로를 실험해본 적이 있다면, 에이전트 팀이야말로 그 아이디어들이 현실로 구현된 결과물이다.

멀티 에이전트 협업이 중요한 이유

단일 에이전트 모델에는 잘 알려진 한계가 있다. 예를 들어, 세 개 서비스에 걸친 인증 리팩토링 같은 복잡한 작업을 맡기면 60% 정도 진행한 시점에서 컨텍스트가 흐려지기 시작한다. 2단계에서 다룬 세부 사항이 5단계에서 뒤섞인다. 결국 /clear로 초기화하고 처음부터 다시 시작하는 과정을 반복하다 지치게 된다.

스웜의 핵심 통찰은 단순하다. LLM은 컨텍스트가 길어질수록 성능이 떨어진다. 단순히 토큰 한도에 걸리는 문제가 아니다. 컨텍스트 윈도우에 정보가 많아질수록, 모델이 지금 당장 중요한 것에 집중하기 어려워진다. CSS 버그를 고치는 중인 컨텍스트에 프로젝트 매니저의 전략 노트까지 끼워 넣으면, 오히려 성능이 나빠진다.

사람 팀도 비슷하게 작동한다. 백엔드 엔지니어가 프론트엔드 코드 리뷰에 참석하지 않고, 모든 Slack 스레드에 회사 전체를 CC하지도 않는다. 전문화의 본질은 집중이다.

멀티 에이전트 패턴은 이 원리를 체계화한 것이다. 각 에이전트에 좁은 범위와 깨끗한 컨텍스트를 부여하면, 각 도메인에서 더 나은 추론, 독립적인 품질 검증, 단계 간 자연스러운 체크포인트, 한 에이전트가 실패해도 전체에 영향이 적은 우아한 장애 격리를 얻을 수 있다. 테스트 에이전트의 컨텍스트에는 테스트 관련 내용만 들어가고, 세 시간짜리 기획 논의는 들어가지 않는다. 보안 리뷰어는 성능 최적화 노트를 뒤질 필요가 없다.

단, 작업이 적절히 분할됐을 때만 효과가 있다. "앱 하나 만들어줘" 같은 요청은 에이전트들이 갈팡질팡하며 토큰만 소모한다. 반면 "이 스펙에 따라 5개 API 엔드포인트를 구현해줘"처럼 명확히 정의된 작업은 좋은 결과를 만들어낸다.

에이전트 팀의 구조

아키텍처는 직관적이다. Claude Code 세션 하나가 팀 리드 역할을 맡는다. 리드가 팀원(Teammate)을 생성하면, 각 팀원은 자체적으로 큰 토큰 컨텍스트 윈도우를 가진 완전히 독립적인 Claude Code 인스턴스로 작동한다. 의존성 추적이 가능한 공유 태스크 목록, 에이전트 간 커뮤니케이션을 위한 인박스 기반 메시징 시스템이 갖추어져 있으며, 팀원은 작업을 마치면 다음 작업을 스스로 가져갈 수 있다.

기존 Claude Code의 서브에이전트와는 다른 개념이다. 서브에이전트는 결과를 상위 에이전트 하나에만 보고하는 집중형 워커로, 서로 간 소통이 불가능하다. 반면 에이전트 팀은 실제 협업이다. 팀원끼리 발견 사항을 공유하고, 서로의 접근 방식에 이의를 제기하며, 독립적으로 조율한다. 대신 토큰 비용이 높다는 트레이드오프가 있다. 각 팀원이 별도의 Claude 인스턴스이기 때문이다.

빠르고 집중적인 워커가 필요하면 서브에이전트를, 팀원 간 발견 공유와 상호 검증, 자율 조율이 필요하면 에이전트 팀을 사용하자.

Claude Code에 에이전트 팀 기능이 추가됐습니다 (리서치 프리뷰)

하나의 에이전트가 순차적으로 작업하는 대신, 리드 에이전트가 여러 팀원에게 위임해 리서치·디버깅·빌드를 병렬로 수행하고 서로 조율합니다.

지금 바로 사용해보세요… pic.twitter.com/vi7lUJDOTi

— Lydia Hallie ✨ (@lydiahallie) February 5, 2026

시작하기

설정에 실험적 플래그를 추가하면 에이전트 팀을 활성화할 수 있다:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

그 다음, 원하는 팀 구성을 자연어로 Claude에게 지시하면 된다. 스폰과 조율은 Claude가 알아서 처리한다:

Claude가 공유 태스크 목록과 함께 팀을 구성하고, 각 관점별로 팀원을 스폰해 문제를 탐색한 뒤, 결과를 종합한다. 리드의 터미널에는 모든 팀원과 현재 작업 현황이 표시된다.

팀 구조를 직접 명시할 수도 있다:

에이전트 팀이 빛을 발하는 경우

효과가 입증된 패턴이 있다: 병렬 탐색이 실질적 가치를 더하고, 팀원이 대체로 독립적으로 작업할 수 있는 태스크다.

디버깅을 위한 경쟁 가설 검증. 앱이 메시지 하나를 처리한 뒤 종료되는 원인에 대해 서로 다른 가설을 조사하는 팀원 5명을 스폰하자. 팀원들이 과학적 토론처럼 서로의 가설을 반증하게 한다. 순차적 조사보다 확실히 낫다. 순차적 방식은 앵커링 편향에 취약해서, 첫 번째 가설을 탐색하고 나면 이후 조사가 그쪽으로 쏠리기 마련이다. 여러 조사자가 반론을 주고받으면 근본 원인에 더 빠르게 수렴한다.

관점별 병렬 코드 리뷰. 팀원 하나는 보안, 하나는 성능 영향, 하나는 테스트 커버리지를 검증한다. 리뷰어가 한 명이면 한 번에 한 유형의 이슈에 집중하기 쉬운데, 리뷰 기준을 독립적인 도메인으로 분리하면 각각이 동시에 철저한 검토를 받게 된다.

레이어를 넘나드는 피처 개발. 프론트엔드·백엔드·테스트에 걸친 변경을 각각 다른 팀원이 담당한다. 하나의 에이전트가 레이어 간 컨텍스트 스위칭을 반복하는 대신, 세 에이전트가 각자 도메인에 온전히 집중하며 병렬로 작업한다.

리서치와 탐색. 여러 팀원이 동시에 다양한 접근법을 조사하고, 발견 사항을 공유한 뒤, 최선의 경로로 수렴한다. 리서치 결과가 구현 컨텍스트에 바로 전달되므로, 전달 과정에서 정보가 왜곡될 일이 없다.

팀 제어하기

에이전트 팀과의 상호작용은 리드의 터미널을 통해 이루어진다. 실제로 자주 쓰이는 주요 기능을 알아보자:

디스플레이 모드

두 가지 옵션이 있다. 인프로세스(In-process) 모드(기본값): 모든 팀원이 메인 터미널 안에서 실행된다. Shift+Up/Down로 팀원을 선택하고 직접 메시지를 보낼 수 있다. Enter로 팀원 세션을 확인하고, Escape로 팀원의 턴을 중단하며, Ctrl+T로 태스크 목록을 토글한다. 어떤 터미널에서든 작동한다.

분할 패널(Split panes) 모드: tmux 또는 iTerm2를 통해 각 팀원에게 별도 패널이 할당된다. 모든 팀원의 출력을 한눈에 보면서, 패널을 클릭해 직접 상호작용할 수 있다. 설정에서 지정하거나 세션별로 설정 가능하다:

{
  "teammateMode": "tmux"
}

단일 세션에만 적용하려면:

claude --teammate-mode in-process

계획 승인(Plan approval)

위험도가 높은 작업에서는 팀원이 구현에 앞서 계획을 먼저 제출하도록 할 수 있다. 리드가 승인할 때까지 팀원은 읽기 전용 모드로 작업한다:

거절되면 팀원이 수정 후 다시 제출한다. 리드의 판단 기준을 직접 지정할 수도 있다: "테스트 커버리지가 포함된 계획만 승인해" 또는 "데이터베이스 스키마를 변경하는 계획은 거절해" 같은 식이다.

위임 모드(Delegate mode)

Shift+Tab를 누르면 리드의 역할을 조율 전용으로 제한할 수 있다. 팀원 스폰, 메시징, 종료, 태스크 관리만 가능하고 코드를 직접 건드리지 못한다. 리드가 팀원 결과를 기다리지 않고 직접 구현에 손대는 흔한 문제를 방지해준다.

팀원과 직접 소통

각 팀원은 완전한 Claude Code 세션이다. 리드를 거치지 않고도, 아무 팀원에게 직접 메시지를 보내 추가 지시를 내리거나, 후속 질문을 하거나, 접근 방식을 변경시킬 수 있다.

태스크 관리

공유 태스크 목록이 팀 전체의 작업을 조율한다. 태스크는 대기(pending), 진행 중(in progress), 완료(completed)의 세 가지 상태를 갖는다. 태스크 간 의존성도 설정할 수 있어서, 선행 태스크가 완료되지 않으면 후속 태스크를 가져갈 수 없다. 선행 태스크가 끝나면 후속 태스크의 블로킹이 자동으로 해제된다.

리드가 태스크를 직접 할당할 수도 있고, 팀원이 작업을 마친 후 미할당·미블로킹 상태인 다음 태스크를 스스로 가져갈 수도 있다. 태스크 클레임 시 파일 잠금(file locking)을 사용해 경합 조건을 방지한다.

팀과 태스크 정보는 로컬에 저장된다:

~/.claude/teams/{team-name}/config.json    # Team metadata + members
~/.claude/tasks/{team-name}/               # Task list

팀원은 설정 파일을 읽어 다른 팀원을 인식할 수 있다.

종료하기

리드에게 특정 팀원의 종료를 요청하면, 해당 팀원은 요청을 승인하거나 사유와 함께 거절할 수 있다. 팀 전체를 정리하려면:

Clean up the team

정리는 반드시 리드를 통해 해야 한다. 팀원이 직접 실행하면 팀 컨텍스트가 올바르게 해석되지 않아, 리소스가 불일치 상태로 남을 수 있다. 리드는 활성 팀원이 남아 있으면 정리를 거부하므로, 먼저 팀원을 종료한 뒤 정리를 실행하자.

엔지니어링 매니지먼트와의 유사성

계속 느끼는 점인데, 뛰어난 엔지니어링 매니저를 만드는 역량이 에이전트 오케스트레이션에도 그대로 적용된다. 에이전트 팀에서는 이 유사성이 한층 더 뚜렷해진다.

태스크 크기가 중요하다. 너무 작으면 조율 오버헤드가 실제 작업보다 커지고, 너무 크면 팀원이 체크인 없이 오래 작업해 노력이 낭비될 수 있다. 적정 크기는 명확한 결과물을 내는 자기완결적 단위다. 팀원당 5~6개 태스크를 배정하면 모두가 생산적으로 일할 수 있고, 누군가 막히면 리드가 작업을 재배분하기도 쉽다.

파일 소유권이 중요하다. 두 팀원이 같은 파일을 수정하면 덮어쓰기가 발생한다. 각 팀원이 서로 다른 파일 세트를 담당하도록 작업을 분리해야 한다. 머지 충돌을 피하기 위해 사람 팀에서 경계를 설정하는 것과 같은 원리다.

컨텍스트 로딩이 중요하다. 팀원은 프로젝트의 CLAUDE.md, MCP 서버, 스킬을 자동으로 상속받지만, 리드의 대화 기록은 상속받지 않는다. 스폰 프롬프트에 태스크별 세부 사항을 포함시키자:

브리프가 구체적일수록 결과물의 품질이 높아진다. 이 원칙은 달라진 게 없다. 다만 이제 브리프를 쓰는 대상이 단일 에이전트가 아니라 팀이라는 점만 다르다.

주의할 점

아직 실험적 기능이다. 거친 부분이 분명히 존재하므로 미리 알아두는 것이 좋다.

리드가 위임 대신 직접 구현하는 경우가 있다. "팀원이 작업을 완료할 때까지 기다려"라고 지시하거나, 위임 모드(Shift+Tab)를 사용해 리드를 조율 전용 도구로 제한하자.

인프로세스 팀원은 세션 복원이 안 된다. /resume와 /rewind 명령이 인프로세스 팀원을 복원하지 못한다. 세션 재개 후 리드가 이미 존재하지 않는 팀원에게 메시지를 보내려 할 수 있다. 새 팀원을 스폰하자.

태스크 상태 갱신이 지연될 수 있다. 팀원이 완료된 태스크를 완료 처리하지 않아 후속 태스크가 블로킹되는 경우가 있다. 작업이 실제로 끝났는지 확인하고, 리드에게 넛지를 주거나 수동으로 상태를 업데이트하자.

세션당 팀 하나, 중첩 팀 불가. 리드는 한 번에 하나의 팀만 관리한다. 팀원이 자체적으로 팀이나 팀원을 스폰할 수 없으며, 팀 관리는 오직 리드만 할 수 있다. 이는 의도적인 설계로, 무한 재귀·토큰 비용 폭주·사람의 감독 상실을 방지한다. 새 팀을 시작하기 전에 현재 팀을 먼저 정리하자.

토큰 비용은 팀원 수에 비례한다. 각 팀원은 자체 컨텍스트 윈도우를 가진 별도의 Claude 인스턴스다. 단순 반복 작업이라면 단일 세션이 훨씬 경제적이다. 멀티 에이전트 패턴은 규모가 크고 병렬화 가능한 작업에서 효과를 발휘한다. 오타 수정에는 쓰지 말자.

분할 패널에는 tmux 또는 iTerm2가 필요하다. VS Code 통합 터미널, Windows Terminal, Ghostty에서는 지원되지 않는다. 기본 인프로세스 모드는 어디서든 작동한다.

권한은 리드 설정을 상속한다. 모든 팀원은 리드의 권한 설정으로 시작한다. 리드가 --dangerously-skip-permissions로 실행되면 모든 팀원도 동일하게 적용된다. 스폰 후에 개별 팀원의 모드를 변경할 수는 있지만, 스폰 시점에 팀원별 모드를 지정하는 것은 불가능하다.

종료가 느릴 수 있다. 팀원이 현재 진행 중인 요청이나 도구 호출을 완료한 뒤에야 종료되므로, 시간이 걸릴 수 있다.

한 가지 당부

에이전트 여러 개가 동시에 돌아가는 모습은 묘한 쾌감이 있다. 시간당 커밋 수, 병렬 태스크 완료율, 변경된 코드 라인 수 같은 활동 지표도 인상적으로 보인다.

하지만 활동량이 곧 가치는 아니다.

멀티 에이전트 시스템의 위험은 대량의 코드를 매우 빠르게 만들어내기 쉽다는 것이다. 그 코드가 정확하고, 유지보수 가능하며, 실제로 문제를 해결하는지는 여전히 사람이 검증해야 한다. 오케스트레이션 패턴을 설정하느라 정작 무엇을 만들고 있는지에 대한 사고를 잃어버리는 개발자를 여럿 봐왔다.

문제가 도구를 결정해야지, 도구가 문제를 결정해서는 안 된다. 집중된 단일 에이전트 세션이 더 빠르다면 그것을 쓰면 된다. 병렬 전문가가 필요하다면 에이전트 팀을 쓰면 된다. 에이전트 팀은 조율 오버헤드가 추가되고 단일 세션보다 토큰도 훨씬 많이 소모한다. 팀원이 독립적으로 작업할 수 있을 때 가장 효과적이다. 순차 작업, 같은 파일 수정, 의존성이 많은 작업에는 단일 세션이나 서브에이전트가 더 낫다.

Compound Engineering으로 스웜 효과 극대화하기

에이전트 팀을 더 체계적인 워크플로로 운영하고 싶다면, Every에서 만든 Compound Engineering 플러그인을 살펴볼 만하다. Claude Code 플러그인 형태로, 전문 리뷰 에이전트와 함께 계획(plan) → 작업(work) → 리뷰(review) → 복리 축적(compound) 사이클을 제공한다. 모든 엔지니어링 작업 단위가 다음 작업을 더 쉽게 만들어야 한다는 철학에 기반한다.

Claude Code에서 바로 설치 가능하다:

/plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin
/plugin install compound-engineering

에이전트 팀과 관련성이 높은 기능: /workflows:plan는 피처 아이디어를 상세한 구현 계획으로 전환한다(에이전트 위임이 잘 작동하려면 바로 이런 사전 스펙이 필요하다). /workflows:review는 머지 전에 멀티 에이전트 코드 리뷰를 수행한다(보안·성능·아키텍처·복잡도를 각각 전문 리뷰어가 담당). /workflows:compound는 학습 내용을 문서화해 이후 에이전트가 과거 작업에서 이점을 얻도록 한다.

마지막 기능이 특히 흥미롭다. 이 플러그인의 철학 — 80%는 기획과 리뷰, 20%는 실행 — 은 에이전트 팀을 효과적으로 운영하는 원리와 정확히 맞닿아 있다. 스펙이 좋을수록 에이전트 결과물이 좋아지고, 학습을 많이 코드화할수록 이후 에이전트가 헤매는 시간이 줄어든다. AGENTS.md와 영속적 컨텍스트에서 설명한 복리 효과와 같은 원리인데, 반복 가능한 워크플로로 패키징되어 있다는 점이 다르다.

Claude Code 외에 OpenCode나 Codex를 사용한다면, 해당 도구에서도 실험적으로 지원된다.

시작한다면 이렇게 해보자

멀티 에이전트 협업이 처음이라면, 작은 것부터 시작하자.

리서치와 리뷰부터 시작하자. 코드 작성이 필요 없으면서 경계가 명확한 태스크 — PR을 세 가지 관점에서 리뷰하거나, 라이브러리를 조사하거나, 경쟁 가설로 버그를 추적하는 작업이 좋다. 병렬 코드 변경의 조율 복잡성 없이도 병렬 탐색의 가치를 확인할 수 있다.

그 다음, 레이어 간 피처 작업을 시도하자. 프론트엔드·백엔드·테스트를 각각 다른 팀원이 담당하는 구조다. 경계가 깔끔하고 결과물이 명확하다.

그 뒤에 대규모 리팩토링으로 확장하자. 설계 단계를 공유한 뒤 여러 서비스를 병렬로 구현하는 방식이다. 이때 시간 압축 효과가 극적으로 나타난다 — 순차적으로 며칠 걸릴 작업이 병렬 실행 + 리뷰로 몇 시간 안에 끝날 수 있다.

핵심 역량은 코드를 덜 쓰는 것이 아니다. 에이전트 팀이 실행할 수 있는 구조로 문제를 분해하는 것 — 무엇을 만들어야 하는지, 정확성의 기준이 무엇인지, 결과를 어떻게 검증할지를 아는 것이다. 구현 자체는 점점 더 정밀한 스펙의 문제로 수렴하고 있다.

에이전트끼리 실제로 협업할 수 있게 됐을 때, 에이전틱 엔지니어링이 어떤 모습인지 바로 이것이다. 협업형 AI 에이전트 시스템을 위한 아키텍처가 도착했다. 현명하게 활용하자.

전체 설정 및 사용법은 Claude Code 에이전트 팀 공식 문서에서 확인할 수 있다.

에이전틱 코딩 워크플로의 진화에 대해 Elevate 뉴스레터와 O'Reilly 저서 Beyond Vibe Coding에서 다루고 있습니다. 에이전트 팀이나 멀티 에이전트 워크플로를 실험 중이시라면, 어떤 방식이 효과적이었는지 꼭 들려주세요.