insforge-debug

InsForge のデバッグ

バックエンドのオブザーバビリティ機能（ログ、メトリクス、db-health、advisor、ポリシー、メタデータ、エラーオブジェクト、デプロイ状態、AI アシスト）を組み合わせて、InsForge プロジェクトの問題を診断します。このスキルでは、次の内容を提供します。

1. 各デバッグプリミティブのリファレンス（それぞれ1つのオブザーバビリティ対象を扱います。references/ 配下）
2. 既知の事後対応が必要な症状と事前監査について、使用するプリミティブの順序を示す症状別レシピ（以下）

必ず npx -y @insforge/cli を使用してください。CLI をグローバルにインストールしないでください。

最短の方法：AI を活用したトリアージ

ユーザーが具体的な説明（エラーメッセージ、失敗する URL、HTTP ステータス）を提示した場合は、InsForge デバッグエージェントに渡します。他のプリミティブと異なり、こちらは観測結果だけでなく提案も返します。提案に基づいて対応する前に、参照先として示されたプリミティブを使って診断内容を検証してください。

npx -y @insforge/cli diagnose --ai "<issue description>"

最初にこれを使うべき場合と使わずに済ませる場合、および出力の検証方法については、references/ai-assisted.md を参照してください。

デバッグプリミティブ

各プリミティブは、それぞれ異なるデータソースに基づく、個別にクエリ可能なオブザーバビリティ対象です。実際の診断では、複数のプリミティブを組み合わせます。

すべてのコマンドは npx -y @insforge/cli ... で実行します。各プリミティブの横に示す (command) が実際の CLI コマンドです。プリミティブ名は概念を示すラベルであり、CLI サブコマンド名ではありません（例：「DB health」は diagnose db であり、diagnose db-health ではありません。「Policies」は 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 health（diagnose db）	7つの名前付きチェック（connections / slow-queries / bloat / size / index-usage / locks / cache-hit）を通じた現在の Postgres の状態	references/db-health.md
Advisor（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 モデル / リアルタイムチャンネル）	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

症状別レシピ

各レシピでは、プリミティブを呼び出す順序と、各手順で「何を確認するか」を1行で示します。コマンドの構文、フラグ、詳しい解釈については、上記の各プリミティブのリファレンスを参照してください。

レシピ：SDK が { data: null, error: { code, message } } を返す

1. error-objects — code/message/details を確認します。code が PGRST* で始まる場合は、リファレンスの表を使ってプレフィックスごとに振り分けます。
2. logs（error-objects の振り分けに応じたソース）— エラーのタイムスタンプを見つけ、バックエンド側のコンテキスト全体を取得します。
3. db-health（connections、locks、slow-queries）— エラーが DB の問題を示唆する場合（PostgREST のタイムアウト、ロック競合）に限ります。

レシピ：特定のリクエストで HTTP 4xx/5xx レスポンスが返る

1. error-objects — HTTP ステータスの振り分け表を使ってログソースを選びます（ステータスごとに異なるパスがあり、429 は例外です）。
2. logs（そのステータスに対応するソース）— 失敗したリクエストの行とエラーを見つけます。
3. metrics — 複数のエンドポイントにまたがる 5xx のパターンに限り、システム全体の負荷の問題を確認します。

レシピ：RLS アクセスの問題（書き込み時の 403、または読み取り時の空の結果）

同じバグでも、現れ方は 2 通りです。書き込み（INSERT / UPDATE / DELETE）は 403 で明示的に失敗します。読み取り（SELECT）は 空の配列を返し、失敗が表面化しません。PostgREST は 403 を返す代わりに拒否された行をフィルタリングするため、リクエストは成功したように見えますが、行数は 0 になります。手順 1 が 403 の場合にのみ適用される点を除き、診断手順は同じです。

1. logs（postgREST.logs）— 403 の場合のみ：テーブルとロールのコンテキストを含むポリシー違反イベントを見つけます。空の結果の場合：スキップします。サイレントにフィルタリングされた行についてはエラーが記録されません。
2. policies — そのテーブルのポリシーを一覧表示し、実際のリクエストと使用された JWT クレームに照らして USING / WITH CHECK を確認します。
3. metadata — 認証設定を確認します（auth.uid() / requesting_user_id() にどのクレームが使われるか。Clerk/Auth0 などのサードパーティー認証の場合、プロバイダーが JWT 発行者として登録されているか）。
4. db query（db query "<sql>"）— 空の結果の場合のみ：ユーザーとしてではなく、サービスロールとしてクエリを実行し、表示されるはずの行が実際に存在することを確認します。npx -y @insforge/cli db query "SELECT id, user_id FROM <table>"。「RLS によってすべてフィルタリングされた」のか、「一致するデータが存在しない」のかを区別できます。

レシピ：ログイン失敗／OAuth コールバックエラー／トークンの有効期限切れ

1. logs（insforge.logs）— タイムスタンプとプロバイダーのコンテキストを含む認証エラーを見つけます。
2. metadata — プロバイダーが有効になっていること、リダイレクト URL がコールバック URL と完全に一致すること（プロトコル＋ホスト＋パス）を確認します。

レシピ：エッジ関数のランタイムエラー／タイムアウト

1. logs（function.logs）— エラースタックと実行コンテキストを取得します。
2. metadata — 関数が存在し、status: "active" であることを確認します。
3. （必要に応じて）npx -y @insforge/cli functions code <slug> — ソースを確認し、明らかな問題がないか調べます。

レシピ：functions deploy が失敗する

1. deploy-state（function-deploy.logs）— ビルド／プッシュのエラーを見つけます。
2. metadata — 関数がアクティブな一覧に追加されているか確認します（部分デプロイの検出）。

レシピ：deployments deploy が失敗する（Vercel）

1. deploy-state（deployments list ＋ status <id> --json）— status、metadata.webhookEventType、envVarKeys を確認します。
2. ローカルで npm run build — 同じエラーをローカルで再現し、反復を早めます。

レシピ：単一のクエリ、または 1 つのエンドポイントが遅い

1. logs（postgres.logs）— クエリのテキストとタイムスタンプを見つけます。
2. db-health（slow-queries、index-usage）— slow-queries が検出するのは実行中のクエリのみです（5 秒超のスナップショット）。不足しているインデックスがないか index-usage を確認します。すでに終了している場合は、advisor（--category performance --json）に pg_stat_statements のテキストと平均時間があります。手順 1 にはタイムスタンプがあります。
3. policies — RLS による制限があるテーブルの場合、ポリシーによって隠れた結合が追加されていないか確認します。

レシピ：「メモリ使用率は約80％だが、遅くはない」

1. 想定どおりです。まずそう伝えてください。 専用の Postgres インスタンスでは、アイドル状態の RAM が共有バッファとページキャッシュに使われます。トラフィックが少ないのにメモリ使用率が高い状態が続くのは、正常な状態であり、メモリリークではありません （references/metrics.md、「メモリ：使用率が高くても正常」）。
2. metrics（--range 24h）— 傾向が上昇している場合や、OOM によるプロセスの強制終了・再起動がある場合にのみ、対応が変わります。 OOM の証拠は postgres.logs に、クラッシュリカバリ後のログとして残ります（「別のサーバープロセスのクラッシュにより接続を終了しています」／「自動リカバリを実行中です」）。
3. OOM の証拠がある場合の解決策は、余裕を持たせることです。有料プランにアップグレードし、より大きなインスタンスサイズを選択してください（ダッシュボード → Project Settings → Compute & Disk）。実際の負荷がある状況で最小サイズのインスタンスに OOM が発生するのはよくあることで、想定内です。「メモリを解放するために再起動する」ことは絶対にしないでください。

レシピ：すべての応答が遅い／CPU・メモリ使用率が高い（発生中のインシデント）

1. metrics（--range 1h）— システム全体に負荷がかかっているか（CPU／メモリ／ディスク）を確認します。
2. db-health — DB が最も一般的なボトルネックです。connections、locks、slow-queries を確認します。
3. logs（diagnose logs の集約）— 急増した時刻における、各ソースのエラーパターンを確認します。
4. advisor（--severity critical）— パフォーマンス低下の原因となりうる、以前から判明している問題を確認します。

レシピ：Realtime チャネルに接続できない／メッセージが見つからない

1. logs（insforge.logs）— WebSocket のエラーとサブスクリプションの失敗を確認します。
2. metadata — チャネルのパターンがクライアントのサブスクリプション対象と一致していること、および enabled: true であることを確認します。
3. policies — 基になるテーブルの RLS を確認します（Realtime は行の変更を配信し、RLS はサブスクライバーが参照できる行を制御します）。

レシピ：429 レート制限

1. error-objects — ステータスが 429 であることを確認します。429 のログは記録されず、Retry-After ヘッダーも返されません。 ログの検索に時間をかけないでください。
2. metrics（--range 1h）— バックエンド全体の負荷状況を確認します。
3. 解決策は常にクライアント側にあります：デバウンス、バッチ処理、指数バックオフ、リトライループの解消を行ってください。

レシピ：特定の URL でゲートウェイタイムアウト（502 / 503 / 504）が発生する

詳しく調べる前に、URL のサブシステムごとに切り分けます。

URL パターン	調査対象
/api/database/records/...	logs（postgREST.logs → postgres.logs）＋ db-health（locks、slow-queries）
/functions/<slug>	logs（function.logs）— 関数がクラッシュループしている可能性があります
/api/auth/...	logs（insforge.logs）
システム全体でスパイクが発生している間のあらゆるパス	metrics（--range 1h）

小規模インスタンスで、無関係なパス全体にわたって504 が発生する場合は、まず OOM を疑ってください。データベース、認証、関数のいずれにも断続的にゲートウェイタイムアウトが発生するのは、最小サイズのインスタンスでよく見られるメモリ不足の典型的な兆候です。カーネルが Postgres を停止し、クラッシュリカバリーの実行中に処理中のすべてのリクエストがゲートウェイでタイムアウトし、次の負荷スパイクでも同じことが繰り返されます。

最短の手順：npx -y @insforge/cli diagnose incident（Platform へのログインが必要です）。レポートは Prometheus のスクレイプ履歴、プラットフォームの記録、外部からのデータベースプローブなど、すべてクラウド側で生成されるため、インスタンスが停止中または応答不能の場合でも機能します。まさに diagnose logs が応答しなくなる状況で利用できます。証拠と推奨アクションを添えて、判定結果（oom_likely、platform_operation_in_progress、paused_or_suspended、metrics_stopped、down_unknown、no_incident_detected）を返します。oom_likely は、以下の再起動とメモリの相関チェックがプラットフォーム側ですでに通過したことを意味します。

コマンドを利用できない場合（古い CLI／バックエンド、または --api-key リンクモードの場合）は、logs（postgres.logs）でクラッシュリカバリー後の記録を手動で確認します。「別のサーバープロセスのクラッシュにより接続を終了しています」や「自動リカバリーを実行中」といった記録が、5xx の集中発生と時間的に相関していることを確認してください。リカバリーの証拠だけでは、Postgres が異常終了したことしかわかりません。OOM が最有力の診断となるには、タイムスタンプが一致している必要があります（references/metrics.md）。その証拠が得られた場合、必要なのはリトライループではなく、十分な余裕を持たせることです。

1. インスタンスをアップグレードします — npx -y @insforge/cli projects upgrade-instance <type> （nano → micro → small → medium → large → xl）。または、ダッシュボード → Project Settings → Compute & Disk から操作します。無料プランの場合は、先に有料プランにアップグレードしてからサイズを選択してください。サイズ変更によって料金が変わり、CLI では対話形式の確認が求められます。最初にユーザーの了承を得てから、CLI レベルの --yes を指定して対話なしで実行してください（npx -y の -y は npm のインストールフラグであり、確認を省略するものではありません）。サイズ変更は非同期です。インシデントが解決したと判断する前に、projects get をポーリングし、operation_status がクリアされたことを確認してください。
2. サイズ変更の一環としてプロジェクトが再起動されるため、応答不能な状態も解消されます。ユーザーが別途実行する再起動はなく、単独で再起動しても、次のスパイクで再び OOM になるまで数分延命できるだけです。最小サイズで実際の負荷による OOM が発生するのはよくあることで、想定内であり、バグではありません。

レシピ：リリース前／事前監査

Platform へのログインが必要です（npx -y @insforge/cli login）。プロジェクトが --api-key 経由でリンクされている場合は利用できません。その場合は、手動監査として db-health ＋ policies ＋ metadata を使用してください。

1. advisor — 全体スキャンを行い、まず --severity critical、次に警告を確認します。
2. advisor（--category security）— セキュリティの問題に重点を置き、policies（RLS のカバレッジ）と metadata（認証設定、公開バケット、シークレットの有無）を使って相互確認します。
3. advisor（--category performance）— db-health（slow-queries、index-usage、bloat）を使って相互確認します。
4. advisor（--category health）— metrics を使って、7d のリソース推移を相互確認します。
5. 修正後に advisor を再実行し、対応した各 ruleId について isResolved: true であることを確認します。

レシピ：何から始めればよいかわからない場合

1. ai-assisted（diagnose --ai "<error or URL>"）— 最初の仮説を得ます。
2. 診断で挙げられたプリミティブを再確認して検証します。提案よりも、プリミティブから得られた観測結果を優先してください。

根本原因がInsForge自体にある場合

診断の結果、プロジェクトの設定ミスではなく、InsForge側の不具合に行き着くことがあります。プラットフォームのバグやリグレッション、SDK呼び出しの不具合、実際の動作と矛盾するドキュメントやスキル、あるいは機能の不足などです。デバッグセッションは、こうした問題が確認される場面です。証拠が手元にあるうちに報告してください。

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<one-line summary>" \
  --detail "<what happened vs expected, minimal repro>" \
  --command "<the failing call>" \
  --error "<verbatim error from logs>" \
  --workaround "<what you did instead>"

ログインは不要です。メールアドレス、認証情報やキーの形式、公開IPアドレス、ホームディレクトリのユーザー名など、一般的なPIIのパターンはローカルでマスキングされます。ただし、これはパターンベースの処理なので、ユーザーデータは含めないでください。SDKの不具合には--component sdk --language <lang>を使用してください。ドキュメントが実際の動作と矛盾する場合は、--docと--expectedを指定して--component docsまたは--component skillsを使用してください。調査結果が「サポートされていない」である場合は、--type feature-requestを使用してください。その後は回避策を使ってユーザーのタスクを続けてください。報告のために作業を止めてはいけません。また、ユーザー自身のアプリのコードや設定に関する問題について、フィードバックを送信してはいけません。すべてのフラグの詳細については、insforge-cliスキルの「Feedback」セクションを参照してください。