explain

/claude-db:explain

スキーマ（または単一の検出結果）を平易な言葉で説明し、パラダイムに応じた図を示します。読み取り専用です。説明のみを行い、編集や移行は行いません。

$ARGUMENTS = <path|table|finding-id> [flags]。対象には、スキーマ／ORM／マイグレーションのパス、単一のテーブル／コレクション名、または前回の監査で得られた検出結果の id を指定できます。

実行内容

1. パラダイム／エンジンを検出し（scripts/detect-stack.mjs）、モデルを解析します（scripts/parse-schema.mjs／parse-orm-python.py）。
2. まず平易な言葉で説明します。冒頭では専門用語を使わず、各エンティティが何を保持するか、誰が何を所有するか、要素同士がどうつながるかを、ユーザー自身の言葉で説明します（「ユーザーには複数の注文があり、各注文は必ず1人のユーザーに属します」など）。
3. パラダイムに応じた図（Mermaid）を、node scripts/gen-diagram.mjs --file <schema> [--paradigm relational|document|key-value|wide-column|graph] で生成します。パラダイムに応じた図の種類は次のとおりです。リレーショナルは ERD、ドキュメントはアクセスパターンマップ、DynamoDB／KV はキーと GSI の概要、グラフはノードとエッジです。
   • リレーショナル → テーブル、PK／FK、カーディナリティを含む erDiagram。
   • ドキュメント → ネストされている要素と参照されている要素を示す、埋め込み／参照ツリー。
   • キー値 → アクセスパターン／キー設計の概要（パーティションキー＋ソートキー）。
   • ワイドカラム → クエリごとのテーブル／パーティションキーの構成。
   • ベクトル → コレクション＋メトリック／次元＋メタデータのフィルターフィールド。
   • 時系列 → ハイパーテーブル／測定値＋タグ＋保持期間。
   • グラフ → 関係の種類を示すノードとエッジの概要。
4. 平易な説明の下に、展開可能な技術情報を提示します。正確なカラム型、インデックス定義、制約名、削除時の動作など、正確な DDL を知りたい読者向けの情報です。
5. 対象が検出結果の id の場合、検証内容、影響するスコア／軸（設計 | パフォーマンス | 両方）、重要である理由、再現方法（verification.reproduce）を説明します。

クエリ／EXPLAIN プランモード

db-query-patterns (M13) の推論を再利用する、次の2つの入力に対応します。

• --query "<SQL>" — 生の SQL 文を受け取り、遅くなる理由と改善方法を平易な言葉で説明します。M13 のパターン（SELECT *、構造的な N+1、深いページングを伴う OFFSET、SARG 不可能な述語）を検出し、インデックスを利用できるようにする具体的なインデックス、キーセット方式への書き換え、または述語の変更を提案します。これはクエリテキストに基づく静的な推論であり、稼働中の DB は必要ありません。
• EXPLAIN プランを貼り付ける — 貼り付けられた EXPLAIN／EXPLAIN ANALYZE プランを受け取り、プランノード（シーケンシャルスキャン、ソート／ハッシュのスピル、行数の推定値と実測値、ネストループの急増）を読み取り、どのステップがボトルネックか、どのインデックス／書き換えで解消できるかを、M13 の推論に基づいて説明します。
• ユーザーがプランを貼り付けるのではなく、実行中のプラン生成（データベースに対して EXPLAIN を実行）を希望する場合は、リクエストを needs_api / Tier-2 として扱います。プランの数値を捏造せず、クエリテキストから静的に説明するか、プランを貼り付けるようユーザーに依頼します。

正確性

• モデルに実際に存在する内容だけを説明します。カラム、関係、行数、レイテンシを捏造してはいけません。関係が暗黙的で強制されていない場合（例：制約のない論理 FK）は、そのことを明示します。
• ユーザーの言語（EN／ES）で回答します。--lang が指定されている場合は、そちらを優先します。