클로드 코드 Dynamic Workflows: 수십 개 에이전트를 스크립트로 굴리기
클로드 코드를 쓰다 보면 어느 순간 이런 작업을 만나게 됩니다. “저장소 전체의 라우트 핸들러를 훑어서 인증 누락을 찾아줘”, “컴포넌트 500개를 새 스타일 시스템으로 옮겨줘”, “문서와 이슈를 여러 방향에서 조사한 뒤 서로 검증해서 보고서를 만들어줘” 같은 요청 말이죠.
이런 작업은 한 대화 안에서 차근차근 진행할 수도 있습니다. 하지만 파일이 많아지고 검증 단계가 늘어나면 컨텍스트가 금방 지저분해지고, Claude가 어느 파일을 봤는지, 어떤 결과를 검증했는지 사람이 계속 추적해야 합니다. 서브 에이전트를 여러 번 호출하는 방법도 있지만, 매 턴마다 오케스트레이션(orchestration)을 Claude가 다시 판단해야 한다는 한계가 있죠.
Claude Code의 Dynamic Workflows는 이 문제를 조금 다른 방식으로 풉니다. Claude가 작업을 위한 자바스크립트(JavaScript) 스크립트를 작성하고, 별도의 런타임(runtime)이 그 스크립트를 실행하면서 수십 개에서 수백 개의 서브 에이전트를 조율합니다. 사람 입장에서는 “큰 작업을 워크플로우로 실행해줘”라고 말하고, 진행 상황은 백그라운드에서 지켜보다가 마지막 결과를 받는 식이에요.
이번 글에서는 Dynamic Workflows가 무엇인지, 언제 써야 하는지, ultracode와 /workflows를 어떻게 쓰는지, 그리고 비용과 권한 측면에서 무엇을 조심해야 하는지 정리해보겠습니다.
Dynamic Workflows란?
Dynamic Workflows는 Claude가 작성한 스크립트가 여러 서브 에이전트를 대규모로 조율하는 기능입니다. 여기서 중요한 단어는 “스크립트”예요. 단순히 Claude가 마음속으로 계획을 세우는 게 아니라, 반복문과 분기, 중간 결과 저장을 포함한 실행 가능한 코드를 만들어 런타임에 넘깁니다.
공식 문서 기준으로 Dynamic Workflows는 Claude Code v2.1.154 이상에서 사용할 수 있습니다. 유료 플랜, Anthropic API 접근, Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry 환경에서 제공되고, Pro 플랜에서는 /config의 Dynamic workflows 항목에서 켜야 합니다.
일반적인 흐름은 이렇습니다.
- 사용자가 큰 작업을 설명합니다.
- Claude가 그 작업에 맞는 워크플로우 스크립트를 작성합니다.
- Claude Code가 실행 전에 단계와 스크립트를 보여주고 승인을 요청합니다.
- 런타임이 백그라운드에서 여러 서브 에이전트를 실행합니다.
- 중간 결과는 스크립트 변수에 쌓이고, 최종 요약만 대화에 돌아옵니다.
이 구조 덕분에 대화창은 비교적 깔끔하게 유지됩니다. 서브 에이전트가 50개를 돌았다고 해서 50개의 긴 결과가 모두 메인 컨텍스트에 들어오는 게 아니라, 워크플로우 스크립트가 중간 결과를 보관하고 마지막에 필요한 결과만 정리해서 넘겨주기 때문입니다.
서브 에이전트, 스킬, 에이전트 팀과 뭐가 다를까요?
Claude Code에는 이미 여러 작업을 나누는 기능이 많습니다. 서브 에이전트, 에이전트 스킬, 에이전트 팀, 그리고 이번 글의 워크플로우가 모두 비슷해 보일 수 있어요. 차이는 “계획을 누가 들고 있느냐”입니다.
서브 에이전트는 Claude가 대화 중에 필요할 때 작업자를 하나 띄우는 방식입니다. 코드 탐색, 리뷰, 테스트 작성처럼 독립적인 하위 작업을 맡기기 좋습니다. 다만 다음에 어떤 에이전트를 띄울지, 결과를 어떻게 합칠지는 메인 Claude가 턴마다 판단합니다.
스킬은 Claude가 특정 절차를 따르도록 알려주는 지침 묶음입니다. 예를 들어 “블로그 글을 쓸 때는 초안을 쓰고 문법과 스타일을 차례로 검사하라” 같은 절차를 담을 수 있습니다. 하지만 스킬 자체가 에이전트를 수백 개 띄우거나 루프를 직접 실행하는 것은 아닙니다.
에이전트 팀은 여러 Claude 세션이 동료처럼 협업하는 모델입니다. 공유 태스크 목록을 보고 각자 일을 나눠 맡고, 팀원끼리 메시지를 주고받을 수 있죠. 장기 작업이나 사람의 개입이 중간중간 필요한 협업에는 잘 맞습니다.
반면 Dynamic Workflows는 계획을 코드로 옮깁니다. 반복, 분기, 병렬 실행, 검증 루프가 워크플로우 스크립트 안에 들어갑니다. 그래서 같은 절차를 다시 실행하기 쉽고, 중간 결과도 Claude의 컨텍스트가 아니라 스크립트 변수에 남습니다. 규모도 다릅니다. 서브 에이전트가 한 턴에 몇 개의 일을 위임하는 느낌이라면, 워크플로우는 한 번의 실행에서 수십 개에서 수백 개의 에이전트를 다루는 쪽에 가깝습니다.
언제 워크플로우를 써야 할까요?
워크플로우는 “많이” 실행해야 할 때 유용합니다. 파일이 많거나, 같은 검사를 여러 대상에 반복해야 하거나, 서로 다른 관점의 결과를 모아서 검증해야 할 때 빛을 발합니다.
예를 들어 라우트 핸들러마다 인증 체크가 빠졌는지 확인해야 한다고 해볼까요? 파일이 5개라면 Claude에게 직접 읽고 고치라고 해도 충분합니다. 파일이 200개라면 이야기가 달라집니다. 한 에이전트가 모든 파일을 순서대로 읽으면 오래 걸리고, 중간에 놓치는 파일도 생길 수 있습니다. 이때 워크플로우는 파일 목록을 찾는 에이전트, 파일별 감사 에이전트, 결과를 반박 관점에서 검증하는 에이전트, 최종 보고서를 합치는 에이전트를 단계별로 구성할 수 있습니다.
마이그레이션(migration) 작업도 좋은 예입니다. styled-components를 Tailwind로 옮기거나, 오래된 API 호출 방식을 새 클라이언트로 바꾸는 작업은 파일마다 비슷하지만 세부 맥락은 다릅니다. 워크플로우는 대상 파일을 나누고, 각 파일을 별도 에이전트가 처리하게 한 뒤, 타입 검사나 테스트 결과를 보고 반복 수정하는 루프를 만들 수 있습니다.
조사 작업에도 잘 맞습니다. 한 가지 질문을 여러 출처에서 조사하고, 각 주장마다 근거가 맞는지 교차 검증(cross-checking)해야 한다면 /deep-research 같은 내장 워크플로우가 훨씬 자연스럽습니다. 단일 응답으로 웹을 훑는 것보다 여러 관점의 에이전트가 따로 조사하고 검증하는 편이 결과의 신뢰도를 높이기 쉽습니다.
반대로 작은 버그 수정, 파일 한두 개짜리 리팩터링(refactoring), 빠른 질문에는 워크플로우가 과합니다. 워크플로우는 준비와 실행, 검증에 토큰을 더 쓰기 때문에 “큰 작업을 안전하게 나눠 처리하고 싶다”는 명확한 이유가 있을 때 쓰는 편이 좋습니다.
먼저 /deep-research로 감 잡기
Dynamic Workflows를 처음 써본다면 직접 스크립트를 만들라고 하기보다 내장 워크플로우인 /deep-research부터 실행해보는 게 좋습니다. 이 명령은 질문을 여러 관점으로 나눠 웹 검색을 수행하고, 출처를 가져와 서로 검증한 뒤, 인용이 붙은 보고서를 만들어줍니다.
/deep-research What changed in the Node.js permission model between v20 and v22?실행하면 Claude Code가 워크플로우를 실행해도 되는지 묻습니다. 승인하면 백그라운드에서 단계별로 에이전트가 돌고, 현재 대화는 계속 사용할 수 있습니다. 진행 상황은 /workflows에서 확인합니다.
/workflows진행 화면에서는 각 단계의 에이전트 수, 토큰 사용량, 걸린 시간을 볼 수 있습니다. 특정 단계로 들어가면 그 안의 에이전트가 어떤 프롬프트를 받았고 어떤 도구를 호출했는지도 확인할 수 있어요. 긴 작업을 맡겨놓고 다른 질문을 하다가, 필요할 때 /workflows로 들어가 상태를 보는 흐름입니다.
흥미로운 점은 결과가 턴별 로그가 아니라 하나의 보고서로 돌아온다는 것입니다. 많은 에이전트가 조사하고 검증했더라도 사용자는 마지막에 정리된 결과를 받습니다. 그래서 Dynamic Workflows는 단순 병렬 실행이라기보다 “큰 작업을 배치 작업(batch job)처럼 실행하고, 검증된 산출물만 돌려받는 방식”에 가깝습니다.
직접 워크플로우 실행하기
직접 워크플로우를 만들 때는 프롬프트에 자연어로 “워크플로우를 사용해줘”라고 요청할 수 있습니다. 최신 버전에서는 ultracode 키워드를 넣어도 됩니다.
ultracode: src/routes 아래의 모든 API 엔드포인트를 감사해서 인증 체크가 빠진 곳을 찾고, 각 발견 사항을 반대 관점에서 한 번 더 검증한 뒤 보고해줘또는 이렇게 써도 됩니다.
use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summaryClaude Code는 입력에서 워크플로우 요청을 감지하면 일반 대화로 바로 작업하지 않고, 먼저 워크플로우 스크립트를 작성합니다. 실행 전에는 계획된 단계가 표시되고, 권한 모드에 따라 승인 프롬프트가 뜹니다. 여기서 바로 실행할 수도 있고, 원시 스크립트를 열어본 뒤 결정할 수도 있습니다.
실수로 ultracode가 강조되었는데 워크플로우로 실행하고 싶지 않다면 macOS에서는 Option+W, Windows와 Linux에서는 Alt+W로 이번 프롬프트의 트리거를 해제할 수 있습니다. 아예 키워드 트리거를 끄고 싶다면 /config에서 Ultracode keyword trigger를 비활성화하면 됩니다.
Ultracode 모드로 자동 판단 맡기기
매번 “워크플로우로 해줘”라고 말하지 않고 Claude에게 판단을 맡기는 방법도 있습니다. /effort ultracode를 켜면 Claude가 실질적인 작업마다 워크플로우가 필요한지 판단합니다.
/effort ultracode세션을 시작할 때부터 켜고 싶다면 이렇게 실행할 수 있습니다.
claude --effort ultracode공식 문서 기준으로 claude --effort ultracode는 Claude Code v2.1.203 이상이 필요합니다. 이 모드에서는 한 요청이 여러 워크플로우로 쪼개질 수도 있습니다. 먼저 코드베이스를 이해하는 워크플로우를 돌리고, 그다음 변경을 적용하는 워크플로우를 돌리고, 마지막으로 검증 워크플로우를 실행하는 식이죠.
다만 ultracode는 모든 작업을 더 신중하고 크게 처리하려는 모드입니다. 토큰도 더 많이 쓰고 시간도 더 걸립니다. 평소의 작은 수정까지 이 모드로 처리하면 답답할 수 있어요. 복잡한 마이그레이션이나 저장소 전체 점검을 하는 동안만 켜고, 일상적인 작업으로 돌아오면 /effort high 같은 일반 추론 강도로 낮추는 편이 좋습니다. 모델과 추론 강도 조절이 낯설다면 클로드 코드 모델 선택과 추론 강도 조절을 먼저 읽어보셔도 좋습니다.
저장해서 명령어처럼 재사용하기
워크플로우가 한 번 잘 돌아갔다면 저장해두는 것이 좋습니다. 예를 들어 “이번 PR의 변경 파일을 리뷰하고, 중요도순으로 정리하는 워크플로우”는 브랜치마다 반복해서 쓰기 좋죠.
저장은 /workflows 화면에서 합니다. 저장할 실행을 선택한 뒤 s를 누르면 저장 위치를 고를 수 있습니다.
.claude/workflows/: 프로젝트에 저장합니다. Git에 커밋하면 팀원도 같은 워크플로우를 사용할 수 있습니다.~/.claude/workflows/: 개인 홈 디렉토리에 저장합니다. 모든 프로젝트에서 쓸 수 있지만 본인에게만 보입니다.
저장된 워크플로우는 다음 세션부터 슬래시 커맨드(slash command)처럼 실행할 수 있습니다. 예를 들어 triage-issues라는 이름으로 저장했다면 /triage-issues 형태로 부를 수 있어요.
입력값도 넘길 수 있습니다. 저장된 워크플로우 안에서는 args라는 전역 값으로 전달됩니다.
Run /triage-issues on issues 1024, 1025, and 1030Claude가 이 입력을 구조화된 데이터로 넘기기 때문에, 스크립트 안에서는 문자열을 직접 파싱하지 않고 배열이나 객체처럼 다룰 수 있습니다. 반복 업무를 팀 표준 절차로 만들고 싶다면 프로젝트의 .claude/workflows/에 저장하는 방식이 특히 유용합니다.
저장된 스크립트는 어떻게 생겼을까요?
워크플로우를 저장하면 .claude/workflows/ 아래에 메타 정보와 스크립트 본문이 들어갑니다. 실제 스크립트는 Claude가 작성하므로 평소에는 직접 편집하지 않아도 됩니다. 다만 어떤 구조인지 알아두면 검토하기가 훨씬 편합니다.
export const meta = {
name: "audit-routes",
description: "라우트 핸들러의 인증 누락을 감사합니다",
};
const found = await agent("src/routes 아래의 .ts 파일 목록을 찾아줘", {
schema: {
type: "object",
required: ["files"],
properties: {
files: { type: "array", items: { type: "string" } },
},
},
});
const audits = await pipeline(found.files, (file) =>
agent(`${file} 파일에서 인증 체크 누락을 감사해줘`, { label: file }),
);
return audits.filter(Boolean);본문은 최상위 await를 사용할 수 있는 자바스크립트입니다. agent()는 서브 에이전트 하나를 띄우고, pipeline()은 목록의 각 항목에 대해 에이전트를 실행하는 식으로 이해하면 됩니다.
여기서 눈여겨볼 점은 스크립트 자체가 직접 파일을 읽거나 셸(shell)을 실행하는 주체가 아니라는 점입니다. 워크플로우 스크립트는 조율자입니다. 실제 읽기, 쓰기, 명령 실행은 스크립트가 호출한 에이전트가 수행합니다. 이 구분을 알아두면 권한과 보안 모델을 이해하기 쉬워집니다.
권한과 승인 흐름 이해하기
워크플로우는 많은 에이전트를 한꺼번에 실행하므로 승인 흐름을 꼭 이해해야 합니다. CLI에서는 실행 전에 계획된 단계가 보이고, 보통 다음 선택지가 나옵니다.
- Yes, run it: 이번 워크플로우를 실행합니다.
- Yes, and don’t ask again for
<name>in<path>: 이 프로젝트의 이 워크플로우에 대해 다음부터 묻지 않습니다. - View raw script: 실행 전에 원시 스크립트를 확인합니다.
- No: 실행하지 않습니다.
Ctrl+G로 스크립트를 편집기에서 열 수 있고, Tab으로 실행 전 프롬프트를 조정할 수도 있습니다. 기본 권한 모드에서는 매번 묻지만, 자동 승인 모드에서는 첫 실행만 묻는 식으로 동작이 달라집니다. 우회 권한 모드나 claude -p, Agent SDK에서는 대화형 승인 없이 바로 실행될 수 있으니 더 조심해야 합니다.
중요한 점이 하나 더 있습니다. 워크플로우가 띄운 서브 에이전트는 acceptEdits 모드로 실행되고, 세션의 도구 허용 목록(tool allowlist)을 상속합니다. 파일 편집은 자동 승인됩니다. 다만 허용 목록에 없는 셸 명령, 웹 요청, MCP 도구 호출은 실행 중간에 추가 승인을 요청할 수 있습니다. 긴 작업을 걸어두고 자리를 비울 계획이라면 필요한 명령을 미리 허용 목록에 넣어두는 편이 안전합니다. 권한 설정 자체가 헷갈린다면 클로드 코드 권한 설정과 권한 모드 가이드를 같이 보면 좋습니다.
실행 중 관리와 재개
워크플로우가 시작되면 /workflows 화면에서 실행 중인 작업과 완료된 작업을 볼 수 있습니다. 진행 화면에서는 단계와 에이전트를 선택해 자세히 들어갈 수 있고, 필요하면 일시정지하거나 중단할 수 있습니다.
자주 쓰는 키는 이 정도만 기억해도 충분합니다.
Enter또는→: 선택한 단계나 에이전트의 상세 화면으로 들어갑니다.Esc: 한 단계 뒤로 나옵니다.p: 실행을 일시정지하거나 재개합니다.x: 선택한 에이전트나 전체 워크플로우를 중단합니다.r: 실행 중인 에이전트를 다시 시작합니다.s: 실행 스크립트를 명령어로 저장합니다.
중단한 워크플로우는 같은 Claude Code 세션 안에서 재개할 수 있습니다. 이미 완료된 에이전트 결과는 캐시된 값을 사용하고, 나머지만 다시 실행합니다. 다만 Claude Code를 종료한 뒤 새 세션을 시작하면 기존 실행을 그대로 이어가는 것이 아니라 워크플로우를 새로 시작합니다.
또 하나 알아둘 제한은 실행 중 사용자 입력입니다. 워크플로우 중간에 “여기서 사람에게 물어보고 다음 단계로 넘어가기” 같은 흐름은 지원되지 않습니다. 도구 권한 프롬프트를 제외하면 중간 사용자 입력이 없다고 보는 편이 맞습니다. 단계 사이에 사람의 승인이 꼭 필요하다면 큰 워크플로우 하나로 묶기보다, 단계별로 별도 워크플로우를 실행하는 구조가 낫습니다.
비용과 규모 조절
Dynamic Workflows는 강력하지만 공짜 점심은 아닙니다. 에이전트를 많이 띄우는 만큼 토큰 사용량도 커집니다. 저장소 전체를 대상으로 실행하면 일반 대화보다 훨씬 많은 사용량과 시간이 들 수 있어요.
가장 현실적인 전략은 작은 범위로 먼저 시험하는 것입니다. 저장소 전체가 아니라 디렉토리 하나, 모든 PR이 아니라 변경 파일 3개, 넓은 조사 질문이 아니라 좁은 하위 질문 하나로 먼저 돌려보세요. 결과가 원하는 방향이면 범위를 넓히면 됩니다.
Claude Code에는 규모를 조절하는 설정도 있습니다. /config의 Dynamic workflow size 설정은 Claude가 작성하는 워크플로우의 목표 에이전트 수를 조언합니다.
unrestricted: 별도 가이드라인이 없습니다. 기본값입니다.small: 5개 미만의 에이전트를 목표로 합니다.medium: 15개 미만의 에이전트를 목표로 합니다.large: 50개 미만의 에이전트를 목표로 합니다.
이 설정은 Claude에게 전달되는 지침이라서, 사용자가 프롬프트에서 더 큰 규모를 명시하면 그 요청이 우선될 수 있습니다. 그래도 평소에는 small이나 medium으로 두고, 정말 큰 작업에서만 넓히는 식으로 쓰면 토큰 폭주를 줄일 수 있습니다.
런타임 자체에도 상한이 있습니다. 동시에 실행되는 에이전트는 최대 16개이고, 머신 성능에 따라 더 적을 수 있습니다. 한 번의 실행에서 전체 에이전트 수는 최대 1,000개로 제한됩니다. 또한 Claude Code v2.1.203 이상에서는 25개가 넘는 에이전트가 예정되거나 예상 토큰이 150만을 넘으면 진행 줄에 Large workflow 경고가 표시됩니다.
워크플로우를 끄고 싶다면
팀이나 개인 환경에서 Dynamic Workflows를 끄고 싶을 수도 있습니다. 예를 들어 비용을 엄격히 통제해야 하거나, 자동으로 많은 파일을 수정하는 기능을 아직 허용하고 싶지 않을 때가 있죠.
개인 사용자는 세 가지 방식으로 끌 수 있습니다.
# 1. Claude Code 안에서 /config를 열고 Dynamic workflows를 끕니다.
/config{
"disableWorkflows": true
}CLAUDE_CODE_DISABLE_WORKFLOWS=1 claude조직 단위로는 관리 설정(managed settings)에 disableWorkflows를 지정하거나 Claude Code 관리자 설정 페이지에서 끌 수 있습니다. 비활성화하면 내장 워크플로우 명령을 사용할 수 없고, ultracode 키워드도 워크플로우를 시작하지 않으며, /effort 메뉴에서도 ultracode가 사라집니다.
실전 프롬프트 패턴
마지막으로 바로 써볼 만한 프롬프트를 몇 가지 정리해보겠습니다. 핵심은 “어떤 대상을 나눌지”, “각 조각에서 무엇을 할지”, “결과를 어떻게 검증하고 합칠지”를 함께 말하는 것입니다.
저장소 전체 감사라면 이렇게 시작할 수 있습니다.
use a workflow to audit every route handler under src/routes for missing authentication checks, then adversarially verify each finding before reporting it타입 오류를 계속 고치고 싶다면 반복 종료 조건을 넣어주세요.
use a workflow to run bun run typecheck and keep fixing reported errors until the type check passes or two rounds in a row make no progress대규모 마이그레이션은 대상과 격리 방식을 분명히 합니다.
use a workflow to migrate every component under src/components from styled-components to Tailwind, working on each file in its own isolated copy and verifying each resultPR 리뷰는 파일별 리뷰와 최종 병합 단계를 나눠 말하면 좋습니다.
use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary조사 작업은 출처와 검증 방식을 강조합니다.
use a workflow to research how our three competitors handle rate limiting, read their public docs and recent changelog entries in parallel, then compare the approaches with citations이런 프롬프트는 Claude가 워크플로우 스크립트를 설계할 때 좋은 힌트가 됩니다. 단순히 “크게 해줘”라고 말하기보다, 병렬화 단위와 검증 기준을 명확히 적을수록 결과가 안정적입니다.
마치며
Dynamic Workflows는 Claude Code를 “대화형 코딩 도우미”에서 “여러 에이전트를 조율하는 작업 런타임”에 가깝게 만들어 주는 기능입니다. 핵심은 계획을 Claude의 컨텍스트에만 두지 않고, 읽고 저장하고 재실행할 수 있는 스크립트로 옮긴다는 점입니다.
작은 작업에는 여전히 일반 대화나 서브 에이전트가 편합니다. 하지만 저장소 전체 감사, 대규모 마이그레이션, 반복 검증, 교차 확인이 필요한 조사처럼 규모가 큰 작업에서는 워크플로우가 훨씬 잘 맞습니다. 처음에는 /deep-research로 감을 잡고, 그다음 작은 디렉토리 하나를 대상으로 직접 워크플로우를 돌려보세요. 결과가 마음에 들면 .claude/workflows/에 저장해서 팀의 반복 업무로 만들 수 있습니다.
더 자세한 옵션과 최신 제한 사항은 Claude Code Dynamic Workflows 공식 문서를 참고하세요.
This work is licensed under CC BY 4.0
