version-aware-recommendations

バージョンを考慮した推奨

基本ルール：内部の記憶をもとにバージョンや機能セットを推奨してはいけません。必ず最新の外部ソースで確認してください。

ソフトウェアのバージョンに関するエージェントの記憶は、数か月で古くなります。機能セットは変わり、メジャーリリースが公開され、「最新の安定版」が正しくなくなることもあります。バージョンを推奨する際は、必ず最新情報を照会して根拠を確認してください。

使用する場面

• 言語ランタイム、フレームワーク、ライブラリ、ツールのバージョンを推奨する場合
• ソフトウェアをインストールまたはデプロイする場合（apt、pip、npm、docker、homebrew など）
• 依存関係を特定のバージョンに固定する場合
• 外部ソフトウェアの機能、性能、要件を列挙する場合
• ソフトウェアの選択肢を比較する場合（「どのデータベースを使うべきですか？」）
• CI/CD ツールチェーン、ベースイメージ、SDK のターゲットを設定する場合

不要な場合： プロジェクト内部のバージョン（独自アプリのバージョン、内部のモノレポパッケージ）。

手順

1. ソフトウェアを特定する — 正確なパッケージ、イメージ、またはツールの名前を確認します。
2. 公式ソースを検索する — web_search を使うか、公式 URL を read します。優先するソース：プロジェクトのウェブサイト、GitHub／GitLab のリリース、Docker Hub、パッケージレジストリ（PyPI、npm、crates.io、Maven）、Homebrew のフォーミュラ。
3. 最新の安定版を特定する — alpha、beta、RC、プレリリースのタグを除外します。最新の安定版リリースのバージョンを確認します。
4. 最新のドキュメントを確認する — 特定したバージョンの最新ドキュメントを読みます。機能、デフォルト設定、非推奨事項は変わるため、記憶に頼らないでください。以下のドキュメント照会表を使用します。
5. 根拠を示して推奨する — バージョンを明記し、確認元へのリンクを示します。記憶ではなく、最新のドキュメントに記載された機能セットを含めてください。

ドキュメントの照会（手順4）

利用できるツール	用途	使用しない用途
context7 MCP ツール（resolve-library-id と query-docs として公開、またはデバイスパス xd://mcp__context_context_resolve_library_id / xd://mcp__context_context_query_docs）	ライブラリ／フレームワークの公式ドキュメントに基づき、機能、設定、デフォルト、コード例、非推奨事項を確認する	バージョン番号 — レジストリとリリースページが信頼できる情報源です
read による公式ドキュメント	context7 が利用できない、または該当項目がない場合の代替手段。バージョン／リリース情報の確認には常に使用する	—

context7 が利用できる場合は、ドキュメントの確認で最初に使用してください。ドキュメント URL を推測してはいけません。

1. {libraryName: "FastAPI", query: "<確認したい内容>"} を指定して resolve-library-id を実行します。名前が完全に一致し、ソースの評価が High／Medium で、コードスニペットが最も多い候補を選びます。
2. {libraryId: "/org/project", query: "<特定のトピック>"} を指定して query-docs を実行します。パラメーター名は topic ではなく query です。1 回の呼び出しにつき 1 つの概念を指定し、概念が異なる場合は別々に呼び出します。
3. 特定のバージョンのドキュメントを確認するには、バージョン固定の ID（例：/vercel/next.js/v14.3.0）を使います。resolve-library-id が返すバージョン一覧から選んでください。
4. resolve-library-id を 3 回以内で試しても適切な候補が見つからない場合は、read で公式ドキュメントを確認し、重要な機能に関する主張はプロジェクト独自のリリースノートとも照合します。

質問ごとの上限： context7 ツールは 3 回を超えるとエラーになります。複数の概念を確認する場合も、概念ごとに query-docs を 1 回だけ使い、合計 3 回で止めてください。互いに関連する概念に限って 1 つのクエリにまとめ、それ以外は推奨の根拠となる概念を優先し、残りは公式ドキュメントを read して照合します。

プレリリースの例外

安定版を優先してください。 次の例外のいずれかに該当しない限り、プレリリース（alpha、beta、RC、nightly、canary、-dev、-preview）は採用しません。

• 必要な機能の不足： 特定の機能またはバグ修正がプレリリースにのみ存在し、現在の要件で必要な場合。その機能と、安定版では不十分な理由を明記してください。
• 最近の安定版がない： プロジェクトに過去12か月以内の安定版リリースがない場合、または初期段階もしくは放棄されたプロジェクトの場合。プロジェクトのリリース履歴と、プレリリースが最善の選択肢である理由を明記してください。

例外に該当する場合、エージェントは次の点を明示する必要があります。

1. 該当する例外
2. 安定版が適さない理由
3. 推奨するプレリリースのバージョン
4. プレリリースソフトウェアに依存するリスク

バージョンの固定

最新ではないバージョンに固定する場合は、その理由を記録してください。

理由	例
互換性の制約	「v4.0ではNode < 18のサポートが削除されるため、v3.2に固定」
既知のリグレッション	「上流の問題 #1234 によりv2.7.1ではユースケースが機能しないため、v2.7.0を使用」
再現性	「既存のCIと本番環境に合わせてv1.4.3に固定」
EOL／セキュリティ	「v6.xは当プラットフォームでサポートされていないため、v5.x LTSに固定」

理由なくバージョンを固定しないでください。 固定したバージョンとその理由は、コードコメント、ロックファイル、またはドキュメントで確認できるようにしてください。

注意点

• 記憶のずれ： 「Python 3.11が最新」—これは誤りです。現在は3.12または3.13かもしれません。必ず調べてください。
• 機能の幻覚： 古い記憶に基づいて機能を列挙すること。最新のドキュメントを確認してください。
• ドキュメントURLの推測： (/tutorial/websockets/ → 404) のようにドキュメントのパスをでっち上げ、別のパスを試すこと。context7が利用できる場合はそれを照会し、利用できない場合はドキュメントのインデックスまたはサイトを指定した検索から始めてください。
• バージョン確認にcontext7を使うこと： context7がインデックス化するのはドキュメントであり、リリースレジストリではありません。バージョン番号は引き続きPyPI／npm／GitHub releases／Docker Hubで確認してください。
• プレリリースを安定版として扱うこと： 「v2.0.0-rc.1」は安定版ではありません。例外に該当しない限り、プレリリースは除外してください。
• 理由のない固定： 理由を説明せずにflask==2.2.0に固定すること。将来のエージェント（またはあなた自身）が制約を把握できなくなります。
• 部分的な検証： バージョンだけを調べ、機能を推測すること。バージョンと機能セットの両方を最新情報で確認する必要があります。
• 二次情報源： ブログ記事、Stack Overflow、第三者の記事は古くなっている可能性があります。必ず公式情報源で確認してください。

検証

推奨した後、次の点を確認してください。

• バージョン番号が公式情報源に記載されているものと一致している（リンクを含める）
• 列挙した機能が記憶ではなく、最新のドキュメントと一致している
• プレリリースの場合：例外が正当な理由とともに明記されている
• バージョンを固定した場合：理由がインラインで記録されている

作業を進める前の簡易チェック：

Is this version number from a live lookup? If no → stop, search.
Am I listing features from memory? If yes → stop, read docs.
Did I guess a documentation URL while context7 was available? If yes → stop, use query-docs.
Is this a pre-release without documented justification? If yes → stop, either find stable or document exception.
Is this pin documented with a reason? If no → stop, add rationale.