Claude Code 워크플로: 개념과 실제로 필요한 순간

Claude Code 워크플로: 개념과 실제로 필요한 순간

Claude Code v2.1.154로 업데이트하면 /config에 Dynamic workflows라는 새 항목이 보입니다. 이걸 켜면 Claude가 최대 16개의 에이전트를 동시에 실행하는 JavaScript 스크립트를 작성할 수 있습니다. 모두가 조용히 이야기하는 바로 그 기능입니다. 공식 문서는 이 기능이 무엇을 하는지 알려줍니다. 하지만 여러분이 진짜 궁금한 건 알려주지 않습니다: 이게 필요한가, 아니면 이미 있는 서브에이전트로 충분한가?

바로 이 간극입니다. Claude Code 워크플로는 리서치 프리뷰로 출시되었고, 문서는 참고 자료처럼 읽히지 조언처럼 읽히지 않습니다. 그래서 저희는 번들된 유일한 워크플로인 /deep-research를 자체 콘텐츠 파이프라인에서 실행하고, 실제 수치를 기록하고, 솔직한 결론을 적었습니다. 짧게 말하면: 에이전트를 아직 손으로 추적할 수 있다면, 워크플로는 아직 필요 없습니다. 다만 일부에게는 확실히 필요합니다. 어느 쪽인지 가려봅시다.

핵심 요약:

• Claude Code 워크플로는 Claude가 서브에이전트를 대규모로 오케스트레이션하기 위해 작성하는 JavaScript 스크립트입니다 (리서치 프리뷰, v2.1.154 이상, 모든 유료 플랜).
• 하나의 대화로 조율할 수 있는 것보다 더 많은 에이전트가 필요할 때만 워크플로가 필요합니다. 그렇지 않으면 서브에이전트로 충분합니다.
• 현재 번들된 워크플로는 하나입니다: /deep-research. 세션이 반응하는 동안 백그라운드에서 실행됩니다.
• 워크플로는 토큰을 많이 소모합니다. 추천하기 전에 실제 실행을 측정했습니다 (수치는 아래에).

Claude Code 워크플로란?

Claude Code 워크플로는 서브에이전트를 대규모로 오케스트레이션하는 JavaScript 스크립트입니다. 작업을 설명하면 Claude가 스크립트를 작성하고, 런타임이 백그라운드에서 실행하는 동안 채팅 세션은 계속 반응합니다. Claude Code의 리서치 프리뷰 기능이며, Claude Code v2.1.154 이상이 필요하고, 모든 유료 플랜(Pro, Max, Team, Enterprise, 그리고 API와 Bedrock/Vertex/Foundry 포함)에서 실행됩니다.

일상적인 비유로 설명하겠습니다. 주방 카운터에 서서 원하는 요리를 설명한다고 상상해 보세요. 셰프가 레시피를 작성하고, 요리사들로 가득한 뒷주방에 넘기면, 여러분이 카운터에서 계속 대화하는 동안 그들이 작업을 시작합니다. 각 요리사를 일일이 지휘하지 않습니다. 레시피가 그 역할을 합니다. 그 레시피가 워크플로이고, 요리사들이 서브에이전트이며, 뒤에서 돌아가는 주방이 런타임입니다.

워크플로는 또 다른 에이전트가 아닙니다. 에이전트에게 무엇을, 어떤 순서로, 결과를 어떻게 처리할지 지시하는 스크립트입니다. 이 구분이 이 글에서 그 무엇보다 중요하며, 다음 섹션에서 구체적으로 설명하겠습니다.

혼동 하나를 먼저 정리하겠습니다. "claude code workflows"를 검색하면 GitHub 저장소, 플러그인, 그리고 Ruflo, claude-flow, wshobson/agents 같은 커뮤니티 스웜 도구로 가득한 marketplace가 나옵니다. 그것들은 서드파티 오케스트레이터입니다. Anthropic의 공식 Dynamic workflows는 다른, 내장 기능입니다. v2.1.154 이상에서 /config에 없으면, 공식 기능이 아닙니다.

이 기능은 최근 fast mode 리서치 프리뷰처럼 Anthropic의 다른 리서치 프리뷰 출시와 같은 선상에 있습니다: 일찍 출시되고, 토글 뒤에 있고, 아직 거친 부분이 있습니다. 프리뷰로 대하세요. 실제로 프리뷰이니까요. 전체 사양은 공식 워크플로 문서에 있습니다.

워크플로 vs 서브에이전트 vs 스킬: 누가 계획을 쥐고 있는가?

이 셋을 구분하는 가장 깔끔한 방법은 하나의 질문을 던지는 것입니다: 누가 계획을 쥐고 있는가? 스킬은 Claude가 필요할 때 로드하는 포장된 지침과 지식입니다. 서브에이전트는 위임된 하나의 작업을 수행하는 별도 컨텍스트입니다. 워크플로는 서브에이전트를 대규모로, 한 번에 최대 16개까지 조율하는 오케스트레이션 스크립트입니다. 같은 도구 상자, 세 가지 다른 역할.

공식 문서가 암시하지만 나란히 펼쳐 보여주지 않는 비교는 이렇습니다:

하나의 Claude 대화로 전체 계획을 머릿속에 담을 수 있다면, 워크플로가 아니라 서브에이전트가 필요합니다. 누가 무엇을 어떤 순서로 하는지 인간인 여러분이 추적할 수 있는 것보다 더 많은 에이전트를 생성하는 순간, 계획이 대화를 벗어난 것입니다. 워크플로가 넘는 선이 바로 그것입니다.

첫 번째 부분을 더 깊이 알고 싶으신가요? 저희 스킬 튜토리얼에서 Claude가 필요 시 로드하는 지식 포장을 다룹니다. 그리고 네이티브 오케스트레이션 대신 완전한 에이전트 프레임워크를 선택할지 고민 중이라면, 그 비교도 도움이 됩니다. 저희 솔직한 의견: 네이티브 프리미티브는 프레임워크가 제 값을 하기 전에 생각보다 멀리 갑니다.

Claude Code 워크플로가 실제로 필요한 순간은?

Claude Code 워크플로가 필요한 경우는 (a) 작업에 하나의 대화로 조율할 수 있는 것보다 더 많은 에이전트가 필요할 때, (b) 오케스트레이션을 일회성 프롬프트가 아닌 재실행 가능한 코드로 저장하고 싶을 때, 또는 (c) 여러 에이전트가 서로의 작업을 검증하는 적대적 또는 교차 검증 리뷰가 필요할 때입니다. 이 중 어느 것도 해당하지 않으면, 서브에이전트로 충분합니다. 여기서 스스로에게 솔직해지세요.

이건 문서가 큰 소리로 말하지 않는 부분이라, 저희가 말하겠습니다: 아마 아직 워크플로는 필요 없습니다. 소수의 서브에이전트를 일반 대화에서 조율하는 것으로 일상 업무를 처리할 수 있습니다. 워크플로는 졸업해서 올라가는 업그레이드가 아닙니다. 하나의 뇌로 추적할 수 없는 규모의 에이전트라는, 특정 형태의 문제를 위한 도구입니다.

이 체크리스트를 스스로 해보세요. 다음 중 최소 하나에 예라고 답하면 워크플로가 필요할 가능성이 높습니다:

• 작업에 하나의 대화로 추적할 수 있는 것보다 더 많은 에이전트가 필요합니다.
• 오케스트레이션을 다시 타이핑하는 일회성 프롬프트가 아닌 재실행 가능한 코드로 원합니다.
• 적대적 또는 교차 검증 리뷰가 필요합니다 (여러 에이전트가 서로 검증).
• 같은 멀티에이전트 작업을 반복적으로 실행합니다. 반복 코드베이스 감사나 500개 파일 마이그레이션처럼.

네 가지 모두 아니라고 답했나요? 서브에이전트에 머무르세요. 토큰을 절약하고, 디버깅 가능하게 유지하고, 아무것도 잃지 않습니다. 스펙 주도 방식에 익숙한 분들은 좋은 CLAUDE.md 모범 사례에서 이 패턴을 알아볼 것입니다: 계획을 한 번 적고, 재실행 가능하게 만들고, 다시 타이핑하지 않기. 워크플로는 그 아이디어를 계획 자체를 실행할 런타임이 필요한 지점까지 밀어붙인 것입니다.

이미 가지고 있는 유일한 워크플로: /deep-research

/deep-research는 프리뷰에 번들된 유일한 워크플로입니다. 질문과 함께 호출하면 서브에이전트를 펼쳐 주제를 병렬로 조사하고, 발견한 내용을 서로 교차 검증하고, 하나의 종합된 답변을 컨텍스트로 반환합니다. 이 모든 것이 백그라운드에서 실행되어 세션은 계속 사용 가능합니다.

/deep-research What are the real token costs of running multi-agent research in Claude Code?

인터페이스는 이게 전부입니다. 내부에서는 단계를 거칩니다: 질문을 리서치 스레드로 분해하고, 각 스레드를 쫓을 에이전트를 생성하고, 에이전트가 서로의 약한 주장을 잡아내도록 교차 검증 또는 리뷰 단계를 실행하고, 최종 답변을 종합해 채팅으로 돌려줍니다. 실행 중에는 방향을 조정하지 않습니다. 질문하면, 작업하고, 보고합니다.

이건 그렇지 않으면 탭 열 개를 열고 오후를 날릴 지저분한 리서치 질문에 정말 유용합니다. 이미 리서치 도구를 연결하고 있다면, 저희 최고의 MCP 서버 라운드업이 이런 팬아웃 리서치와 잘 맞습니다. 하지만 "유용한 것"과 "토큰 비용만큼 가치 있는 것"은 같은 말이 아니며, 정확히 그걸 측정하려고 했습니다.

자체 파이프라인에서 워크플로를 실행했을 때 일어난 일

저희 /deep-research 실행은 4개 단계에 걸쳐 9개의 서브에이전트를 생성하고, 100만 토큰을 약간 넘게 소모하고, 벽시계 시간으로 약 8분 만에 완료되었습니다. 가치 있었나요? 빠른 질문에는, 어림없습니다. 그렇지 않으면 반 dozen 에이전트를 손으로 조율했을 리서치 작업에는, 그 자체로 값을 했습니다. 솔직한 내역입니다.

저희 파이프라인에서, 여러분이 읽고 있는 이 글 자체가 멀티에이전트 시스템으로 제작되었습니다: 리서치, 브리프, 작성, 검증, 번역, 게시가 각각 별도 서브에이전트로 실행됩니다. 그래서 저희는 이미 위 체크리스트의 "하나의 대화에 에이전트가 너무 많은" 세계에 살고 있습니다. 그게 저희를 적절한 테스트 케이스로 만들었고, 작위적인 사례가 아닙니다.

이미 리서치 중이던 라이브 키워드에 /deep-research를 실행하고 전체 실행을 기록했습니다:

가장 놀라웠던 건 교차 검증 단계였습니다. 한 에이전트가 만든 초기 주장 몇 개가 다른 에이전트가 이의를 제기한 후 조용히 수정되었는데, 이건 단일 대화에서는 그냥 넘어가기 쉬운 종류의 것입니다. 그 적대적 단계가 진짜 가치입니다. 원시적 병렬 처리보다 더. 다만 토큰 비용은 가파르고, 그 에이전트들은 Opus급 모델에서 실행됩니다 (왜 그게 비용에 중요한지는 Opus 4.8의 새로운 점 참조). 프롬프트 두 개로 답할 수 있는 질문에 100만 토큰은 나쁜 거래입니다. 정말 여섯 개 소스를 맞춰야 하는 질문에는, 시간 대비 싼 거래입니다.

이건 저희가 Techsy에서 클라이언트를 위해 구축하는 종류의 오케스트레이션이라, 어디서 값어치를 하고 어디서 예산만 태우는지에 대한 강한 사전 판단이 있었습니다. 저희 의견: 어려운 질문에 실행하고, 쉬운 질문은 건너뛰세요.

나만의 워크플로를 작성하고 저장하는 방법

나만의 워크플로를 만들려면, workflow 키워드를 사용해 일반 언어로 Claude에게 작업을 설명하고, 생성된 스크립트를 검토하고 승인한 다음, 그 스크립트를 재사용 가능한 /command로 저장하세요. 더 높은 노력을 원하면, /effort ultracode를 설정하고 Claude가 스스로 워크플로를 계획하게 합니다. JavaScript를 직접 작성할 필요는 없습니다; Claude가 스크립트를 쓰고, 여러분이 승인합니다.

전체 루프는 이렇고, 따라 하고 있다면 단계이기도 합니다:

1. Dynamic workflows 활성화. Pro에서 /config를 열고 Dynamic workflows 행을 켜세요. (v2.1.154 이상이죠, 맞죠?)

   bash

   /config
   # then enable the "Dynamic workflows" row

2. workflow 키워드로 작업 설명. 프롬프트 어디에든 workflow라는 단어를 포함하세요. 예: "이 저장소의 모든 라우트 파일에서 누락된 인증 검사를 감사하는 워크플로를 실행해." Claude Code가 단어를 강조 표시하고, 턴별로 작업하는 대신 스크립트를 작성합니다. Claude가 스스로 결정하게 하고 싶나요? /effort ultracode를 설정하세요. xhigh 추론과 자동 워크플로 오케스트레이션을 모든 실질적 작업에 결합합니다 (그리고 토큰을 더 태우니, 일상 작업은 /effort high로 돌아가세요).

3. 생성된 스크립트 검토 및 승인. Claude가 실행 전에 JavaScript 오케스트레이션을 보여줍니다. 읽으세요. 원보다 넓은 팬아웃을 잡아낼 기회입니다.

4. 재사용을 위해 /command로 저장. 작동하면, 워크플로를 커스텀 슬래시 커맨드로 저장해서 다음 분기 감사는 키 한 번으로 끝내세요.

재사용성이 조용한 승리입니다. 일회성 /deep-research는 편리하지만, "모든 라우트의 인증 감사"나 "이 디렉터리를 새 API로 마이그레이션"을 위한 저장된 워크플로는 수 시간의 조율 작업을 하나의 반복 가능한 커맨드로 바꿉니다. 그때 토큰 비용이 한 번 아픈 게 아니라 실행 전반에 걸쳐 상각되기 시작합니다.

한계, 비용, 그리고 워크플로 끄는 방법

워크플로는 동시 최대 16개 에이전트, 실행당 1,000개 에이전트 하드 캡을 가지며, 실행 중 입력을 받지 않고, 같은 세션 내에서만 재개 가능합니다. 모든 에이전트가 컨텍스트를 소비하므로 설계상 토큰을 많이 소모합니다. config의 disableWorkflows 또는 CLAUDE_CODE_DISABLE_WORKFLOWS 환경 변수로 기능을 완전히 비활성화할 수 있습니다.

각 한계는 작업에 의미를 가집니다. 실행 중 입력 불가는 시작하면 방향을 수정할 수 없다는 뜻이라, 모호한 프롬프트는 전체 실행의 토큰을 낭비합니다. 같은 세션에서만 재개 가능은 터미널을 닫으면 실행이 사라진다는 뜻입니다. 실행당 1,000개 에이전트는 엄청나게 들리지만, Opus급 요금의 넓은 팬아웃은 실제 돈이라, 16개 동시 기본값을 밀어붙일 상한이 아닌 기능으로 대하세요.

끄려면:

export CLAUDE_CODE_DISABLE_WORKFLOWS=1
# or set "disableWorkflows": true in your config

버전 함정에 걸리는 분들이 있습니다: /config에 Dynamic workflows 행이 안 보이면, v2.1.154 미만입니다. 먼저 업데이트하세요. 그리고 실제 업무를 위해 이런 에이전트 파이프라인을 구축하고 실제로 값어치를 하게 만들고 싶다면, 저희가 B2B 팀을 위해 에이전트 파이프라인을 구축합니다. 오케스트레이션이 병목이 되고 있다면 무료 상담 받기 →.

결론

전체 글을 다섯 줄로. Claude Code 워크플로는 Claude가 서브에이전트를 대규모로 오케스트레이션하기 위해 작성하는 JavaScript 스크립트로, v2.1.154에서 리서치 프리뷰로 출시되었습니다. 현재 존재하는 것은 /deep-research입니다. 워크플로는 작업이 하나의 대화로 조율할 수 있는 것을 벗어날 때, 재실행 가능한 오케스트레이션을 원할 때, 또는 에이전트가 서로 교차 검증해야 할 때만 필요합니다. 저희 실제 실행은 8분에 9개 에이전트에 ~100만 토큰이 들었고, 쉬운 질문에는 과잉이고 어려운 리서치에는 값어치가 있습니다. 아마 아직 필요 없고, 그건 괜찮습니다.

저자 소개

Mert Batur Gurbuz는 Techsy.io의 공동 창립자로, 팀은 B2B 클라이언트를 위해 AI 에이전트, 자동화 시스템, 음성/SDR 파이프라인을 출시합니다. University of Birmingham에서 공부하며 Techsy 팀이 실제 프로덕션에서 사용하는 LLM 도구 스택에 대해 글을 씁니다.

공동 창립자, Techsy.io, University of Birmingham · LinkedIn

자주 묻는 질문

Claude Code 워크플로란 무엇인가요?

Claude Code 워크플로는 서브에이전트를 대규모로 오케스트레이션하는 JavaScript 스크립트입니다. 작업을 설명하면 Claude가 스크립트를 작성하고, 런타임이 백그라운드에서 실행하는 동안 세션은 계속 반응합니다. Claude Code v2.1.154 이상의 리서치 프리뷰 기능으로, 모든 유료 플랜에서 사용 가능합니다.

워크플로와 서브에이전트의 차이는 무엇인가요?

서브에이전트는 자체 별도 컨텍스트에서 실행되는 하나의 위임된 작업으로, 대화에서 여러분이 조율합니다. 워크플로는 서브에이전트를 한꺼번에, 최대 16개까지 조율하는 오케스트레이션 스크립트입니다. 하나의 대화로 전체 계획을 담을 수 있으면 서브에이전트를 쓰세요. 계획이 에이전트를 추적할 런타임이 필요하면 워크플로를 쓰세요.

Claude Code 워크플로의 토큰 비용은 얼마인가요?

저희가 측정한 /deep-research 실행에서, 4개 단계에 걸친 9개 서브에이전트가 약 8분에 대략 105만 토큰을 소모했습니다. 워크플로는 모든 에이전트가 자체 컨텍스트를 소비하므로 설계상 토큰을 많이 소모하며, 그 에이전트들은 Opus급 모델에서 실행됩니다. 단순 질문에는 낭비이고; 진짜 멀티소스 리서치에는 비용을 값어치 있게 합니다.

Claude Code 워크플로를 쓰려면 유료 플랜이 필요한가요?

네. Dynamic workflows는 모든 유료 Claude 플랜(Pro, Max, Team, Enterprise)과 API 및 Bedrock/Vertex/Foundry에서 실행됩니다. 무료 티어 접근은 없습니다. Pro에서는 Claude Code v2.1.154 이상으로 업데이트한 후 /config에서 Dynamic workflows 행을 토글해 기능을 활성화합니다.

Claude Code의 /deep-research는 무엇인가요?

/deep-research는 리서치 프리뷰에 번들된 유일한 워크플로입니다. 질문을 주면 서브에이전트를 펼쳐 주제를 병렬로 조사하고, 에이전트가 서로의 발견을 검증하는 교차 검증 단계를 실행하고, 하나의 답변을 종합해 컨텍스트로 반환합니다. 이 모든 것이 백그라운드에서 실행됩니다.

워크플로를 슬래시 커맨드로 어떻게 저장하나요?

workflow 키워드를 사용해 Claude에게 작업을 설명하고, 생성된 JavaScript 스크립트를 검토하고 승인한 다음, 그 승인된 스크립트를 커스텀 /command로 저장하세요. 그러면 전체 멀티에이전트 작업이 키 한 번으로 실행되며, 이때 워크플로가 반복 실행 전반에 걸쳐 토큰 비용을 상각하기 시작합니다.

워크플로가 한 번에 실행할 수 있는 에이전트 수는?

워크플로는 동시 최대 16개 에이전트를 실행하며, 실행당 1,000개 에이전트 하드 캡이 있습니다. 16개 동시 기본값은 좋은 이유가 있습니다: Opus급 요금의 넓은 팬아웃은 빠르게 비싸집니다. 한계를 목표가 아닌 가드레일로 대하고, 작업이 허용하는 한 팬아웃을 좁게 유지하세요.

Dynamic workflows는 어떻게 끄나요?

config에서 disableWorkflows를 true로 설정하거나, Claude Code를 시작하기 전에 CLAUDE_CODE_DISABLE_WORKFLOWS=1 환경 변수를 내보내세요. 둘 다 기능을 완전히 비활성화합니다. /config에 Dynamic workflows 행이 단순히 안 보이면, 필요한 v2.1.154 미만일 가능성이 높고 먼저 업데이트해야 합니다.

Claude Code 워크플로가 실제로 필요한가요, 아니면 서브에이전트로 충분한가요?

서브에이전트는 작업이 하나의 대화를 벗어나기 전까지 충분합니다. 일반 대화에서 조율되는 소수의 서브에이전트는 토큰 비용 없이 일상 업무를 커버합니다. 워크플로가 정말 필요한 경우는 작업이 하나의 대화로 추적할 수 없는 규모의 에이전트를 생성할 때, 재실행 가능한 오케스트레이션을 코드로 원할 때, 또는 에이전트가 적대적으로 서로 교차 검증해야 할 때뿐입니다.