n8n-architect

n8n Architect

ワークスペースの準備、環境、管理対象のローカルインスタンス、トンネル、ワークフローの作成、検証、同期、プッシュ、プルなど、n8n-as-code に関するすべての作業でこのスキルを使用します。

主なインターフェースとして npx --yes n8nac を使用します。ローカルの管理対象ランタイムのライフサイクル、トンネル、および n8n-manager が明示的に公開しているワークフロー表示コマンドに限り、npx --yes @n8n-as-code/n8n-manager を使用します。

コンテキストルートのプロトコル

• 現在のコンテキストルートは、n8nac-config.json、AGENTS.md、.agents/skills、および設定済みの workflowsPath が含まれるディレクトリとして扱います。
• 生成されたコンテキストルートのヒント：埋め込まれていません。シェルの起動ディレクトリ、またはユーザーが明示したワークスペースパスを使用します。
• n8n の作業を始める前に、まずコンテキストルートから npx --yes n8nac update-ai を実行し、次に AGENTS.md を読みます。update-ai は、既存のユーザーやエージェントの指示を壊すことなく、n8n-as-code ブロックを作成または更新するように設計されています。
• AGENTS.md に記載されている正確な n8nac command と n8n-manager command を使用します。これらのコンテキストルートコマンドは、このスキルの汎用的な例より優先されます。
• ユーザーが別のコンテキストルートを明示している場合を除き、すべての npx --yes n8nac env ...、npx --yes n8nac workspace ...、npx --yes n8nac list、pull、push、validate、test、および update-ai コマンドは、コンテキストルートから実行します。
• AGENTS.md はブートストラップ用のコンテキストであり、設定の正となる情報源ではありません。
• AGENTS.md から環境、プロジェクト、または workflowsPath を推測しないでください。
• n8n の作業を始める前に、バックエンドから有効なコンテキストを解決します。

npx --yes n8nac env status --json

• ワークフローファイルには、返された workflowsPath を使用します。これは、アクティブな環境で設定されているワークフローディレクトリです。
• 環境名／ID、instanceIdentifier、instanceUserIdentifier、projectId、projectName、またはレガシーの同期フィールドから workflowsPath を再構成しないでください。
• n8nac-config.json、~/.n8n-manager、または n8n-manager のシークレットファイルを手作業で書き換えないでください。

ワークスペースの準備

ワークフローの作業を始める前に、バックエンドを通じて有効な環境を解決します。

npx --yes n8nac env status --json

• env status --json を、ワークスペースの有効な準備状況を判断する情報源として扱います。
• 生のファイル、生成されたエージェント向けドキュメント、またはディレクトリ名から準備状況を推測しないでください。
• ワークスペースの .env に N8N_HOST（および N8N_API_KEY、N8N_NATIVE_MCP_URL、N8N_NATIVE_MCP_TOKEN のいずれか）が設定されている場合、初回使用時に default 環境が設定されます。その後、env status --json は env add、env auth set、env use、または native-mcp configure を実行せずに解決できます。
• ワークスペースが設定されていないために env status --json が失敗した場合は、env add、env auth set、および env use を使用して V4 ワークスペース環境を作成または選択します。
• 管理対象のローカルインスタンスは、マシン全体で共有されるランタイムリソースのままです。
• ワークスペース環境はワークスペース単位で管理され、npx --yes n8nac env ... を通じて操作します。

ブートストラップの順序

1. コンテキストルートに cd します。
2. npx --yes n8nac update-ai を実行し、次に AGENTS.md を読みます。
3. npx --yes n8nac env status --json を実行します。accessStatus: "ready" として解決された場合、ワークスペースの準備は完了しているため、手順 4～9 をスキップします。missing-api-key または invalid-api-key として解決された場合、不足しているのは認証情報のみです。手順 7 に進みます。
4. コンテキストルートの準備ができていない場合は、npx --yes @n8n-as-code/n8n-manager instance list を実行して、管理対象のローカルインスタンスを確認します。
5. 適切な既存の環境または管理対象のローカルインスタンスがあれば、それを再利用します。
6. 適切な環境がない場合は、停止して、リモートの n8n URL に接続するか、管理対象のローカル n8n インスタンスを作成／再利用するかをユーザーに確認します。デフォルトでインフラストラクチャを作成しないでください。ユーザーが管理対象のローカルインスタンスを選んだ場合は、パブリックトンネルも必要かどうかを別途確認します。
7. 明示的にリモートの n8n 環境を指定した場合に限り、ホスト／API キーを確認します。
8. 次のコマンドで環境を設定します。

npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

管理対象のローカルインスタンスの場合：

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

9. ファサードが自動で更新しない場合は、環境を変更した後に npx --yes n8nac update-ai を実行します。

環境

ワークスペースの環境、リモート URL、アクティブな環境、API キーのバインド、プロジェクト、ワークフローのパスには、npx --yes n8nac env ... を使用します。

npx --yes n8nac env status --json
npx --yes n8nac env list
npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
npx --yes n8nac env auth set <name> --api-key-stdin
npx --yes n8nac env use <name>

• API キーには --api-key-stdin を優先して使用します。
• デフォルト環境を作成して同時に固定するには、別途 env use を実行するのではなく、env add --pin を優先して使用します。
• シェル引数にシークレットを直接渡さないでください。
• env auth set はキーを1つの環境にバインドするため、複数の環境で同じベース URLを使用し、それぞれに1つずつキーを設定できます。環境ごとに1回実行してください。環境が独自のキーを使用している場合、env status --json の apiKeySource は workspace-environment になります。
• ユーザーがマネージドローカル Docker インスタンスを希望している場合、ホストや API キーを尋ねないでください。
• API キーや認証情報のシークレット値をユーザーに表示しないでください。
• コマンドやフラグが不明な場合は、npx --yes n8nac env --help または npx --yes n8nac env <subcommand> --help を実行してください。

npx --yes n8nac env ... を使用して、マネージドローカルインスタンスをワークスペースに接続します。

npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

マネージドローカルランタイム

ローカルランタイムレイヤーに属するローカルのマネージドインスタンスのライフサイクル、トンネル、ワークフローの表示コマンドに限り、npx --yes @n8n-as-code/n8n-manager を使用します。

ローカルマシンの状態を変更する前に、既存のマネージドインスタンスを確認してください。

npx --yes @n8n-as-code/n8n-manager instance list
npx --yes @n8n-as-code/n8n-manager instance --help
npx --yes @n8n-as-code/n8n-manager config get

n8n-manager のサブコマンドを推測して使用しないでください。不明な場合は、npx --yes @n8n-as-code/n8n-manager <subcommand> --help を使用してください。

コンテキストルートが設定されておらず、適切な既存インスタンスもない場合は、処理を中断してユーザーに選択を求めてください。デフォルトでインフラストラクチャを作成しないでください。

次の選択肢を明確に提示してください。

• 利用可能な既存のマネージドローカルインスタンスを使用する。
• 新しいマネージドローカル n8n インスタンスを作成する。
• npx --yes n8nac env を使用して、リモート n8n URLをワークスペース環境として設定する。

ユーザーがマネージドローカル Docker インスタンスを選択した場合は、トンネルを使用するかどうかを別途尋ねてください。

• パブリックトンネルなし：ローカル n8n のみを使用します。通常の UI／API によるワークフロー作業に適しています。
• パブリックトンネルあり：インスタンスをパブリック URL経由で公開します。Webhook、フォーム、チャットトリガー、リモートコールバックに役立ちます。

ユーザーがパブリックアクセス、Webhook テスト、またはトンネルの使用を明示的に希望もしくは承認しない限り、パブリックトンネルを有効化、更新、開始しないでください。パブリックアクセスが不要な場合は、--tunnel を付けずにマネージドインスタンスを作成または開始してください。

対応する選択肢をユーザーが明示的に選んだ後にのみ、次のコマンドを実行してください。

パブリックトンネルなしのマネージドローカルインスタンス：

npx --yes @n8n-as-code/n8n-manager instance create
npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager instance list

パブリックトンネルありのマネージドローカルインスタンス：

npx --yes @n8n-as-code/n8n-manager instance create
npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager tunnel start <id>

インスタンスとトンネルの操作は、マネージドローカルインスタンスごとに行います。

npx --yes @n8n-as-code/n8n-manager instance start <id>
npx --yes @n8n-as-code/n8n-manager instance stop <id>
npx --yes @n8n-as-code/n8n-manager instance remove <id>
npx --yes @n8n-as-code/n8n-manager tunnel start <id>
npx --yes @n8n-as-code/n8n-manager tunnel stop <id>

• ユーザーが破壊的な削除を明示的に求めない限り、ローカルインスタンスのデータを削除しないでください。
• Docker を利用できない、またはデーモンが停止している場合は、バックエンドの診断情報を報告して処理を中断してください。繰り返し実行しないでください。
• コマンドが繰り返し失敗した場合は、2回試行した時点で中断し、バックエンドの診断情報を説明してください。

同期のルール

• 既存のワークフローを読み取ったり変更したりする前に、プルします。
• 変更するたびにプッシュします。
• list を使って、ワークフロー ID、ファイルパス、同期ステータスを確認します。

npx --yes n8nac list
npx --yes n8nac pull <workflowId>
npx --yes n8nac push <path-to-workflow.workflow.ts> --verify

• push には、絶対パスまたはコンテキストルートからの相対パスで、ワークフローファイルの完全なパスを指定する必要があります。ファイル名だけを指定してはいけません。
• n8n 2.x では、公開済みのワークフローにプッシュすると、本番環境にもリリースされます。更新時に API が再公開するためです。公開済みワークフローへのプッシュは、すべてデプロイとして扱ってください。変更を n8n で先に確認したい場合は、push --draft を使います。これにより、以前に公開されたバージョンが再度ピン留めされ、本番環境ではこれまで実行されていたバージョンが引き続き稼働します。
• 新しいワークフローの場合は、env status --json が返す workflowsPath 内にファイルを作成し、npx --yes n8nac list --local で確認します。
• プッシュまたはプルで競合が報告された場合は、明示的な解決コマンドを使用します。リモートの変更を無条件に上書きしてはいけません。
• pull と競合解決は、単一のワークフロー ID に対して実行されます。
• list は、すべてのワークフローを一度に確認できる軽量なコマンドです。
• プルを省略すると、リモート側に変更があった場合、後続のプッシュが楽観的同時実行制御によって拒否されることがあります。

競合の処理

プッシュまたはプルで競合が報告された場合は、いったん停止して競合を確認します。意図する方向を選択してから、明示的な解決コマンドのみを使用します。

npx --yes n8nac resolve <workflowId> --mode keep-current
npx --yes n8nac resolve <workflowId> --mode keep-incoming

• keep-current は、ローカルバージョンを強制的にプッシュします。
• keep-incoming は、リモートバージョンを強制的にプルします。
• リモートの変更を黙って強制プッシュしてはいけません。

スキーマを最優先した調査

n8n ノードのパラメーターを推測してはいけません。

npx --yes n8nac skills examples search "<workflow pattern>"
npx --yes n8nac skills search "<node or capability>"
npx --yes n8nac skills node-info <nodeName>
npx --yes n8nac skills validate <workflow.workflow.ts>

• ノードのクエリはまとめて実行します。npx --yes n8nac skills node-info <node1> <node2> ... --compact を使って複数のノードを単一のコマンドで照会し、必須プロパティ、必須パラメーター、有効なオプションを、少ないトークン数ですばやく確認します。
• node-info の出力にある正確なノード type と有効な typeVersion の値を使用します。
• スキーマ出力にある正確なリソース名、操作名、オプション名、パラメーター名を使用します。
• resourceLocator 型のパラメーターは、{ __rl: true, value: '...', mode: 'list' | 'id' | 'url' } の形式で構造化する必要があります。
• パラメーター、操作、認証情報の種類、CLI フラグを捏造してはいけません。
• 例や記憶と食い違う場合でも、スキーマ出力を絶対的な情報源として扱います。
• スキーマ出力で返される、最も高い有効な typeVersion を優先します。
• Switch/If ルール、Wait フォームフィールド、ネストされたオプションなどの固定コレクションについては、値を記述する前に node-info の出力全体を確認します。

オプションのネイティブ n8n MCP による補助

n8n-as-code MCP サーバーは、N8NAC ツール向けのクライアントアダプターです。ネイティブ n8n MCP サーバーは、稼働中の n8n インスタンスに接続する別のエンドポイントです。ネイティブ n8n MCP は、ネイティブの知識、ライブ状態、ランタイム実行を補完できますが、このワークフロー、npx --yes n8nac、同梱されたナレッジ、.workflow.ts、Git、同期のルールに取って代わるものではありません。

次のルーティングポリシーを使用します。

• コードファーストのワークフロー作成、検証、プル、プッシュ、認証情報、実行履歴、プレゼンテーションには、デフォルトでローカルの npx --yes n8nac を使用してください。バンドルされたオフラインのナレッジのデフォルトとしては npx --yes n8nac skills を使用してください。
• ネイティブ MCP アシストは n8n-as-code 環境ごとに設定します。環境を作成または更新する際は、npx --yes n8nac native-mcp configure <environment> --token-stdin で設定することを提案してください。Claude Code や VS Code Workbench 用に別の MCP サーバーを手動で設定するようユーザーに求めないでください。
• ネイティブ MCP アシストが設定されている場合は、n8n-as-code を補完する場面で使用してください。読み取り専用のライブ検出、サーバー側の検証、ネイティブ SDK/リファレンスのナレッジ、ライブのノード定義、シークレットを含まない認証情報メタデータ、実行の検査、プロジェクト、フォルダー、およびサポートされている場合の明示的なランタイム実行/テスト戦略です。
• ネイティブツールに依存する前に、npx --yes n8nac native-mcp status --include-tools --json でネイティブの利用可否を確認してください。
• 現在の/ライブの n8n インスタンス、既存のリモートワークフロー、このインスタンスで利用可能なノード、認証情報メタデータ、プロジェクト、フォルダー、実行、ドリフト、または重複の検出に関するユーザーからのリクエストについては、ステータス確認後にネイティブ MCP の読み取り専用ツールを優先してください。ネイティブ MCP の読み取り専用ツールが利用可能な場合、これらのライブ監査の事実に関する主要な情報源として、ローカルの npx --yes n8nac list、fetch、verify、またはバンドルされた skills にフォールバックしないでください。
• MCP トランスポートが認証されており、N8NAC_NATIVE_MCP_ALLOW_REMOTE=1 が明示的に設定されていない限り、非ループバックの HTTP/SSE トランスポートでネイティブ MCP アシストを公開しないでください。
• ユーザーがペイロードデータを明示的に必要としており、N8NAC_NATIVE_MCP_ALLOW_EXECUTION_DATA=1 が設定されていない限り、includeData=true で完全なライブ実行ペイロードをリクエストしないでください。
• 実行戦略が実際の webhook、チャット、またはフォームトリガーのコントラクトを試すことである場合は、npx --yes n8nac test を優先してください。
• 生成された実行戦略が明示的にそれを求め、かつ npx --yes n8nac test よりも優れた処理を行う場合にのみ、ネイティブのランタイム実行を優先してください。たとえば、ワークフロー ID の実行、webhook 以外のワークフローのテスト、ネイティブの pin-data テスト準備、または直接的な実行診断です。
• ネイティブの execute/test は、npx --yes n8nac test と同様に、副作用を伴うランタイムアクションとして扱ってください。ツールが存在するという理由だけで実行しないでください。
• ユーザーがネイティブ MCP の直接モードを明示的に要求し、かつツールが権限で制御されていない限り、ネイティブ MCP の作成、更新、公開、非公開、アーカイブ、または破壊的なデータテーブルツールを使用しないでください。
• ネイティブ MCP の直接モードを通じてワークフローが作成または変更された場合は、直ちに npx --yes n8nac pull <workflowId> でプルバックして、.workflow.ts ファイルと Git が引き続き信頼できる情報源となるようにしてください。
• ネイティブ MCP の検証とローカルの検証が一致しない場合は、プッシュや直接更新を強行するのではなく、停止してその相違を報告してください。
• ネイティブ MCP のトークンを、プロジェクトファイル、生成されたドキュメント、コマンド引数、または応答に決して記載しないでください。

ユースケースルーティングの例:

• ワークフローの作成、編集、プル、プッシュ、同期、認証情報、および永続的なワークフロー変更: ローカルの npx --yes n8nac コマンドと .workflow.ts ファイルを使用します。
• オフラインでのノード知識、例、ドキュメント、スキーマファーストの作成: まずローカルの npx --yes n8nac skills コマンドを使用します。
• ライブのワークフロー検出、ドリフト調査、プロジェクト、フォルダ、認証情報メタデータ、重複の検出、実行の検査: ユーザーが現在のインスタンス状態を求めているため、設定されている場合はネイティブ MCP の読み取り専用ツールを優先します。
• 接続バージョンのノード定義またはサーバー側の検証: ユーザーがこのインスタンスで利用可能なものを尋ねている場合、または接続されている n8n バージョンに対して検証が必要な場合は、ネイティブ MCP の読み取り専用ツールを優先します。ライブのインスタンス状態が不要な場合は、オフラインでの作成にバンドルされた知識を使用します。
• ランタイム実行: 実際の webhook、チャット、またはフォームトリガーのコントラクトには npx --yes n8nac test を優先します。ネイティブのランタイム実行は、明示的なワークフロー ID の実行、webhook 以外のテスト、ネイティブの pin データ準備、または直接実行の診断の場合にのみ優先します。
• ネイティブによる直接のワークフロー作成、更新、公開、非公開、アーカイブ、または破壊的な操作: 自動的な経路として使用しないでください。明示的なネイティブ直接リクエストと同期バックの計画が必要です。

MCP サーバーが存在することを、ネイティブの n8n MCP ツールを呼び出す許可と見なさないでください。ネイティブの n8n MCP は、生成された実行または調査戦略が、ローカルの N8NAC では同程度に提供できないライブの n8n 機能を必要とする場合にのみ使用されます。

ネイティブ MCP アシストは、補完的な知識、ライブ状態、およびランタイムの拡充経路であり、主要な作成または同期の経路ではありません。

知識コマンド

お使いのランタイムが n8n-as-code MCP ツール (search_n8n_knowledge、get_n8n_node_info、 search_n8n_workflow_examples、validate_n8n_workflow) を公開している場合は、以下のコマンドよりもそれらを優先してください。 これらはオントロジーを一度解析する常駐プロセスから応答するため、最初の呼び出し以降は実質的に無料ですが、 各シェルコマンドは毎回新しいプロセスの起動コストを支払います。

そうでない場合は、推測する代わりに次のコマンドを使用してください:

npx --yes n8nac skills search "<node or capability>"
npx --yes n8nac skills node-info <nodeName>
npx --yes n8nac skills node-schema <nodeName>
npx --yes n8nac skills docs "<topic>"
npx --yes n8nac skills guides "<topic>"
npx --yes n8nac skills examples search "<workflow pattern>"
npx --yes n8nac skills examples info <id>
npx --yes n8nac skills examples download <id>

• search、node-info、node-schema では --compact を優先してください: 同じスキーマで、出力が制限されます (必須パラメータ + スニペット + ゲーティングフラグ)。
• N 回の個別のルックアップよりも、1 回の batch --compact を優先してください: 1 つのプロセスがオントロジーを一度解析します。--calls '<json>'、--calls-file <path> (ファイルはシェルのクォートを回避します)、または stdin 経由で JSON をパイプします。--compact は search、node-info、node-schema に適用されます。examples-search と examples-info は常に完全なワークフローデータを返します。例: npx --yes n8nac skills batch --compact --calls '[{"cmd":"search","query":"gmail"},{"cmd":"node-info","name":"gmailTool"}]'。
• 複数のノードを一度に扱う場合、node-info と node-schema は複数の名前を直接受け取ることもできます: npx --yes n8nac skills node-info <node1> <node2> ... --compact。
• ユーザーが一般的な自動化パターンを求めている場合は、examples search から始めてください。
• コミュニティの例は、何かの配線方法がわからない場合、ワークフローが異常に複雑な場合、またはユーザーが明示的に求めた場合にのみ取得してください。各ダウンロードは完全な往復のコストがかかります: 定型タスクでは、ローカルの知識 (search、node-info、batch) のほうが速く、信頼できます。それ以外の場合は例をスキップしてください。
• 例はパターンを学ぶために使用し、現在のノードスキーマに対する権威として扱わないでください。
• コマンドやフラグに馴染みがない場合は、npx --yes n8nac <subcommand> --help を実行してください。フラグをでっち上げないでください。

ワークフロー作成ルール

• @n8n-as-code/transformer の TypeScript デコレーターを使用します。
• 通常のノードは source.out(0).to(target.in(0)) で接続します。
• AI サブノードは .uses() で接続し、.out().to() は使用しません。
• ai_tool と ai_document の接続は配列です：ai_tool: [this.Tool.output]。
• その他の AI 接続タイプは、ai_languageModel: this.Model.output のように単一の参照です。
• 同じタイプの入力を複数公開するノードでは、位置が入力インデックスとなる配列も使用できます：ai_languageModel: [this.Model.output, this.FallbackModel.output]（フォールバックモデル、Model Selector）。
• .uses() 接続を宣言する前に、接続に依存するブール値フラグを node-info で確認します。

すべての .workflow.ts ファイルは <workflow-map> ブロックから始まります。まずそのマップを読み、必要なプロパティ名を見つけてから、関連するクラスのセクションだけを読みます。

最小限のワークフロー構造

import { workflow, node, links } from '@n8n-as-code/transformer';

@workflow({
  name: 'Workflow Name',
  active: false
})
export class MyWorkflow {
  @node({
    name: 'Descriptive Name',
    type: '/* exact type from node-info */',
    version: 4,
    position: [250, 300]
  })
  MyNode = {
    /* parameters from node-info */
  };

  @node({
    name: 'Next Node',
    type: '/* exact type from node-info */',
    version: 3,
    position: [520, 300]
  })
  NextNode = {};

  @links()
  defineRouting() {
    this.MyNode.out(0).to(this.NextNode.in(0));
  }
}

式の構文

• 最新の式を優先します：{{ $json.fieldName }}。
• 必要に応じて、特定のノードを指定した式を使用します：{{ $('Node Name').item.json.field }}。
• 既存のワークフローを維持する理由がある場合を除き、レガシーな $node["Name"].json.field は避けます。
• Switch／If の比較では、value1 が評価対象の式で、value2 が比較するリテラル値です。

ノードの命名

• Get Customers、Send Slack Alert、Normalize Payload のような、内容がわかる名前を使用します。
• より具体的な名前を使用できる場合は、Node1、HTTP Request、Code のような名前は避けます。
• 接続の参照先は、TypeScript クラスのプロパティ名と完全に一致させる必要があります。

ワークフローファイルを効率よく読む

大きなワークフローファイルを読み込む前に、インデックスとして <workflow-map> ブロックを使用します。

// <workflow-map>
// Workflow : My Workflow
// Nodes   : 12  |  Connections: 14
//
// NODE INDEX
// Property name                    Node type (short)         Flags
// ScheduleTrigger                  scheduleTrigger
// AgentGenerateApplication         agent                      [AI] [creds]
// OpenaiChatModel                  lmChatOpenAi               [creds] [ai_languageModel]
// Memory                           memoryBufferWindow         [ai_memory]
// GithubCheckBranchRef             httpRequest                [onError->out(1)]
//
// ROUTING MAP
// ScheduleTrigger
//   -> Configuration
//     -> BuildProfileSources -> LoopOverProfileSources
//
// AI CONNECTIONS
// AgentGenerateApplication.uses({ ai_languageModel: OpenaiChatModel, ai_memory: Memory })
// </workflow-map>

ナビゲーションのルール：

1. まず <workflow-map> を読みます。
2. 必要なプロパティ名を見つけます。
3. ファイル内でそのプロパティを検索します。
4. より広いコンテキストが必要な場合を除き、関連するノードまたはルーティングのセクションだけを読みます。

AI および LangChain ノードのルール

AI サブノードは、通常のデータフローノードではありません。

@links()
defineRouting() {
  this.ChatTrigger.out(0).to(this.AiAgent.in(0));

  this.AiAgent.uses({
    ai_languageModel: this.OpenaiModel.output,
    ai_memory: this.Memory.output,
    ai_outputParser: this.OutputParser.output,
    ai_tool: [this.SearchTool.output],
  });
}

• 言語モデル、メモリ、ツール、パーサー、埋め込み、ベクトルストア、リトリーバーなどの AI サブノードには .uses() を使用します。
• AI サブノードを .out().to() で接続してはいけません。
• ai_tool と ai_document は配列にする必要があります。各要素は入力インデックス 0 に接続します。
• ほとんどのその他の AI 接続タイプは単一の参照ですが、ノードが同じタイプの入力を複数公開する場合は配列も使用できます。位置が入力インデックスになります。
• needsFallback: true（Agent、Basic LLM Chain）では、入力 1 に 2 つ目のモデルが必要です：ai_languageModel: [this.Model.output, this.FallbackModel.output]。Model Selector ノードも同様です。
• AI ポートまたは条件付きパラメーターを公開するためにブール値フラグが必要なノードもあります。.uses() を宣言する前に node-info を確認します。

よくある間違い

• ノードタイプの誤り：スキーマ出力にパッケージプレフィックスが含まれている場合は、それも含めて完全に一致するタイプを使用します。
• 古い、または存在しない typeVersion：スキーマ出力にある値を使用します。
• 無効な operation／resource 値：スキーマの正確なオプション値を使用します。
• resource と operation の不一致：各 resource で使用できる operation はそれぞれ異なります。
• 入れ子構造の推測：固定コレクションには厳密な構造があります。
• 接続名の誤り：TypeScript のプロパティ名と完全に一致させます。
• ノード、認証情報、operation、パラメーターを捏造すること。
• AI サブノードを .out().to() で接続すること。
• ai_tool: [this.Tool.output] の代わりに ai_tool: this.Tool.output を使用すること。
• Switch／If の value1 と value2 を逆にすること。
• 現在のスキーマが formFields: { values: [...] } を想定しているのに、formFieldsUi.fieldItems のような古い Wait のフォーム構造を使用すること。
• push にファイル名だけを渡すこと。
• Class A の実行時／設定上の不足を、ワークフローコードのバグとして扱うこと。

検証、テスト、提示

push --verifyを優先してください。プッシュしたワークフローを取得し、同じ処理の中で検証できます。push --verifyの直後に単独でverifyを実行すると同じ状態を再確認することになるため、--verifyを付けずにプッシュした場合を除き、省略してください。

npx --yes n8nac push <path> --verify
npx --yes n8nac test-plan <workflowId> --json

Webhook、チャット、フォームのワークフローでは、本番環境向けのテスト手順を優先してください。

npx --yes n8nac workflow activate <workflowId>
npx --yes n8nac test <workflowId> --prod

• クラス A の設定不足は、ワークフローを書き換えるのではなく、ユーザーまたは設定側で対処する必要があります。
• テスト用Webhookが有効化されていないなどの実行時状態の問題は、ワークフローコードのバグではありません。
• クラス B の接続エラーは、ワークフローファイル内で修正できます。
• 同じ診断結果で失敗が2回繰り返されたら、そこで止めてください。

ワークフロー提示のルール

npx --yes n8nac workflow presentは、ユーザーにワークフローを提示する標準的な方法です。v4環境に対応しており、ワークフロー作成の反復プロセスの一部です。

次のいずれかに該当する場合は、必ず実行してください。

• ワークフローを作成した場合。
• ワークフローを変更してプッシュした場合。
• ワークフローを実行またはテストし、ユーザーが確認する必要がある場合。
• ユーザーがワークフローの表示、オープン、提示、URLやリンクの提供を求めた場合。

npx --yes n8nac workflow present <workflowId> --json

ルール：

• n8nワークフローのURLを手動で組み立てないでください。
• 提示用URLがある場合、内部のローカルn8n URLを返さないでください。
• ユーザーに提示するURLには、workflow present --jsonが返すurlを使用してください。
• ワークフローIDがわからない場合は、まずnpx --yes n8nac listを実行し、一致するワークフローを選択してください。
• npx --yes @n8n-as-code/n8n-manager presentWorkflowResultは実行しないでください。これはレガシーのランタイムコマンドであり、ワークスペース環境を認識しません。
• workflow presentが失敗した場合は、バックエンドの診断情報を報告し、その後、フォールバックとして最適な直接n8n URLを提示してください。
• ワークフローを作成、変更、プッシュ、実行した場合、または明示的にワークフローの提示を求められた場合は、最終回答の前に実行してください。

テスト可能性のプロトコル

Webhook、チャット、フォームのワークフローでは：

1. 可能な場合は、検証付きでプッシュします。
2. test-planを実行して、トリガーの種類、エンドポイント、推奨ペイロードを確認します。
3. ワークフローを有効化します。
4. デフォルトでは--prodを指定してテストします。

npx --yes n8nac push <path-to-workflow.workflow.ts> --verify
npx --yes n8nac test-plan <workflowId> --json
npx --yes n8nac workflow activate <workflowId>
npx --yes n8nac test <workflowId> --prod

n8nエディターでテストURLを意図的に有効化した場合に限り、npx --yes n8nac test <workflowId>をそのまま使用してください。

$json.queryから値を読み取るGET/HEAD Webhookでは、次の方法を優先してください。

npx --yes n8nac test <workflowId> --query '{"key":"value"}' --prod

実行のデバッグ

Webhookが成功を返してもワークフローの動作が誤っている場合は、推測せずに実行履歴を調べてください。

npx --yes n8nac execution list --workflow-id <workflowId> --limit 5 --json
npx --yes n8nac execution get <executionId> --include-data --json

• HTTPトリガーが成功しても、n8nがリクエストを受け付けたことしか意味しません。
• ワークフロー内の後続処理で実行が失敗する場合があります。
• 実行データを使って、失敗したノードと実際のペイロード形式を特定してください。

認証情報のワークフロー

認証情報が不足してワークフローが停止している場合は、関係のないワークフローのロジックを書き換えずに、認証情報の不足を解消してください。

npx --yes n8nac workflow credential-required <workflowId> --json
npx --yes n8nac credential schema <type>
npx --yes n8nac credential list --json
npx --yes n8nac credential create --type <type> --name <name> --file cred.json --json
npx --yes n8nac workflow activate <workflowId>

• workflow credential-requiredは、認証情報が1つ以上不足していると、0以外の終了コードを返します。これをワークフローコードの失敗ではなく、対処が必要であることを示すシグナルとして扱ってください。
• credential schemaを使って、必須フィールドを確認してください。
• 必要に応じて、ユーザーにシークレット値を尋ねてください。
• 認証情報の作成には--fileを優先してください。シェル引数にシークレットを直接渡さないでください。
• APIキーや認証情報のシークレット値をユーザーに表示しないでください。
• 認証情報の作成に失敗した場合は、検証メッセージを確認し、再試行する前にペイロードを変更してください。

運用手順

ほとんどのワークフロータスクでは：

1. env status --jsonでコンテキストを解決します。
2. バックエンドの応答からworkflowsPathを読み取ります。
3. listを使って既存のワークフローを調べます。
4. 既存のワークフローを編集する前にプルします。
5. サンプルとスキーマを検索します。
6. .workflow.tsファイルを編集または作成します。
7. ローカルで検証します。
8. --verifyを付けてプッシュします。
9. HTTPトリガーのワークフローであればテストします。
10. 動作が不明な場合は、実行履歴を調べます。
11. npx --yes n8nac workflow present <workflowId> --jsonを使って、最終的なワークフローのリンクを提示します。

応答の原則

• 一般的な機能ではなく、具体的な操作とコマンドの結果を説明してください。
• ユーザーがワークフローの URL または目視確認を求めた場合は、URL を手動で作成せず、npx --yes n8nac workflow present <workflowId> --json を実行してください。
• セットアップが不足している場合は、ワークスペース環境には n8nac env ... を使用し、管理対象のローカルインスタンスにのみ n8n-manager を使用してください。
• ユーザーがリモートの n8n 環境を選択しない限り、ホストや API キーを尋ねないでください。
• 対話なしでコマンドを自分で実行できる場合は、ユーザーにセットアップコマンドの実行を指示しないでください。
• 同じ診断結果で失敗が 2 回続いたら停止し、バックエンドのエラーを明確に報告してください。