Claude Opus 4.8은 Claude Code의 주요 기능인 동적 워크플로우(Dynamic Workflows)와 함께 출시되었습니다. 단일 세션에서 오케스트레이션 에이전트(orchestrating agent)는 수백 개의 병렬 서브에이전트(subagents)를 가동해 여러 파일 리팩토링, 대규모 테스트 매트릭스 실행, 여러 솔루션 경로 탐색처럼 크고 분기되는 작업을 처리할 수 있습니다.
이 글에서는 동적 워크플로우가 실제로 어떻게 작동하는지, 언제 사용해야 하는지, 그리고 raw API로 같은 오케스트레이션 패턴을 구현하는 방법을 단계별로 정리합니다. 모델 자체에 대한 내용은 Claude Opus 4.8이란 무엇인가를 참조하세요. 에이전트 아키텍처 배경은 Claude Code 에이전트 하네스 분석에서 확인할 수 있습니다.
동적 워크플로우의 실제 작동 방식
Claude Code에서 동적 워크플로우는 노력 메뉴(effort menu)의 ultracode 모드로 제공됩니다. 여기서 중요한 점은 ultracode가 새로운 API 노력 수준(effort level)이 아니라는 것입니다.
실제로는 Opus 4.8의 두 가지 기능을 조합한 실행 모드입니다.
-
xhigh노력 수준 - 대화 중간 시스템 메시지(Mid-conversation system messages)
이 조합을 사용하면 오케스트레이터 에이전트는 다음을 수행할 수 있습니다.
- 큰 작업을 하위 작업으로 분해
- 병렬 실행이 가능한 작업 단위 식별
- 필요한 수만큼 워커 에이전트 생성
- 각 워커의 결과를 수집
- 최종 결과로 병합
즉, 핵심은 “더 깊게 계획할 수 있는 모델 설정”과 “실행 중 새 권한을 주입할 수 있는 메시지 구조”입니다. 나머지는 Claude Code가 이를 어떻게 연결하느냐의 문제입니다.
요소 1: xhigh 노력 수준
effort 매개변수는 Opus 4.8이 응답과 도구 호출(tool calls)에 사용할 추론 토큰 양을 제어합니다.
xhigh는 Anthropic이 장기적인 코딩 및 에이전트(agentic) 작업에 권장하는 수준입니다. 수백만 토큰 예산과 30분을 넘는 실행을 전제로 조정되어 있습니다.
동적 워크플로우에서 xhigh가 필요한 이유는 오케스트레이터가 단순 응답이 아니라 실제 실행 계획을 만들어야 하기 때문입니다.
예를 들어 오케스트레이터는 다음 판단을 해야 합니다.
- 작업을 어떤 단위로 나눌 것인가
- 어떤 작업은 병렬 실행하고 어떤 작업은 순차 실행할 것인가
- 몇 개의 워커를 생성할 것인가
- 각 워커에게 어떤 컨텍스트를 줄 것인가
- 결과 충돌을 어떻게 병합할 것인가
낮은 노력 수준은 작업 범위를 축소하고 도구 호출 수를 줄이는 경향이 있습니다. 이는 오케스트레이터에게 필요한 동작과 반대입니다.
실무에서는 오케스트레이터 호출에 큰 max_tokens 값을 함께 설정하세요. 64K는 합리적인 시작점입니다.
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."
}
],
)
요소 2: 대화 중간 시스템 메시지
대화 중간 시스템 메시지는 Opus 4.8의 Messages API에서 동적 워크플로우를 가능하게 하는 핵심 기능입니다.
Opus 4.8 이전에는 시스템 프롬프트가 대화 시작 부분에 고정되어 있었습니다. 이제는 messages 배열 중간에 시스템 항목을 배치해 작업 도중 새로운 지침이나 권한을 주입할 수 있습니다.
이 기능을 사용하면 오케스트레이터는 대화가 시작된 뒤에도 다음과 같은 권한을 받을 수 있습니다.
- 워커 에이전트 생성
- 하위 작업 위임
- 병렬 실행 계획 변경
- 새로 발견한 정보를 기반으로 실행 방식 조정
Anthropic은 이 메커니즘을 대화 중간 시스템 메시지 문서에서 설명합니다.
API 변경은 작지만 효과는 큽니다. 에이전트가 실행 중 발견한 내용을 기준으로 새로운 기능이나 권한을 얻을 수 있기 때문입니다.
Claude Code에서 활성화하기
Claude Code에서는 노력 메뉴에서 ultracode 옵션을 선택하면 됩니다.
이 옵션을 선택하면 다음이 함께 설정됩니다.
-
xhigh노력 수준 - 대화 중간 시스템 메시지를 통한 병렬 서브에이전트 생성 권한
사용 흐름은 간단합니다.
- Claude Code에서 노력 메뉴를 엽니다.
-
ultracode를 선택합니다. - 큰 작업을 구체적으로 설명합니다.
- Claude가 작업을 나누고 병렬 워커를 실행하도록 둡니다.
- 스트리밍되는 결과를 확인하고 최종 병합 결과를 검토합니다.
예시 프롬프트:
이 저장소의 인증 모듈을 14개 서비스 전체에서 리팩토링해 주세요.
요구사항:
- 기존 public API는 유지
- 중복된 토큰 검증 로직 제거
- 각 서비스의 테스트 업데이트
- 변경 파일과 리스크를 마지막에 요약
Claude Code는 내부적으로 다음을 수행합니다.
- 작업 계획 수립
- 하위 작업 분할
- 병렬 워커 실행
- 결과 수집
- 메인 세션으로 병합
Claude Code를 plan과 함께 설정했다면 Claude plan 설정 가이드가 포함된 Claude Agent SDK도 참고하세요.
동적 워크플로우를 사용해야 할 때
동적 워크플로우는 “넓고 병렬화 가능한 작업”에 적합합니다.
대표적인 사용 사례는 다음과 같습니다.
- 여러 파일에 걸친 동일 패턴 리팩토링
- 대규모 테스트 매트릭스 생성 및 실행
- 여러 구현 접근 방식의 병렬 탐색
- 대규모 코드베이스 분석
- 각 워커가 하나의 모듈이나 서비스만 담당하는 작업
예를 들어 다음과 같은 작업은 좋은 후보입니다.
전체 monorepo에서 deprecated API 사용 지점을 찾아 새 API로 마이그레이션해 주세요.
작업 방식:
- 패키지별로 독립적으로 분석
- 변경 전후 diff 요약
- 테스트가 필요한 패키지 목록 작성
- 충돌 가능성이 있는 변경은 별도 표시
이런 작업은 여러 패키지나 파일을 독립적으로 분석할 수 있으므로 병렬 워커가 효과적입니다.
동적 워크플로우를 피해야 할 때
반대로 좁고 순차적인 작업에는 적합하지 않습니다.
피해야 할 예시는 다음과 같습니다.
- 단일 파일의 작은 버그 수정
- 한 단계 결과가 다음 단계 입력으로 반드시 필요한 작업
- 간단한 코드 설명 요청
- 작은 함수 하나의 리팩토링
- 병렬화할 수 없는 디버깅 절차
예를 들어 다음 작업에 수백 개의 서브에이전트를 생성하는 것은 비효율적입니다.
이 함수에서 null 체크 하나를 추가해 주세요.
이 경우 병렬 실행으로 얻는 이점은 거의 없고 토큰 비용만 증가합니다.
비용도 중요합니다. 수백 개의 xhigh 서브에이전트는 수백만 개의 토큰을 사용할 수 있습니다. 작업의 형태가 병렬 처리에 맞는지 먼저 판단하세요.
API를 통해 동일한 기능 구축하기
Claude Code 없이도 같은 오케스트레이션 패턴을 raw Messages API로 구현할 수 있습니다.
Anthropic은 오케스트레이션 모드 구축 문서에서 작동 예시를 제공합니다.
기본 구조는 다음과 같습니다.
-
xhigh노력 수준으로 오케스트레이터 호출 실행 - 대화 중간 시스템 메시지로 워커 파견 권한 부여
- 각 워커 호출을 독립 작업 단위로 병렬 실행
- 워커 결과를 수집
- 오케스트레이터에게 다시 전달해 병합
1단계: 오케스트레이터로 작업 계획 생성
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."
},
],
)
이 호출의 목표는 코드를 바로 변경하는 것이 아니라 실행 가능한 작업 분해 계획을 얻는 것입니다.
계획 결과에는 다음 정보가 포함되도록 요청하는 것이 좋습니다.
각 하위 작업에 대해 다음 형식으로 출력하세요.
- task_id
- 대상 서비스 또는 파일 범위
- 필요한 컨텍스트
- 예상 변경 유형
- 병렬 실행 가능 여부
- 병합 시 주의할 점
2단계: 워커 호출을 병렬 실행
각 워커는 독립적인 Messages 호출입니다. 워커는 좁은 범위의 작업만 처리하므로 항상 xhigh일 필요는 없습니다.
하위 작업이 단순 분석이나 제한된 파일 변경이라면 medium 또는 low 노력 수준으로 시작할 수 있습니다.
def run_worker(task):
return client.messages.create(
model="claude-opus-4-8",
max_tokens=12000,
output_config={"effort": "medium"},
messages=[
{
"role": "system",
"content": "You are a focused worker agent. Only solve the assigned subtask."
},
{
"role": "user",
"content": f"""
Task ID: {task["task_id"]}
Scope: {task["scope"]}
Instructions: {task["instructions"]}
Return:
- summary
- changed_files
- risks
- test_recommendations
"""
}
],
)
3단계: 결과 병합
워커 결과를 그대로 사용하지 말고 오케스트레이터에게 다시 전달해 충돌, 중복, 누락을 확인하게 합니다.
merge = client.messages.create(
model="claude-opus-4-8",
max_tokens=32000,
output_config={"effort": "xhigh"},
messages=[
{
"role": "user",
"content": f"""
Merge these worker results into a single final refactor plan.
Worker results:
{worker_results}
Check:
- conflicting recommendations
- duplicated changes
- missing services
- test coverage gaps
- final execution order
"""
}
],
)
Anthropic의 호스팅 에이전트 인프라와 비교하려면 관리형 에이전트 vs 에이전트 SDK 가이드를 참고하세요.
비용 및 제어
병렬 서브에이전트는 토큰 사용량을 빠르게 늘립니다.
예를 들어 xhigh 수준의 워커 200개가 각각 수만 토큰을 사용하면 전체 비용은 크게 증가할 수 있습니다. 따라서 동적 워크플로우를 구현할 때는 처음부터 제어 장치를 두는 것이 좋습니다.
1. 워커 범위를 좁게 유지
워커에게 전체 저장소를 넘기지 마세요. 각 워커가 필요한 파일, 모듈, 서비스만 보게 해야 합니다.
좋은 예:
이 워커는 billing-service의 auth middleware만 분석합니다.
다른 서비스는 참고하지 마세요.
나쁜 예:
전체 저장소를 보고 인증 리팩토링을 수행하세요.
2. 워커의 노력 수준 낮추기
오케스트레이터는 xhigh를 사용하더라도 모든 워커가 xhigh일 필요는 없습니다.
권장 패턴:
- 오케스트레이터:
xhigh - 복잡한 설계 워커:
high - 파일 단위 분석 워커:
medium - 단순 검증 워커:
low
3. max_tokens 제한
워커별 max_tokens를 제한해 폭주하는 에이전트가 예산을 소진하지 않도록 하세요.
max_tokens=8000
또는 작업 유형별로 제한을 다르게 둘 수 있습니다.
TOKEN_LIMITS = {
"analysis": 6000,
"implementation": 12000,
"test_generation": 10000,
"merge": 32000,
}
4. 공유 컨텍스트 캐싱
모든 워커가 같은 시스템 프롬프트나 저장소 설명을 반복해서 받으면 비용이 증가합니다. 공유 컨텍스트는 캐싱해 반복 청구를 줄이는 방식으로 설계하세요.
Opus 4.8 가격 분석에는 노력 수준과 캐싱에 대한 계산이 포함되어 있습니다.
요약하면, 오케스트레이션은 강력하지만 비용은 에이전트 수에 비례합니다. 병렬 처리는 기본값이 아니라 선택지로 다뤄야 합니다.
Apidog로 오케스트레이션 테스트하기
API로 오케스트레이션을 구축할 때 가장 디버그하기 어려운 부분은 팬아웃(fan-out)입니다.
확인해야 할 지점은 다음과 같습니다.
- 워커가 올바른 범위의 컨텍스트를 받는가
- 워커 응답 형식이 병합 단계와 맞는가
- 대화 중간 시스템 메시지가 의도대로 전달되는가
- 병렬 실행 중 실패한 워커를 어떻게 처리하는가
- 부분 결과만 있을 때 병합 로직이 안전한가
200개의 실시간 워커 호출을 실행한 뒤에야 버그를 발견하면 비용과 시간이 모두 낭비됩니다.
Apidog를 사용하면 오케스트레이션 구성 요소를 단계별로 테스트할 수 있습니다.
실무 흐름은 다음과 같습니다.
-
https://api.anthropic.com/v1/messages에 대한 오케스트레이터 요청을 저장합니다. - 오케스트레이터가 생성한 작업 분할 결과를 확인합니다.
- 워커 엔드포인트를 mock으로 구성합니다.
- 수백 개의 실제 호출 없이 팬아웃 로직을 테스트합니다.
- 워커 응답 스키마에 assertion을 추가합니다.
- 병합 요청이 예상 형식의 결과만 받도록 검증합니다.
- 단일 워커를 여러
effort수준으로 다시 실행해 비용과 품질을 비교합니다.
예를 들어 워커 응답은 다음처럼 고정된 형태로 제한하는 것이 좋습니다.
{
"task_id": "auth-service-03",
"status": "completed",
"summary": "Token validation logic can be migrated to the shared auth utility.",
"changed_files": [
"services/auth/middleware/token.ts"
],
"risks": [
"Existing integration tests depend on the old error message."
],
"test_recommendations": [
"Run auth middleware integration tests."
]
}
이런 응답 형태를 assertion으로 검증하면 병합 단계에서 예기치 않은 payload로 실패하는 문제를 줄일 수 있습니다.
Apidog를 다운로드한 뒤 https://api.anthropic.com/v1/messages에 대한 오케스트레이터와 워커 요청을 구성하세요. 먼저 mock 환경에서 루프를 검증하고, 로직이 안정화되면 live endpoint로 전환하는 방식이 안전합니다.
시작 요청 구성은 Opus 4.8 API 가이드를 참고하세요.
구현 체크리스트
동적 워크플로우를 직접 구현할 때는 다음 순서로 진행하세요.
- [ ] 작업이 병렬화 가능한지 확인
- [ ] 오케스트레이터와 워커 역할 분리
- [ ] 오케스트레이터는
xhigh로 실행 - [ ] 워커는 작업 난이도에 따라
low,medium,high선택 - [ ] 워커별
max_tokens제한 - [ ] 워커 입력 컨텍스트 최소화
- [ ] 워커 응답 스키마 고정
- [ ] 실패한 워커 재시도 정책 정의
- [ ] 병합 단계에서 충돌 및 누락 확인
- [ ] mock 환경에서 팬아웃과 병합 로직 검증
- [ ] 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 서브에이전트는 수백만 개의 토큰을 사용할 수 있습니다. 워커 범위를 좁히고, 가능한 경우 노력 수준을 낮추며, 공유 컨텍스트를 캐싱해 비용을 제어하세요.
동적 워크플로우를 언제 피해야 하나요?
좁거나 엄격하게 순차적인 작업에서는 피하는 것이 좋습니다. 각 단계가 이전 단계에 의존하면 병렬 워커의 이점이 작고, 작은 작업에서는 토큰만 낭비될 수 있습니다.
Top comments (0)