Claude Code 서브에이전트(Subagents)와 오케스트레이터 패턴으로 병렬 AI 에이전트 파이프라인 구축하기

9개의 병렬 AI 에이전트로 PR 코드 리뷰 사이클을 대폭 단축한 팀의 사례가 주목받고 있다. 보안 검사, 코드 품질 분석, 정적 분석이 동시에 실행되고, 오케스트레이터가 결과를 심각도 순으로 통합해 최종 판정을 내리는 방식이다. 단일 AI 세션에 모든 것을 맡겼다면 컨텍스트 윈도우가 포화되고 응답 품질이 저하됐을 작업을, 역할 분리된 에이전트 팀이 해결하는 구조다.

Claude Code를 이미 써봤거나 진지하게 도입을 고려 중인 개발자라면 이 한계를 체감했을 것이다. 코드 리뷰, 보안 감사, 구현을 하나의 세션에 밀어 넣으면 컨텍스트는 금방 찰 뿐 아니라, 앞선 작업의 맥락이 뒤의 작업을 오염시킨다. Claude Code의 오케스트레이터-서브에이전트 아키텍처는 이 문제를 역할 분리와 컨텍스트 격리로 정면 돌파한다.

이 글에서는 병렬 코드 리뷰 파이프라인과 엔드-투-엔드 개발 파이프라인을 실제 에이전트 정의 파일과 함께 구현하는 방법을 다룬다. 그리고 서브에이전트를 언제 써야 하고 언제 쓰지 말아야 하는지 판단하는 기준을 독립 섹션으로 정리한다. Claude Code 자체의 설치와 기본 사용법은 전제로 하지만, 에이전트 시스템을 처음 접하는 개발자도 따라올 수 있도록 핵심 개념은 순서대로 풀어낸다.

핵심 개념

오케스트레이터와 서브에이전트의 역할 분리

오케스트레이터 패턴은 세 계층으로 구성된다.

사용자 요청
     │
     ▼
┌──────────────────────────────┐
│        오케스트레이터          │
│  (작업 분해 → 위임 → 통합)    │
└──────┬───────────┬────────────┘
       │           │
       ▼           ▼
 [서브에이전트A]  [서브에이전트B]
  독립 컨텍스트   독립 컨텍스트

핵심 구조: 각 서브에이전트는 독립된 컨텍스트 윈도우에서 실행된다. 서브에이전트 A의 작업이 서브에이전트 B의 컨텍스트를 오염시키지 않는다.

Agent Teams 참고: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true 환경 변수로 활성화하는 실험적 기능이다. 현재는 프로덕션 투입보다 개념 검증 수준으로 접근하는 것이 권장되며, 안정성이 보장되지 않는다.

서브에이전트 정의: .claude/agents/ 디렉터리

서브에이전트는 .claude/agents/ 아래 Markdown 파일로 정의한다. YAML 프론트매터로 이름·역할·허용 도구를 선언하고, 본문에 행동 지침을 작성한다.

---
name: security-reviewer
description: 보안 취약점 전문 리뷰어. SQL 인젝션, 인증 취약점, 하드코딩 시크릿을 검사한다.
tools:
  - read_file
  - bash
---
 
당신은 보안 전문 코드 리뷰어입니다.
다음 항목을 반드시 검사하세요:
1. SQL 인젝션 가능성
2. 인증 및 세션 관리 취약점
3. 하드코딩된 비밀키 또는 자격증명
4. 입력값 검증 누락
 
심각도(Critical / High / Medium / Low)로 분류하여 보고하세요.

CLAUDE.md vs .claude/agents/*.md: 프로젝트 전반의 행동 규칙은 CLAUDE.md에, 특정 역할로 호출되는 서브에이전트 정의는 .claude/agents/에 분리하는 것이 권장 패턴이다.

Task 도구: 서브에이전트 호출 메커니즘

오케스트레이터는 Claude Code 내장 task 도구를 통해 서브에이전트를 명시적으로 호출한다. task 도구를 사용하면 지정한 에이전트 이름의 .claude/agents/*.md 파일을 로드하여 독립 Claude 세션으로 실행한다. 오케스트레이터 에이전트 정의 파일의 tools 항목에 task가 포함되어야 다른 서브에이전트를 생성할 수 있다.

병렬 실행 원리: 오케스트레이터가 동일 응답 내에서 여러 task 호출을 발행하면, Claude Code는 이를 별도 세션으로 동시에 실행한다. 각 세션이 자체 컨텍스트를 가지기 때문에 가능한 구조다. 단, 순차 의존성이 있는 작업(A의 출력이 B의 입력인 경우)은 병렬로 실행할 수 없다.

CLI 실행 방법: claude 명령으로 대화형 세션을 시작한 뒤, 오케스트레이터 에이전트를 명시적으로 참조하여 호출한다.

# 대화형 세션 시작
claude
 
# 세션 내에서 오케스트레이터 에이전트 호출 예시:
# "@orchestrator-code-review 에이전트를 사용해서 현재 브랜치의 변경 사항을 리뷰해줘"

비대화형(CI/CD 등)으로 실행할 때는 -p 플래그를 사용한다.

# 비대화형 실행 (CI/CD 파이프라인에서)
claude -p "orchestrator-code-review 에이전트로 \
  $(git diff main...HEAD --name-only)를 리뷰하고 \
  결과를 review-report.md에 저장해줘" \
  --output-format json

심화: GitHub Actions 통합
GitHub Actions 워크플로우에서 위의 claude -p "..." 명령을 step으로 추가하면 PR이 열릴 때 자동으로 코드 리뷰 파이프라인이 실행된다. 프로그래밍 방식으로 제어하려면 Anthropic Agent SDK의 subagents 엔드포인트를 통해 에이전트를 직접 생성하고 결과를 스트리밍으로 받을 수 있다.

서브에이전트 도입 결정 체크리스트

서브에이전트는 강력하지만 모든 작업에 적용하면 비용과 복잡도만 늘어난다. 아래 기준으로 판단하라.

✅ 서브에이전트가 효과적인 경우

• 작업이 독립적으로 실행 가능하다 (A와 B가 서로의 결과를 기다리지 않아도 된다)
• 작업이 서로 다른 전문성을 요구한다 (보안 + 성능 + 스타일이 각각 다른 관점 필요)
• 단일 컨텍스트 윈도우(200K 토큰)로 감당이 안 되는 대형 코드베이스를 다룬다
• 검증 단계를 구현 단계와 분리하고 싶다 (편향 차단)
• 팀 전체가 재사용할 수 있는 표준화된 워크플로우가 필요하다

❌ 서브에이전트가 과잉인 경우

• 5분 안에 끝나는 단순 변환 또는 요약 작업
• 작업 간 강한 순차 의존성이 있어 병렬화 이득이 없다
• 토큰 비용에 민감한 환경 (서브에이전트는 에이전트 수와 출력 길이에 따라 표준 세션 대비 비용이 크게 늘어난다)
• 서브에이전트가 할 작업의 범위가 불명확하다 (범위가 겹치면 결과 충돌이 발생한다)

판단 경험칙: "이 작업을 두 명의 전문가에게 각각 맡겨도 결과가 독립적으로 의미 있는가?" — 그렇다면 서브에이전트 후보다.

실전 적용

예시 1: 병렬 코드 리뷰 파이프라인

언제 이 패턴을 쓰는가: 리뷰 항목이 독립적이고, 동시 실행으로 전체 소요 시간을 단축할 수 있을 때.

PR 변경 파일
     │
     ▼
┌─────────────────────────────────────────────┐
│              오케스트레이터                    │
│  (결과 수집 → Critical~Low 순 통합 → 판정)    │
└──────┬──────────┬──────────┬────────────────┘
       │          │          │          │
       ▼          ▼          ▼          ▼
  [linter]  [security]  [code-rev]  [quality]
  정적분석   취약점검사   개선5선    복잡도분석
  (병렬)     (병렬)      (병렬)     (병렬)

오케스트레이터 에이전트 정의

<!-- .claude/agents/orchestrator-code-review.md -->
---
name: orchestrator-code-review
description: PR 코드 리뷰를 전문 에이전트에게 병렬 위임하고 결과를 통합하는 오케스트레이터
tools:
  - task
  - read_file
---
 
당신은 코드 리뷰 오케스트레이터입니다.
 
## 실행 순서
 
1. 변경된 파일 목록을 파악한다
2. 다음 에이전트를 **동시에** 호출한다:
   - `security-reviewer`: 보안 취약점 검사
   - `code-quality-reviewer`: 품질 및 복잡도 분석
   - `linter-agent`: 정적 분석 및 스타일
3. 모든 에이전트 결과를 수집한다
4. Critical → High → Medium → Low 순으로 통합 리포트를 작성한다
5. 각 이슈에 담당 에이전트 출처를 명시한다
 
## 출력 형식
 
### 최종 판정: [APPROVED / REQUEST_CHANGES / BLOCKED]
 
| 심각도 | 이슈 | 파일:라인 | 출처 에이전트 |
|--------|------|-----------|--------------|

tools 항목의 task가 서브에이전트를 생성하는 핵심이다. 이 항목이 없으면 오케스트레이터는 다른 에이전트를 호출하지 못하고 스스로 처리하게 된다.

서브에이전트 정의 예시

<!-- .claude/agents/linter-agent.md -->
---
name: linter-agent
description: ESLint/Pylint 정적 분석 및 IDE 진단을 수집하여 보고한다
tools:
  - bash
  - read_file
---
 
당신은 정적 분석 전문가입니다.
제공된 파일에 대해 다음을 실행하고 결과를 보고하세요:
1. ESLint 또는 Pylint 실행 (bash 사용)
2. 스타일 가이드 위반 항목 목록 작성
3. 자동 수정 가능한 항목과 수동 검토 필요 항목을 구분하여 보고

예시 2: 엔드-투-엔드 개발 + 검증 파이프라인

언제 이 패턴을 쓰는가: 각 단계의 출력이 다음 단계의 입력이 되는 선형 파이프라인. 병렬화보다 순서가 중요할 때.

[pm-spec] → [architect-review] → [implementer-tester] → [black-box-verifier]

마지막 검증 단계를 별도 에이전트로 분리하는 것이 이 패턴의 핵심이다. 구현 에이전트는 자신이 만든 코드를 직접 검증할 때 이미 알고 있는 맥락으로 인해 결함을 간과하는 경향이 있다("전화 게임" 편향). 검증 에이전트는 구현 과정을 전혀 모르는 상태에서 블랙박스로 접근하여 이 편향을 차단한다.

<!-- .claude/agents/pm-spec.md -->
---
name: pm-spec
description: 자연어 요구사항을 구조화된 워킹 스펙 문서로 변환한다
tools:
  - write_file
  - read_file
---
 
당신은 시니어 PM입니다. 입력받은 요구사항을 아래 형식의 스펙 문서로 작성하세요.
출력 파일: `docs/spec-{feature-name}.md`
 
## 스펙 문서 형식
- **목표**: 한 문장 요약
- **사용자 스토리**: As a ... I want ... So that ...
- **수용 기준(AC)**: 체크리스트
- **비기능 요구사항**: 성능, 보안, 접근성
- **범위 외(Out of Scope)**: 명시적 제외 항목

<!-- .claude/agents/architect-review.md -->
---
name: architect-review
description: 스펙 문서를 검토하고 기존 아키텍처 기준으로 설계 적합성을 검증한다
tools:
  - read_file
  - write_file
  - bash
---
 
당신은 시니어 아키텍트입니다. pm-spec이 생성한 스펙 문서를 검토하세요.
 
검증 항목:
1. 기존 코드베이스와의 정합성 (`src/` 디렉터리 구조 참고)
2. 성능 및 확장성 위험 요소
3. 보안 아키텍처 고려사항
4. 구현 전 해결해야 할 선행 조건
 
출력: `docs/arch-review-{feature-name}.md`

<!-- .claude/agents/implementer-tester.md -->
---
name: implementer-tester
description: 스펙과 아키텍처 리뷰를 바탕으로 코드를 구현하고 테스트를 작성한다
tools:
  - read_file
  - write_file
  - bash
  - edit_file
---
 
당신은 풀스택 엔지니어입니다.
 
실행 순서:
1. `docs/spec-*.md`와 `docs/arch-review-*.md`를 읽는다
2. 수용 기준을 모두 충족하는 코드를 구현한다
3. 각 AC에 대응하는 유닛 테스트를 작성한다
4. `pnpm test`로 전체 테스트를 실행하고 모두 통과시킨다
5. `README.md` 또는 관련 문서를 업데이트한다

<!-- .claude/agents/black-box-verifier.md -->
---
name: black-box-verifier
description: 구현 컨텍스트 없이 완성된 코드를 블랙박스 테스트로 검증한다
tools:
  - bash
  - read_file
---
 
당신은 구현 과정을 전혀 모르는 QA 엔지니어입니다.
제공된 코드와 스펙 문서만 보고 독립적으로 검증하세요.
 
검증 절차:
1. `pnpm test` — 전체 테스트 통과 확인
2. `pnpm build` — 빌드 성공 확인
3. 스펙의 수용 기준을 하나씩 수동 대조
4. 엣지 케이스 3개 이상 추가 테스트
 
## 중요
구현자의 의도나 설명을 참고하지 마세요. 코드가 스스로 말하게 하세요.

implementer-tester와 black-box-verifier 둘 다 pnpm test를 실행하는 것이 중복 아닌가? implementer-tester는 테스트를 작성하고 통과시키는 구현자 관점이고, black-box-verifier는 스펙의 수용 기준과 엣지 케이스를 독립적으로 대조하는 검증자 관점이다. 같은 명령을 다른 목적으로 실행한다.

장단점 분석

장점

단점 및 주의사항

*"컨텍스트 버블링"은 이 글에서 사용하는 표현으로, 공식 용어가 아니다. 병렬 서브에이전트들의 출력이 오케스트레이터 컨텍스트 윈도우에 모두 누적되어, 에이전트 수가 늘수록 오케스트레이터의 컨텍스트 소모가 급증하는 현상을 가리킨다.

실무에서 가장 흔한 실수

실수 1: 모든 작업을 서브에이전트로 위임하기

5분 안에 끝나는 단순 작업을 서브에이전트로 나누면 오케스트레이터-서브에이전트 간 통신 오버헤드와 토큰 비용만 증가한다. 서브에이전트는 독립적으로 실행 가능하고, 병렬화 이득이 명확하며, 전문 컨텍스트가 필요한 작업에만 적용하라. 앞서 제시한 도입 결정 체크리스트를 판단 기준으로 삼으면 된다.

실수 2: 서브에이전트 간 암묵적 상태 공유 가정

서브에이전트 A가 생성한 파일을 서브에이전트 B가 자동으로 인식한다고 가정하는 경우가 많다. 서브에이전트는 독립 컨텍스트에서 실행되므로, 파일 경로와 기대 출력 형식을 오케스트레이터 프롬프트에 명시적으로 전달해야 한다.

# 잘못된 방식 (암묵적 의존)
`pm-spec` 에이전트를 실행한 후 `architect-review`를 실행하세요.
 
# 올바른 방식 (명시적 전달)
`pm-spec` 에이전트를 실행하여 `docs/spec-login-feature.md`를 생성하세요.
완료되면 `architect-review` 에이전트에 다음을 전달하여 실행하세요:
"검토할 스펙 파일: docs/spec-login-feature.md"

실수 3: 자동 라우팅에 의존하기

description 필드가 현재 태스크와 잘 일치하더라도 오케스트레이터가 서브에이전트를 호출하지 않고 메인 세션에서 직접 처리하는 경우가 많다. task 도구를 통한 명시적 호출이 현재로서는 훨씬 신뢰성이 높다. 오케스트레이터 프롬프트에 어떤 에이전트를 언제 호출할지 이름과 함께 명시하라.

마치며

서브에이전트 패턴의 본질은 AI를 더 많이 쓰는 것이 아니라, 복잡한 작업을 역할 분리된 전문가 팀처럼 처리하여 단일 에이전트로는 불가능한 품질과 규모를 달성하는 아키텍처 전환이다.

지금 바로 시작할 수 있는 3단계 — 단, Claude Code가 설치된 프로젝트가 선행 조건이다:

1. .claude/agents/security-reviewer.md 파일 하나를 만들어 기존 프로젝트에 보안 리뷰 에이전트를 추가한다. awesome-claude-code-subagents에서 100개 이상의 즉시 사용 가능한 템플릿을 확인하라.
2. 현재 가장 반복적으로 수행하는 작업(PR 리뷰, 테스트 작성, 문서 업데이트) 하나를 골라 오케스트레이터-서브에이전트 파이프라인으로 설계해본다. 이 글의 예시 1 또는 예시 2 구조를 시작점으로 삼으면 된다.
3. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true를 설정하고 Agent Teams를 탐색해본다. 프로덕션 투입보다는 피어-투-피어 에이전트 협업 패턴을 직접 경험하는 목적으로 접근할 것을 권장한다.

먼저 읽어야 할 자료: 공식 문서 Create custom subagents와 How and when to use subagents가 이 글의 직접적인 출발점이다. 나머지 참고 자료는 심화 학습 용도다.

다음 글: MCP(Model Context Protocol)로 Claude Code 서브에이전트에 GitHub, Slack, Sentry 등 외부 도구를 연결하여 자율 DevOps 파이프라인을 구축하는 방법

참고 자료

핵심 자료 (여기서 시작)

• Create custom subagents | Claude Code 공식 문서
• How and when to use subagents in Claude Code | Claude Blog

심화 자료

• Orchestrate teams of Claude Code sessions | Claude Code 공식 문서
• Multi-agent coordination patterns: Five approaches and when to use them | Claude Blog
• When to use multi-agent systems (and when not to) | Claude Blog
• Building effective agents | Anthropic Research
• How we built our multi-agent research system | Anthropic Engineering
• The Task Tool: Claude Code's Agent Orchestration System | DEV Community
• 9 Parallel AI Agents That Review My Code (Claude Code Setup) | HAMY
• Shipyard | Multi-agent orchestration for Claude Code in 2026
• Best practices for Claude Code subagents | PubNub Blog
• Connect Claude Code to tools via MCP | Claude Code 공식 문서
• Subagents in the SDK | Claude API Docs
• GitHub - VoltAgent/awesome-claude-code-subagents
• GitHub - wshobson/agents
• GitHub - ruvnet/ruflo