DifyのワークフローをGUIではなくYAMLで組む
Difyのワークフローエディタは直感的で扱いやすいのですが、ノード数が10を超えたあたりから、GUIでの直接編集だけでは辛くなってきます。変更履歴が残らない、差分レビューができない、といった問題が出てくるためです(背景の詳しい話はZenn版にまとめています)。
この記事では、そのDifyワークフローをエクスポートしたYAMLをClaude Codeで編集するという運用の、具体的な手順だけをまとめます。10〜50ノード規模のワークフローで実際に使っている進め方です。
全体の流れ
一気に全体を生成させると、生成のたびに構成や出力の振れ幅が大きくなり、質が安定しません。そのため、次の3ステップに分けて進めます。
| ステップ | やること |
|---|---|
| 1. 大枠を作る | ノードの種類と接続だけを決めた、中身が空に近いYAMLを作る |
| 2. ノード単位でチューニングする | ノードを1つずつ指定して、そのノードの中身だけを詰める |
| 3. 変数の整合性をチェックする | ノード間の変数参照に型不一致・未接続がないかを横断的にチェックする |
準備：ワークフローをYAMLでエクスポートする
DifyのワークフローはGUI画面から「エクスポート」でYAML(DSL)ファイルとしてダウンロードできます。これをGitリポジトリに置いてバージョン管理します。
# エクスポートしたYAMLをリポジトリに配置してコミットしておく
git add workflow.yml
git commit -m "chore(wf): DifyワークフローYAMLを取り込み"
以降はこのYAMLファイルをClaude Codeに編集させ、編集後のYAMLをDify側にインポートし直す、というサイクルで進めます。
ステップ1：大枠だけを決める
最初のプロンプトでは、ノードの種類・接続だけを作らせ、各ノードの中身(プロンプトや詳細設定)には触れさせません。
workflow.yml にDifyのワークフローの骨組みを作ってください。
条件:
- ノードの種類と、ノード間の接続(edges)だけを決める
- 各ノードのプロンプトや詳細設定は最小限の仮の値でよい
- 全体の処理の流れ(入力→分析→出力など)が一目でわかる構成にする
ここで中身まで作り込ませないのがポイントです。全体設計とノードの細部を同時に生成させると、そのぶん一度に決めなければいけないことが増え、生成のたびに違う判断が混ざり込みやすくなります。骨組みだけに絞ることで、まず全体構成をレビューできる状態を作ります。
骨組みができたら、git diffで構成を確認してからコミットします。
git add workflow.yml
git commit -m "feat(wf): ワークフローの骨組み(ノード構成・接続)を作成"
ステップ2：ノードを1つずつチューニングする
大枠に問題がなければ、ここからノード単位で中身を詰めていきます。1回の指示で触るノードを1つに絞るのがコツです。
workflow.yml の analyze_data ノードのプロンプトと設定だけを詰めてください。
他のノードの定義・接続は一切変更しないでください。
ノードごとに指示を分けることで、git diffに出る変更範囲もそのノードだけに収まり、レビューがしやすくなります。1ノード=1コミット程度の粒度にしておくと、後から「どのノードをいつ・どう変えたか」をgit logで追えます。
git add workflow.yml
git commit -m "feat(wf): analyze_dataノードのプロンプトを調整"
50ノード規模のワークフローだとこの工程がそれなりの回数になりますが、機械的に「1ノードずつ、他は触らせない」を徹底するだけなので、時間はかかっても質は安定します。
ステップ3：変数の整合性をチェックする
全ノードのチューニングが終わったら、最後に変数参照の整合性だけをまとめてチェックします。ノード単位の作業中は見落としやすいポイントなので、独立した工程として切り出します。
workflow.yml 全体を確認してください。
以下の観点で、変数参照の不整合があれば一覧にしてください。
- 参照している変数が、実在するノードの出力キーを指しているか(未接続・存在しない参照がないか)
- 参照元と参照先で型が一致しているか(文字列を期待している箇所に配列を渡していないか、など)
- リネーム・削除したノードを参照したままの箇所が残っていないか
実際にこの工程で、型が一致していない変数参照や、リネーム後に参照が更新されていない箇所が複数見つかりました。ノード単位のチューニングでは1ノードずつしか見ていないため、こうした「ノードをまたいだ整合性の崩れ」はこのステップまで残っていることが多いです。
不整合が出た場合は、指摘された箇所だけを修正させて再度チェックを回します。
git add workflow.yml
git commit -m "fix(wf): 変数参照の型不一致・未接続を修正"
インポートして動作確認
ここまでの変更をDify側にインポートし直し、実際に実行して動作を確認します。GUI上の設定とYAMLの内容がずれないよう、編集はYAML側のみで行い、GUIでは直接いじらないことを徹底しています。
まとめ
- DifyワークフローはGUIで直接編集せず、エクスポートしたYAMLをClaude Codeで編集してからインポートし直す
- 一気に全体を生成させず、①大枠(ノード構成・接続)→②ノード単位のチューニング→③変数の整合性チェック、の3ステップに分けて進める
- 各ステップの単位でコミットしておくと、
git diffでのレビューやgit logでの変更追跡がしやすい - 変数の整合性チェックはノード単位の作業では拾いきれないため、最後に独立した工程として実施する
なぜGUIをやめてこの運用にしたのか、最初に一気に生成させて失敗した経緯についてはZenn版で書いています。