gke-ai-troubleshooting-skill-creation-guide

トラブルシューティングスキル作成ガイド

このガイドでは、GKE ワークロードの複雑な障害を AI エージェントが診断できる、高品質なトラブルシューティングスキルの作成方法を説明します。

🏗️ スキル構造の標準

必須コンポーネント

1. SKILL.md：診断と解決の基本的なワークフロー。
2. README.md：一般公開向けの概要と「使用するタイミング」のガイド。
3. references/failure_signatures.md：実際のログやメトリクスのシグネチャ。
4. scripts/validate_queries.sh：すべてのクエリを対象とする自動構文バリデーター。
5. TEST.md：人間が手動で検証するための計画。
6. EVAL.yaml：パフォーマンス追跡用の評価スイート。

任意のコンポーネント

1. BUILD：ビルド定義。

🏷️ 命名規則

• ディレクトリ名：必ず kebab-case にします（例： gke-ai-troubleshooting-tpu-vbar-oom）。
• スキル名：ディレクトリ名と一致させる必要があります。

🔍 診断ワークフローの標準

ステップ 0：必須コンテキスト

すべてのスキルは、必要なコンテキストを取得する「ステップ 0」から開始する必要があります。

• 必須フィールド：<project_id>、<location>、<cluster_name>、 <timestamp>。
• 任意／ケースバイケースのフィールド：<node_name>、<workload_name>、 <workload_namespace>、<nodepool_name>。
• 時刻のルール：相対時刻（例：「5 分前」）は受け付けません。[T - 30m] から [T + 30m] までの時間範囲を計算します。

診断ステップ

• 明示的なクエリ：各ステップには、すぐに使える Cloud Logging （LQL） または Cloud Monitoring（PromQL） のクエリを記載する必要があります。
• プレースホルダーの構文：テンプレート解決エラーを避けるため、プレースホルダーには波括弧ではなく、<project_id> のような 山括弧 を使います。
• リスク分類：各ステップに [Low Risk]（読み取り専用）または [High Risk]（変更／破壊を伴う）のラベルを付けます。
• 自動化：エージェントが自動的に続行するのか、ユーザーの確認を待つのかを明記します。

🛠️ 正確性と検証

ハルシネーションゼロ

• ログやメトリクスの例を捏造しないでください。
• 実際のインシデントからシグネチャを取得し、必要に応じて匿名化します。
• 外挿しないでください：ソースの会話で検証されたステップとクエリのみを含めてください。

セキュリティとプライバシー

• 生データのダンプは禁止：共有スペース（バグ報告、チャット）に生ログをダンプするようエージェントに指示しないでください。
• 重要な情報のみ：調査結果を要約し、重要度の高い情報のみ報告するようエージェントに指示してください（例：「ノード Y で特定のエラーパターン X を検出」）。

自動検証

• すべてのスキルには、query_logs または gcloud logging read ... --limit=1 を使って LQL クエリを検証するスクリプト（scripts/validate_queries.sh）を含める必要があります。

📋 ベストプラクティス

• 簡潔さ：指示は簡潔にします。「何をするか」と「どう検証するか」に重点を置きます。
• 一般公開できる内容：内部メモ、個人的なブックマーク、プロジェクト固有の専門用語はすべて削除します。
• エラーシグネチャ：関連する診断ステップから references/failure_signatures.md へのリンクを明示します。