클로드 코드 ‘동적 워크플로우’로 에이전트 작업 최적화

Optimizing Agentic Work using Claude Code Dynamic Workflows

• 앤스로픽 기술 블로그 | A harness for every task: dynamic workflows in Claude Code
  https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code
• 앤스로픽 개발자 문서 | Orchestrate subagents at scale with dynamic workflows
  https://code.claude.com/docs/en/workflows

핵심 정리 (Executive Summary)

Claude Code의 동적 워크플로우(Dynamic Workflows): 대규모의 복잡한 작업을 처리하기 위해 Claude가 스스로 자바스크립트(JavaScript) 기반의 오케스트레이션(Orchestration) 스크립트를 작성하고 실행하는 기능

• 단일 컨텍스트 윈도우 내에서 발생할 수 있는 에이전트의 나태함(Agentic laziness), 자기 편향성(Self-preferential bias), 목표 이탈(Goal drift) 한계 극복 목표
• 동적 워크플로우를 통해 Claude는 수십에서 수백 개의 하위 에이전트를 동시에 생성하고 조율하며, 코드 마이그레이션, 심층 연구, 보안 감사 등 고도의 지능과 병렬 처리가 필요한 작업을 수행
• 사용자는 ultracode 키워드나 전용 명령어를 통해 이를 실행할 수 있으며, 실행 중인 워크플로우를 모니터링하거나 중단 후 재개 가능

1. 동적 워크플로우의 정의 및 작동 원리

개념적 정의

동적 워크플로우는 Claude가 특정 작업에 맞춰 실시간으로 작성하는 맞춤형 ‘하네스(Harness)’다. 기존의 Claude Code가 단일 대화 맥락에서 계획과 실행을 동시에 수행했다면, 동적 워크플로우는 계획을 코드로 명문화하여 실행 환경을 분리한다.

기술적 매커니즘

• 자바스크립트 런타임: 워크플로우는 하위 에이전트를 생성하고 조정하는 특수 함수가 포함된 자바스크립트 파일을 실행한다. 여기에는 JSON, Math, Array와 같은 표준 자바스크립트 함수가 포함되어 데이터 처리를 돕는다.
• 하위 에이전트 오케스트레이션: Claude는 지능 수준(모델 선택)과 격리 수준(워크트리 사용 여부)을 직접 결정하여 하위 에이전트를 배치한다.
• 세션 유지 및 재개: 사용자 작업이나 터미널 종료로 인해 워크플로우가 중단되더라도, 세션을 다시 시작하면 중단된 지점부터 이어서 작업을 진행할 수 있다.

2. 동적 워크플로우 도입의 필요성

단일 컨텍스트 윈도우에서 장시간 작동하는 에이전트는 다음과 같은 실패 모드에 빠질 가능성이 높으며, 워크플로우는 이를 구조적으로 방지한다.

• 에이전트의 나태함 (Agentic Laziness): 복잡한 다단계 작업 중 일부만 수행하고 작업을 완료했다고 선언하는 현상. (예: 50개 보안 항목 중 35개만 검토 후 종료)
• 자기 편향성 (Self-preferential Bias): 자신이 도출한 결과물을 검증하거나 평가할 때 자신의 논리를 그대로 따르며 오류를 간과하는 경향.
• 목표 이탈 (Goal Drift): 대화가 길어지고 요약 과정이 반복되면서 초기 목표나 특정 제약 조건(예: “X는 하지 말 것”)이 유실되는 현상.

3. 다른 기능과의 비교 분석

워크플로우는 계획을 ‘코드’로 보유한다는 점에서 다른 협업 방식과 차별화된다.

구분	하위 에이전트 (Subagents)	스킬 (Skills)	에이전트 팀 (Agent Teams)	워크플로우 (Workflows)
실체	Claude가 생성한 작업자	Claude가 따르는 지침	수석 에이전트와 동료 세션	런타임이 실행하는 스크립트
결정 주체	Claude (턴 단위)	Claude (프롬프트 준수)	수석 에이전트 (턴 단위)	스크립트 (코드 기반)
결과 저장	컨텍스트 윈도우	컨텍스트 윈도우	공유 작업 목록	스크립트 변수
확장성	턴당 소수 작업	하위 에이전트와 동일	소수의 장기 실행 동료	수십~수백 개의 에이전트
중단 시	해당 턴 재시작	해당 턴 재시작	팀원 지속 실행	동일 세션 내 재개 가능

4. 핵심 워크플로우 패턴 및 품질 전략

Claude는 워크플로우 구축 시 다음과 같은 고도의 품질 관리 패턴을 활용한다.

• 분류 후 실행 (Classify-and-act): 분류기 에이전트가 작업 유형을 결정하고 적절한 경로로 라우팅한다.
• 분산 및 합성 (Fan-out-and-synthesize): 작업을 작은 단계로 쪼개어 독립된 에이전트들에게 맡긴 후 결과를 통합한다. 각 단계가 깨끗한 컨텍스트 윈도우를 가져 교차 오염을 방지한다.
• 적대적 검증 (Adversarial Verification): 생성된 결과물을 별도의 에이전트가 루브릭(기준안)에 따라 엄격하게 검증한다.
• 토너먼트 (Tournament): 동일한 작업에 대해 여러 에이전트가 서로 다른 접근법으로 경쟁하게 하고, 심사 에이전트가 승자를 선발한다.
• 완료 시까지 루프 (Loop until done): 고정된 횟수가 아니라 로그 오류가 사라지거나 새로운 발견이 없을 때까지 에이전트 생성을 반복한다.

5. 주요 활용 사례

기술 및 코드 관리

• 대규모 마이그레이션: Bun 프로젝트의 Zig에서 Rust로의 전환 사례처럼, 수백 개의 파일을 대상으로 수정과 검증을 병렬 처리한다.
• 심층 검증: 보고서의 모든 기술적 주장을 코드베이스와 대조하여 확인한다.
• 루트 원인 조사: 로그, 파일, 데이터를 각각 독립된 에이전트가 분석하여 서로 다른 가설을 세우고 검증함으로써 자기 편향성을 배제한다.

비즈니스 및 운영

• 대규모 분류 및 트리야지 (Triage): 지원 티켓이나 버그 보고서를 심각도에 따라 분류하고 중복을 제거하며, 필요시 자동 수정을 시도하거나 담당자에게 에스컬레이션한다.
• 심층 연구 (Deep Research): /deep-research 명령어를 통해 웹 검색 결과를 분산 수집하고 소스를 교차 검증하여 인용문이 포함된 보고서를 작성한다.
• 정렬 및 평가: 1,000개 이상의 항목을 루브릭에 따라 정렬할 때, 토너먼트 방식이나 쌍체 비교(Pairwise-comparison)를 사용하여 정확도를 높인다.

6. 실행 및 관리 가이드

실행 방법

1. 키워드 트리거: 프롬프트에 ultracode를 포함하거나 “워크플로우를 사용해줘”라고 요청한다.
2. 노력 수준 설정: /effort ultracode로 설정하면 모든 실질적인 작업에 대해 Claude가 워크플로우 사용 여부를 스스로 결정한다.
3. 내장 명령어: /deep-research <질문>과 같은 번들 워크플로우를 사용한다.

모니터링 및 제어

• /workflows 명령어: 현재 실행 중이거나 완료된 워크플로우 목록을 확인한다.
• 진행 뷰: 각 단계별 에이전트 수, 토큰 사용량, 경과 시간을 확인하고 특정 에이전트의 프롬프트와 도구 호출 내역을 상세히 조사할 수 있다.
• 저장 및 공유: 성공적인 워크플로우 스크립트는 프로젝트(.claude/workflows/)나 사용자 홈 디렉토리에 저장하여 재사용 가능하다.

제약 사항 및 비용 관리

• 토큰 사용량: 워크플로우는 많은 에이전트를 동원하므로 일반 대화보다 토큰 소모가 크다. 프롬프트에 “10k 토큰 사용”과 같이 예산을 명시할 수 있다.
• 동시성 제한: 로컬 리소스 보호를 위해 최대 16개의 동시 에이전트 실행을 지원하며, 전체 실행당 에이전트 수는 1,000개로 제한된다.
• 모델 라우팅: 작업의 복잡도에 따라 Sonnet이나 Opus 모델로 동적으로 라우팅하여 비용과 성능의 균형을 맞출 수 있다.

보안 및 권한

워크플로우가 생성한 하위 에이전트는 기본적으로 acceptEdits 모드에서 작동하며 사용자의 도구 허용 목록을 상속받는다. 신뢰할 수 없는 공용 콘텐츠를 읽는 에이전트의 권한을 제한하는 ‘격리(Quarantine)’ 패턴 활용이 권장된다.

FAQ on the Dynamic Workflows

클로드 코드(Claude Code)의 **동적 워크플로우(Dynamic Workflows)**에 대해 사용자가 가장 궁금해할 만한 5가지 핵심 질문과 답변을 FAQ 형식으로 정리해 드립니다.

Q1. 동적 워크플로우란 무엇이며, 기존 서브 에이전트(Subagents)와 무엇이 다른가요?

동적 워크플로우는 클로드가 당면한 특정 작업에 맞춰 실시간으로 작성하고 실행하는 자바스크립트 기반의 오케스트레이션 스크립트입니다.

• 차이점: 기존 서브 에이전트나 기술(Skills)은 클로드가 대화 창 내에서 턴 단위로 무엇을 실행할지 결정하지만, 워크플로우는 계획 자체를 코드로 옮겨 실행합니다.
• 규모: 서브 에이전트가 한 번에 몇 개의 작업을 수행한다면, 워크플로우는 한 번의 실행으로 수십에서 수백 개의 에이전트를 조율할 수 있는 확장성을 가집니다. 또한 중간 결과가 대화 문맥(Context window)이 아닌 스크립트 변수에 저장되어 문맥 오염을 방지합니다.

Q2. 왜 일반적인 작업 대신 동적 워크플로우를 사용해야 하나요?

복잡하고 긴 작업에서 발생할 수 있는 클로드의 세 가지 주요 실패 모드를 방지하기 위해 사용합니다.

1. 에이전트 태만(Agentic laziness): 복잡한 작업 중 일부만 완료하고 작업을 마쳤다고 선언하는 현상을 방지합니다.
2. 자기 편향(Self-preferential bias): 자신의 결과를 스스로 검증할 때 관대해지는 경향을 방지하며, 독립적인 검증 에이전트를 통해 객관성을 높입니다.
3. 목표 이탈(Goal drift): 작업이 길어짐에 따라 초기 목표나 제약 조건을 잊어버리는 현상을 막고 코드화된 계획을 끝까지 유지합니다.

Q3. 동적 워크플로우를 어떻게 시작하고 실행할 수 있나요?

사용자는 크게 세 가지 방법으로 워크플로우를 트리거할 수 있습니다.

• 키워드 사용: 프롬프트에 **”ultracode”**라는 단어를 포함하거나 “워크플로우를 사용해줘”라고 직접 요청하면 클로드가 스크립트를 작성합니다.
• 노력 수준 설정: /effort ultracode 명령어를 통해 세션 전체의 노력 수준을 설정하면, 클로드가 판단하기에 실질적인 모든 작업에 대해 워크플로우를 자동으로 계획합니다.
• 내장 명령어: 복잡한 조사를 위해 미리 구축된 /deep-research와 같은 번들 워크플로우를 즉시 실행할 수 있습니다.

Q4. 동적 워크플로우에서 자주 사용되는 설계 패턴은 무엇인가요?

클로드는 작업 성격에 따라 다음과 같은 고도화된 패턴을 조합하여 워크플로우를 구성합니다.

• 분산 및 합성(Fan-out-and-synthesize): 작업을 작은 단계로 나누어 수많은 에이전트에게 병렬로 맡긴 후, 결과를 하나로 합칩니다.
• 적대적 검증(Adversarial verification): 한 에이전트가 내놓은 결과물을 다른 독립적인 에이전트가 엄격한 기준에 따라 검증하게 합니다.
• 토너먼트(Tournament): 여러 에이전트가 각기 다른 접근 방식으로 같은 작업을 수행하게 한 뒤, 심사 에이전트가 최선의 결과물을 선정합니다.
• 분류 및 실행(Classify-and-act): 작업 유형을 먼저 분류하고 그에 적합한 특정 모델이나 에이전트에게 작업을 할당합니다.

Q5. 비용이나 토큰 사용량 측면에서 주의할 점이 있나요?

동적 워크플로우는 많은 수의 에이전트를 동시에 실행하므로 일반적인 대화보다 훨씬 더 많은 토큰을 사용합니다.

• 비용 관리: 큰 작업을 수행하기 전, 전체 저장소가 아닌 특정 디렉터리에만 적용해 보는 식으로 작은 단위에서 먼저 테스트하는 것이 권장됩니다.
• 예산 설정: “10k 토큰만 사용해줘”와 같이 프롬프트에 명시적인 토큰 예산을 설정하여 지출을 제한할 수 있습니다.
• 모델 선택: 모든 에이전트가 강력한 모델을 쓸 필요는 없으므로, 단순 작업 단계에는 더 작은 모델을 사용하도록 클로드에게 요청하여 비용을 최적화할 수 있습니다.

참고자료 및 다운로드

구글시트 | 클로드 코드 다이나믹 워크플로우 개요 (동준상.넥스트플랫폼 / 26.06.03)
https://docs.google.com/spreadsheets/d/117X4s-JyeMzSlwmIdnzS6qBAQJQn2HmVR3j6cEVbQc8/edit?usp=sharing

슬라이드 | Mastering Dynamic Workflows for AI_Orchestration
https://drive.google.com/file/d/1YZbmkyAyDIJSN8tECgZhu9aF9mH_oSbJ/view?usp=sharing