InsForge デバッグ は何をしますか？
InsForge プロジェクトの問題を、バックエンドの可観測性プリミティブ（ログ、メトリクス、DB ヘルス、アドバイザー、ポリシー、メタデータ、エラーオブジェクト、デプロイ状態、AI アシスト）を組み合わせて診断します。このスキルは以下の機能を提供します：
- 各デバッグプリミティブのリファレンス（各可観測性サーフェスごとに
references/配下にあります） - 既知のリアクティブ症状とプロアクティブ監査に対応するプリミティブシーケンスを示す症状レシピ（以下）
常に npx -y @insforge/cli を使用してください。CLI をグローバルにインストールしないでください。
最速のパス: AI アシストによるトリアージ
ユーザーが具体的な説明（エラーメッセージ、失敗した URL、HTTP ステータス）を提供した場合、それを InsForge デバッグエージェントに渡します。他のプリミティブとは異なり、これは観測結果だけでなく提案も返します。提案に従う前に、その診断結果が引用しているプリミティブと照合してください。
npx -y @insforge/cli diagnose --ai "<問題の説明>"
これを最初に使用すべき場合とスキップすべき場合、および出力を検証する方法については、references/ai-assisted.md を参照してください。
デバッグプリミティブ
各プリミティブは、独立してクエリ可能な可観測性サーフェスであり、それぞれ異なる基礎データソースによって支えられています。実際の診断はプリミティブの組み合わせで行われます。
すべてのコマンドは npx -y @insforge/cli ... で実行します。各プリミティブの横に示されている (command) が実際の CLI コマンドです。プリミティブ名は概念ラベルであり、CLI サブコマンド名ではありません（例：「DB ヘルス」は diagnose db であり、diagnose db-health ではありません。「ポリシー」は db policies であり、diagnose policies ではありません）。
| プリミティブ (コマンド) | 表示される内容 | リファレンス |
|---|---|---|
ログ (logs <source>; diagnose logs で複数ソース集約) | 5 つのバックエンドソース（insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs）からのイベントの時系列 | references/logs.md |
メトリクス (diagnose metrics) | EC2 インスタンスの時系列データ（CPU / メモリ / ディスク / ネットワーク）を 1h / 6h / 24h / 7d の範囲で表示 | references/metrics.md |
DB ヘルス (diagnose db) | 7 つの名前付きチェック（connections / slow-queries / bloat / size / index-usage / locks / cache-hit）による現在の Postgres 状態 | references/db-health.md |
アドバイザー (diagnose advisor --json) | 3 つのカテゴリ（security / performance / health）にわたる静的スキャン結果（ruleId / affectedObject / recommendation を含む） | references/advisor.md |
ポリシー (db policies) | pg_policies からのアクティブな RLS ルール（コマンドとロールごとの USING / WITH CHECK）— すべてのポリシーをダンプとして表示 | references/policies.md |
メタデータ (metadata --json) | 宣言型バックエンド状態のダンプ（認証設定 / テーブル / バケット / 関数 / AI モデル / Realtime チャネル） | references/metadata.md |
| エラーオブジェクト（コマンドなし — SDK / HTTP 応答を読む） | SDK エラーエンベロープ + HTTP ステータス — クライアントから見えるエラーを適切なログソースにルーティングするためのテーブル | references/error-objects.md |
デプロイ状態 (deployments list + deployments status <id> --json + logs function-deploy.logs) | フロントエンド（Vercel）のデプロイ履歴 + デプロイごとのメタデータ、およびエッジ関数のデプロイログ | references/deploy-state.md |
AI アシスト (diagnose --ai "<description>") | 他のプリミティブを組み合わせて診断結果と提案を返す LLM エージェント | references/ai-assisted.md |
症状レシピ
各レシピはプリミティブ呼び出しのシーケンスであり、各ステップには「X を探す」という 1 行の手がかりが含まれます。コマンド構文、フラグ、詳細な解釈については、上記のプリミティブごとのリファレンスを参照してください。
レシピ: SDK が { data: null, error: { code, message } } を返した場合
- error-objects — code/message/details を読み取ります。code が
PGRST*で始まる場合、リファレンスのテーブルを使ってプレフィックスでルーティングします。 - logs（error-objects のルーティングに従って適切なソース）— エラーのタイムスタンプを見つけ、バックエンド側の完全なコンテキストを取得します。
- db-health（
connections、locks、slow-queries）— エラーが DB の問題（PostgREST タイムアウト、ロック競合）を示唆する場合のみ。
レシピ: 特定のリクエストに対する HTTP 4xx/5xx 応答
- error-objects — HTTP ステータスルーティングテーブルを使用してログソースを選択します（ステータスごとに異なるパスがあります。429 は特殊です）。
- logs（そのステータスに適したソース）— 失敗したリクエスト行とエラーを見つけます。
- metrics — 複数のエンドポイントにわたる 5xx パターンでのみ、システム全体の負荷の問題を確認するために使用します。
レシピ: RLS アクセス問題（書き込み時の 403、または読み取り時の空の結果）
同じバグ、2 つの現れ方。書き込み（INSERT / UPDATE / DELETE）は 403 で大きなエラーとして失敗します。読み取り（SELECT）は空の配列で静かに失敗します — PostgREST は拒否された行をフィルタリングして取り除き、403 を返さないため、リクエストは成功したように見えますが、結果は 0 行です。診断パスは同じですが、ステップ 1 は 403 バリアントにのみ適用されます。
- logs（
postgREST.logs）— 403 バリアントのみ: テーブルとロールのコンテキストを含むポリシー違反イベントを見つけます。空の結果バリアント: スキップ — 静かにフィルタリングされた行に対してはエラーはログに記録されません。 - policies — そのテーブルのポリシーを一覧表示します。USING / WITH CHECK を実際のリクエストと使用された JWT クレームに照らし合わせて検証します。
- metadata — 認証設定を確認します（
auth.uid()/requesting_user_id()にどのクレームが供給されるか。Clerk/Auth0 のようなサードパーティ認証の場合、プロバイダーが JWT 発行者として登録されているか）。 - db query（
db query "<sql>"）— 空の結果バリアントのみ: 表示されるべき行が実際に存在することを、ユーザーとしてではなくサービスロールとしてクエリして確認します:npx -y @insforge/cli db query "SELECT id, user_id FROM <table>"。これにより、「RLS がすべてをフィルタリングした」のか、「一致するデータが存在しない」のかを区別します。
レシピ: ログイン失敗 / OAuth コールバックエラー / トークン期限切れ
- logs（
insforge.logs）— タイムスタンプとプロバイダーコンテキストを含む認証エラーを見つけます。 - metadata — プロバイダーが有効になっていること、リダイレクト URL がコールバック URL（プロトコル + ホスト + パス）と正確に一致していることを確認します。
レシピ: エッジ関数のランタイムエラー / タイムアウト
- logs（
function.logs）— エラースタックと実行コンテキストを取得します。 - metadata — 関数が存在し、
status: "active"であることを確認します。 - （必要に応じて）
npx -y @insforge/cli functions code <slug>— ソースを調べて明らかな問題を確認します。
レシピ: functions deploy が失敗した場合
- deploy-state（
function-deploy.logs）— ビルド/プッシュエラーを見つけます。 - metadata — 関数がアクティブなリストに結局含まれているかどうかを確認します（部分デプロイの検出）。
レシピ: deployments deploy が失敗した場合（Vercel）
- deploy-state（
deployments list+status <id> --json）—status、metadata.webhookEventType、およびenvVarKeysを読み取ります。 - ローカルで
npm run build— 同じエラーをローカルで再現して、迅速なイテレーションを行います。
レシピ: 単一の遅いクエリ / 1 つのエンドポイントが遅い
- logs（
postgres.logs）— クエリテキストとタイムスタンプを見つけます。 - db-health（
slow-queries、index-usage）—slow-queriesはクエリがまだ実行中の場合のみ捕捉します（5 秒以上のスナップショット）。index-usageで不足しているインデックスがないか確認します。すでに終了している場合？ advisor（--category performance --json）にpg_stat_statementsのテキストと平均時間があります。ステップ 1 にはタイムスタンプがあります。 - policies — RLS で保護されたテーブルの場合、ポリシーが隠れた結合を追加していないか確認します。
レシピ: 「メモリが約 80% ですが、特に遅くはありません」
- まず、それは期待される動作であると伝えます。 専用の Postgres インスタンスはアイドル状態の RAM を共有バッファとページキャッシュに変換します。トラフィックが少ない状態でメモリが高いまま安定しているのは、正常な状態であり、メモリリークではありません（references/metrics.md、「メモリ：高いのは正常」を参照）。
- metrics（
--range 24h）— 上昇傾向がある場合、または OOM による強制終了/再起動がある場合のみ、答えが変わります。OOM の証拠はpostgres.logsにクラッシュリカバリ後の形で残っています（