멀티 에이전트 AI 코드 리뷰 오케스트레이션 아키텍처 패턴 가이드

┌─────────────────────────────────────────────────┐
│                 Orchestrator                     │
│  (PR 분석 → 에이전트 선택 → 결과 합성)            │
└──────────┬──────────┬──────────┬────────────────┘
           │          │          │
     ┌─────▼──┐ ┌─────▼──┐ ┌────▼───┐
     │ 보안   │ │ 성능   │ │ 스타일  │  ← Specialized Agents
     │ Agent  │ │ Agent  │ │ Agent  │     (병렬 실행)
     └─────┬──┘ └─────┬──┘ └────┬───┘
           │          │          │
     ┌─────▼──────────▼──────────▼────┐
     │       Verification Layer        │
     │  (허위 양성 필터링 + 심각도 랭킹)  │
     └────────────────────────────────┘

// ⚠️ 개념 예시 — 실제 API는 @modelcontextprotocol/sdk의 Client.callTool()을 사용합니다
// 참고: https://github.com/modelcontextprotocol/typescript-sdk
 
const securityAgent = {
  name: "security-reviewer",
  tools: [
    mcp.connect("semgrep-scanner"),    // Semgrep: SAST(정적 보안 분석) 도구
    mcp.connect("dependency-checker"), // 의존성 취약점 검사
  ],
  prompt: securityReviewPrompt,
};
 
const performanceAgent = {
  name: "performance-reviewer",
  tools: [
    mcp.connect("complexity-analyzer"), // 순환 복잡도 분석
    mcp.connect("benchmark-runner"),    // 벤치마크 실행
  ],
  prompt: performanceReviewPrompt,
};

// 오케스트레이터 — PR을 받아 전문 에이전트를 병렬 디스패치
async function orchestrateReview(pr: PullRequest): Promise<ReviewSummary> {
  // 1단계: PR 변경 범위 분석
  const analysisContext = await analyzeDiff(pr.diff);
 
  // 2단계: 변경 내용에 따라 필요한 에이전트 선택
  const agentsToDispatch = selectAgents(analysisContext);
  // e.g., 인증 관련 변경 → 보안 에이전트 포함
  // e.g., DB 쿼리 변경 → 성능 에이전트 포함
 
  // 3단계: Fan-Out — 선택된 에이전트를 병렬 실행
  const agentResults = await Promise.allSettled(
    agentsToDispatch.map(agent =>
      runWithTimeout(agent.review(analysisContext), 60_000)
    )
  );
  // runWithTimeout: Promise.race([task, timeout])으로 구현
  // AbortController로 타임아웃 시 정리까지 처리하는 유틸리티
 
  // 4단계: Fan-In — 결과 수집 및 실패한 에이전트 처리
  const findings = agentResults
    .filter(r => r.status === "fulfilled")
    .flatMap(r => r.value.findings);
 
  // 5단계: 검증 레이어 — 중복 제거 + 허위 양성 필터링 + 심각도 랭킹
  const verified = await verificationLayer(findings);
 
  return composeFinalReview(verified);
}

// 전문 에이전트 — 보안 리뷰어 예시
const securityAgent: ReviewAgent = {
  name: "security-reviewer",
  // 비용 최적화: 관련 변경이 있을 때만 활성화
  shouldActivate: (ctx) =>
    ctx.touchesAuth || ctx.touchesApi || ctx.modifiesDependencies,
 
  async review(ctx: AnalysisContext): Promise<AgentResult> {
    // Semgrep(OWASP Top 10 룰셋)으로 정적 분석 먼저 실행
    const semgrepResults = await mcp.invoke("semgrep-scanner", {
      files: ctx.changedFiles,
      ruleset: "owasp-top-10",
    });
 
    // LLM이 정적 분석 결과 + diff를 함께 분석
    const llmAnalysis = await llm.analyze({
      systemPrompt: SECURITY_REVIEW_PROMPT,
      context: {
        diff: ctx.diff,
        staticAnalysis: semgrepResults,
        threatModel: ctx.repoThreatModel,
      },
    });
 
    return { findings: [...semgrepResults, ...llmAnalysis] };
  },
};

# .github/workflows/ai-review.yml
name: AI Code Review Orchestration
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  # Sequential 1단계: 빠른 정적 분석 먼저 실행
  static-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run ESLint + TypeScript Check
        run: pnpm lint && pnpm tsc --noEmit
      - name: Run Semgrep Security Scan
        uses: semgrep/semgrep-action@v1
        with:
          config: p/owasp-top-ten
      - name: Upload analysis artifacts
        uses: actions/upload-artifact@v4
        with:
          name: static-analysis-results
          path: ./reports/
 
  # Sequential 2단계: 정적 분석 결과를 컨텍스트로 AI 리뷰 실행
  ai-review:
    needs: static-analysis
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download static analysis results
        uses: actions/download-artifact@v4
      - name: Run AI Review Orchestrator
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        # ⚠️ 아래 CLI는 가상의 도구입니다.
        # 실제로는 CodeRabbit GitHub App, Claude Code의 /review,
        # 또는 직접 구현한 스크립트를 사용하게 됩니다.
        run: |
          npx your-review-orchestrator \
            --pr ${{ github.event.pull_request.number }} \
            --static-results ./reports/ \
            --agents security,performance,style \
            --max-concurrency 3 \
            --severity-threshold medium
 
  # Sequential 3단계: 정책 검사 및 라우팅
  policy-check:
    needs: ai-review
    runs-on: ubuntu-latest
    steps:
      - name: Enforce ownership policy
        run: echo "CODEOWNERS 검증 및 리뷰어 자동 배정"
      - name: Route to human reviewer if needed
        run: echo "critical 이슈 발견 시 시니어 리뷰어에게 자동 라우팅"

async function verificationLayer(
  findings: Finding[]
): Promise<VerifiedFinding[]> {
  // 1. 중복 제거 — 같은 파일·같은 줄 범위를 지적하는 발견을 병합
  // (의미적 유사도가 아닌 위치 기반으로 먼저 처리하고,
  //  같은 위치의 다른 관심사 발견은 별도 유지)
  const deduplicated = deduplicateByLocation(findings);
 
  // 2. 교차 검증 — 별도 모델로 각 발견의 타당성 확인
  const crossValidated = await Promise.all(
    deduplicated.map(async (finding) => {
      const validation = await verifierModel.evaluate({
        finding: finding,
        surroundingCode: await getCodeContext(finding.location, 20),
        question: "이 발견이 실제 버그/이슈인가? 근거를 제시하라.",
      });
      return { ...finding, confidence: validation.confidence };
    })
  );
 
  // 3. 신뢰도 기반 필터링 — 낮은 신뢰도는 제외
  const filtered = crossValidated.filter(f => f.confidence > 0.7);
 
  // 4. 심각도 랭킹 — critical > high > medium 순 정렬
  return filtered.sort((a, b) => severityScore(b) - severityScore(a));
}