Amazon Q Developer CLIをClaude Codeから使うためのベストプラクティスを考えてみた

■プレゼンテーション概要
この資料は、「Claude Code」から「Amazon Q Developer CLI」を利用するためのベストプラクティスを考察したプレゼンテーションです 。2025年11月1日にAI Coding Meetup Aichi | AIAUで発表されたものです。

■目的
業務でClaude Codeを利用する中で、AWSへのデプロイやインフラ障害調査にはAmazon Q Developer CLIを活用していると述べられています 。 この資料の目的は、Claude CodeからAmazon Q CLIを使う複数の方法を比較し、業務に最も使いやすい方法を整理することです 。

■比較検討される3つのパターン
資料では、Amazon Q CLIを操作する主な方法として、以下の3つのパターンが挙げられています 。

Subagent : Claude Codeから独立して自律実行する 。
Skills : Claude Code本体が直接実行する 。
MCP Server : MCPプロトコル経由でカスタム実装（AWS Q CLI MCP Server）を利用する 。

各パターンの分析（EKSのエラー調査ユースケース）
「EKSクラスタのPodエラー原因調査」という具体的なユースケースを想定して、各パターンが分析されています 。

Subagent（ページ7）
メリット: 指示したタスクを一気通貫で実施できる 。
デメリット: 実行中に途中経過が見えず、介入もできない 。指示が完璧でないと手戻りが発生しやすい 。

Skills（ページ8）
メリット: リアルタイム対話が可能で、各ステップでユーザーが確認・方向転換できる 。透明性が高い 。
デメリット: 途中で追加指示や修正ができる反面、会話履歴をClaude Code側で管理する必要がある 。

MCP Server（ページ9）
動作: Claude Code側から見るとSkillsと似た動作になる 。
デメリット: MCP Serverの構築コストが高い 。

結論
比較検討の結果、この資料では以下の結論が示されています。
迷った時は Skills から始める!

基本方針として、AI対話での情報取得には「Skills」を使い、必要に応じてカスタム統合のために「MCP Server」を、長時間バッチ処理などの例外的なケースで「Subagent」を使う、という使い分けが推奨されています 。

■主な注意点
リスク : 自動実行（--no-interactive, --trust-all-tools）を行う設定が必要なため、AWS環境を誤って変更・破壊するリスクが（Amazon Q CLIを直接使う場合より）一定上がる 。
会話履歴 : Amazon Q CLI側では会話履歴を保持しないため、Claude Code側で履歴を保持し、次の指示に含める必要がある

Transcript

1. Amazon Q Developer CLI をClaude Codeから使うための ベストプラクティスを考えてみた 2025-11-01 AI Coding Meetup Aichi | AIAU
2. 自己紹介
3. Amazon Q Developer CLI とは 効率的なアプリケーション開発を実現 AWSリソースのあらゆる情報をAI対話形式で取得 参 考 :Amazon Q Developer CLI で は じ め る 、 効 率 的 な ア プ リ ケ ー シ ョ ン 開 発 参考:Amazon Q Developer CLI ではじめる、効率的なアプリケーション開発
4. 背景/目的 • Claude Codeを業務利用しているが、AWSへのデプロイやインフラ障害調査は Amazon Q Developer CLI（※）を活用している ※以下、 Amazon Q CLI • Claude CodeからAmazon Q CLIを使う方法はいくつかあり、 どの方法が業務に最も使いやすいか整理したい。明日からの仕事を楽にしたい。 VSCodeの ここから使いたい ＜前提＞ ※各種詳細設定については 割愛します。ご興味のある方は 今後git repoに上げますので確認ください。
5. Amazon Q CLI 操作の3つのパターン 1. Subagent Claude Codeから独立して 自律実行 2. Skills Claude Code本体が直接実行 3. MCP Server MCPプロトコル経由でカスタム実装 AWS CLI MCP AWS CLIコマンドを Claude Codeが直接実行 Amazon Q CLIを直接使う場合はSubagentに近い動作になると思われる AWSリソースを操作する別の方法 Amazon Q CLIを 使わないので今回対象外
6. 想定ユースケース（原因調査系タスク） “arn:aws:eks:us-west-1:XXXX:cluster/XXXX EKSクラスタの YYY-ZZZ-worker-0 podで発生しているエラー理由を教えて。 そして、その理由をマークダウンファイルで保存して。” AWS EKS Kubernetesのコントロールプレーン（クラスターの頭脳部分）の運用や高可用性の 確保をAWSに任せられるマネージドサービスです。 これにより開発者はインフラ管理の負担を減らし、MLOpsの文脈では、コンテナ化された 機械学習のワークフローを動かすための堅牢な基盤として機能します。具体的には、大 規模な分散学習ジョブの実行、GPUリソースの効率的なスケジューリング、推論API （モデルサービング）の自動スケーリングなどに広く利用されます。
7. Subagent 利用の場合の動作 ✓ 指示したタスクを一気通貫で実施可能だが、途中で介入できない。 ✓ Amazon Q CLIとのやり取りの会話履歴がSubagent内に閉じる。 ✓ 指示が完璧でないと手戻りが発生し易い。 amazon-q-agent {指示文}
8. Skills 利用の場合の動作 途中で追加指示や修正ができるが、会話履歴をClaude Code側で管理必要 amazon-q-skill {指示文}
9. MCP Server 利用の場合の動作 ✓ Claude Code側から見るとSkillsと同じ様な動作となる。 ✓ （私にとっては） MCP Serverの構築コストが高い。 amazon-q-cli MCPサーバーを 使って以下を実施して {指示文}
10. 結果 どのケースでも真因に辿り着けてはいる “アサーションは数値演算エラー(NaN: Not a Number、または負の無限大)を検出 しています。” Skills MCP Server Subagent 今回のケースは比較的シンプルだからかもしれない
11. 比較 自動化優先 → Subagent 柔軟性・対話性優先 → Skills 統合管理・構造化優先 → MCP Server デプロイ系のタスクだと Subagentの方が使い 易いかもしれない、、
12. 結論 あくまで今回のユースケースにおいてはということで、、 迷った時は Skills から始める! 基本方針 •AI対話での情報取得: Skills使用 •必要に応じて: MCP Server(カスタム) •例外的に: Subagent(長時間バッチ) •補完的にAWS CLI直接実行: AWS CLI MCP 各パターンは併用可能!状況に応じて使い分け
13. 注意点①リスク • Amazon Q CLIはデフォルトで実行コマンドごとにユーザーに承認を求める設定になっ ている。これだと上手く動作しない。以下で実行する必要がある。 `--no-interactive`: 対話モードを無効化（自動実行） `--trust-all-tools`: すべてのツール使用を自動許可（確認プロンプトなし） Amazon Q CLIを直接使うよりも、AWS環境を壊すリスクは一定上がる
14. 注意点②会話履歴保持 • Amazon Q CLIを実行する度に新たなセッションが立ち上がる。 そためAmazon Q CLI側では会話履歴を保持しない。 Claude Code側で会話履歴を保持して、それを踏まえて 次回Amazon Q CLIへ指示出しする必要がある。
15. Thank You! Questions?
16. 3パターン比較表の各特性の詳細説明 1. 自動化度 - 意味: ユーザーが指示を出した後、どの程度自動的に処理が進むか - 高（完全自動）: 一度指示したら最後まで自動実行される - 中（対話的）: 途中でユーザーの判断・指示が必要 - 中（構造化対話）: ユーザーの指示が必要だが、ツールが構造化されている 2. 実行制御 - 意味: 実行の流れを誰が主導するか - Agent主導: Subagentが自律的に判断して実行 - User主導: ユーザーが各ステップを指示 - User主導(Claude経由): ユーザーが指示→Claude Codeがツールを選択・実行 3. 会話継続性 - 意味: 同じコンテキストで会話を続けられるか - なし: 各実行が独立（前回の会話を記憶しない） - あり: 前回の会話を踏まえて続けられる
17. 3パターン比較表の各特性の詳細説明 4. 会話履歴保持 - 意味: 会話履歴がどこで管理されるか - AWS Q CLI独自管理: AWS Q CLIが内部で履歴を保持（Claude Codeとは独立） - なし: MCPツール呼び出しは状態を持たない（各実行が独立） 5. エラー対処 - 意味: エラー発生時に誰が対処方法を判断するか - Agent判断: Subagentが自動的にリトライや代替手段を試す - User判断: ユーザーがエラー内容を見て次の指示を出す 6. 実行速度 - 意味**: タスク完了までにかかる時間 - 遅い（5-10分）: Subagentの思考・試行錯誤を含む - 速い（3-5分）: 直接CLIを実行するため高速 - 中（実装依存）: MCPツールの実装品質次第
18. 3パターン比較表の各特性の詳細説明 7. トークン消費 - 意味: AI処理に使用するトークン量（コスト） - 大: Subagentの内部思考プロセスを含む - 小: 必要最小限のコマンド実行のみ - 中: 構造化されているが、ある程度の処理が必要 8. 柔軟性 - 意味: 想定外の状況への対応能力 - 低: 事前定義された処理のみ - 高: ユーザーが状況に応じて柔軟に指示変更可能 - 中: 構造化されているが、ツール定義の範囲内で対応 9. デバッグ性 - 意味: 問題発生時の原因特定のしやすさ - 低: Subagentの内部処理が見えにくい - 高: 各ステップの実行結果が明確 - 中: ツール実行ログは見えるが、内部ロジックは隠蔽
19. 3パターン比較表の各特性の詳細説明 10. 複数ツール統合 - 意味: 複数のAWSツールを組み合わせる容易さ - 困難: Subagentに複雑な指示を出すのが難しい - 手動: ユーザーが手動で各ツールを順番に実行 - 容易: MCPツールとして統合管理可能 11. セットアップ - 意味: 使い始めるまでの準備作業 - 不要: すぐに使える - 要（開発必要）: TypeScript/JavaScriptでMCPサーバー実装が必要 12. 推奨度 - 意味: どのような場面で推奨されるか - 特定ケース: 定型タスクや完全自動化が必要な場合 - 一般的推奨: 多くの場面で推奨される汎用的な方法 - カスタム統合時: 複数ツール統合やエンタープライズ利用時
20. Subagent が適切なケース 以下の条件のすべてに該当する場合 •タスクが完全に定型化されている •途中判断がほぼ不要 •長時間実行(10分以上) •大量データの自動処理 •ユーザーは結果だけ知りたい •自己完結型タスク •定期的なバッチ処理 Amazon Q Developer CLIには基本的に不向き
21. Skills が適切なケース •EKS/Kubernetes情報収集 •トラブルシューティング •探索的調査 •段階的な意思決定 具体例 "EKSクラスターの情報を調査して" 1. クラスター基本情報 → VPC ID取得 2. サブネット情報 → タグ確認 3. セキュリティグループ → 設定確認 各ステップで方向転換可能!
22. 判断フローチャート Step 1: 何を実行するか? AWS CLIコマンド実行 → AWS CLI MCP AI対話で情報取得 → Step 2へ Step 2: Claude統合が必要か? YES → Step 3へ | NO → スタンドアロンCLI Step 3: タスクの性質は? 情報取得・調査 → Skills 大量バッチ → Subagent | 複数ツール統合 → MCP Server
23. 推奨ワークフロー フェーズ1: 調査(AI対話) → Skills で情報収集 → トラブルシューティング → 必要な操作を特定 フェーズ2: 実行(直接操作) → AWS CLI MCP で設定変更 → リソース作成/削除 → 権限確認付き実行 フェーズ3: 検証 → Skills で状態確認 → 結果の評価