cortex-code

Cortex Code 統合スキル

インストール

# Install via npm skills ecosystem (works with Claude Code, Cursor, Codex, and 40+ agents)
npx skills add snowflake-labs/subagent-cortex-code --copy

# Prerequisite: Cortex Code CLI must be installed and configured
# See: https://docs.snowflake.com/en/user-guide/cortex-code
which cortex  # verify installation

このスキルを使うと、コーディングエージェントは Cortex Code の Snowflake に関する専門知識を活用し、Snowflake 関連の操作をヘッドレスモードの Cortex Code CLI にインテリジェントに振り分けられます。

アーキテクチャの概要

振り分けの原則：Snowflake の操作のみを Cortex Code に振り分けます。それ以外はすべてコーディングエージェントが処理します。

主要コンポーネント：

• セッション初期化時の動的なスキル検出
• LLM ベースのセマンティックな振り分け（キーワードマッチングではありません）
• 承認モード（prompt/auto/envelope_only）を備えたセキュリティラッパー
• コンテキストを補完する、ステートレスな Cortex 実行
• ハイブリッドメモリ管理
• コンプライアンスのための監査ログ

セキュリティ

このスキルには、Cortex の実行を保護するセキュリティラッパーが含まれており、3 つの承認モードを利用できます。

承認モード

1. prompt（デフォルト）：高いセキュリティ

   • 予測されたツールと信頼度を示す承認プロンプトがユーザーに表示されます
   • 実行前にユーザーの承認が必要です
   • 監査ログは不要です
   • 適した用途：対話型セッション、信頼できないプロンプト、本番環境

2. auto：中程度のセキュリティ

   • すべての操作が自動承認されます
   • 監査ログが必須です
   • エンベロープは引き続き適用されます
   • 適した用途：自動化されたワークフロー、信頼できる環境

3. envelope_only：中程度のセキュリティ

   • ツールの予測を行いません（より高速です）
   • 自動承認され、監査ログが記録されます
   • エンベロープのブロックリストのみを使用します
   • 適した用途：信頼できる環境、低レイテンシが必要な場合

設定：スキルのインストールディレクトリにある config.yaml、または組織ポリシーで設定します。

IMPORTANT — config.yaml は省略可能です。 このスキルにはテンプレートとして config.yaml.example のみが含まれています。config.yaml が存在しない場合、Python スクリプトは安全なデフォルト値（approval_mode: prompt、default_envelope: RO）を適用します。実行前に config.yaml を検索したり、glob や ls で探したりしないでください。ConfigManager が内部で処理します。ユーザーから設定変更を明示的に求められた場合に限り、config.yaml を読み取るか作成してください。

組み込みの保護機能

• プロンプトのサニタイズ：PII の自動削除とインジェクションの検出
• 認証情報のブロック：認証情報のパスが検出された場合、振り分けを防止します
• セキュアキャッシュ：~/.cache/cortex-skill/ にある SHA256 検証済みキャッシュ
• 監査ログ：構造化された JSONL ログ（auto/envelope_only では必須）
• 組織ポリシー：~/.snowflake/cortex/claude-skill-policy.yaml によるエンタープライズ向けの上書き

繰り返しのクエリを高速化する

セッションの状態はキャッシュされます。クエリごとに初期化手順を再実行しないでください。

現在のセッションですでに実行済みの場合、以下の手順は省略してください。

• discover_cortex.py — 出力は ~/.cache/cortex-skill/cortex-capabilities.json にキャッシュされます
• route_request.py — 明らかな Snowflake クエリ（ユーザーが「Snowflake」「Cortex」「databases」「warehouse」などと言及している場合）は、振り分けを省略して実行に進めます
• cortex connections list — セッション中にアクティブな接続は変わらないため、そのまま再利用します
• config.yaml／組織ポリシーの確認 — ConfigManager が処理します（上記の注記を参照）

セッションで最初のクエリを実行した後の、後続の Snowflake クエリに対する最小限のフロー：

1. （approval_mode: prompt の場合）ユーザーに承認を求めます
2. 補完したプロンプトとエンベロープを指定して execute_cortex.py を呼び出します
3. 結果を返します

以上です。3 つの手順だけです。再検出も、再振り分けも、設定の確認も必要ありません。

セッションの初期化

このスキルを初めて読み込むとき：

ステップ 1：Cortex の機能を検出する

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/discover_cortex.py

このスクリプトは次の処理を行います。

1. cortex skill list を実行し、利用可能なすべての Cortex スキルを列挙します
2. 各スキルの SKILL.md のフロントマターとトリガーパターンを読み取ります
3. 設定されたキャッシュディレクトリにある CacheManager を使って機能をキャッシュします
4. Cortex が処理できる内容を示す構造化データを返します

想定される出力：スキル名と、そのトリガーパターンおよび機能を対応付けた JSON。

ステップ 2：振り分けコンテキストを読み込む

検出された機能はメモリに読み込まれ、セッション全体を通じて振り分けの判断に利用されます。

ワークフロー：ユーザーリクエストへの対応

ステップ 1：LLM ベースのルーティングでリクエストを分析する

操作を行う前に、ユーザーのリクエストを分析します。

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/route_request.py --prompt "USER_PROMPT_HERE"

このスクリプトは次の処理を行います。

1. キャッシュから Cortex の機能を読み込みます
2. LLM の推論を使ってリクエストを分類します
3. 信頼度スコアとともにルーティングの判断を返します

ルーティングのロジック：

• Cortex にルーティングするのは、リクエストに次の内容が含まれる場合です。

  • Snowflake のデータベース、ウェアハウス、スキーマ、テーブル
  • Snowflake 専用の SQL クエリ
  • Cortex の AI 機能（Cortex Search、Cortex Analyst、ML 関数）
  • Snowpark、動的テーブル、ストリーム、タスク
  • Snowflake のコンテキストにおけるデータガバナンス、データ品質、セキュリティ
  • ユーザーが「Cortex」または「Snowflake」と明示的に言及している場合

• コーディングエージェントにルーティングするのは、リクエストに次の内容が含まれる場合です。

  • ローカルファイルの操作（ローカルファイルの読み込み、書き込み、編集）
  • 一般的なプログラミング（Snowflake 専用ではない Python、JavaScript など）
  • Snowflake 以外のデータベース（PostgreSQL、MySQL、MongoDB など）
  • ウェブ開発、フロントエンドの作業
  • Snowflake に関係しないインフラストラクチャ／DevOps
  • Git の操作、GitHub、バージョン管理

ステップ 2：ルーティングの判断に基づいて実行する

ルーティングが coding_agent の場合（ローカルで処理する場合）：

エージェントに組み込まれた機能を使って、リクエストを直接処理します。Cortex は関与しません。

Cortex Code にルーティングされた場合：

ステップ 3 に進みます。

ステップ 3：セキュリティエンベロープを選択し、承認を処理する

Cortex の実行前に、セキュリティラッパーが設定モードに基づいて承認を処理します。

ステップ 3a：承認モードを確認する

security_wrapper.py は内部で config.yaml から approval_mode を読み込みます。自分で設定ファイルを調べないでください。 config.yaml が存在しない場合、デフォルトは prompt モードです。

• prompt モード（デフォルト）：ユーザーの承認が必要です
• auto モード：監査ログを記録しながら自動承認します
• envelope_only モード：ツールの予測を行わず、自動承認します

ステップ 3b：承認を処理する（prompt モードの場合）

prompt モードを使用する場合：

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/security_wrapper.py \
  --prompt "ENRICHED_PROMPT" \
  --envelope "RW"

次の処理が行われます。

1. LLM を使って必要なツールを予測します
2. ユーザーに承認プロンプトを表示します。

   Cortex Code needs to execute the following tools:
   
     • snowflake_sql_execute
     • Read
     • Write
   
   Envelope: RW
   Confidence: 85%
   
   Approve execution? [yes/no]
   

3. 承認された場合は、ステップ 3c に進みます
4. 拒否された場合は、実行を中止します

ステップ 3c：セキュリティエンベロープを決定する

操作に適したセキュリティエンベロープを決定します。

• RO（読み取り専用）：クエリと読み取り操作向けです。Edit、Write、破壊的な Bash をブロックします
• RW（読み書き）：データの変更向けです。大半の操作を許可し、破壊的な Bash をブロックします
• RESEARCH：探索的な作業向けです。読み取りアクセスに加え、ウェブツールを使用できます
• DEPLOY：デプロイ操作向けです。破壊的な Bash コマンドをブロックします
• NONE：--disallowed-tools を使ったカスタムブロックリストです

ステップ 4：Cortex 用にコンテキストを拡充する

次の内容を含む、コンテキストを拡充したプロンプトを作成します。

Claude の会話コンテキスト：

• 現在の Claude セッションにおける、関連性の高い直近 2～3 件のやり取り
• すでに話し合った Snowflake 固有の詳細

最近の Cortex セッションのコンテキスト：

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/read_cortex_sessions.py --limit 3

~/.local/share/cortex/sessions/ から最新の Cortex セッションファイルを読み込み、Cortex が最近取り組んだ内容を把握します。

拡充したプロンプトの形式：

# Context from Current Session
[Recent relevant conversation history]

# Recent Cortex Work
[Summary from recent Cortex sessions]

# User Request
[Original user prompt]

Step 5: Cortex Code をヘッドレスで実行する

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/execute_cortex.py \
  --prompt "ENRICHED_PROMPT" \
  --connection "connection_name" \
  --envelope "RW" \
  --disallowed-tools "tool1" "tool2"

このスクリプトでは、次の処理を行います。

1. cortex -p "prompt" --output-format stream-json を呼び出します
2. プロンプトの送信にはプリントモードを使用し、非 TTY での解析にはストリーム JSON 出力を使用します
3. 安全性を確保するため、--disallowed-tools のブロックリストでエンベロープベースのセキュリティを適用します
4. NDJSON イベントストリームをリアルタイムで解析します
5. ツール使用イベントと実行結果を検出します

重要なポイント：このラッパーでは、意図的に -p と --input-format stream-json を組み合わせていません。Cortex は --input-format を JSON 標準入力用に予約しているため、標準入力が閉じている状態でこの組み合わせを使うと、init イベントのみを出力して、プロンプトを処理する前に終了することがあります。

セキュリティエンベロープ：

• RO（読み取り専用）：Edit、Write、破壊的な Bash コマンドをブロックします
• RW（読み書き）：rm -rf、sudo などの破壊的な操作をブロックします
• RESEARCH：読み取りアクセスとウェブツールを許可し、書き込み操作をブロックします
• DEPLOY：デプロイ操作を許可し、破壊的な Bash コマンドをブロックします
• NONE：--disallowed-tools パラメーターでカスタムブロックリストを指定します

イベントストリームの処理：

• type: assistant → Cortex の応答をユーザーに表示します
• type: tool_use → Cortex がツールを呼び出しています
• type: result → 最終結果です

Step 6: 権限リクエストを処理する

セキュリティラッパーでは、次のように処理します。

• prompt モード：実行前にユーザーが承認します（実行中のプロンプトはありません）
• auto/envelope_only モード：ブロックされていないツールは、ストリーム JSON モードで自動承認されます

セキュリティラッパーは、次の方法で権限を管理します。

1. 事前承認（prompt モード）：実行前に、予測されたツールをユーザーが承認します
2. 監査ログ（auto/envelope_only）：すべての操作をスキルのインストールディレクトリにある audit.log に記録します
3. エンベロープの適用：--disallowed-tools によるツールのブロックリストは引き続き適用されます

Step 7: 結果をユーザーに返す

現在のセッションに合わせて Cortex の出力を整形します。

• SQL クエリの結果を読みやすい形式で表示します
• 生成された成果物を表示します
• 成功／失敗の状態を報告します
• Cortex の分析から関連する抜粋を提示します

例

例 1: Snowflake クエリ

ユーザーの発言：「Snowflake で売上上位 10 社の顧客を表示してください」

ルーティング：→ Cortex Code（Snowflake SQL クエリ）

セキュリティエンベロープ：RW（SQL 実行を許可）

Cortex のアクション：

1. snowflake_sql_execute を使用して、次のクエリを実行します：SELECT customer_name, SUM(revenue) as total FROM sales GROUP BY customer_name ORDER BY total DESC LIMIT 10
2. 整形した結果を返します

結果：上位 10 社の顧客を表形式でユーザーに表示します。

例 2: ローカルファイルの操作

ユーザーの発言：「このディレクトリにある config.json ファイルを読み取ってください」

ルーティング：→ お使いのコーディングエージェント（ローカルファイルの操作）

Claude のアクション：Read ツールを直接使用し、Cortex は関与しません。

結果：ファイルの内容を表示します。

例 3: データ品質のチェック

ユーザーの発言：「SALES_DATA テーブルのデータ品質を確認してください」

ルーティング：→ Cortex Code（Snowflake のデータ品質。Cortex の data-quality スキルに一致）

セキュリティエンベロープ：RW（分析のための SQL 実行を許可）

Cortex のアクション：

1. data-quality スキルを使用してデータ品質チェックを実行します
2. スキーマ、NULL 率、重複などを分析します
3. 品質レポートを生成します

結果：推奨事項を含む包括的なデータ品質レポートです。

重要な注意事項

セキュリティラッパー

このスキルでは、次の機能を提供するセキュリティラッパーを使用します。

• 承認モード：prompt（デフォルト）、auto、envelope_only
• プロンプトのサニタイズ：PII の自動削除とインジェクションの検出
• 認証情報のブロック：認証情報のパスが検出された場合、ルーティングを防止します
• 監査ログ：auto/envelope_only モードでは必須です
• ツールの予測：LLM が承認プロンプトに必要なツールを予測します

設定：スキルのインストールディレクトリにある config.yaml、または組織のポリシーから設定します

自動承認によるヘッドレス実行

auto モードまたは envelope_only モードを使用する場合：

• すべてのツール呼び出しは、対話型プロンプトなしで自動的に承認されます
• 組み込みツール（Read、Write、Edit、Bash、Grep、Glob）と、組み込みではないツール（snowflake_sql_execute、data_diff、MCP ツール）の両方で動作します
• プロンプトの送信には print モードを使用し、TTY ではない出力の解析には stream JSON モードを使用します
• セキュリティは対話型承認ではなく --disallowed-tools ブロックリストで制御します。これらのモードは信頼できる環境でのみ使用してください

ステートレス実行

Cortex の各実行はステートレスです。コンテキストは、拡充したプロンプトで明示的に提供する必要があります。

メモリの境界

• コーディングエージェントが保持する内容：会話履歴全体、ユーザーの設定、プロジェクトのコンテキスト
• Cortex Code が受け取る内容：現在の操作に必要なタスク固有のコンテキストのみ
• Cortex セッションの読み取り目的：過去のコンテキストを補足する場合のみ

セキュリティエンベロープの戦略

操作のリスクに応じてエンベロープを選択します：

1. RO または RW から開始する：ほとんどの操作はこの範囲で対応できます
2. RESEARCH を使用する：探索的な作業でウェブアクセスが必要な場合に使用します
3. DEPLOY を使用する：より広範な非破壊的ツールアクセスが必要なデプロイ形式の操作に限って使用します
4. カスタムブロックリストと NONE を使用する：きめ細かな制御が必要な場合に使用します

パフォーマンスに関する考慮事項

• Cortex のスキル検出はセッションごとに一度実行されます（キャッシュされます）
• Cortex の実行ごとに約 2～5 秒の遅延が発生します
• 不要な Cortex 呼び出しを最小限に抑えるため、ルーティングを適切に使用してください

トラブルシューティング

エラー：「Cortex CLI が見つかりません」

原因：Cortex Code がインストールされていないか、PATH に含まれていません

解決方法：

which cortex
# If not found, check installation: ~/.snowflake/cortex/

エラー：承認プロンプトが表示されない（または予期せず表示される）

原因：承認モードの設定ミス、または組織ポリシーによる上書き

解決方法：

# Check approval mode (path varies by agent: ~/.claude/, ~/.cursor/, ~/.codex/, etc.)
cat "$(dirname $(which cortex))/../skills/cortex-code/config.yaml" | grep approval_mode 2>/dev/null \
  || cat ~/skills/cortex-code/config.yaml | grep approval_mode

# Check organization policy (overrides user config)
cat ~/.snowflake/cortex/claude-skill-policy.yaml 2>/dev/null

# Expected:
#   prompt = shows approval prompts (default)
#   auto = auto-approves all operations
#   envelope_only = auto-approves, no tool prediction

エラー：「プロンプトに認証情報ファイルのパスが含まれています」

原因：認証情報の許可リストに一致するパス（例：~/.ssh/、.env）がプロンプトに含まれています

解決方法：

1. プロンプトから認証情報への参照を削除します
2. 誤検知の場合は、config.yaml の許可リストをカスタマイズします

エラー：プロンプトから個人情報が削除される

症状：メールアドレスや電話番号がプレースホルダーに置き換えられます

原因：自動サニタイズがデフォルトで有効になっています

解決方法：必要に応じて無効にします（推奨しません）：

security:
  sanitize_conversation_history: false

エラー：auto モードにもかかわらず「アクセスが拒否されました」

原因：現在のエンベロープの --disallowed-tools ブロックリストにツールが含まれています

解決方法：

1. 使用中のエンベロープ（RO/RW/RESEARCH/DEPLOY）を確認します
2. 操作が安全であれば、制限の緩いエンベロープに切り替えます
3. auto モードまたは envelope_only モードでは NONE を避け、必要に応じて名前付きエンベロープと明示的なカスタムブロックリストを使用します

エラー：監査ログが作成されない

症状：auto モードまたは envelope_only モードにもかかわらず、audit.log がありません

解決方法：

# Create the skill's install directory if missing and set permissions
# Path is agent-specific: ~/.claude/skills/cortex-code/, ~/.cursor/skills/cortex-code/, etc.
chmod 700 "$(cd "$(dirname "$0")/.." && pwd)"

# Verify audit_log_path in config.yaml within the skill directory
grep audit_log_path config.yaml

エラー：ツールが引き続き承認を要求する

原因：承認モード、エンベロープのブロックリスト、または stream JSON の呼び出し設定に誤りがあります

解決方法：ラッパーが cortex -p "..." --output-format stream-json を --input-format なしで呼び出していること、および設定されたエンベロープが対象のツールをブロックしていないことを確認します。

問題：ルーティングにより、Snowflake のクエリがコーディングエージェントに送られる

原因：ルーティングロジックが Snowflake のキーワードを検出できませんでした

解決方法：

1. ユーザーが「Snowflake」と明示的に言及したか確認します
2. scripts/route_request.py のルーティングスクリプトのロジックを確認します
3. ルーティングコンテキストにトリガーパターンを追加します

問題：Cortex が「接続が拒否されました」を返す

原因：Cortex で Snowflake 接続が設定されていません

解決方法：

cortex connections list
# Verify connection is active
# Check ~/.snowflake/cortex/settings.json for cortexAgentConnectionName

問題：コンテキストの拡充が大きすぎる

原因：会話履歴を含めすぎています

解決方法：関連する直近のやり取りを 2～3 件に制限し、それ以前のコンテキストは要約します。

上級編：カスタムルーティングルール

デフォルトのロジックを超えてルーティングをカスタマイズするには、scripts/route_request.py を編集します：

# Add custom patterns
FORCE_CORTEX_PATTERNS = [
    "snowflake",
    "cortex",
    "warehouse",
    "snowpark"
]

FORCE_CLAUDE_PATTERNS = [
    "local file",
    "git commit",
    "python script" # unless Snowpark
]

参考資料

以下をご覧ください：references/ ディレクトリには次の資料があります。

• cortex-cli-reference.md - Cortex CLI の完全なドキュメント
• routing-examples.md - ルーティング判断の追加例
• session-file-format.md - Cortex セッションファイルの構造
• troubleshooting-guide.md - 詳細なトラブルシューティング