convex-explain-app

この Convex アプリを説明する

アプリを安全に変更するには、まずそれが何なのかを把握する必要があります。しかし、15 個の関数ファイルを最初から最後まで読むのは時間がかかり、間違いも起こりやすくなります。この機能は、嘘をつけない 2 つの情報源、つまりスキーマ（データモデル）と関数の公開範囲（functionSpec／エクスポートされたクエリ・ミューテーション・アクション）を読み取り、すばやく正確に全体像を作成します。意図的に説明に徹しており、実際の状態を説明し、判断は監査機能に、変更は修正機能に委ねます。また、最適化やセルフヒーリングのセッションを始める自然な第一歩であり、「構築したものを変更する」が依存する、再利用可能な「現在のアーキテクチャを再説明する」機能でもあります。

ワークフロー

1. アプリを検出します。convex/ ディレクトリ、schema.ts、デプロイが存在するかを確認します（デプロイがある場合は、公式 MCP 経由で取得する functionSpec／tables が稼働中の公開範囲を示す信頼できる情報源です。ない場合は、ソースを直接読み取ります）。deploy-guard は、デプロイの読み取りを読み取り専用として分類します。
2. データモデル：schema.ts から、すべてのテーブルとそのフィールド、そして特に重要なリレーションシップを列挙します。どの v.id("other") フィールドがどこを指すのか、どのインデックスが存在するのか（インデックスから、意図されたアクセス経路がわかります）を示します。外部キーのグラフを言葉で説明します。「タスクはプロジェクト（projectId）とユーザー（ownerId）に属し、メッセージは会話に属します」のように記述します。
3. 関数の公開範囲：エクスポートされた関数をすべて列挙し、公開（query／mutation／action。攻撃対象／API の公開範囲）と内部（internalQuery/...。クライアントからは到達できない）に分けます。それぞれについて、「何をし、何にアクセスするか」を 1 行で説明します。公開／内部の区別は、新しく関わる人が最も把握する必要があり、ソースをざっと読むだけでは最も間違いやすい点です。
4. 認証／所有権モデル：本人確認の方法（auth.config.ts のプロバイダーか、tokenIdentifier をキーとする users テーブルかなど）と、所有権の強制方法（requireOwner のようなチェックがあるか、どのフィールドが所有者なのか）を明記します。認証の基盤が存在しない場合は、そのことをはっきり伝えます。これは、これからアプリを変更する人にとって重要な前提です。（モデルを説明してください。問題点の監査はしないでください。それは convex-authz の役目です。）
5. コンポーネントと外部接続：導入済みの @convex-dev/* コンポーネント（convex.config.ts）とその機能、HTTP ルート（http.ts）、cron、アクション内の外部呼び出し（対象 API と環境変数）を列挙します。
6. フロー：代表的なエンドツーエンドの経路を 1～2 個たどります（「クライアントが createTask を呼び出す → 検証する → 呼び出し元のスコープ内で tasks に挿入する → listMyTasks が by_owner インデックスで読み取る」など）。こうして、部品をただ列挙するだけでなく、各要素がどうつながるかを示します。
7. ひと目で把握できる全体像として提示します（データモデル → 公開／内部関数 → 認証モデル → コンポーネント／外部接続 → フロー）。ソースに忠実であること。最後に、次に使うべき動詞を示します。監査には convex-reviewer/convex-authz、評価には launch-readiness、拡張には design/convex-expert を案内します。ソースに示されていない動作を決して作り上げないでください。不明確な点があれば、推測せずにそう伝えます。

ルール

• スキーマと関数の公開範囲（functionSpec／ソース）を信頼できる情報源として読み取ります。コードに示されていない動作を説明せず、推測するのではなく曖昧な点を明示します。
• 新しく関わる人が最も知る必要があり、ざっと読むだけでは最も間違いやすい 2 点、すなわちデータモデルのリレーションシップグラフと、公開関数と内部関数の区別から説明を始めます。
• 認証／所有権モデルを、認証の基盤が存在しない場合はその点も含めて明確に説明します。ただし、問題点の監査はしません。それは convex-authz の役目です。
• 評価ではなく説明に徹します。explain-app は現状を示し、判断は監査機能に、変更は修正機能に委ねます。
• 読み取り専用です。デプロイを調査する場合も読み取り専用（deploy-guard）であり、アプリは変更しません。
• 次に使うべき動詞を示して終わります（監査 → reviewer/authz、評価 → launch-readiness、拡張 → design/expert）。