min.log

Day 14: 멀티 에이전트 오케스트레이션 패턴

16 min read

Day 14: 멀티 에이전트 오케스트레이션 패턴

AI Tools Mastery Curriculum — Week 3, Day 14 소요 시간: 50분 | 학습 + 실습

핵심 배운 점

  • Fan-out/Fan-in(병렬) / 파이프라인(순차) / 토론(경쟁적) 3가지 패턴
  • 멀티 에이전트의 핵심은 병렬이 아니라 “컨텍스트 분리”
  • 서브 에이전트 간 직접 통신 불가 → 파일로 데이터 전달

① 오케스트레이터-워커 패턴 학습

왜 멀티 에이전트가 필요한가

단일 에이전트의 한계:

문제: "배송 시스템의 성능 병목을 분석하고 리팩토링해줘"

단일 에이전트로 처리하면:
  1. 코드 분석 (컨텍스트 소모 ↑)
  2. 성능 프로파일링 (컨텍스트 소모 ↑↑)
  3. 리팩토링 설계 (컨텍스트 소모 ↑↑↑)
  4. 구현 (컨텍스트 부족 → 품질 ↓)

→ 후반부로 갈수록 초반 맥락을 잊고 품질이 떨어진다

멀티 에이전트로 해결:

오케스트레이터 (메인):
  ├─ 워커 A: "코드 분석" → 결과 반환 (독립 컨텍스트)
  ├─ 워커 B: "성능 프로파일링" → 결과 반환 (독립 컨텍스트)
  └─ 오케스트레이터가 결과 종합 → 리팩토링 실행

→ 각 워커가 깨끗한 컨텍스트에서 작업, 메인도 깨끗하게 유지

핵심 패턴 3가지

패턴 1: 오케스트레이터-워커 (Fan-out/Fan-in)

가장 기본적인 패턴. 메인이 작업을 분배하고, 워커 결과를 취합한다.

        ┌─── 워커 A (분석) ───┐
메인 ───┤                     ├─── 메인 (종합)
        └─── 워커 B (테스트) ──┘

적합한 상황: 독립적인 작업을 병렬로 수행할 때

패턴 2: 파이프라인 (순차 처리)

앞 단계의 결과를 다음 단계의 입력으로 넘긴다.

메인 → 워커 A (설계) → 워커 B (구현) → 워커 C (테스트) → 메인

적합한 상황: 작업 간 의존성이 있을 때 (설계 → 구현 → 테스트)

패턴 3: 토론/검증 (경쟁적 병렬)

같은 문제를 다른 관점에서 분석하게 하고, 결과를 비교한다.

        ┌─── 워커 A (Redis 옹호) ───┐
메인 ───┤                           ├─── 메인 (최종 판단)
        └─── 워커 B (Kafka 옹호) ───┘

적합한 상황: 기술 선택, 아키텍처 결정, 디버깅 가설 검증

Claude Code의 멀티 에이전트 도구

도구수준특징
Task() (서브 에이전트)세션 내별도 컨텍스트, 결과만 반환, 최대 10개 병렬
Agent Teams (실험적)세션 간tmux 기반, 에이전트 간 메시지, 독립 세션
.claude/agents/커스텀역할별 시스템 프롬프트 + 도구 제한

이번 Day에서는 Task() 서브 에이전트를 중심으로 실습한다. Day 3에서 배운 내용의 실전 확장이다.

② Claude Code Task() 멀티 에이전트 시뮬레이션

기본 사용법 복습 (Day 3)

claude
 
> "3개 영역을 병렬로 분석해줘:
  1. src/service/ 폴더의 코드 품질
  2. src/controller/ 폴더의 API 설계
  3. src/repository/ 폴더의 쿼리 효율성
  각각 서브 에이전트로 분석하고 결과를 종합해줘"

Claude가 3개의 general-purpose 서브 에이전트를 생성해서 병렬로 분석한다.

실습 1: Fan-out/Fan-in — 날씨 MCP 서버 코드 리뷰

Day 12~13에서 만든 weather-mcp-server를 멀티 에이전트로 리뷰한다:

claude
 
> "weather-mcp-server 프로젝트를 3개 관점에서 병렬 리뷰해줘.
  각각 서브 에이전트로 수행하고 결과를 종합해줘:
 
  1. 에러 처리 리뷰: 모든 도구 핸들러의 try/catch, 에러 메시지 품질,
     edge case 누락 여부를 분석
 
  2. 성능 리뷰: API 호출 패턴, 캐시 효율성, 
     불필요한 중복 호출이 있는지 분석
 
  3. 보안 리뷰: API 키 관리, 입력 검증,
     인젝션 가능성이 있는지 분석
 
  종합 결과를 심각도(High/Medium/Low)별로 정리해줘."

기대 결과:

  • 3개 서브 에이전트가 각각 독립 컨텍스트에서 분석
  • 메인 에이전트가 결과를 취합하여 심각도별 보고서 작성
  • 메인의 컨텍스트는 깨끗하게 유지 (각 분석의 상세 과정은 서브 에이전트에서 소모)

실습 2: 파이프라인 — 새 기능 추가

순차적 의존성이 있는 작업을 서브 에이전트 체인으로 처리한다:

claude
 
> "weather-mcp-server에 'get_air_quality'라는 새 도구를 추가하고 싶어.
  다음 순서로 서브 에이전트를 사용해서 진행해줘:
 
  Step 1 (조사 에이전트): OpenWeather Air Pollution API 문서를 조사하고
         API 엔드포인트, 파라미터, 응답 구조를 정리해서 파일로 저장
 
  Step 2 (구현 에이전트): Step 1의 조사 결과를 읽고
         기존 코드 패턴에 맞춰 get_air_quality 도구를 구현
 
  Step 3 (테스트 에이전트): Step 2의 구현을 검토하고
         에러 처리가 적절한지, 기존 도구와 일관성이 있는지 확인
 
  각 Step의 결과를 파일로 저장하고, 최종 코드를 보여줘."

핵심: 서브 에이전트 간에 직접 통신은 안 되므로, 파일을 통해 결과를 전달한다. 메인 에이전트가 “Step 1 결과를 읽고”라고 지시하면, Step 2 서브 에이전트가 해당 파일을 읽어서 작업한다.

실습 3: 토론 — 아키텍처 결정

Day 12의 서버를 확장할 때 기술 선택이 필요한 상황을 시뮬레이션한다:

claude
 
> "weather-mcp-server를 여러 사용자가 쓸 수 있는 원격 서버로
  전환하려고 해. 두 가지 접근을 비교해줘.
  각각 서브 에이전트가 담당해서 장단점을 분석하고,
  마지막에 종합 판단을 내려줘:
 
  에이전트 A (Streamable HTTP 옹호):
  - MCP SDK의 StreamableHTTPServerTransport 사용
  - 장점과 구현 방법을 구체적으로 제시
 
  에이전트 B (Express + 미들웨어 옹호):
  - @modelcontextprotocol/express 미들웨어 사용
  - 장점과 구현 방법을 구체적으로 제시
 
  두 결과를 비교해서 우리 프로젝트에 맞는 선택을 추천해줘."

커스텀 에이전트로 역할 고정하기

매번 프롬프트에 역할을 설명하는 대신, .claude/agents/에 정의해두면 재사용할 수 있다:

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: 코드 품질, 보안, 성능 관점에서 리뷰하는 시니어 리뷰어
model: sonnet
tools:
  - Read
  - Glob
  - Grep
---
 
당신은 시니어 코드 리뷰어입니다.
다음 관점에서 코드를 리뷰하세요:
 
1. 에러 처리: try/catch 누락, 에러 메시지 품질
2. 보안: 입력 검증, 인젝션 가능성, 키 노출
3. 성능: 불필요한 API 호출, N+1 패턴, 캐시 미스
 
리뷰 결과를 High/Medium/Low 심각도로 분류하세요.
<!-- .claude/agents/test-writer.md -->
---
name: test-writer
description: 테스트 코드를 작성하는 전문가
model: sonnet
tools:
  - Read
  - Write
  - Bash
  - Glob
---
 
당신은 테스트 전문가입니다.
테스트 작성 시 다음을 준수하세요:
 
1. 정상 케이스, 에러 케이스, edge case 최소 3가지
2. 모킹은 최소화하고 실제 동작 테스트 우선
3. 테스트명은 한글로 "~하면_~해야한다" 형식

사용법:

claude
 
> @code-reviewer weather-mcp-server의 src/index.ts를 리뷰해줘
> @test-writer get_current_weather 도구에 대한 테스트를 작성해줘

③ 실무 적용 시나리오 설계

시나리오 1: 스프린트 시작 — 요구사항 분석

새 스프린트에서 "날씨 알림 기능"을 개발해야 할 때:

오케스트레이터:
  ├─ 에이전트 A (조사): 기존 코드에서 관련 로직 탐색
  ├─ 에이전트 B (설계): API 설계 & 시퀀스 다이어그램 작성
  └─ 에이전트 C (추정): 작업 분해 & 시간 추정

프롬프트 예시:
> "다음 기능을 구현하기 위한 분석을 병렬로 진행해줘:
  '특정 도시의 기온이 임계값을 넘으면 알림을 보내는 기능'

  에이전트 1: 기존 코드에서 알림/이벤트 관련 코드가 있는지 탐색
  에이전트 2: 이 기능의 API 설계 초안 작성 (엔드포인트, 파라미터, 응답)
  에이전트 3: 작업을 세부 태스크로 분해하고 각각 시간 추정

  결과를 하나의 기획 문서로 통합해줘."

시나리오 2: 대규모 리팩토링

weather-mcp-server를 모듈별로 분리 리팩토링:

오케스트레이터:
  ├─ 에이전트 A: tools/ 폴더로 도구 핸들러 분리
  ├─ 에이전트 B: services/ 폴더로 API 클라이언트 분리
  └─ 에이전트 C: 분리 후 import 경로 수정 & 빌드 확인

프롬프트 예시:
> "weather-mcp-server를 아래 구조로 리팩토링해줘.
  서브 에이전트로 병렬 작업하되, 최종 빌드 확인은 마지막에:

  에이전트 1: src/tools/ 폴더를 만들고 각 도구 핸들러를 개별 파일로 분리
             (currentWeather.ts, forecast.ts, compare.ts, clothing.ts)

  에이전트 2: src/services/ 폴더를 만들고 geocode(), getWeather()를
             weatherService.ts로 분리

  두 작업 완료 후: src/index.ts에서 import 정리하고 npm run build 확인"

시나리오 3: 배포 전 검증

코드 변경 후 배포 전 종합 검증:

오케스트레이터:
  ├─ 에이전트 A: 코드 리뷰 (보안 + 품질)
  ├─ 에이전트 B: 빌드 & 테스트 실행
  └─ 에이전트 C: CHANGELOG 작성

프롬프트 예시:
> "배포 전 검증을 병렬로 진행해줘:

  에이전트 1: 최근 변경된 파일들을 코드 리뷰해줘 (보안, 에러 처리 중심)
  에이전트 2: npm run build && 모든 도구를 Inspector로 테스트해줘
  에이전트 3: git log --oneline -10을 보고 CHANGELOG.md를 작성해줘

  모두 통과하면 '배포 준비 완료' 보고서를 작성해줘."

멀티 에이전트 적용 판단 기준

모든 작업에 멀티 에이전트를 쓸 필요는 없다. 판단 기준:

멀티 에이전트가 적합한 경우:
  ✅ 작업을 독립적인 단위로 분리할 수 있다
  ✅ 병렬 처리로 시간을 줄일 수 있다
  ✅ 단일 컨텍스트로는 정보가 너무 많다
  ✅ 서로 다른 관점의 분석이 필요하다

단일 에이전트가 나은 경우:
  ❌ 작업이 순차적이고 매 단계 사람의 확인이 필요하다
  ❌ 같은 파일을 여러 에이전트가 동시에 수정해야 한다
  ❌ 작업이 단순해서 분리하면 오히려 오버헤드
  ❌ 토큰 비용을 최소화해야 한다 (멀티 에이전트는 토큰 소모 ↑)

실습 과제

과제 1: Fan-out/Fan-in 실습 (20분)

  1. weather-mcp-server 프로젝트에서 실습 1 실행
  2. 3개 서브 에이전트가 병렬로 실행되는지 확인
  3. 종합 보고서 품질 평가
  4. 단일 에이전트로 같은 작업 시 결과 비교

과제 2: 커스텀 에이전트 생성 (15분)

  1. .claude/agents/code-reviewer.md 작성
  2. .claude/agents/test-writer.md 작성
  3. @code-reviewer로 호출 테스트
  4. 일반 프롬프트 vs 커스텀 에이전트 결과 비교

과제 3: 실무 시나리오 설계 (15분)

  1. 자신의 실무에서 멀티 에이전트가 유용할 시나리오 3개 설계
  2. 각 시나리오의 패턴 선택 (Fan-out / 파이프라인 / 토론)
  3. 프롬프트 초안 작성
  4. 적용 판단 기준으로 타당성 검토

오늘의 핵심 정리

포인트설명
멀티 에이전트 목적컨텍스트 분리 + 병렬 처리 + 다관점 분석
3가지 패턴Fan-out/Fan-in, 파이프라인, 토론/검증
Task() 서브 에이전트별도 컨텍스트, 최대 10개 병렬, 결과만 메인에 반환
에이전트 간 데이터 전달직접 통신 불가, 파일을 통해 전달
커스텀 에이전트.claude/agents/에 역할 정의 → @이름으로 호출
Agent Teams실험적 기능, tmux 기반, 에이전트 간 메시지 가능
적용 판단독립 분리 가능 + 병렬 이득 있을 때만 사용
주의토큰 소모 ↑, 같은 파일 동시 수정 주의

참고 리소스

그래프 뷰

최근 게시글