동적 워크플로우로 서브에이전트를 대규모로 오케스트레이션
동적 워크플로우는 Claude가 작성하고 당신이 다시 실행할 수 있는 스크립트로 수많은 서브에이전트를 조율합니다. 코드베이스 감사, 대규모 마이그레이션, 출처를 서로 교차 검증해야 하는 리서치에 적합합니다.
워크플로우는 "계획"을 코드로 옮긴다.
서브에이전트·스킬·에이전트 팀에서는 Claude가 턴마다 무엇을 띄울지 결정하고 모든 결과가 컨텍스트 윈도우에 쌓인다. 워크플로우 스크립트는 루프·분기·중간 결과를 스스로 보관하므로, Claude의 컨텍스트에는 최종 답변만 남는다.
동적 워크플로우는 리서치 프리뷰 단계입니다. Claude Code v2.1.154 이상이 필요하며 모든 유료 플랜과 Anthropic API, Amazon Bedrock·Google Cloud Vertex AI· Microsoft Foundry에서 사용할 수 있습니다. Pro에서는 /config의 Dynamic workflows 항목에서 켭니다.
1. 언제 워크플로우를 쓰는가
서브에이전트·스킬·에이전트 팀·워크플로우는 모두 다단계 작업을 수행할 수 있습니다. 차이는 누가 계획을 쥐고 있느냐입니다. 한 대화가 조율할 수 있는 것보다 많은 에이전트가 필요하거나, 오케스트레이션 자체를 읽고 다시 돌릴 수 있는 스크립트로 코드화하고 싶을 때 워크플로우를 선택합니다.
| 서브에이전트 | 스킬 | 에이전트 팀 | 워크플로우 | |
|---|---|---|---|---|
| 정체 | Claude가 띄우는 워커 | Claude가 따르는 지침 | 동료 세션을 감독하는 리드 에이전트 | 런타임이 실행하는 스크립트 |
| 다음 작업 결정 주체 | Claude (턴 단위) | Claude (프롬프트에 따라) | 리드 에이전트 (턴 단위) | 스크립트 |
| 중간 결과 저장 위치 | Claude의 컨텍스트 윈도우 | Claude의 컨텍스트 윈도우 | 공유 작업 목록 | 스크립트 변수 |
| 재사용 대상 | 워커 정의 | 지침 | 팀 정의 | 오케스트레이션 자체 |
| 규모 | 턴당 소수의 위임 작업 | 서브에이전트와 동일 | 장기 실행 동료 몇 명 | 실행당 수십~수백 에이전트 |
| 중단 시 | 턴 재시작 | 턴 재시작 | 팀원은 계속 실행 | 같은 세션 내에서 재개 가능 |
계획을 코드로 옮기면 단순히 에이전트를 더 돌리는 것을 넘어 반복 가능한 품질 패턴을 적용할 수 있습니다. 독립된 에이전트들이 서로의 결과를 적대적으로 검증한 뒤 보고하게 하거나, 하나의 계획을 여러 각도에서 작성해 서로 견주게 만들어 단일 패스보다 신뢰할 수 있는 결과를 얻습니다.
2. 번들 워크플로우 실행하기 (/deep-research)
워크플로우를 가장 빠르게 체험하는 방법은 /deep-research를 실행하는 것입니다. Claude Code에 내장된 워크플로우로, 하나의 질문을 여러 출처에 걸쳐 조사합니다. 에이전트들이 백그라운드에서 여러 단계를 거치는 동안 세션은 그대로 쓸 수 있고, 턴 단위 기록 대신 마지막에 하나의 리포트를 받습니다.
/deep-research Node.js의 권한 모델은 v20에서 v22로 가며 무엇이 바뀌었나?
워크플로우 실행
/deep-research에 조사할 질문을 넘긴다. 여러 각도로 웹 검색을 펼치고, 찾은 출처를 가져와 교차 검증한 뒤, 인용이 달린 리포트로 종합한다.
워크플로우 허용
Claude Code가 워크플로우 실행 여부를 묻는다. Yes를 선택해 진행한다. 정확한 프롬프트는 권한 모드에 따라 달라진다.
진행 상황 관찰
실행은 백그라운드에서 시작되어 세션은 그대로 사용할 수 있다. /workflows로 실행을 선택해 진행 뷰를 열면 단계별 에이전트 수·토큰 합계·경과 시간을 볼 수 있다.
리포트 읽기
실행이 끝나면 리포트가 세션에 도착한다. 각 주장이 인용한 출처가 표시되고, 교차 검증을 통과하지 못한 주장은 이미 걸러져 있다.
진행 뷰 단축키 (/workflows)
| ↑ / ↓ | 단계 또는 에이전트 선택 |
| Enter / → | 선택한 단계로 진입, 다시 에이전트로 들어가 프롬프트·최근 툴 호출·결과 확인 |
| Esc | 한 단계 뒤로 |
| j / k | 에이전트 상세가 넘칠 때 스크롤 |
| p | 실행 일시정지/재개 |
| x | 선택 에이전트 중지, 포커스가 실행이면 워크플로우 전체 중지 |
| r | 선택한 실행 중 에이전트 재시작 |
| s | 실행 스크립트를 커맨드로 저장 |
3. Claude에게 워크플로우를 작성시키기
내 작업을 위한 워크플로우를 Claude가 작성하게 만드는 두 가지 방법이 있습니다.
프롬프트에 워크플로우를 요청
세션의 effort 레벨을 바꾸지 않고 단일 작업을 워크플로우로 돌리려면 프롬프트에 ultracode 키워드를 포함합니다. "워크플로우를 써줘"처럼 직접 말로 요청해도 같은 옵트인으로 취급됩니다. (v2.1.160 이전에는 트리거 키워드가 workflow였습니다.)
ultracode: src/routes/ 아래 모든 API 엔드포인트에서 누락된 인증 검사를 감사해줘
Ultracode로 Claude가 알아서 판단
Ultracode는 xhigh 추론 effort와 자동 워크플로우 오케스트레이션을 결합한 설정입니다. 켜두면 Claude가 모든 실질적 작업마다 워크플로우를 계획합니다. 하나의 요청이 코드 이해 → 변경 → 검증처럼 여러 워크플로우로 이어질 수 있어 토큰과 시간이 더 듭니다. 현재 세션 동안만 유지되며 /effort high로 되돌립니다.
/effort ultracode
키워드를 의도하지 않았다면 macOS는 Option+W, Windows·Linux는 Alt+W로 하이라이트를 해제할 수 있습니다. 아예 트리거를 끄려면 /config에서 Ultracode keyword trigger를 끕니다.
4. 실행 전 계획 승인하기
CLI에서는 실행마다 계획된 단계와 함께 승인 프롬프트가 표시됩니다. Yes, run it(실행), don't ask again(이 프로젝트에서 이 워크플로우는 다시 묻지 않음), View raw script(스크립트 확인), No(취소) 중 선택합니다. Ctrl+G로 에디터에서 스크립트를 열고, Tab으로 실행 전 프롬프트를 조정할 수 있습니다.
| 권한 모드 | 언제 묻는가 |
|---|---|
| Default, accept edits | 매 실행마다. 단, 해당 워크플로우에 대해 '다시 묻지 않음'을 선택한 경우 제외 |
| Auto | 첫 실행만. Yes를 누르면 사용자 설정에 동의가 기록되어 이후 실행은 묻지 않음. ultracode가 켜져 있으면 완전히 생략 |
| Bypass / claude -p / Agent SDK | 묻지 않음. 즉시 실행 |
권한 모드는 실행 시작 프롬프트만 제어한다. 워크플로우가 띄우는 서브에이전트는 세션 모드와 무관하게 항상 acceptEdits 모드로 실행되며 파일 편집은 자동 승인된다.
허용 목록에 없는 셸 명령·웹 페치·MCP 툴은 실행 도중 여전히 물을 수 있다. 긴 실행에서 이를 피하려면 에이전트가 필요한 명령을 미리 허용 목록에 추가한다.
5. 워크플로우 저장 & 재사용
반복할 작업의 워크플로우를 Claude가 작성했다면, 그 실행의 스크립트를 커맨드로 저장할 수 있습니다. /workflows에서 실행을 선택하고 s를 누른 뒤, 저장 다이얼로그에서 Tab으로 저장 위치를 고르고 Enter로 저장합니다. 이후 세션에서 /<name>으로 실행됩니다.
.claude/workflows/
프로젝트에 저장 — 저장소를 클론한 모두와 공유
~/.claude/workflows/
홈 디렉터리에 저장 — 모든 프로젝트에서, 나에게만 보임
저장한 워크플로우는 args 파라미터로 입력을 받을 수 있습니다. 스크립트는 이를 전역 변수 args로 읽으며, Claude가 구조화된 데이터로 넘기므로 파싱 없이 배열·객체 메서드를 바로 호출할 수 있습니다.
> /triage-issues를 이슈 1024, 1025, 1030에 대해 실행해줘
6. 워크플로우는 어떻게 실행되는가
워크플로우 런타임은 대화와 분리된 격리 환경에서 스크립트를 실행합니다. 중간 결과는 Claude의 컨텍스트가 아니라 스크립트 변수에 머뭅니다. 모든 실행은 스크립트를 ~/.claude/projects/ 아래 세션 디렉터리의 파일로 기록하므로, 그 파일을 열어 Claude가 작성한 오케스트레이션을 읽거나 이전 실행과 diff하거나 편집해 다시 띄울 수 있습니다.
동작과 제약
| 제약 | 이유 |
|---|---|
| 실행 중 사용자 입력 불가 | 에이전트 권한 프롬프트만 실행을 멈출 수 있다. 단계 간 승인이 필요하면 각 단계를 별도 워크플로우로 실행한다 |
| 워크플로우 자체의 직접 파일/셸 접근 불가 | 읽기·쓰기·명령 실행은 에이전트가 한다. 스크립트는 에이전트를 조율할 뿐이다 |
| 동시 에이전트 최대 16개 (코어 적은 머신은 더 적음) | 로컬 자원 사용량을 제한한다 |
| 실행당 총 1,000 에이전트 | 폭주 루프를 방지한다 |
7. 실행 관리: 재개 · 비용 · 끄기
일시정지 후 재개
실행을 멈춰도 재개할 수 있습니다. 이미 끝난 에이전트는 캐시된 결과를 돌려주고 나머지는 실시간으로 돕니다. 단, 재개는 같은 Claude Code 세션 안에서만 동작합니다. 실행 중 Claude Code를 종료하면 다음 세션에서는 워크플로우가 처음부터 시작됩니다.
비용
워크플로우는 많은 에이전트를 띄우므로 한 번의 실행이 같은 작업을 대화로 처리하는 것보다 훨씬 많은 토큰을 쓸 수 있습니다. 큰 작업에 들어가기 전, 한 디렉터리나 좁은 질문 같은 작은 슬라이스로 먼저 돌려 비용을 가늠하세요. 모든 에이전트는 세션의 모델을 사용하므로, /model을 확인하거나 강한 모델이 필요 없는 단계는 더 작은 모델을 쓰도록 요청해 비용을 제어할 수 있습니다.
워크플로우 끄기
/config의 Dynamic workflows 토글을 끄거나, ~/.claude/settings.json에 "disableWorkflows": true를 설정하거나, 환경변수 CLAUDE_CODE_DISABLE_WORKFLOWS=1을 지정합니다. 조직 전체는 managed settings에서 끕니다.