Claude Code: Sub-agent vs Agent Teams 비교

#들어가며

Claude Code에는 작업을 병렬로 처리하는 두 가지 메커니즘이 있다. Sub-agent(서브에이전트)와 Agent Teams(에이전트 팀). 둘 다 여러 AI 인스턴스를 활용하지만, 설계 철학과 사용 시나리오가 다르다. 이 글에서는 공식 문서를 기반으로 둘의 차이를 정리한다.

#한 줄 요약

• Sub-agent: 메인 세션 안에서 도우미를 파견하고, 결과만 받아오는 구조
• Agent Teams: 독립적인 Claude Code 인스턴스 여러 개가 공유 작업 목록과 메시징으로 협업하는 구조

#Sub-agent란?

Sub-agent는 메인 대화 안에서 특정 작업을 위임하는 보조 에이전트다. 각 서브에이전트는 자체 컨텍스트 윈도우, 커스텀 시스템 프롬프트, 독립적인 도구 접근 권한을 가진다. 작업이 끝나면 결과를 메인 에이전트에게 보고하고 종료된다.

#핵심 특징

• 단방향 통신: 서브에이전트는 결과를 메인 에이전트에게만 보고한다. 서브에이전트끼리 대화할 수 없다.
• 메인 세션 내부에서 동작: 별도 프로세스가 아니라 메인 세션의 하위 작업으로 실행된다.
• 중첩 불가: 서브에이전트가 또 다른 서브에이전트를 생성할 수 없다.
• 컨텍스트 보호: 서브에이전트의 작업 내용이 메인 대화 컨텍스트를 오염하지 않는다. 결과 요약만 돌아온다.

#빌트인 서브에이전트

#서브에이전트 정의 방법

마크다운 파일에 YAML frontmatter로 정의한다.

1---
2name: code-reviewer
3description: 코드 품질과 보안을 리뷰하는 전문 에이전트
4tools: Read, Grep, Glob, Bash
5model: sonnet
6---
7
8코드 리뷰어입니다. 호출되면 코드를 분석하고
9품질, 보안, 모범 사례를 짚어 구체적인 피드백을 제공합니다.

1---
2name: code-reviewer
3description: 코드 품질과 보안을 리뷰하는 전문 에이전트
4tools: Read, Grep, Glob, Bash
5model: sonnet
6---
7
8코드 리뷰어입니다. 호출되면 코드를 분석하고
9품질, 보안, 모범 사례를 짚어 구체적인 피드백을 제공합니다.

서브에이전트 파일을 어디에 저장하느냐에 따라 어디서 쓸 수 있는지가 결정된다. 예를 들어 code-reviewer.md라는 서브에이전트를 만들었다면:

• ~/.claude/agents/에 넣으면 → 내 컴퓨터의 모든 프로젝트에서 사용 가능 (개인용)
• .claude/agents/에 넣으면 → 해당 프로젝트 안에서만 사용 가능. git에 커밋하면 팀원도 함께 쓸 수 있다
• --agents CLI 플래그로 전달하면 → 그 세션에서만 쓰고 사라진다 (임시 테스트용)
• 플러그인 안의 agents/에 있으면 → 플러그인을 설치한 곳에서만 사용 가능

같은 이름의 서브에이전트가 여러 곳에 있으면 우선순위에 따라 하나만 적용된다. 더 구체적인 범위가 이긴다:

#주요 설정 옵션

모든 설정은 마크다운 파일의 YAML frontmatter에 선언한다. frontmatter가 설정, 본문이 시스템 프롬프트 역할을 한다.

#tools / disallowedTools

허용 또는 차단할 도구를 지정한다. tools를 생략하면 메인 대화의 모든 도구를 상속한다.

1tools: Read, Grep, Glob, Bash       # 허용 목록 (allowlist)
2disallowedTools: Write, Edit         # 차단 목록 (denylist)

1tools: Read, Grep, Glob, Bash       # 허용 목록 (allowlist)
2disallowedTools: Write, Edit         # 차단 목록 (denylist)

#model

서브에이전트가 사용할 모델을 선택한다. 생략하면 inherit(메인 대화 모델 상속)이 기본값이다.

1model: haiku    # sonnet, opus, haiku, inherit 중 택 1

1model: haiku    # sonnet, opus, haiku, inherit 중 택 1

#permissionMode

서브에이전트의 권한 프롬프트 처리 방식을 결정한다.

1permissionMode: acceptEdits   # 파일 수정 자동 승인

1permissionMode: acceptEdits   # 파일 수정 자동 승인

• default: 표준 권한 확인
• acceptEdits: 파일 수정 자동 승인
• dontAsk: 권한 요청 자동 거부 (명시적 허용 도구만 동작)
• bypassPermissions: 모든 권한 확인 건너뜀 (주의 필요)
• plan: 읽기 전용 탐색 모드

#hooks

서브에이전트가 도구를 쓰기 전/후에 셸 스크립트를 실행한다. 스크립트가 exit code 2를 반환하면 해당 도구 호출을 차단한다.

1hooks:
2  PreToolUse:
3    - matcher: "Bash"
4      hooks:
5        - type: command
6          command: "./scripts/validate-query.sh"

1hooks:
2  PreToolUse:
3    - matcher: "Bash"
4      hooks:
5        - type: command
6          command: "./scripts/validate-query.sh"

#memory

세션 간 지식을 축적하는 영구 저장소를 활성화한다. 설정하면 MEMORY.md 첫 200줄이 시스템 프롬프트에 자동 주입된다.

1memory: user    # user, project, local 중 택 1

1memory: user    # user, project, local 중 택 1

#isolation

임시 git worktree를 만들어 서브에이전트가 격리된 저장소 복사본에서 작업하게 한다. 변경 사항이 없으면 worktree가 자동 정리된다.

1isolation: worktree

1isolation: worktree

#skills

지정된 스킬의 전체 내용을 서브에이전트의 컨텍스트에 주입한다. 메인 대화의 스킬을 자동 상속하지 않으므로 명시적으로 나열해야 한다.

1skills:
2  - api-conventions
3  - error-handling-patterns

1skills:
2  - api-conventions
3  - error-handling-patterns

#Agent Teams란?

Agent Teams는 여러 Claude Code 인스턴스가 하나의 팀으로 협업하는 구조다. 한 세션이 팀 리드가 되고, 나머지 팀원(teammate)이 독립적으로 작업하면서 서로 직접 소통한다.

현재 실험적(experimental) 기능이며, 기본적으로 비활성화되어 있다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수를 1로 설정해야 사용할 수 있다.

#핵심 특징

• 양방향 통신: 팀원끼리 직접 메시지를 주고받을 수 있다. 리드를 거치지 않아도 된다.
• 완전히 독립적인 컨텍스트: 각 팀원이 별도의 Claude Code 인스턴스로 실행된다.
• 공유 작업 목록: 팀원이 공유 태스크 리스트에서 작업을 자율적으로 가져간다(self-claim).
• 사용자 직접 개입 가능: 리드뿐 아니라 개별 팀원에게 직접 지시할 수 있다.

#아키텍처 구성요소

#디스플레이 모드

• In-process: 모든 팀원이 하나의 터미널에서 실행. Shift+Down으로 팀원 간 전환.
• Split panes: 각 팀원이 별도의 pane에서 실행 (tmux 또는 iTerm2 필요).

#핵심 비교표

#언제 뭘 쓸까?

#Sub-agent가 적합한 경우

• 결과만 필요한 작업: 테스트 실행 후 실패 목록만 받기, 문서 조회 후 요약만 받기
• 컨텍스트 보호가 중요할 때: 대량의 출력(로그, 테스트 결과)이 메인 대화를 오염하지 않게 하고 싶을 때
• 도구 제한이 필요할 때: 읽기 전용 리뷰어, 특정 도구만 허용하는 전문 에이전트
• 비용 최적화: Haiku 모델로 간단한 탐색 작업을 빠르고 저렴하게 처리
• 순차 체이닝: A 결과를 B에게 넘기는 파이프라인 구조

1예: "서브에이전트로 테스트 스위트를 실행하고 실패한 테스트만 보고해줘"

1예: "서브에이전트로 테스트 스위트를 실행하고 실패한 테스트만 보고해줘"

#Agent Teams가 적합한 경우

• 상호 토론이 필요한 작업: 여러 관점에서 PR을 리뷰하고 서로의 발견을 공유/반박
• 경쟁 가설 검증: 버그 원인에 대한 여러 가설을 동시에 조사하면서 서로 반증 시도
• 독립적인 모듈 개발: 프론트엔드, 백엔드, 테스트를 각각 다른 팀원이 담당
• 장시간 병렬 작업: 서브에이전트의 컨텍스트 윈도우를 초과할 수 있는 대규모 조사

1예: "에이전트 팀을 만들어서 PR #142를 리뷰해줘.
2     한 명은 보안, 한 명은 성능, 한 명은 테스트 커버리지 담당."

1예: "에이전트 팀을 만들어서 PR #142를 리뷰해줘.
2     한 명은 보안, 한 명은 성능, 한 명은 테스트 커버리지 담당."

#둘 다 아닌 경우

• 빠른 질문: /btw를 사용하면 현재 컨텍스트에서 도구 없이 빠르게 답변
• 재사용 가능한 워크플로우: Skills를 사용하면 메인 대화 컨텍스트에서 실행
• 단순한 수정: 메인 대화에서 직접 처리하는 게 빠름

#제약 사항 비교

#Sub-agent 제약

• 서브에이전트끼리 통신 불가
• 서브에이전트가 다른 서브에이전트 생성 불가
• 백그라운드 실행 시 사용자 질문(AskUserQuestion) 불가

#Agent Teams 제약

• 실험적 기능이라 안정성 보장 없음
• 세션 재개(/resume, /rewind) 시 in-process 팀원 복원 안 됨
• 작업 상태가 지연될 수 있음 (팀원이 완료 표시를 빠뜨리는 경우)
• 세션당 하나의 팀만 운영 가능
• 팀원이 자체적으로 팀을 만들 수 없음 (중첩 팀 불가)
• 리드 교체 불가
• Split pane 모드는 VS Code 통합 터미널, Windows Terminal, Ghostty에서 미지원

#실전 사례: Agent Teams로 REST API 모듈 추가하기

프로젝트에 사용자 관리 REST API를 새로 추가하는 상황을 가정해 보자. 엔드포인트 설계, 구현, 테스트, 문서화가 모두 필요한 작업이다.

#팀 구성

1에이전트 팀을 만들어서 사용자 관리 REST API를 구현해줘.
2한 명은 백엔드 API 구현, 한 명은 테스트 작성, 한 명은 API 문서화 담당.

1에이전트 팀을 만들어서 사용자 관리 REST API를 구현해줘.
2한 명은 백엔드 API 구현, 한 명은 테스트 작성, 한 명은 API 문서화 담당.

이렇게 요청하면 Claude가 팀 리드가 되어 3명의 팀원을 생성한다:

#진행 흐름

1. 리드가 작업을 분해한다 - 코드베이스를 탐색해서 기존 구조(프레임워크, DB, 인증 방식)를 파악하고, 하위 작업으로 쪼갠다.

2. 팀원이 병렬로 작업한다 - worker-1이 API를 구현하는 동안 worker-3은 기존 API 문서 패턴을 파악해 명세 초안을 잡는다. worker-2는 테스트 환경을 세팅한다.

3. 팀원끼리 소통한다 - 이게 서브에이전트와의 핵심 차이다.

   • worker-1이 엔드포인트 시그니처를 확정하면 → worker-2와 worker-3에게 직접 알린다
   • worker-2가 테스트 중 버그를 발견하면 → worker-1에게 직접 보고한다
   • worker-3이 API 응답 형식에 의문이 있으면 → worker-1에게 직접 질문한다

4. 리드가 전체를 조율한다 - 작업 목록에서 진행 상황을 확인하고, 막히는 팀원이 있으면 개입한다. 모든 작업이 끝나면 결과를 종합해 보고한다.

#같은 작업을 서브에이전트로 했다면?

서브에이전트는 리드에게만 결과를 보고하므로, 흐름이 달라진다:

• worker-1이 엔드포인트를 확정해도 worker-2, worker-3은 모른다
• 리드가 일일이 결과를 전달해야 한다 ("worker-1이 이런 시그니처로 결정했으니 참고해")
• 테스트에서 버그가 발견되면, 리드가 중계해야 worker-1이 알 수 있다

단순한 작업(테스트만 실행, 문서만 조회)이면 서브에이전트로 충분하다. 하지만 이처럼 팀원 간 정보 교환이 빈번한 작업에서는 Agent Teams의 양방향 통신이 조율 부담을 줄여 준다.

#주의할 점

• 파일 충돌 방지: 팀원별로 담당 파일을 명확히 나눠야 한다. 같은 파일을 둘이 수정하면 덮어쓰기가 발생한다.
• 토큰 비용: 팀원 3명이면 독립 인스턴스 3개가 돌아간다. 단순한 작업에 팀을 꾸리면 비용만 늘어난다.
• 적정 팀 규모: 공식 문서에서는 3-5명을 권장한다. 팀원당 5-6개 작업이 적당하다.

#일상 작업에서는?

Agent Teams가 소프트웨어 개발 외의 일상 작업에서도 유용할까? 솔직히 말하면, 거의 쓸 일이 없다.

일상 작업은 대부분 이런 특성을 가진다:

• 한 사람의 요청에 하나의 결과가 나온다 (일정 조회, 메모 정리, 요약)
• 흐름이 순차적이다 (조사 → 판단 → 실행)
• 에이전트 간 토론이 필요 없다

이런 작업은 메인 대화 하나로 충분하고, 병렬 조사가 필요하면 서브에이전트로 해결된다.

#억지로 찾아본다면

이사할 동네를 조사하는 것처럼 여러 축을 동시에 비교해야 하는 경우가 그나마 가능성이 있다:

1토론토에서 이사할 동네를 조사해줘.
2한 명은 교통/통근, 한 명은 생활비/집값, 한 명은 생활 인프라.
3서로 발견한 정보를 공유하면서 종합 추천해줘.

1토론토에서 이사할 동네를 조사해줘.
2한 명은 교통/통근, 한 명은 생활비/집값, 한 명은 생활 인프라.
3서로 발견한 정보를 공유하면서 종합 추천해줘.

교통 담당이 "이 동네는 지하철역이 가깝다"고 추천하면, 생활비 담당이 "하지만 예산 초과"라고 바로 반박할 수 있다. 서브에이전트였다면 리드가 중계해야 할 정보가 팀원 간에 직접 오간다.

#하지만 현실적으로는

• 이런 조사도 서브에이전트 여러 개를 돌리고 리드가 종합하면 충분하다
• Agent Teams는 토큰 비용이 훨씬 높고, 아직 실험적 기능이다
• 일상 작업에서 "에이전트 간 실시간 토론"이 결과 품질을 유의미하게 올리는 경우는 드물다

Agent Teams는 여러 파일을 동시에 수정하고 변경 사항을 서로 알려야 하는 소프트웨어 개발에 특화된 기능이다. 일상 작업에서는 서브에이전트나 메인 대화 하나로 거의 다 커버된다.

#정리

Sub-agent와 Agent Teams는 "병렬 처리"라는 공통 목표를 다른 방식으로 해결한다.

• Sub-agent = 파견. 일 시키고 결과만 받는다. 가볍고 저렴하다.
• Agent Teams = 협업. 팀원이 스스로 소통하고 작업을 나눈다. 무겁지만 복잡한 문제에 강하다.

대부분의 작업에는 서브에이전트로 충분하다. 여러 관점의 토론, 경쟁 가설 검증, 대규모 병렬 개발처럼 "에이전트 간 소통"이 핵심인 작업에서만 Agent Teams를 고려하면 된다.

#참고

• Claude Code 공식 문서 - Sub-agents
• Claude Code 공식 문서 - Agent Teams