Claude Code의 Workflow 도구는 서브에이전트(subagents)를 병렬로 확장하고 그 결과를 디스크에 로우 로그(raw logs) 형태로 남깁니다. 저는 이러한 아티팩트(artifacts)를 읽어 실행 과정을 렌더링하는 로컬 대시보드와, 다시 실행 가능한 스크립트로 컴파일되는 블록 캔버스(block canvas)를 구축했습니다. 이것이 무엇을 하는지, 의도적으로 하지 않는 것은 무엇인지, 그리고 어떻게 설치하는지에 대해 설명하겠습니다.

요약: Workflow Studio는 Claude Code의 내장 Workflow 도구를 위한 로컬 컴패니언(companion)입니다. 이 도구는 두 부분으로 구성됩니다. 첫 번째는 **Observe(관찰)**로, Claude Code 자체의 디스크 기반 실행 아티팩트를 읽어 각 멀티 에이전트(multi-agent) 실행을 단계 그래프(phase graph)와 실제 시간 타임라인(wall-clock timeline)으로 그려주는 대시보드입니다. 두 번째는 **Author(작성)**로, 실제 실행 가능한 Workflow 스크립트로 컴파일되는 12개 블록의 캔버스입니다. 두 기능 모두 9개의 도구를 갖춘 MCP 서버를 통해 에이전트에게 노출됩니다. 이 도구는 127.0.0.1에서 실행되며, MIT 라이선스를 따르고, 복사 붙여넣기 한 번으로 설치할 수 있습니다. 현재 릴리스 버전은 v0.2.0입니다.

문제점: 멀티 에이전트 실행은 블랙박스이다

Claude Code의 Workflow 도구는 결정론적인 멀티 에이전트 프리미티브(primitive)입니다. 에이전트를 병렬로 확장하고, 목록을 단계별로 파이프(pipe)하며, 특정 값에 따라 게이트(gate)를 설정하고, 조건이 충족될 때까지 루프를 도는 작은 JS 스크립트를 작성하면 됩니다. 잘 작동합니다. 문제는 실행이 끝나는 순간 시작됩니다.

실행이 완료되면 디스크에 실제 아티팩트가 남습니다. ~/.claude/projects/<project>/<session>/subagents/workflows/wf_*/ 경로 아래에 journal.jsonl, 각 서브에이전트별 트랜스크립트(transcript), 그리고 각각의 작은 메타데이터 파일이 생성됩니다. 이는 방대한 양의 실측 데이터(ground truth)입니다. 하지만 이를 시각화해 주는 것이 아무것도 없습니다. 그래서 사용자는 스크롤을 해야 합니다. 단계(phases)를 한눈에 볼 수 없고, 팬아웃(fan-out)이 실제로 얼마나 넓게 퍼졌는지, 각 에이전트가 얼마나 많은 토큰을 소모했는지, 각 에이전트가 얼마나 오래 걸렸는지, 또는 중요한 순간에 게이트가 어떤 분기를 선택했는지 등을 파악할 수 없습니다.

이는 제가 _silent failures in agentic systems (에이전트 시스템에서의 침묵하는 실패)_에서 기술했던 실패의 형태와 동일합니다. 시스템이 충돌하지 않기 때문에, 12개의 검증기(verifier) 중 11개가 빈 결과를 반환했다는 사실을 아무도 알려주지 않습니다. 또한 이는 저작(authoring) 측면에서도 문제를 심화시킵니다. 이를 구축하는 유일한 방법은 스크립트를 직접 작성하는 것이며, 작성한 스크립트와 이를 실행하는 에이전트 사이의 유일한 채널은 디스크에 저장된 .js 파일뿐입니다.

Workflow Studio란 무엇인가

런타임(runtime)이 아닌, 로컬에서 실행되는 컴패니언 레이어(companion layer)입니다. 자체적인 에이전트를 포함하지 않으며 실행 엔진(execution engine)을 정의하지도 않습니다. 대신 여러분이 이미 보유하고 있는 엔진 위에 자리 잡습니다. 두 개의 인터페이스와 하나의 채널로 구성됩니다:

• Observe (관찰) — Claude Code의 실행 아티팩트(run artifacts)를 수동적으로 읽어 각 실행을 단계/에이전트 그래프(phase/agent graph)와 타임라인으로 렌더링하는 대시보드입니다.
• Author (저작) — 실제 Workflow 스크립트로 컴파일되는 노코드(no-code) 블록 캔버스입니다.
• MCP — 9개의 도구를 갖춘 stdio 서버로, 여러분의 워크플로우를 실행하는 동일한 Claude Code 에이전트가 여러분의 설계를 읽고, 관찰 내용을 검사하며, 새로운 설계를 빌더(builder)에 다시 쓸 수 있게 합니다.

다른 모든 것을 결정짓는 중요한 사항을 먼저 명확히 해두겠습니다: Workflow Studio는 실행(run)을 시작할 수 없습니다. MCP를 통해서도, 빌더를 통해서도 불가능합니다. 이 도구는 Claude Code가 이미 생성한 결과물을 읽고, 에이전트가 자신의 Workflow 도구를 사용하여 실행할 수 있는 스크립트를 에이전트에게 전달할 뿐입니다. 이는 기능적 결함이 아니라 설계 결정(design decision)이며, 그 이유는 저작(authoring) 섹션에서 설명하겠습니다.

Observe: 실제로 실행된 내용을 확인하기

대시보드는 실행 과정을 읽을 수 있는 그래프로 변환합니다. 단계(Phases), 팬아웃(fan-out), 에이전트당 토큰 사용량, 선택된 분기(branch), 각 에이전트의 출력값 등을 확인할 수 있습니다. 노드를 클릭하면 인스펙터(inspector)를 통해 해당 에이전트에게 무엇이 주어졌고 무엇을 반환했는지 확인할 수 있습니다. 즉, 프롬프트(prompt), 사고 과정(thinking), 도구 호출(tool calls), 출력(output), 사용 모델(model), 상태(state) 및 소요 시간, 그리고 생성 깊이(spawn depth)를 보여줍니다.

Observe · 나의 실제 심층 조사 (deep-research) 실행 사례 — Scope → Search → Fetch → Verify → Synthesize 단계에 걸친 111개의 에이전트, 3.7M 토큰, 약 22분 소요. 벤치마크가 아닌 단일 머신에서의 1회 실행 결과입니다.

타임라인 뷰(timeline view)는 그래프가 답해주지 못하는 또 다른 질문, 즉 '무엇이 무엇과 겹쳤는가'에 대한 답을 제공합니다. 그래프상에서는 하나의 넓은 행처럼 보이는 팬아웃 (fan-out) 구조가 실제 시간(wall-clock time)상으로는 계단식으로 나타나는 경우가 많습니다. 이를 통해 두 번째 팬아웃 (fan-out)이 첫 번째 단계의 단일 지연 작업(straggler)을 기다리고 있었다는 사실을 찾아낼 수 있습니다.

Observe · 실제 시간 타임라인 — Review 팬아웃 (fan-out)이 먼저 실행된 후, 각 에이전트가 도착함에 따라 Verify가 단계적으로 이어집니다.

구조적으로 정직함 (Honest by construction). 수치는 두 가지 서로 다른 출처에서 가져오며, 대시보드는 그 출처를 명시합니다. Claude Code 자체의 진행 오버레이 (progress overlay)가 아직 디스크에 남아 있는 경우, 레이블 (labels), 단계 (phases), 상태 (states) 및 토큰 수 (token counts)를 해당 오버레이에서 직접 읽어오며 이 실행 데이터는 권위 있는 (authoritative) 정보가 됩니다. 해당 오버레이가 이미 가비지 컬렉션 (garbage-collected)된 경우, 단계 (phases)와 레이블 (labels)은 저널 (journal)로부터 휴리스틱 (heuristically)하게 도출되며, 해당 실행은 그 상태로 표시됩니다. 측정할 수 없는 토큰이나 시간은 표시될 뿐, 결코 임의로 만들어내지 않습니다. 현재 진행 중인 실행은 live로 표시되며, 경과 시간은 하한값 (lower bounds)으로 나타납니다. 측정된 것처럼 보이지만 실제로는 그렇지 않은 숫자는 절대 보여주지 않습니다.

관찰 (Observing)은 다음 워크플로우가 시작되는 지점이기도 합니다. 실행 결과가 만족스러우면 클릭 한 번으로 이를 재사용 가능한 워크플로우로 승격시킬 수 있습니다. 방금 읽고 있던 그래프가 빌더 (builder)에서 시작점으로 열리므로, 잘 만들어진 파이프라인 (pipeline)은 다음 달에 기억에 의존해 재구성해야 하는 대상이 아닌 템플릿 (template)이 됩니다.

두 가지 실질적인 참고 사항이 있습니다. 대시보드는 푸시 (push) 방식이 아니라 짧은 캐시 (cache)를 사용한 폴링 (polling) 방식으로 새로고침됩니다. 즉, 소켓 (socket) 방식은 아니지만 몇 초 이내에 최신 상태를 반영합니다. 또한 모든 프로젝트와 세션을 가로질러 읽어오므로, 생성된 세션이 종료된 후에도 오래된 실행 기록을 계속 탐색할 수 있습니다.

저자: 보일러플레이트 (boilerplate)가 아닌 레시피를 만드세요

나머지 절반은 캔버스 (canvas)입니다. 블록 (block)을 배치하고 포트 (port)를 연결하면, Workflow Studio가 그래프 (graph)를 실제 Claude Code 워크플로우 스크립트 (workflow script)로 컴파일합니다. 여기에는 네이티브 호출 (agent(), phase(), parallel(), pipeline(), log())과 설계를 담은 사이드카 (sidecar) 주석이 포함됩니다. 이 왕복 과정 (round-trip)은 손실이 없습니다 (lossless). 컴파일된 스크립트는 당신이 그린 것과 정확히 일치하는 그래프로 다시 열리므로, 어느 한쪽에서 작업 내용이 유실되지 않고 캔버스에서 편집하거나, 에디터 (editor)에서 편집하거나, 혹은 양쪽 모두에서 편집할 수 있습니다.

저자 · 블록 빌더 (block builder) — 타이핑된 블록은 실행 가능한 스크립트로 컴파일됩니다.

열두 가지 종류의 블록이 있습니다. 각 블록은 출력의 형태 (shape)를 선언하며, 이를 통해 다운스트림 (downstream) 블록이 단순히 존재하기를 바라는 문자열이 아니라 실제 필드 (field)를 기반으로 분기 (branch)하거나 맵 (map)할 수 있습니다.

빈 캔버스에서 시작하는 일은 없습니다. 모든 새로운 워크플로우는 동적 프리미티브 (dynamic primitives)를 이미 활용하고 있는 7가지 내장 패턴 중 하나에서 시작합니다: Basic (에이전트 및 인플레이스 반복 (in-place iteration)), Classify and act (여러 분기 중 하나로 라우팅하는 분류기 열거형 (classifier enum)), Fan-out and synthesis, Adversarial verification (작업자의 결과를 반박하려는 독립적인 검증기들), Generate and filter, Tournament, 그리고 Loop until done. 하나를 선택한 다음 편집하세요.

Run 버튼은 아무것도 실행하지 않습니다. 빌더에는 Run 액션이 있지만, 이것이 워크플로우를 실행하지는 않습니다. 대신 실행하지 않는다는 사실을 명확하게 알리는 대화 상자를 열고, Claude Code에 붙여넣을 문구를 제공한 뒤, Observe에 실행 정보가 나타나는지 지켜봅니다. 그 이유는 지루하지만 중요한 설계상의 이유 때문입니다. 서버 측에서 셸 명령을 실행(shell-out)하게 되면, 루프백 대시보드(loopback dashboard)가 인증되지 않은 로컬 실행 표면(unauthenticated local exec surface)으로 변질될 수 있습니다. 저는 디자인 리뷰(design review) 단계에서 이를 거부했으며, 다시 하더라도 거부할 것입니다. 실행은 권한이 존재하는 곳, 즉 사용자의 Claude Code 세션 내에 머물러야 합니다.

한 번의 붙여넣기로 설치하기

PATH에 uv / uvx가 설정되어 있어야 하며, Python 3.9 이상의 버전이 필요합니다. 그 외에는 필요하지 않습니다. 대시보드는 패키지 내에 미리 빌드된 상태로 포함되어 있으므로, Node 단계는 필요 없습니다.

아마 이미 코딩 에이전트(coding agent)를 사용 중이실 겁니다. 에이전트에게 다음을 전달하고 자리를 비우세요:

Read https://github.com/hculap/workflow-studio/blob/main/AGENT_INSTALL.md
and set up Workflow Studio for me — run the steps, verify it,
and tell me whether to restart Claude Code.

직접 설치하는 것을 선호하시나요? 다음 두 가지는 Claude Code 세션에서 입력하는 슬래시 명령(slash commands)이며, 에이전트가 대신 실행할 수 없습니다:

/plugin marketplace add hculap/workflow-studio
/plugin install workflow-studio@workflow-studio

Claude Code 2.1 이상 버전에서는 셸 명령어 형태(./claude plugin marketplace add …, claude plugin install …)로도 사용 가능하며, 이는 에이전트 경로에서 사용하는 방식입니다. 어떤 방식이든, 설치 후에는 Claude Code를 재시작하세요 — MCP 도구와 /workflow-studio:dashboard 명령은 다음 세션에서만 로드됩니다. claude mcp list로 확인하여 서버가 연결된 상태(connected)인지 확인하세요. 만약 실패(failed)로 표시된다면, 이는 GUI로 실행된 Claude Code가 PATH에서 uvx를 상속받지 못해 발생하는 경우가 대부분입니다.

플러그인을 완전히 건너뛸 수도 있습니다:

# http://127.0.0.1:8787/ 에서 대시보드 실행 (브라우저가 열림)
uvx workflow-studio

...

알아두어야 할 주의 사항 하나: uvx는 PyPI에서 패키지를 가져오며, 플러그인은 버전을 고정하지 않으므로 새로운 릴리스가 조용히 적용됩니다.

LangGraph, CrewAI, n8n과의 관계

Workflow Studio는 이들과 경쟁하는 것이 아닙니다. 이들은 스택(stack)의 서로 다른 계층에 위치합니다. LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, n8n, Flowise는 각각 채택할 수 있는 런타임(runtime)을 제공하며, 각 도구는 모델 제공자(model provider) 간에 이식(portable)이 가능합니다. 이는 Workflow Studio가 가지고 있지 않으며, 가지려고 하지도 않는 진정한 강점입니다. Workflow Studio는 사용자가 이미 Claude Code를 실행하고 있다고 가정하며, 실행된 작업이 무엇을 했는지 확인하고 다음 작업을 시각적으로 설계할 수 있는 방법을 제공합니다.

해당 표는 2026년 중반 기준 각 도구의 포지셔닝을 반영하며, 라이선스와 프로젝트 상태는 변경될 수 있습니다. 이들 모두 각자의 니치(niche) 시장에서 유능합니다. 몇몇은 v0.2.0 사이드 프로젝트보다 더 기능이 풍부한 캔버스나 강력한 트레이싱(tracing) 기능을 갖추고 있으며, 모두 모델 제공자 간에 이식 가능하지만 Workflow Studio는 그렇지 않습니다. 여기서 기준은 순위가 아니라 적합성(fit)입니다. 만약 Claude Code를 사용하지 않는다면, 이 도구들은 귀하를 위한 것이 아닙니다.

FAQ

Workflow Studio가 제 워크플로우를 실행하나요?
아니요. 빌더(builder)에서나 MCP를 통해서도 실행을 시작할 수 없습니다. Workflow Studio는 스크립트를 컴파일하여 귀하의 Claude Code 에이전트에게 전달하며, 에이전트는 자신의 Workflow 도구를 사용하여 이를 실행합니다. 서버 측 셸 아웃(shell-out) 방식은 루프백 대시보드를 인증되지 않은 로컬 실행 표면으로 변질시킬 수 있으므로, 실행은 권한 모델(permission model)이 존재하는 귀하의 Claude Code 세션 내부에서 유지됩니다.

설치를 위해 무엇이 필요한가요?
PATH에 설정된 uv / uvx 및 Python 3.9 이상의 버전이 필요합니다. 그 외에는 아무것도 필요하지 않습니다. 대시보드가 패키지 내부에 사전 빌드(pre-built)된 상태로 포함되어 있어, Node 단계가 필요 없습니다. GitHub 마켓플레이스에서 Claude Code 플러그인으로 설치하거나, uvx workflow-studio를 통해 단독으로 실행할 수 있습니다.

제 데이터가 기기 외부로 유출되나요?
애플리케이션은 외부 호출을 수행하지 않으며 텔레메트리(telemetry)를 수집하지 않습니다. 로컬 실행 아티팩트(run artifacts)를 읽고 기본적으로 127.0.0.1에 바인딩됩니다. 두 가지 주의 사항이 있습니다: uvx는 첫 실행 시와 버전 업데이트 시 PyPI에서 패키지를 다운로드하며, 로컬 서버에는 인증 기능이 없으므로 별도의 인증 계층을 앞에 추가하지 않는 한 루프백(loopback) 상태로 유지하십시오.