Claude Code Dynamic Workflows 실전 — 병렬 서브에이전트로 대규모 리팩토링 하는 법

직접 오케스트레이션 코드 짜던 시대는 끝났습니다. Opus 4.8이 알아서 씁니다.

---

핵심 요약

→ Dynamic Workflows = Claude Code가 오케스트레이션 스크립트를 직접 작성 → 수백 개 서브에이전트 병렬 실행
→ 서브에이전트 최대 동시 실행 16개, 세션당 총 1,000개 상한
→ 결과는 테스트 스위트로 검증 후 최종 답변만 메인 세션에 반환 — 컨텍스트 오염 없음
→ Max / Team 플랜 기본 활성화, Enterprise는 어드민 수동 활성화
→ Research Preview 단계 — API에서도 사용 가능
→ Mid-conversation system messages 기술이 기반 — 오케스트레이터가 서브에이전트에 실시간 권한 부여
→ 비용 폭발 위험 있음 — 서브에이전트 수 제한 + 테스트 게이트 필수
→ 독립적으로 처리 가능한 작업에만 적합 (출력이 서로 의존하는 작업은 ❌)

---

실전 1 — Dynamic Workflows가 기존 서브에이전트와 뭐가 다른가

Opus 4.7까지의 멀티에이전트는 개발자가 직접 오케스트레이션 코드를 작성해야 했습니다. 어떤 서브에이전트를 만들지, 어떤 작업을 배분할지, 결과를 어떻게 합칠지 전부 수동이었습니다.

Dynamic Workflows는 이 구조가 바뀝니다.

# 기존 방식 (Opus 4.7까지)
개발자 → 오케스트레이션 코드 작성 → 서브에이전트 수동 정의 → 태스크 배분

# Dynamic Workflows (Opus 4.8)
개발자 → 자연어 지시 → Claude가 오케스트레이션 스크립트 작성 → 병렬 서브에이전트 자동 실행

내부 동작 구조는 두 가지로 구성됩니다.

① 오케스트레이션 스크립트 자동 작성 Claude가 태스크를 분석해 JS 오케스트레이션 스크립트를 직접 작성합니다. 실행 계획은 스크립트 변수에 저장 — Claude의 컨텍스트 윈도우를 차지하지 않습니다.

② Mid-conversation system messages Opus 4.8의 새 API 기능입니다. 오케스트레이터가 대화 중간에 서브에이전트에게 실시간으로 권한과 지시를 주입할 수 있습니다. 기존엔 시스템 프롬프트가 대화 시작 시 고정이었지만, 이제 태스크 진행 중에도 업데이트 가능합니다.

# Mid-conversation system messages API 예시
messages = [
    {"role": "user", "content": "레포지토리 전체 Python 2→3 마이그레이션 시작해"},
    {"role": "assistant", "content": "...분석 완료, 서브태스크 87개 식별..."},
    # 여기서 새 시스템 메시지 삽입 — 프롬프트 캐시 유지
    {"role": "system", "content": "하위 에이전트에 파일 쓰기 권한 부여. 테스트 실패 시 자동 롤백."},
    {"role": "user", "content": "계속 진행해"}
]

구조 이해 박스 Dynamic Workflows의 핵심은 "계획 → 분산 → 검증 → 통합" 4단계입니다.

1. 계획: Claude가 전체 태스크를 독립 서브태스크로 분해
2. 분산: 최대 16개 동시, 총 1,000개까지 병렬 실행
3. 검증: 각 서브에이전트 출력을 테스트 스위트로 검증
4. 통합: 검증 통과한 결과만 메인 세션에 반환

---

실전 2 — Claude Code에서 실제로 쓰는 법

Claude Code에서 Dynamic Workflows는 별도 명령어 없이 자연어 요청만으로 트리거됩니다. 규모가 크고 병렬화 가능한 작업을 요청하면 Claude가 자동 판단합니다.

# Claude Code 터미널에서

# 예시 1: 레포지토리 전체 마이그레이션
> Python 2 코드를 전부 Python 3으로 마이그레이션해줘. 
  테스트 통과한 파일만 커밋해.

# 예시 2: 대규모 리팩토링
> 이 레포지토리의 모든 컴포넌트에서 deprecated된 API 호출 찾아서 
  최신 버전으로 교체해줘.

# 예시 3: 병렬 코드 리뷰
> 전체 PR 변경사항을 보안 취약점, 성능, 코드 품질 3개 관점에서 
  동시에 검토해줘.

Dynamic Workflows가 시작되면 Claude Code 세션은 블로킹되지 않습니다. 서브에이전트들이 백그라운드에서 실행되고, 완료된 결과만 메인 세션으로 돌아옵니다.

# 진행 상황 확인
> 현재 몇 개 서브에이전트 실행 중이야?

# 중간 체크포인트 저장 — 재개 가능
> 지금까지 완료된 파일 저장하고 나머지는 나중에 계속해줘.

# 특정 서브태스크 우선순위 조정
> 인증 관련 파일 먼저 처리해줘.

---

실전 3 — 비용 폭발 막는 방법

Dynamic Workflows는 수백 개 서브에이전트를 동시 실행하는 만큼 토큰 소비가 급격히 증가합니다. 아무 설정 없이 돌리면 예산을 순식간에 소진할 수 있습니다.

# 비용 제어 3가지 레버

# 1. 서브에이전트 모델 티어링
#    오케스트레이터: Opus 4.8 (복잡한 계획 수립)
#    서브에이전트: Haiku 4.5 또는 Sonnet 4.6 (단순 실행)
#    → 비용 구조 대폭 개선 가능

# 2. 병렬 실행 상한 설정
#    기본 최대: 16 동시 / 1,000 총합
#    → 소규모 테스트: 먼저 5개 서브에이전트로 스코프 제한

# 3. 테스트 게이트 필수
#    서브에이전트 출력이 테스트를 통과해야만 다음 단계로 진행
#    → 잘못된 결과가 연쇄 확산되는 비용 차단

# 실제 비용 스케일 추정 예시
일반 Claude Code 세션 1회: ~5,000~20,000 토큰
Dynamic Workflows (서브에이전트 50개): ~500,000~2,000,000 토큰

→ 먼저 작은 스코프(파일 10개)로 테스트
→ 비용 확인 후 전체 레포로 확장

---

실전 4 — 쓰면 안 되는 케이스

Dynamic Workflows가 항상 정답은 아닙니다.

✅ 적합한 케이스
- 파일 단위 독립 처리 (각 파일이 서로 의존하지 않음)
- 대규모 마이그레이션 (Python 2→3, API 버전업)
- 병렬 코드 리뷰 (보안/성능/품질 동시 검토)
- 수백 개 테스트 케이스 병렬 생성

❌ 부적합한 케이스
- 출력이 순서에 의존하는 작업 (A 완료 후 B 시작)
- DB 스키마 변경처럼 전역 상태를 건드리는 작업
- 소규모 단일 파일 수정 (오버헤드가 이득보다 큼)
- 실시간 사용자 응답이 필요한 인터랙티브 작업

---

마무리

✅ Dynamic Workflows는 오케스트레이션 코드 작성 부담을 Claude가 대신 처리합니다.
✅ 동시 16개 / 총 1,000개 서브에이전트, 테스트 검증 후 결과 반환 구조입니다.
✅ Max / Team은 기본 활성화, Enterprise는 어드민 수동 활성화가 필요합니다.
❌ 토큰 소비가 기하급수적으로 증가하므로 소규모 스코프 테스트 먼저 필수입니다.
❌ 서로 의존성 있는 작업에는 효과 없고 오히려 비용만 증가합니다.

---

관련 글

• Claude Opus 4.8 Fast Mode 완전 분석