n8n-workflow-lifecycle

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

6 つのステージ

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

ステージを省略すると、完成したように見えて本番環境で壊れるワークフローや、根本的に誤った問題を解決するワークフローが生まれます。よくある省略は次の 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 を参照してください。

推奨される既定の方針

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

検証だけでは不十分です

validate_workflow はスキーマと形式のチェックを実行し、パラメーターの不足、型エラー、存在しないノードへの参照を検出します。ただし、次の問題は検出できません。

• .add() 内の .to() によって接続が破棄される問題
• ファンアウトが 1 つの接続にまとめられる問題
• 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 と n8n-subworkflows を参照してください。

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

命名規則

名前の付け方が悪いと、問題は積み重なります。6 か月後に見つけにくいワークフローは、重複して作成されることになります。

動詞と名詞の組み合わせ、大文字・小文字、プレフィックスなど、規則の全容については 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 の references/NAMING_AND_DISCOVERY.md を参照してください。
• タグ： AI 側での検索に使う仕組みです（n8n 2.27.0 以降）。MCP はタグの一覧を取得し（list_tags）、タグでフィルタリングし（search_workflows({ tags })）、タグを付与します（update_workflow の addTags／removeTags。存在しない名前は自動作成されます）。小文字で、ワークフローごとに 2～4 個にします。references/NAMING_CONVENTIONS.md を参照してください。

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

ノードが 5 個を超えるワークフローでは、読みやすさを保つために次の 4 つの工夫が重要です。

• ワークフローの description：AI から得た背景を含め、「なぜ」を記録します。 何をするものか、なぜ存在するのかを 2 文で記述します。特に重要なのは、ファイルには残らず、会話で得た背景を記録することです（設計の根拠となった制約、別の方法ではなくこの方法を選んだ理由、ユーザーが依頼した理由など）。記録しなければ、チャットとともに失われます。
• ノードグループ：ノード数が 10 個を超える場合、論理的な各ステップをグループ化します。 update_workflow の setNodeGroups（n8n 2.28.0 以降）を使って、論理的なステップごとにキャンバスを名前付きグループに分割します（Validate input、Enrich order、Notify など）。各グループは、トリガーを含まない、単一の入口と出口を持つ接続された一連のノードでなければなりません（n8n はそれ以外を拒否します）。折りたたむと、ワークフローはノードではなくステップ単位で読み取れるようになります。分岐が多すぎて 1 つのグループにできないセクションには、代わりに付箋を使います。これは整理のためのもので、グループ内のノードはインラインで実行されます（再利用と分離はサブワークフローの役割です）。
• 付箋：目的ごとにノードをグループ化します。 n8n-nodes-base.stickyNote ノードを使い、Markdown の content（1 行目は ### Title、本文は 1～3 文）と、1～7 の整数 color を指定します。タイトルには目的を記載します（If, Set, If ではなく Validate input）。少数の色に絞って統一します（例：処理にはグレー／黄色、エラーには赤、TODO にはピンク）。色をランダムに使っても意味は伝わりません。
• ノードの notes：分かりにくい設定の理由を記します。 回避策が必要な理由や Code ノードの処理内容を説明します。自明なノードには注釈を付けないでください。

さらに、次の 2 点にも注意してください。

• 独自の規則を取り入れる前に、既存プロジェクトの規則に合わせます。 search_workflows と get_workflow_details を使って近くのワークフローをいくつか確認し、付箋の配色、命名、説明のスタイルを踏襲します。
• レイアウトは作成時／更新時に自動で適用されます。 sticky 以外のノードに指定した SDK の position 値は無視されます。読みやすさを左右するのは、付箋、ノードグループ、命名です。

フォルダーの制限

MCP は、すでに存在するフォルダーにワークフローを配置できます。次の操作はできません。

• 新しいフォルダーの作成
• 既存のフォルダーの移動
• 既存のワークフローの別フォルダーへの移動

ユーザーが存在しないフォルダーを指定した場合は、構築を始める前にそのことを伝えてください。プロジェクトのルートに黙って作成して成功したと報告してはいけません。次の選択肢を提示してください。

1. ユーザーが手動でフォルダーを作成し、その後、そこにワークフローを配置します。
2. ほかの既存フォルダーを使用します。
3. ルート階層への配置で問題ないか確認します。

search_folders で既存のフォルダーを検出する方法を含むプロトコル全体については、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 の必須事項 #2 を参照してください。
• 不足している認証情報を作成する。 ユーザーがチャットにシークレットを貼り付けた場合や、ワークフローでまだ存在しないアカウントが必要な場合は、認証情報の種類を伝え、UI で作成するよう依頼してください。
• 不足しているフォルダーを作成する。 MCP はフォルダーを作成できません。ユーザーが存在しないフォルダーを指定した場合、そこにワークフローを配置する前に、ユーザーがフォルダーを作成する必要があります。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/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 を参照してください。
15 ノードのワークフローに付箋がない	読み手は目的の箇所を探すために、すべてのノードを読む必要があります	論理的なセクションごとに付箋を追加します。上記の「可読性」を参照してください
「Set、If、Set」のようなタイトルの付箋、または色を多用した付箋	目に見える内容を繰り返すだけになり、色が単なるノイズになります	目的をタイトルにし、カテゴリごとに 1 色を使います
description: "Sends Slack."	トリガーや Slack ノードから分かること以上の情報がありません	理由と AI が導き出した背景を含めます。「創業者に週次サマリーを送信します。これまで何度も抜けていた手動レポートを置き換えます。」
ファンアウトする分岐が並行実行されるものとして設計する	n8n はファンアウトする分岐を Y 位置の上から下へ順番に実行します。合計実行時間は分岐の合計であり、最長の分岐の時間ではありません	実際に並行実行するには、mode: 'each' と waitForSubWorkflow: false を指定して Execute Workflow でディスパッチします。n8n-subworkflows の「Fire-and-forget parallelization」を参照してください