n8n-workflow-lifecycle-official

n8n ワークフローのライフサイクル

6 つのステージ

1. 計画。 要件を収集し、確認の質問をして、すでに同じ処理を行う既存のワークフロー／サブワークフローを検索します。
2. 構築。 SDK コードを記述します（スキル：subworkflows、node-config、expressions、code-nodes。下記の「読みやすさ」セクションを参照）。validate_node_config は、反復作業、デバッグ、小規模な単一ノードの編集に、補助的な手段として使用します。グラフ全体のノイズなしで、パラメーターごとのエラーを明確に確認できます。VALIDATE での validate_workflow の代わりにはなりません。
3. 検証。 接続を確認するために validate_workflow と get_workflow_details を実行し、各ノードの認証情報をユーザーに確認してもらいます。また、作成できなかったもの（不足している認証情報やフォルダーなど）も作成してもらいます。
4. テスト。 prepare_workflow_pin_data を使って test_workflow を実行し、出力が意図どおりになるまで反復します。
5. 公開。 ステージ 3 と 4 が問題なく完了した後にのみ、publish_workflow を実行します。
6. 引き継ぎ。 本番環境への引き継ぎとして、起動方法、返される内容、監視すべき点、効果的に使用するために知っておくべきことを説明します。

ステージを省略すると、完成したように見えて本番環境で壊れるワークフローや、問題そのものを解決できていないワークフローが生まれます。最もよくある省略は次の 3 つです。

• 計画前に構築する。 「ユーザーが X を頼んだので、すぐにコーディングを始めよう」と考え、X の意味や、同じロジックがサブワークフローとしてすでに存在するか、どのフォルダー／プロジェクトに配置すべきかを確認しません。後から作り直すより、確認の質問を 1 つする方が低コストです。
• ユーザー側の接続設定前にテストする。 ユーザーがノードごとの認証情報を確認する前に test_workflow を実行すると、誤ったサービスに接続したり、401 エラーが発生したりします。VALIDATE の一環として、ユーザー側の設定を完了してもらいます。
• テストせずに公開する。 検証に合格したということは、SDK の形式が正しいという意味であり、ワークフローが正しいという意味ではありません。

必須事項

1. 公開前に検証と確認を行う。 SDK コードに対して validate_workflow を実行し、作成／更新のたびに get_workflow_details を実行して connections オブジェクトを確認します。検証だけでは、接続が気づかれないまま削除されているケースを見逃します。validate_node_config はノードごとの個別反復に使うツールであり、このステップの代わりにはなりません。
2. 既知の制限をユーザーに伝える。 フォルダー、MCP アクセス、その他の制限によってリクエストを実行できない場合は、そのことを明確に伝え、実現するための方法を提案します。誤った場所にワークフローを黙って配置したり、リクエストを完全には実行できていないのに成功したと報告したりしないでください。
3. 自動ピン留めされない下流ノードに副作用がある場合は、テスト前に確認する。 test_workflow はトリガー、認証情報を使用するノード、HTTP Request ノードを自動でピン留めします。それ以外（Code、Edit Fields、If、Wait、Execute Command、ファイル操作、サブワークフローの呼び出し、Data Tables）は実際に実行されます。これらがユーザーに見える副作用を引き起こす場合は、実行前にユーザーに確認してください。references/TESTING.md を参照してください。

推奨されるデフォルト

• 公開前にテストする。 test_workflow と prepare_workflow_pin_data を使用します。トリガーの種類ごとのモック方法、個別ノードのピン留め方法、副作用が発生する範囲については references/TESTING.md を参照してください。実行を監視できる内部用の単発スクリプトでは、より柔軟に対応できます。
• create_workflow_from_code には必ず description を含める。 何を行い、なぜ行うのかを 1～2 文でまとめます。下記の「読みやすさ」を参照してください。

検証だけでは不十分

validate_workflow は、スキーマと構造を検査します。具体的には、パラメーターの不足、型エラー、存在しないノードへの参照を確認します。ただし、次の問題は検出できません。

• .add() 内の .to() による接続の問題（接続が気づかれないまま削除される）
• 複数の接続先への分岐が、単一の接続にまとめられる
• Merge のインデックスが 1 ずれている
• onError: 'continueErrorOutput' を設定せずに、エラー出力が接続されている
• 構文上は有効でも、意味的に誤っているパラメーター（例：誤ったシート ID や列名）

検証は必要ですが、それだけでは十分ではありません。本番公開の判定基準は次のとおりです。

1. validate_workflow に合格している。
2. get_workflow_details が、意図した内容と一致する connections オブジェクトを返す。
3. test_workflow が、代表的なピン留めデータに対して正しい出力を生成する。

その後にのみ、publish_workflow を呼び出します。

公開前の完全なチェックリストについては、references/VALIDATION_CHECKLIST.md を参照してください。

実行モデル

n8n ワークフローは、左から右へ、上から下へ順番に実行されます。キャンバス上で並列に見える分岐（1 つのソースから複数の下流ノードへの分岐）は、キャンバス上のターゲットノードの Y 座標順に、1 つずつ実行されます。自動的な並行処理はありません。

実際には、次のような影響があります。

• 低速な HTTP 呼び出し 3 つへの分岐は直列で実行されます。合計レイテンシは最大値ではなく、各呼び出しの合計です。
• 「並列」分岐は実行順にワークフローの状態を共有します。下流のノードが参照するのは、最後の分岐が残した状態です。
• 実際に並行処理するには、mode: 'each' と waitForSubWorkflow: false を指定してサブワークフローをディスパッチします。n8n-loops-official と n8n-subworkflows-official を参照してください。

これはプラットフォームの動作であり、SDK の癖ではありません。並行処理を前提に分岐を設計しないでください。

命名規則

見つけにくいワークフローは、重複が積み重なります。半年後に見つけにくいワークフローは、複製されてしまいます。

詳細な規則（動詞と名詞のパターン、大文字・小文字、接頭辞）については、references/NAMING_CONVENTIONS.md をお読みください。概要は次のとおりです。

• ワークフロー： 動詞から始め、対象を明確にします。Customer report sender ではなく Send weekly customer report とします。
• ノード： ノードの種類ではなく、このワークフロー内での動作を表す名前にします。Postgres1 ではなく Fetch active customers とします。
• サブワークフロー： わかりやすい名前を付けます（Parse RFC2822 date）。カテゴリは名前の接頭辞ではなく、タグ（subworkflow、ドメインタグ、tool）で示します。search_workflows({ tags }) で絞り込めます。n8n-subworkflows-official の references/NAMING_AND_DISCOVERY.md を参照してください。
• タグ： AI 側での検出手段です（n8n 2.27.0 以降）。MCP では一覧表示（list_workflow_tags）、絞り込み（search_workflows({ tags })）、付与（update_workflow の addTags／removeTags。未知の名前は自動作成）を行えます。小文字で、ワークフローごとに 2～4 個にします。references/NAMING_CONVENTIONS.md を参照してください。

読みやすさ：説明、ノードグループ、付箋、規則

読みやすさを支える要素は 4 つあります。グループ化はボックスが 7 個以上の場合に、それ以外の 3 つはノードが 5 個ほどになった時点で検討します。

• ワークフローの description：AI から得たコンテキストも含め、「なぜ」を記録します。 何をするのか、なぜ存在するのかを 2 文で記述します。特に重要なのは、会話中に把握したものの、ファイルには残らないコンテキストを記録することです（設計の根拠となった制約、別の方法ではなくこの方法を選んだ理由、ユーザーが依頼した理由など）。記録しなければ、チャットとともに失われてしまいます。
• ノードグループ：ノードをグループ化する唯一の方法です。 論理的なステップごとに名前付きの枠を作成します（Validate input、Enrich order、Notify）。整理のみを目的とし、メンバーはインラインで実行されます（再利用と分離はサブワークフローの役割です）。グループを作成または編集する前と、グループの問題が報告された保存の後には、必ず references/NODE_GROUPS.md をお読みください。事前に把握しておくべき点は次の 3 つです。
  • タイミング： グループをすべて折りたたんだ状態でボックスが 7 個を超える場合は、通常 3～5 個のグループにまとめます。ボックスにはトリガー、各グループ、グループ化されていない各ノードが含まれます。サブノードと付箋は数えません。
  • グループは、トリガーを含まない接続されたセクションでなければならず、各方向に外向きのメンバーは最大 1 つまでです。 Agent のサブノードはすべてグループ内に含めるか、すべてグループ外に配置する必要があります。メンバーとして指定するのはノードの ID ではなく名前 です。
  • 無効なグループ操作は致命的なエラーにはならず、スキップされます。 また、無関係な編集によって有効な既存グループが通知なく削除されることがあるため、問題なく保存できたように見えてもグループが失われている場合があります。ただし、説明が 145 文字を超える場合は例外で、update_workflow 呼び出し全体が拒否されます。作成時と更新時には必ずグループフィールドを確認し、完了を報告する前に修復してください。
• スティッキーノート：グループ化ではなく注釈に使います。 グループ化は（上記のとおり）ノードグループの役割です。スティッキーノートには、グループ名では伝えられない内容を記します。補足、TODO、警告などです。配置する前に references/STICKY_NOTES.md を読んでください。
  • 作成時は必ずアンカーを指定します。 sticky(content, [nodes], { color }) はレイアウト後、囲むノードをもとにボックスを算出します。座標を指定するのは、まだ存在しないキャンバスを推測することになります。両方を省略するのはさらによくありません。フォールバックではノートがグラフ全体の下に配置され、ほかのスティッキーノートは避けてもノードは避けないためです。ノートの対象となるノードを指定できないなら、キャンバスに配置すべきではありません。
  • 役割は3つで、アンカーのセットは役割に応じて決まります。 ステージゾーンは1つのステージのノードをアンカーにします。補足は警告対象の単一ノードをアンカーにします。グレーのタイトル帯はフロー全体をアンカーにし、キャンバスを意図的にグループ化しない場合に限って、まれに使います。
  • 規模： ノードが約5個未満なら、スティッキーノートは不要です。ボックスが5～7個なら、ステージごとにゾーンを1つ配置します。7個を超える場合は、ノードグループでセクション分けし、説明文でもキャンバスを記述します。また、グループ化したノードはアンカーにしません。ノートが展開されたグループの上に重なり、折りたたまれた状態では何にも合致しない、チップ状の位置になるためです。
  • ゾーンには、算出されたボックスに含まれない余白が必要です。 1行のゾーンには height: 272、分岐の扇状配置には 464 を指定します（Message an Agent v2+ では32を追加）。幅は指定しないでください。そのうえで、キャンバスが完成してから、すべてのゾーンを1回のまとめた update_workflow で横に広げます。x = min(node.x) - 56、width = span + 112 とします。ノードから算出するため、再実行しても問題ありませんが、これは仕上げの工程であり、編集ごとに行うものではありません。
  • update_workflow にスティッキーノートの操作はありません。 ここでスティッキーノートを追加するには、n8n-nodes-base.stickyNote の addNode を使い、parameters に content、width、height、color を指定します。position を省略すると [0, 0] になります。
  • 内容と色： 要点を示す ### Title と短い1行を記します。ノードに重ならず表示されるのは上部の64pxだけなので、テキストを増やすために高さを追加してはいけません。長い説明はノードの notes またはワークフローの description に記載します。color の1～7は、その場所で何が起きるかを表します。緑は作成または人が関与する処理、赤は破壊的または取り消せない処理、青はルーティングと変換、グレーはドキュメントです。ただし、ユーザーの好みがある場合はそれを優先し、次に近くのワークフローに合わせます。
• わかりにくい設定にはノードの notes を使います。 回避策が必要な理由や、Code ノードの処理内容を説明します。明白なノードには注釈を付けません。

さらに2点：

• 独自の規約を導入する前に、既存プロジェクトの規約に合わせます。 search_workflows と get_workflow_details を使って近くのワークフローをいくつか確認し、スティッキーノートの配色、命名、説明文のスタイルを踏襲します。
• レイアウトが実行されるのは作成時だけで、更新時には実行されません。 create_workflow_from_code は、明示的な position が設定されていないすべてのノードをレイアウトするため、省略して任せてください。一部だけに指定してほかは指定しないのはよくありません。指定した位置は維持され、残りのノードはその周囲に配置されるため、ノードが重なる原因になります。update_workflow はレイアウトを一切実行しないため、追加したものは指定した位置にそのまま置かれます。

フォルダーの管理

登録済みのインスタンスでは、MCP がフォルダーを作成・整理します。create_folder、update_folder（名前変更／移動）、move_workflows_to_folder、および作成時の配置に使う create_workflow_from_code の folderId が利用できます。search_folders で名前から ID を特定できます。

ユーザーが指定したフォルダーが存在しない場合は、ルートに作成して成功を報告するのではなく、そのフォルダーを作成してください。フォルダーツールがない場合、そのインスタンスは未登録です。UI でもフォルダーはブロックされているため、手動で作成せず、ユーザーに登録を依頼してください（無料。Settings 内で行えます）。フォルダーを削除するツールはありません。また、プロジェクトは読み取り専用です。

プロトコルの詳細は references/FOLDER_LIMITATIONS.md を読んでください。

ワークフローごとの MCP アクセス

各ワークフローには availableInMCP フラグがあります。デフォルトの設定は、誰が作成したかによって異なります。

• MCP 経由で作成されたワークフロー（create_workflow_from_code）は、デフォルトで MCP からアクセス可能です。切り替え操作は不要です。search_workflows で検索して、すぐに操作できます。
• n8n UI で作成されたワークフローは、デフォルトでオフの場合があります。ユーザーが切り替えを行うまで、あなたからは見えません。

これが問題になる最もよくあるケースは、ユーザーが UI でワークフローを手動で作成し、それを確認または編集してほしいと依頼したものの、あなたには見えない場合です。 存在しない、あるいは別のプロジェクトを検索していると決めつける前に、MCP アクセスが有効になっているかユーザーに確認してください。

MCP 経由で呼び出されるサブワークフローについては、呼び出し元は切り替えなしでコードレベルのサブワークフローとして使用できます。MCP に公開された ツール として呼び出すには切り替えが必要です（MCP で作成されたサブワークフローでは、デフォルトでオンです）。

ケースごとの詳細なガイドとユーザー向けメッセージについては、references/MCP_ACCESS_PER_WORKFLOW.md を参照してください。

ユーザー側での接続設定（ステージ 3 の一部）

ユーザーが行う必要があり、あなたにはできない作業があります。テスト前に済ませておかないと、誤った認証情報でテストが実行されたり、フォルダーが見つからなかったり、401 エラーが発生したりします。TEST の前に、VALIDATE 中に次の項目を簡潔なリストとして伝えてください。

• ノードごとに認証情報を確認する。 newCredential('Label') は表示上の設定にすぎません。n8n は、該当する種類の認証情報のうち最後に編集されたものを自動的に割り当てます。複数ある場合（本番用とステージング用の Gmail、2 つの API キーなど）、誤ったものが気づかれないまま選ばれる可能性があります。ユーザーには「認証情報を使用するすべてのノードを開き、正しい認証情報が選択されていることを確認してください」と伝えてください。n8n-credentials-and-security-official の必須事項 #2 を参照してください。
• 不足している認証情報を作成する。 ユーザーがチャットにシークレットを貼り付けた場合や、まだ存在しないアカウントがワークフローで必要な場合は、認証情報の種類を指定し、UI で作成するよう依頼してください。
• フォルダー用に登録する（ツールが見つからない場合のみ）。 フォルダーツールを使うには、インスタンスの登録が必要です。ツールが見つからない場合は、ユーザーに登録（無料、Settings 内）してもらってから、フォルダーを作成または配置できます。登録されていない場合は、フォルダーの処理をあなたが行います。references/FOLDER_LIMITATIONS.md を参照してください。
• ユーザーが作成したワークフローの MCP アクセス切り替え。 MCP 経由であなたが作成したワークフローは、デフォルトで MCP からアクセスできます。テストで UI 作成のワークフローを MCP から呼び出す必要がある場合にのみ、この切り替えが関係します。references/MCP_ACCESS_PER_WORKFLOW.md を参照してください。

これらが完了したと確認できるまで、TEST に進まないでください。

引き継ぎ：本番環境への引き継ぎ（ステージ 6）

publish_workflow の実行後、テストに問題がなければ、ワークフローは技術的には稼働中ですが、ユーザーが本番環境で実際に使うには、まだ十分な情報が必要です。フリーランサーから顧客への引き継ぎと同じように、簡潔で構成が明確であり、今後の運用方法を重視した内容にしてください。

含める内容：

• 起動方法。 Webhook URL（公開済みなので現在有効です）、スケジュールの実行間隔とタイムゾーン、手動トリガーボタン、サブワークフローからの呼び出しなど、該当するものを記載します。Webhook の場合は、URL を渡してください。
• 返される内容／データの送信先。 1 文で記載します。「customers テーブルに新しい行を書き込みます」「呼び出し元に JSON で応答します」「オンコール用の Slack チャンネルに通知します」などです。
• 実際の呼び出し方法と例。 「curl -X POST <url> -d '{...}' で Webhook を呼び出します」「UI から手動でトリガーします」「最初のスケジュール実行は 09:00 UTC までお待ちください」などです。
• 監視する項目。 アラートやエラーとして表面化する障害の種類、上流サービスのレート制限、問題発生時に最初に確認する場所（実行タブ、エラーワークフロー、監査ログなど）を記載します。
• MCP アクセスの状態。 MCP 経由でワークフローを作成した場合、すでに MCP からアクセスできます。アクセスを制限したい場合は、Settings で取り消せることをユーザーに伝えてください。UI で手作業で作成した場合は、ほかのエージェントが呼び出せるように、MCP アクセスを有効にする必要があります。
• ユーザー側で未対応の作業。 チャットに貼り付けたトークンのローテーション、アクセスできずに残った後続の接続設定、付箋に残した既知の TODO などです。

簡潔にまとめてください。箇条書きは 6 項目程度にし、長文にはしないでください。ユーザーが「では、次はどうすればいいですか？」と尋ねずに済むようにしてください。

参考ファイル

ファイル	読むタイミング
references/NAMING_CONVENTIONS.md	新しいワークフロー、サブワークフロー、またはノードに名前を付けるとき
references/NODE_GROUPS.md	ノードグループを作成または編集する前、または保存時にグループがスキップまたは削除されたと報告された後
references/STICKY_NOTES.md	いずれかのツールで付箋を追加、移動、またはサイズ変更するとき
references/FOLDER_LIMITATIONS.md	ユーザーがフォルダーやプロジェクト構成に言及したとき、またはワークフローを整理したいとき
references/MCP_ACCESS_PER_WORKFLOW.md	自分または別のエージェントが MCP 経由で呼び出すワークフローを作成するとき
references/VALIDATION_CHECKLIST.md	ワークフローが完成し、publish_workflow を呼び出す直前
references/REVIEW_CHECKLIST.md	既存のワークフロー（作成時期や作成者を問わず）をレビューまたは監査するとき。公開前の検証チェックリストとは異なり、重大度別の指摘事項が記載されています
references/TESTING.md	test_workflow または execute_workflow を実行するとき、トリガー入力をモックするとき、または副作用のプロトコルを確認するとき

アンチパターン

アンチパターン	問題点	対処方法
検証せずに publish_workflow を呼び出す	壊れたワークフローが本番環境に反映されます	検証し、接続を確認してからテストします
指定されたフォルダーが存在しないため、ルートにワークフローを作成する	ワークフローが見つけにくくなり、ユーザーが手動でドラッグして移動する必要があります	作成前に制約を伝えます
汎用的なノード名（HTTP Request1、Set2）	1 か月後にはワークフローが読みにくくなります	アクションの内容が分かる名前に変更します
create_workflow_from_code で description を指定しない	ワークフローが検索結果に表示されず、保守担当者向けの説明もありません	必ず 1～2 文を記載します
MCP 経由で作成したワークフローの MCP アクセス切り替えをユーザーに依頼する	ユーザーの時間を無駄にします。エージェントが作成したワークフローは、デフォルトで MCP からアクセスできます	切り替えに言及するのは、UI で作成したワークフローの場合、またはエージェントが作成したワークフローの MCP アクセスをユーザーが取り消したい場合に限ります
副作用のある未固定の下流ノードがあるワークフローに対し、確認せずに test_workflow を実行する	Data Table への実データの書き込み、サブワークフローの実際の副作用、Execute Command の実際の出力などが発生します。トリガー、認証情報を使うノード、HTTP は固定されますが、それ以外は固定されません	まず確認します。references/TESTING.md を参照してください。
トップレベルのボックスが 7 個を超えるキャンバスにノードグループがない	読み手は目的のノードを探すために、すべてのノードを確認しなければなりません	論理的な手順ごとにグループ化します。references/NODE_GROUPS.md を参照してください
グループのフィールドを確認せずに、作成や更新が完了したと報告する（作成時は skippedGroups、更新時は skippedOperations / removedGroups）	グループ操作が通知なくスキップされたり、無関係な編集によって既存のグループが削除されたりしているのに、保存は成功したように見えます	毎回確認し、修復します。references/NODE_GROUPS.md を参照してください
グループの代わりに付箋を使う、またはすべての色の付箋を使う	グループ化はノードグループの役割です。色が単なるノイズになります	ノードグループでまとめ、付箋は注釈に使い、カテゴリーごとに色を 1 色にします
create_workflow_from_code で付箋の位置を手動で指定する	座標はレイアウト実行前に決まるため、付箋が説明対象のノードから離れて配置されます	sticky(content, [nodes]) にノードを渡し、ボックスの位置を自動で決めます。references/STICKY_NOTES.md を参照してください
description: "Sends Slack."	トリガーや Slack ノードを見れば分かることしか説明していません	理由と AI が導き出した背景情報を含めます。「創業者に週次サマリーを送信します。何度も省略されていた手動レポートに代わるものです。」
ファンアウト分岐が並行して実行される前提で設計する	n8n のファンアウト分岐は、Y 座標の上から順に逐次実行されます。合計実行時間は各分岐の合計であり、最大値ではありません	実際に並行実行するには、mode: 'each' と waitForSubWorkflow: false を指定して Execute Workflow 経由でディスパッチします。n8n-subworkflows-official の「Fire-and-forget parallelization」を参照してください