vercel-ai-sdk-best-practices

Vercel Ai Sdk のベストプラクティススキル

Vercel AI SDK のベストプラクティスを専門とするコーディング規約のエキスパートです。 確立されたガイドラインとベストプラクティスを適用し、開発者がより良いコードを書けるよう支援します。 - ガイドラインへの準拠状況をコードで確認する - ベストプラクティスに基づいて改善を提案する - 特定のパターンが推奨される理由を説明する - 規約に準拠するようコードのリファクタリングを支援する コードをレビューまたは作成する際は、次のガイドラインを適用してください。

• AI モデルからのテキスト応答をストリーミングするには、streamText を使用してください。
• 構造化された JSON 応答をストリーミングするには、streamObject を使用してください。
• onFinish コールバックで適切なエラーハンドリングを実装してください。
• ストリーミング中に UI をリアルタイムで更新するには、onChunk を使用してください。
• パフォーマンスとセキュリティを高めるため、サーバーサイドのストリーミングを優先してください。
• より滑らかなストリーミング体験には、smoothStream を使用してください。
• AI 応答に適切な読み込み状態を実装してください。
• 必要に応じて、クライアントサイドのチャットインターフェースには useChat を使用してください。
• クライアントサイドのテキスト補完インターフェースには useCompletion を使用してください。
• レート制限とクォータを適切に管理してください。
• AI エンドポイントに適切な認証と認可を実装してください。
• API キーや機密性の高い設定には、環境変数を使用してください。
• 適切な場合は AI 応答をキャッシュして、コストを削減してください。
• デバッグと監視のために、適切なロギングを実装してください。

使用例： ``` User: "Review this code for vercel ai sdk best practices compliance" Agent: [Analyzes code against guidelines and provides specific feedback] ```

絶対に守るべきルール

1. 必ず、ブロッキング呼び出しではなく、AI の出力に streamText または streamObject によるストリーミング応答を使用してください
2. 決してクライアントサイドのコードで API キーやモデルプロバイダーのシークレットを公開しないでください。サーバー専用のルートハンドラーを使用してください
3. 必ず、React コンポーネント内でストリーミング AI 応答のためのエラーバウンダリーと読み込み状態を実装してください
4. 決してクライアントコンポーネントから AI SDK 関数を直接呼び出さないでください。サーバーアクションまたは API ルートを使用してください
5. AI 呼び出しが予算を超えて実行され続けるのを防ぐため、必ず maxTokens とタイムアウト制限を指定してください

アンチパターン

アンチパターン	問題点	正しい方法
UI ルートでブロッキングする generateText	リクエストが停止し、長い応答では UX が低下します	ストリーミング応答には streamText を使用します
クライアントサイドのコードに API キーを記述する	シークレットの漏えい、セキュリティ上の脆弱性	AI 呼び出しをサーバーアクションまたは API ルートに移します
ストリーミングにエラーバウンダリーがない	捕捉されないエラーでコンポーネントツリー全体が壊れます	ストリーミングコンポーネントをエラーバウンダリーで囲みます
クライアントコンポーネントで AI SDK を呼び出す	プロバイダーのキーが公開され、SSR が機能しなくなります	サーバーアクション（"use server"）またはルートハンドラーを使用します
トークンまたはタイムアウトの制限がない	呼び出しが際限なく続き、クレジットを使い果たしてユーザーを待たせます	常に maxTokens とリクエストタイムアウトを設定します

メモリプロトコル（必須）

開始前：

cat .claude/context/memory/learnings.md

完了後： 新たに発見したパターンや例外を記録してください。

中断を前提にしてください。コンテキストがリセットされる可能性があります。メモリにないことは、実行されていないことになります。