Claude Code 서브에이전트와 에이전트 팀 비교: 풀스택 기능 개발은 어떻게 나눌까
TL;DR
Claude Code의 서브에이전트와 에이전트 팀은 모두 별도 컨텍스트에서 일을 나눕니다. 차이는 작업자끼리 대화해야 하는가에 있습니다. 결과만 메인 세션으로 돌려받으면 되는 조사·검토는 서브에이전트, 프런트엔드·백엔드·테스트 담당이 발견 사항을 직접 공유하고 작업 상태를 함께 봐야 하면 에이전트 팀을 검토합니다.
에이전트 팀은 실험 기능이고 기본 비활성입니다. 각 teammate가 별도 Claude 인스턴스라 토큰 비용과 조정 부담도 더 큽니다. 처음에는 비민감 테스트 브랜치에서 파일 소유권이 겹치지 않게 정합니다. 병합·배포는 사람이 diff와 테스트를 확인한 뒤 승인합니다.
핵심 3줄 요약
이 글에서 다룰 내용
- 서브에이전트와 에이전트 팀의 공식 문서상 차이
- 결과 보고형 작업과 직접 협업형 작업의 선택 기준
- 풀스택 기능을 비민감 범위에서 나누는 7단계
- 실험 기능 활성화, 권한, 토큰 비용, 파일 충돌 주의점
- 추정 금지와 사람 승인까지 포함한 복사용 프롬프트
두 기능은 무엇이 다른가
풀스택 기능 하나를 추가하다 보면 검색 로그, API 변경, 화면 구현, 테스트 결과가 한 대화에 몰립니다. 컨텍스트가 복잡해졌다고 작업자부터 늘리면 오히려 조정할 일이 많아집니다. 먼저 작업 사이의 통신과 의존성을 봐야 합니다.
Claude Code 서브에이전트는 특정 작업을 맡는 전문 AI 작업자입니다. 자체 컨텍스트, 시스템 프롬프트, 도구 접근, 권한으로 일하고 결과를 호출자에게 돌려줍니다. 공식 문서는 검색 결과나 로그처럼 다시 볼 필요가 적은 자료를 별도 컨텍스트에서 처리하고 요약만 받는 용도를 설명합니다. 서브에이전트는 한 세션 안에서 동작하며 다른 서브에이전트와 공동 작업 목록을 운영하는 구조가 아닙니다.
Claude Code 에이전트 팀은 리드 세션이 여러 독립 teammate 세션을 조정하는 실험 기능입니다. teammate들은 공유 작업 목록에서 일을 확인하고 서로 직접 메시지를 보낼 수 있습니다. Anthropic은 프런트엔드·백엔드·테스트처럼 계층을 나눠 수정하는 작업을 강한 사용 사례로 제시합니다.
공식 비교표의 결정 규칙은 분명합니다. 빠르고 집중된 작업의 결과만 필요하면 서브에이전트를 사용합니다. 작업자들이 발견을 공유하고 서로 반박하거나 스스로 조정해야 하면 에이전트 팀을 검토합니다. 이는 성능 순위가 아니라 통신 구조에 따른 선택입니다.
서브에이전트를 고를 때
서브에이전트는 메인 세션이 계획과 통합을 계속 쥘 때 맞습니다. 옆 작업의 결과만 받아도 되는 경우입니다. 기존 인증 흐름 찾기, 영향 파일 목록 만들기, 실패 로그 요약, 읽기 전용 보안 검토처럼 입력과 산출물이 분명한 일이 해당합니다.
각 서브에이전트는 별도 컨텍스트를 쓰므로 탐색 출력이 메인 대화를 밀어내는 일을 줄일 수 있습니다. 도구와 권한을 제한한 사용자 정의 서브에이전트도 만들 수 있습니다. 반복해서 같은 검토를 맡긴다면 정의 파일을 재사용하는 방식이 맞습니다. 한 번의 탐색이라면 내장 Explore나 Plan 같은 작업자를 쓰는 흐름부터 확인할 수 있습니다.
진입 방식은 예전 글과 달라졌습니다. 현재 공식 문서 기준으로 v2.1.198부터
/agents
는 대화형 생성 마법사를 열지 않습니다. 이제 Claude에게 서브에이전트 파일 생성을 요청하거나
.claude/agents/
또는
~/.claude/agents/
를 직접 편집합니다. 설치 버전에 이 변경이 반영됐는지 확인해야 합니다. 문서에 없는 마법사 화면을 전제로 삼지 않습니다.
다만 서브에이전트 여러 개가 서로 협의해야 하는 작업은 메인 세션이 중계자가 됩니다. 프런트엔드 담당이 백엔드 응답 변경을 즉시 알아야 하고 테스트 담당이 두 쪽의 결정을 함께 따라야 한다면 보고가 메인 세션에 몰립니다. 이 경우에만 에이전트 팀의 직접 통신 구조를 검토합니다.
에이전트 팀을 고를 때
에이전트 팀은 독립적으로 진행할 영역 사이에 직접 협의가 필요할 때 맞습니다. Anthropic은 새 모듈이나 기능, 경쟁 가설을 시험하는 디버깅, 교차 계층 조정을 대표 사례로 듭니다.
리드는 일을 만들고 배정하며 결과를 종합합니다. teammate들은 공유 작업 목록에서 대기·진행·완료 상태와 의존성을 확인합니다. 서로 직접 메시지도 주고받습니다. 백엔드 담당이 응답 스키마 변경을 테스트 담당에게 알릴 수 있습니다. 테스트 담당은 실패 조건을 프런트엔드 담당에게 되물을 수 있습니다.
에이전트 팀은 기본으로 켜져 있지 않습니다. 현재 공식 문서는
settings.json
의
env
또는 셸 환경에서
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
을 설정하라고 안내합니다. 활성화한 다음 필요한 teammate 역할과 작업 경계를 자연어로 요청합니다. Claude가 서브에이전트를 대신 띄울 수도 있으므로, 팀이 꼭 필요하다고 판단했다면 프롬프트에서 에이전트 팀을 명시하고 실제 작업자 유형을 확인합니다.
선정한 공식 문서는 플랜·계정·지역·언어별 조건을 구체적으로 열거하지 않습니다. 현재 계정과 설치 버전에서 기능이 보이는지 확인합니다. 이 작업 환경에는 Claude Code CLI가 설치돼 있지 않아 로컬 화면을 직접 검증하지 못했습니다. 이 결과를 다른 환경의 기능 부재로 일반화하지 않습니다.
풀스택 기능 개발 도구를 고르는 7단계
1. 비민감 테스트 범위부터 만듭니다
운영 브랜치나 고객 데이터로 바로 시험하지 않습니다. 되돌릴 수 있는 테스트 브랜치와 비민감 예제 데이터를 준비합니다. 비밀값, 실제 고객 기록, 운영 토큰, 개인 식별 정보는 입력과 작업 파일에서 뺍니다.
완료 범위도 먼저 고정합니다. 이번 실행은 코드 변경안, 테스트 결과, 확인 필요 목록까지입니다. 병합, 배포, 데이터베이스 스키마 변경, 외부 전송은 사람이 별도로 승인할 항목으로 남깁니다.
2. 변경 지도를 먼저 만듭니다
수정 후보를 프런트엔드, 백엔드, 테스트로 나눕니다. 각 영역의 파일·인터페이스·검증 명령도 적습니다. 이때는 아직 작업자를 띄우지 않습니다. 같은 파일을 둘 이상이 고쳐야 하는지, 한 영역의 결정이 끝나야 다음 영역을 시작할 수 있는지부터 확인합니다.
한 파일에 변경이 몰리거나 순서 의존성이 크다면 단일 세션이나 서브에이전트가 더 적합합니다. 공식 문서도 순차 작업, 같은 파일 수정, 의존성이 많은 작업에는 팀보다 단일 세션이나 서브에이전트가 효과적이라고 안내합니다.
3. 작업자 간 직접 통신이 필요한지 정합니다
조사 결과와 테스트 요약을 메인 세션이 받아 합치면 충분한지 봅니다. 이 조건이면 서브에이전트를 선택합니다. 반대로 구현 담당들이 계약 변경과 실패 원인을 서로 직접 주고받아야 한다면 에이전트 팀을 검토합니다.
단순히 빨리 끝내고 싶다는 이유만으로 팀을 고르지 않습니다. 통신이 필요하지 않은데 독립 세션을 늘리면 토큰과 조정 비용만 커질 수 있습니다.
4. 이번 실행에서는 한 구조만 고릅니다
서브에이전트 경로를 골랐다면 메인 세션이 구현 계획을 소유합니다. 탐색, 영향 분석, 테스트 로그 요약처럼 결과형 작업만 서브에이전트에 맡기고 요약을 받은 뒤 메인 세션에서 수정합니다.
에이전트 팀 경로를 골랐다면 실험 기능 활성화 상태를 확인합니다. 프런트엔드·백엔드·테스트처럼 파일 소유권이 겹치지 않는 teammate를 요청합니다. 첫 실험에서는 두 구조를 자동으로 이어 쓰지 않습니다. 문제가 생겼을 때 어느 구조의 결과인지 추적하기 어려워지기 때문입니다.
5. 작업 경계와 승인 조건을 프롬프트에 넣습니다
각 작업자에게 허용 파일, 금지 파일, 입력 계약, 완료 테스트를 적습니다. teammate는 리드의 권한 설정으로 시작하며 권한 프롬프트는 리드 세션으로 올라옵니다. 다른 teammate가 사람 대신 권한을 승인하거나 거절된 작업을 우회할 수 없습니다.
에이전트 팀의 plan approval은 리드가 자율적으로 판단하는 기능입니다. 사람의 병합 승인과 같다고 보지 않습니다. 위험한 변경은 계획 단계에서도 금지합니다. 최종 diff·테스트·배포 여부는 사람이 따로 확인합니다.
6. 결과와 충돌을 대조합니다
서브에이전트 결과에는 근거 파일과 확인한 명령을 함께 요구합니다. 메인 세션에서 실제 파일과 로그를 다시 봅니다. 요약만 맞아 보여도 근거가 없으면 구현 판단에 쓰지 않습니다.
에이전트 팀에서는 공유 작업 목록의 완료 표시만 믿지 않습니다. 공식 문서는 작업 상태가 늦게 반영될 수 있다고 경고합니다. 같은 파일을 둘이 편집하면 덮어쓰기가 생길 수 있으므로 파일 소유권과 diff를 대조하고 전체 테스트를 다시 실행합니다.
7. 사람이 병합 여부를 승인합니다
변경 파일 목록과 테스트 통과·실패, 미해결 의존성, 추정한 부분을 한곳에 모읍니다. 사람이 요구사항과 공식 인터페이스 계약에 맞는지 확인합니다. 테스트가 통과했더라도 보안·데이터 처리·권한 경계가 바뀌었다면 별도 리뷰를 받습니다.
병합·배포·스키마 변경은 자동 완료 조건에 넣지 않습니다. 사람이 diff와 원래 요구사항을 확인하고 승인한 변경만 다음 단계로 넘깁니다.
그대로 복사해 쓸 프롬프트
아래 프롬프트는 한 실행에서 서브에이전트 또는 에이전트 팀 중 하나만 고르도록 설계했습니다. 대괄호 부분을 현재 저장소에 맞게 바꿉니다.
목표: [기능명]을 위한 변경 지도를 만들고, 작업자 간 직접 통신 필요 여부에 따라 서브에이전트 또는 에이전트 팀 중 하나만 선택해 코드 변경안과 테스트 결과를 준비한다.
허용 입력: 비민감 테스트 브랜치, [허용 디렉터리], 공개 가능한 요구사항, 현재 API·타입 계약, 테스트 명령.
제외 입력: 운영 비밀값, 고객 데이터, 개인 식별 정보, 허용 범위 밖 저장소, 외부 전송, 운영 배포 명령.
출력 형식: 1) 선택한 구조와 근거 2) 작업·파일 소유권 3) 변경 파일 4) 실행한 테스트와 결과 5) 충돌·미해결 의존성 6) 사람 확인 필요 항목.
완료 기준: 허용 범위의 변경안과 테스트 결과가 준비되고, 모든 주장에 근거 파일 또는 명령 결과가 있으며, 병합 전 확인 목록이 남아 있다.
추정 금지: 문서나 코드에서 확인하지 못한 API, 스키마, 권한, 테스트 결과, 성능 수치를 만들지 말고 확인 필요로 표시한다.
승인 지점: 파일 삭제, 같은 파일의 동시 편집, 비밀값·권한·스키마 변경, git commit·merge·push, 배포, 외부 전송은 내가 diff와 테스트를 본 뒤 승인한다.
선택 규칙:
- 결과만 메인 세션에 돌려주면 되는 집중 조사·검토라면 서브에이전트를 사용한다.
- 작업자끼리 발견을 직접 공유하고 작업 목록을 함께 조정해야 한다면 에이전트 팀을 검토한다.
- 순차 작업, 같은 파일 수정, 의존성이 많은 작업이면 팀을 만들지 않는다.
작업:
[구현할 기능과 검증할 사용자 흐름]
실전 활용 팁
첫 시험부터 병렬 구현을 맡기지 않는 편이 안전합니다. Anthropic도 처음 쓰는 사람에게 리뷰·조사·버그 탐색처럼 경계가 분명하고 코드를 쓰지 않는 작업부터 시작하라고 권합니다. 비민감 PR 하나를 보안, 성능, 테스트로 나눠 보면 직접 통신과 공유 작업 목록이 실제로 필요한지 확인하기 쉽습니다.
결정 기록은 길게 남길 필요가 없습니다. 왜 이 구조를 골랐는지, 누가 어떤 파일을 소유하는지, 사람이 무엇을 승인해야 하는지 세 항목이면 다음 실행에서 같은 실수를 줄일 수 있습니다. 팀이 필요 없었다면 다음에는 서브에이전트나 단일 세션으로 줄입니다.
주의할 점
에이전트 팀은 실험 기능입니다. 공식 문서는 세션 재개, 작업 상태, 종료 동작에 알려진 제한이 있다고 밝힙니다. in-process teammate는
/resume
과
/rewind
로 복원되지 않습니다. 작업 완료 상태가 늦게 반영되거나 종료가 지연될 수도 있습니다. 장시간 무인 실행을 전제로 삼지 않습니다.
토큰 사용량은 활성 teammate 수에 따라 늘어납니다. 팀 규모를 늘린다고 속도가 같은 비율로 늘지는 않습니다. 정기 작업이나 작은 수정은 단일 세션이 더 경제적일 수 있습니다. 비용 한도와 중단 조건을 먼저 정합니다.
두 teammate가 같은 파일을 고치면 덮어쓰기가 발생할 수 있습니다. 공유 작업 목록은 파일 격리를 보장하지 않습니다. 파일 소유권을 나누고 diff를 확인합니다. 테스트 통과도 요구사항·보안·데이터 처리의 정확성을 보장하지 않으므로 사람이 원래 자료에 대조합니다.
현재 공식 페이지는 에이전트 팀의 구체적인 플랜·계정·지역·언어 조건을 열거하지 않습니다. 현재 문서와 계정 UI를 확인합니다. 조직 저장소라면 관리자 정책, 소스 코드 반출 기준, 허용 모델과 권한 설정을 먼저 따릅니다.
자주 묻는 질문
서브에이전트도 서로 메시지를 보낼 수 있지 않나요?
현재 문서에는 이름 있는 서브에이전트의 재개와 메시지 전달 기능도 설명돼 있습니다. 그러나 공식 비교에서 서브에이전트의 기본 조정 구조는 결과를 메인 호출자에게 돌려주는 방식입니다. 에이전트 팀은 공유 작업 목록과 teammate 간 직접 통신을 핵심으로 둡니다. 이번 선택은 단일 메시지 가능 여부가 아니라 공동 작업 상태와 자체 조정이 필요한지를 기준으로 합니다.
에이전트 팀이 서브에이전트보다 항상 빠른가요?
아닙니다. 공식 문서는 에이전트 팀에 조정 오버헤드와 더 큰 토큰 비용이 있다고 밝힙니다. 순차 작업, 같은 파일 수정, 의존성이 많은 작업은 단일 세션이나 서브에이전트가 더 효과적입니다. 독립 영역을 실제로 동시에 진행할 수 있을 때만 팀의 이점이 생깁니다.
`/agents`를 실행하면 서브에이전트 생성 화면이 열리나요?
현재 공식 문서 기준으로 v2.1.198부터 생성 마법사가 열리지 않습니다. Claude에게 필요한 정의를 만들어 달라고 요청하거나
.claude/agents/
또는
~/.claude/agents/
를 직접 편집합니다. 설치 버전이 다르면 현재 공식 문서와 로컬 동작을 함께 확인합니다.
에이전트 팀의 plan approval이면 사람 검토를 생략해도 되나요?
안 됩니다. 공식 문서의 plan approval은 teammate 계획을 리드가 자율적으로 승인하거나 반려하는 흐름입니다. 사람의 보안 검토, 병합 승인, 배포 승인을 대신하지 않습니다. 위험한 변경을 금지 범위로 남기고 사람이 diff와 테스트를 확인합니다.
출처
마무리
Claude Code 서브에이전트와 에이전트 팀의 차이는 작업자 수가 아니라 조정 구조입니다. 검색·검토 결과를 메인 세션에서 통합하면 충분하다면 서브에이전트를 고릅니다. 프런트엔드·백엔드·테스트 담당이 발견을 직접 공유하고 공동 상태를 봐야 한다면 에이전트 팀을 검토합니다.
먼저 변경 지도와 파일 소유권을 적습니다. 그다음 직접 통신이 필요한지 판단해 한 구조만 선택합니다. 마지막에는 공유 작업 목록이나 테스트 표시를 그대로 믿지 않습니다. 사람이 diff·근거·미해결 의존성을 확인한 뒤 병합 여부를 승인합니다.
