동적 워크플로우로 서브에이전트 대규모 조율하기

동적 워크플로우로 서브에이전트 대규모 조율하기 (Orchestrate subagents at scale with dynamic workflows)

동적 워크플로우는 Claude가 작성하고 여러분이 다시 실행할 수 있는 스크립트 하나로 많은 서브에이전트를 조율하는 기능이에요. 코드베이스 감사, 대규모 마이그레이션, 상호 검증이 필요한 리서치에 잘 맞습니다. 플랜을 대화가 아니라 코드로 옮기기 때문에, Claude의 컨텍스트에는 최종 답만 남고 중간 결과는 스크립트 변수에 쌓여요.

출처: 공식문서

본문

동적 워크플로우는 유료 플랜 전부와 Anthropic API 접근, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 사용할 수 있어요. Pro에서는 /config의 Dynamic workflows 행에서 켤 수 있습니다.

동적 워크플로우는 여러 서브에이전트를 한 번에 조율하는 JavaScript 스크립트예요. Claude가 여러분이 설명한 작업에 맞는 스크립트를 작성하고, 런타임이 세션을 응답 가능하게 유지한 채 백그라운드에서 실행합니다.

언제 워크플로우를 쓸까

서브에이전트, 스킬, 에이전트 팀, 워크플로우 모두 다단계 작업을 실행할 수 있어요. 차이는 누가 플랜을 쥐고 있느냐입니다:

	서브에이전트	스킬	에이전트 팀	워크플로우
무엇인가	Claude가 생성하는 작업자	Claude가 따르는 지시	피어 세션을 감독하는 리드 에이전트	런타임이 실행하는 스크립트
다음에 뭘 실행할지 정하는 쪽	Claude, 턴마다	Claude, 프롬프트에 따라	리드 에이전트, 턴마다	스크립트
중간 결과가 사는 곳	Claude의 컨텍스트 창	Claude의 컨텍스트 창	공유 태스크 리스트	스크립트 변수
반복 가능한 것	작업자 정의	지시	팀 정의	조율 자체
규모	턴당 몇 개의 위임 작업	서브에이전트와 동일	소수의 장기 실행 피어	실행당 수십~수백 에이전트
중단	턴을 다시 시작함	턴을 다시 시작함	팀원은 계속 실행	같은 세션에서 재개 가능

워크플로우는 플랜을 코드로 옮겨요. 서브에이전트·스킬·에이전트 팀에서는 Claude가 오케스트레이터라서 턴마다 무엇을 생성하거나 할당할지 결정하고 모든 결과가 컨텍스트 창에 들어와요. 반면 워크플로우 스크립트는 루프·분기·중간 결과를 스스로 쥐고 있으므로 Claude의 컨텍스트에는 최종 답만 남습니다.

플랜을 코드로 옮기면 단순히 에이전트를 더 돌리는 것 이상으로, 반복 가능한 품질 패턴까지 적용할 수 있어요. 독립 에이전트들이 서로의 발견을 적대적으로(adversarially) 검토하게 하거나, 여러 각도에서 플랜을 초안하고 서로 비교하게 할 수 있어 더 신뢰할 만한 결과를 얻습니다.

번들 워크플로우 실행하기

워크플로우를 바로 체험하는 가장 빠른 길은 /deep-research, 즉 Claude Code가 다양한 소스의 질문을 조사하기 위해 포함하는 내장 워크플로우를 실행하는 거예요. 세션이 자유로운 동안 에이전트들이 백그라운드에서 일련의 단계를 진행하는 모습을 보고, 턴별 기록 대신 보고서 하나를 받습니다.

워크플로우 실행: /deep-research를 조사하고 싶은 질문과 함께 실행하면 여러 각도로 웹 검색을 펼치고, 찾은 소스를 가져와 상호 검증한 뒤 인용된 보고서를 종합합니다.

/deep-research What changed in the Node.js permission model between v20 and v22?

워크플로우 허용: Claude Code가 워크플로우를 허용할지 묻습니다. Yes를 선택하면 계속됩니다. 정확한 프롬프트는 권한 모드에 따라 달라지며, 모드별 옵션은 실행 전 플랜 승인을 참고하세요.

진행 상황 보기: 실행이 백그라운드에서 시작됩니다. /workflows를 실행하고 화살표 키로 실행을 선택한 뒤 Enter를 눌러 진행 뷰를 엽니다:

/workflows

이 뷰는 각 단계의 에이전트 수, 토큰 합계, 경과 시간을 보여줘요. 단계를 파고들면 해당 에이전트와 각자가 찾은 결과를 볼 수 있습니다. 전체 컨트롤은 실행 보기를 참고하세요. 입력 박스 아래 작업 패널에서도 볼 수 있습니다. 실행 중에 한 줄 진행 요약이 나타나며, 아래 화살표로 포커스한 뒤 Enter로 펼칩니다.

보고서 읽기: 실행이 끝나면 보고서가 세션에 들어와요. 각 주장이 나온 소스를 인용하고, 상호 검증을 통과하지 못한 주장은 이미 걸러냅니다. 검증 에이전트가 주장을 확인할 수 없을 때(예: rate limit이나 API 오류 후)에는 그 주장을 반박된 것으로 세지 않고 미검증(unverified)으로 남겨 둡니다.

번들 워크플로우

Claude Code는 /deep-research를 내장 워크플로우로 포함합니다:

명령	하는 일
`/deep-research <question>`	여러 각도로 질문 웹 검색을 펼치고, 찾은 소스를 가져와 상호 검증하며, 각 주장에 투표하고, 상호 검증을 통과하지 못한 주장이 거른 인용 보고서를 반환합니다. WebSearch 도구가 가능해야 합니다

/deep-research는 호출할 때만 실행됩니다. 직접 저장한 워크플로우도 같은 방식으로 명령이 되며, 번들된 것들과 함께 / 자동완성에 나타납니다.

실행 보기

워크플로우는 백그라운드로 실행되므로 에이전트가 일하는 동안 세션은 응답을 유지해요. 언제든 /workflows를 실행해 실행 중·완료된 워크플로우를 나열하고, 하나를 선택해 진행 뷰를 엽니다.

진행 뷰는 각 단계의 에이전트 수·토큰 합계·경과 시간을 보여줘요. 푸터에는 각 동작의 키가 나옵니다:

키	동작
`↑` / `↓`	단계 또는 에이전트 선택
`Enter` 또는 `→`	선택한 단계로 파고들기, 그다음 에이전트 상세로. 상세에서 `Enter`는 펼치거나 접음
`Esc` 또는 `←`	한 단계 뒤로. v2.1.203~v2.1.205에서는 `←`가 단계/에이전트를 벗어나지 못했으니 해당 버전은 `Esc` 사용
`j` / `k`	에이전트 상세가 넘칠 때 스크롤
`f`	선택한 단계의 에이전트 목록을 상태별로 필터. 다시 누르면 순환
`p`	실행 일시정지 또는 재개
`x`	선택한 에이전트 정지, 또는 포커스가 실행에 있을 때 전체 워크플로우 정지
`r`	선택한 실행 중 에이전트 재시작
`s`	실행의 스크립트를 명령으로 저장

에이전트 상세에는 에이전트의 프롬프트, 최근 도구 호출, 결과가 나와요. 각 호출은 아직 실행 중인지·실패했는지 같은 상태를 보여줍니다. 에이전트가 자신의 태스크 리스트를 유지하면 그것도 각 태스크 상태와 함께 표시됩니다.

Enter를 눌러 상세를 펼치면 프롬프트와 결과가 전체로 보이고, 나열된 각 호출의 입력과 결과의 시작 부분이 보입니다.

Claude가 워크플로우를 작성하게 하기

두 가지 방법이 있어요.

프롬프트에서 워크플로우 요청하기: 자신의 말로, 또는 키워드 ultracode를 포함해 요청하면 Claude가 작업에 맞는 워크플로우를 작성합니다.
ultracode로 Claude가 결정하게 하기: /effort ultracode를 설정하면 Claude가 세션의 모든 실질 작업에 워크플로우를 계획합니다.

이미 존재하는 워크플로우 명령(번들 워크플로우인 /deep-research나 저장한 것)을 실행할 수도 있어요.

프롬프트에서 워크플로우 요청하기

세션의 effort 수준을 바꾸지 않고 단일 작업을 워크플로우로 실행하려면 프롬프트에 키워드 ultracode를 포함하세요. "use a workflow"나 "run a workflow"처럼 자신의 말로 요청해도 됩니다. Claude는 직접 요청을 같은 옵트인으로 취급합니다.

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude Code가 입력에서 키워드를 강조하고, Claude는 작업을 턴별로 진행하는 대신 워크플로우 스크립트를 작성해요. 키워드는 단지 Claude가 작업을 어떻게 구조화할지만 정합니다. 에이전트의 도구 호출은 세션의 다른 도구 호출과 동일한 권한 검사와 샌드박싱을 받습니다.

원하는 대로 실행이 됐다면 나중에 명령으로 저장할 수 있어요. 다른 방식으로 만든 오케스트레이터(서브에이전트 프롬프트 폴더나 작업을 펼치는 스킬 등)가 이미 있다면, 그걸 가리키며 같은 일을 하는 워크플로우를 요청할 수 있습니다.

키워드 해제 또는 끄기: 워크플로우를 시작하려던 게 아니라면 macOS에서 Option+W, Windows·Linux에서 Alt+W를 눌러 이 프롬프트의 강조를 해제하거나, 커서가 강조된 키워드 바로 뒤에 있을 때 backspace를 누르세요. 키워드가 아예 발동하지 않게 하려면 /config에서 Ultracode keyword trigger를 꺼야 합니다.

키워드가 작동하는 곳: 키워드는 여러분이 직접 입력하는 프롬프트에서만 옵트인입니다. 인터랙티브 프롬프트, IDE 확장 패널, Remote Control 클라이언트, 또는 키보드 입력의 origin을 { kind: "human" }으로 스탬프하는 Agent SDK 애플리케이션에서요. 다른 경로로 세션에 도달하면 워크플로우를 시작하지 않습니다:

-p로 전달된 프롬프트
Agent SDK 애플리케이션이 인간 입력으로 스탬프하지 않고 보낸 프롬프트
예약된 태스크 프롬프트
대화로 중계된 웹훅 페이로드 또는 풀 리퀘스트 댓글

참고: v2.1.210 이전에는 키워드가 웹훅 페이로드나 대화로 중계된 PR 댓글을 포함해 이 모든 경로에서도 워크플로우를 시작했습니다.

ultracode로 Claude가 결정하게 하기

Ultracode는 xhigh 추론 effort와 자동 워크플로우 조율을 결합한 Claude Code 설정이에요. 켜면 Claude가 요청을 기다리는 대신 각 실질 작업에 워크플로우를 계획합니다.

/effort ultracode

ultracode를 켠 채 세션을 시작하려면 claude --effort ultracode로 실행하세요. Claude Code v2.1.203 이상이 필요합니다. 모델을 고르면서 켜려면 /model 선택기의 effort 슬라이더를 화살표 키로 ultracode로 옮기세요. ultracode를 켜는 경로는 Adjust effort level에 나와 있어요.

ultracode를 켜면 Claude가 언제 작업이 워크플로우를 받을 만한지 결정합니다. 단일 요청이 연달아 여러 워크플로우로 바뀔 수 있어요. 하나는 코드 이해, 하나는 변경, 하나는 검증. 이것은 세션의 모든 작업에 적용되므로, 각 요청이 낮은 effort 수준보다 더 많은 토큰을 쓰고 더 오래 걸립니다.

/effort ultracode는 현재 세션에만 적용되고, 모든 세션이 그렇게 시작하게 하려면 ultracode 설정을 지정하세요. 일상 작업으로 돌아갈 때는 /effort high로 내리세요. /effort 메뉴는 ultracode가 가능할 때만 이를 제안합니다.

실행 전 플랜 승인

CLI에서 실행별 프롬프트는 계획된 단계와 다음 옵션을 보여줍니다:

Yes, run it: 실행 시작
Yes, and don't ask again for <name> in <path>: 시작하고, 앞으로 이 프로젝트에서 이 워크플로우의 프롬프트를 건너뜀. Claude Code는 번들·저장·플러그인 워크플로우를 이름으로 실행할 때만 이 옵션을 제공하며, 현재 작업용으로 Claude가 작성한 스크립트에는 제공하지 않음
View raw script: 결정 전에 스크립트 읽기
No: 취소

Ctrl+G는 에디터에서 스크립트를 엽니다. Tab은 실행 시작 전에 프롬프트를 조정하게 해 줍니다.

이 프롬프트를 볼지 여부는 권한 모드에 따라 달라집니다:

권한 모드	프롬프트 시점
Auto	최초 실행만. 어떤 Yes든 사용자 설정에 동의를 기록하고 이후 실행은 프롬프트 없이 시작. ultracode가 켜지면 완전히 건너뜀
Manual, accept edits	매 실행. 해당 워크플로우에 대해 이 프로젝트에서 Yes, and don't ask again을 선택하지 않았다면
Bypass permissions	프롬프트하지 않음. 실행이 즉시 시작됨
`claude -p`, Agent SDK	프롬프트하지 않음

claude -p와 Agent SDK에서 Claude Code는 이 프롬프트를 절대 보여주지 않아요. Workflow 도구 호출을 세션의 나머지와 같은 권한 평가로 실행하므로, deny 규칙, ask 규칙, dontAsk 모드가 다른 모든 도구 호출처럼 실행에 적용됩니다. 이 실행에서 워크플로우를 시작하게 하려면 다음 중 하나를 사용하세요:

권한 규칙: 허용 규칙의 Workflow는 모든 워크플로우를 승인하고, Workflow(<name>)는 이름으로 하나의 저장된 워크플로우를 승인합니다.
Auto 권한 모드: 분류기가 호출을 검토하고 승인할 수 있습니다.
Bypass permissions 모드: Claude Code가 호출을 승인합니다.
PreToolUse 훅: 호출에 대해 allow를 반환하는 훅이 승인합니다.
여러분의 호스트: --permission-prompt-tool이 승인하거나, Agent SDK라면 canUseTool 콜백이나 PermissionRequest 훅이 승인합니다.

Desktop 앱에서는 승인 카드가 워크플로우 이름, 단계 목록, 토큰 사용 경고를 보여주며 Once, Always, Deny 동작이 있습니다. 진행 뷰는 Background tasks 사이드 패널에 나타납니다.

워크플로우가 생성하는 서브에이전트는 여러분의 권한 규칙을 사용하며, Claude Code는 서브에이전트가 실행되는 권한 모드 규칙에 따라 그들의 권한 모드를 정합니다. 긴 실행 중 프롬프트를 피하려면 시작 전에 에이전트가 필요한 도구를 허용 규칙에 추가하세요.

재사용을 위해 워크플로우 저장하기

Claude가 반복할 작업용 워크플로우를 작성하면, 그 실행의 스크립트를 명령으로 저장할 수 있어요. 모든 브랜치에서 실행하는 리뷰 같은 과정이 매번 같은 조율을 실행하게 됩니다.

/workflows를 실행하고 유지할 실행을 선택한 뒤 s를 누르세요. 저장 대화상자에서 Tab은 두 저장 위치를 전환합니다:

프로젝트의 .claude/workflows/: 리포를 클론하는 모두와 공유
홈 디렉터리의 ~/.claude/workflows/: 모든 프로젝트에서 사용 가능, 자신만 보임. CLAUDE_CONFIG_DIR를 설정했다면 이 위치는 그 경로 아래의 workflows/ 디렉터리입니다

저장 대화상자는 개인 위치의 해석된 경로를 보여줍니다.

Enter를 누르면 저장됩니다. 이후 세션에서 어느 위치든 워크플로우는 /<name>으로 실행됩니다.

Claude Code는 쓰기 전에 저장 위치의 심볼릭 링크를 확인하고, 링크를 통해 쓰는 대신 오류를 표시합니다. 확인 내용은 저장 위치에 따라 달라집니다:

프로젝트 위치: .claude, .claude/workflows, 또는 대상 파일이 심볼릭 링크면 거부합니다.
개인 위치: 대상 파일 자체만 심볼릭 링크면 거부하므로, dotfiles 도구가 관리하는 ~/.claude 디렉터리는 계속 동작합니다.

v2.1.216 이전에는 Claude Code가 링크를 따라가, 파일을 선택한 위치 밖에 놓을 수 있었습니다.

여러 .claude/ 디렉터리가 있는 모노레포에서는 워크플로우를 적용 대상 패키지 옆에 둘 수 있어요. v2.1.178부터 프로젝트 위치 저장은 작업 디렉터리와 리포지토리 루트 사이에 이미 존재하는 가장 가까운 .claude/workflows/ 디렉터리에 쓰고, 없으면 리포지토리 루트에 씁니다. 프로젝트 워크플로우는 그 경로를 따라 있는 모든 .claude/workflows/에서도 로드되며, 두 곳이 같은 이름을 정의하면 작업 디렉터리에 가장 가까운 것을 실행합니다.

프로젝트 워크플로우와 개인 워크플로우가 이름을 공유하면 프로젝트 것이 실행됩니다.

플러그인으로 워크플로우 배포하기

팀이나 리포지토리 전반에 워크플로우를 공유하려면 플러그인에 포함하세요. 스크립트를 플러그인 루트의 workflows/ 디렉터리에 두거나, workflows 매니페스트 필드로 다른 위치를 가리키세요.

플러그인 워크플로우는 플러그인 이름으로 네임스페이스됩니다. meta.name이 release-audit인 스크립트를 포함한 acme-tools 플러그인은 /acme-tools:release-audit으로 실행됩니다.

저장된 워크플로우에 입력 전달하기

저장된 워크플로우는 args 파라미터로 입력을 받을 수 있어요. 스크립트는 이를 args라는 전역으로 읽습니다. 매 실행마다 스크립트를 편집하는 대신 호출 시점에 리서치 질문, 대상 경로 목록, 설정 객체를 공급하는 데 쓰세요.

다음 프롬프트는 이슈 번호 목록과 함께 저장된 워크플로우를 실행합니다:

Run /triage-issues on issues 1024, 1025, and 1030

Claude는 목록을 구조화된 데이터로 전달하므로, 스크립트는 먼저 파싱하지 않고 args에서 배열·객체 메서드를 직접 호출할 수 있어요. args가 생략되면 스크립트 안에서 전역은 undefined입니다.

워크플로우 프롬프트 예시

워크플로우는 작업이 한 에이전트가 컨텍스트에 담기에는 너무 클 때, 또는 같은 단계를 많은 항목에 실행해야 할 때 가장 잘 맞아요. 아래 프롬프트는 일반적인 형태를 보여줍니다. 각각은 그 작업에 워크플로우를 작성·실행하라고 Claude에게 요청하며, 스크립트를 직접 작성하지는 않습니다.

같은 문제로 많은 파일 감사하기: 파일 하나당 에이전트 하나를 펼친 뒤, 발견 결과를 모으고 검증합니다.

use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

검사가 통과할 때까지 계속 고치기: 검사기를 실행하고, 실패한 것을 고치고, 통과하거나 더 이상 진전이 없을 때까지 반복합니다.

use a workflow to run npx tsc --noEmit and keep fixing the 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 JavaScript to TypeScript, working on each file in its own isolated copy

변경된 모든 파일을 리뷰하고 요약 하나 쓰기: 파일당 리뷰어를 실행한 뒤, 모든 발견을 순위를 매겨 중복을 제거하는 에이전트 하나에 넘깁니다.

use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

많은 소스에 걸쳐 주제 리서치하기: 변경 로그·이슈·문서에 읽기 에이전트를 펼친 뒤 종합합니다. 번들 /deep-research 워크플로우가 이 일을 하며, 더 좁은 버전을 직접 설명할 수도 있어요.

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

목록이 늘지 않을 때까지 문제 찾기: 라운드를 거듭하며 검색하고 새 라운드가 새것을 찾지 못하면 멈춥니다.

use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

저장된 스크립트의 생김새

워크플로우를 저장하면 .claude/workflows/의 파일은 meta 블록과 서브에이전트를 조율하는 스크립트 본문을 담아요. 보통 편집할 필요는 없지만, Claude가 생성한 것을 알아볼 수 있도록 작은 예의 형태는 이렇습니다:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

본문은 최상위 await가 있는 일반 JavaScript예요. agent()는 서브에이전트 하나를 생성하고, pipeline()은 목록의 항목마다 하나씩 실행하며, parallel()은 일련의 에이전트 작업을 동시에 실행하고 전부를 기다립니다.

agent() 호출은 실행 중간에 멈추거나 복구 불가능한 API 오류에 부딪히면 null로 해석돼요. auto 모드에서는 분류기가 서브에이전트가 시작하기 전에 agent() 호출을 차단할 수 있습니다. 차단된 호출은 null로 해석되고 실행의 진행 뷰에 이유와 함께 표시됩니다. pipeline()은 각 null을 결과 배열에 유지하므로, 예시가 .filter(Boolean)으로 끝나 그 항목들을 버리는 이유입니다.

agent() 호출에 schema를 전달하면 해당 서브에이전트는 산문 대신 그 형태와 일치하는 JSON을 반환해요. Claude Code는 서브에이전트를 시작하기 전에 스키마를 확인합니다. 스키마가 스스로 모순됨을 증명할 수 있으면 호출은 모순을 이름으로 가리키는 오류와 함께 실패하고 서브에이전트는 시작되지 않습니다. 증명할 수 있는 모순 중 하나는 additionalProperties: false가 배제하는 required 키입니다.

서브에이전트 출력이 다섯 번 시도 후에도 여전히 검증에 실패하면, 호출은 마지막 검증 실패를 포함한 오류와 함께 실패합니다. 시도 횟수를 바꾸려면 MAX_STRUCTURED_OUTPUT_RETRIES를 설정하세요.

저장된 스크립트 편집하기

저장한 워크플로우를 바꾸려면 .js 파일을 편집하거나 Claude에게 변경을 요청하세요. 편집하거나 요청하기 전에 /workflow-authoring 번들 스킬을 실행해 Claude가 따르는 스크립트 작성 레퍼런스를 로드하세요. 이 스킬은 Claude Code v2.1.248 이상이 필요합니다.

편집한 버전을 현재 세션에서 실행하려면 /reload-skills를 실행해 워크플로우 디렉터리를 다시 읽은 뒤 /<name>을 다시 실행하세요.

Claude Code는 파일을 로드·실행할 때 파일의 각 부분에 다음 규칙을 적용합니다:

meta 블록: export const meta를 첫 문장으로 유지하고, name과 description이 있는 일반 객체 리터럴로 유지하세요. 변수·함수 호출·spread 같은 리터럴 외의 값을 포함하면 Claude Code는 / 자동완성에서 /<name>을 뺍니다.
본문: agent(), pipeline(), parallel() 외에 phase()로 뒤따르는 에이전트를 진행 뷰의 제목 아래 그룹화하고, log()로 단계 위에 메시지를 표시하며, args 전역을 읽을 수 있습니다. 본문에 문법 오류가 있으면 워크플로우를 실행할 때 Claude Code가 보고합니다.
phases: meta에 나열한다면 각 항목에 phase()로 전달한 제목과 정확히 같은 제목을 주세요. 항목이 없는 phase() 제목은 자체 진행 그룹을 얻습니다.
타임스탬프와 난수: Claude Code는 Date.now(), Math.random(), 그리고 인자 없는 new Date()를 스크립트 안에서 throw하도록 만들어, 재개된 실행이 같은 agent() 호출을 반복하게 합니다. 대신 args로 타임스탬프를 전달하세요.

단일 실행의 스크립트를 저장된 사본 대신 편집할 수도 있어요. 일시정지 후 재개는 편집된 스크립트를 다시 실행할 때 어떤 에이전트가 다시 실행되는지 다룹니다. Workflow 도구의 입력에 대해서는 Agent SDK 레퍼런스 항목을 보세요.

워크플로우가 어떻게 실행되나

워크플로우 런타임은 대화와 분리된 격리 환경에서 스크립트를 실행해요. 중간 결과는 Claude의 컨텍스트가 아니라 스크립트 변수에 남습니다.

모든 실행은 ~/.claude/projects/의 세션 디렉터리 아래 파일에 스크립트를 씁니다. 실행이 시작될 때 Claude가 그 경로를 받으므로 물어볼 수 있어요. 그 파일을 열어 Claude가 작성한 조율을 읽고, 이전 실행의 스크립트와 diff하고, 편집해 Claude에게 편집된 버전으로 재실행을 요청할 수 있습니다.

Claude는 세션이 이미 읽을 수 있게 허용된 스크립트 파일에서만 워크플로우를 시작할 수 있어요. 작업 디렉터리 밖에 있는 스크립트를 실행하려면 먼저 /add-dir 또는 Read 허용 규칙으로 그 디렉터리를 추가하세요.

런타임은 실행이 진행됨에 따라 각 에이전트의 결과를 추적하는데, 이것이 실행을 같은 세션 안에서 재개 가능하게 만듭니다.

팬아웃의 프롬프트 캐싱

같은 실행의 에이전트들은 서로의 프롬프트 캐시를 읽을 수 있어요. 같은 모델·effort 수준·에이전트 타입·도구·출력 스키마·작업 디렉터리로 실행되는 두 에이전트는 같은 도구-및-시스템-프롬프트 프리픽스를 만들므로, 일치하는 형제의 응답이 시작된 뒤에 시작하는 에이전트는 첫 요청에서 그 형제의 캐시를 읽습니다.

워크플로우 에이전트의 요청은 기본 대화의 캐시 TTL 버킷 밖에 있어서, 그 캐시는 기본 5분 동안 유지됩니다(Claude 구독도 포함). 한 시간 유지하려면 subagentPromptCacheTtl을 1h로 설정하세요. API는 1시간 캐시 쓰기를 더 높은 요율로 청구합니다.

팬아웃이 일치하는 에이전트 여러 개를 한 번에 시작하면, Claude Code는 첫 에이전트의 응답이 시작될 때까지 첫 번째를 제외한 모두를 보류했다가 함께 풀어, 그들의 첫 요청이 각각 미캐시로 처리하는 대신 공유 프리픽스를 읽게 합니다. Claude Code는 보류를 CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS 밀리초로 제한하며 기본값은 5000입니다. 0으로 설정하면 보류를 비활성화합니다.

동작과 한계

런타임은 다음 제약을 적용합니다:

제약	이유
실행 중 사용자 입력 없음	오직 에이전트 권한 프롬프트만 실행을 일시정지할 수 있음. 단계 사이에 서명(sign-off)이 필요하면 각 단계를 자체 워크플로우로 실행
워크플로우 자체에서 직접 파일시스템·셸 접근 없음	에이전트가 읽고·쓰고·명령을 실행함. 스크립트는 에이전트를 조율
모듈 로딩 없음: `import()`를 포함한 스크립트는 실행 시작 전에 실패	스크립트 본문은 일반 JavaScript. 라이브러리가 필요한 작업은 에이전트의 태스크에 넣기
동시 에이전트 최대 16개, CPU 제한 컨테이너 포함 Claude Code가 더 적은 CPU를 가질 때는 더 적음	로컬 리소스 사용 제한
팬아웃에서 첫 에이전트의 프롬프트-캐시 프리픽스를 공유하는 에이전트는 기본으로 그것보다 최대 5초 늦게 시작	첫 번째를 제외한 모두가 첫 에이전트가 캐시한 프리픽스를 각각 미캐시로 처리하는 대신 읽음
단일 `parallel()`·`pipeline()` 호출에 최대 4,096개 항목: 런타임은 더 긴 목록을 오류로 거부	조용한 상한은 스크립트에 알리지 않고 작업량 일부를 버릴 것
실행당 총 에이전트 1,000개	폭주 루프 방지

실행 관리

실행이 시작되면 /workflows 뷰에서, 또는 입력 박스 아래 작업 패널의 진행 줄을 펼쳐 관리합니다.

실행을 정지하면 그 에이전트의 프로세스가 아직 실행 중인 동안 작업 패널에 남아요. 다시 정지하면 Claude Code가 그 프로세스에 재신호합니다.

일시정지 후 재개

일시정지한 실행은 /workflows에서 선택하고 p를 눌러 재개해요. 정지한 실행은 Claude에게 같은 스크립트로 워크플로우를 재실행하라고 요청하세요. 정지된 실행의 에이전트가 아직 종료하지 않았다면, 그 에이전트의 두 번째 사본이 나란히 실행될 수 없도록 Claude Code는 전부 종료될 때까지 재실행을 거부합니다.

Claude Code는 실행이 시작된 순서로 재생하며, 각 에이전트는 저장된 결과를 반환하거나 다시 실행됩니다:

완료: 저장된 결과를 반환합니다. 스크립트를 편집했거나 이전 에이전트가 다른 것을 반환해서 프롬프트가 이전 실행과 다른 첫 에이전트는 다시 실행되고, 완료된 것까지 포함해 그 뒤의 모든 에이전트도 다시 실행됩니다.
정지했을 때 아직 실행 중: 처음부터 시작합니다. 전체 실행을 정지하는 것은 어떤 에이전트도 실패로 세지 않습니다.
실패: 다시 실행되고, 완료된 것까지 포함해 그 뒤에 시작된 모든 에이전트도 다시 실행됩니다. /workflows에서 선택하고 x를 눌러 에이전트 하나만 정지하는 것은 실패로 간주합니다.

마지막 경우는 팬아웃 중간의 실패가 이미 끝난 작업을 다시 실행한다는 뜻이에요. 스크립트가 A, B, C, D 순서로 시작하고 B가 실패하면, 재실행은 A를 캐시에서 반환하고 B, C, D를 다시 실행합니다.

같은 Claude Code 세션 안에서 실행을 재개할 수 있어요. 세션을 떠날 때 실행 중인 워크플로우가 어떻게 되느냐는 떠나는 방식에 달려 있습니다:

세션을 백그라운드하면 Claude Code가 백그라운드 세션에서 같은 방식으로 실행을 재생하고 계속합니다.
워크플로우가 실행되는 동안 Claude Code를 종료하고 agent view가 켜져 있으면, 종료 대화상자가 Move to background and exit을 제공하고 같은 방식으로 실행을 이어갑니다. 대신 Exit and stop tasks를 선택하거나 그 옵션이 제공되지 않으면 실행은 세션과 함께 멈춥니다. Claude Code는 실행의 저장된 결과를 ~/.claude/projects/의 그 세션 디렉터리 아래에 보관하므로, claude --resume으로 재개한 세션은 Claude에게 워크플로우 재실행을 요청할 때 그것들을 재생할 수 있습니다. 새로 시작한 세션에서는 Claude가 재실행할 이전 실행이 없고 워크플로우를 새 실행으로 다시 시작합니다.

클라우드 세션에서 Claude Code는 실행 결과를 세션의 대화 기록과 함께 저장해, 세션의 VM이 회수되어도 살아남습니다. 그런 세션을 다시 열고 워크플로우 재실행을 요청하면 완료된 에이전트는 여전히 저장된 결과를 반환합니다.

로컬·클라우드 세션 모두에서, Claude가 이전 실행을 재실행하는데 Claude Code가 그 실행의 저장된 결과를 아예 찾을 수 없으면, 재실행은 스스로 새로 시작하는 대신 nothing to resume 오류로 실패합니다. Claude에게 워크플로우를 새 실행으로 다시 시작하라고 요청하세요.

비용

워크플로우는 많은 에이전트를 생성하므로, 단일 실행이 대화에서 같은 작업을 처리하는 것보다 훨씬 많은 토큰을 쓸 수 있어요. 실행은 다른 세션처럼 플랜의 사용량과 rate limit에 포함됩니다.

큰 작업에 투입하기 전 지출을 가늠하려면 먼저 작은 조각으로 실행하세요. 리포 전체 대신 디렉터리 하나, 넓은 질문 대신 좁은 질문으로요. /workflows 뷰는 실행이 진행됨에 따라 각 에이전트의 토큰 사용량을 보여주고, 언제든 실행을 정지할 수 있으며 보통 완료된 작업을 잃지 않습니다. 일시정지 후 재개가 정지된 실행이 무엇을 유지하는지 다룹니다. 런타임의 에이전트 상한이 단일 실행이 생성할 수 있는 에이전트 수를 제한해 폭주 스크립트의 비용 경계를 만듭니다. 더 적은 에이전트로 유지하려면 small 크기 가이드라인을 선택하세요.

Claude Code는 비정상적으로 커지는 실행도 표시합니다. 워크플로우가 25개 이상의 에이전트를 예약하거나 예상 토큰 합계가 150만을 넘으면, 입력 박스 아래 작업 패널의 진행 줄에 Large workflow 경고가 나타납니다. 이 경고는 실행을 정지할 수 있는 /workflows를 가리킵니다.

경고는 조언일 뿐입니다. 실행을 일시정지하거나 제한하지 않아요. 경고가 보이는 시점을 바꾸는 설정 두 가지:

크기 가이드라인을 직접 고르면 그 에이전트 수가 25-에이전트 임계값을 대체합니다. 내장 기본 가이드라인은 임계값을 25로 둡니다.
ultracode가 켜진 세션은 경고를 보여주지 않습니다. ultracode를 켜는 것 자체가 큰 실행에 옵트인하기 때문입니다.

Claude Code는 각 워크플로우 에이전트의 모델을 서브에이전트에 쓰는 것과 같은 순서로 고릅니다. 스크립트가 단계에 이름을 붙인 모델은 그 순서에서 호출별(invocation) 모델로 간주됩니다. 다른 것이 지정하지 않으면 에이전트는 세션의 모델에서 실행됩니다.

모델 비용을 통제하려면:

일상 작업에서 보통 더 작은 모델로 전환한다면 큰 실행 전에 /model을 확인하세요
작업을 설명할 때 굳이 강한 모델이 필요 없는 단계에는 더 작은 모델을 쓰라고 Claude에게 요청하세요

조직의 availableModels 허용 목록이 스크립트가 에이전트에 요청한 모델을 차단하면, 그 에이전트는 서브에이전트와 같은 대체 규칙을 따라 대체 모델에서 실행됩니다. /workflows의 실행 진행 뷰는 요청된 모델과 대체된 모델 둘 다 이름을 지은 경고를 보여줍니다.

크기 가이드라인 설정

크기 가이드라인은 Claude가 동적 워크플로우를 작성할 때 몇 개의 에이전트를 목표로 할지 알려줘요. Claude Code는 가이드라인을 상한이 아닌 조언으로 Claude에게 보내므로, 다른 규모를 요구하는 프롬프트가 여전히 그것을 덮어씁니다. Claude Code v2.1.202 이상이 필요합니다.

각 값은 에이전트 수로 매핑됩니다:

값	Claude가 목표로 하는 에이전트 수
`unrestricted`	가이드라인 없음: Claude가 작업에 맞게 크기 조정
`small`	에이전트 5개 미만
`medium`	에이전트 15개 미만
`large`	에이전트 50개 미만

기본값은 medium이에요. 값을 고르기 전까지 /config 행은 medium (default)를, 워크플로우의 Running in background 줄은 medium size (/config)를 보여줍니다. Claude Code v2.1.219 이상이 필요하며, 이전 버전은 unrestricted가 기본값입니다.

가이드라인을 바꾸려면 /config의 Dynamic workflow size 설정에서 값을 고르거나 /config workflowSizeGuideline=small을 실행하세요. v2.1.219 이상에서는 workflowSizeGuideline 키를 어떤 설정 파일에서든 설정할 수 있으며, 그 값이 /config보다 우선하고 설정 파일이 제공하는 동안 Claude Code는 /config 행을 숨깁니다.

변경 사항은 다음 프롬프트부터 적용됩니다. 런타임 에이전트 상한은 설정과 무관하게 여전히 적용됩니다.

워크플로우 끄기

워크플로우는 CLI, Desktop 앱, IDE 확장, claude -p의 비대화형 모드, Agent SDK에서 사용할 수 있습니다. 같은 비활성화 설정이 모든 표면에 적용됩니다.

자신에게 워크플로우를 끄려면:

/config에서 Dynamic workflows를 끄세요. 세션 간 유지됩니다.
~/.claude/settings.json에 "disableWorkflows": true를 설정하세요. 세션 간 유지됩니다.
CLAUDE_CODE_DISABLE_WORKFLOWS=1을 설정하세요. 시작 시 읽히므로 어디서든 적용됩니다.

조직 전체에서 끄려면 관리 설정에 "disableWorkflows": true를 설정하거나 Claude Code 관리자 설정 페이지의 토글을 사용하세요.

워크플로우가 비활성화되면 번들 워크플로우 명령과 /workflow-authoring 스킬이 없어지고, ultracode 키워드가 더 이상 실행을 촉발하지 않으며, /effort 메뉴에서 ultracode가 제거됩니다.

더 알아보기

에이전트 병렬 실행: 서브에이전트, 에이전트 뷰, 에이전트 팀, 워크플로우 비교
커스텀 서브에이전트 만들기: 워크플로우가 조율하는 작업자 프리미티브
비용 관리: 다중 에이전트 실행이 사용량 한도에 어떻게 집계되는지