클로드 코드 다이내믹 워크플로 완전 가이드 — 에이전트 수백 개를 배경에서 자동 실행하는 방법

클로드 코드의 다이내믹 워크플로는 클로드가 직접 자바스크립트(JavaScript) 오케스트레이션 스크립트를 작성하고, 그 스크립트가 수십~수백 개의 서브에이전트를 배경에서 병렬 실행하는 기능이다. 사용자는 할 일을 한 줄로 말하면 되고, 나머지는 클로드가 알아서 처리한다.

기존 클로드 코드와의 차이는 여기서 발생한다. 원래 클로드 코드는 단일 에이전트가 파일을 읽고 수정하며 순차적으로 작업하는 방식이다. 프로젝트 규모가 크면 작업이 길어지고, 한 번에 검사할 수 있는 범위도 제한된다. 다이내믹 워크플로는 이 한계를 깬다. 오케스트레이터(클로드)가 작업을 작은 단위로 쪼개고, 각 단위를 독립 서브에이전트에게 동시에 맡긴다.

앤트로픽은 이 기능을 다음처럼 설명한다. "클로드가 수십~수백 개의 병렬 서브에이전트를 실행하는 오케스트레이션 스크립트를 직접 작성하고, 결과가 사용자에게 닿기 전에 검토까지 마친다."

벽시계 시간(실제 걸리는 시간)은 줄어든다. 100개 파일을 혼자 순차로 보면 100번 걸리지만, 10개 서브에이전트가 나눠 보면 약 10번으로 끝난다. 단, 총 토큰 비용은 줄지 않는다. 오케스트레이션 오버헤드가 있어 오히려 늘 수도 있다. 시간이 중요할 때 쓰는 도구다.

다이내믹 워크플로의 핵심은 오케스트레이터-서브에이전트 구조다. 흐름은 다음과 같다.

1. 분해(Decomposition) — 오케스트레이터(상위 클로드)가 사용자 프롬프트를 받아 작업을 여러 하위 작업으로 나눈다. 어떻게 나눌지, 몇 개로 나눌지는 클로드가 상황에 맞게 결정한다.
2. 스크립트 작성 — 오케스트레이터가 자바스크립트 오케스트레이션 스크립트를 직접 작성한다. 몇 개의 서브에이전트를 실행할지, 어떻게 작업을 배분할지, 언제 검증 패스를 돌릴지, 결과가 충분히 수렴하면 언제 멈출지가 모두 이 스크립트에 담긴다.
3. 병렬 실행 — 서브에이전트들이 각자 맡은 작업을 동시에 처리한다. 각 서브에이전트는 독립적으로 도구를 호출하고 파일을 읽으며 작업한다.
4. 검증(Verification) — 오케스트레이터가 서브에이전트 결과를 수집하고, 필요하면 반론 검증(adversarial verification) 패스를 추가로 돌린다. 허위 긍정(false positive)을 걸러내는 단계다.
5. 최종 결과 전달 — 검증이 끝난 결과만 사용자에게 보고한다.

이 구조 덕분에 다이내믹 워크플로는 기존 단일 에이전트보다 훨씬 깊고 넓은 분석을 할 수 있다. 코드베이스 전체를 스캔하고 싶을 때, 수천 개 파일에 걸친 패턴을 찾아야 할 때, 또는 보안 취약점을 체계적으로 추적해야 할 때 효과가 두드러진다.

오케스트레이터는 서브에이전트를 몇 개 만들지 스스로 결정한다. 최대 수백 개까지도 가능하다. 사용자가 직접 숫자를 지정할 필요는 없다.

다이내믹 워크플로를 시작하는 방법은 두 가지다.

방법 1: 프롬프트에 'workflow' 키워드 포함

명령에 'workflow'라는 단어를 넣으면 클로드가 다이내믹 워크플로를 실행한다. 예를 들어 다음과 같이 입력한다.

방법 2: 울트라코드(Ultracode) 설정 활성화

울트라코드는 클로드 코드의 설정 옵션이다. 활성화하면 두 가지가 합쳐진다. 첫째, xhigh 추론 노력(reasoning effort)이 자동 적용된다. 둘째, 복잡한 작업마다 별도 키워드 없이도 클로드가 스스로 다이내믹 워크플로를 실행할지 결정한다. 요청할 때마다 'workflow'를 붙이기 귀찮거나, 복잡한 태스크를 자동 판단에 맡기고 싶다면 울트라코드가 편하다.

단, 울트라코드는 비용이 빠르게 늘 수 있다. 매번 더 깊은 추론을 하고 서브에이전트를 더 많이 띄우기 때문이다. 크고 중요한 작업에만 쓰는 게 좋다.

다이내믹 워크플로는 연구 미리보기(research preview) 단계다. 모든 클로드 코드 사용자에게 열린 게 아니라, 아래 조건을 만족해야 한다.

클라이언트 버전도 중요하다. 다이내믹 워크플로는 클로드 코드 v2.1.154 이상에서 동작한다. 터미널에서 claude --version으로 버전을 확인하고, 구버전이면 npm update -g @anthropic-ai/claude-code로 업데이트해야 한다.

실행 환경은 CLI(터미널), 데스크톱 앱, VS Code 확장 모두 지원된다.

앤트로픽이 공개한 초기 사용 사례 중 실무에서 적용성이 높은 세 가지를 정리한다.

1. 코드베이스 전체 버그 헌팅

수백 개 파일에서 특정 패턴의 버그를 찾아야 할 때다. 예를 들어 비동기 오류 처리가 누락된 곳, 널 포인터 가능성이 있는 곳, 특정 API 버전의 잘못된 사용처 등을 프로젝트 전체에서 추출하는 작업이다. 단일 에이전트로는 파일을 하나씩 순차로 봐야 해서 시간이 오래 걸리지만, 다이내믹 워크플로는 여러 서브에이전트가 동시에 다른 파일 묶음을 분석한다. 시간이 큰 폭으로 줄어든다.

2. 보안 감사 및 취약점 스캔

입력값 검증 미흡, SQL 인젝션 가능성, 인증 우회 경로, 안전하지 않은 패턴 등 보안 관련 문제를 코드베이스 전반에서 체계적으로 찾아낼 때 효과적이다. 서브에이전트마다 특정 보안 패턴을 담당하게 하고, 오케스트레이터가 결과를 취합해 허위 긍정을 걸러낸다. 앤트로픽 내부 팀도 이 기능을 보안 강화 작업에 직접 쓰고 있다고 밝혔다.

3. 대규모 마이그레이션 및 현대화

수천 개 파일에 걸친 API 버전 업그레이드, 라이브러리 교체, 코드 스타일 통일 등 대형 마이그레이션 작업에 적합하다. 서브에이전트들이 각자 파일 묶음을 맡아 변환하고, 오케스트레이터가 결과를 검증한 뒤 최종 병합한다. 혼자서 수천 개 파일을 하나씩 고치는 것보다 훨씬 빠르게 마무리할 수 있다.

그 밖에도 전체 프로젝트 테스트 커버리지 분석, 문서화 자동 생성, 프로파일러 기반 성능 최적화 감사 등 다양한 케이스에 응용된다.

다이내믹 워크플로를 쓰기 전에 반드시 이해해야 할 점이 있다. 병렬 실행은 벽시계 시간(실제 걸리는 시간)을 줄여주지만, 총 토큰 비용은 줄지 않는다.

예를 들어 단일 에이전트가 100개 파일을 순차로 분석하면 토큰 X가 쓰인다고 치자. 10개 서브에이전트가 동시에 10개씩 나눠 분석해도 소비 토큰의 합계는 거의 X와 같다. 오케스트레이션 오버헤드(스크립트 작성, 결과 수집, 검증 패스)가 더해져 오히려 조금 더 늘 수 있다.

이 점을 명확히 하면 사용 기준이 보인다.

• 쓸 때: 작업이 크고, 빨리 끝내야 하고, 비용보다 시간이 중요할 때
• 안 쓸 때: 비용을 최소화해야 할 때, 작은 작업을 반복적으로 할 때

앤트로픽도 공식 문서에서 처음 시작할 때는 범위가 좁은 작업부터 해보며 사용량 감각을 익히라고 권고한다. 맥스 플랜이라도 대형 코드베이스에서 워크플로를 반복 실행하면 한도가 빠르게 소진된다.

이 글의 기능 설명과 사용 방법은 다음 공식 자료를 근거로 했습니다. 연구 미리보기 기간이라 세부 사항이 바뀔 수 있으니, 최신 정보는 공식 문서에서 확인하세요.

• 앤트로픽 블로그 발표 — 다이내믹 워크플로 소개: https://claude.com/blog/introducing-dynamic-workflows-in-claude-code
• 클로드 코드 공식 문서 — 서브에이전트 오케스트레이션 가이드: https://code.claude.com/docs/en/workflows
• InfoQ 보도 — 클로드 코드 다이내믹 워크플로 릴리스 분석: https://www.infoq.com/news/2026/06/dynamic-workflows-claude-code/