요약
- 동적 워크플로우는 Claude가 작성한 JavaScript 스크립트로 수십~수백 개의 서브에이전트를 백그라운드에서 조율하는 기능이다.
- 핵심 목적은 "한 번의 대화 컨텍스트로 감당 안 되는 규모의 작업"을, 컨텍스트를 오염시키지 않고 코드로 외주화해 처리하는 것이다.
- 중간 결과를 Claude 컨텍스트가 아니라 스크립트 변수에 두기 때문에, 수백 개 에이전트를 돌려도 최종 답만 컨텍스트에 남는다.
본문
무엇인가
서브에이전트·스킬·에이전트 팀과 동렬에 있는 다단계 작업 조율 수단이다. 차이는 "계획(조율 로직)을 누가 들고 있느냐"에 있다.
| 서브에이전트 | 스킬 | 에이전트 팀 | 워크플로우 | |
|---|---|---|---|---|
| 다음에 뭘 실행할지 결정 | Claude, 차례대로 | Claude, 프롬프트 따라 | 리드 에이전트 | 스크립트 |
| 중간 결과 위치 | Claude 컨텍스트 | Claude 컨텍스트 | 공유 작업 목록 | 스크립트 변수 |
| 반복 가능한 것 | 워커 정의 | 지침 | 팀 정의 | 조율 자체 |
| 규모 | 차례당 몇 개 | 동일 | 소수의 장기 피어 | 실행당 수십~수백 개 |
서브에이전트/스킬/팀에서는 Claude가 조율자라서 모든 중간 결과가 컨텍스트 윈도우로 들어온다. 워크플로우는 루프·분기·중간결과를 스크립트가 자체 보유하므로 Claude 컨텍스트엔 최종 답변만 남는다.
왜 쓰는가 — 세 가지 목적
- 규모(Scale): 컨텍스트 한계 돌파. 500개 파일을 마이그레이션해도 500개 중간 결과가 컨텍스트에 안 쌓인다. 중간 결과가 스크립트 변수에 있기 때문.
- 신뢰성(Confidence): 단순히 에이전트를 많이 돌리는 게 아니라 반복 가능한 품질 패턴을 코드로 박는다. 예) 독립 에이전트들이 서로의 발견을 적대적으로 교차검증한 뒤에만 보고 → 그럴듯하지만 틀린 결과를 거름. 한 계획을 여러 각도로 짜서 비교 후 합성 → 단일 패스보다 신뢰도 ↑.
- 재사용성(Reproducibility): 조율 로직 자체가 스크립트라 저장해두고
/<name>으로 매번 똑같이 돌릴 수 있다.
적합한 작업
코드베이스 전체 버그 스윕, 대규모 마이그레이션, 소스 간 교차검증 리서치, 한 번에 커밋하기 전 여러 독립 각도로 짜볼 가치가 있는 어려운 계획. 한두 줄 수정은 오버킬이고 토큰만 많이 쓴다.
실행/생성 방법
- 번들 워크플로우:
/deep-research <질문>— 웹검색 fan-out → 소스 교차검증 → 검증 못 통과한 주장은 필터링된 인용 보고서. - 프롬프트에
ultracode키워드 포함하거나 "워크플로우 써서…"라고 자연어로 요청하면 Claude가 그 작업용 스크립트를 작성. /effort ultracode: 세션 전체에서 모든 실질적 작업을 워크플로우로 계획 (xhigh 추론 + 자동 조율, 토큰 많이 씀)./workflows로 진행상황 보기·일시정지·중지·s로 명령 저장. 저장 위치는.claude/workflows/(프로젝트 공유) 또는~/.claude/workflows/(개인). 저장된 워크플로우는args전역변수로 입력을 받는다.
런타임 제약
- 동시 에이전트 최대 16개, 실행당 총 1,000개 상한(폭주 방지).
- 실행 중 사용자 입력 불가 — 에이전트 권한 프롬프트만 일시정지 가능. 단계 간 승인이 필요하면 각 단계를 별도 워크플로우로 분리.
- 워크플로우 자체는 파일시스템/셸 직접 접근 없음. 에이전트가 읽고 쓰고 실행하며, 스크립트는 에이전트를 조율만 한다.
- 같은 세션 내에서는 일시정지 후 재개 가능(완료된 에이전트는 캐시 결과 반환). Claude Code를 종료하면 다음 세션은 새로 시작.
요구사항: Claude Code v2.1.154+, 모든 유료 요금제(Pro는 /config에서 활성화). 끄려면 /config, settings.json의 "disableWorkflows": true, 또는 CLAUDE_CODE_DISABLE_WORKFLOWS=1.