convex

Convex ガイドライン

このスキルでは、現在の Convex ドキュメントの範囲を扱います。まず、以下から最も関連性の高いローカルガイドを参照してください。タスクがまだ references/ に反映されていない新しいプラットフォーム領域に関わる場合は、変更を加える前に https://docs.convex.dev/llms-full.txt にあるリンク先の最新ドキュメントを確認してください。

基本ルール

1. 周囲のコードベースですでに別のパターンが使われている場合を除き、ファイルごとにエクスポートする Convex 関数は1つにすることを推奨します。同じファイル内に小さなプライベートヘルパーを置いても問題ありません。
2. 安全性、生成される API 型、OpenAPI 出力、または静的コード生成の改善につながる場合は、精密なバリデーターを使用してください。Convex のすべての関数で args または returns のバリデーターが必須だとは説明しないでください。省略した場合、Convex は v.any() にフォールバックします。
3. v.any() は、真に動的なペイロードや信頼できる外部 Webhook のペイロードに対する意図的な例外として扱い、通常のアプリケーションデータのデフォルトの選択肢にはしないでください。
4. ランタイムは意図的に選択してください。クエリとミューテーションは ctx.db を使うトランザクション内で実行し、アクションは外部 I/O と Node 専用の処理に使用します。ベクトル検索はアクションでのみ実行できます。
5. 広範なフィルタリングより、インデックスとスキーマ設計を優先してください。クエリの形状が正確性やスケーラビリティに関わる場合は、適切なインデックス戦略を確認してください。

まずローカルのリファレンスガイドを使用する

関数ガイドライン

参照する場面：Convex 関数の作成や変更、HTTP エンドポイントの設定、バリデーターの定義、関数の登録、API 構造の設計、ページネーションの処理、またはクエリ、ミューテーション、アクション、内部関数、HTTP アクションの選択を行う場合。

バリデーターガイドライン

参照する場面：引数または戻り値のバリデーターを定義する場合。特に整数、レコード、ユニオン、または動的なペイロードを扱う場合。バリデーターは型を強化するために推奨されますが、Convex で常に必須というわけではありません。

スキーマガイドライン

参照する場面：convex/schema.ts の作成や変更、テーブルの追加、インデックスの定義、_id と _creationTime の処理、またはテーブル間の関係を設計する場合。

TypeScript ガイドライン

参照する場面：Convex の TypeScript 型を扱う場合。特に Id<>、Record、判別可能ユニオン、生成される API 型、静的コード生成のトレードオフ、または Node の型設定を扱う場合。

クエリガイドライン

参照する場面：データベースクエリの作成、結果のフィルタリング、データの並べ替え、ページネーションの使用、またはインデックスを利用したアクセスパターンの検討を行う場合。

ミューテーションガイドライン

参照する場面：ctx.db を使ってドキュメントを更新、置換、挿入、または削除する場合。

アクションガイドライン

参照する場面：外部 API の呼び出し、Node モジュールの使用、ベクトル検索の実行、またはトランザクション外の処理の調整を行うアクションを作成する場合。

スケジューリングガイドライン

参照する場面：スケジュール関数や定期ジョブを使って、cron ジョブやスケジュールされた処理を設定する場合。

ファイルストレージガイドライン

参照する場面：アップロード、ダウンロード、生成ファイル、ファイルの配信、またはファイルメタデータを扱う場合。

全文検索ガイドライン

参照する場面：withSearchIndex を使ったテキスト検索を実装する場合。

マイグレーションガイドライン

参照する場面：マイグレーションの計画や実行、スキーマの進化への対応、またはこのリポジトリのマイグレーション用ショートカットや一括実行ワークフローを使用する場合。

例

参照する場面：スキーマ設計、パブリック／内部関数、バックグラウンド処理のパターンを含む、より詳細なリファレンス実装が必要な場合。

認証ガイドライン

参照する場面：Convex Auth、Clerk、Auth0、WorkOS/AuthKit、カスタム OIDC または JWT プロバイダーの設定、Convex でのユーザーの保存、または関数内での認証状態の読み取りを行う場合。

コンポーネントのガイドライン

読むタイミング：Convex コンポーネントをインストール、使用、作成するとき。

AI とエージェントのガイドライン

読むタイミング：Convex Agent コンポーネント、スレッド、ツール、ストリーミング、RAG、使用状況の追跡、ワークフロー、Convex MCP サーバー、または AI コード生成のワークフローに取り組むとき。

ベクトル検索のガイドライン

読むタイミング：ベクトルインデックスの定義、埋め込みの生成、またはハイブリッド／ベクトル検索の実行を行うとき。

テストのガイドライン

読むタイミング：バックエンドテスト、CI カバレッジ、ローカルのバックエンドテスト、または convex-test のモックを追加するとき。

本番環境のガイドライン

読むタイミング：convex.json、環境変数、プレビュー用デプロイ、複数のリポジトリ、ログストリーム、例外レポート、またはデプロイ／ランタイム設定を編集するとき。

クライアント統合のガイドライン

読むタイミング：Convex を React、React Native、Next.js App Router、Next.js Pages Router、TanStack Start、Bun、Node.js、Python、Swift、Kotlin、または OpenAPI ベースのクライアントに接続するとき。

現行ドキュメントに基づく実践的なガイダンス

1. タスクが公開 API の形状、生成クライアント、OpenAPI 出力、または静的コード生成に影響する場合は、明示的な args と returns バリデーターを強く推奨します。
2. タスクが内部のみを対象とし、ペイロードの型を意図的に緩くしている場合は、対象を絞った v.any() を使用できます。ただし、周囲のヘルパー名と型を通じて信頼境界を明確にしてください。
3. タスクに高度な検索が含まれる場合は、スキーマ、インデックス、関数の型が異なるため、早い段階で全文検索とベクトル検索のどちらを使用するか決めてください。
4. タスクにフロントエンド統合が含まれる場合は、React の既定値がどこでも適用されると想定せず、フレームワーク固有のクライアントドキュメントを選んでください。
5. タスクにデプロイまたは AI ツールが含まれる場合は、プロジェクトレベルの規約を独自に作る前に、convex.json と CLI のドキュメントを確認してください。現行の Convex ドキュメントでは、functions、aiFiles、Node ランタイム設定、静的コード生成オプションが説明されています。
6. ローカルのリファレンスファイルに必要な情報がない場合は、https://docs.convex.dev/llms-full.txt と、使用する機能に固有のリンク先ページを参照してください。