Claude Code로 대형 오픈소스 분석하기 - 멀티에이전트 접근법

문제: 컨텍스트가 커지면 퀄리티가 떨어진다

OpenTelemetry Collector 같은 대형 프로젝트를 분석할 때 한 세션에서 전부 처리하려고 하면 문제가 생긴다.

LLM은 컨텍스트 윈도우 안에서 처리하는 정보가 많아질수록 집중도가 떨어지고, 분석 퀄리티도 함께 낮아진다. 소스가 클수록 "전체를 다 보여주는" 방식은 오히려 역효과다.

[X] 한 세션에서 전부 처리
소스 전체 → [단일 에이전트] → 퀄리티 낮은 분석

[O] 멀티에이전트
소스 전체 → 파트 분할 → [스페셜리스트 A] → 검토/검증
                       → [스페셜리스트 B] → 검토/검증  → 최종 합성
                       → [스페셜리스트 C] → 검토/검증

핵심 원칙은 단순하다. 좁은 컨텍스트 = 깊은 분석

---

접근법: 오케스트레이터 + 스페셜리스트

구조

오케스트레이터 (메인 세션)
  ├── 전체 구조 파악 및 분석 단위 확정
  ├── 서브에이전트들에게 파트 위임
  ├── 결과 검토 및 cross-cutting 검증
  └── 최종 합성
       ↑
스페셜리스트 에이전트들 (병렬 실행)
  ├── Agent A: 핵심 인터페이스 담당
  ├── Agent B: 데이터 수집/전송 담당
  ├── Agent C: 데이터 처리/라우팅 담당
  ├── Agent D: 서비스/확장 담당
  └── Agent E: 설정/인프라 담당

역할 분리

역할	담당	컨텍스트 범위
오케스트레이터	구조 파악, 위임, 검증, 합성	전체 (얕게)
스페셜리스트	담당 파트 심층 분석	부분 (깊게)

오케스트레이터는 깊이 파지 않는다. 스페셜리스트가 가져온 결과를 검토하고 검증하고 보완 요청하는 게 주 역할이다.

---

OpenTelemetry Collector에 적용

프로젝트 구조

OpenTelemetry Collector는 멀티모듈 Go 프로젝트로, 컴포넌트 경계가 명확하게 디렉토리로 나뉘어 있어 에이전트 분할에 적합하다.

opentelemetry-collector/
├── component/      # 핵심 인터페이스
├── pdata/          # 텔레메트리 데이터 모델
├── pipeline/       # 파이프라인 시그널 타입
├── consumer/       # 컨슈머 인터페이스
├── receiver/       # 데이터 수집
├── exporter/       # 데이터 전송
├── processor/      # 데이터 처리
├── connector/      # 파이프라인 라우팅
├── extension/      # 확장 기능
├── service/        # 서비스 오케스트레이션
├── otelcol/        # 메인 바이너리
├── confmap/        # 설정 처리
├── featuregate/    # 피처 플래그
└── internal/       # 내부 유틸리티

에이전트 분할 (5개)

에이전트	담당 디렉토리	분석 포인트
Core	component, pdata, pipeline, consumer	핵심 인터페이스, 데이터 모델, 의존성 방향
Receiver/Exporter	receiver, exporter	수집/전송 인터페이스, 구현체 패턴, helper 구조
Processor/Connector	processor, connector	데이터 변환 로직, 라우팅 메커니즘
Service	extension, service, otelcol	라이프사이클 관리, 파이프라인 조립, 진입점
Infra	confmap, featuregate, filter, scraper, internal	설정 해석, 피처 플래그, 공통 유틸리티

---

구현: Claude Code Agent 툴

Claude Code에서 이 패턴은 별도 인프라 없이 내장 Agent 툴만으로 구현된다.

병렬 실행

# 메인 세션에서 여러 서브에이전트를 한 번에 호출
Agent(subagent_type="Explore", prompt="Core 분석: component, pdata...")
Agent(subagent_type="Explore", prompt="Receiver/Exporter 분석: receiver, exporter...")
Agent(subagent_type="Explore", prompt="Processor/Connector 분석: processor, connector...")
# → 병렬로 실행, 결과가 메인 세션으로 반환

결과 흐름

스페셜리스트 결과 반환
    ↓
오케스트레이터가 검토
    ↓
cross-cutting concerns 교차 검증
    ↓
누락 부분 보완 요청 (필요시 추가 에이전트 실행)
    ↓
최종 합성

---

프롬프트 설계 원칙

각 스페셜리스트 프롬프트에 반드시 포함해야 할 것:

1. 담당 범위 명시 - 어떤 디렉토리/패키지만 볼 것인지
2. 분석 포인트 - 인터페이스, 의존성, 핵심 로직 중 무엇에 집중할지
3. 결과 형식 - 오케스트레이터가 검토하기 좋은 구조화된 포맷
4. 경계 명시 - 다른 에이전트 담당 영역은 깊이 들어가지 않도록

오케스트레이터 프롬프트에 반드시 포함해야 할 것:

1. cross-cutting 체크리스트 - 각 에이전트 결과 간 연결 포인트
2. 검증 기준 - 누락/모순 여부 판단 기준
3. 보완 요청 조건 - 어떤 경우에 추가 분석을 요청할지

---

마치며

이 접근법의 핵심은 컨텍스트 관리다. LLM에게 많은 정보를 한꺼번에 주는 것보다, 적절히 쪼개서 각자 깊이 파게 하고 메인이 검증하는 구조가 실제로 더 나은 결과를 만든다.

대형 오픈소스 프로젝트 분석뿐 아니라, 복잡한 버그 디버깅이나 아키텍처 리뷰에도 같은 패턴을 적용할 수 있다.