Cloudflare Workflowsの可視化技術——ASTを活用したコードから図への変換プロセスを解説

Cloudflare Workflowsの可視化技術——ASTを活用したコードから図への変換プロセスを解説

Cloudflare Workflowsでデプロイされたすべてのワークフローに対し、ダッシュボード上で完全な視覚的図解（ダイアグラム）を表示する機能が追加された。この機能は、YAMLやJSONのような宣言的な設定ファイルからではなく、実際に記述されたJavaScript/TypeScriptのコードを直接解析して生成される点が最大の特徴だ。

開発者が記述したコードを「oxc-parser」を用いてAST（Abstract Syntax Tree / 抽象構文木）へと変換し、静的解析によってステップ間の依存関係や並列処理を抽出している。これにより、複雑なループや条件分岐を含む動的なワークフローであっても、その構造を一目で把握することが可能になった。

AIエージェントによるコード生成が増加する現代において、人間がコードの全容を即座に理解するための補助ツールとして、この可視化技術は極めて重要な役割を果たす。本記事では、難解な最小化済みコードからどのようにして意味のある図を導き出しているのか、その技術的な裏側を詳しく見ていく。

Cloudflare Workflowsの可視化機能とその背景

なぜ「コードからの可視化」が必要なのか

従来のワークフロー構築ツールの多くは、ドラッグ＆ドロップのビジュアルエディタや、YAML/JSONによる宣言的な定義をベースにしていた。これらは図解しやすい反面、複雑なロジックを記述する際の柔軟性に欠けるという弱点がある。

対してCloudflare Workflowsは「コードがすべて」というモデルを採用している。Promise.allによる並列実行、複雑なforループ、条件分岐などが通常のJavaScriptとして記述できる。しかし、自由度が高い反面、コードが複雑になると全体の流れを把握するのが難しくなる。記事によれば、特にAIが生成したコードを人間が確認する際、その「形状（shape）」を視覚的に理解できるメリットは大きいという。

動的実行モデルという技術的ハードル

Workflowsは「動的実行モデル」に従っている。これは、ランタイムがコードを実行中にステップ（step.do）に遭遇するたびに、制御をエンジン（Durable Object）に渡す仕組みだ。エンジンは実行されたステップの結果を保存するが、次にどのステップが来るかを事前には知らない。

図を作成するには、実行前（デプロイ時）に全体の構造を知る必要がある。しかし、エンジンが実行時にしかステップを把握できないのであれば、静的な図を作ることはできない。そこで、Cloudflareのチームはデプロイ時にスクリプトを解析し、コードの構造を「読み解く」アプローチを選択した。

AST（抽象構文木）を用いたコード解析の仕組み

最小化されたJavaScriptという難問

デプロイされるコードは、通常esbuildやrspack、viteなどのツールによって「最小化（Minify）」されている。変数名はaやbに書き換えられ、改行は消え、人間には解読不能な1行の巨大な文字列となる。この状態からワークフローのステップを抽出するのは容易ではない。

AST（Abstract Syntax Tree / 抽象構文木）とは、プログラミング言語の構文構造を樹木構造で表現したデータ形式だ。コードをトークンに分解し、どの関数がどの引数で呼び出されているかを構造的に把握できる。Cloudflareは、このASTを利用して最小化されたコードのジャングルからstep.doやstep.sleepといった特定の呼び出しを特定している。

高速な解析を実現するoxc-parserの採用

解析エンジンには、Rust製の高速なJavaScriptツールチェーンである「OXC（JavaScript Oxidation Compiler）」のoxc-parserが採用された。当初はコンテナ上でRustを動かしていたが、最終的にはWebAssembly（Wasm）を介してCloudflare Workers上で動作するRust Workerへと移行されたという。

このRust Workerが最小化されたJSをASTに変換し、定義されたノードタイプ（LoopNode, ParallelNode, IfNodeなど）にマッピングしていく。以下に、コードがどのようにASTを経て図の要素へ変換されるかの概念図を示す。

このデモは、ソースコードがAST解析を経て、最終的にダッシュボード上の視覚的なステップノードへとマッピングされる流れを視覚化したものだ。

複雑なロジックをグラフ構造にマッピングする手法

並列処理を表現する「開始」と「解決」のインデックス

Workflowsにおいて最も表現が難しいのが、並列処理だ。JavaScriptではawaitを付けずにステップを呼び出すと並列に実行され、Promise.allでそれらをまとめて待機できる。これを図にするため、Cloudflareのチームは各ノードにstartsとresolvesというフィールドを持たせた。

解析中にawaitされていないPromiseに遭遇すると、そのノードに「開始（starts）」のインデックスを付与する。その後、awaitに遭遇した時点でインデックスを増やし、「解決（resolves）」として記録する。この数値の重なりを見ることで、どのステップが垂直方向に並ぶべきか（＝並列か）、どのステップが完了を待って次に進むべきかを正確に判定している。

制御構文（ループ・分岐）のパターン網羅

単なる直線的なフローだけでなく、実務では多様な構文が使われる。著者のAndré氏とMia氏は、以下のような多岐にわたるパターンをASTから抽出できるように設計したと述べている。

• ループ: for...of, while, items.map, forEach
• 分岐: switch/case, if/else, 三項演算子
• エラーハンドリング: try/catch/finally
• 関数呼び出し: ステップをラップした関数の追跡

特に、関数の中に隠れたステップの追跡は工夫が必要だ。ある関数が直接ステップを呼び出していなくても、その中で呼び出している別の関数がステップを含んでいる場合、その依存関係をグラフに含める必要がある。記事によれば、関数ごとのサブグラフを作成し、最終的にステップを含まない「葉」の部分をトリミングすることで、ノイズのない図を実現している。

開発体験（DX）における可視化の価値と今後の展望

デバッグ効率を劇的に高めるリアルタイム追跡

この可視化機能は単なる「清書された図」ではない。Cloudflareは、これをフルサービスのデバッグツールへと進化させる計画だ。具体的には、実行中のワークフローが今どのノードにいるのかをグラフ上でリアルタイムに追跡できるようにするという。

エラーが発生した場所の特定、人間による承認待ちの状態確認、あるいはテスト目的での特定ステップのスキップなど、ビジュアルインターフェースを通じて操作できる未来を目指している。さらに、ローカル開発環境での可視化も視野に入れているとのことで、開発サイクル全体での利便性向上が期待される。

独自の分析：コードを「正解」とするアプローチの意義

今回のCloudflareの取り組みで特筆すべきは、「ビジュアルエディタで作ったものをコードに書き出す」のではなく、「コードからビジュアルを逆生成する」という方向性を徹底している点だ。これは、エンジニアにとっての真実の源泉（Source of Truth）が常にコードであることを尊重している。

このアプローチの利点は、Gitによるバージョン管理やコードレビューといった既存の開発フローと完全に共存できることにある。図を作成するために特別な設定ファイルを書く必要がなく、普段通りにコードを書くだけで、非エンジニアのステークホルダーにも共有しやすい図が手に入る。これは、開発組織におけるコミュニケーションコストを大幅に下げる可能性を秘めている。

また、AST解析という「枯れた」技術を、最小化されたJSという「汚れた」実データに適用し、それをWasmでエッジ上で高速実行するという構成は、非常にCloudflareらしい合理的でパワフルな解決策だと言えるだろう。

この記事のポイント

• コードから図を自動生成: Cloudflare Workflowsは、JS/TSコードを解析して視覚的な図を自動作成する。
• AST（抽象構文木）の活用: 最小化された難解なコードも、AST解析によって構造的に理解し、ステップを抽出する。
• oxc-parserによる高速処理: Rust製の解析器をWasmで動かすことで、デプロイ時の高速な図解生成を実現した。
• 並列処理の可視化: startsとresolvesというインデックスを用いて、複雑な並列実行の関係を正確に図示する。
• デバッグツールへの進化: 今後はリアルタイムの実行追跡や、図からの操作機能も追加される予定だ。

出典

• Cloudflare Blog「How we use Abstract Syntax Trees (ASTs) to turn Workflows code into visual diagrams」（2026年3月27日）

海田 洋祐

・ 複数業界における17年間のデジタルビジネス開発経験
・ ウェブサイト開発のためのHTML、PHP、CSS、Java等の実用的知識
・ 15ヶ国語対応の多言語SaaSの開発経験
・ 17年間にも及ぶ、Eコマース長期運営経験
・ 幅広い業界でのSEO最適化の豊富な経験