redis-expert

Redis エキスパート

目的

データモデリングとキーの命名、クライアント接続、クラスタリングとレプリケーション、Redis Search、可観測性、セキュリティ、セマンティックキャッシュ、エージェントメモリの8つの領域にわたって、Redis の包括的な専門知識を提供します。コード、設定、設計上の判断が Redis に関わる場合は、いつでもこのスキルを活用してください。詳細は references/<domain>/ にあります。推測するのではなく、該当する領域とトピックのファイルを読み込んでください。技術的なガイダンスは、入手可能な場合は上流の資料に沿っており、集約した内容で Redis のバージョン、モジュール、クライアント、デプロイモデルを区別する必要がある場合は、その条件を明記しています。

基本原則

1. ユーザーが Redis と明示していない場合でも、コード、設定、設計上の判断が Redis に関わるときは、いつでもこのスキルを活用してください。
2. データの形状ではなく、アクセスパターンに基づいてデータ構造を選んでください。
3. タスクに関係するすべての領域を読み込んでください。本番環境の検索デプロイでは、コア、検索、セキュリティ、可観測性の領域がすべて関わります。
4. Redis に関するガイダンスは、対象のバージョン、モジュール、クライアントライブラリ、デプロイモデルに照らして検証してください。一般的なデータベースの常識では誤った方向に進みがちなため、ここでは信頼できません。
5. バージョンによって挙動が異なる場合は、その条件を明示してください。たとえば、次元数の不一致は拒否される一方で、メトリックの不一致は関連性をひそかに低下させるだけの場合があります。
6. 小規模な場合にしか通用しない近道より、段階的な SCAN 系コマンドと接続プールを優先してください。
7. 共有の認証情報を1つ使うより、最小権限に基づくアプリケーションごとの ACL を優先してください。
8. 生成するガイダンスでは、エムダッシュを使わないでください。

認可モデル

Redis に関する作業の大半は助言です。認可が重要になるのは、稼働中のシステムにアクセスする操作です。

ユーザーの指示	認可された範囲
「どのデータ構造がよいか」	接続不要の推論と推奨
「これをどうインデックス化すればよいか」	スキーマとクエリの設計。インデックスは作成しません
「動作が遅い」	提供されたメトリクス、SLOWLOG、FT.PROFILE の出力に基づく診断
「この設定を適用して」	設定変更の提案。適用するのは、適用を求められた場合のみ
「本番環境に接続して」	接続先を明示する別途の認可。接続前にリスクを報告
「キャッシュをフラッシュして」	明示的かつ具体的な指示であること。別のタスクを進める手段としては、決して実行しない

質問に答えるための便宜的な手順として、稼働中のデプロイに接続したり、破壊的なコマンドを実行したり、セキュリティ設定を変更したりしないでください。

ステップ0：先回りして検知する

ユーザーが「Redis」と言った場合に限らず、コード、設定、設計上の判断が Redis に関わるときは、いつでもこのスキルを活用してください。トリガーの全リスト、確信度のルール、対応を控えるべき状況については、references/proactive-trigger.md を読んでください。

ステップ1：適切な領域に振り分ける

作業内容	領域	参照フォルダー
データ構造の選択、キーの命名、エンティティのモデリング	コア	references/core/
クライアント、プーリング、パイプライン、タイムアウト、クライアントサイドキャッシュの設定、低速コマンドの回避	接続	references/connections/
シャーディング、ハッシュタグ、CROSSSLOT エラー、読み取りレプリカ	クラスタリング	references/clustering/
検索インデックスの設計、FT.SEARCH/FT.AGGREGATE/FT.HYBRID、ベクトル検索、RAG	検索	references/search/
メトリクス、SLOWLOG、INFO、インシデントのトリアージ、Redis Insight	可観測性	references/observability/
認証、ACL、TLS、ネットワーク公開、本番環境のセキュリティ強化	セキュリティ	references/security/
LangCache による LLM 応答のセマンティックキャッシュ	セマンティックキャッシュ	references/semantic-cache/
Iris によるエージェントのセッションイベント、長期記憶、バックグラウンドでの昇格	エージェントメモリ	references/iris/

1つのタスクに複数の領域が関わることはよくあります（本番環境の検索デプロイでは、コア、検索、セキュリティ、可観測性の領域がすべて関わります）。1つだけを選ぶのではなく、関係する領域のファイルをすべて読み込んでください。

コア：データモデリングとキーの命名

データの形状だけでなく、アクセスパターンに合った Redis の型を選びます。アトミックなカウンターには String、個別に更新するフィールドを持つオブジェクトには Hash、キューには List、メンバーシップの確認には Set、ランキングには Sorted Set、ネストされたデータには JSON、イベントログには Stream、類似検索には Vector Set を使います。よくあるアンチパターンは、フラットなオブジェクトをシリアライズした文字列に詰め込むことです。これでは、フィールドを更新するたびに取得・解析・変更・再書き込みが必要になるため、代わりに Hash を使います。

キー名は小文字とコロン区切りにし、安定した階層構造にします（user:1001:profile）。短くても読みやすい名前にし、マルチテナントの場合はテナントごとにプレフィックスを付けます（tenant:42:user:7:cart）。

references/core/choose-data-structure.md と references/core/key-naming.md を参照してください。

接続：Redis と効率的に通信する

接続はプールするか多重化し、リクエストごとに新しい接続を開かないでください。これはクライアントに関する最大のミスです。独立したコマンドはパイプラインにまとめ、1 回の往復で実行します。キー空間全体をスキャンするコマンド（KEYS、大きなセットに対する SMEMBERS、大きなハッシュに対する HGETALL）を本番環境で呼び出さないでください。代わりに、インクリメンタルな SCAN／SSCAN／HSCAN 系のコマンドを使います。アクセス頻度が高く、書き込みがまれなキーには RESP3 のクライアントサイドキャッシュを有効にします。クライアントのデフォルト設定に頼らず、アプリケーションの実際の障害モデルに合わせて、接続タイムアウトと読み取りタイムアウトを明示的に設定します。

接続プール、パイプライン、ブロッキング、クライアントキャッシュ、タイムアウトについては references/connections/ を参照してください。

クラスタリング：シャーディングとレプリケーション

Redis Cluster は各キーを 16,384 個のスロットのいずれかにハッシュします。複数キーを扱うコマンド（MGET、SDIFF、トランザクション、パイプライン、複数キーを扱う Lua）は、すべてのキーが同じスロットにないと CROSSSLOT エラーで失敗します。ハッシュタグ（{ と } の間の部分）を使うと、キーを同じ場所に配置できます。タグの範囲は意味のあるエンティティに絞ります（{user:1001}）。タグを付けすぎるとホットスポットが発生するため、付けすぎないでください。読み取り負荷の高いワークロードでは読み取りをレプリカに振り分けられますが、レプリカは結果整合性です。レプリカから直前に自分が書き込んだデータを読み取らないでください。また、厳密な鮮度が必要な処理ではレプリカから読み取らないでください。

references/clustering/hash-tags.md と references/clustering/read-replicas.md を参照してください。

検索：インデックス作成、クエリ、ベクトル、RAG

クエリコマンドは 3 つあります。ドキュメントを直接取得する FT.SEARCH（デフォルトの選択肢）、ファセット処理や分析パイプラインに使う FT.AGGREGATE、語彙検索（BM25）とベクトル類似検索を 1 つの統合クエリで組み合わせる FT.HYBRID（Redis 8.4 以降）です。FT.CREATE では必ず PREFIX を明示し、DIALECT 2 を使います。アクセスパターンに合った、必要最小限のフィールド型を選びます。完全一致フィルタリングには TAG を使うと、TEXT を誤って使う場合より約 10 倍高速です。ベクトルフィールドでは、DIM を埋め込みモデルに合わせ、距離メトリックを検索設計に合わせる必要があります。Redis、モジュール、クライアントのバージョンによっては、次元数の不一致はインデックス作成時またはクエリ実行時に拒否されます。一方、メトリックやモデルの不一致は、アプリケーションで明らかなエラーが発生しないまま、関連性を低下させることがあります。本番規模の近似検索には HNSW、小規模な完全一致コーパスには FLAT を使います。ダウンタイムなしでスキーマを変更する場合はインデックスエイリアスを使い、アプリケーションのクエリをインデックス名に直接向けないでください。

スキーマとフィールド型、クエリ構文、集約とカーソル、ベクトル検索とハイブリッド検索、ネイティブのベクトルセット、RAG パターン、インデックス管理、FT.EXPLAIN／FT.PROFILE によるデバッグ、および redis-py、Jedis、RedisVL のクライアント別の例（references/search/clients/）について、詳細は references/search/ を参照してください。

オブザーバビリティ：監視とインシデントのトリアージ

INFO から used_memory、connected_clients、blocked_clients、 instantaneous_ops_per_sec、keyspace_hits／keyspace_misses（ヒット率）、および rejected_connections を監視システムにエクスポートします。個別の診断には、 SLOWLOG GET で低速コマンドのしきい値を超えた操作を特定し、MEMORY DOCTOR でメモリプレッシャーのわかりやすい概要を確認し、CLIENT LIST で接続状態を調べ、 FT.PROFILE で遅い検索クエリを特定します。Redis Insight は対話的な調査に使用する公式 GUI であり、エクスポートしたメトリクスの代替ではありません。

references/observability/metrics.md および references/observability/commands.md を参照してください。

セキュリティ：本番環境の強化

本番環境にデプロイする場合は、マネージドサービスまたはセルフホストの構成に応じて、認証を設定し TLS を使用してください。認証なしの本番 Redis は、よくある侵害のパターンです。漏えいした認証情報による被害範囲を限定できるよう、共有の requirepass を 1 つ使用するのではなく、各アプリケーションに必要なコマンドとキーのパターンだけを許可する ACL ユーザーを優先してください。bind、protected-mode yes、およびアプリケーションのサブネットにアクセスを制限するファイアウォールルールで、ネットワークへの露出を制限します。bind 0.0.0.0 と protected-mode no を組み合わせると、Redis がネットワーク全体に公開されます。破壊的なコマンド（FLUSHALL、DEBUG、CONFIG）には、ACL 制限とネットワーク制御を優先してください。コマンド名の変更や無効化も行う場合は、期待されるコマンド名が使えなくなる可能性があるため、クライアントと運用ツールとの互換性を確認してください。

references/security/auth.md、references/security/acls.md、および references/security/network.md を参照してください。

セマンティックキャッシュ：LangCache による LLM 応答のキャッシュ

あらゆる LLM 呼び出しの前にキャッシュアサイドパターンを適用します。まずプロンプトの類似度でキャッシュを検索し、ヒットした場合は保存済みの応答を返し、ミスした場合は LLM を呼び出して結果を保存します。類似度のしきい値は、ワークロードや埋め込みモデルに応じたヒューリスティックであり、そのまま使える汎用の既定値ではありません。まずは保守的な値から始め、プライバシー、テナント分離、TTL、無効化、ポイズニングのリスクを考慮しながら、評価用データセットを使って調整してください。 タスクの種類が異なるもの（コードに関する質問とパスワードリセットに関する質問は、形式が似ていても意味的に異なります）でキャッシュを共有せず、タスクごとに別々のキャッシュ ID を使用するか、属性ベースのフィルタリングを使用してください。

references/semantic-cache/langcache-usage.md および references/semantic-cache/best-practices.md を参照してください。LangCache は現在 Redis Cloud でプレビュー提供中のため、動作が変更される可能性があります。

エージェントメモリ：Iris によるセッションメモリと長期メモリ

マネージド Redis Agent Memory データプレーンが提供する 2 つの階層です。会話ごとの追記専用セッションイベント（低コストで順序付けされ、書き込み経路では LLM を使用しません）と、デフォルトの TTL が 1 年の、意味検索が可能な長期メモリです。バックグラウンドの昇格ワーカーが 5 分間の重複排除ウィンドウでセッションから永続的な事実を抽出するため、書き込み後、長期メモリは最終的に一貫性が保たれます。

すべてのターンを、安定した単一の session_id とタイムゾーン対応の UTC タイムスタンプを使って追加します。書き込み時に owner_id、namespace、topics、および memory_type で長期レコードのスコープを設定します。クライアント側でフィルタリングするのではなく、構造化フィルターと類似度しきい値を使ってサーバー側で検索します。

references/iris/setup-and-auth.md、references/iris/session-memory.md、 references/iris/long-term-memory.md、および references/iris/promotion.md を参照してください。

障害への対処

Redis に関するガイダンスが、確認できなかった事実に依存する場合は、次のようにしてください。

1. ガイダンスの前提となるバージョン、モジュール、またはクライアントを明示します
2. 明示的な拒否と、気づかないうちに起きる性能や動作の劣化を区別します。より危険なのは後者です
3. ワークロードやバージョンに固有のベストプラクティスを、どの環境にも適用できるものとして示しません
4. たとえば、調整が必要な類似度のしきい値など、測定によって適切な答えを見つける必要がある場合は、その旨を伝えます
5. 不確実性を解消するために、稼働中のデプロイに接続したり、再設定したり、フラッシュしたりしないでください

類似度のしきい値を誤ると、気づかないうちに性能が劣化します。それについて確認されていない主張をした場合も同様です。

アンチパターン

• フラットで個別に更新されるオブジェクトを Hash ではなくシリアライズ済み文字列として保存する
• 完全一致のフィルタリングが必要なフィールドに TAG ではなく TEXT を使う
• SCAN ファミリーの増分処理を使わず、本番データに対して KEYS、上限のない SMEMBERS、または上限のない HGETALL を呼び出す
• 接続をプールまたは多重化せず、リクエストごとに新しい接続を開く
• クラスター化されたデプロイで、ハッシュタグを使ってキーを同じスロットに配置せずにマルチキー操作を行う
• 残高や冪等性の状態など、厳密な最新性が求められるものをレプリカから読み取る
• DIM または DISTANCE_METRIC が実際の埋め込みモデルと一致しない VECTOR フィールドを使う
• パスワードや TLS を設定せず、protected mode をオフにして 0.0.0.0 にバインドした Redis を本番環境で使う
• 無関係なタスク種別で意味キャッシュを共有する
• セッションイベントではなく、長期記憶を会話バッファーとして使う
• セッション書き込み後、昇格された記憶を同期的に検索できると想定する
• 関連するリファレンスを確認せず、一般的なデータベースの直感から Redis 固有のベストプラクティスを推測する。Redis には、他のデータベースでの直感が誤った判断につながりやすい固有の動作が十分にあります（CROSSSLOT、気づきにくいベクトル次元の不一致、RESP3 の要件など）。

同梱リファレンス

上流の公式スキルに加え、Iris のエージェントメモリドメインに合わせ、ドメイン別に整理しています。

• references/proactive-trigger.md：依頼されていなくてもこのスキルを使うべき状況と、確信度に関するルール。
• references/core/：データ構造の選択、キーの命名規則。
• references/connections/：接続プーリング、パイプライン処理、ブロッキングコマンド、クライアント側キャッシュ、タイムアウト。
• references/clustering/：ハッシュタグ、読み取りレプリカ。
• references/search/：スキーマとフィールド型、クエリ構文と最適化、集約とカーソル、ベクトル検索とハイブリッド検索、ネイティブベクトルセット、RAG パターン、ダイアレクト、インデックス管理とデバッグ、および references/search/clients/ にあるクライアント別の例。
• references/observability/：監視対象のメトリクス、組み込みのデバッグコマンド。
• references/security/：認証と TLS、ACL、ネットワーク制限。
• references/semantic-cache/：LangCache の使用方法とチューニングのベストプラクティス。
• references/iris/：Agent Memory ストアのセットアップと認証、セッションメモリ、長期記憶、バックグラウンドでの昇格。

リファレンス以外の同梱コンテンツ

• この集約には評価スイートは同梱されていません。Redis 固有のガイダンスを正式な実装契約として扱う前に、対象の Redis バージョン、モジュール、クライアントライブラリ、デプロイモデルに照らして検証してください。
• Cursor プラグインのパッケージングは、プロジェクトレベル（.cursor-plugin/plugin.json）にあり、このスキル単独ではなく、このリポジトリ内のすべてのスキルを対象としています。

実行時の動作については、対象の Redis バージョンとデプロイに関するドキュメントを引き続き正式な情報源としてください。