Claude Code의 Dynamic Workflows를 시도하기 전에 알아두어야 할 것 (특히 토큰 소비에 대하여)

Dynamic Workflows는 research preview입니다.

Claude Code v2.1.154에서 **Dynamic Workflows (동적 워크플로우)**라는 기능이 추가되었습니다.

한마디로 말하면 "Claude에게 워크플로우를 구성하게 하면, 백그라운드에서 수십~수백 개의 서브 에이전트 (Sub-agent)를 병렬로 실행하여 큰 태스크를 통째로 해결해 주는" 기능입니다.

재미있어 보이는 기능이지만, 처음에 많은 사람이 궁금해하는 점은 "이거, 토큰을 엄청나게 쓰는 거 아냐?" 하는 부분일 것입니다. 결론부터 말하자면 그 말이 맞으며, 일반적인 사용 방식보다 명확하게 더 많이 소비합니다. 본 기사에서는 그 메커니즘과 소비를 억제하기 위한 실용적인 팁을 정리합니다.

기존의 "서브 에이전트 (Sub-agent)", "스킬 (Skill)", "에이전트 팀 (Agent Team)"과는 무엇이 다른가. 공식 문서의 비교가 이해하기 쉬우므로 요약합니다.

구분	서브 에이전트 (Sub-agent)	스킬 (Skill)	에이전트 팀 (Agent Team)	워크플로우 (Workflow)
실체	Claude가 기동하는 워커 (Worker)	Claude가 따르는 지시서	피어 세션을 통괄하는 리드 에이전트 (Lead Agent)	런타임이 실행하는 스크립트
...

포인트는 **"계획 (Orchestration)을 코드로 옮기는 것"**입니다.

서브 에이전트, 스킬, 에이전트 팀에서는 Claude(또는 리드 에이전트) 자신이 "다음에는 무엇을 기동할까"라고 턴(Turn)마다 판단하며, 그 결과가 모두 컨텍스트 (Context)에 쌓여갑니다. 이렇게 되면 에이전트 수가 늘어날수록 컨텍스트가 팽창하여 한계에 도달하게 됩니다.

반면 워크플로우는 루프 (Loop), 분기 (Branch), 중간 결과물을 JavaScript 스크립트 측에서 유지합니다. Claude의 컨텍스트로 돌아오는 것은 "최종적으로 검증된 정답"뿐입니다. 그렇기 때문에 대량의 에이전트를 협조시킬 수 있는 것입니다.

나아가 이 설계의 장점은 단순히 "에이전트를 늘릴 수 있다"는 것뿐만 아니라, 재현 가능한 품질 패턴을 구축할 수 있다는 점입니다. 예를 들어 "독립된 에이전트가 서로의 조사 결과를 적대적으로 리뷰한 뒤 보고한다"라거나 "여러 각도에서 플랜을 세워 대조한다"와 같이, 단발성 경로보다 신뢰할 수 있는 결과를 얻는 메커니즘을 심어둘 수 있습니다.

ultracode: src/routes/ 이하의 모든 API 엔드포인트를 감사하여, 인증 체크가 누락되지 않았는지 확인한다.

프롬프트 어딘가에 ultracode가 포함되어 있으면, Claude Code가 해당 키워드를 하이라이트하며 턴마다 작업하는 것이 아니라 워크플로우 스크립트를 작성해 줍니다. "use a workflow", "run a workflow"와 같이 자신의 언어로 요청해도 직접적인 리퀘스트(Request)로서 동일하게 취급됩니다.

v2.1.160에서 트리거 키워드가 workflow에서 ultracode로 변경되었습니다. 그 이전에는 workflow라는 단어가 발화 키였으나, 현재 그 단어로는 발화되지 않습니다 (자연스러운 언어로의 요청은 두 버전 모두 유효합니다). 의도치 않게 발화된 경우에는 macOS라면 Option+W, Windows / Linux라면 Alt+W로 해당 프롬프트에 한해 무시하거나, 하이라이트 직후에 backspace로 취소할 수 있습니다.

완전히 무효화하고 싶다면 /config의 "Ultracode keyword trigger"를 Off로 설정하십시오.

/effort ultracode

ultracode는 xhigh의 추론 노력 (Reasoning effort)과 자동 워크플로우 오케스트레이션 (Workflow orchestration)을 결합한 설정입니다. 이를 켜두면 사용자가 요청하지 않아도 Claude가 실질적인 태스크마다 워크플로우를 계획합니다.

하나의 리퀘스트가 "코드를 이해하는 워크플로우 → 변경하는 워크플로우 → 검증하는 워크플로우"로 연쇄될 수도 있습니다. 세션 내의 모든 태스크에 적용되므로, 각 리퀘스트가 낮은 effort 레벨보다 더 많은 토큰을 사용하며 시간도 더 걸립니다. 일상적인 작업으로 돌아갈 때는 /effort high로 낮추십시오 (ultracode는 세션 한정이며, 새 세션에서 리셋됩니다).

좋은 결과를 낸 워크플로우는 /workflows에서 선택하여 s 키로 저장할 수 있으며, 이후 /<이름> 명령어로 재사용할 수 있습니다.

저장 위치는 두 곳입니다:

• .claude/workflows/ (프로젝트 공유용 - 리포지토리를 clone한 모든 사용자가 사용 가능)
• ~/.claude/workflows/ (개인용 - 모든 프로젝트에서 사용할 수 있지만 본인만 사용 가능)

공식 문서의 「Cost」 섹션은 모호하게 표현하지 않고 다음과 같이 명시하고 있습니다.

A workflow spawns many agents, so a single run can use meaningfully more tokens than working through the same task in conversation.
(워크플로우는 다수의 에이전트 (agents)를 생성하므로, 단 한 번의 실행으로 동일한 작업을 대화로 진행할 때보다 유의미하게 더 많은 토큰을 사용할 수 있습니다.)

그리고 블로그 측은 더욱 직설적입니다.

Dynamic workflows can consume substantially more tokens than a typical Claude Code session.
(Dynamic workflows는 일반적인 Claude Code 세션보다 실질적으로 훨씬 더 많은 토큰을 소비할 수 있습니다.)

즉, "꽤 많이 쓴다"는 것은 기분 탓이 아니라 사양 (specification) 입니다. 이유는 간단합니다. 수십~수백 개의 에이전트가 각각 독립적인 컨텍스트 (context)를 가지며, 게다가 상호 검증을 위해 동일한 주제를 여러 번 처리하기 때문입니다. 이러한 소비는 일반 세션과 마찬가지로 플랜의 이용량 및 레이트 리밋 (rate limit)에 합산되므로 사용 시점을 결정하기가 까다롭습니다.

제약 사항	이유
동시 실행은 최대 16 에이전트 (CPU 코어가 적은 머신에서는 더 적음)	로컬 리소스의 상한선
1회 실행당 총 1,000 에이전트까지	폭주 루프 방지

"최대 1,000 에이전트"라는 숫자를 보면 토큰 소비가 순식간에 불어날 수 있음을 짐작할 수 있을 것입니다. 반대로 말하면 1,000개에서 하드 캡 (hard cap)이 걸리므로, 무한정 과금이 늘어나는 것은 아닙니다.

무턱대고 겁낼 필요는 없습니다. Claude Code 측에 적절한 가시화 및 제어 수단이 마련되어 있기 때문입니다.

① 실행 전 승인 프롬프트에서 중단

기본(default) / accept edits 모드에서는 매번 ("이 워크플로우를 앞으로 확인하지 않음"을 선택하기 전까지), 계획된 페이즈 (phase) 목록이 표시되며 승인을 요청합니다. 데스크톱 앱에서는 승인 카드에 토큰 사용량 주의 문구가 표시됩니다. View raw script를 통해 스크립트 본체를 놓치지 않는다면, 내용을 읽고 판단하는 것도 가능합니다.

② /workflows의 진행 상황 뷰에서 토큰 총량 확인 가능

/workflows

진행 상황 뷰는 각 페이즈별 에이전트 수, 토큰 총량, 경과 시간을 표시합니다. 각 페이즈를 드릴다운 (drill-down)하면 에이전트 단위로 무엇을 찾아냈는지도 추적할 수 있습니다. "생각보다 많이 쓰고 있네"라고 느껴지면 x 키로 에이전트 단위 또는 워크플로우 전체를 중단할 수 있습니다 (완료된 작업은 손실되지 않습니다).

③ 모델을 구분하여 사용

워크플로우 내의 각 에이전트는 스크립트에서 별도의 모델을 지정하지 않는 한 세션의 모델을 사용합니다. 따라서 비용 제어의 핵심은 모델 선택입니다.

• 대규모 실행 전에 /model을 확인한다 (평소 루틴하게 작은 모델로 전환하여 사용하는 사람은 특히 주의).
• 작업을 설명할 때 "강력한 모델이 필요 없는 페이즈에는 작은 모델을 사용해줘"라고 Claude에게 요청한다.

공식 권장 사항은 "처음에는 범위를 좁힌 작업으로 사용량 감각을 익힐 것" 입니다. 저도 동감하는 부분으로, 갑자기 "리포지토리 전체를 마이그레이션해줘"라고 하기보다는, 우선 1개의 디렉토리, 1개의 관점으로 범위를 좁혀 /workflows의 토큰 표시를 살펴보며 체감을 익히는 것이 안전합니다. 비용을 예측할 수 없는 자동화를 실제 규모로 갑자기 돌리는 것은 편의성보다 사고에 대한 불안감이 더 큽니다. 무엇이든 무조건 사용하는 도구는 아닙니다.

조직에서 사용하지 못하게 하거나, 자신의 환경에서 완전히 차단하고 싶은 경우:

• 개인: /config에서 "Dynamic workflows"를 Off / ~/.claude/settings.json에 "disableWorkflows": true 설정 / 환경 변수 CLAUDE_CODE_DISABLE_WORKFLOWS=1 설정
• 조직 전체: managed settings에 "disableWorkflows": true 설정

또는 Claude Code admin settings 페이지의 토글

• 워크플로우 자체는 파일 시스템이나 쉘 (Shell)에 직접 액세스하지 않음 - 워크플로우가 실행하는 서브 에이전트 (Sub-agent)는 세션의 모드와 관계없이 항상 acceptEdits 모드로 동작하며, 파일 편집은 자동으로 승인됨

• 실행 중에는 사용자 입력을 받지 않음

• Dynamic Workflows는 "계획을 스크립트로 옮기고, 백그라운드에서 수십~수백 개의 에이전트를 협업시키는" 기능

• 토큰 (Token) 소비는 일반적인 세션보다 명확하게 많음

• 우선은 범위를 좁힌 1개의 태스크 (Task)로 /workflows의 숫자를 살펴보며 감을 익히는 것이 안전함