다이내믹 워크플로우

다이내믹 워크플로우(dynamic workflow)는 Claude가 직접 작성한 JavaScript 스크립트가, 한 번의 대화로는 감당하기 어려운 수십~수백 개의 에이전트를 백그라운드에서 조율하게 만드는 Claude Code의 실행 방식입니다. 비유하자면, Claude에게 “이 큰일을 이렇게 돌려 줘"라는 작전 계획서를 써 달라고 하면 Claude는 그 계획을 스크립트로 옮기고 실행은 런타임에 맡겨 버립니다.

배경 참조

이 문서는 MoAI-ADK가 올라타 있는 플랫폼인 Claude Code 자체를 다루는 배경 자료입니다. MoAI-ADK 안에서 다이내믹 워크플로우를 어떻게 쓰는지는 동적 워크플로우와 Ultracode에서 이어집니다.

정보

한 줄 요약: 서브에이전트와 에이전트 팀이 “계획을 Claude의 머릿속에” 둔다면, 다이내믹 워크플로우는 “계획을 스크립트 코드 안에” 옮겨 대규모 작업을 한 번에 돌립니다.

비유로 이해하기

다이내믹 워크플로우는 대형 프로젝트를 맡은 총괄 매니저에게 미리 짜둔 작전 계획서를 건네는 일과 비슷합니다. 매니저는 그 계획서대로 여러 팀을 동시에 움직이고, 각 팀에서 나온 중간 산출물은 모두 매니저의 클립보드(스크립트 변수)에 모입니다. 당신에게 돌아오는 것은 최종 보고서 한 장뿐이고, 그 아래의 수많은 시행착오와 메모는 당신의 책상(세션 컨텍스트)을 전혀 어지럽히지 않습니다.

다이내믹 워크플로우는 작업을 기술하면 Claude가 직접 작성하는 JavaScript 스크립트이며, 런타임이 이 스크립트를 대화와 분리된 백그라운드에서 실행합니다. 스크립트 안에 루프, 분기, 중간 결과가 모두 들어 있기 때문에 세션의 컨텍스트 윈도우에는 최종 답변만 돌아옵니다.

핵심은 단순히 “에이전트를 더 많이 돌리는 것"이 아니라 계획 자체를 코드로 옮기는 것입니다. 계획이 코드가 되면 이런 일들이 가능해집니다.

• 독립된 에이전트들이 서로의 결과를 적대적으로(adversarial) 교차검증한 뒤 보고
• 하나의 계획을 여러 각도에서 동시에 초안 작성한 뒤 비교 평가
• 한 번의 순차 진행보다 훨씬 신뢰할 수 있는 결과 산출

다이내믹 워크플로우는 리서치 프리뷰(research preview) 단계이며 Claude Code v2.1.154 이상이 필요합니다. 모든 유료 플랜에서 쓸 수 있고, Pro 플랜에서는 /config의 Dynamic workflows 항목에서 켭니다. 런타임이 v2.1.154보다 오래되었거나 워크플로우가 꺼져 있으면 이 기능을 아예 쓸 수 없습니다.

Claude Code에는 크게 세 가지 오케스트레이션 프리미티브(orchestration primitive), 즉 실행 방식이 있습니다 — 서브에이전트 (subagent), 에이전트 팀 (Agent Teams), 다이내믹 워크플로우. 셋 다 여러 단계 작업을 수행하지만, 결정적 차이는 계획을 누가 쥐고 있는가입니다.

서브에이전트와 에이전트 팀은 Claude가 오케스트레이터로서 매 턴 무엇을 만들지 결정하고, 결과가 Claude의 컨텍스트로 들어옵니다. 반면 워크플로우 스크립트는 그 조율 로직을 스스로 품고 있어서 Claude의 컨텍스트에는 최종 답변만 전달됩니다. 이 차이가 “왜 대규모 팬아웃에 워크플로우가 유리한가"의 핵심입니다 — 수백 개 에이전트의 중간 산출물이 오케스트레이터의 컨텍스트를 채우지 않으니까요.

한 대화로 조율할 수 있는 양보다 더 많은 에이전트가 필요하거나, 조율 방식 자체를 읽고 다시 돌릴 수 있는 스크립트로 코드화하고 싶을 때 워크플로우를 선택합니다.

반대로 쓰지 않는 경우도 분명합니다.

• 한 대화로 충분한 소수 작업 → 서브에이전트를 직접 쓰는 편이 싸고 빠릅니다
• 단계마다 사용자 승인이 필요한 상호작용 작업 → 워크플로우는 실행 중 입력을 받지 못합니다
• 단일 파일 일상 편집 → 그냥 직접 하면 됩니다

공식 권장사항도 이 맥락과 같습니다. “대부분의 코딩 작업은 리서치보다 진짜로 병렬화 가능한 부분이 적다” — 그래서 코딩 중심 작업의 기본값은 순차 서브에이전트이고, 워크플로우는 정말 대량 병렬이 필요한 순간에 남겨 둡니다.

워크플로우 런타임은 스크립트를 대화와 분리된 격리 환경 (isolated environment)에서 실행합니다. 중간 결과는 Claude의 컨텍스트가 아니라 스크립트 변수에 머무르고, 런타임이 각 에이전트의 결과를 추적하므로 같은 세션 안에서는 재개도 가능합니다.

flowchart TD
    A[작업 기술
workflow 키워드] --> B[Claude가
스크립트 작성]
    B --> C[런타임 백그라운드
실행 시작]
    C --> D[팬아웃
다수 에이전트 병렬]
    D --> E[중간 결과
스크립트 변수에 수집]
    E --> F[교차검증·종합]
    F --> G[최종 결과만
세션 컨텍스트로 반환]

실행은 두 가지로 시작합니다. /deep-research 같은 번들 워크플로우를 호출하거나, 프롬프트 어디든 workflow라는 단어를 넣으면 Claude가 해당 작업용 스크립트를 작성합니다. 마음에 드는 결과가 나왔다면 /workflows 화면에서 s 키로 저장해 /<이름> 명령으로 재사용할 수 있습니다.

# 한 작업을 워크플로우로 실행
Run a workflow to audit every API endpoint under src/routes/ for missing auth checks

강력한 만큼 명확한 제약이 있습니다. 런타임이 적용하는 규칙은 다음과 같습니다.

워크플로우가 만드는 에이전트는 사용자에게 직접 질문하지 못합니다 — 서브에이전트·에이전트 팀과 같은 비대칭 경계 (asymmetric boundary)를 따릅니다. 입력이 필요하면 blocker report를 반환할 뿐이므로, 워크플로우를 띄우기 전에 필요한 모든 정보와 선호를 채워 넣어야 합니다.

추가로 알아둘 동작입니다.

• 권한 모드 (permission mode): 워크플로우가 생성하는 서브에이전트는 세션 모드와 무관하게 항상 acceptEdits로 실행되어 파일 편집이 자동 승인됩니다. 다만 허용 목록에 없는 셸 명령·웹 페치·MCP 도구는 실행 중에 프롬프트가 뜰 수 있으니, 긴 작업 전에 자주 쓸 명령을 settings.json 허용 목록에 미리 추가해 두는 것이 좋습니다.
• 재개 (resume): 실행을 멈췄다가 다시 돌리면 이미 끝난 에이전트는 캐시된 결과를 돌려주고 나머지만 라이브로 돕니다. 단, 같은 Claude Code 세션 안에서만 유효합니다 — 세션을 닫으면 다음 세션에서는 처음부터 다시 시작합니다.
• 비용 (cost): 한 번의 실행이 같은 작업을 대화로 처리할 때보다 훨씬 많은 토큰을 쓸 수 있습니다. 큰 실행 앞에서는 /model로 모델과 추론 강도를 한 번 확인하는 것이 안전합니다.

워크플로우는 다음 중 하나로 끌 수 있으며, 끄면 번들 워크플로우 명령·workflow 키워드·/effort 메뉴의 ultracode가 모두 사라집니다.

• /config에서 Dynamic workflows 토글 끄기 (세션 간 유지)
• ~/.claude/settings.json에 "disableWorkflows": true 설정

{
  "disableWorkflows": true
}

• 환경 변수 CLAUDE_CODE_DISABLE_WORKFLOWS=1
• 조직 전체는 관리 설정(managed settings)의 "disableWorkflows": true로 일괄 적용

MoAI-ADK는 다이내믹 워크플로우를 SPEC 기반 plan/run/sync 라이프사이클과 구분되는 세 번째 오케스트레이션 프리미티브로 인식하고, 실제 파이프라인에도 투입합니다. sync 단계의 4차원 품질 평가(sync-audit-4dim)와 plan 단계의 리서치 병렬 팬아웃(plan-research-fanout)이 워크플로우 스크립트로 구현되어 있습니다.

“계획을 스크립트 코드로 옮기고 중간 결과를 스크립트 변수에 가둔다"는 성질은 토크노믹스 관점에서도 매력적입니다 — 수십 개 에이전트의 중간 산출물이 오케스트레이터의 컨텍스트를 전혀 차지하지 않기 때문입니다. 워크플로우 에이전트도 사용자에게 직접 질문하지 못하는 같은 비대칭 경계를 따르므로, MoAI 오케스트레이터는 워크플로우를 띄우기 전에 모든 선호를 먼저 수집합니다. 자세한 운용 가이드는 아래 관련 문서를 참고하세요.

• 서브에이전트
• 에이전트 팀
• 동적 워크플로우와 Ultracode (MoAI-ADK)

• Orchestrate subagents at scale with dynamic workflows (Claude Code 공식 문서)

팁

대부분의 코딩 작업은 리서치보다 진짜로 병렬화 가능한 부분이 적습니다. 코딩 중심 작업의 기본값은 순차 서브에이전트로 두고, 다이내믹 워크플로우는 코드베이스 전수 스캔·대규모 마이그레이션처럼 실제로 대량 병렬이 필요한 작업에만 아껴 쓰는 것을 추천합니다.