n8n-builder

[H1][N8N-BUILDER]

要旨： スキーマに準拠すれば、実行時の検証エラーなしで n8n にインポートできます。

有効な n8n ワークフロー JSON を生成します。

タスク：

1. schema.md を読む — ルート構造、設定
2. nodes.md を読む — ノード定義、typeVersion
3. connections.md を読む — グラフトポロジー、AI タイプ
4. （動的な値）expressions.md を読む — 変数、関数
5. （特定のノード）integrations.md を読む — ノードパラメーター
6. JSON を生成 — workflow.template.md のテンプレートを適用
7. 検証 — uv run .claude/skills/n8n-builder/scripts/validate-workflow.py を実行

REFERENCE: index.md — ファイル一覧。

---

[0][N8N_2.0]

要旨： 破壊的変更により、2025年以前のパターンは無効になります。

破壊的変更（2025年12月）：

• Database — PostgreSQL が必須です。MySQL/MariaDB のサポートは廃止されました。
• Python — "language": "python" は削除されました。タスクランナーで "pythonNative" を使用してください。
• Security — ExecuteCommand と LocalFileTrigger はデフォルトで無効です。
• Code Isolation — Code ノードでの環境変数へのアクセスはブロックされています（N8N_BLOCK_ENV_ACCESS_IN_NODE=true）。
• Agent Type — エージェントタイプの選択は削除されました（v1.82 以降）。すべてのエージェントは Tools Agent です。

---

[1][SCHEMA]

要旨： ルート構造により、n8n パーサーがワークフローを認識して実行できるようになります。

ガイダンス：

• AI Workflows — 設定に executionOrder: "v1" が必要です。これがないと、非同期ノードの順序付けに失敗します。
• Portability — 認証情報 ID と errorWorkflow UUID はインスタンス固有です。インポート後に再割り当てが必要になることを想定してください。
• Optional Fields — 省略するよりも、空のオブジェクト（"pinData": {}）を含めてください。インポート時のエッジケースを防げます。
• Sub-Workflow Typing — トリガーノードで workflowInputs スキーマを使用し、実行前に呼び出し元のペイロードを検証してください。
• pinData Limits — 12MB 未満にしてください。大きなペイロードはエディターのレンダリングを遅くし、バイナリデータを含めることもできません。

ベストプラクティス：

• [ALWAYS] 生成時には "active": false を設定してください。有効化するかどうかはデプロイ時に決定します。
• [NEVER] 認証情報 ID をハードコードしないでください。インスタンス間で移行できるよう、プレースホルダー名を使用してください。

---

[2][NODES]

要旨： 一意の識別子により、ノード間の参照が確実に行えるようになります。

ガイダンス：

• Name Collisions — n8n は重複名を自動で変更します（Set→Set1）。これにより、$('NodeName') 式が気付かないうちに壊れます。
• Version Matching — typeVersion は対象の n8n インスタンスと一致する必要があります。新しいバージョンには後方互換性がない場合があります。
• Error Strategy — フォールトトレラントなパイプラインには onError: "continueErrorOutput" を使用してください。デフォルトでは実行が停止します。
• Node Documentation — インラインドキュメントには notes フィールドを使用してください。notesInFlow: true にするとキャンバスに表示されます。

ベストプラクティス：

• [ALWAYS] 接続を構築する前にノードごとに UUID を生成してください。接続は node.name を参照します。
• [ALWAYS] キャンバスで読みやすくなるよう、ノードの間隔は水平方向に200px、垂直方向に150pxにしてください。

[3][接続]

要点： 接続タイプによって、解析時にワークフローモードを区別できます。

ガイダンス：

• AI vs Main — AI ノードには専用のタイプ（ai_tool、ai_languageModel）が必要です。main を使うと、ツールが気づかれないまま表示されなくなります。
• ファンアウト — 1 つの出力から複数のノードへ接続すると、並列実行されます。配列内の順序は非決定的です。
• 複数出力 — 配列インデックスは出力ポートに対応します。IF ノードの場合、インデックス 0 は true ブランチ、インデックス 1 は false ブランチです。
• 単一モデル — エージェントが受け付ける ai_languageModel 接続は 1 つだけです。複数のモデルを接続しても、競合は通知されません。
• メモリのスコープ — ai_memory は 1 回のトリガー実行中のみ保持され、セッションをまたいで保持されることはありません。

ベストプラクティス：

• [ALWAYS] 接続キーと type プロパティの両方を一致させてください。不一致があると、通知されないまま失敗します。
• [NEVER] AI ツールを main タイプで接続しないでください。エージェントが検出できません。
• [NEVER] 1 つのエージェントに複数の言語モデルを接続しないでください。動的に選択する場合は Model Selector ノードを使用してください。

---

[4][式]

要点： 動的評価によって、パラメーターのハードコーディングを避けられます。

ガイダンス：

• 静的 vs 動的 — = を先頭に付けると評価が行われます。付けない場合、{{ }} を含めて値はリテラル文字列として扱われます。
• ピン留めデータ — テストモードでピン留めしたデータには実行コンテキストがありません。.item は失敗するため、代わりに .first() または .all()[0] を使用してください。
• 複雑なロジック — IIFE パターン {{(function(){ return ... })()}} を使うと、複数文の評価が可能になります。
• スコープの混同 — $json がアクセスできるのは現在のノードの入力のみです。他のノードには $('NodeName').item.json を使用してください。

ベストプラクティス：

• [ALWAYS] ノードをまたぐデータには $('NodeName') を使用してください。$json がアクセスできるのは現在のノードの入力のみです。
• [ALWAYS] JSON 文字列内の引用符をエスケープするか、テンプレートリテラルを使用して、無効な JSON になるのを防いでください。
• [NEVER] どのコンテキストでも .item が使えると思い込まないでください。ピン留めデータのテストでは明示的なアクセサーが必要です。

---

[5][インテグレーション]

要点： ノードタイプの選択によって、インテグレーション機能が決まります。

ガイダンス：

• トリガーの選択 — 外部からの呼び出しには Webhook、定期実行には scheduleTrigger を使用します。開始元に応じて選択してください。
• AI ツールの可視性 — サブワークフローツールには description パラメーターが必要です。エージェントはこれをツール選択の推論に使用します。
• コード言語 — Python には "pythonNative" を使用してください。"python" は非推奨です。
• エラーの伝播 — 制御された失敗には stopAndError ノードを使用してください。指定したエラーワークフローがトリガーされます。
• 2025 年の機能 — MCP ノードによりエージェント間の相互運用が可能になります。Guardrails ノードは AI の出力の安全性を確保します。
• 出力パーサー — outputParserStructured の jsonSchema は静的である必要があります。スキーマ内の式は通知されないまま無視されます。
• バッチ処理 — メモリ不足を防ぐには、大規模なデータセットに splitInBatches を使用して、チャンク単位で処理してください。

ベストプラクティス：

• [ALWAYS] Webhook からレスポンスを返すパターンでは responseMode: "lastNode" を設定してください。呼び出し元に出力が確実に返されます。
• [ALWAYS] AI ツールとして使用する HTTP ノードには description を含めてください。説明のないツールはエージェントから見えません。
• [ALWAYS] ワークフロー間でパスが衝突しないよう、各ワークフローに固有の webhookId を設定してください。

---

[6][RAG]

要点： RAG パイプラインは、ドメイン固有のナレッジに基づいて LLM の応答を生成します。

ガイダンス：

• Vector Store Selection — 開発にはシンプルなものを、本番環境での永続化には PGVector／Pinecone／Qdrant を使用します。
• Embedding Consistency — 挿入とクエリには同じ埋め込みモデルが必要です。不一致があると、意味的なずれが生じます。
• Chunk Strategy — Recursive Character splitter を推奨します。文字数を基準に分割する前に、Markdown／HTML／コードを分割します。
• Memory vs Chains — メモリをサポートするのはエージェントのみです。チェーンはステートレスな単一ターンのプロセッサーです。
• Retriever Modes — 複雑な質問には MultiQuery、ノイズの削減には Contextual Compression を使用します。

ベストプラクティス：

• [ALWAYS] ドキュメントの挿入操作とクエリ操作で、同じ埋め込みモデルを使用します。
• [ALWAYS] メモリノードには ai_memory 接続タイプを使用します。main を使用すると、エラーが通知されずに失敗します。
• [NEVER] 本番環境で Simple Vector Store を使用しません。再起動時にデータが失われ、すべてのユーザーがアクセスできるためです。

---

[7][VALIDATION]

要点： エクスポート前に検証することで、n8n のインポート失敗を防げます。

スクリプト：

uv run .claude/skills/n8n-builder/scripts/validate-workflow.py workflow.json
uv run .claude/skills/n8n-builder/scripts/validate-workflow.py workflow.json --strict

チェック項目（12 項目を自動検証）：

• root_required — name、nodes、connections が存在すること
• node_id_unique / node_name_unique — 重複がないこと
• node_id_uuid — UUID 形式が有効であること
• conn_targets_exist — 接続先が既存のノードを参照していること
• conn_ai_type_match — AI 接続キーが type プロパティと一致すること
• settings_exec_order_ai — LangChain ワークフローでは executionOrder: "v1" が必要です
• settings_caller_policy / node_on_error — 列挙値の検証

ガイダンス：

• API Deployment — POST の後に PUT を実行するパターンを使用します。API のバグにより、POST だけでは設定が無視されることがあります。
• Performance — saveExecutionProgress: true を設定すると、ノードごとに DB の I/O が発生します。高スループット（>1000 RPM）では無効にしてください。
• Source Control — 共有時には instanceId を削除します。認証情報ファイルに含まれるのはスタブのみで、シークレットは含まれません。