コンテキストフックの使用 - Amazon Q Developer
コンテキストフックの種類コンテキストフックの管理ユースケースの例動作と制限事項セキュリティに関する考慮事項トラブルシューティング

コンテキストフックの使用

コンテキストフックは Amazon Q Developer CLI の機能で、Q Developer との会話にコンテキストを自動的に挿入するために使用できます。/context コマンドでコンテキストを手動で追加する代わりに、コンテキストフックでコマンドを実行し、出力をコンテキストとして含めます。

コンテキストフックの種類

Q Developer CLI は、次の 2 種類のコンテキストフックをサポートします。

会話開始フック

会話の開始時に 1 回実行します。出力は会話コンテキストに追加され、セッションの間中ずっと保持されます。

プロンプトごとのフック

各ユーザーメッセージで実行します。出力は現在のプロンプトにのみ追加されます。

コンテキストフックの管理

Q Developer CLI の /context hooks コマンドを使用して、コンテキストフックを管理できます。

フックを表示する

グローバルレベルとプロファイルレベルの両方ですべての設定済みフックを表示するには:

/context hooks

このコマンドは、現在のプロファイルにグローバルレベルで設定されているすべてのフックとそのステータス (有効または無効) を表示します。

フックを追加する

新しいコンテキストフックを追加するには:

/context hooks add [--global] <name> --trigger <trigger> --command <command>
<名前>

フックの一意の名前

<トリガー>

per_prompt または conversation_start

<コマンド>

実行するシェルコマンド

--global

(オプション) 現在のプロファイルではなく、フックをグローバル設定に追加します

例 git ステータスフックの追加
/context hooks add git-status --trigger per_prompt --command "git status --short"

フックを削除する

既存のコンテキストフックを削除するには:

/context hooks rm <name> [--global]

フックを有効または無効にする

特定のフックを有効にするには:

/context hooks enable [--global] <name>

特定のフックを無効にするには:

/context hooks disable [--global] <name>

すべてのフックを有効にするには:

/context hooks enable-all [--global]

すべてのフックを無効にするには:

/context hooks disable-all [--global]

フックに関するヘルプを取得する

フックコマンドの詳細なヘルプを表示するには:

/context hooks help

設定

フックの設定は、次の場所で確認できます。

フックがグローバルの場合:

~/.aws/amazonq/global_context.json

フックがプロファイルベースの場合:

~/.aws/amazonq/profiles/profile-name/context.json

ユースケースの例

以下は、コンテキストフックの一般的なユースケースの例です。

git ステータス

各プロンプトで git ステータスを表示するフックを追加します。

/context hooks add git-status --trigger per_prompt --command "git status --short"

このフックは、各プロンプトの前に git status --short コマンドを実行し、Q Developer との会話に出力を含めます。これにより、バージョン管理について質問したり、git コマンドに関するヘルプが必要な場合に、Q Developer が git リポジトリの現在の状態を理解するのに役立ちます。

プロジェクト情報

会話の開始時にプロジェクト情報を表示するフックを追加します。

/context hooks add project-info --trigger conversation_start --command "echo 'Project: '$(basename $(pwd))"

このフックは会話の開始時に 1 回実行され、コンテキストに現在のプロジェクト名を含めます。これは、Q Developer がプロジェクトに固有のより関連性の高い応答を提供するのに役立ちます。

ヒント

このフックを拡張して、プログラミング言語、フレームワーク、プロジェクト構造など、より多くのプロジェクト情報を含めることができます。

動作と制限事項

コンテキストフックを使用する場合は、次の動作と制限事項に注意してください。

  • フックは並列して実行され、応答時間への影響を最小限に抑えます

  • フック出力はフォーマットされ、コンテキスト内で明確にマークされます

  • /clear コマンドは会話開始フックを再評価します

  • フックは Q Developer CLI 設定に保存されます

  • 現在、インラインコマンドフックのみがサポートされています

  • フック出力はフックごとに 10KB に制限されています

  • フックは デフォルトで 5 秒後にタイムアウトします

セキュリティに関する考慮事項

コンテキストフックを使用する場合は、次のセキュリティのベストプラクティスを考慮してください。

  • コンテキストフックは、現在のユーザーアクセス許可でシェルコマンドを実行します。フックに含まれるコマンドには、ユーザーアカウントと同じアクセス権限があるため、どのコマンドを含めるかに注意してください。

  • 認証情報や個人データなどの機密情報を公開する可能性のあるフックを追加する場合は注意してください。フックの出力を確認して、共有したくない情報が含まれていないことを確認してください。

  • フックが必要ない場合は、無効にすることを検討してください。これにより、誤って機密情報を公開するリスクが軽減されます。

  • フックを使用して、システムまたはデータを変更する可能性のあるコマンドを実行しないでください。フックは、変更を行うためではなく、情報を読み取るために使用してください。

  • 共有環境でフックを使用する場合は注意してください。Q Developer CLI セッションにアクセスできる他のユーザーは、フックの出力を表示できる可能性があります。

警告

パスワード、アクセスキー、またはその他の認証情報を公開するコマンドをフックに含めないでください。この情報は会話履歴に保存され、他のユーザーに公開される可能性があります。

トラブルシューティング

コンテキストフックで問題が発生した場合は、次のソリューションを試してください。

コンテキストフックのトラブルシューティング
問題 ソリューション
フックが実行されない フックが /context hooks で有効になっていることを確認します
コマンドが失敗する ターミナルでコマンドを直接テストして、動作することを確認します
出力が多すぎる コマンドを変更して出力サイズを制限します
フックがタイムアウトする コマンドを最適化して実行を高速化します