This page is also available in English.View in English

← 블로그로 돌아가기

Claude Code 에이전트 팀 설정과 사용법

업데이트 2026-11: Claude Code 에이전트 팀이 무엇인지, 켜는 방법, 서브에이전트와의 차이, 각 팀원과 직접 대화하는 방법을 정리했습니다.

읽는 데 9분

Claude Code 에이전트 팀 설정과 사용법

업데이트 2026-11

TL;DR: Claude Code 에이전트 팀을 쓰면 Claude Code 세션 하나가 팀 리더가 되어 작업 목록을 만들고, 팀원을 띄우고, 이들을 조율합니다. 각 팀원은 자기만의 컨텍스트 창에서 일하며 서로 메시지를 주고받을 수 있습니다. 이 기능은 아직 실험 단계이고 기본값은 꺼져 있습니다. 설정 하나로 켠 뒤 원하는 팀을 프롬프트로 설명하면, 어느 팀원과도 직접 대화할 수 있습니다.

공식 Claude Code 문서의 에이전트 팀 페이지

공식 Claude Code 문서 '에이전트 팀' 페이지 스크린샷.

Claude Code 에이전트 팀이란?

Claude Code 에이전트 팀은 여러 Claude Code 인스턴스가 한 프로젝트에서 함께 일하도록 조율하는 기능이다. Anthropic은 2026년 2월에 이 기능을 내놓았고, 2026년 11월 기준으로도 공식 문서는 이를 실험 기능이자 기본 비활성 상태로 표시합니다. 세션 하나가 리더가 되고 나머지는 팀원이 되므로, 프롬프트 1개로 계획하고 일을 나누고 보고하는 작은 팀을 움직일 수 있습니다.

이 기능으로 Claude Code 안에서 보통의 팀과 똑같이 일하는 완전한 에이전트 팀을 만들 수 있습니다.

작업 목록이 있고, 팀원에게 작업을 맡기면 그들이 알아서 처리합니다. Claude Code 인스턴스 하나가 모든 것을 떠안는 대신, 이제 한 프로젝트에 여러 전문 에이전트를 배치할 수 있습니다. 각자 역할도 기술도 다르고, 서로 방해하지 않으면서 함께 일합니다.

이건 프리랜서 한 명을 고용하는 것과 진짜 팀을 꾸리는 것의 차이입니다.

Claude 에이전트 팀을 쓰면 여러 에이전트를 동시에 실행할 수 있습니다.

에이전트 하나는 금방 벅차지지만, 여러 에이전트는 나눠서 해결하고, 리더 에이전트는 누구도 일을 중복하거나 충돌을 만들지 않도록 챙깁니다.

팀 리더는 어떻게 일하나

팀 리더는 메인 대화이며, 에이전트 팀에서 내 프롬프트를 실제 작업으로 바꾸는 부분이다. 2026년 2월의 데모에서 리더는 코드베이스를 읽고 작업 목록을 쓴 뒤 몇 분 만에 에이전트 3개를 병렬로 띄웠습니다. 공식 문서도 같은 역할을 설명합니다. 리더는 작업을 조율하고 작업을 배정하며 결과를 종합하고, 팀원은 독립적으로 일하면서 서로 직접 소통합니다.

팀 리더는 모든 에이전트 사이를 조율하는 역할을 맡습니다.

그냥 또 하나의 일꾼이 아닙니다. 조율자입니다.

프로젝트 전체를 보고, 각 팀원이 무엇을 하는지 알고, 충돌이 생기기 전에 알아채고, 우선순위가 바뀌면 작업을 다시 배정합니다.

사실상 프로젝트 매니저에게 프롬프트를 주고, 그 매니저가 실행 팀을 관리하는 셈입니다.

리더는 전체 작업 목록을 만들고 의존 관계에 따라 첫 작업을 배정합니다. 다른 모두가 그 결과물을 필요로 하니까 한 전문가가 먼저 시작합니다. 전문가가 일을 마치면 그 작업을 완료로 표시하고, 다음 개발자가 준비된 것을 보고 다음 작업을 가져갑니다. 지연도 혼란도 없고, 진행 상황을 물어볼 필요도 없습니다.

Claude Code 에이전트 팀 켜는 방법

에이전트 팀 켜기는 직접 참여해야 하는 실험 기능을 여는 1줄짜리 변경이다. 2026년 11월 기준 공식 문서는 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 설정하라고 안내하며, 셸에서 설정해도 되고 settings.json의 env 블록에 넣어도 됩니다. 설정을 마치면 팀을 띄울 준비가 끝납니다.

  1. Claude 설정 파일을 엽니다. 사용자 홈 폴더 아래 Claude 폴더에 있는 settings.json입니다.
  2. env 안에 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" 한 줄을 추가합니다. 실험 기능이고 시험해 봐도 괜찮다는 뜻입니다.
  3. Claude Code를 실행하고 원하는 팀을 평범한 말로 설명합니다.
  4. 리더가 작업 목록을 만들고 팀원을 띄우는 모습을 지켜봅니다.

설정은 정말 2분이면 끝납니다. 에이전트마다 따로 프롬프트를 줄 필요가 없습니다. 리더에게만, 회사의 팀장에게 브리핑하듯 프롬프트를 쓰면 됩니다.

Claude Code 에이전트 팀 문서 페이지

공식 Claude Code 문서의 에이전트 팀 페이지 스크린샷.

첫 에이전트 팀 프롬프트

첫 에이전트 팀 프롬프트는 목표, 역할, 완료 기준을 적은 짧은 브리핑이다. 2026년 2월의 한 데모는 기능 하나에 역할 3개를 썼습니다. PRD 에이전트, UI 디자이너, 블로그 작성자입니다. 프로젝트를 설명하고, 목표를 설명하고, 성공이 어떤 모습인지 설명한 뒤, 어떤 전문가가 필요한지 알려 줍니다.

계산기를 만들 에이전트 두 명으로 팀을 꾸려 줘.

PRD 에이전트는 사용자의 입력을 바탕으로 제품 요구 사항 문서를 만들고, UI 디자이너는 UI 목업을 만들고, 블로그 작성자가 있습니다. 그래서 새 기능을 추가할 때마다 새 블로그가 쓰입니다. 보시다시피 에이전트는 벌써 코드베이스를 파악하고 팀을 꾸리기 시작했습니다.

에이전트 세 개를 병렬로 띄우고 작업을 배정하기 시작한 것이 보입니다. 가장 좋은 점은 모든 것이 병렬로 진행된다는 것입니다. 다른 데모도 같은 방식이었습니다. 에이전트 팀을 만들어 달라고 하고, 프런트엔드 개발자, 백엔드 개발자, QA를 둡니다. 작업 의존 관계를 설정하고 담당자를 배정한 다음 에이전트들을 띄웁니다.

팀 리더가 어떻게 움직여야 하는지까지 분명하게 적는 것이 좋은 팀을 만드는 방법입니다. 예를 들어 작업 6개를 배정하고, 명확하게 전달하고, 스스로 종료하기 전에 먼저 물어보라고 적습니다. 그리고 어디서 무엇을 할지, 어떻게 되면 작업이 끝난 것인지 충분한 제약을 줍니다.

에이전트 팀과 서브에이전트의 차이

에이전트 팀과 서브에이전트는 Claude Code에서 일을 나누는 두 가지 방법이며, 차이는 누가 누구와 대화하느냐에 있다. 2026년 11월 문서에 따르면 서브에이전트는 결과를 메인 에이전트에게만 돌려주고, 팀원은 작업 목록 1개를 공유하며 일을 직접 가져가고 서로 메시지를 보냅니다. 그래서 집중된 작업에는 서브에이전트가, 논의가 필요한 작업에는 팀이 맞습니다.

서브에이전트와 에이전트 팀의 가장 중요한 차이는, 서브에이전트에서는 모든 에이전트가 일을 끝내고 메인 에이전트로 돌아오기를 기다려야 한다는 점입니다

그래서 에이전트를 관리하는 데 손이 많이 갑니다. 간단한 작업에는 잘 맞지만, 여러 일을 동시에 하려 할 때는 그렇지 않습니다. 그때는 메인 에이전트가 가운데 있는 한 여전히 내가 병목이 됩니다.

에이전트 팀에서는 메인 대화가 팀 리더가 됩니다. 작업 목록을 만들고 작업을 배정한 뒤, 팀원과 따로 대화할 수 있게 해 줍니다. 에이전트 1이 에이전트 2에게 넘기고 에이전트 2가 에이전트 3에게 넘기는 식일 필요는 없습니다. 그런 일이라면 애초에 에이전트 팀이 필요 없을지도 모릅니다. 에이전트 팀은 병렬로 협력하며 처음부터 끝까지 소통해야 합니다.

각 팀원과 대화하는 방법

팀원과 직접 대화하는 것은 긴 세션 하나 대신 에이전트 팀을 쓰는 주요 이유 중 하나이다. 2026년 2월 출시 이후 리더를 거치지 않고 어느 팀원에게나 메시지를 보낼 수 있고, 문서는 이를 위한 표시 모드 2가지를 소개합니다. 인프로세스 모드는 어떤 터미널에서도 되고, 분할 창 모드에는 tmux나 iTerm2가 필요합니다.

에이전트 팀의 장점 하나는 원하면 서브에이전트 하나에게 따로 메시지를 보낼 수 있다는 것입니다.

tmux 터미널에서 Claude Code를 실행하면, 여기 프런트엔드 개발자가 막 만들어졌고, 파란색 에이전트입니다. 여기 또 하나, 백엔드 개발자가 있고 초록색 에이전트입니다. 그리고 QA 에이전트도 나왔습니다. 노란색입니다.

각 에이전트가 무엇을 하고 있는지 아주 분명하게 보여서 정말 멋집니다.

tmux에서 실행 중인 에이전트 팀, 팀원마다 창 하나

데모 장면: 리더와 팀원 세 명이 각각 다른 tmux 창에 있습니다.

여기로 와서 프런트엔드 개발자와 대화할 수 있고, 작업을 승인하거나 정보를 더 줄 수도 있습니다. 인프로세스 보기에서는 각 에이전트에 따로 들어갈 수 있습니다. 예를 들어 블로그 작성자에게 가서 401k 기능에 대한 블로그를 두 편 더 써 달라고 하면, 그 요청은 블로그 작성자에게만 갑니다. 다른 에이전트는 모두 대기 상태입니다.

일이 끝나면 팀 리더에게 에이전트 팀을 종료해 달라고 하면 됩니다. 종료할 때 리더는 팀 전체에 일이 끝났다며 작별 인사를 합니다. 팀원 세 명이 모두 종료된 것을 확인할 수 있습니다.

좋은 에이전트 팀의 세 가지 규칙

좋은 에이전트 팀은 간단한 규칙 3가지를 지키는 팀이며, 이 규칙이 팀 규모보다 중요하다. 2026년 9월의 한 설명에서 나온 것으로, 팀원마다 다른 파일을 맡기라는 공식 조언과도 같습니다. 첫째, 각 에이전트는 자기 영역을 가집니다. 자기 파일을 갖고 자기 결과물에 집중해야 합니다.

에이전트 팀의 세 가지 규칙: 자기 영역, 직접 메시지, 병렬 시작

세 가지 규칙을 보여 주는 데모 슬라이드.

결과물을 주고받고 소통할 수는 있지만, 실제로 편집하는 것은 자기 몫뿐이어야 합니다. 둘째는 역시 직접 메시지입니다. 서로 대화할 수 있으니 메인 세션이라는 중개자를 거칠 필요가 없습니다. 셋째는 동시에 일할 수 있다는 것입니다.

Claude Code 에이전트 팀의 한계

Claude Code 에이전트 팀의 한계는 짧고 분명하며, 대부분 기능이 아직 실험 단계라는 데서 나온다. 2026년 11월 문서는 세션 재개, 작업 조율, 종료에 알려진 문제가 있다고 밝히며, 세션당 팀은 1개만 가능하고 중첩 팀은 만들 수 없습니다. 리더도 세션이 끝날 때까지 바뀌지 않습니다. 첫 대규모 실행 전에 알아 두면 헷갈려서 처음부터 다시 하는 일을 줄일 수 있습니다.

  • 세션 하나에 팀 하나만 실행할 수 있고, 팀원이 자기 팀을 만들 수는 없습니다.
  • 처음 시작한 리더가 세션이 끝날 때까지 리더로 남습니다.
  • 팀원은 리더의 권한 설정을 이어받아 시작합니다.
  • 세션을 재개해도 인프로세스 팀원이 돌아오지 않을 수 있습니다.

여러 세션을 나란히 돌리는 것 자체는 새롭지 않습니다. 한 데모는 별도의 Claude 세션 6개를 병렬로 돌려 한 회사를 위한 영업 CRM을 통째로 만들었고, 마지막에 이렇게 말했습니다.

그리고 프롬프트 하나로 전부 돌아갑니다. 프롬프트 하나에, 끝에 오류가 한두 개 있을 뿐입니다.

그것은 병렬 세션 6개였지 공식 기능은 아니었습니다. 에이전트 팀은 그 위에 리더, 공유 작업 목록, 직접 메시지를 더합니다. 좋은 활용법은 같은 에이전트 팀에서 한 기능의 프런트엔드와 백엔드를 빠르게 만드는 것입니다. 공식 문서가 꼽는 적합한 작업도 비슷합니다. 조사와 리뷰, 새 모듈이나 기능, 경쟁 가설을 활용한 디버깅, 여러 계층에 걸친 변경입니다.

Pachat에서 Claude Code 에이전트 팀과 함께 쓰기

에이전트 팀은 내 프로젝트 안에서 일하는 여러 Claude Code 세션이고, Pachat은 서로 다른 AI를 나란히 둘 수 있는 곳입니다. Pachat은 pachat.ai의 웹 제품이며, 사이트에서는 "Different personal AI agents, in one group chat."(서로 다른 개인 AI 에이전트를 하나의 그룹 채팅에)이라고 소개합니다.

  1. Claude Code 에이전트 팀이 작업을 마치고 결과를 정리하게 합니다.
  2. pachat.ai를 열고 Claude, Grok Bot, Muse, ChatGPT를 하나의 그룹 채팅에 넣습니다.
  3. 계획이나 결과에 대해 그룹에 질문합니다. 서로의 사실을 확인하고 논쟁한 뒤, 결정은 내가 내립니다.

Claude Code가 다른 에이전트와 나란히 어떻게 소개되는지는 Claude Code 에이전트 페이지, Codex와 Claude Code 사용 사례, Claude Code 첫 작업 가이드를 참고하세요.

자주 묻는 질문

Claude Code 에이전트 팀이란 무엇인가요?

여러 Claude Code 인스턴스를 한 프로젝트에서 조율하는 기능입니다. 세션 하나가 팀 리더가 되어 작업 목록을 만들고, 일을 배정하고, 결과를 합칩니다. 각 팀원은 자기 컨텍스트 창에서 일하고 다른 팀원에게 직접 메시지를 보낼 수 있습니다. 2026년 2월에 나왔고 2026년 11월에도 여전히 실험 기능이라, 직접 켜기 전까지는 꺼져 있습니다.

Claude Code에서 에이전트 팀을 어떻게 켜나요?

환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 설정합니다. 셸에서 export해도 되고 settings.json의 env 블록에 추가해도 됩니다. 그런 다음 Claude Code를 실행하고 원하는 역할로 에이전트 팀을 만들어 달라고 하면 됩니다. 2026년 11월 문서는 첫 팀을 만들기 전에 필요한 스위치가 이 설정 1개뿐이라고 설명합니다.

에이전트 팀과 서브에이전트는 무엇이 다른가요?

서브에이전트는 한 세션 안에서 실행되고 결과를 메인 에이전트에게만 돌려줍니다. 에이전트 팀의 팀원은 작업 목록을 공유하고, 일을 가져가고, 서로 직접 메시지를 보내며, 나도 어느 팀원과든 직접 대화할 수 있습니다. 2026년 문서는 결과만 중요한 집중 작업에는 서브에이전트를, 2명 이상이 논의해야 하는 복잡한 작업에는 팀을 권합니다.

리더를 거치지 않고 팀원과 대화할 수 있나요?

네. 인프로세스 표시 모드에서는 화살표 키로 팀원을 고른 뒤 바로 메시지를 입력하고, 분할 창 모드에서는 그 팀원의 창을 클릭하면 됩니다. 2026년 11월 기준 분할 창에는 tmux나 iTerm2가 필요합니다. 이렇게 보낸 메시지는 그 팀원 1명에게만 가고, 다른 팀원은 대기하거나 자기 작업을 계속합니다.

어떤 작업이 에이전트 팀에 맞나요?

동시에 진행할 수 있는 부분으로 나눌 수 있으면서도 서로 소통이 필요한 작업에 맞습니다. 2026년 문서는 대표적인 경우 4가지를 꼽습니다. 조사와 리뷰, 새 모듈이나 기능, 경쟁 가설을 활용한 디버깅, 프런트엔드·백엔드·테스트에 걸친 변경입니다. 파일 하나만 고치는 작은 작업이라면 세션 하나나 서브에이전트 하나로 충분합니다.

Pachat이 Claude Code 에이전트 팀을 실행하나요?

아니요, 역할이 다릅니다. 에이전트 팀은 내 프로젝트 안에서 돌아가는 Claude Code 세션입니다. Pachat은 Claude, Grok Bot, Muse, ChatGPT를 하나의 그룹 채팅에 넣는 웹 제품으로, 서로의 사실을 확인하고 논쟁한 뒤 결정은 내가 내립니다. 2026년에는 둘을 함께 쓸 수 있습니다. 팀이 작업을 마치게 한 다음 그 결과를 pachat.ai로 가져가 보세요.

서로 다른 AI를 하나의 그룹 채팅에 모아 볼까요? pachat.ai에서 시작하세요.

References

  • Claude Code Docs, "Orchestrate teams of Claude Code sessions," fetched 2026-11-18: https://code.claude.com/docs/en/agent-teams
  • @akshatbahety, 2026-02-21: https://x.com/akshatbahety/status/2025269286357618991
  • @catmanyau, 2026-09-16: https://x.com/catmanyau/status/2100057764995174565
  • @danhergir, 2026-02-25: https://x.com/danhergir/status/2026699963586245088
  • @SEOMastery2026, 2026-02-09: https://x.com/SEOMastery2026/status/2020907067578646964
  • @JulianGoldieSEO, 2026-02-14: https://x.com/JulianGoldieSEO/status/2022603591199133779
  • @rick_boers, 2026-02-07: https://x.com/rick_boers/status/2020154972936220735

블로그의 다른 글

모든 글 보기 →

지금 앞에 놓인 결정부터 시작해 보세요.