カスタムエージェントの管理 - Amazon Q Developer
カスタムエージェントファイルの場所カスタムエージェントを整理するためのベストプラクティスチームとのカスタムエージェントの共有

カスタムエージェントの管理

このセクションでは、開発ワークフローでカスタムエージェントを効果的に整理、管理、操作する方法について説明します。

カスタムエージェントファイルの場所

カスタムエージェント設定ファイルは、特定のディレクトリに JSON ファイルとして保存されます。

グローバルカスタムエージェント

~/.aws/amazonq/cli-agents/{agent-name}.json

システム上のすべてのプロジェクトとディレクトリで使用できます。

プロジェクトレベルのカスタムエージェント

.amazonq/cli-agents/{agent-name}.json

特定のプロジェクトディレクトリとそのサブディレクトリ内でのみ使用できます。

重要： ファイル名の {agent-name} は参考用です。実際のエージェント名は、JSON 設定ファイル自体にある name フィールド (必須) によって決まります。

カスタムエージェントの優先順位と競合の解決

Amazon Q Developer CLI がカスタムエージェントを検索する場合、特定の優先順位が適用されます。

  1. 最初にローカルカスタムエージェント - 現在の作業ディレクトリ内のカスタムエージェントをチェック

  2. 次にグローバルカスタムエージェント - ホームディレクトリに戻ってカスタムエージェントをチェック

  3. 組み込みのデフォルト - カスタムエージェントが見つからない場合はデフォルトエージェントを使用

ローカルディレクトリとグローバルディレクトリの両方に同じ名前のカスタムエージェントが含まれている場合、ローカルカスタムエージェントが優先されます。このような状況が発生すると、Amazon Q Developer CLI に警告メッセージが表示されます。

WARNING: Agent conflict for my-agent. Using workspace version.

この優先順位システムにより、次のことが可能になります。

  • グローバルカスタムエージェントをプロジェクト固有のバージョンで上書きする

  • カスタムエージェントの変更をグローバルにする前にローカルでテストする

  • プロジェクトごとに異なるカスタムエージェント設定を維持する

カスタムエージェントを整理するためのベストプラクティス

グローバルカスタムエージェントを使用する状況

グローバルカスタムエージェントは、以下のような状況で使用します。

  • 汎用ワークフロー - 複数のプロジェクトで使用されるカスタムエージェント

  • 個人の生産性向上 - 個人のワークスタイルに合わせたカスタムエージェント

  • 一般的な開発タスク - コードレビュー、デバッグ、ドキュメント生成

  • ツール固有のワークフロー - AWS 管理、Git オペレーション、Docker ワークフロー

ローカルカスタムエージェントを使用する状況

ローカルカスタムエージェントは、以下のような状況で使用します。

  • プロジェクト固有の設定 - 特定のプロジェクトファイルへのアクセスが必要なカスタムエージェント

  • チームコラボレーション - バージョン管理を通じて共有されるカスタムエージェント

  • 開発環境 - 特定のプロジェクトに固有の要件を持つカスタムエージェント

  • テストと実験 - グローバル設定に影響を与えない一時的なカスタムエージェントの変更

カスタムエージェントの命名規則

カスタムエージェントを整理しやすくするために、次のような命名規則を使うことを検討してください。

  • 目的ベースの名前 - aws-specialist.json、code-reviewer.json、documentation-writer.json

  • テクノロジー固有の名前 - python-dev.json、react-frontend.json、terraform-ops.json

  • プロジェクト固有の名前 - project-alpha.json、mobile-app.json、api-backend.json

  • 環境固有の名前 - development.json、staging.json、production.json

チームとのカスタムエージェントの共有

ローカルカスタムエージェントは、バージョン管理システムを通じてチームメンバーと共有できます。このアプローチにより、チームは次のことが可能になります。

  • 開発環境の標準化 - すべてのチームメンバーが必ず同じツールと設定にアクセスできる

  • プロジェクト固有のコンテキストの共有 - プロジェクトのドキュメント、コーディング標準、カスタムスクリプトを含めることができる

  • 一貫性の維持 - 使用するツールのアクセス許可と設定をチーム全体で統一できる

  • 共同での改善 - プルリクエストを使用してカスタムエージェント設定を確認および改善できる

バージョン管理のベストプラクティス

バージョン管理を通じてカスタムエージェントを共有する場合のベストプラクティスは以下のとおりです。

  • カスタムエージェントディレクトリを追加する - リポジトリに .aws/amazonq/agents/ を追加する

  • カスタムエージェントの目的を文書化する - カスタムエージェント設定ファイルで明確な説明を使用する

  • カスタムエージェントの変更を確認する - カスタムエージェント設定の変更をコード変更のように扱う

  • カスタムエージェント設定をテストする - 共有カスタムエージェントがすべてのチームメンバーに対して正しく動作することを確認する

  • 機密情報を使用しない - 共有カスタムエージェントには API キー、パスワード、または個人情報を含めない