AI 코딩 에이전트 실전 (4/5) — 멀티 에이전트 패턴: 오케스트레이터와 전문가 분리

-
AI 코딩 에이전트 실전 (4/5) — 멀티 에이전트 패턴: 오케스트레이터와 전문가 분리

한 LLM 세션이 모든 일을 다 하면 컨텍스트가 망가진다. 그래서 역할 분리가 필요해진다.

핵심 요약

  • 멀티 에이전트는 모델을 더 많이 쓰자가 아니라 컨텍스트를 분리하자는 설계
  • 1차 자료: Anthropic Claude Code subagents docs, OpenClaw·Hermes 운영 경험
  • 핵심 패턴 3가지: 오케스트레이터 + 전문가 / 파이프라인 / 협업
  • 비용은 단순 합산이 아니라 컨텍스트 절약 × 재시도 감소 = 전체적으로 더 싸지는 경우가 많음
  • 흔한 함정: 권한 누수, 컨텍스트 오염, 디버깅 곤란

1. 왜 한 에이전트로 다 하면 안 되는가

단일 LLM 세션이 모든 작업(설계 + 구현 + 테스트 + 리뷰 + 문서)을 다 하면 세 가지 문제가 생긴다:

  • 컨텍스트 오염: 한 작업의 디테일이 다른 작업의 판단을 흐린다. 디버깅 중 본 임시 코드가 PR 리뷰의 기준이 된다.
  • 컨텍스트 한도 초과: 200K 토큰도 무거운 작업이 누적되면 빠르게 찬다. 자동 압축은 결정의 근거를 깎아 낸다.
  • 권한 비대칭: 같은 세션이 발행 + 자격 정보 접근 + 코드 변경을 모두 갖는다. 한 실수가 광범위하다.

해결책: 작업 종류별로 에이전트를 분리하고, 위에서 한 명이 조정한다.

2. 오케스트레이터 + 전문가 분리 패턴

가장 많이 쓰는 토폴로지다.

        [오케스트레이터 = main]
            │
   ┌────────┼────────┬────────┐
   ▼        ▼        ▼        ▼
[코드 변경] [테스트] [리뷰] [문서화]
  executor   tester   reviewer  writer

오케스트레이터의 역할: - 작업을 받아 어느 전문가에게 보낼지 결정. - 전문가가 돌려준 결과를 간략히 흡수 (full output이 아니라 요약). - 다음 단계를 결정.

전문가의 역할: - 자기 전문 영역에서 깊게 일한다. - 결과를 정리된 형태(완료 보고)로 돌려준다 — 오케스트레이터의 컨텍스트를 보호.

핵심 원리: 오케스트레이터는 전체 그림을, 전문가는 깊이를 본다. 두 종류의 컨텍스트가 분리되어 누구도 과부하되지 않는다.

3. 토폴로지 3가지

3.1 수퍼바이저 (Hub-and-Spoke)

  • 위 그림처럼 한 명의 오케스트레이터 + N명의 전문가.
  • 단순·예측 가능. 디버깅이 쉽다.
  • 한계: 전문가끼리 직접 협업해야 할 때 매번 오케스트레이터를 거친다.

3.2 파이프라인 (직렬)

  • 전문가 A → B → C 순서로 결과를 넘긴다.
  • 데이터 변환·검증·발행 같은 단계 명확한 작업에 강하다.
  • 한계: 한 단계 실패가 전체를 막는다.

3.3 협업 (메시 / 합의)

  • 여러 전문가가 동시에 같은 입력을 보고 각자 답을 내고, 합의/투표로 결과를 정한다.
  • 코드 리뷰의 서로 다른 관점 (보안 / 성능 / 가독성)에 적합.
  • 비용이 가장 비싸다 — 같은 토큰을 N번 처리한다.

선택 룰: 작업이 명확한 단계면 파이프라인, 명확한 분업이면 수퍼바이저, 서로 다른 관점이 필요하면 협업.

4. Claude Code의 subagents — 실전 구현

Claude Code는 Agent 도구로 서브에이전트를 호출한다. subagent_type으로 전문가 타입을 지정하고, self-contained 프롬프트를 넘긴다.

프롬프트 작성 원칙 (실전에서 가장 많이 틀리는 곳): - 서브에이전트는 메인의 컨텍스트를 모른다. 따라서 무엇을 하는지·왜 하는지·이미 시도한 것을 모두 프롬프트에 넣는다. - 출력 형태를 명시한다: "200단어 이하 보고", "JSON 결과", "URL만 반환" 등. - 생각의 위임은 금지: "분석해서 결정해라"가 아니라 "X 파일 Y줄을 Z로 바꿔라" — 메인이 이해한 다음 위임한다.

병렬 vs 직렬: - 독립적인 N개 조사를 동시에 보낼 수 있다 (병렬). - 결과가 다음 단계에 의존하면 직렬로. - 병렬은 빠르지만 총 토큰 비용이 같거나 더 든다.

5. 비용 — 단순 합산이 아니다

"멀티 에이전트는 N배 비용"이라는 직관은 절반만 맞다.

더 비싸지는 요인: - 각 서브에이전트의 자체 컨텍스트 (CLAUDE.md, 룰, 도구 정의 등)가 매번 로드된다. - 오케스트레이터-전문가 메시지 왕복 자체가 토큰 소비.

더 싸지는 요인: - 메인의 컨텍스트가 가벼워져 압축이 덜 발생. 압축은 재요청을 부른다. - 전문가는 작은 모델(Haiku 등)로 돌려도 되는 경우가 많다 — 같은 모델을 쓸 필요 없다. - 재시도가 줄어든다 — 메인이 오염되면 결정 품질이 떨어져 작업 자체가 다시 돌아간다.

경험적 룰: 작업이 단순하고 1~2 step이면 단일 에이전트가 거의 항상 싸다. 5+ step 또는 전문성이 다른 단계가 섞이면 멀티가 종합 비용에서 유리해진다.

6. 흔한 함정 4가지

6.1 컨텍스트 오염 (cross-contamination)

  • 메인이 전문가의 전체 출력을 흡수해 메모리에 저장 → 오염.
  • 해결: 전문가는 요약 보고만 돌려주고 메인은 그 요약만 신뢰.

6.2 권한 누수

  • 모든 에이전트가 모든 도구를 갖는다 → 한 실수가 광범위.
  • 해결: 에이전트별 도구 화이트리스트. 발행은 지정 에이전트만.

6.3 디버깅 곤란

  • "어느 에이전트가 어디서 잘못했는가"가 추적 어렵다.
  • 해결: 모든 에이전트 호출에 correlation ID + 결과 요약을 로그한다. 세션 종료 시 별도 파일로 보존.

6.4 오버 엔지니어링

  • 단순 작업에 멀티를 끼워 넣음.
  • 해결: 3+ step 작업이라는 진입 룰. 그 미만은 단일 에이전트 + 자체 검증.

7. 한눈에 정리

패턴 적합한 상황 강점 약점
오케스트레이터 + 전문가 (수퍼바이저) 명확한 분업 단순, 디버깅 쉬움 전문가 간 직접 통신 어려움
파이프라인 단계 명확 결과 추적성 한 단계 실패 = 전체 정지
협업 (메시/합의) 서로 다른 관점 필요 다양성 가장 비쌈
단일 에이전트 ≤2 step 작업 가장 싼 컨텍스트 오염 위험

설계 룰: 작업 종류가 분리되면 에이전트도 분리, 그렇지 않으면 단일이 답.

다음 편

다음 편(5/5)은 코딩 에이전트 비용 관리 — 토큰·캐싱·라우팅이다. 멀티 에이전트가 구조 분리라면, 다음 편은 비용 분리다.

참고 자료

  • Anthropic, Subagents in Claude Code — code.claude.com/docs/agents (2026-05-05 확인).
  • Anthropic, Multi-Agent Research System — anthropic.com/research/built-multi-agent-research-system (2026-05-05 확인).
  • 시리즈 4편(하네스 엔지니어링이란) — 멀티 에이전트의 이론적 배경.

이 글은 AI 코딩 에이전트 실전 시리즈의 4/5 편입니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »