[Claude] 서브에이전트에서 에이전트 팀으로

들어가며

처음에는 서브에이전트(Sub-agent)를 만들어 각각 특화된 역할을 맡기면 모든 게 편해질 줄 알았습니다. 하지만 현실은 달랐습니다. 에이전트를 일일이 스위칭해가며 일을 시키고, A 에이전트가 작업을 끝냈는지 확인한 뒤 그 결과를 제가 직접 B 에이전트에게 넘겨주는 과정이 반복되었죠. 어느새 제가 AI들의 '메시지 셔틀'이 되어 끊임없이 요청과 조율을 반복하고 있었고, 이 과정 자체가 너무 버겁고 불편했습니다.

'얘네들끼리 알아서 대화하고 결과를 내면 안 되나?'

이런 답답함에 해결책을 찾다 발견한 것이 바로, 에이전트들끼리의 직접적인 상호작용을 지원하는 Claude Code의 Agent Teams 기능이었습니다. 여러 개의 독립적인 인스턴스가 하나의 프로젝트 안에서 실제로 협업하고, 컨텍스트를 공유하며 서로 메시지를 주고받는다니 딱 제가 원하던 그림이었죠.

이 글은 제가 기존에 서브에이전트 형태로 일일이 호출하며 운영하던 6명의 'Spark 학습용 도우미' 중 3명을 묶어, 처음으로 하나의 유기적인 팀을 구축해 본 생생한 기록입니다.

 

1. 서브에이전트 vs 에이전트 팀

두 기능의 가장 큰 차이는 이 한 줄로 요약할 수 있습니다.

구분	서브에이전트 (Sub-agent)	에이전트 팀 (Agent Team)
컨텍스트	독립 윈도우, 결과는 리더에게만 반환	독립 윈도우 + 팀원끼리 직접 메시지 교환
통신	메인 에이전트에게만 1:1 보고	팀원 간 토론 및 반박 가능
작업 조율	메인이 중앙에서 통제	공유 작업 목록을 통한 자체 조율
직접 개입	불가	특정 팀원에게 직접 지시 가능
최적 용도	단순 정보 수집, 요약 작업	가설 검증, 협업 디버깅, 복합 파이프라인
토큰 비용	상대적으로 낮음	팀원 수에 비례해 가파르게 증가

 

단순한 검색이나 결과 요약이라면 서브에이전트가 여전히 효율적입니다. 하지만 다각도의 코드 리뷰나 경쟁 가설을 세워 디버깅해야 하는 상황에서는 팀 단위의 협업이 압도적인 퍼포먼스를 보여줍니다.

2. 내 워크스페이스 — Spark 학습용 6개 에이전트

저는 Apache Spark를 본격적으로 딥다이브하기 위해 .claude/agents/ 폴더에 6개의 특화된 서브에이전트를 만들어 운영하고 있었습니다.

• spark-env-builder: Docker 클러스터 셋업, 포트 운영(4040/8080/18080), 환경 트러블슈팅
• spark-tutor: 레슨 설계, 예제/연습 파일 생성, README 학습 일지 작성
• spark-reviewer: 프로덕션 리뷰 및 학습용 연습 문제 채점 (듀얼 모드)
• spark-project-planner: 실전 프로젝트의 PROJECT_PLAN.md 아키텍처 작성
• spark-project-coder: 계획서(PLAN)의 태스크별 실제 코드 구현
• spark-data-generator: 엣지 케이스 테스트용 더미 데이터(Skew, NULL 대량, 대용량) 생성

서브에이전트 단계에서도 이 6명은 제 역할을 다했습니다. 학습을 시작하면 Tutor에게 예제를 받고, 제가 직접 푼 뒤, Reviewer에게 채점을 부탁하는 사이클이 꽤 매끄러웠죠.

그런데 어느 순간 "이 셋이 동시에 움직이면 훨씬 빠르지 않을까?"라는 생각이 들었습니다. 채점 결과를 받자마자 학습 일지(README) 업데이트를 트리거하거나, 클러스터 헬스체크가 돌아가는 동안 Tutor가 다음 레슨 자료를 미리 준비하게 만들고 싶어졌거든요.

그래서 이들을 팀으로 전환하기로 결심했습니다.

3. 왜 6명을 전부 팀으로 묶지 않았나?

처음엔 6명 전체를 거대한 하나의 팀으로 만들까 고민했지만, 다음 세 가지 이유로 포기했습니다.

1. 오버헤드와 비용: 공식 권장 인원은 3~5명입니다. 인원이 늘어날수록 조율을 위한 오버헤드와 토큰 비용이 급격히 증가합니다.
2. 역할의 시기적 분리: Planner, Coder, Data Generator는 '실전 프로젝트' 단계에서만 필요합니다. 기초 학습 단계에서는 휴식하는 것이 맞습니다.
3. 충돌 리스크: 팀 멤버가 많을수록 동일한 파일을 동시에 수정하려다 충돌할 위험이 커집니다. 책임 영역이 완벽히 분리된 인원만 묶는 것이 안전합니다.

학습 사이클 한 바퀴(환경 준비 → 학습 자료 제공 → 풀이 → 채점)를 완결할 수 있는 최소 인원. 답은 이미 정해져 있었습니다.

4. 학습 사이클의 핵심 트리오

에이전트	팀 내 역할	핵심 책임
spark-env-builder	환경 운영팀	컨테이너 헬스체크, spark-submit 실행, 포트 확인
spark-tutor	학습 진행팀	레슨 주제 안내, 실습 파일 생성, 학습 일지 업데이트
spark-reviewer	품질 검토팀	실습 문제 채점, 코드 최적화 리뷰

 

이렇게 세 명을 묶으면 학습의 한 사이클을 자체적으로 완결하면서도, 서로의 작업 영역(인프라/학습/검증)이 겹치지 않아 안전합니다.

5. 셋업 — settings.json 위치 결정

Agent Teams는 아직 실험적 기능이므로 환경변수를 통해 명시적으로 활성화해야 합니다.

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

여기서 설정 파일의 위치 선택이 중요합니다.

• 글로벌 (~/.claude/settings.json): 모든 프로젝트에 영향을 미칩니다.
• 프로젝트 (<프로젝트>/.claude/settings.json): 해당 워크스페이스에서만 활성화됩니다.

저는 Spark 학습 워크스페이스에만 한정해서 실험하고 싶었기에 프로젝트 단위를 선택했습니다. (C:\spark-study\.claude\settings.json) 설정을 저장한 후 해당 폴더에서 Claude를 새로 실행하면 기능이 켜집니다. (다른 폴더에서 열려 있던 기존 세션에는 적용되지 않으니 주의하세요.)

6. 실전 워크플로우 — 세 가지 시나리오 테스트

시나리오 1. 첫 시도 (읽기 전용)

공식 가이드에서도 권장하는 패턴입니다. 파일을 직접 수정하지 않고 상태 조사만 시키면서 팀이 어떻게 소통하는지 관찰해 보았습니다.

• 지시: "세 명으로 에이전트 팀을 만들어줘. Env-builder는 컨테이너 상태 점검, Tutor는 진척 상황 확인, Reviewer는 지난 실습 코드 점검. 병렬로 자기 영역만 조사하고 수정은 하지 마."

시나리오 2. 협업 워크플로우 (새 레슨 시작)

• 목표: 다음 레슨인 Join 파트 실습 준비
• 흐름: Tutor가 기초 및 응용 실습 코드를 작성하는 동안, Env-builder는 백그라운드에서 Docker와 History Server 상태를 확인합니다. Reviewer는 대기하다가 Tutor의 작업이 끝나면 코드를 넘겨받아 사전 검증을 진행합니다.

시나리오 3. 채점 자동화 흐름

• 지시: "내가 4강 실습 코드를 다 채웠어. 순서대로 진행해 줘."
• 흐름: 1. Env-builder가 spark-submit으로 코드를 실행하고 로그 캡처.3. Tutor가 채점 결과를 바탕으로 README의 학습 진척도 업데이트.
• (만약 1단계에서 에러가 나면 흐름이 멈추고 바로 디버깅으로 전환됩니다.)
• 2. Reviewer가 실행 결과와 정답지를 대조해 채점 진행.

7. 디스플레이 모드와 통제 기능

디스플레이 모드

• 인프로세스 (In-process): 메인 터미널 하나에서 실행되며 Shift + ↑/↓ 키로 팀원 화면을 전환합니다. (Windows에서는 사실상 이 방식이 기본이며 꽤 쾌적합니다.)
• 분할 창 (Split-pane): 각 팀원이 별도의 창에 뜹니다. tmux나 iTerm2 환경이 필요합니다.

팀 통제력을 높이는 팁

• 계획 승인 요구: "코드를 수정하기 전에 계획부터 보여주고 내 승인을 받아"라고 명시해 두면 사고를 방지할 수 있습니다.
• Delegate 모드 (Shift + Tab): 리더인 제가 직접 코드를 만지지 않고 조율에만 집중하도록 강제합니다. 팀 운영 시 켜두는 것을 추천합니다.
• 직접 개입: 특정 팀원의 화면으로 넘어가 개별적인 추가 지시를 내릴 수도 있습니다.

8. 주의 사항과 한계

• 동시 수정 금지: git처럼 충돌을 알아서 머지(Merge)해주지 않습니다. 팀원 간 수정 권한 영역을 파일 단위로 명확히 갈라두어야 합니다.
• 비용 문제: 팀원 수에 비례해 토큰이 빠르게 소모됩니다. 3명 기준 단일 세션 대비 2~3배의 비용이 발생합니다.
• 세션 복구 불가: /resume나 /rewind 명령어로 진행 중이던 팀원 세션을 되돌릴 수 없습니다.
• 명시적 종료 필요: 작업이 끝나면 반드시 "팀을 정리해 줘"라고 지시해야 합니다. 그렇지 않으면 백그라운드에 남아 불필요한 토큰을 갉아먹을 수 있습니다.

9. 서브에이전트와 비교한 체감 효과

서브에이전트가 "심부름꾼이 다녀와서 보고하는" 느낌이었다면, 에이전트 팀은 "내 옆자리에 앉아 같이 일하는 든든한 동료"라는 느낌이 강했습니다.

특히 만족스러웠던 순간은 채점 흐름(시나리오 3)이었습니다. 단일 세션이었다면 AI가 혼자서 코드를 돌려보고, 채점하고, 문서까지 수정하느라 컨텍스트가 엉키기 일쑤였을 겁니다. 하지만 팀 환경에서는 Env-builder가 캡처한 로그를 Reviewer에게 넘기고, 평가가 끝나면 Tutor가 문서를 다듬는 식으로 명확한 '파이프라인'이 형성되어 디버깅과 진행 상황 파악이 훨씬 수월했습니다.

마치며

서브에이전트에서 에이전트 팀으로 넘어가는 것은 분명 짜릿한 경험입니다. 하지만 가장 중요한 것은 "내 워크플로우 중 어디에 진짜 '팀'이 필요한가"를 파악하는 일입니다. 모든 작업이 팀을 요구하지는 않으니까요.

저는 6명의 에이전트 중 단 3명만 팀으로 묶었습니다. 이들이 기초 학습 사이클의 핵심 트리오이기 때문이죠. 나머지 3명(Planner, Coder, Data Generator)은 훗날 실전 프로젝트 단계에 돌입했을 때 따로 팀으로 묶거나 개별 호출하여 사용할 예정입니다.