Claude Code agent teams vs 서브에이전트: 언제 무엇을 쓰고, 팀은 어떻게 꾸릴까

Agent teams vs 서브에이전트

둘 다 별도의 컨텍스트 창에서 병렬로 일해요. 차이는 누가 조율하느냐예요. 서브에이전트는 메인 에이전트가 모든 걸 관리하고, 팀에서는 팀원들이 공유 목록에서 작업을 가져가고 서로 대화해요.

Agent teams를 써야 할 때(와 쓰지 말아야 할 때)

• 조사와 리뷰: 팀원들이 서로 다른 각도에서 문제를 보고, 서로의 결론에 반박해요.
• 새 모듈이나 기능: 프런트엔드, 백엔드, 테스트처럼 팀원마다 별도 부분을 맡아요.
• 가설이 경쟁하는 디버깅: 여러 팀원이 각자 자기 가설을 증명하고 다른 가설을 반박하려 해요.
• 순서대로 해야 하는 일, 같은 파일을 고치는 일, 의존 관계가 많은 작업에는 맞지 않아요. 이럴 땐 세션 하나나 서브에이전트를 쓰세요.
• 일상적인 일에도 맞지 않아요. 활성 팀원이 늘 때마다 토큰 사용량도 늘어요.

Claude Code agent team 설정하는 법

1. Agent teams 켜기

   환경 변수나 settings.json의 env 블록에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 1로 설정하세요. 팀은 대화형 세션에서만 돼요. -p(와 Agent SDK)에서는 Claude가 팀원을 만들지 않아요.

   // settings.json: agent teams are experimental and off by default
   {
     "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
   }
   
   // Optional: give each teammate its own split pane (tmux or iTerm2)
   {
     "teammateMode": "auto"
   }

2. 평소 말로 팀 설명하기

   팀원이 몇 명이고 각자 무엇을 하는지 말하세요. Claude가 공유 작업 목록을 만들고, 팀원을 만들고, 끝나면 결과를 종합해요.

   Spawn three teammates to review PR #142:
   - One focused on security implications
   - One checking performance impact
   - One validating test coverage
   Have them each review and report findings.

3. 표시 모드 고르기

   기본값은 in-process 모드로, 어떤 터미널에서든 돼요. 팀원은 프롬프트 아래 패널에 표시되고, 화살표 키와 Enter로 열어 메시지를 보낼 수 있어요. 작업 목록은 Ctrl+T로 봐요. 분할 창 모드는 팀원마다 창을 따로 주며, tmux나 it2 CLI를 설치한 iTerm2가 필요해요. teammateMode를 auto나 tmux로 설정하거나 claude --teammate-mode auto로 시작하세요.

4. 이미 정의한 역할 재사용하기

   “using the security-reviewer agent type”으로 팀원을 요청하면 .claude/agents/의 서브에이전트 정의를 도구, 모델, 지시 사항까지 그대로 재사용해요.

5. 방향을 잡고, 마지막에 종료하기

   팀원들을 확인하고 방향을 바꿔 주세요. 리드가 팀원의 일을 직접 하기 시작하면 “wait for your teammates”라고 말하세요. 끝낼 때는 리드에게 팀원을 이름으로 지정해 종료하라고 하세요. 팀 디렉터리는 세션이 끝날 때 정리돼요.

출처: Claude Code 문서, Agent teams(영어)

모범 사례와 제한

• 팀원 3~5명, 한 명당 작업 5~6개 정도로 시작하세요. 집중한 세 명이 흩어진 다섯 명보다 나은 경우가 많아요.
• 팀원마다 다른 파일을 맡기세요. 두 팀원이 같은 파일을 고치면 서로 덮어써요.
• 작업 세부 사항은 팀원을 만드는 프롬프트에 넣으세요. 팀원은 CLAUDE.md, MCP 서버, skills를 불러오지만 리드의 대화는 모르기 때문이에요.
• hooks를 품질 게이트로 쓰세요. TeammateIdle, TaskCreated, TaskCompleted는 종료 코드 2로 작업을 되돌려 보낼 수 있어요.
• 제한: 세션당 팀 하나, 중첩 팀 불가, 리드 교체 불가, /resume으로 in-process 팀원이 돌아오지 않음, 작업 상태가 늦게 반영될 수 있음.
• 분할 창은 VS Code 통합 터미널, Windows Terminal, Ghostty에서 안 돼요. in-process 모드는 어디서든 돼요.
• Agent teams를 켜면 Claude가 이름으로 부른 서브에이전트가 팀원으로 실행될 수 있어요. 일반 서브에이전트로 돌아가려면 변수를 0으로 설정하세요.

Agent teams vs Claude Code를 병렬로 돌리는 다른 방법

Agent teams는 내가 지켜보는 작업 하나를 세션 하나 안에서 나눠요. 서로 독립적인 작업이라면 git worktrees에서 별도 세션을 돌리거나 백그라운드 에이전트로 돌리세요. 전체 비교는 Claude Code 에이전트 여러 개 실행을, 비용을 줄이려면 Claude Code 토큰 사용량 줄이는 법을 읽어 보세요.

세션이 끝나도 계속 일하는 팀

Agent team은 세션 하나 안에만 있고, 세션을 닫으면 멈춰요. Crewmark는 Claude Code, Codex, DeepSeek Harness, OpenCode 세션을 계속 유지되는 직무, 목표, 근무 시간을 가진 AI 직원으로 바꿔요. 직원은 하트비트로 깨어나 공유 보드에서 다음 이슈를 가져가고, 결정이 필요하면 메시지를 보내요.

1. 직원마다 직무 주기

   소프트웨어 엔지니어, 리뷰어, SEO 전문가: 팀원으로 만들던 역할을 영구히 유지해요.

2. 보드 하나에서 일하기

   이슈가 세션의 작업 목록을 대신하고, 재시작해도, 며칠이나 몇 주가 지나도 남아 있어요.

3. 하트비트로 일 시작하기

   근무 시간 동안 15분, 30분, 60분마다요. AI 직원이란을 읽어 보세요.

Claude Code agent teams FAQ