결제 오류 하나를 조사하려면 화면, 서버 처리와 테스트를 함께 봐야 할 때가 있습니다. 이 글의 개발팀은 작업 분할을 설명하기 위한 사례입니다. 여러 Claude Code 인스턴스를 Agent Teams로 묶을 수 있지만, 같은 파일을 함께 고치게 두면 조사보다 충돌 정리에 더 많은 시간이 들 수 있습니다.

핵심 Agent Teams는 서로 직접 대화하고 공유 작업 목록으로 조율해야 하는 독립 작업에 맞습니다. 결과만 받아도 되는 좁은 일에는 서브에이전트가 더 단순합니다. 어느 방식을 쓰든 파일 소유권, 중단 조건과 최종 통합 책임자를 사람이 먼저 정해야 합니다.

실험 기능은 어디에서 켜는가

Agent Teams는 현재 실험 기능입니다. 개인 셸에서 시험할 때는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 환경 변수를 쓰고, 프로젝트에서 반복해 쓸 때는 `.claude/settings.json`의 `env`에 같은 값을 둡니다. 팀 저장소에 넣기 전에는 참여자 모두가 비용과 제한을 이해했는지 확인합니다.

한 번의 조사에만 필요하다면 셸 환경 변수로 시험한 뒤 세션을 닫는 편이 낫습니다. 프로젝트 설정에 남기면 이후 세션도 기능을 사용할 수 있으므로 도입 결정처럼 다뤄야 합니다.

한 셸에서만 Agent Teams를 켜는 예시
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\nclaude

실험 기능을 기본값처럼 켜 두지 않습니다

Agent Teams는 실험 기능이며 기본으로 비활성화되어 있습니다. 사용하려면 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`을 설정이나 환경 변수에 넣어야 합니다. 세션 재개, 작업 조율과 종료 동작에는 알려진 제한이 있습니다.

팀을 켜면 Claude가 이름을 붙인 일반 서브에이전트도 `teammate`로 실행될 수 있습니다. 팀을 요청하지 않았는데도 팀이 생길 수 있다는 뜻입니다. 서브에이전트만 쓰고 싶다면 이 실험 기능을 끕니다.

처음 적용할 때는 운영 변경보다 읽기 전용 조사나 코드 리뷰처럼 실패 영향이 작은 일부터 시작합니다.

사용자 또는 시험 프로젝트에서 Agent Teams를 켜는 설정
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

팀원은 직접 대화하고 공유 작업 목록을 봅니다

각 팀원은 독립된 컨텍스트 창에서 작업합니다. 팀원은 리드에게만 결과를 보내지 않고 다른 팀원에게 직접 메시지를 보낼 수 있습니다. 팀 리드는 작업을 나누고 결과를 모으는 메인 세션입니다.

공유 작업 목록에는 대기, 진행 중, 완료 상태와 작업 간 의존성을 둘 수 있습니다. 한 팀원이 API 응답 형식을 확인하면 그 결과를 기다리던 화면 작업이 다음 단계로 넘어갈 수 있습니다.

이 구조는 서로의 발견이 계속 필요한 문제에 유용합니다. 다만 공유 목록은 대화와 상태를 정리할 뿐, 같은 파일을 두 사람이 고치지 않게 보장하지는 않습니다.

역할보다 파일 경계로 일을 나눕니다

두 팀원이 같은 파일을 편집하면 결과가 덮어써질 수 있습니다. 프런트엔드 담당, 백엔드 담당처럼 역할만 적지 말고 각자 수정할 경로와 손대지 않을 공통 파일을 정해야 합니다.

공통 API 계약이나 잠금 파일은 여러 팀원의 소유로 두지 않습니다. 팀 리드가 먼저 결정하거나, 앞선 조사가 끝난 뒤 한 명이 맡는 선행·후행 작업으로 분리합니다.

파일 소유권과 선행 조건을 적은 작업 계약
작업 A: 웹 화면 조사와 수정
- 소유: apps/web/checkout/**
- 금지: services/payment/**, packages/contracts/**

작업 B: 서버 검증과 수정
- 소유: services/payment/**
- 금지: apps/web/**, packages/contracts/**

작업 C: 공통 계약 검토
- 소유: packages/contracts/payment.ts
- 선행 조건: A와 B의 조사 결과 확인
- 담당: 팀 리드 또는 지정한 한 명

결과만 필요하면 서브에이전트가 낫습니다

서브에이전트도 별도 컨텍스트에서 작업하지만, 호출한 쪽에 결과를 돌려주는 일에 맞습니다. 작은 조사, 한 파일의 리뷰, 테스트 실패 원인 찾기처럼 중간 토론이 필요하지 않은 작업에 적합합니다.

Agent Teams는 팀원끼리 발견을 공유하고 서로의 가설을 따져야 할 때 씁니다. 여러 원인을 동시에 시험하는 오류 조사나 서로 다른 계층의 독립 파일을 맡는 기능 작업이 여기에 가깝습니다.

순서대로 해야 하는 일, 같은 파일 편집, 의존성이 많은 일에는 팀을 쓰지 않습니다. 한 세션에서 처리하거나 조사만 서브에이전트에 맡깁니다.

팀원이 늘면 토큰과 조율 비용도 커집니다

각 팀원은 자기 컨텍스트 창을 사용합니다. 공식 문서는 Agent Teams가 단일 세션보다 훨씬 많은 토큰을 쓴다고 설명합니다. 팀을 쓰는 이유는 사람 수를 늘리기 위해서가 아니라 동시에 살펴볼 가치가 있는 독립 문제가 있기 때문입니다.

오류 메시지 한 줄의 뜻을 확인하는 일에는 팀이 필요하지 않습니다. 웹 화면, 서버 처리와 테스트 재현이 서로 다른 파일에 있고 각 결과를 대조해야 한다면 팀이 시간을 줄일 수 있습니다.

시작 전에 팀원별 산출물, 결론 형식과 다음 작업에 전달할 정보를 적습니다. 이 셋이 분명하지 않으면 먼저 한 세션에서 문제를 좁힙니다.

직접 통신도 권한 승인을 대신하지 않습니다

팀원에게 직접 추가 지시를 보내거나 다른 팀원의 조사 결과를 확인할 수 있습니다. 여러 가설을 나눠 시험한 뒤 서로 반박하게 할 때 이 장점이 큽니다.

잘못된 가설을 여러 팀원이 이어서 확장할 수도 있습니다. 팀 리드나 사람은 진행 상황을 읽고 범위를 벗어난 접근을 멈춰야 합니다.

운영 자격 증명이 있어야 재현할 수 있다는 보고가 나오면 팀도 멈춥니다. 팀원끼리 주고받은 메시지는 운영 접근이나 배포 승인이 아닙니다.

상태 표시보다 실제 산출물을 확인합니다

Agent Teams에는 작업 상태가 제때 바뀌지 않거나, 재개한 세션에서 진행 중이던 팀원이 복원되지 않는 제한이 있습니다. 완료·대기 표시는 작업 결과를 직접 확인하기 위한 단서일 뿐입니다.

작업이 멈춘 것처럼 보이면 변경 파일, 테스트 결과와 남은 질문을 먼저 확인합니다. 그 뒤 상태를 정정하거나 다른 팀원에게 인계합니다. 팀 리드의 종료 판단도 같은 방식으로 검토합니다.

중단 조건과 통합 책임자를 계약에 넣습니다

두 팀원이 같은 파일을 고치려 하거나 공통 API 결정이 끝나지 않았으면 병렬 작업을 멈춥니다. 운영 데이터·비밀·배포 권한이 필요해진 경우, 한 작업의 실패가 다른 팀원의 입력을 바꾼 경우도 다시 분할해야 합니다.

최종 통합은 한 책임자가 맡습니다. 팀원별 테스트가 통과해도 전체 기능이 맞는지는 별개입니다. 통합 담당자는 변경 파일, 공통 계약과 전체 테스트를 확인하고, 커밋·푸시·배포 전에는 사람이 영향 범위를 검토합니다.

읽고 나서 확인하기

답을 떠올린 뒤 본문의 판단 기준과 비교해 보세요.

  • 결과만 돌려받는 짧은 조사는 서브에이전트, 독립 브랜치 구현은 `worktree`가 먼저입니다.
  • 팀원끼리 발견을 주고받아야 하고 파일 소유권도 나눌 수 있을 때 Agent Teams를 검토합니다.
  • 같은 파일을 둘이 고치거나 공통 계약이 미정이면 병렬 작업을 시작하지 않습니다.

공식 출처