클로드 코드 멀티 에이전트 패턴: 오케스트레이터-워커·파이프라인·피어 선택 가이드

클로드 코드 멀티 에이전트 아키텍처에는 세 가지 핵심 패턴이 있습니다. 독립 작업을 병렬로 위임할 때는 오케스트레이터-워커 패턴, 각 단계가 앞 결과에 의존할 때는 파이프라인 패턴, 독립적인 상호 검증이 필요할 때는 피어 패턴을 선택합니다. 패턴마다 토큰 비용과 지연 시간 프로파일이 다르므로 작업 특성을 먼저 분석해야 합니다.

클로드 코드 단일 에이전트는 언제 한계에 부딪히나?

클로드 코드 단일 에이전트로 충분한 작업이 많습니다. 코드 리뷰, 문서 작성, 간단한 리팩터링은 하나의 에이전트로 처리하는 것이 빠르고 저렴합니다. 아키텍처를 복잡하게 만들기 전에 단일 에이전트로 충분한지 먼저 확인해야 합니다.

다음 세 가지 상황에서는 단일 에이전트가 한계에 부딪힙니다. 첫째, 작업 규모가 컨텍스트 창을 초과합니다. 대규모 코드베이스 분석이나 긴 문서 처리에서 자주 발생합니다. 둘째, 서로 독립적인 하위 작업을 순차 처리하느라 지연 시간이 과도해집니다. 병렬화할 수 있는 작업을 순서대로 처리하면 불필요한 대기가 생깁니다. 셋째, 단일 관점의 판단으로는 오류를 검출하기 어렵습니다. 보안 취약점 분석이나 중요한 아키텍처 결정은 독립적인 검토가 필요합니다. 세 조건 중 하나라도 해당되면 멀티 에이전트 전환을 검토할 시점입니다.

클로드 코드 멀티 에이전트 패턴 세 가지는 무엇인가?

클로드 코드 멀티 에이전트 패턴은 에이전트 간 관계에 따라 오케스트레이터-워커, 파이프라인, 피어 세 가지로 구분합니다.

• 오케스트레이터-워커: 중심 에이전트(오케스트레이터)가 하위 에이전트(워커)에 작업을 위임합니다. 하위 작업들이 서로 독립적이어서 병렬 실행이 가능한 경우에 씁니다.
• 파이프라인: 에이전트 A의 출력이 에이전트 B의 입력이 됩니다. 코드 생성 → 테스트 작성 → 코드 리뷰 → 문서화처럼 각 단계가 앞 단계에 의존하는 흐름에 씁니다.
• 피어: 여러 에이전트가 같은 문제를 독립적으로 분석합니다. 결과를 비교하거나 다수결로 최종 판단을 내립니다. 독립 검증이 필요한 고위험 작업에 씁니다.

세 패턴은 서로 배타적이지 않습니다. 오케스트레이터가 여러 파이프라인을 병렬로 실행하거나, 파이프라인의 마지막 단계에서 피어 패턴으로 최종 검증하는 방식으로 조합할 수 있습니다.

오케스트레이터-워커 패턴은 어떻게 구현하나?

클로드 코드에서 오케스트레이터-워커 패턴은 Agent 도구를 통해 구현합니다. Agent 도구를 호출하면 독립된 컨텍스트 창을 가진 하위 에이전트가 생성됩니다. 오케스트레이터는 자신의 컨텍스트를 유지하면서 여러 워커에게 작업을 위임할 수 있습니다.

구현 단계는 다음과 같습니다.

1. 오케스트레이터가 전체 작업을 분석하고 독립적인 하위 작업 목록을 작성합니다.
2. Agent 도구를 여러 번 호출합니다. 의존성이 없는 작업은 병렬로 호출할 수 있습니다.
3. 각 워커가 할당된 하위 작업을 처리하고 결과를 반환합니다.
4. 오케스트레이터가 워커 결과를 수집해 통합하고 전체 일관성을 검증합니다.

아래는 모듈별 병렬 리팩터링을 예로 든 의사코드입니다. CLAUDE.md에 오케스트레이터 역할을 정의하고, 독립적인 워커 두 개를 동시에 호출합니다.

# CLAUDE.md — 오케스트레이터 역할 정의
당신은 코드베이스 리팩터링 오케스트레이터입니다.
전체 작업을 모듈 단위로 분해하고, 독립 모듈은 Agent 도구로 병렬 위임합니다.
각 워커 결과를 수집한 뒤 인터페이스 일관성을 최종 검증합니다.

# 서브에이전트 호출 패턴
Agent(
  description = "auth 모듈 리팩터링",
  prompt = """
    src/auth/ 를 분석하고 불필요한 외부 의존성을 제거하라.
    변경 범위는 이 모듈 내부로 제한한다.
    완료 후 변경 파일 목록과 변경 요약을 반환한다.
  """
)

Agent(                        # 워커 1과 의존성 없음 → 동시 실행 가능
  description = "api 모듈 리팩터링",
  prompt = """
    src/api/ 를 분석하고 불필요한 외부 의존성을 제거하라.
    변경 범위는 이 모듈 내부로 제한한다.
    완료 후 변경 파일 목록과 변경 요약을 반환한다.
  """
)

# 오케스트레이터: 두 결과를 수집한 뒤 전체 인터페이스 일관성 검증

대규모 코드베이스 리팩터링이 전형적인 사례입니다. 오케스트레이터는 모듈 목록을 파악하고 모듈별로 워커를 배정합니다. 각 워커가 독립적으로 모듈을 분석하고 수정하는 동안 오케스트레이터는 전체 인터페이스 일관성을 관리합니다. 순차 처리 대비 지연 시간을 크게 줄일 수 있습니다.

오케스트레이터-워커를 선택할 때 주의해야 할 점이 있습니다. 워커 수가 늘수록 클로드 코드 토큰 사용량이 비례해 증가합니다. 병렬화로 얻는 속도 이득이 늘어나는 토큰 비용을 감수할 만한지 미리 따져야 합니다. 하위 작업 사이에 의존성이 있다면 파이프라인 패턴이 더 적합합니다.

파이프라인 패턴은 언제 선택해야 하나?

파이프라인 패턴은 각 에이전트의 역할을 명확히 분리합니다. 에이전트마다 앞 에이전트의 출력을 받아 처리하고, 결과를 다음 에이전트에 전달합니다. 단계 사이에 JSON 스키마처럼 구조화된 인터페이스를 정의하면 디버깅과 부분 재실행이 쉬워집니다.

파이프라인 설계 전에 세 가지를 확인합니다. 첫째, 각 단계의 입력과 출력 형식을 명확히 정의해야 합니다. 자연어 인터페이스는 모호성을 유발합니다. 둘째, 중간 단계가 실패했을 때 재시작할 수 있는 지점을 설계합니다. 셋째, 단계 수가 늘어날수록 전체 지연 시간이 증가한다는 점을 감안합니다. 각 에이전트의 응답 시간이 순서대로 누적됩니다.

단일 에이전트가 모든 단계를 처리할 때와 비교하면 파이프라인은 각 에이전트의 컨텍스트를 해당 단계에 집중시킬 수 있습니다. 코드 생성 에이전트는 좋은 코드를 쓰는 데만, 리뷰 에이전트는 생성된 코드의 품질 평가에만 집중합니다. 역할 분리가 각 단계의 출력 품질을 높입니다.

피어 패턴은 어떤 상황에 쓰나?

피어 패턴에서는 여러 에이전트가 같은 문제를 독립적으로 분석합니다. 에이전트들은 수평적 관계로, 어느 에이전트도 다른 에이전트의 결과를 미리 보지 않습니다. 독립성이 패턴의 핵심 가치입니다.

보안 취약점 분석이 좋은 사례입니다. 에이전트 A는 인증 흐름을 집중 분석하고, 에이전트 B는 데이터 검증 레이어를 검토하며, 에이전트 C는 외부 API 호출 패턴을 살핍니다. 각 에이전트가 독립된 컨텍스트에서 분석하므로 한 에이전트의 오판이 다른 에이전트에 영향을 주지 않습니다. 모든 에이전트가 같은 취약점을 지적했다면 신뢰도가 높습니다. 에이전트 간 의견이 갈린다면 해당 부분을 더 깊이 검토합니다.

피어 패턴은 단일 에이전트 판단보다 신뢰성이 높지만 에이전트 수만큼 토큰 비용이 증가합니다. 오류 비용이 높은 작업, 즉 보안 감사나 중요 비즈니스 로직 검증에 우선적으로 적용하는 것이 합리적입니다.

클로드 코드 토큰 사용량은 어떻게 확인하나?

멀티 에이전트 워크플로를 운영할 때는 클로드 코드 사용량 확인이 필수입니다. 클로드 코드 데스크탑 앱에서 /usage 명령을 입력하면 현재 세션의 클로드 코드 토큰 소비 현황을 바로 확인할 수 있습니다. 예상보다 빠르게 토큰이 소모된다면 어느 에이전트가 많이 쓰는지 파악하고 최적화합니다.

패턴별 토큰 특성을 파악해 두면 비용 예측에 도움이 됩니다.

• 오케스트레이터-워커: 워커 수에 비례해 토큰이 증가합니다. 병렬 실행이므로 지연 시간은 짧지만 총 토큰 소비는 많습니다.
• 파이프라인: 중간 단계 출력이 다음 단계 입력에 포함되므로 단계가 늘수록 토큰이 누적됩니다. 중간 출력을 압축해 전달하면 누적량을 줄일 수 있습니다.
• 피어: 에이전트 수만큼 토큰이 늘어납니다. 독립 검증의 가치가 추가 비용을 정당화하는지 판단해야 합니다.

멀티 에이전트 도입 시 팀이 가장 많이 하는 실수는?

클로드 코드 멀티 에이전트를 처음 도입하는 팀에서 반복적으로 나타나는 실수가 있습니다. 미리 파악해 두면 시행착오를 줄일 수 있습니다.

1. 모든 작업에 멀티 에이전트를 적용하려 합니다. 단순 작업은 단일 에이전트가 빠르고 저렴합니다. 패턴을 적용하기 전에 단일 에이전트로 먼저 시도하는 것을 기본 원칙으로 삼습니다.
2. 에이전트 간 인터페이스를 자연어로만 정의합니다. 자연어 인터페이스는 모호성을 유발하고 디버깅을 어렵게 합니다. JSON 스키마나 명확한 구조체로 정의합니다.
3. 오류 처리를 오케스트레이터에만 맡깁니다. 워커나 파이프라인 단계별로도 부분 실패를 처리할 수 있어야 합니다. 각 단계에 재시도 정책을 설계합니다.
4. 토큰 비용을 사전에 추정하지 않습니다. 클로드 코드 데스크탑의 /usage를 프로토타입 단계부터 모니터링합니다. 실운영 전에 비용 프로파일을 파악해 두는 것이 중요합니다.
5. 패턴 선택 근거를 기록하지 않습니다. 왜 이 패턴을 선택했는지 문서화해 두면 나중에 최적화하거나 다른 패턴으로 전환할 때 판단 기준이 됩니다.

이 내용이 ai-pot 자격증 시험에서 어떻게 출제되나?

멀티 에이전트 아키텍처 설계는 CCA-F(Claude Certified Architect — Foundations) 시험의 핵심 학습 주제입니다. 오케스트레이터-워커·파이프라인·피어 패턴의 선택 기준, 컨텍스트 창 관리, 에이전트 간 인터페이스 설계, 토큰 최적화 전략은 공식 학습 가이드에서 강조하는 영역입니다. Plinth Prep은 Anthropic과 무관한 독립 학습 사이트로, ai-pot 자격증을 목표로 하는 개발자를 위해 실전 중심 학습 자료를 제공합니다.