양파개발자 실바의 블로그

Claude Code 에이전트 팀 입문: 여러 AI가 한 팀으로 일하게 만들기

dev ai

1. 에이전트 팀이란 무엇인가

Claude Code의 에이전트 팀(Agent Teams) 은 여러 개의 Claude Code 세션을 하나의 팀처럼 묶어 협업시키는 기능입니다.

혼자 일하는 AI와 팀으로 일하는 AI의 차이는, 1인 다재다능 프리랜서에게 일을 맡기는 것과 분야별 전문가로 구성된 전담 TF팀을 꾸리는 것의 차이와 같습니다.

[ 단일 세션 ]
사용자 ──> Claude (혼자 순차적으로 조사 -> 개발 -> 검증)

[ 에이전트 팀 ]
                 ┌──> 팀원 A (보안 관점)  ─┐
사용자 ──> 팀 리드 ┼──> 팀원 B (성능 관점)  ─┼─> 서로 메시지로 반박·합의
                 └──> 팀원 C (테스트 관점) ─┘
                        ↑ 공유 태스크 리스트에서 각자 일을 집어감

팀은 네 가지 요소로 구성됩니다.

구성 요소 역할
팀 리드(Team Lead) 내가 대화하는 메인 세션. 팀원을 만들고 일을 나누고 결과를 종합
팀원(Teammates) 각자 독립된 Claude Code 인스턴스. 자기만의 컨텍스트 창을 가짐
태스크 리스트(Task List) 팀 전체가 공유하는 할 일 목록. 팀원이 직접 집어가서 처리
메일박스(Mailbox) 에이전트 간 메시지 전달 시스템

핵심 이점은 세 가지입니다.

  • 병렬 처리: 순차로 하던 일을 여러 팀원이 동시에 진행합니다.
  • 컨텍스트 과부하 방지: 팀원마다 컨텍스트 창이 따로 있어, 대규모 작업에서도 정밀도가 떨어지지 않습니다.
  • 상호 검증: 한 팀원의 가설을 다른 팀원이 반박합니다. 혼자 조사할 때 생기는 “먼저 찾은 그럴듯한 답에 안착해버리는” 편향(anchoring)을 깨뜨립니다.

주의: 에이전트 팀은 아직 실험적(experimental) 기능이며 기본적으로 꺼져 있습니다. 세션 재개(/resume) 미지원 등 알려진 제약이 있습니다(7장 참고).

2. 서브에이전트와 무엇이 다른가

Claude Code에는 이미 서브에이전트(Subagents) 라는 병렬화 수단이 있습니다. 둘의 결정적 차이는 일꾼들끼리 직접 대화할 수 있는지입니다.

  서브에이전트 에이전트 팀
컨텍스트 독립 컨텍스트, 결과만 호출자에게 반환 독립 컨텍스트, 완전히 별개 세션
통신 메인 에이전트에게만 보고 팀원끼리 이름으로 직접 메시지
조율 메인 에이전트가 전부 관리 공유 태스크 리스트로 자율 조율
내가 개입 메인 에이전트를 통해서만 특정 팀원에게 직접 지시 가능
토큰 비용 낮음(결과가 요약되어 돌아옴) 높음(팀원 각각이 별도 Claude)

판단 기준은 간단합니다.

  • 결과만 필요하면 서브에이전트: “이 라이브러리 사용처 전부 찾아와” 같은 조사·검증 작업.
  • 논의가 필요하면 에이전트 팀: 서로 발견을 공유하고 반박하며 합의를 만들어야 하는 작업.

반대로 순차적인 작업, 같은 파일을 계속 고치는 작업, 의존 관계가 촘촘한 작업은 단일 세션이나 서브에이전트가 더 낫습니다. 팀은 조율 비용이 있고, 팀원이 서로 독립적으로 움직일 수 있을 때만 이득입니다.

3. 시작하기

3-1. 기능 활성화

기본값이 꺼져 있으므로 환경변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정해야 합니다. settings.json에 넣는 방식을 권장합니다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

이 변수가 없으면 팀 관련 디렉터리도 만들어지지 않고, Claude가 팀원을 만들거나 제안하지도 않습니다.

과거에는 “팀을 먼저 만들고 이름을 지어라”는 절차가 있었지만, v2.1.178부터는 팀원을 하나 띄우는 순간 팀이 자동 구성되고 세션 종료 시 자동 정리됩니다. TeamCreate / TeamDelete 도구는 더 이상 존재하지 않습니다.

3-2. 첫 팀 띄워보기

별도 명령어가 없습니다. 자연어로 “팀원 몇 명을 만들어서 이렇게 나눠 하라”고 말하면 됩니다.

TODO 주석을 코드베이스 전체에서 추적하는 CLI 도구를 설계하려고 합니다.
팀원 3명을 만들어서 각각 다른 관점으로 탐색해 주세요.
한 명은 UX, 한 명은 기술 아키텍처, 한 명은 반대 입장(devil's advocate).

이 프롬프트가 잘 작동하는 이유는 세 역할이 서로를 기다릴 필요가 없기 때문입니다. 팀원 간 의존이 없을 때 병렬화 효과가 가장 큽니다.

한 가지 함정: Claude가 팀 대신 서브에이전트를 띄울 수도 있습니다. 둘 다 같은 에이전트 패널에 표시되므로 화면만 봐서는 구분이 안 됩니다. 팀이 필요하면 “에이전트 팀으로 해달라”고 명시하세요.

3-3. 화면 모드 두 가지

  • in-process (기본값): 모든 팀원이 내 터미널 하나에서 돌아갑니다. 프롬프트 입력창 아래 에이전트 패널에 팀원 목록이 뜹니다. 추가 설치가 필요 없어 입문자에게 적합합니다.
  • split panes: 팀원마다 별도 창(pane)을 가집니다. 모두의 출력을 동시에 볼 수 있지만 tmux 또는 iTerm2(it2 CLI) 가 필요하고, VS Code 내장 터미널·Windows Terminal·Ghostty에서는 지원되지 않습니다.
{
  "teammateMode": "auto"
}

auto는 tmux/iTerm2 환경이면 분할 창을, 아니면 in-process를 씁니다. 한 세션만 바꾸려면 claude --teammate-mode auto 로 실행합니다.

4. 팀을 다루는 법

4-1. 팀원 수와 모델 지정

팀원 수는 Claude가 알아서 정하지만, 직접 지정할 수도 있습니다.

팀원 4명을 만들어 이 모듈들을 병렬로 리팩토링해 주세요. 각 팀원은 Sonnet을 쓰세요.

팀원은 리드의 /model 설정을 자동으로 물려받지 않습니다. 프롬프트에 모델을 지정하지 않았을 때의 기본값은 /config의 Default teammate model 에서 바꿉니다(리드와 같게 하려면 Default (leader’s model) 선택).

비용 관점의 기본 전략은 이렇습니다.

  • 팀 리드(설계·조율): 최고 성능 모델 (Opus)
  • 팀원(구현·조사): 가성비·속도 모델 (Sonnet, Haiku)

팀원의 모델과 fast mode는 생성 시점에 고정되므로, 팀원 화면에서 /model을 입력해도 리드 설정만 바뀝니다.

4-2. 특정 팀원에게 직접 말 걸기

팀원은 각자 온전한 Claude Code 세션이므로, 리드를 거치지 않고 직접 지시할 수 있습니다. in-process 모드 기준 조작법입니다.

키 동작
↑ ↓ 에이전트 패널에서 팀원 선택
Enter 선택한 팀원의 대화창 열기 (이후 입력은 그 팀원에게 전달)
Esc 선택한 팀원의 현재 턴 중단
x 선택한 팀원 정지
Ctrl+T 태스크 리스트 토글

팀원 화면을 보고 있어도 내장 슬래시 명령은 리드 세션에서 실행됩니다. 일반 텍스트와 스킬만 그 팀원에게 갑니다.

4-3. 태스크 배분

태스크는 대기 / 진행중 / 완료 세 상태를 가지며, 태스크 간 의존 관계를 걸 수 있습니다. 선행 태스크가 끝나지 않으면 후속 태스크는 집어갈 수 없고, 선행이 완료되면 자동으로 잠금이 풀립니다.

배분 방식은 두 가지입니다.

  • 리드가 지정: “이 태스크는 A에게 줘”
  • 팀원이 자율 클레임: 하나 끝내면 남은 태스크를 스스로 집어감 (파일 락으로 중복 방지)

4-4. 위험한 작업엔 플랜 승인 요구

팀원이 곧바로 코드를 고치는 게 불안하면, 읽기 전용 플랜 모드를 강제할 수 있습니다.

인증 모듈을 리팩토링할 아키텍트 팀원을 만들어 주세요.
코드를 수정하기 전에 반드시 플랜 승인을 받도록 하세요.
테스트 커버리지가 포함되지 않은 계획은 승인하지 마세요.

팀원이 계획을 제출하면 리드가 승인 또는 피드백과 함께 반려합니다. 반려되면 팀원은 플랜 모드에 머물며 수정 후 재제출합니다. 승인 판단은 리드가 자율적으로 하므로, 위 예시처럼 승인 기준을 프롬프트에 못 박아 두는 것이 중요합니다.

4-5. 팀원 종료

이름을 불러 종료를 요청합니다.

researcher 팀원에게 종료를 요청해 주세요

팀원은 승인하고 정상 종료하거나, 이유를 대며 거부할 수 있습니다. 팀 공유 디렉터리는 세션 종료 시 자동 정리되므로 별도 청소 작업은 없습니다.

5. 초보자용 실전 시나리오 2개

처음이라면 코드를 쓰지 않는 작업부터 시작하는 것이 좋습니다. 병렬 탐색의 이점은 그대로 누리면서, 병렬 구현에서 생기는 파일 충돌 문제를 피할 수 있습니다.

5-1. 병렬 코드리뷰

리뷰어 한 명은 한 번에 한 종류의 문제에만 집중하는 경향이 있습니다. 관점을 나눠주면 보안·성능·테스트가 동시에 검토됩니다.

PR #142를 리뷰할 팀원 3명을 만들어 주세요.
- 1명: 보안 관점 (인증/세션, 입력값 검증)
- 1명: 성능 관점 (쿼리, 메모리, N+1)
- 1명: 테스트 커버리지 관점
각자 리뷰한 뒤 발견 사항을 보고하게 하고, 마지막에 종합해 주세요.

포인트: 세 팀원에게 서로 다른 렌즈를 명시적으로 배정해 관점이 겹치지 않게 합니다. 모두 읽기 전용 작업이라 충돌 위험도 없습니다.

5-2. 가설 경쟁형 버그 추적

원인이 불분명할 때 단일 에이전트는 그럴듯한 설명 하나를 찾고 탐색을 멈춥니다. 팀원들에게 서로의 이론을 반박하라고 지시하면 이 문제가 해결됩니다.

사용자들이 "메시지 한 번 보내면 앱이 종료된다"고 신고했습니다.
팀원 5명을 만들어 각각 다른 가설을 조사하게 해 주세요.
서로 메시지를 주고받으며 상대 이론을 반박하도록, 과학적 토론처럼 진행하세요.
합의된 결론을 findings.md에 정리해 주세요.

포인트: 순차 조사는 먼저 살펴본 이론에 편향됩니다. 서로를 반박하는 조사자가 여럿일 때, 살아남은 이론이 실제 근본 원인일 확률이 훨씬 높아집니다.

5-3. 병렬 구현으로 넘어갈 때

리서치·리뷰가 익숙해진 뒤 구현에 쓸 때는 파일 소유권을 프롬프트에 명시합니다.

당신은 Auth 모듈 전담 팀원입니다.

- 작업 범위: `src/modules/auth/` 내부 파일만 수정 가능
- 제약: `src/modules/user/`, `src/common/` 은 읽기 전용. 공통 모듈 수정이 필요하면
  직접 고치지 말고 리드에게 요청하세요.
- 완료 조건: 작업 후 `npm run test:auth` 를 실행하고, 100% 통과했을 때만 완료 보고

팀원 생성 프롬프트에는 다음 요소가 담겨야 합니다.

요소 설명
역할(Role) 정체성과 임무를 한 문장으로
작업 범위(Scope) 가장 중요 — 수정 가능한 디렉터리를 엄격히 격리
권한(Permissions) 읽기 전용인지, 어떤 파일까지 수정 가능한지
모델(Model) 지정하지 않으면 리드 모델을 물려받지 않음
완료 조건(Verification) “npm test 통과 시 보고” 같은 검증 가능한 종료 기준

6. 잘 쓰기 위한 원칙 6가지

핵심 원칙: 팀원이 많다고 좋은 게 아닙니다. 명확한 역할 분담과 검증 수단이 승패를 좌우합니다.

6-1. 리서치·리뷰부터 시작한다

경계가 명확하고 코드를 쓰지 않는 작업(PR 리뷰, 라이브러리 조사, 버그 원인 추적)이 첫 연습으로 최적입니다.

6-2. 파일 소유권을 겹치지 않게 나눈다

두 팀원이 같은 파일을 고치면 서로의 변경을 덮어씁니다.

  • Bad: “A, B 둘 다 로그인 화면과 DB를 같이 고쳐봐”
  • Good: “A는 auth.ts만, B는 user.service.ts만 전담. 연동 인터페이스 규격은 먼저 합의”

6-3. 3~5명으로 시작한다

공식 권장은 3~5명, 팀원당 태스크 5~6개입니다. 독립 태스크가 15개라면 팀원 3명이 적절합니다. 팀원이 늘면 토큰이 선형으로 늘고 조율 비용도 커집니다. 집중된 3명이 산만한 5명보다 낫습니다.

태스크 크기도 중요합니다. 너무 작으면 조율 비용이 이득을 넘고, 너무 크면 중간 점검 없이 오래 헤매게 됩니다. 함수 하나, 테스트 파일 하나, 리뷰 하나처럼 명확한 산출물이 나오는 단위가 적당합니다.

6-4. 스폰 프롬프트에 컨텍스트를 충분히 담는다

팀원은 CLAUDE.md, MCP 서버, 스킬은 자동으로 읽지만 리드의 대화 이력은 물려받지 않습니다. 리드와 한참 논의한 내용은 팀원에게 전달되지 않으므로, 생성 프롬프트에 필요한 배경을 직접 써야 합니다.

보안 리뷰 팀원을 만들고 다음 프롬프트를 주세요:
"`src/auth/` 인증 모듈의 보안 취약점을 검토하세요. 토큰 처리, 세션 관리,
입력값 검증에 집중하세요. 이 앱은 httpOnly 쿠키에 JWT를 저장합니다.
발견한 문제는 심각도 등급과 함께 보고하세요."

단, 필요한 최소한만 넣습니다. 리드의 긴 대화 내역을 통째로 넘기면 토큰만 낭비되고 정밀도가 떨어집니다.

6-5. 공통 규칙은 CLAUDE.md에, 검증 수단은 미리 준비한다

모든 팀원이 프로젝트 루트의 CLAUDE.md를 읽으므로, 팀 공통 규칙을 여기에 두면 됩니다. 컨텍스트 낭비를 막기 위해 핵심만 간결하게 적습니다.

  • 넣을 것: 실행/빌드/테스트 명령어, 코딩 스타일·브랜치 규칙, 절대 수정 금지 파일 목록
  • 뺄 것: 장황한 코드 구조 설명, 외부 API 문서 링크

그리고 팀원이 스스로 작업 완료를 확인할 수단(단위 테스트, 빌드, lint)이 반드시 준비돼 있어야 합니다. 검증 수단이 없으면 AI는 문법만 멀쩡해도 “완료했다”고 착각합니다.

품질 기준을 강제하려면 훅(Hooks) 을 쓸 수 있습니다.

훅 시점 종료코드 2의 효과
TeammateIdle 팀원이 유휴 상태로 전환하려 할 때 피드백을 주고 계속 일하게 함
TaskCreated 태스크가 생성될 때 생성 차단 + 피드백
TaskCompleted 태스크가 완료 처리될 때 완료 차단 + 피드백

6-6. 최종 승인은 사람이 한다 (Human-in-the-loop)

팀이 기획·개발·테스트를 다 끝냈더라도 Git commit, PR 병합, 실행 판단은 사람이 diff와 테스트 결과를 직접 확인해야 합니다. 결과물이 자동 반영되기 전에 검수 버퍼를 두세요.

추가로, 팀을 오래 방치하지 말고 중간중간 확인하며 방향을 잡아주는 것이 낭비를 줄입니다. 리드가 팀원을 기다리지 않고 혼자 일하기 시작하면 이렇게 말하면 됩니다.

팀원들이 태스크를 마칠 때까지 기다린 뒤 진행하세요

7. 비용과 한계

7-1. 토큰 비용

에이전트 팀은 단일 세션보다 토큰을 훨씬 많이 씁니다. 팀원마다 독립된 컨텍스트 창을 가지므로 사용량이 팀원 수에 비례해 늘어납니다. 리서치·리뷰·신규 기능 개발에서는 그만한 값을 하지만, 일상적인 작업은 단일 세션이 훨씬 경제적입니다.

7-2. 알려진 제약

실험적 기능이므로 다음 제약을 알고 써야 합니다.

  • 세션 재개 미지원: /resume, /rewind 로는 in-process 팀원이 복원되지 않습니다. 재개 후 리드가 존재하지 않는 팀원에게 메시지를 보내려 할 수 있습니다. 이때는 새 팀원을 만들라고 지시하세요.
  • 태스크 상태 지연: 팀원이 완료 처리를 깜빡해 후속 태스크가 막힐 수 있습니다. 수동으로 상태를 고치거나 리드에게 확인시키세요.
  • 종료가 느릴 수 있음: 팀원은 현재 요청/도구 호출을 끝낸 뒤 종료합니다.
  • 세션당 팀 하나: 여러 팀을 만들거나 세션 간에 팀을 공유할 수 없습니다.
  • 중첩 팀 불가: 팀원은 자기 팀원을 만들 수 없습니다. 팀 관리는 리드만 합니다.
  • 리드 고정: 메인 세션이 끝까지 리드입니다. 리드 교체·승격은 불가합니다.
  • 권한은 리드 기준: 모든 팀원이 리드의 권한 모드로 시작합니다. 리드가 --dangerously-skip-permissions로 실행 중이면 팀원도 전부 그렇습니다. 생성 시점에 팀원별 권한을 따로 줄 수는 없습니다(생성 후 개별 변경은 가능).

보안상 유용한 사실도 하나 있습니다. 팀원끼리 SendMessage로 주고받은 메시지는 “사용자가 아닌 다른 Claude 세션에서 왔다”고 명시되어 전달됩니다. 따라서 어떤 팀원이 거부된 작업을 다른 팀원에게 대신 시켜 우회하는 일은 막혀 있습니다.

8. 자주 겪는 문제

증상 원인과 대응
팀원이 안 보인다 유휴 상태 팀원 행은 30초 후 숨겨집니다(정지된 게 아님). 이름을 불러 메시지를 보내면 다시 나타납니다. 4명 이상 유휴 시 N idle agents 한 줄로 접히며, Enter로 펼칩니다
팀 대신 서브에이전트가 떴다 둘 다 같은 패널에 표시됩니다. “에이전트 팀으로 해달라”고 명시해 다시 요청하세요
권한 프롬프트가 쏟아진다 팀원의 권한 요청이 모두 리드로 올라옵니다. 팀을 띄우기 전에 자주 쓰는 명령을 권한 설정에서 미리 허용해 두세요
팀원이 에러 후 멈췄다 패널에서 선택 → Enter로 출력을 확인한 뒤, 추가 지시를 주거나 대체 팀원을 새로 만드세요
리드가 일이 끝나기 전에 종료한다 “계속 진행하라”고 지시하세요. 리드가 위임 대신 직접 일하는 경우도 같은 방식으로 교정합니다
tmux 세션이 남아있다 tmux ls 로 확인 후 tmux kill-session -t <이름>

핵심요약

  • 에이전트 팀은 여러 Claude Code 세션을 팀 리드 + 팀원으로 묶어 병렬 협업시키는 실험적 기능. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 로 활성화한다.
  • 서브에이전트와의 차이는 팀원끼리 직접 메시지를 주고받고 공유 태스크 리스트로 자율 조율한다는 점. 논의·반박이 필요하면 팀, 결과만 필요하면 서브에이전트.
  • 첫 시도는 PR 리뷰·버그 원인 추적 같은 읽기 전용 작업으로. 관점을 나눠 배정하고 서로 반박하게 하는 것이 최대 무기.
  • 3~5명, 팀원당 태스크 5~6개, 파일 소유권 분리가 실패를 막는 기본기. 팀원은 리드 대화 이력을 물려받지 않으니 스폰 프롬프트에 배경을 담는다.
  • 토큰은 팀원 수만큼 선형 증가하고 /resume 미지원 등 제약이 있다. 커밋·PR 최종 승인은 사람이 한다.