Claude Code Agent Teams: Skill, SubAgent, Agent Team 완전 정복
혼자 일하는 AI에서 팀으로 일하는 AI로 — 언제 무엇을 써야 하는가
Claude Code를 처음 쓰기 시작하면 대부분 단순하게 쓴다. 터미널에서 claude를 실행하고, 코드 작성을 시키거나 버그를 고쳐달라고 한다. 그런데 어느 순간 한계가 느껴진다. "이 작업은 병렬로 돌릴 수 있을 텐데", "이 부분은 전문화된 역할이 따로 있으면 좋겠는데" 하는 생각이 드는 순간이 온다.
Claude Code는 그 필요를 정확히 인식하고 Agent Teams라는 개념을 도입했다. 그리고 이 안에서 Skill, SubAgent, Agent Team이라는 세 가지 구성 요소가 서로 다른 역할을 맡는다. 이 세 가지를 헷갈리는 사람이 많다. 당연하다. 이름만 보면 다 비슷해 보인다. 오늘 그 차이를 정확하게 짚어보자.
왜 Agent Teams가 필요한가
전통적인 Claude Code 사용 방식은 단일 에이전트가 모든 것을 처리하는 구조다. 마치 혼자 일하는 개발자처럼 — 요구사항을 받고, 코드를 분석하고, 구현하고, 테스트하고, 문서를 쓰는 모든 일을 순차적으로 처리한다.
그런데 현실의 소프트웨어 개발은 그렇지 않다. 대규모 리팩토링을 할 때 프론트엔드와 백엔드를 동시에 수정해야 한다. 코드 리뷰와 테스트 자동화를 병렬로 돌려야 한다. 특정 기술에 특화된 전문가가 해당 영역만 담당해야 품질이 올라간다. 인간 팀이 분업하는 이유와 정확히 같다.
Agent Teams는 바로 이 문제를 해결한다. 복잡한 작업을 분해해서 여러 agent가 협업하게 만드는 것이다. 그렇다면, 이 협업의 구성 요소를 하나씩 살펴보자.
세 가지 핵심 개념: Skill, SubAgent, Agent Team
이 세 가지는 각자 다른 추상화 레벨에서 동작한다. 가장 작은 단위인 Skill부터 시작해서 위로 올라가는 방식으로 이해하는 것이 직관적이다.
Skill — "이 한 가지만큼은 내가 전문가다"
Skill은 agent가 수행할 수 있는 특화된 능력의 단위다. MCP(Model Context Protocol) tool이나 bash 명령어, API 호출처럼 agent가 외부 세계와 상호작용하는 구체적인 행동을 캡슐화한 것이라고 보면 된다.
예를 들어 "GitHub PR 생성", "데이터베이스 쿼리 실행", "특정 언어의 lint 실행"이 각각 하나의 Skill이 될 수 있다. Skill은 그 자체로는 독립된 agent가 아니다. 마치 함수처럼, 누군가가 호출해야 동작한다. Java에서 메서드를 정의해두는 것과 비슷하다 — 정의만으로는 실행되지 않는다.
Skill의 특징을 정리하면:
- 재사용 가능한 원자적 행동 단위
- 특정 도메인이나 작업에 특화됨
- 다른 agent나 orchestrator가 호출해서 사용
- 단독으로는 복잡한 워크플로우를 처리하지 못함
SubAgent — "나는 이 작업을 독립적으로 처리할 수 있다"
SubAgent는 독립적으로 작동하는 Claude Code 인스턴스다. 단순히 skill을 모아놓은 게 아니라, 자신만의 context를 갖고, 스스로 판단하며, 주어진 작업을 자율적으로 완료할 수 있는 에이전트다.
Orchestrator(상위 agent)로부터 작업을 받으면 SubAgent는 그것을 처음부터 끝까지 책임진다. 필요하면 파일을 읽고, 코드를 수정하고, 명령을 실행하고, 결과를 반환한다. 중간에 orchestrator에게 매번 보고하지 않고 자율적으로 처리한다는 점이 핵심이다.
SubAgent의 특징:
- 독립적인 Claude 인스턴스 — 자체 context window를 가짐
- 작업 단위로 실행되고 완료되면 결과를 반환
- Orchestrator의 지시 하에 동작하지만 세부 실행은 자율적
- 다른 SubAgent와 병렬 실행 가능
- 독립적인 context 덕분에 서로 간섭하지 않음
개인적으로 SubAgent를 이해하는 데 가장 좋은 비유는 팀의 주니어 개발자다. 시니어(Orchestrator)가 "이 모듈의 테스트를 작성해줘"라고 지시하면, 주니어는 알아서 코드를 분석하고, 테스트 케이스를 설계하고, 작성하고, 실행까지 해서 "완료했습니다, 결과는 이렇습니다"라고 보고한다. 중간 과정마다 허락을 구하지 않는다.
Agent Team — "우리는 함께 더 큰 문제를 푼다"
Agent Team은 Orchestrator 하나와 여러 SubAgent로 구성된 조직이다. Orchestrator는 전체 계획을 세우고 작업을 분배하며, 각 SubAgent는 맡은 영역을 병렬 또는 순차적으로 처리한다.
중요한 점은, Agent Team이 단순히 여러 agent를 묶어놓은 것이 아니라는 것이다. Orchestrator는 전체 목표를 이해하고, 어떤 SubAgent에게 어떤 작업을 언제 줄지를 동적으로 결정한다. 작업이 끝나면 각 SubAgent의 결과를 통합해서 최종 산출물을 만든다.
아래 그림이 전체 구조를 잘 보여준다.
<그림. Agent Team의 전체 구조 — Orchestrator가 SubAgent들을 조율하고 각 SubAgent는 Skill을 활용>
세 가지 비교: 무엇이 다른가
표로 정리하는 게 이 경우엔 가장 명확하다. 숫자 비교는 아니지만, 구조적 특성을 나란히 보는 것이 이해에 도움이 되기 때문이다.
구분SkillSubAgentAgent Team
| 추상화 레벨 | 원자적 행동 | 독립 실행 단위 | 조직/협업 구조 |
| 자율성 | 없음 (호출 의존) | 높음 (자율 실행) | 최상위 (전략적 결정) |
| Context | 없음 | 독립 context window | Orchestrator + 각 SubAgent context |
| 병렬 실행 | 불가 | 가능 | 기본 지원 |
| 재사용성 | 매우 높음 | 중간 | 낮음 (목적 특화) |
| 설정 복잡도 | 낮음 | 중간 | 높음 |
그런데 이 표만 보면 또 헷갈릴 수 있다. "그러면 항상 Agent Team을 쓰면 되는 거 아닌가?" 당연히 그렇지 않다. 각각 적합한 시나리오가 다르다.
언제 무엇을 써야 하는가
Skill을 쓸 때
반복적으로 사용하는 특정 도구나 외부 시스템 연동을 캡슐화할 때 Skill이 적합하다. MCP server로 제공되는 tool들이 대표적인 Skill의 형태다. GitHub, Jira, Slack과 연동하는 API call, 특정 형식으로 파일을 파싱하는 로직, 코드베이스에서 특정 패턴을 검색하는 기능 등이 여기에 해당한다.
Skill은 한 번 잘 정의해두면 어느 SubAgent든 재사용할 수 있다. 마치 잘 만든 라이브러리처럼, 정의는 한 번이고 사용은 여러 곳에서 한다.
SubAgent를 쓸 때
작업을 독립적인 단위로 분리할 수 있고, 그 단위들이 서로 다른 context에서 처리되어야 할 때 SubAgent가 빛난다. 특히 이런 상황:
- 작업이 명확하게 분리 가능하고 각자 독립적으로 완료될 수 있을 때
- 병렬로 처리하면 시간이 크게 단축될 때
- 메인 agent의 context window가 부족해질 때 (대규모 코드베이스 분석 등)
- 각 작업이 완전히 다른 집중이 필요할 때 (예: 보안 검토 vs 성능 최적화)
예를 들어 대규모 마이그레이션 작업에서 모듈별로 SubAgent를 띄워 병렬로 처리하면 전체 작업 시간이 획기적으로 줄어든다.
Agent Team을 쓸 때
프로젝트 전체를 아우르는 복잡한 목표가 있고, 그 목표를 달성하기 위해 여러 전문화된 역할이 협업해야 할 때 Agent Team이 필요하다. 다음 케이스가 대표적이다:
- 전체 기능 구현 — 설계, 구현, 테스트, 문서화를 각각의 SubAgent가 담당
- 코드베이스 전체 리뷰 — 보안, 성능, 코드 품질을 각자 전문 SubAgent가 담당
- CI/CD 파이프라인 자동화 — 빌드, 테스트, 배포 각 단계를 분리
- 리서치 + 구현 조합 — 한 SubAgent가 기술 조사를 하는 동안 다른 SubAgent가 스캐폴딩을 구성
실제로 어떻게 작동하는가
Claude Code에서 Agent Team을 구성하는 방법은 CLAUDE.md 설정 파일과 명시적인 orchestration 지시를 통해 이루어진다. Orchestrator로 동작하는 메인 Claude Code 인스턴스가 Task tool(또는 TodoWrite 같은 planning tool)을 사용해서 SubAgent에게 작업을 위임한다.
아래 예제는 Orchestrator가 SubAgent에게 작업을 분배하는 CLAUDE.md 설정의 예시다.
# CLAUDE.md — Orchestrator 설정 예시
## 역할
당신은 이 프로젝트의 기술 리드 역할을 하는 Orchestrator입니다.
복잡한 작업은 반드시 SubAgent에게 분배해서 병렬로 처리하세요.
## SubAgent 사용 지침
- 테스트 작성: SubAgent를 새로 생성해서 tests/ 디렉토리만 담당하게 하세요.
- 문서화: 별도 SubAgent에게 docs/ 디렉토리 전체를 위임하세요.
- 코드 리뷰: 각 모듈별로 독립 SubAgent를 생성해서 병렬 리뷰를 실행하세요.
## 금지 사항
- 모든 작업을 혼자 처리하지 마세요.
- 각 SubAgent의 결과를 수집한 뒤 통합해서 최종 보고서를 작성하세요.
## SubAgent 사용 지침 섹션이 핵심이다. Orchestrator에게 언제 어떤 역할의 SubAgent를 띄울지를 명시하면, 복잡한 작업을 받았을 때 자동으로 팀을 구성해서 처리한다.
SubAgent 자체의 CLAUDE.md는 더 단순하게, 자신이 맡은 역할에만 집중하도록 설정한다.
# CLAUDE.md — SubAgent (테스트 전문) 설정 예시
## 역할
당신은 테스트 작성 전문 SubAgent입니다.
오직 tests/ 디렉토리 안의 파일만 수정하세요.
다른 소스 파일은 읽기만 하고 절대 수정하지 마세요.
## 담당 Skill
- pytest 실행 및 결과 분석
- coverage 리포트 생성
- 테스트 케이스 설계 (경계값, 예외 케이스 포함)
## 완료 기준
모든 신규 코드의 coverage가 80% 이상이 되면 완료로 간주합니다.
이렇게 각 SubAgent의 역할과 제약을 명확하게 정의하는 것이 좋은 Agent Team 설계의 핵심이다.
Orchestrator와 SubAgent의 통신 구조
Agent Team이 내부적으로 어떻게 통신하는지 이해하면 설계할 때 실수를 줄일 수 있다. 아래 흐름을 보자.
<그림. Orchestrator와 SubAgent 간의 통신 흐름 — 병렬 실행 후 결과 통합>
Orchestrator는 SubAgent에게 작업을 위임할 때 초기 context와 목표를 전달한다. SubAgent는 독립적인 context window를 갖기 때문에 자신이 받은 정보 내에서만 동작한다. 이것이 장점이자 제약이다. SubAgent가 작업 도중 새로운 정보를 발견했을 때, 그 정보를 Orchestrator에게 전달하려면 명시적으로 결과에 포함시켜야 한다.
주의사항과 한계
Agent Team이 강력하긴 하지만, 만병통치약은 아니다. 몇 가지 현실적인 한계를 알고 써야 한다.
Context 단절 문제: 각 SubAgent는 독립된 context를 가지기 때문에, SubAgent 간에 직접 정보를 공유할 수 없다. 모든 정보 공유는 Orchestrator를 경유해야 한다. SubAgent A가 발견한 버그를 SubAgent B가 직접 알 수 없다는 뜻이다.
비용 증가: SubAgent 하나하나가 독립적인 Claude API 호출이다. 5개의 SubAgent를 동시에 띄우면 API 비용도 그만큼 증가한다. 단순한 작업에 Agent Team을 쓰는 것은 오버엔지니어링이다.
Orchestrator의 설계가 전부다: Orchestrator의 작업 분해 능력이 전체 팀의 성과를 결정한다. Orchestrator가 잘못된 방식으로 작업을 분배하면, SubAgent들이 아무리 열심히 일해도 결과가 엉킨다. CLAUDE.md 설정에 공을 들여야 하는 이유가 여기에 있다.
결과 통합의 복잡성: 여러 SubAgent의 결과를 Orchestrator가 통합할 때, 서로 충돌하는 변경사항이 생길 수 있다. SubAgent A는 파일 X를 이렇게 수정했는데, SubAgent B도 같은 파일 X를 다르게 수정하는 경우다. 이를 방지하려면 SubAgent 간의 작업 영역을 명확하게 분리해야 한다.
적합한 사용 시나리오 정리
지금까지 설명한 내용을 바탕으로, 실제 프로젝트에서 어떤 상황에 무엇을 써야 하는지 정리해보자.
Skill만으로 충분한 경우:
- 특정 외부 서비스와의 단순 연동 (GitHub PR 생성, Slack 알림 발송)
- 코드베이스에서 정보를 검색하거나 읽는 작업
- 단일 명령으로 완결되는 반복 작업
SubAgent가 필요한 경우:
- 대규모 코드베이스를 모듈별로 분석해야 할 때
- 시간이 오래 걸리는 작업을 병렬화하고 싶을 때
- 주 agent의 context window가 작업 내용을 모두 담기에 너무 클 때
Agent Team이 필요한 경우:
- 새 기능을 처음부터 끝까지 완성해야 할 때 (설계 → 구현 → 테스트 → 문서화)
- 코드베이스 전체에 대한 다각도 분석이 필요할 때 (보안 + 성능 + 품질)
- 여러 저장소나 서비스를 동시에 수정해야 하는 대규모 마이그레이션
- 24시간 자율 동작하는 개발 파이프라인 구축
마치며
Claude Code의 Agent Teams는 AI 코딩 도구가 단순한 자동완성이나 코드 생성을 넘어서, 실제 소프트웨어 개발 팀처럼 동작할 수 있다는 가능성을 보여준다. Skill은 능력의 원자 단위, SubAgent는 독립적으로 생각하고 실행하는 팀원, Agent Team은 그 팀원들을 조율하는 조직 구조다.
중요한 것은 복잡하다고 무조건 Agent Team을 쓸 필요는 없다는 점이다. 단순한 작업에 단순한 도구를, 복잡한 작업에 Agent Team을 쓰는 것이 맞다. 도구의 강력함은 적재적소에 쓸 때 빛난다.