서브에이전트 오케스트레이션 | 클로드 코드 완벽 마스터: AI 개발 워크플로우

서브에이전트 오케스트레이션 — 팀처럼 일하기

단일 Claude 세션으로 처리하기 어려운 작업이 있습니다. "전체 코드베이스 i18n 번역 추가", "모든 API 엔드포인트 보안 감사", "50개 컴포넌트 접근성 개선" — 이런 작업들은 범위가 너무 커서 하나의 컨텍스트 윈도우에 담기 어렵습니다. 서브에이전트 오케스트레이션은 이 문제를 해결합니다. 하나의 메인 에이전트가 여러 전문 서브에이전트를 생성하고, 각자 독립 컨텍스트에서 작업한 결과를 취합하는 방식입니다.

오케스트레이션 기본 구조

# 메인 세션에서 오케스트레이터 역할 지시
"다음 대규모 작업을 서브에이전트를 활용해서 처리해줘.
 각 서브에이전트는 독립 컨텍스트에서 실행됨을 인지해줘.

 작업: messages/ 디렉토리의 en.json, ja.json에 누락된 번역 키 추가
 
 오케스트레이션 계획:
 1. 서브에이전트 A: ko.json 분석 → 전체 키 목록 추출
 2. 서브에이전트 B: en.json 분석 → 누락 키 목록 생성 (A 결과 기반)
 3. 서브에이전트 C: ja.json 분석 → 누락 키 목록 생성 (A 결과 기반)
 4. 서브에이전트 D: en.json 누락 키 번역 추가
 5. 서브에이전트 E: ja.json 누락 키 번역 추가
 
 B와 C는 병렬 실행 가능. D와 E는 B·C 완료 후 순차 실행."

병렬 실행 가능 vs 순차 실행 필수

# 병렬 실행 가능 — 독립적인 작업
Agent({ description: "auth 모듈 타입 오류 수정", prompt: "app/actions/auth.ts 타입 오류 모두 수정..." })
Agent({ description: "jobs 모듈 타입 오류 수정", prompt: "app/actions/jobs.ts 타입 오류 모두 수정..." })
Agent({ description: "profile 모듈 타입 오류 수정", prompt: "app/actions/profile.ts 타입 오류 모두 수정..." })

# 순차 실행 필수 — 의존성 있는 작업
# 1. DB 스키마 변경
Agent({ description: "마이그레이션 생성", prompt: "notifications 테이블 마이그레이션 파일 생성..." })
# 2. 타입 재생성 (마이그레이션 완료 후)
Agent({ description: "TS 타입 갱신", prompt: "supabase gen types typescript 실행..." })
# 3. 컴포넌트 업데이트 (타입 갱신 후)
Agent({ description: "컴포넌트 업데이트", prompt: "새 notifications 타입 사용하도록 컴포넌트 수정..." })

자기완결적 서브에이전트 프롬프트 작성

서브에이전트는 부모 세션의 대화를 모릅니다. 프롬프트 안에 모든 컨텍스트를 담아야 합니다.

# ❌ 실패하는 프롬프트
Agent({
  prompt: "아까 얘기한 대로 결제 모듈 구현해줘"
  // 서브에이전트는 "아까 얘기"가 뭔지 모름
})

# ✅ 성공하는 프롬프트
Agent({
  description: "결제 Server Action 구현",
  prompt: `
    **프로젝트**: Next.js 16 App Router + Supabase + TypeScript
    **작업**: 결제 Server Action 구현
    
    **구현할 파일**: app/actions/payment.ts
    **참조 파일**: 
      - app/actions/auth.ts (인증 패턴 참고)
      - types/supabase.ts (DB 타입)
    
    **요구사항**:
    - createPayment(orderId: string, amount: number) 함수
    - Toss Payments API 연동 (TOSS_SECRET_KEY 환경변수)
    - 성공: { success: true, paymentKey: string }
    - 실패: { success: false, message: string }
    - supabase/migrations/ 에 payments 테이블 마이그레이션 파일 생성
    
    **완료 조건**: npx tsc --noEmit 타입 오류 없음
  `
})

결과 취합과 검증

"5개 서브에이전트 작업이 완료됐어.
 이제 전체 결과를 통합 검증해줘:
 
 1. npm run build — 빌드 오류 없는지
 2. npx tsc --noEmit — 타입 충돌 없는지
 3. 각 에이전트가 생성한 파일 목록 확인
 4. 파일 간 import 오류 없는지
 5. 최종 요약: 완료된 작업, 발견된 문제, 권장 후속 조치"

Worktree 격리 — 브랜치 충돌 방지

# 여러 에이전트가 같은 저장소에서 동시에 작업할 때
Agent({
  description: "결제 모듈",
  isolation: "worktree",  // 별도 git worktree에서 작업
  prompt: "feature/payment 브랜치에서 결제 기능 구현..."
})
Agent({
  description: "알림 모듈",
  isolation: "worktree",  // 별도 git worktree에서 작업
  prompt: "feature/notification 브랜치에서 알림 기능 구현..."
})
# 각 에이전트가 다른 브랜치에서 작업 → 충돌 없음
# 완료 후 메인이 각 브랜치를 순차 merge

실전: 전체 사이트 접근성 감사

"사이트 전체 접근성(a11y) 감사를 서브에이전트로 분산해서 해줘.

 디렉토리별로 서브에이전트 할당:
 - 서브에이전트 1: app/[locale]/ 공개 페이지
 - 서브에이전트 2: app/admin/ 어드민 페이지
 - 서브에이전트 3: components/ 공통 컴포넌트

 각 에이전트 체크 항목:
 - img 태그 alt 텍스트
 - 버튼/링크 접근 가능한 이름
 - 폼 라벨 연결
 - 색상 대비 (클래스 기준)
 
 결과를 accessibility-report.md 하나로 취합해줘."

서브에이전트 오케스트레이션의 핵심 가치는 "병렬 처리"만이 아닙니다. 각 에이전트가 독립된 컨텍스트에서 특정 영역에만 집중하기 때문에 품질이 높아집니다. 모든 것을 아는 제너럴리스트 하나보다, 각 도메인에 집중하는 스페셜리스트 여럿이 대규모 작업에서 더 좋은 결과를 냅니다.

핵심 정리

서브에이전트는 독립 컨텍스트 — 프롬프트에 프로젝트 스택·참조 파일·완료 조건 등 모든 정보 자기완결적으로 포함
독립 작업은 병렬, 의존 작업은 순차 — worktree isolation으로 브랜치 충돌 없이 동시 기능 개발
오케스트레이터는 분배·취합·검증 담당 — 서브에이전트 완료 후 빌드·타입 체크로 통합 검증 필수

관련 검색어 · 클로드 코드 서브에이전트 · AI 오케스트레이션 · Claude Code 병렬 작업 · 클로드 코드 완벽 마스터 · 에이전트 분산 처리