⚠️
概念 #Dify #アンチパターン #設計 #ベストプラクティス #失敗事例 #実践 📚 Dify実践ガイド

Difyアンチパターン集（設計・プロンプト・RAG・運用の落とし穴）

Difyで実際によく起きる設計ミス・プロンプトの落とし穴・RAG精度低下の原因・運用で詰まるポイントを体系的に整理した逆引きガイド。

このドキュメントの使い方

「なぜかうまくいかない」と感じたとき、まずここを確認する。
アンチパターンを設計層・プロンプト層・RAG層・運用層の4カテゴリで整理した。

設計層のアンチパターン

AP-1: すべてのロジックを LLM に任せる

❌ 悪い例:
  1つの LLM ノードに「ユーザー入力を分類し、
  必要な情報を検索し、返信を生成し、感情に応じてトーンを変えろ」
  と1万文字のシステムプロンプトを書く

問題:
  - 処理が複雑になるほど LLM の精度が落ちる
  - どのステップが失敗したかデバッグできない
  - 1箇所変更すると全体に影響する
  - コストが高くなる（常に長いコンテキストを消費）

✅ 正しい設計:
  役割ごとにノードを分割する
  [分類 LLM] → [検索ノード] → [生成 LLM] → [トーン調整 LLM]

  各ノードの責務を1つに絞る（Single Responsibility）

AP-2: ワークフローを1つに詰め込みすぎる

❌ 悪い例:
  500行を超えるワークフローに全機能を詰め込む
  → レイアウトがスパゲッティ化
  → チーム内で誰も触れなくなる

✅ 正しい設計:
  Workflow を機能単位で分割し、HTTP Request で連携する

  例:
    workflow_analyze.dsl    - 分析処理
    workflow_generate.dsl   - コンテンツ生成
    workflow_notify.dsl     - 通知処理

  親ワークフローから子ワークフローを呼び出す構成にする
  → 1ワークフロー = 1画面に収まる規模を目安にする

AP-3: Human-in-the-loop を省略する

❌ 悪い例:
  AI が生成したメール・契約書・診断結果を
  人間の確認なしに自動送信・自動保存する

問題が起きやすいケース:
  - 「田中様」と書くべき箇所に「{{customer_name}}」が残る
  - 法的に問題のある表現が混入する
  - ハルシネーションした数値がレポートに掲載される

✅ 正しい設計:
  重要なアクション（メール送信・DB書き込み・外部API呼び出し）の
  直前に Human Input ノードを挿入する

  リスクレベル別に確認の粒度を変える:
    低リスク: 自動実行 OK
    中リスク: プレビュー表示 + ワンクリック承認
    高リスク: 担当者のレビュー + 記録

AP-4: エラーハンドリングを設計しない

❌ 悪い例:
  LLM が空文字を返したとき、次のノードが空文字を処理しようとして
  ワークフロー全体がサイレントに失敗する

よくある無言失敗ケース:
  - API が 429 (Rate Limit) を返してもリトライしない
  - PDF に文字が含まれていないとき Doc Extractor が空を返す
  - JSON パースエラーが無視される

✅ 正しい設計:
  条件分岐でエラーパスを明示的に設計する

  [LLM ノード]
    → 成功: 次の処理へ
    → 失敗 / 空文字: [Error ハンドラー]
         - ユーザーへのエラーメッセージ表示
         - Slack/メールへのアラート通知
         - フォールバック処理

  Code ノードでの防御的実装:
  ```python
  result = variables.get("llm_output", "")
  if not result or len(result.strip()) == 0:
      return {"error": "LLM returned empty response", "fallback": True}

---

## プロンプト層のアンチパターン

### AP-5: システムプロンプトが長すぎる・曖昧すぎる

❌ 悪い例（長すぎる）: System Prompt に 5,000 文字以上のルールを詰め込む → LLM は後半のルールを「忘れる」傾向がある → どのルールが守られたか検証できない

❌ 悪い例（曖昧すぎる）: 「丁寧に答えてください」 「適切な情報を提供してください」 → LLM が「丁寧」「適切」を自己解釈して品質がバラつく

✅ 正しい設計: 具体的・測定可能な指示に書き直す

❌ 「丁寧に」→ ✅ 「敬語（です・ます体）を使い、 一文を50文字以内に収めること」

❌ 「適切な情報を」→ ✅ 「回答は3つの箇条書きで、 各項目は1文以内にまとめること」

ルールが10個を超えたら分割を検討する


### AP-6: Few-shot 例を入れない

❌ 悪い例: 「JSONで出力してください」だけ書いて出力形式が安定しない

問題:

  • LLM によって JSON の構造・キー名が変わる
  • マークダウンのコードブロックで囲まれたり囲まれなかったりする
  • null vs “null” のような微妙な差異でダウンストリームが壊れる

✅ 正しい設計: 出力例を1〜2件プロンプトに含める

「以下の形式でJSONを出力してください: { “category”: “技術系”, “priority”: 1, “summary”: “要約テキスト” } ※コードブロックや余分なテキストは不要です」


### AP-7: 言語モデルに算数をさせる

❌ 悪い例: LLM ノードに「合計金額を計算して」「割引後の価格を出して」 と指示する

問題: LLM は確率的なテキスト生成エンジンであり、 計算は非常に得意ではない。 桁数が多いと誤答率が急上昇する。

✅ 正しい設計: 数値計算は Code ノード（Python）で処理する

[LLM: 数値を抽出] → [Code: Python で計算] → [LLM: 結果を文章化]

price = float(variables.get("price", 0))
discount = float(variables.get("discount_rate", 0))
final_price = price * (1 - discount / 100)
return {"final_price": round(final_price, 2)}

---

## RAG 層のアンチパターン

### AP-8: チャンキング設定をデフォルトのまま使う

❌ 悪い例: デフォルト設定（500トークン・重複50トークン）で すべての文書を登録する

問題: 文書の種類によって最適なチャンクサイズが大きく異なる

法律文書・契約書: 条文の区切りでチャンキングしないと 文脈が切れて誤回答につながる FAQ: 1 Q&A = 1チャンクでないと質問と回答が分離する マニュアル: セクション単位（見出しレベル）でチャンキングが最適

✅ 正しい設計: 文書種別ごとにチャンキング戦略を変える

文書種別推奨チャンクサイズ推奨区切り
FAQ200〜300トークンQ&A単位
法律文書条文単位条番号
技術ドキュメント500〜800トークンセクション見出し
会話ログ発言単位ターン

### AP-9: ナレッジベースの更新を怠る

❌ 悪い例: 「2024年4月版」の規程集を登録したまま1年放置する → 法改正・規則変更があっても古い情報を回答し続ける

問題が発生しやすいコンテンツ:

  • 料金表・価格情報
  • 法令・規制
  • 組織図・担当者情報
  • 手続きフロー・締切日

✅ 正しい設計: 更新プロセスを事前に設計する

  1. 各文書に「有効期限」メタデータを付与する
  2. 定期レビュー担当者・スケジュールを決める
  3. ナレッジベースへの変更をバージョン管理する （例: ファイル名に YYYYMM を含める）
  4. 情報の鮮度をシステムプロンプトに明示する 「このナレッジは2026年4月時点の情報です」

### AP-10: 機密情報・個人情報をナレッジベースに丸ごと登録する

❌ 悪い例: 顧客名・連絡先・病歴・財務情報が含まれたCRMエクスポートを そのままナレッジベースに登録する

問題:

  • RAG 検索で別のユーザーの個人情報が返答に含まれる可能性
  • クラウド型 Dify の場合、OpenAI 等に個人情報が送信される
  • データ漏洩リスクが大幅に高まる

✅ 正しい設計: ナレッジベースには「汎用知識」のみ登録する

登録OK: 製品仕様・FAQ・マニュアル・規程・一般的な手順書

登録NG: 個人情報・顧客情報・取引情報・社員の個人データ

個人情報が必要な場合: → API経由で都度取得し、ワークフロー内だけで使用 → ログに残さない設計にする → セルフホスト + 日本国内サーバーを使用する


---

## 運用層のアンチパターン

### AP-11: ログ・可観測性を後回しにする

❌ よくある状況: 「まずリリースして、問題が起きたら調べよう」と ログ設計を後回しにする → 問題が起きても何が原因かわからない → 「AIの精度が悪い」としか言えなくなる

✅ 正しい設計: リリース前にログ戦略を決める

最低限記録すべき情報: - 入力（ユーザーメッセージ） - 出力（AI の回答） - レイテンシ（各ノードの処理時間） - トークン消費量 - エラー・例外

ツール選定: Dify 内蔵ログ → 基本の確認に十分 Langfuse → 詳細トレース・評価・無料枠あり LangSmith → チームでの評価・データセット管理

詳細: 可観測性・デバッグ・評価


### AP-12: モデル選定をコスト視点で最適化しない

❌ 悪い例: すべてのノードに GPT-4o（高性能・高コスト）を使う

問題: 単純な分類・フォーマット変換・キーワード抽出のような タスクに高性能モデルを使うのはコストの無駄。

✅ タスク別のモデル選定指針:

高精度が必要なタスク: 契約書レビュー・法的判断補助・複雑な推論 → GPT-4o / Claude 3.5 Sonnet

中程度のタスク: 文章生成・要約・翻訳・Q&A回答 → GPT-4o mini / Claude Haiku

シンプルなタスク: 分類・タグ付け・JSON抽出・感情判定 → GPT-4o mini / Gemini Flash（最安クラス）

高頻度な処理: 月100万回以上の呼び出し → Ollama（ローカル）で完全無料化を検討

コスト詳細: Difyのコスト設計と節約テクニック


---

## アンチパターン早見表
カテゴリアンチパターン影響
設計AP-1: LLM に全部任せる精度・コスト・保守性
設計AP-2: ワークフローが巨大化保守性・チーム開発
設計AP-3: Human-in-the-loop省略品質・法的リスク
設計AP-4: エラーハンドリングなし信頼性・デバッグ困難
プロンプトAP-5: プロンプトが長すぎ/曖昧精度・再現性
プロンプトAP-6: Few-shot例なし出力形式の安定性
プロンプトAP-7: LLMに計算させる数値精度
RAGAP-8: チャンキングのデフォルト放置検索精度
RAGAP-9: ナレッジベース更新を怠る情報の鮮度
RAGAP-10: 個人情報を登録するセキュリティ・法令
運用AP-11: ログ設計を後回し障害対応・改善不能
運用AP-12: モデル選定の最適化なしコスト過大

---

## 参考：関連ドキュメント

- [本番リリース前チェックリスト](concepts_dify_production_checklist.md) — このアンチパターンを防ぐ確認手順
- [Difyのコスト設計と節約テクニック](concepts_dify_intro_cost.md) — AP-12 のコスト最適化
- [可観測性・デバッグ・評価](concepts_dify_observability.md) — AP-11 のログ設計
- [ナレッジベース・RAGパイプライン](concepts_dify_knowledge_rag.md) — AP-8〜10 の正しい設計
📚 Dify実践ガイド 11件
  1. 1. ⚠️Difyアンチパターン集（設計・プロンプト・RAG・運用の落とし穴）
  2. 2. ✅Dify本番リリース前チェックリスト＆運用設計ガイド
  3. 3. ✍️Difyプロンプトエンジニアリング実践ガイド
  4. 4. 🔍DifyのRAG精度チューニングガイド
  5. 5. 🛡️Difyハルシネーション対策ガイド
  6. 6. 🔗Dify×n8n連携ガイド（AIと外部サービスをつなぐオーケストレーション）
  7. 7. 🖥️Difyセルフホスト本番構成ガイド（Docker・セキュリティ・スケーリング）
  8. 8. 🏢Dify Enterprise機能ガイド（SSO・RBAC・監査ログ・マルチワークスペース）
  9. 9. 👨‍💻エンジニア向けDifyガイド（API統合・CI/CD・テスト自動化）
  10. 10. 💼ビジネスパーソン向けDifyガイド（ノーコードで始めるAI活用）
  11. 11. 🚀スタートアップ向けDifyガイド（最小コストでAI機能を最速でリリース）

出典: Dify公式ドキュメント / コミュニティ事例・実践知