spring-ai

Spring AI

プロジェクトを変更する前に、実際の Maven または Gradle の Spring AI プロジェクトを調査するには、この運用スキルを使用します。付属の診断 CLI はオフラインで動作し、プロバイダーに依存しません。ビルドファイル、アプリケーション設定、ソースコードを読み取り、互換性の手がかり、安全でないデフォルト設定、会話 ID の不足、ストリーミングの前提条件、ツール／MCP の境界、検索設定、オブザーバビリティのリスクを報告します。プロンプトを送信したり、API キーの値を公開したりすることはありません。

最初の確認

プロジェクトのルートと、タスクが読み取り専用か、設定／コードを変更するものかを確認します。読み取り専用の診断は実行できます。状態を変更する最初の操作の前に、対象プロジェクト、作業範囲、ロールバック方法（通常はレビュー済みのコミットまたはリバート）を確認します。CLI 自体は読み取り専用です。

次を実行します。

python3 spring-ai/scripts/spring_ai_check.py --root /path/to/project --json

結果は status、project、facts、findings、errors を含む安定した JSON です。終了コード 0 はエラー重大度の指摘がないことを意味します。終了コード 1 は、エラー重大度の指摘、または --strict によって警告が昇格された指摘があることを意味します。終了コード 2 は、呼び出しが無効か、プロジェクトを読み取れないことを意味します。

ワークフロー

1. チェッカーを実行し、プロジェクトのリビジョンとともに JSON 出力を保持します。
2. references/source-index.md にある Spring AI と Spring Boot の公式ドキュメントを参照して、ビルド互換性に関する指摘を解決します。推移的な依存関係だけからサポート状況を推測しないでください。
3. ChatClient のアドバイザーの順序とパラメーターを調べます。メモリーアドバイザーを呼び出すたびに、アプリケーションの認証済み／セッション境界に基づく会話 ID を明示的に指定してください。共有のデフォルト値は使用しないでください。
4. 検索では、検索コンテキストがプロンプトに入る前に、ドキュメントの所有権／認可を検証します。検索結果が空の場合、データが古い場合、プロバイダーエラー、レイテンシをそれぞれ個別にテストします。
5. ツールと MCP では、モデルによるツール要求を信頼できない提案として扱います。認可と実行の責任はアプリケーションが負います。ツール名、引数、タイムアウト、再試行、副作用、監査フィールドに制限を設けます。現在のプロジェクト依存関係に照らして、MCP のトランスポートとスキーマを検証します。
6. ストリーミングでは、完了するまでは部分出力を暫定的なものとして扱います。キャンセル、タイムアウト、切断、完了失敗をテストします。部分的なストリームを確定済みの回答や副作用として扱わないでください。
7. 本番環境では、プロンプト／補完のログ記録をデフォルトで無効にします。一時的に有効にする場合は、マスキング、アクセス、保持、ロールバックについて記録します。
8. 依存関係とプロバイダーの認証情報が利用できる場合は、プロジェクト独自のテスト／ビルドを実行します。このチェッカーでは、プロバイダーへの接続、モデルの品質、RAG の正しさ、本番環境への準備状況は確認できません。

対象範囲と振り分け

• ChatClient／アドバイザー、Spring の設定、ローカル診断、フレームワークのトラブルシューティングは、ここで扱います。
• モデルの品質、評価設計、統計的比較、トレーススキーマは agent-evals-and-observability の対象です。
• 権限、フォールバック、無効化、予算、ロールアウトは agent-production-operations の対象です。
• 脅威モデリングとセキュリティ実装は secure-software-engineering の対象です。
• Java／Spring アプリケーションの一般的な設計は、該当するエンジニアリングスキルの対象です。

バージョンの方針

公式ドキュメントでは現在、Spring AI 2.0.1 が最新の安定版として示され、1.0 のリファレンス（1.0.9）も掲載されています。API はバージョン系列によって異なります。たとえば、現在の 2.0 ドキュメントでは ToolCallingAdvisor が ChatClient のツールループとして説明されていますが、1.x アプリケーションではモデル内部のツールループが使用される場合があります。チェッカーは検出したバージョンを報告して不確実性を指摘しますが、依存関係を書き換えたり、一次情報の互換性資料なしにバージョンの組み合わせがサポートされていると断定したりはしません。アップグレード時は references/source-index.md とリリースノートを再確認してください。

完了条件

プロジェクトのビルド／設定／ソースに関する事実、指摘、担当者への振り分け、制限事項が記録された時点で終了します。または、外部依存関係（プロバイダーの認証情報、利用できないビルドツール、プライベートなアーティファクトリポジトリ）が利用できず、ブロック中であることが明示された時点で終了します。静的診断だけを根拠に、実環境でのスモークテストが成功したと主張しないでください。