Claude Opus 4.8의 Dynamic Workflows를 사용하여 코드베이스 감사를 자동화해 보았다

2025년 8월에 출시된 Claude Opus 4.8에는 Dynamic Workflows라는 신기능이 탑재되어 있습니다. 이는 단순한 채팅의 연장이 아니라, JavaScript 스크립트가 AI 서브 에이전트(Sub-agent)를 대규모로 오케스트레이션(Orchestration)하는, 지금까지와는 궤를 달리하는 아키텍처입니다.

이 기사에서는 Dynamic Workflows의 구조와 사용법을 해설하고, 대규모 코드베이스의 자동 감사 태스크에 활용한 지견을 소개합니다.

Dynamic Workflows는 Claude Code에 탑재된 멀티 에이전트 오케스트레이션 (Multi-agent Orchestration) 기능입니다.

방식	구조	결과 처리
일반적인 서브 에이전트	단일 세션 내에서 동작, 완료 후 호출 측으로 답변	Claude의 컨텍스트 (Context) 경유
Agent Teams	독립된 세션에서 동작, 세션 간 직접 통신	Claude의 컨텍스트 (Context) 경유
Dynamic Workflows	JS 스크립트가 오케스트레이터 (Orchestrator)로 동작	스크립트 변수에 중간 결과 유지

Workflows의 가장 큰 특징은 중간 결과가 Claude의 컨텍스트 (Context)를 통과하지 않는다는 점입니다. 스크립트 변수로서 유지되기 때문에 컨텍스트 길이의 제약을 받기 어려워, 대규모 태스크에 적합합니다.

Dynamic Workflows는 다음과 같은 세 가지 방법으로 기동할 수 있습니다:

• 프롬프트에 **"workflow"**라는 키워드를 포함한다

• /deep-research 명령어를 사용한다

• /effort ultracode를 사용한다 (xhigh 추론 + 자동 워크플로우 기동)

• Claude Code v2.1.154 이상

• 플랜: Pro / Max / Team / Enterprise (무료 플랜은 미지원)

• 모델: Claude Opus 4.8 (/effort ultracode의 경우 xhigh 대응 모델이 필수)

# 1. Dynamic Workflows 활성화
/config → Dynamic Workflows → ON
# 2. 모델을 Opus 4.8로 전환
...

/effort ultracode는 「xhigh 추론 + Dynamic Workflows 자동 기동」의 단축키입니다. 두 설정이 모두 갖춰져 있지 않으면 다음과 같은 에러가 발생합니다:

Ultracode needs dynamic workflows enabled (see /config) and an xhigh-capable model.
Valid options are: low, medium, high, xhigh, max, auto

Dynamic Workflows가 기동되면, Claude Code는 내부적으로 JavaScript 오케스트레이터 스크립트를 생성 및 실행합니다. 스크립트는 다음과 같은 4가지 주요 프리미티브 (Primitive)로 구성됩니다.

// phase: 순서가 있는 페이즈(Phase) 정의
await phase("discovery", async () => {
// ...
...

옵션	설명
schema	서브 에이전트의 반환값 JSON 스키마 (zod 등)
model	에이전트마다 모델을 변경 가능 (비용 최적화에 유효)
label	UI 상에 표시되는 식별명
phase	에이전트가 속한 페이즈 이름

서브 에이전트가 결과를 반환하려면, StructuredOutput 도구를 명시적으로 호출해야 합니다. 이를 호출하지 않고 완료해 버리면 결과가 스크립트로 전달되지 않아 「검증 실패」 처리가 됩니다.

프롬프트에 반드시 다음과 같은 지시를 포함합시다:

태스크 완료 후, 반드시 StructuredOutput 도구를 호출하여 결과를 반환해 주세요.
호출 없이 종료할 경우, 결과는 폐기됩니다.

수만 행 규모의 TypeScript 코드베이스를 대상으로, 인시던트급 보안 문제를 자동 검출하는 워크플로우를 구축했습니다.

상정하는 감사 타겟 (예):

• 서버 미들웨어군 (주요 공격 표면)
• 플러그인 · SSR 처리계
• 클라이언트 사이드 코드
• 패키지 엔트리 포인트 (Entry point)

첫 번째 시도 (1회차)는 다음과 같은 문제로 완전히 실패했습니다:

• 에이전트가 3분 × 6회 스톨 (Stall) (Opus 4.8 + xhigh 조합이 너무 무거웠음)
• 조사 대상이 너무 넓었음 (디렉토리 단위로 지정)
• 「확인된 것만 보고하라」는 제약이 너무 엄격했음

개선책으로 채택한 설계:

모델: Sonnet (비용 절감 & 안정성 우선)
영역 분할: 12개의 세밀한 영역(Fine-grained area)으로 파일 리스트를 통해 명시
정밀도 방침: 「확신도를 포함하여 후보를 표면화」(판단은 검증 단계에 위임)
...

지표	수치
총 에이전트 수	66
...
증상: verification failure: agent completed without calling StructuredOutput

대책: 에이전트 프롬프트 끝에 반드시 「StructuredOutput을 호출하지 않고 종료하지 마라」고 명시한다. 스키마(Schema)도 구체적으로 정의한다.

증상: 에이전트가 3분 이상 응답 없이 타임아웃(Timeout)

대책: 오케스트레이터(Orchestrator)는 Opus 4.8을 유지하더라도, 서브 에이전트(Sub-agent)의 모델을 Sonnet으로 낮춤으로써 안정성이 대폭 향상된다.

182만 서브 에이전트 토큰은 Max 플랜에서도 한꺼번에 소비됩니다.

대책:

• 스캔 단계는 Haiku, 검증 단계는 Sonnet, 요약만 Opus로 구성하는 계층형 모델 할당 (Hierarchical model allocation)
• 대상 파일을 좁히고, 「이 파일만 봐라」고 명시한다
• 워크플로우 실행 중에는 /workflows 다이얼로그를 열지 않는다 (중단될 수 있음)

「어느 디렉토리 전체」라는 지정 방식은 에이전트가 무엇을 우선해야 할지 판단할 수 없어 결과가 얕아지기 쉽다. 파일 이름을 명시한 리스트로 지정하면 정밀도가 올라간다.

Dynamic Workflows는 단발적인 코드 질문과는 다른 **대규모 코드베이스 횡단 태스크 (Large-scale codebase cross-task)**에서 진가를 발휘한다. 특히 유효한 유스케이스(Use case)는:

• 보안 감사 (여러 파일을 병렬 스캔 → 독립 검증)
• 코드 리뷰 자동화 (PR 전체를 분할하여 병렬 체크)
• 문서 생성 (파일별로 병렬 분석 → 통합)
• 테스트 커버리지 분석 (모듈 단위의 병렬 체크)

한편 토큰 비용이 상당히 높기 때문에, /effort ultracode는 핀포인트로 사용하고, 평소의 태스크에는 일반 모드를 사용한다는 식의 구분 사용이 중요하다.

우선 작은 스코프(Scope)에서 시도해 보고, 에이전트 수 · 모델 구성 · StructuredOutput 호출 확인이라는 세 가지 포인트를 짚어내면 안정적인 결과를 얻을 수 있게 된다.