Claude CodeからCortex CodeへSnowflakeの依頼を転送するプラグイン

Snowflakeに関する依頼だけをSnowflake自身のエージェントに任せ、それ以外はClaude Codeで進める。snowflake-cortex-codeプラグインは、この振り分けを自動で行います。提供元はSnowflakeで、Claude Code公式のプラグインマーケットプレイスに載っています。

プラグインの中身は、プロンプトを監視するhookと、Cortex Code CLIを呼び出す3つのスキルです。Claude Code自身がSnowflakeへ接続するのではありません。依頼を受けたClaude Codeが、手元のcortexコマンドを実行して結果を受け取ります。

Cortex Codeとは何で、プラグインは何を足すのか

Cortex Code(Snowflake側の資料では「CoCo」とも表記されます)は、Snowflakeのデータエンジニアリング、分析、機械学習の作業向けに作られたAIエージェントです。Snowflakeのロールベースのアクセス制御やスキーマの構造を理解したうえで動く、と説明されています。

提供形態は3つあります。

• Snowsight(Web画面)内のCoCo
• macOSとWindows向けのデスクトップアプリ
• ローカルのシェルで動くCLI

プラグインが呼ぶのは3つ目のCLIです。CLIは既存の認証方法でSnowflakeアカウントに接続し、SQLの実行、ローカルのリポジトリの読み書き、gitやbashの実行ができます。

つまりプラグインの役目は、Claude Codeの会話の中からcortexを呼ぶ橋渡しです。Snowflake固有のスキル(データ品質、セマンティックビュー、コスト分析、機械学習、ガバナンスなど)はCortex Code側にあり、プラグインのcortex-routerスキルもそれを前提に書かれています。

インストールと前提条件

必要なのは、cortexコマンドがPATHにあることです。プラグインのインストールはClaude Codeで1行です。

claude plugin install snowflake-cortex-code@claude-plugins-official

更新はclaude plugin update snowflake-cortex-codeです。プラグインの管理全般はClaude Codeプラグイン完全ガイドで扱っています。

cortexが見つからないとき、プラグインはcortex-setupスキルを読み込んでインストールに進みます。手順は、snowとcortexの有無を確かめ、無ければインストーラーを実行し、snow connection listで接続設定を確認するという流れです。接続が無ければsnow connection addでアカウントURL、ユーザー名、認証方法を登録します。

費用の面では、Snowflakeの資料にCLIの課金モデルが2つ書かれています。

ウェアハウスやストレージの費用は、CoCoの利用料とは別に通常のレートで請求されます。

依頼はどう振り分けられるか

振り分けは3段階で、最初の段階は軽いキーワード判定です。

第1段階: プロンプトのキーワード判定

プラグインはUserPromptSubmitのhookで、prompt_filter.pyをプロンプトごとに実行します。Snowflake側の判定語には、snowflake、cortex、snowpark、warehouse、dynamic table、semantic view、data quality、native appなどが入っています。「show me my tables」「show databases」のような言い方にも反応する正規表現があります。

一方で、local file、git commit、fix the bug、unit test、npm、pip installといったローカル作業の語が先に見つかると、Snowflake語があっても転送されません。

ここで注意したいのは、判定語が英語である点です。READMEが自動転送の例として挙げているのも「Show me my Snowflake warehouses」のような英語の依頼です。日本語だけで書いた依頼が同じように拾われるかは、パターン定義からは読み取れません。確実に回したいときは、次の$cortex-runを使います。

hookが返すのは「cortex-routerスキルを読み込んで手順に従え」という追加指示です。実際に転送するかどうかは、その指示を受けたClaude Codeがスキルの手順に沿って進めます。

第2段階: cortex-routerの3ステップ

cortex-routerスキルは、順番を飛ばさないよう明記されています。

1. which cortexでcortexの有無を確かめる(無ければcortex-setupへ)
2. route_request.pyにプロンプトを渡し、route: cortexかroute: claudeかを受け取る
3. route: cortexのときだけ、execute_cortex.pyでCortex Codeを実行する

route: claudeが返ったら、転送せずClaude Codeが処理します。単純なSQLならCortexのスキルは要らない、という扱いです。

第3段階: ヘッドレス実行と会話の引き継ぎ

実行時、execute_cortex.pyはcortexを--output-format stream-jsonと--input-format stream-json、--permission-prompt-tool stdio付きで起動し、出力を逐次解析します。ツール呼び出しはすべてプラグイン側のポリシー判定を通る設計です。

Cortexは呼び出しごとにsession_idを返し、プラグインがそれを保存します。直前の続きの依頼(「もっと掘り下げて」「前四半期も」など)には--resume-lastを付けて同じセッションを再開し、話題が変わったら新規セッションで始めます。付けるかどうかを決めるのもスキルの指示を読んだClaude Codeです。

所要時間の目安として、スキルには30〜90秒と書かれています。2分を超えたら止まっているとみなし、$cortex-runでの直接実行を案内する決まりです。

明示的に呼ぶ$cortex-run

自動判定に頼らず確実にCortex Codeへ送るには、プロンプトの先頭に$cortex-runを付けます。

$cortex-run analyze query performance for the last 7 days

READMEは、自動転送が拾わなかったとき、Cortex Codeを使うと明示したいとき、Snowflakeの作業とそれ以外が混ざった依頼のときに便利だとしています。キーワード判定を通らないため、ローカル語が入っていても転送されます。

$cortex-runだけを入力して中身が無い場合は、何をしたいかを聞き返す仕様です。スキル名はcortex-runで、スキルの説明文には/cortex-runでも起動すると書かれています。Claude Codeでは/cortex-runの形でも呼べます。

実行権限の4段階(セキュリティエンベロープ)

Cortex Codeに何を許すかは「エンベロープ」で決まります。スキルは依頼の性質から選び、読み取りだけと明らかなとき以外はRWを既定にします。

DEPLOYは、設定ファイルの許可リスト(allowed_envelopes)の初期状態ではコメントアウトされています。有効化するには自分で外す必要があります。許可リストを空にすると何も実行できなくなります。

追加の保護として、READMEはPIIの除去、認証情報のパスのブロック、SHA256で検証するキャッシュ、監査ログを挙げています。~/.ssh/**、~/.aws/credentials、.env、*.pemのような場所を参照するプロンプトは、実行前に拒否されます。

承認モードはprompt(既定。実行前に確認)、auto(自動承認、監査ログ必須)、envelope_only(自動承認でツール予測なし、監査ログ必須)の3種です。ただしREADMEには、ライブ実行ではエンベロープの判定が使われ、承認モードのラッパーはシミュレーションに留まると書かれています。承認モードの設定値だけで挙動が決まるとは考えず、エンベロープの許可リストを主な歯止めにするのが安全です。

設定を変えるには、サンプルをコピーして編集します。

cp plugins/cortex-code/scripts/router/config.yaml.example \
  ~/.claude/skills/cortex-code/config.yaml

設定ファイルを置いたら、YAMLを読むためにPyYAMLが必要になります。ここは落とし穴です。設定ファイルが存在するのにPyYAMLが無い、YAMLが壊れている、空ファイルである、のいずれでも、転送と実行は黙って素通りせず、ファイル名付きのエラーで止まります。空にしたいときは{}と書きます。設定ファイルを置かなければ、組み込みの既定値でPyYAML無しに動きます。

競合するSnowflake MCPサーバーを検出して止まる

このプラグインで最も実務に響くのは、MCPとの関係です。prompt_filter.pyは、Snowflakeらしい名前・コマンド・URLを持つMCPサーバーが設定に見つかると、転送を止めて「無効にしてからやり直してください」と案内します。理由は、ツールの重複と認証の問題です。

検査対象は次の場所です。

• プロジェクトの.mcp.json
• ~/.claude.jsonのuserスコープ
• ~/.claude.jsonのlocalスコープ(プロジェクトごと)
• ~/.claude/settings.jsonのmcpServers

判定はサーバー名、コマンド、引数、URLのいずれかにsnowflakeを含むかどうかです。この一覧に、claude.aiのConnectorsで追加した接続は含まれていません。上で紹介した記事のSnowflakeコネクタを使っている場合に、このチェックがどう働くかは、パターン定義だけでは判断できません。コネクタと併用するときは、ツールが二重に並ばないかを自分の環境で確かめてください。

どちらの経路を使うかの目安は、次のとおりです。

動かないときの切り分け

転送されないときは、原因は大きく4つです。

1. cortexがPATHに無い: which cortexで確認し、無ければcortex-setupで導入する
2. Snowflake MCPサーバーが残っている: 上の4か所を点検し、該当エントリを外してClaude Codeを再起動する
3. プロンプトにローカル語(git pushやnpmなど)が混じっている: $cortex-runで明示する
4. 設定ファイルに不備がある: エラー文のファイル名を確認し、PyYAMLの導入かYAMLの修正をする

PyYAMLが外部管理のPythonに入れられないときは、仮想環境を作ってそこに入れ、その環境からClaude Codeを起動します。READMEは--break-system-packagesを使わないよう明記しています。

自動転送されるはずなのに止まらない、逆に意図せず転送される、という場合も、まずは判定語の一覧を見ると原因が掴めます。warehouseという一語は一般的な倉庫の話題にも当たり得るため、物流系の作業が混ざるプロジェクトでは、ローカル語で打ち消されるかを確かめておくと安心です。

使い始める前の確認

このプラグインは、Claude Codeの会話からSnowflakeのデータに手が届く経路を増やします。書き込みを伴うRWが既定で選ばれる点と、Snowflakeの認証情報がcortex側の接続設定にある点は、導入前に把握しておく価値があります。まずはRO限定で読み取りの依頼から試し、allowed_envelopesをROとRESEARCHだけにしたチームの標準設定を作る、という進め方なら、影響範囲を小さく保てます。