Claude Code Agent Teams 사용법: 여러 AI 에이전트 협업시키기

Claude Code Agent Teams는 하나의 팀 리드와 여러 독립 Claude Code 세션이 공유 작업 목록과 메시지를 이용해 협업하는 실험 기능입니다. 아키텍처, 프론트엔드, 백엔드와 테스트처럼 경계를 나눌 수 있는 복합 작업에서 각 에이전트가 동시에 조사하고 서로 결과를 전달할 수 있습니다. 다만 에이전트 수만 늘리면 같은 파일 충돌, 중복 조사와 토큰 비용도 함께 커지므로 역할·소유 파일·완료 조건을 먼저 설계해야 합니다.

Claude Code Agent Teams란 무엇인가

Agent Teams는 여러 Claude Code 인스턴스를 하나의 협업 단위로 묶습니다. 팀을 만든 현재 세션이 lead가 되고, 별도 context window를 가진 teammate들이 작업을 맡습니다. 모든 구성원은 공유 task list를 확인할 수 있으며 teammate끼리 직접 메시지를 보낼 수 있습니다.

Anthropic 공식 문서 기준으로 이 기능은 실험 단계이며 기본값은 비활성화입니다. 세션 재개, 작업 상태 동기화와 종료 과정에 알려진 제한이 있으므로 중요한 저장소에서는 작은 읽기 전용 작업부터 시험하는 편이 안전합니다.

Agent Team의 네 가지 구성 요소

Agent Teams와 Subagent 차이

결과만 전달받으면 되는 짧은 업무라면 Claude Code Subagent 사용법이 단순합니다. 여러 담당자가 서로 발견한 내용을 검토하고 작업 의존성을 조율해야 할 때 Agent Teams를 선택하세요.

Agent Teams가 잘 맞는 작업

• 연구와 리뷰: 보안, 성능과 테스트 관점에서 같은 설계를 독립 검토
• 새 기능: 프론트엔드, API와 테스트가 분리된 모듈 개발
• 디버깅: 여러 원인 가설을 동시에 재현하고 반박
• 교차 계층 작업: UI·서버·데이터 변경을 명확한 인터페이스로 분리
• 설계 토론: 제안자, 검증자와 반대 역할이 근거를 교환

단계가 완전히 순차적이거나 모든 에이전트가 같은 파일을 자주 고쳐야 하는 작업에는 적합하지 않습니다. 이런 경우 조율 비용이 실제 구현 시간을 넘어설 수 있습니다.

사용 전 요구사항 확인하기

claude --version

공식 문서는 Agent Teams에 Claude Code 2.1.32 이상이 필요하다고 안내합니다. 기능이 보이지 않으면 먼저 버전을 확인하고 현재 설치 방식에 맞춰 공식 업데이트 절차를 사용하세요.

1단계: Agent Teams 활성화하기

사용자 또는 프로젝트의 Claude Code settings.json에 환경 변수를 추가할 수 있습니다.

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

셸 환경 변수로 현재 실행에만 적용할 수도 있습니다.

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

실험 기능을 팀 프로젝트에 공유하기 전에는 지원 버전, 비용 정책과 저장소 권한을 함께 합의하세요. 프로젝트 안에 임의로 .claude/teams/teams.json을 만들어도 공식 팀 설정으로 인식되지 않습니다.

2단계: 역할이 명확한 팀 요청하기

“에이전트 여러 개를 만들어줘”보다 목표, teammate 이름, 담당 범위, 허용 작업, 결과 형식과 종료 조건을 적어야 중복이 줄어듭니다. 예측 가능한 이름을 지정하면 이후 특정 teammate에게 직접 지시하기 쉽습니다.

좋은 역할 분담의 기준

• 각 역할이 다른 질문 또는 파일 집합을 소유합니다.
• 한 teammate가 다른 teammate의 중간 결과를 계속 기다리지 않게 합니다.
• 공유 인터페이스와 변경 금지 경계를 시작 전에 정합니다.
• 조사 결과는 파일 경로, 명령 결과와 불확실성을 포함합니다.
• 최종 결정과 충돌 해소 책임은 lead에게 둡니다.

3단계: 공유 Task List 설계하기

Agent Teams의 작업은 pending, in progress와 completed 상태로 관리됩니다. 선행 작업이 끝나야 시작할 수 있는 task에는 dependency를 둘 수 있으며, 막힌 dependency가 완료되면 다음 작업이 열립니다.

1. 먼저 독립 조사 task를 만듭니다.
2. 각 task에 산출물과 완료 기준을 적습니다.
3. 동일 파일을 수정하는 task는 동시에 열지 않습니다.
4. 통합과 최종 검증 task는 구현 task 이후에 배치합니다.
5. 실제 결과 없이 상태만 completed로 바뀌지 않았는지 lead가 확인합니다.

lead가 특정 task를 teammate에게 지정하거나, teammate가 비어 있는 unblocked task를 스스로 가져갈 수 있습니다. task claim에는 동시 할당을 막기 위한 잠금이 사용되지만 파일 수정 충돌까지 자동으로 막아주는 것은 아닙니다.

4단계: Teammate와 직접 대화하기

기본 in-process 모드에서는 Shift+Down으로 teammate를 순환해 선택하고 메시지를 보낼 수 있습니다. teammate 세션을 연 뒤 작업 방향을 바꾸거나 추가 증거를 요청할 수 있으며, 현재 작업을 중단해야 할 때는 인터페이스의 중단 조작을 사용합니다.

특정 teammate에게 직접 지시한 내용이 전체 설계에 영향을 주면 lead에게도 결정과 근거를 전달하세요. 개별 세션에만 남은 합의는 최종 종합에서 누락될 수 있습니다.

In-process와 Split panes 선택

공식 문서에는 split panes가 VS Code 통합 터미널, Windows Terminal과 Ghostty에서 지원되지 않는다는 제한이 명시돼 있습니다. 처음에는 호환성이 넓은 in-process 모드로 동작을 확인하세요.

파일 충돌을 막는 방법

Agent Teams는 teammate별 Git worktree를 자동으로 제공하는 방식이 아닙니다. 같은 작업 디렉터리에서 같은 파일을 수정하면 한 변경이 다른 변경을 덮거나 결과를 잘못 해석할 수 있습니다.

• frontend, backend, tests처럼 소유 디렉터리를 나눕니다.
• 공유 타입과 설정 파일은 한 teammate만 수정합니다.
• 인터페이스 변경은 먼저 합의하고 메시지로 전달합니다.
• 통합 전 git diff와 예상 밖 파일을 lead가 확인합니다.
• 겹치는 수정이 불가피하면 순차 작업 또는 별도 worktree를 선택합니다.

CLAUDE.md로 공통 프로젝트 규칙 제공하기

각 teammate는 일반 Claude Code 세션처럼 작업 디렉터리의 CLAUDE.md, MCP 서버와 Skills를 로드합니다. 패키지 관리자, 파일 경계, 테스트 명령과 안전 기준을 CLAUDE.md 프로젝트 규칙에 정리하면 모든 역할이 같은 기본 계약을 참고할 수 있습니다.

다만 CLAUDE.md는 기술적인 권한 차단 장치가 아닙니다. 삭제, 배포와 외부 쓰기는 permissions와 사람 승인을 함께 사용해야 합니다.

재사용할 Teammate 역할 만들기

기존 custom subagent 정의를 teammate 유형으로 재사용할 수 있습니다. 예를 들어 보안 리뷰어 정의가 있다면 “security-reviewer agent type으로 teammate를 생성해줘”라고 요청합니다. 해당 정의의 도구 allowlist와 model이 적용되고 역할 본문은 추가 지침으로 제공됩니다.

공식 문서상 subagent 정의의 skills와 mcpServers frontmatter는 teammate 실행에 그대로 적용되지 않습니다. teammate는 일반 세션처럼 프로젝트와 사용자 설정의 Skills·MCP를 로드하므로 실제 도구 목록을 확인해야 합니다.

Teammate 권한과 보안

teammate는 생성 시 lead의 permission 설정으로 시작합니다. lead를 과도하게 넓은 권한으로 실행하면 모든 teammate가 같은 위험한 출발점을 가질 수 있습니다. 공식 문서는 --dangerously-skip-permissions로 lead를 실행하면 teammate도 같은 설정을 이어받는다고 설명합니다.

• 읽기 중심 조사부터 시작합니다.
• 역할에 필요하지 않은 도구와 외부 쓰기를 제한합니다.
• 운영 환경, 배포와 데이터 변경은 사람 승인을 유지합니다.
• MCP 도구의 scope와 전송 데이터를 개별 검토합니다.
• 비밀값과 고객 데이터가 task·message·로그에 남지 않게 합니다.

Hooks로 품질 기준 적용하기

Agent Teams에는 teammate가 idle 상태로 가기 전 실행되는 TeammateIdle, task 생성 시의 TaskCreated, 완료 처리 시의 TaskCompleted Hook 이벤트가 있습니다. 공식 문서에 따르면 이 이벤트에서 종료 코드 2로 피드백을 보내 작업 생성이나 완료를 막을 수 있습니다.

예를 들어 테스트 결과와 변경 파일 목록이 없는 task 완료를 되돌리는 품질 관문을 만들 수 있습니다. Hook은 사용자 권한으로 실행될 수 있으므로 입력 검증, 제한 시간과 로그 비식별화를 적용하세요.

토큰 비용 줄이는 방법

Agent Teams는 teammate마다 독립 context window를 사용하므로 활성 인원에 따라 토큰 사용량이 크게 늘어납니다. 병렬화가 가능한 중요한 작업에서만 사용하고 단순 수정은 단일 세션이나 Subagent로 처리하세요.

• 최소 인원으로 시작하고 역할이 겹치면 줄입니다.
• 각 spawn prompt에 필요한 파일과 질문만 명시합니다.
• 동일한 대형 로그와 문서를 모든 teammate가 읽지 않게 합니다.
• 중간 보고는 전체 transcript보다 근거와 결론 중심으로 공유합니다.
• 끝난 teammate는 종료하고 팀을 정리합니다.

완료 결과를 검증하는 순서

1. lead가 모든 task의 실제 산출물과 상태를 대조합니다.
2. teammate의 결론이 충돌하면 근거를 비교하고 미확인 항목을 남깁니다.
3. 예상 밖 수정과 같은 파일의 덮어쓰기를 확인합니다.
4. lint, 타입 검사, 단위·통합 테스트를 통합 상태에서 다시 실행합니다.
5. 외부 쓰기, 마이그레이션과 배포는 사람이 diff를 검토합니다.
6. 최종 보고에 실행한 검증과 실행하지 못한 검증을 분리합니다.

Teammate 종료와 Team cleanup

작업이 끝나면 lead에게 특정 teammate의 종료를 요청합니다. teammate는 종료 요청을 승인해 정상적으로 빠지거나 진행 중인 이유를 설명하고 거부할 수 있습니다. 모든 teammate가 종료된 뒤 lead에게 다음과 같이 요청합니다.

Clean up the team

cleanup은 활성 teammate가 남아 있으면 실패할 수 있습니다. 공식 문서는 teammate가 아니라 lead를 통해 cleanup하라고 안내합니다. team 설정과 task 상태가 맞지 않는 상황을 줄이기 위해 이 순서를 지키세요.

팀 상태 파일을 직접 수정하면 안 되는 이유

Claude Code는 팀 상태를 사용자 디렉터리의 ~/.claude/teams/{team-name}/config.json, task를 ~/.claude/tasks/{team-name}/에 관리합니다. 이 파일에는 세션과 pane 같은 실행 상태가 포함되며 자동 갱신되므로 미리 만들거나 직접 편집하지 않는 것이 좋습니다.

반복 가능한 역할은 상태 파일을 복사하는 대신 custom subagent 정의로 관리하세요.

알려진 제한 사항

• in-process teammate는 /resume과 /rewind로 복원되지 않을 수 있습니다.
• task 완료 상태가 늦게 반영돼 dependency가 막힐 수 있습니다.
• 진행 중인 요청이나 도구 호출 때문에 종료가 늦어질 수 있습니다.
• 한 lead 세션은 동시에 하나의 team만 관리합니다.
• teammate는 중첩 team이나 추가 teammate를 만들 수 없습니다.
• 생성한 세션의 lead를 다른 teammate로 바꿀 수 없습니다.
• split panes는 지원 터미널과 tmux·iTerm2 조건이 있습니다.

Agent Team이 멈춘 것처럼 보일 때

1. 공유 task list에서 pending dependency를 확인합니다.
2. 담당 teammate에게 실제 작업 완료 여부를 묻습니다.
3. 작업은 끝났지만 상태만 남았다면 lead에게 상태 확인을 요청합니다.
4. lead가 너무 일찍 종료하려 하면 모든 teammate 결과를 기다리라고 지시합니다.
5. 재개 후 teammate가 사라졌다면 새 teammate로 남은 task를 인계합니다.

실전 팀 구성 예시

도입 전 체크리스트

• 현재 Claude Code 버전이 요구사항을 충족하는가
• 작업이 실제로 독립된 역할로 나뉘는가
• 각 teammate의 파일 소유권과 금지 범위가 명확한가
• 공유 task의 완료 기준과 dependency가 정의됐는가
• lead의 permission이 최소 범위인가
• 토큰 예산과 중단 조건을 정했는가
• 종료, cleanup과 통합 검증 책임자를 정했는가

Agent Team 실행 기록표

병렬 작업의 효과는 teammate 수가 아니라 충돌 없이 완료한 작업으로 평가해야 합니다. 단일 세션 기준값과 함께 기록하세요.

편집부 결론

Claude Code Agent Teams의 장점은 단순히 AI 에이전트를 여러 개 실행하는 것이 아니라 독립 context, 공유 task와 직접 메시지를 이용해 복합 작업을 조율하는 데 있습니다. 서로 다른 파일이나 가설을 맡길 수 있을 때 작은 팀으로 시작하고, lead에게 통합과 검증 책임을 명확히 주세요. 같은 파일을 함께 수정하거나 순차 의존성이 강한 작업이라면 Subagent 또는 단일 세션이 더 안정적일 수 있습니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 실제 조직 저장소에서 Agent Teams의 생산성이나 비용을 장기간 측정한 후기는 아닙니다. 실험 기능의 동작과 제한은 바뀔 수 있으므로 활성화 전 현재 버전과 공식 문서를 확인하세요.

공식 문서와 함께 읽을 글

Claude Code Agent Teams 공식 문서 보기

Claude Code 병렬 에이전트 방식 비교하기

Agent Teams 토큰 비용 확인하기

Claude Code Subagent와 선택 기준 비교하기

모든 teammate에 CLAUDE.md 규칙 적용하기

Teammate와 Task 품질 관문을 Hook으로 만들기

Codex 병렬 에이전트 방식과 비교하기

Codex와 Claude Code 개발 에이전트 전체 비교하기

자주 묻는 질문

Claude Code Agent Teams는 기본으로 활성화돼 있나요?

아닙니다. 실험 기능이며 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 settings.json 또는 환경 변수에 설정해야 합니다.

Agent Teams에 필요한 Claude Code 버전은 무엇인가요?

Anthropic 공식 문서 기준 Claude Code 2.1.32 이상이 필요합니다. claude --version으로 현재 버전을 확인하세요.

Agent Teams와 Subagent 중 무엇을 써야 하나요?

짧은 작업 결과만 주 에이전트에 돌려받으려면 Subagent, 여러 독립 세션이 공유 task와 직접 메시지로 지속 협업해야 한다면 Agent Teams가 적합합니다.

Agent Team의 에이전트들이 같은 파일을 동시에 수정해도 되나요?

피하는 것이 좋습니다. Agent Teams는 teammate별 worktree를 자동 격리하지 않으므로 파일 또는 디렉터리 소유권을 분리해야 합니다.

Teammate에게 직접 메시지를 보낼 수 있나요?

가능합니다. in-process 모드에서는 Shift+Down으로 teammate를 선택해 메시지를 보내고 split panes에서는 해당 pane에서 직접 대화할 수 있습니다.

Agent Teams는 토큰을 더 많이 사용하나요?

그렇습니다. teammate마다 독립 context window를 사용하므로 활성 인원과 작업량에 따라 비용이 증가합니다. 병렬화 가치가 큰 작업에 제한해서 사용하세요.

작업 후 Agent Team은 어떻게 종료하나요?

lead를 통해 teammate를 먼저 정상 종료한 뒤 lead에게 Clean up the team을 요청합니다. 활성 teammate가 남아 있으면 cleanup이 실패할 수 있습니다.

Agent Teams를 재개하면 teammate도 복원되나요?

in-process teammate는 /resume이나 /rewind로 복원되지 않을 수 있습니다. 재개 후 사라진 teammate가 있다면 새 teammate를 만들어 남은 작업을 인계해야 합니다.