convex-docs

バージョンに合った Convex ドキュメントを取得する

convex-expert には、プラグインのバージョンに応じた知識が組み込まれています。安定した慣用表現には最適ですが、新しいエクスポートが追加されたコンポーネント、変更された CLI フラグ、バージョン間で名前が変わった API など、重要な部分ほど情報が古くなります。この機能では、その上に情報の鮮度を保つ手順を重ねます。プロジェクトで実際に使われているバージョンを特定し、最新のページを低コストで Markdown として取得し、現在の情報を一度取得するだけで済むときに、見慣れない API を記憶から書くことは決してありません。

ワークフロー

1. バージョンを特定します。インストール済みの convex のバージョン（node -p "require('./node_modules/convex/package.json').version" または package.json）と、使用中の @convex-dev/* コンポーネントのバージョンを読み取ります。参照するドキュメントは、これらのバージョンと一致している必要があります。バージョンのずれは、誤った Convex コードが生じる最大の原因です。
2. 情報の鮮度に関する優先順位（Supabase から学んだ、正確さを保てる中で最も低コストな順）： (a) 提供されているドキュメントツール／MCP の search_convex_docs があれば使用します（コンテキストウィンドウに収まるサイズで、バージョンに合わせて絞り込み、再ランク付けした回答が返されます）。 (b) それがなければ、該当するドキュメントページを Markdown として取得します。docs.convex.dev/<path> をリクエストし、サイトが対応している場合は .md／Markdown 形式を優先します（HTML より大幅に少ないトークンで済みます）。または、指定したバージョンのコンポーネントの README を取得します。 (c) その後に限り、一般的なウェブ検索を行い、バージョンは未確認として扱います。 最新情報に不確実性がある場合、手順を飛ばして記憶から API を書いてはいけません。
3. 重要な場合は、インストール済みパッケージで確認します。コンポーネントのエクスポートが存在するか確信が持てない場合は、node_modules/@convex-dev/<x>/ にある package.json の exports と .d.ts を確認します。インストール済みの型定義が、このバージョンにおける信頼できる情報源であり、どのドキュメントよりも優先されます。
4. 取得した情報は必要な範囲だけに使います。最新のシグネチャ／フラグを適用し、情報元（ページとバージョン）を示してから、実際のコードを convex-expert に渡し、慣用的な書き方にしてもらいます。convex-docs は最新情報を提供し、convex-expert は慣用表現を提供します。
5. バージョンの不一致によるビルドエラーが起きた場合（「存在するはず」のエクスポート／フラグが見つからない場合）は、別のつづりを推測せず、最新情報の問題として扱います。バージョンを特定し、最新の API を取得して修正します。

ルール

• 最新情報に不確実性がある場合、バージョンを特定して最新の情報源を取得する前に、見慣れない、または名前が変更された可能性のある Convex／コンポーネントの API をモデルの記憶から書いてはいけません。
• インストール済みパッケージの node_modules にある exports／.d.ts が、このバージョンにおける信頼できる情報源です。ドキュメントページよりも優先されます。
• 情報の鮮度に関する優先順位に従います。提供されているドキュメントツール → ページを Markdown として取得／指定バージョンの README → 一般的なウェブ（未確認）。正確さを保てる中で最も低コストな方法を選び、トークンを最小限に抑えます。
• HTML のドキュメントページよりも Markdown を優先します。同じ内容でも、必要なトークンが大幅に少なくなります。
• 最新の事実情報を提示し、慣用的なコードは convex-expert に任せます。これは情報の鮮度を保つための層であり、組み込まれた知識に取って代わるものではありません。
• バージョン不一致によるビルドエラーは、つづりを推測する問題ではなく、最新情報の問題です。バージョンを特定し直して、情報を再取得します。