insforge-backend-advisor

InsForge バックエンドアドバイザー

InsForge プロジェクトのバックエンドの健全性を先回りして監査します。このスキルは diagnose advisor スキャンを実行し、セキュリティの設定ミス、パフォーマンスの低下、システムの健全性に関する問題を検出します。その後、各問題カテゴリに対して、変更を加える前に検出結果を検証・再現するための実践的なコマンドを提示します。

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

このスキルと insforge-debug の使い分け

このスキルを使うケース...	insforge-debug を使うケース...
定期的な健全性チェック／リリース前の監査を行う	特定のリクエストがエラーや予期しないステータスを返した
セキュリティ態勢（RLS、シークレット、認証設定）を確認する	ユーザーがログインできない／トークンの有効期限が切れた／OAuth コールバックに失敗する
遅いクエリ、肥大化、インデックス不足を先回りして調べる	特定のエンドポイントが 今まさに 遅く、ユーザーが URL を提示している
バックエンド全体の性能低下：CPU／メモリ使用率が高い、すべての応答が遅い、コネクションプールが枯渇している、ロックが競合している	単一のリクエストが失敗した、またはタイムアウトした
具体的な症状なしに「バックエンドのどこに問題がありますか？」と尋ねられた	具体的な症状とともに「このリクエストが失敗した理由は？」と尋ねられた

どちらを使うか迷った場合は、具体的なエラー／URL／ステータスコードがあるなら insforge-debug を使います。一般的に「問題を探してほしい」という依頼なら、このスキルを使います。

まずスキャンを実行する

このスキルのすべてのワークフローは、最新のアドバイザースキャンから始まります。このスキャンは、セキュリティ、パフォーマンス、健全性の各カテゴリにわたるチェックを集約し、各問題の重大度に基づいて優先順位を付けます。

npx @insforge/cli diagnose advisor

デフォルトでは、最新のスキャン概要と最大 50 件の問題が表示されます。--severity と --category で絞り込めます。

# Only critical issues (start here in any audit)
npx @insforge/cli diagnose advisor --severity critical

# Security category only
npx @insforge/cli diagnose advisor --category security

# JSON for full issue payload (ruleId, affectedObject, recommendation, isResolved)
npx @insforge/cli diagnose advisor --json

各問題オブジェクトには、ruleId、severity、category、title、description、affectedObject、recommendation が含まれます。詳細を調べる前に affectedObject を確認し、問題の対象となるテーブル／ポリシー／シークレット／リソースを把握してください。

注: diagnose advisor の使用には InsForge Platform へのログインが必要です。--api-key を使ってリンクしたプロジェクトでは利用できません。

優先度の簡易判定

スキャン実行後は問題の category を、事前情報なしにユーザーが来た場合はユーザーの症状を、詳細セクションに照らし合わせてください。

情報源	該当する内容	詳細セクション
Advisor の category=security	RLS、公開されている設定、シークレット	セキュリティ監査
Advisor の category=performance	遅いクエリ、インデックス、肥大化	パフォーマンス監査
Advisor の category=health	接続、ロック、システムメトリクス	システム健全性監査
症状：「すべてが遅い」、CPU／メモリ使用率が高い、すべての応答が遅い	バックエンド全体の性能低下	システム健全性監査
症状：「このクエリが遅い」（単一の失敗した URL はない）	クエリ単位のパフォーマンス	パフォーマンス監査

複数カテゴリにまたがるレポートや「最初に何を修正すべきか」という質問には、すべてのカテゴリの重大な問題から優先的に対処し、その後に警告へ進んでください。

---

セキュリティ監査

該当するケース: category=security のアドバイザー問題、または「RLS を確認してほしい」「認証設定を監査してほしい」「シークレットが公開されていないか」といった依頼です。

手順

1. 最新のスキャンからセキュリティ上の問題を一覧表示します。

npx @insforge/cli diagnose advisor --category security

2. RLS 関連の問題（affectedObject がテーブル名またはポリシーの場合）について、そのテーブルの現在のポリシーを確認します。

npx @insforge/cli db policies

3. プロジェクトの認証設定が想定どおりであることを確認します（有効なプロバイダー、リダイレクト URL、JWT 設定）。

npx @insforge/cli metadata --json

4. シークレット関連の問題について、現在のシークレットを一覧表示します（名前のみ。明示的に要求されない限り、値は表示されません）。また、--reserved のマークが付いたものや、--expires の期限が切れたものがないか確認します。

npx @insforge/cli secrets list --all

5. advisor の ruleId が情報の露出を示している場合（例：機密データを含むパブリックバケット、ユーザーデータテーブルで RLS が無効）、変更を推奨する前に、対象オブジェクトの実際の状態を確認してください。advisor の推奨を盲目的に適用しないでください。

収集する情報：有効な RLS ポリシー、認証プロバイダーとリダイレクト URL、シークレットの一覧、advisor が指摘したすべての affectedObject の実際の状態。

---

パフォーマンス監査

トリガー：category=performance の advisor の問題、または「遅いクエリを探して」「不足しているインデックスはある？」「DB が肥大化している？」などのリクエスト。

手順

1. パフォーマンスの問題を一覧表示します。

npx @insforge/cli diagnose advisor --category performance

2. データベースのパフォーマンス全体を確認します。遅いクエリ、インデックス効率、肥大化、キャッシュヒット率、サイズを調べます。

npx @insforge/cli diagnose db --check slow-queries,index-usage,bloat,cache-hit,size

3. affectedObject で指摘された特定のテーブルについて、SQL で直接確認します。

npx @insforge/cli db query "SELECT pg_size_pretty(pg_total_relation_size('<table>')) AS total_size, pg_size_pretty(pg_indexes_size('<table>')) AS indexes_size"

4. EC2 インスタンスのメトリクスと照合します。「遅いクエリ」という報告は、クエリ自体ではなく CPU やメモリの負荷が原因の場合もあります。

npx @insforge/cli diagnose metrics --range 6h

5. インデックス関連の問題の場合、postgres のログで実際のインデックス使用状況を調べ、不足しているインデックスが実行時に利用されているか確認します。

npx @insforge/cli logs postgres.logs --limit 50

収集する情報：遅いクエリの実行計画、インデックス使用状況、テーブルの肥大化、キャッシュヒット率、現在の EC2 リソース使用率、postgres のクエリパターン。

---

システムヘルス監査

トリガー：category=health の advisor の問題、または「バックエンドは正常？」「ロックはある？」「コネクションプールは大丈夫？」「EC2 の状態は問題ない？」などのリクエスト。

手順

1. ヘルス関連の問題を一覧表示します。

npx @insforge/cli diagnose advisor --category health

2. データベースのヘルス状態を一通り確認します。接続、ロック、その他の現在の状態を調べます。

npx @insforge/cli diagnose db --check connections,locks

3. 十分な期間の EC2 インスタンスメトリクスを取得します（デフォルトは 1h。傾向を調べる場合は期間を広げます）。

npx @insforge/cli diagnose metrics --range 24h

4. エラーログを集計し、ヘルス上の問題が最近のエラー急増と相関しているか確認します。

npx @insforge/cli diagnose logs

5. コネクションプールの枯渇またはロック競合が指摘された場合、スキャン時刻前後の postgres のログを詳しく調べます。

npx @insforge/cli logs postgres.logs --limit 100

収集する情報：コネクションプールの状態、ロック競合、傾向を含む CPU／メモリ／ディスク／ネットワークのメトリクス、エラーログの概要、postgres レベルのアクティビティ。

---

反復ワークフロー

advisor の問題は解決されるまでスキャン間で継続します（問題オブジェクトには isResolved が含まれます）。推奨される監査ループは次のとおりです。

1. スキャン — diagnose advisor --severity critical を実行して、対応対象を取得します。
2. 詳細調査 — 各問題について、上記の該当する詳細調査セクションを使い、現在の状態が advisor の報告と一致するか確認します。
3. 判断 — 問題が実際に存在することを確認してから、修正に進みます。advisor はルール違反を検出しますが、それがビジネス上重要かどうかは個別に判断する必要があります。
4. 修正 — insforge-cli スキル（npx @insforge/cli ... コマンド）を使って変更（RLS の編集、インデックスの追加、クエリの書き換えなど）を適用します。
5. 再スキャン — diagnose advisor を再実行します。修正した問題は、次回のスケジュール済みスキャンで isResolved: true として表示されるか、対応対象から除外されます。

修正前と同じスキャン結果に依存しないでください。変更を適用した後は、必ず再スキャンしてください。

---

コマンドクイックリファレンス

Advisor スキャン

npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit <n>] [--json]

デフォルトの --limit は 50 です。--json は、スキャンの概要と完全な問題オブジェクト（ruleId、recommendation、isResolved を含む）を返します。

バックエンドの詳細調査

# Database health checks
npx @insforge/cli diagnose db [--check connections,slow-queries,bloat,size,index-usage,locks,cache-hit]

# EC2 instance metrics
npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]

# Aggregate error logs from all sources
npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]

# Postgres-level logs
npx @insforge/cli logs postgres.logs --limit 50

補助コマンド

# Project metadata (auth config, tables, buckets, functions, RLS policies)
npx @insforge/cli metadata --json

# Live RLS policies
npx @insforge/cli db policies

# Ad-hoc SQL against the project
npx @insforge/cli db query "<sql>"

# Secrets inventory
npx @insforge/cli secrets list --all

具体的なエラー、ステータスコード、または失敗する URL に対するリアクティブなデバッグでは、insforge-debug に切り替えてください。