서브에이전트와 agent teams

두 가지 병렬화 모델

Claude Code에서 작업을 나누는 가장 단순한 방법은 서브에이전트다. 주 에이전트가 하위 작업을 위임하고 결과를 받아 다음 결정을 내린다. 서로 독립적인 조사, 테스트, 코드 검토처럼 결과만 모으면 되는 일에 적합하다.

agent teams는 여러 Claude Code 세션이 리드(lead)와 팀원(teammate)로 협력하는 실험 기능이다. 팀원은 공유 작업 목록을 보고 서로 메시지를 주고받을 수 있으므로, 한 사람이 만든 인터페이스를 다른 사람이 검토하는 식의 상호 의존 작업에 더 적합하다. 이 기능은 기본적으로 꺼져 있으며, 현재 설치 버전과 조직 정책에서 사용 가능 여부를 먼저 확인해야 한다.

독립적인 검사                    상호 조율이 필요한 변경
주 에이전트                         리드 세션
 ├─ 테스트 서브에이전트               ├─ 구현 팀원
 ├─ 문서 서브에이전트                 ├─ 검토 팀원
 └─ 보안 서브에이전트                 └─ 테스트 팀원
      ↓ 결과 보고                         ↕ 작업 목록·메시지
   주 에이전트가 통합                  리드가 통합·검증

선택 기준

| 상황 | 우선 선택 | 이유 | | --- | --- | --- | | 여러 파일을 독립적으로 읽고 요약 | 서브에이전트 | 통신 비용과 조율이 적다 | | 같은 설계 결정을 반복해서 맞춰야 함 | agent teams | 팀원 간 메시지와 공유 작업 목록이 있다 | | 같은 파일을 동시에 편집할 가능성이 큼 | 순차 작업 또는 파일 분할 | 병렬화보다 충돌 비용이 크다 | | 비용을 낮추고 최종 결과만 필요 | 서브에이전트 | 결과가 호출자에게 돌아오는 단순한 흐름이다 |

Agent teams는 실험적 기능이며 문서에 세션 재개, 작업 조정, 종료 처리의 제한이 명시돼 있다. 따라서 배포·마이그레이션처럼 되돌리기 어려운 작업을 팀에 완전히 맡기기보다는, 리드가 변경 범위와 검증 기준을 정하고 마지막 승인·통합을 직접 수행해야 한다.

안전한 병렬 작업 설계

병렬 실행은 시간을 자동으로 줄여 주지 않는다. 공유 파일·공유 환경·순서 의존성이 있으면 충돌과 재작업이 생긴다. 먼저 산출물 경계를 정하고, 각 팀원에게 읽기/쓰기 범위와 완료 조건을 명확하게 제공한다.

작업 A: src/auth/** 구현        → 담당자 A
작업 B: tests/auth/** 테스트    → 담당자 B
작업 C: 문서·릴리스 노트        → 담당자 C

공유 경계: 공개 API와 잠금 파일은 리드가 최종 통합

공식 문서상 팀 설정과 작업 데이터는 로컬 Claude 디렉터리에 관리되며, 사용자가 이 파일을 직접 편집하는 운영 방식은 권장되지 않는다. 팀을 종료하기 전에는 남은 작업과 변경 파일을 확인하고, 테스트·diff 검토를 별도의 완료 조건으로 둔다. 이를 통해 agent teams를 ‘자동 완성’이 아니라 통제 가능한 협업 구조로 사용할 수 있다.