클로드 코드 다이나믹 워크플로우: Opus 4.8로 수백 개의 병렬 서브 에이전트 실행

Claude Opus 4.8은 Claude Code의 주요 기능인 동적 워크플로우(Dynamic Workflows)와 함께 출시되었습니다. 단일 세션에서 오케스트레이션 에이전트(orchestrating agent)는 수백 개의 병렬 서브에이전트(subagents)를 가동하여 여러 파일에 걸친 리팩토링, 광범위한 테스트 매트릭스 실행, 또는 여러 솔루션 경로를 동시에 탐색하는 등 크고 분기되는 작업을 처리할 수 있습니다. 터미널에서는 마법처럼 보이지만, 그 내부에서는 두 가지 구체적인 요소가 함께 작동합니다.

이 가이드는 동적 워크플로우가 실제로 어떻게 작동하는지, 언제 사용해야 하는지, 그리고 raw API를 통해 동일한 오케스트레이션 패턴을 구축하는 방법을 설명합니다. 모델 자체에 대한 내용은 Claude Opus 4.8이란 무엇인가를 참조하세요. 에이전트 아키텍처 배경에 대해서는 Claude Code 에이전트 하네스 분석을 함께 읽어보세요.

버튼

동적 워크플로우의 실제 작동 방식

Claude Code에서 동적 워크플로우는 노력 메뉴(effort menu)의 '울트라코드(ultracode)'라는 모드로 나타납니다. 여기서 이해해야 할 점은 울트라코드가 새로운 API 노력 수준(effort level)이 아니라는 것입니다. 이는 Opus 4.8에 이미 존재하는 두 가지 요소를 조합한 것입니다.

xhigh 노력 수준
대화 중간 시스템 메시지 (Mid-conversation system messages)

이들을 함께 사용하면 오케스트레이터 에이전트(orchestrator agent)는 큰 작업을 계획할 수 있는 추론 깊이와 작업이 진행됨에 따라 워커 에이전트(worker agents)를 시작할 수 있는 상시 권한을 모두 얻게 됩니다. 이것이 핵심 기술입니다. 나머지 모든 것은 Claude Code의 연결(wiring)입니다.

요소 1: xhigh 노력 수준

effort 매개변수는 Opus 4.8이 도구 호출(tool calls)을 포함하여 응답에 걸쳐 사용하는 토큰의 양을 제어합니다. xhigh는 Anthropic이 장기적인 코딩 및 에이전트(agentic) 작업을 위해 권장하는 수준입니다. 이는 수백만 토큰 예산으로 30분을 넘는 실행에 맞춰 조정됩니다.

동적 워크플로우의 경우, 오케스트레이터가 작업을 독립적인 단위로 분할하고, 얼마나 많은 워커를 생성할지 결정하며, 그 결과를 병합하는 등 실제 계획을 수행해야 하므로 이러한 깊이가 중요합니다. 낮은 노력 수준은 작업 범위를 축소하고 도구 호출 횟수를 줄이는데, 이는 오케스트레이터에게 필요한 것과는 반대입니다. xhigh를 실행할 때는 모델이 생각하고 조정할 공간을 가질 수 있도록 큰 max_tokens(64K가 합리적인 시작점)를 설정하세요.

요소 2: 대화 중간 시스템 메시지

이것이 전체를 가능하게 하는 새로운 Messages API 기능입니다. Opus 4.8 이전에는 시스템 프롬프트가 대화 시작 부분에 고정되어 있었습니다. 이제 messages 배열의 중간에 시스템 항목을 배치하여 작업 도중에 새로운 지침이나 권한을 주입할 수 있습니다.

이것이 오케스트레이터에게 대화가 시작된 후에 다중 에이전트 워크플로우를 시작할 수 있는 상시 권한을 부여하는 이유입니다. 미리 협상할 필요 없이 말이죠. Anthropic은 이 메커니즘을 대화 중간 시스템 메시지에서 설명합니다. 이는 작은 API 변경이지만, 에이전트가 실행 도중 발견한 것을 기반으로 기능을 얻을 수 있다는 큰 결과를 가져옵니다.

Claude Code에서 활성화하기

Claude Code에서 동적 워크플로우는 노력 메뉴의 울트라코드 옵션 뒤에 있습니다. 이 옵션을 선택하면 xhigh 노력 수준이 설정되고, 대화 중간 시스템 메시지를 통해 병렬 서브에이전트를 생성할 수 있는 세션 권한이 부여됩니다. 그 후에는 큰 작업을 설명하고 오케스트레이터가 이를 분산 처리하도록 할 수 있습니다.

몇 가지 사항이 자동으로 발생합니다:

Claude는 작업을 계획하고 분할 방법을 결정합니다.
작업을 여러 조각으로 나누어 각각 병렬 워커를 시작합니다.
결과가 스트리밍되어 메인 세션으로 병합됩니다.

Claude Code를 계획(plan)과 함께 설정했다면, Claude plan 설정 가이드가 포함된 Claude Agent SDK에서 관련 설정을 다룹니다.

동적 워크플로우를 사용해야 할 때 (그리고 사용하지 말아야 할 때)

동적 워크플로우는 광범위하고 병렬화 가능한 작업에서 빛을 발합니다.

여러 파일에 걸쳐 패턴을 한 번에 리팩토링할 때
대규모 테스트 매트릭스를 생성하고 실행할 때
여러 구현 접근 방식을 병렬로 탐색한 후 비교할 때
각 워커가 하나의 모듈을 담당하는 대규모 코드베이스 분석 시

이는 좁고 순차적인 작업에는 적합하지 않은 도구입니다. 단일 파일 변경을 위해 수백 개의 서브에이전트를 생성하는 것은 아무런 이득 없이 토큰을 소모하며, 각 단계가 이전 단계에 의존하는 경우에는 병렬 워커가 도움이 될 수 없습니다. 비용은 실제적입니다: 수백 개의 xhigh 서브에이전트는 수백만 개의 토큰을 의미합니다. 작업 형태에 맞게 패턴을 선택하세요.

API를 통해 동일한 기능 구축하기

오케스트레이션(orchestration)을 구축하는 데 Claude Code가 필요하지 않습니다. 동일한 두 가지 요소는 raw Messages API에서 사용할 수 있으며, Anthropic은 오케스트레이션 모드 구축에서 작동 예시를 제공합니다. 그 형태는 다음과 같습니다.

xhigh 노력 수준으로 작업을 계획하는 오케스트레이터 호출을 실행합니다.
대화 중간 시스템 메시지를 사용하여 오케스트레이터에게 워커를 파견할 권한을 부여합니다.
각 워커 호출을 하나의 작업 단위에 맞춰 병렬로 분산시킵니다.
결과를 수집하고 오케스트레이터에게 다시 전달하여 병합합니다.

import anthropic

client = anthropic.Anthropic()

orchestrator = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64000,
    output_config={"effort": "xhigh"},
    thinking={"type": "adaptive"},
    messages=[
        {"role": "user", "content": "Plan a refactor of the auth module across all 14 services."},
    ],
)

각 워커는 독립적인 Messages 호출이며, 작업 범위가 좁기 때문에 종종 더 낮은 노력 수준으로 동시에 실행할 수 있습니다. 이를 Anthropic의 호스팅 에이전트 인프라와 비교한다면, 관리형 에이전트 vs 에이전트 SDK 가이드에서 장단점을 설명합니다.

비용 및 제어

병렬 서브에이전트는 토큰 지출을 빠르게 증가시킵니다. xhigh 수준에서 각각 수만 개의 토큰을 사용하는 200개의 워커를 시작하는 동적 워크플로우는 상당한 비용이 발생합니다. 다음 세 가지 습관이 이를 합리적으로 유지하는 데 도움이 됩니다.

워커의 범위를 엄격하게 지정하고, 하위 작업이 허용하는 경우 medium 또는 low 노력 수준으로 실행합니다.
워커당 max_tokens를 제한하여 폭주하는 에이전트가 예산을 소진하지 않도록 합니다.
공유 컨텍스트를 캐싱하여 반복되는 시스템 프롬프트가 모든 워커에서 전체 요금으로 청구되지 않도록 합니다.

Opus 4.8 가격 분석은 노력 수준과 캐싱에 대한 계산을 포함하고 있습니다. 요약하자면: 오케스트레이션은 강력하지만, 비용은 에이전트 수에 비례하므로 병렬 처리는 신중한 선택으로 다루어야 합니다.

Apidog로 오케스트레이션 테스트하기

API를 통해 오케스트레이션을 구축할 때 디버그하기 어려운 부분은 팬아웃(fan-out)입니다. 즉, 워커가 올바른 범위의 컨텍스트를 받고 있는지, 응답이 병합 단계에서 예상하는 형태인지, 그리고 대화 중간 시스템 메시지가 올바르게 전달되는지 여부입니다. 200개의 실시간 워커 호출 후에 버그를 발견하고 싶지는 않을 것입니다.

Apidog를 사용하면 개별 구성 요소를 테스트할 수 있습니다.

오케스트레이터 요청을 저장하고, 어떤 것도 파견하기 전에 계획된 작업 분할을 검사합니다.
워커 엔드포인트를 모의(mock)하여 수백 개의 실제 호출에 토큰을 사용하지 않고도 팬아웃 및 병합 로직을 테스트할 수 있습니다.
워커 응답 형태에 대한 어설션(assertion)을 추가하여 불일치하는 페이로드(payload)가 확실히 실패하도록 합니다.
단일 워커 호출을 다양한 effort 수준에서 다시 실행하여 워커당 비용을 조정합니다.

Apidog를 다운로드하고, https://api.anthropic.com/v1/messages에 대해 오케스트레이터 및 워커 요청을 구축한 다음, 먼저 모의(mock) 환경에서 루프를 검증하세요. Opus 4.8 API 가이드에 시작할 기본 요청이 있습니다. 모의 환경에서 로직이 확고해지면 라이브 엔드포인트(live endpoint)로 전환하세요.

버튼

자주 묻는 질문

Claude Code의 동적 워크플로우(Dynamic Workflows)란 무엇인가요? 단일 세션에서 수백 개의 병렬 서브에이전트를 시작하여 크고 분기되는 작업을 처리할 수 있게 하는 기능입니다. Opus 4.8의 xhigh 노력 수준과 대화 중간 시스템 메시지를 통해 작동합니다.

울트라코드(ultracode)는 별도의 노력 수준인가요? 아닙니다. 울트라코드는 Claude Code에서 xhigh 노력 수준과 다중 에이전트 워크플로우를 시작할 수 있는 상시 권한이 결합된 것을 지칭하는 이름입니다. API 노력 수준은 여전히 low, medium, high, xhigh, max입니다.

대화 중간 시스템 메시지란 무엇인가요? Opus 4.8의 Messages API 변경 사항으로, 대화 중간에 시스템 항목을 배치하여 작업 도중에 새로운 지침이나 권한을 주입할 수 있게 합니다. 이는 오케스트레이터가 실행 시작 후에 워커를 생성할 수 있도록 하는 기능입니다.

Claude Code 없이 동적 워크플로우를 구축할 수 있나요? 네. raw Messages API에서 xhigh 노력 수준과 대화 중간 시스템 메시지를 사용하면 됩니다. Anthropic은 문서에서 작동하는 오케스트레이션 예시를 제공합니다.

동적 워크플로우는 비용이 많이 드나요? 그럴 수 있습니다. 수백 개의 xhigh 서브에이전트는 수백만 개의 토큰을 사용하게 됩니다. 워커의 범위를 엄격하게 지정하고, 가능한 경우 노력 수준을 낮추며, 공유 컨텍스트를 캐싱하여 비용을 제어하세요.

동적 워크플로우를 언제 피해야 하나요? 좁거나 엄격하게 순차적인 작업에서는 피해야 합니다. 각 단계가 이전 단계에 의존하는 경우 병렬 워커는 가치를 더하지 못하며, 작은 작업에서는 토큰을 낭비하게 됩니다.