Amazon Q Developer本番運用Vol1｜IDE・CLI・コードレビュー

1. この記事について — Amazon Q Developer を開発現場の本番戦力にする

Amazon Q ファミリーは「AI アシスタント」という括りで語られることが多いですが、それぞれのサービスが解決する課題は大きく異なります。本記事を読み進める前に、4 つのサービスの棲み分けを整理しておきます。

本シリーズ（Q Developer 本番運用）は上記表の 1 行目、「開発者のコーディング生産性向上」 に特化したシリーズです。社内ナレッジ検索（Q Business）や基盤モデル構築（Bedrock）とは検索意図が完全に異なりますので、目的に合わせてシリーズを使い分けてください。

1-1. 本記事のゴール

本記事を読み終えた時点で達成できる状態を具体的に説明します。

まず IDE 側では、VS Code または JetBrains に Amazon Q Developer 拡張をインストールし、インラインコード補完・チャットパネル・エージェントコマンドが日常開発の手順として定着した状態を目指します。拡張の設定は AWS Builder ID または IAM Identity Center のどちらかで完了し、チームメンバー全員が同じプロファイルで起動できるようになります。

CLI 側では、q chat コマンドがターミナルから使えるようになります。単なるチャットに留まらず、ローカルファイルの読み書きや AWS リソースへの照会をエージェントが代行し、対話的にコードを生成して承認を求めるワークフローを日常化できます。

品質確保の面では、コードレビューコマンドとセキュリティスキャン機能を使い、PR 単位・コミット単位でのチェックを仕組みとして組み込みます。「指摘されてから対応する」から「自動検出で事前につぶす」への転換が本 Vol1 の最大のゴールです。

コード変換については、Java のバージョンアップグレードや .NET の Linux 移植のような大規模変換に向け、LOC 見積もりとコスト計画を立てた上でエージェントを走らせる一連の手順を習得します。

1-2. 読者像

本記事は、次のいずれかの状況にある方を主な読者として想定しています。

開発者・テックリードのうち、AI コーディングアシスタントを「試験的に使ってみた」段階から「チームの開発フロー全体に組み込んだ本番稼働状態」へ引き上げたい方を想定しています。GitHub Copilot や Cursor を使ったことはあるが、AWS 環境との親和性・セキュリティスキャン・コード変換まで一貫して使えるツールを探している方にも適しています。

プラットフォームエンジニア・DevOps 担当のうち、Q Developer の組織展開（IAM Identity Center 連携・Pro ライセンスの一括割当）や CI パイプラインへのスキャン組み込みを設計したい方も対象です。個人が使い始めるのではなく、複数チームへの展開と運用管理を担当する立場の方に向けて、組織展開の手順を詳しく解説します。

前提とする知識は、AWS コンソールの基本操作と VS Code または JetBrains の利用経験です。Lambda・IAM・S3 などの AWS 基本サービスの理解があると、エージェント機能でのリソース照会の例が理解しやすくなります。機械学習やモデルの詳細知識は不要です。

1-3. 本シリーズの位置づけと既存記事との棲み分け

Amazon Q Developer については、当ブログの「Bedrock 生成AIアプリ層 本番運用編 Vol2」ですでに他のサービスとともに紹介しています。あの記事では Q Developer・Q Business・Bedrock Data Automation・カスタムモデルを横断的に概観し、「どんなサービスか（what）」を解説しています。

本シリーズはその続きとして、Q Developer 単体に絞り、「どう本番運用するか（how）」の実装粒度まで掘り下げます。概観は既存記事に任せ、本シリーズは実運用の判断軸と設定手順に集中します。概観をあらためて確認したい方は下のリンクをご覧ください。

本シリーズの軸は「開発者生産性の向上」であり、「インフラ構築」や「機械学習」とは別軸です。AWS DevOps・CI/CD シリーズとの違いは、「パイプライン自体の設計」ではなく「開発者の手元でのコーディング支援と品質自動化」にあります。Q Developer を組み込む先のパイプラインについては DevOps シリーズをご参照ください。

概観編：Bedrock 生成AIアプリ層 Vol2（Q Developer/Business 概観）を読む

1-4. Amazon Q Developer が変える開発生産性 — 公式実績データ

Amazon Q Developer の導入効果について、AWS が公開している実績データをもとに整理します。

コーディング速度の向上

AWS の調査によると、Amazon Q Developer を活用した開発者は、サポートのない状態と比較して コーディングタスクを平均 57% 速く完了 できることが報告されています。特に、インラインコード補完とエージェント機能（/dev）の組み合わせにより、定型的な実装（CRUD 処理・テストコードのひな形・エラーハンドリングの追加）が大幅に加速します。

テスト生成の効率化

/test コマンドを使用すると、既存の実装コードからユニットテストのひな形を自動生成できます。ゼロからテストを書く工数を削減し、カバレッジ向上に必要な追加テストケースの洗い出しを支援します。生成されたテストをそのまま使用できるわけではありませんが、テスト設計の出発点として活用することで、テスト作成にかかる時間を大幅に短縮できます。

セキュリティ脆弱性の早期検出

コードレビューとセキュリティスキャン機能の組み合わせにより、AWS が定義する OWASP Top 10 相当の脆弱性 や AWS の設定ミスをコーディング段階で検出できます。開発プロセスの早い段階（シフトレフト）で問題を発見・修正することで、本番障害や後工程での修正コストを削減します。秘密情報の誤コミット（Secrets Scan）や IaC の設定ミス（IaC Scan）も同様に自動検出の対象です。

コード変換の規模感

Java のバージョンアップグレード（例：Java 8 → Java 17/21）では、Q Developer の変換エージェントが LOC 単位で自動変換を実施します。Pro tier では 1 ユーザーあたり月次 LOC 枠が設けられており、大規模な移行プロジェクトを計画的に分割実行できます。

1-5. Vol1 のロードマップ — 各章の概要

本記事の各セクションで扱う内容を事前に把握しておくと、目的に合わせて必要な章から読み始めることができます。

各セクションは独立して読めるよう構成しています。すでに VS Code への拡張インストールを完了している方は §3 から、CI/CD への統合設計が目的の方は §5〜§6 から読み進めることを推奨します。

Free tier と Pro tier の機能差も読み進める際の参考になります。Free tier でも大半の機能を試用できますが、Pro tier では以下の主要項目の利用上限が変わります。

個人の学習・評価用途であれば Free tier で十分対応できますが、チームへの組織展開や CI/CD パイプラインへの組み込みを想定する場合は Pro tier の採用を推奨します。料金・最新の上限値については AWS 公式のドキュメントを参照してください。

本記事では §2 で tier の選択判断基準を詳しく解説します。読み進める前に、自分のユースケースが「個人評価」なのか「チーム展開」なのかを意識しておくと、各セクションの実装判断がより明確になります。

以上が、本記事を通じて得られる全体像です。

2. 前提・サブスクリプション設計・IDE/CLI セットアップ

2-1. 前提環境

Amazon Q Developer を本番利用するにあたって必要な前提環境を整理します。

AWS アカウント

個人利用（Free tier）の場合、AWS アカウントは不要です。AWS Builder ID を取得するだけで利用を開始できます。ただし、Pro tier への昇格・組織展開・IAM Identity Center 連携・コード変換機能の利用を予定している場合は、AWS アカウントが必要です。

アイデンティティの選択肢

Amazon Q Developer では認証に 2 つの方式を選択できます。

Builder ID は即時作成でき、Free tier でのコード補完・q chat が使えます。IAM Identity Center は組織内の全開発者に一括で Q Developer を展開し、Pro ライセンスを割り当てる際に必要です。

対応 IDE

Q Developer の IDE 統合プラグインは次の IDE を正式サポートしています。

• Visual Studio Code（VS Code）1.75 以降
• JetBrains IDE 2023.1 以降（IntelliJ IDEA・PyCharm・WebStorm・GoLand・Rider・DataGrip・CLion など主要 IDE を網羅）
• Amazon SageMaker Studio・JupyterLab（データサイエンス用途）

CLI（Amazon Q CLI）

q コマンドは macOS・Linux・WSL2 をサポートしています。

• macOS: Homebrew または dmg インストーラで導入
• Linux: シェルスクリプト 1 行または各ディストリビューションのパッケージマネージャ
• Windows: WSL2 経由（ネイティブ Windows は 2025 年時点でパブリックプレビュー）

ネットワーク要件

Q Developer の IDE 拡張・CLI ともに、*.amazonaws.com への HTTPS アウトバウンド接続が必要です。プロキシ環境下では IDE の HTTP プロキシ設定または環境変数（HTTPS_PROXY）の設定が必要になります。

2-2. サブスクリプション tier 設計（Free / Pro）

Amazon Q Developer には Free tier と Pro tier の 2 段階があります。それぞれの機能差を理解し、チームへの適切な割当を設計することが重要です。

Free / Pro 機能比較

Free tier の上限を超えた場合の挙動

Free tier は各機能に月次の利用上限があります。上限に達すると、その月の残り日数はその機能が利用不可になります。月初めに自動リセットされます。コード補完は IDE のステータスバーに残回数が表示されるため、チームへの事前周知を推奨します。

コード変換の超過課金

Pro tier のコード変換は月 4,000 LOC（Lines of Code）/ユーザーが含まれます。超過分は $0.003/LOC の従量課金が発生します。例として、10,000 LOC の Java アップグレードを実施する場合、超過分 6,000 LOC × $0.003 = $18 の追加費用が発生します。大規模変換プロジェクトでは事前に LOC を見積もり、複数月への分割や必要ユーザー数の計画を立てることを推奨します。

Builder ID での Pro 昇格

2025 年 6 月時点では、Builder ID ユーザーが AWS コンソールの「Amazon Q Developer」→「サブスクリプション」から直接 Pro にアップグレードできます。クレジットカード情報を AWS アカウントに紐付けることで、組織アカウントなしで個人 Pro を利用できます。

組織展開の判断基準

チームへの展開形態は次の観点で判断します。

Builder ID vs IAM Identity Center の詳細比較

企業環境では監査ログの要件から IAM Identity Center が必須になるケースが多いです。個人利用や PoC（実証実験）段階では Builder ID から始めて、後で IAM Identity Center へ移行できます。

2-3. IDE/CLI セットアップとゴール状態

VS Code・JetBrains・CLI それぞれのセットアップ手順と、最終的なゴール状態を説明します。

VS Code 拡張のインストール

1. VS Code を開き、左サイドバーの Extensions（拡張機能）アイコンをクリックします。
2. 検索ボックスに「Amazon Q」と入力します。
3. 「Amazon Q」（発行元: Amazon Web Services）を選択し「Install」をクリックします。2025 年時点の最新バージョンをインストールしてください。
4. インストール後、VS Code を再起動します。
5. 左サイドバーまたはステータスバーに「Q」アイコンが表示されたら拡張の準備完了です。

VS Code での認証設定（Builder ID）

1. サイドバーの「Q」アイコンをクリックし、「Use with Builder ID」を選択します。
2. ブラウザが開き、AWS Builder ID のサインインページに遷移します。
3. アカウントをお持ちでない場合は「Create a free AWS Builder ID」からメールアドレスで作成します。
4. ブラウザでサインインが完了すると、VS Code に認証トークンが返却されます。
5. ステータスバーの「Q」アイコンにサインイン済みのユーザー名が表示されれば完了です。

VS Code での認証設定（IAM Identity Center）

1. 「Q」アイコンをクリックし「Use with Pro license」→「Sign in with IAM Identity Center」を選択します。
2. IAM Identity Center の「スタート URL」を入力します。管理者から提供される https://<d-xxxxxxxxxx>.awsapps.com/start 形式の URL です。
3. ブラウザでシングルサインオンが完了すると VS Code に戻ります。
4. 割り当てられた Pro ライセンスが自動的に適用されます。

JetBrains プラグインのインストール

1. IntelliJ IDEA・PyCharm 等の JetBrains IDE を開き、「Settings」→「Plugins」→「Marketplace」を開きます。
2. 「Amazon Q」で検索し、「Amazon Q」プラグイン（発行元: Amazon Web Services）をインストールします。
3. IDE を再起動します。
4. 右側のツールウィンドウに「Amazon Q」タブが表示されたらインストール完了です。

認証手順は VS Code と同様です。「Amazon Q」タブからサインインを実行します。

CLI（q コマンド）のインストール

macOS で Homebrew を使う場合:

brew install amazon-q

macOS でインストーラを使う場合は、Amazon Q CLI の公式ドキュメントページから macOS 用 dmg をダウンロードします。dmg を開いてアプリケーションフォルダにドラッグし、ターミナルで q --version を実行してバージョンが表示されれば完了です。

Linux の場合:

curl --proto '=https' --tlsv1.2 -sSf https://install.amazonaws.com/q | sh

インストール後、q --version でバージョンを確認します。

CLI の認証設定

q login

コマンドを実行するとブラウザが開き、Builder ID または IAM Identity Center でのサインインを選択できます。サインイン完了後、ターミナルに「Successfully logged in」と表示されれば認証が完了しています。

IAM Identity Center での組織展開

チームへの一括展開は次の手順で実施します。

1. IAM Identity Center の有効化: AWS Organizations 管理アカウントの IAM Identity Center コンソールで有効化します。既に有効化済みの場合はスキップします。
2. ユーザー・グループの作成: IAM Identity Center コンソールで開発者ユーザーを登録します。Active Directory や Okta と連携している場合は自動同期を設定します。
3. Q Developer のプロビジョニング: AWS コンソールの「Amazon Q Developer」→「サブスクリプション」→「組織からユーザーを割り当て」を選択します。
4. ユーザーまたはグループの選択: Pro ライセンスを割り当てるユーザーまたはグループを選択します。
5. 割り当ての確認: 割り当てられたユーザーには IAM Identity Center のメール通知または管理者からの連絡でスタート URL を共有します。

プロファイル設定と切り替え

複数の AWS アカウントや複数のサブスクリプション（例: 個人 Builder ID と会社 IAM Identity Center）を使い分ける場合は、プロファイル設定を利用します。

q profile list # 利用可能なプロファイルを一覧表示
q profile switch  # インタラクティブにプロファイルを選択して切り替え

VS Code では、Q アイコンの「Switch Account」からプロファイルを切り替えられます。組織で複数のサブスクリプションを使う場合（例: 開発環境用・本番環境用）は、プロファイルをあらかじめ設定しておくことで混乱を防げます。

セットアップのゴール状態確認

次のコマンドで CLI の動作確認を行います。

q --version
q chat "Hello"

q chat の応答が返ってきたら CLI 統合が正常に機能しています。VS Code では、エディタで任意のコードファイルを開き、インラインにカーソルを置いた状態でコード補完が発動することを確認します。

この状態（IDE と CLI の両方で認証済み・応答確認済み）が §2 のゴール状態です。§3 以降で、この環境を使った具体的な開発ワークフローへの組み込み方を解説します。

セットアップ後の推奨確認事項

セットアップが完了したら、次の点を確認しておくことを推奨します。

• IDE のステータスバーに Free tier の残回数が表示されている（Pro tier では「無制限」と表示される）
• q chat で AWS リソースの照会が可能か確認する（例: q chat "現在のリージョンを教えてください"）
• チームメンバー全員が同じプロファイルでサインインできることを確認する

これらの確認を済ませておくと、§3 以降のエージェント機能や品質チェックの手順をスムーズに進められます。

3. IDE/CLI 統合 — VS Code・JetBrains・コマンドライン

3-1. IDE 統合(VS Code / JetBrains)

Amazon Q Developer の IDE 統合は、VS Code と IntelliJ IDEA をはじめとする JetBrains 製品向けの拡張機能として提供されています。拡張機能をインストールして Builder ID または IAM Identity Center でサインインすると、エディタのサイドバーにチャットパネルが表示され、コーディング中のあらゆる場面で Q Developer へ問い合わせられるようになります。

インラインコード補完の精度とコンテキスト設定

最も日常的に活用できる機能がインラインコード補完です。コードを入力していると Q Developer がカーソル位置の後続コードを自動的に提案し、Tab キーで確定できます。補完の精度を高める上で重要なのが、ワークスペース全体をコンテキストとして活用させることです。

VS Code の場合、設定画面で「Workspace context」を有効にすることで、開いているファイルだけでなくプロジェクト全体の型情報・インポート関係・命名規則を参照した補完が得られます。JetBrains では、プラグイン設定の「Workspace context」チェックボックスを有効にします。ワークスペース参照が有効な状態では、プロジェクト固有のユーティリティ関数やカスタム型を使った補完が提案されるため、補完後の手修正が大幅に減少します。

AWS の公式情報によれば、ワークスペースコンテキストを有効にした開発者は、単一ファイル参照の補完と比較して受け入れ率(acceptance rate)の向上が報告されています。コードの文脈整合性が高まることで、型エラーに起因する手直しが減り、レビュー工数の削減につながります。

チャット機能と @workspace / @file コンテキスト指定

VS Code のチャットパネルでは、メッセージに @workspace を付けることでリポジトリ全体を対象にした質問ができます。たとえば「@workspace の認証フローはどこで処理していますか？」と入力すると、該当するファイルとコードパスを特定して回答します。特定のファイルだけを対象にしたい場合は @file:src/auth/handler.ts のようにファイルパスを指定します。

JetBrains では、チャットウィンドウの「+」アイコンからコンテキストに追加するファイルを選択します。複数ファイルをコンテキストとして加えることで、「この2ファイル間のインターフェース整合性を確認してください」といった横断的な問い合わせが可能になります。

会話履歴はチャットセッション内で保持されます。一連のリファクタリング作業を会話として積み重ねることで、前の指示を踏まえた続きの変更を依頼できます。セッションをまたいで文脈を引き継ぎたい場合は、変更の要約を新しいセッションの冒頭で提示するのが実用的です。

補完とチャットを組み合わせた活用の流れとして、まずチャットで設計方針・インターフェース定義を相談し、骨格を固めた後でインライン補完によりコードの中身を埋めていく方法が生産性の観点で有効です。補完はリアルタイムに動作し、チャットでの会話コンテキストとは独立しているため、両機能を用途に応じて使い分けることが重要です。

VS Code と JetBrains の機能差と使い分け

両 IDE のプラグインは共通の機能セットを提供しますが、統合の深さに若干の差があります。VS Code では、@workspace コンテキスト指定をチャットパネルから直接入力できる点と、Inline Chat によるエディタ内への直接挿入の利便性が特徴です。JetBrains 系では、コード補完エンジンとの親和性が高く、補完候補はエディタの補完ドロップダウンに自然に統合されます。

どちらの IDE を選んでも、Amazon Q Developer の中核機能(インライン補完・チャット・エージェントコマンド)は同等に利用できます。チームで IDE が混在している場合は、エージェント定義ファイルとカスタムプロンプトをリポジトリで共有することで、環境に関わらず一貫したコーディング支援体験を確保できます。

また、どちらの IDE でも「実行中のコードを選択してチャットに送る」操作が数クリックで行えます。テストが失敗したコードブロックを選択して「なぜこのコードが失敗するか教えてください」と送ると、選択範囲のコンテキストをもとに原因の仮説と修正案を返してくれます。エラー診断から修正コードの提案、適用までをエディタ内で完結できるため、デバッグのコンテキストスイッチを最小化できます。

生産性向上の実践パターン

日常的な開発サイクルに Q Developer を組み込む際には、以下のパターンが実績のあるアプローチです。

• 新規実装前の相談: 実装を始める前にチャットで設計の妥当性を確認します。「この方針で実装する場合の潜在的な問題点は？」と問うことで、着手前にリスクを洗い出せます。
• コードレビュー依頼: コミット前にチャットへ diff を貼り付け、「このコードの改善点を指摘してください」と依頼します。小さな修正はその場でインライン補完を使って即時適用できます。
• デバッグの壁打ち: エラーメッセージとスタックトレースをチャットに貼り付けて原因の仮説を立てます。コードベースのコンテキストが加わることで、プロジェクト固有の設定が原因のエラーも特定しやすくなります。

IDE 統合を最大限に活用するには、補完とチャットを片方だけ使うのではなく、両機能を組み合わせたワークフローに慣れることが大切です。補完は速度を、チャットは精度を担当すると考えると役割が明確になります。Pro tier では補完とチャットの両方がより高い上限で利用でき、大規模なコードベースや長いセッションでも安定したコーディング支援が継続します。

導入初期には補完機能だけを数日間試し、その後チャット機能を加えるという段階的な使い始め方が定着しやすいです。すべての機能を一度に使おうとすると操作に慣れるコストが高くなるため、まずインライン補完の受け入れ基準を自分なりに整理した後でチャットを活用していくと、自然に使いこなせるようになります。

3-2. CLI の agentic 体験(q chat / カスタムエージェント)

CLI の q chat は、Amazon Q Developer をターミナルから直接操作する対話型インターフェースです。IDE との最大の違いは、ローカルファイルの読み書きと AWS リソースへの照会を組み合わせた反復的なコード生成が一つの会話の流れで完結する点にあります。IDE を開かずにターミナル作業をしている場面でも、Q Developer の支援を継続的に受けられます。

q chat の基本フロー

ターミナルで q chat を実行するとプロンプトが表示され、自然言語で指示を入力できます。たとえば「このプロジェクトの Lambda 関数に設定されているアラームを一覧してください」と入力すると、Q Developer は AWS CLI を実行してアカウントのリソース情報を取得し、結果を整形して返答します。

コード生成では「src/handlers/user.py の findUser 関数に DynamoDB のキャッシュ層を追加してください」と指示すると、Q Developer は対象ファイルを読み込み、差分を提示した上で「適用しますか？」と確認を求めます。確認後、ファイルが直接更新されます。このように指示 → 差分確認 → 承認のサイクルを繰り返しながら変更を積み重ねるのが q chat の agentic ワークフローです。

AWS リソースの照会では、Lambda の最新デプロイ状況・S3 バケットの設定・ECS タスクの稼働状態など、開発中に頻繁に参照するリソース情報をコンソールへ移動せずに確認できます。ローカル作業とクラウドリソースの確認を同一ターミナルで完結できる点が、開発速度の向上につながります。

カスタムエージェント(.json)の切り替え

q chat --agent <エージェント名> で、あらかじめ定義したカスタムエージェントに切り替えられます。カスタムエージェントは JSON ファイルで動作スコープ・指示・利用可能なツールを定義します。代表的な用途は以下のとおりです。

• code-reviewer: レビュー観点(可読性・パフォーマンス・品質基準)を事前定義し、差分ファイルを渡すとレビューコメントを生成します。
• documentation-writer: 対象ファイルの関数シグネチャを読み取り、docstring・README セクション・API ドキュメントを自動生成します。
• test-helper: テスト対象のモジュールを受け取り、ユニットテストのひな形とカバレッジ計画を作成します。

カスタムエージェントを使うことで、チームのコーディング規約やドキュメント標準を事前に組み込んだ専用アシスタントを整備できます。新しいメンバーへの onboarding や、繰り返し発生するレビュー作業の標準化に有効です。エージェント定義ファイルをリポジトリに含めることで、チーム全員が同一の設定を共有できます。

q chat は AWS リソース照会の場面でも特に力を発揮します。「現在のリージョンで実行中の ECS タスク一覧を教えてください」「この S3 バケットのバージョニング設定を確認してください」といった問い合わせを自然言語で行うと、Q Developer が適切な AWS CLI コマンドを組み立てて実行し、結果を整形して返答します。開発中のトラブルシューティングで必要になるリソース状態の確認を、コンソールとターミナルを行き来せずに完結させられるのは実務上の大きな利点です。

q chat のセッションは継続的な作業に対応しており、途中でローカルファイルの編集や AWS リソースの確認をはさみながら会話を続けられます。長時間のコーディングセッションでも文脈が維持されるため、複雑な実装タスクを段階的に進める際に有効です。セッションを終了する場合は exit または quit を入力します。再開時は前回の作業内容を簡単に要約してから指示を出すと、スムーズに続きの作業に入れます。

4. エージェント機能 — 実装・テスト・ドキュメント生成

4-1. 機能実装エージェント(/dev)とテスト生成(/test)

/dev — 自然言語から複数ファイル横断コード生成

/dev コマンドは、IDE のエージェントパネルまたは CLI チャット内で利用できる機能実装エージェントです。自然言語で「ユーザー管理モジュールに招待リンク送信機能を追加してください」と指示すると、Q Developer はリポジトリ内の関連ファイルを走査し、変更が必要なファイルを特定した上で、複数ファイルにまたがる差分をまとめて提示します。

実際の実行フローは次のとおりです。

1. 指示の入力: 機能の仕様を自然言語で記述します。参照してほしいファイルを明示することで精度が向上します。
2. 実装計画の提示: Q Developer はまず変更する予定のファイル一覧と変更概要を提示します。この段階でスコープの修正を依頼できます。
3. 差分の確認: 各ファイルの差分が表示されます。IDE の場合は diff ビューで変更前後を並べて比較できます。
4. 承認と適用: 内容に問題がなければ「承認」を選択してファイルへ書き込みます。一部だけ適用・却下もできます。
5. 反復修正: 「この部分のエラーハンドリングを強化してください」のように続けて指示を出し、差分を積み重ねます。

複数ファイル横断変更の制御では、変更範囲が広がりすぎないよう指示を機能単位に分割するのがベストプラクティスです。「認証とメール送信を同時に追加してください」といった多機能一括指示は差分が膨大になり、承認の判断が困難になります。1指示につき1機能単位を目安にすると、承認フローを適切に機能させられます。

大規模リファクタリングで差分ファイル数が多い場合、Q Developer は一部を省略することがあります。この場合はスコープを絞るか「まず〇〇モジュールだけ変更してください」と段階的に指示します。

/test — ユニットテスト自動生成とカバレッジ向上

/test コマンドは、既存のコードを対象にユニットテストを自動生成します。テスト対象のファイルまたは関数を指定して実行すると、Q Developer はコードの構造・インターフェース・想定エラーケースを解析し、対応するテストケースのひな形を生成します。

生成されるテストには以下の要素が含まれます。

• 正常系テスト: 期待される入力と出力のケース
• 境界値テスト: 空文字・ゼロ・最大値・最小値など
• 異常系テスト: 不正な引数・例外スロー・外部リソース不在のケース

生成されたテストはそのまま実行できる状態で提示されますが、外部サービスのモック詳細やテストデータは実際のプロジェクト仕様に合わせた補完が必要です。特にデータベースや外部 API への依存をモックする部分は、生成コードの意図を確認してから採用するのが安全です。

カバレッジ向上のプロセスとして、現在のテストカバレッジレポートを Q Developer のチャットに貼り付けて「カバレッジが低い箇所のテストを追加してください」と指示する方法が実用的です。レポートの数値を参考にしながら、追加すべきテストケースをピンポイントで生成できます。

複数の関数をまとめてテスト化したい場合は「src/services/order.py の全関数のテストを作成してください」と指定します。ただし、ファイルが大きい場合はセクション単位に分割して依頼する方が、生成されるテストの精度が安定します。

4-2. ドキュメント生成(/doc)とカスタムエージェント

/doc — コメントと API ドキュメントの自動生成

/doc コマンドは、コードのコメント・docstring・README セクション・API ドキュメントを自動生成します。対象のファイルまたは関数を指定すると、Q Developer はコードのロジックを解析して適切なドキュメントを生成します。

利用シナリオごとの活用方法は以下のとおりです。

関数 docstring の生成: 関数シグネチャとボディを読み取り、パラメータの説明・戻り値・例外・使用例を含む docstring を生成します。Python の場合は Google スタイルと NumPy スタイルを指定できます。Java では Javadoc 形式、TypeScript では JSDoc 形式で出力されます。

モジュール README の生成: モジュール全体のエントリーポイント・公開 API・使用手順を含む README セクションを生成します。「src/auth/ モジュールの README セクションを生成してください」と指示します。新規開発者が参照するドキュメントのひな形を素早く用意できるため、onboarding コストの削減に有効です。

API ドキュメントの生成: REST API のルーティングファイルから、エンドポイント一覧・リクエスト/レスポンスの形式・認証要件を記述した API ドキュメントのひな形を生成します。OpenAPI/Swagger 形式での出力も指定できます。

生成されたドキュメントは、プロジェクトのドキュメント規約と照合して内容を確認した上で採用します。特に「エラーケース」や「非推奨の警告」はコードから自動推論しにくい場合があるため、手動で補足することが実践的です。

カスタムエージェントの定義と用途特化

カスタムエージェントは JSON 形式の設定ファイルで定義します。定義ファイルには、エージェントの名前・説明・利用可能なツールのスコープ・デフォルトのシステムプロンプトを記述します。

{
  "name": "code-reviewer",
  "description": "品質と可読性を重点にコード差分をレビューします",
  "tools": ["read_file", "list_directory"],
  "systemPrompt": "あなたは経験豊富なシニアエンジニアです。提示されたコード差分を品質・可読性・パフォーマンスの観点で評価し、具体的な改善案とともに指摘してください。"
}

この設定で q chat --agent code-reviewer を起動すると、毎回同じレビュー観点でコードを評価できます。

複数エージェントの使い分けの例:

• 開発フェーズ: --agent implementation-helper(実装支援・コンテキスト重視)
• PR 作成前: --agent code-reviewer(品質・可読性観点でのレビュー)
• リリース前: --agent doc-generator(ドキュメント更新の確認と生成)

チームで共通の .q/agents/ ディレクトリにエージェント定義を管理し、リポジトリへコミットすることで、全メンバーが統一されたエージェントを利用できます。

エージェント実行のベストプラクティスと詰まりポイント

指示の粒度: エージェントが一度に処理できるコンテキスト量には上限があります。大規模なファイル群を一括で渡すより、変更対象を 3〜5 ファイル程度に絞って指示する方が、精度と処理速度の両面で有利です。

承認を忘れない: q chat でのエージェント実行では、変更の適用前に必ず承認ステップが挟まります。ターミナルが別ウィンドウにある場合、気付かず放置されることがあります。エージェントが待機中のまま停止しているように見える場合は、ターミナルの出力を確認して承認プロンプトに応答してください。

コンテキスト不足への対処: 「コンテキストが不足しているため正確な実装が困難です」という旨の応答が返ってきた場合は、参照してほしいファイルを明示的に指定するか、変更スコープを絞って再度指示します。関連するインターフェース定義ファイルや設定ファイルをコンテキストに追加するだけで、精度が大幅に改善する場合があります。

大規模変更の分割: 多数のファイルにまたがるリファクタリングや、アーキテクチャレベルの変更を一括で依頼するのは避けます。まずインターフェース定義の変更 → 実装ファイルの更新 → テストの更新 → ドキュメントの更新 という段階に分割し、各ステップの差分を確認しながら進める方が失敗リスクを低減できます。一度に適用する差分が小さいほど、レビューの精度が上がり、問題発生時の切り戻しも容易です。

エージェント機能の活用サイクル

エージェント機能を開発フローに定着させるには、タスクの種類に応じてコマンドを使い分ける習慣を整備することが重要です。以下のサイクルを参考に、チームの開発プロセスに組み込んでください。

• スプリント開始時: タスクチケットの要件を /dev に渡して実装計画とファイル一覧を生成し、実装コストの見積もりに活用します。
• 実装中: 既存テストの網羅率を確認しながら /test でカバレッジを補完します。テスト追加と実装変更を交互に繰り返すことで、変更の影響範囲を常に把握できます。
• レビュー前: /doc でコメントとインターフェースドキュメントを整備し、レビュアーの読解コストを下げます。ドキュメントの空白が少ない状態でレビューを受けることで、ロジック中心のフィードバックが得やすくなります。

このサイクルを繰り返すことで、コードの品質・テスト網羅率・ドキュメント整備を並行して向上させる開発リズムが定着します。

5. コードレビュー(/review) — 脆弱性と品質の継続的チェック

5-1. レビューの実行と重大度(severity)分類

Amazon Q Developer の /review コマンドは、コードベース全体または単一ファイルを対象にコードレビューします。IDE のチャットパネルに /review と入力するだけで解析が開始され、数十秒から数分程度で結果が表示されます。ターミナルから利用する場合は q review コマンドを使います。

人手のレビュワーが担うべき高付加価値な作業(設計の妥当性や要件との整合)へ集中できるよう、機械的に検出できる問題をあらかじめ除去する役割を /review が担います。コードを書いた直後からフィードバックを受け取れるため、問題を記憶の新しいうちに対処できます。

レビュー対象の指定方法

コードベース全体を対象にする場合は /review とだけ入力します。プロジェクトのソースツリーを一括で走査するため、PR を出す直前の最終確認や定期チェックに向いています。

特定のファイルに絞る場合は /review src/payment/processor.py のようにパスを指定します。大規模リポジトリで変更した箇所だけを素早く確認したいときに有効です。現在エディタで開いているファイルを対象にする場合は、ファイルパスを省略するとアクティブなファイルが自動的に選ばれます。

スキャン完了後は results パネルに finding の一覧が表示されます。各 finding にはファイル名・行番号・問題の説明・修正案が含まれており、finding をクリックすると問題のあるコードにジャンプできます。

findings の件数はプロジェクトの規模や過去の対処状況によって異なります。初回スキャン時に大量の findings が出た場合でも、重大度の高い順に着手することで効率的に品質を引き上げられます。レビュー対象をリポジトリのルートではなく主要なソースディレクトリに絞ることで、スキャン時間を短縮できます。

重大度(code issue severity)による 4 段階分類

重大度は finding ごとに個別に判定されます。

レビュー結果は以下の 4 段階の重大度で分類されます。各段階の意味を理解することで、チームが finding にどの優先度で対処するかを統一した基準で判断できます。

• CRITICAL: 本番環境で即座に重大な問題を引き起こす可能性がある課題です。リリース前に必ず修正し、見つかった時点で最優先に着手します。
• HIGH: 特定の条件下で深刻な動作不良につながる課題です。スプリント内での対処を強く推奨します。テスト環境での再現が難しい問題でも、放置しないことが重要です。
• MEDIUM: コードの保守性や信頼性に影響する課題です。技術的負債が蓄積する前に計画的に対処することで、将来の修正コストを削減できます。次のリファクタリングサイクルに組み込むのが現実的です。
• LOW: ベストプラクティスとの乖離や軽微なスタイル上の問題です。優先度を下げて別チケットで管理し、コーディング規約の整備と合わせて対処します。

Amazon Q Developer はデフォルトで重大度の高い順に findings を並べて表示します。出力を上から順に処理するだけで、自然と優先度の高い課題から着手できます。

チームで運用する際は、CRITICAL の findings をリリースブロッカーとして扱い、HIGH は翌スプリント対応、MEDIUM/LOW は技術的負債バックログに積む運用が継続しやすいです。各 severity への対処期限を SLA として定めておくことで、放置 finding が積み重なることを防げます。

セキュリティ課題と品質課題の区別

検出された課題はカテゴリ別にラベル付けされます。コードのリスクに関わる findings と、コードの品質・保守性に関わる findings が区別されて表示されるため、担当チームへの振り分けがスムーズになります。

DevSecOps プロセスが整備されているチームでは、リスク関連の findings のみを専任チームへ自動ルーティングし、品質関連は開発チームが自己完結して対処する分担が多く採用されています。この分担により、それぞれの専門チームが自分の領域に集中できます。

5-2. findings への対応と修正適用フロー

/review が返す各 finding には、問題の説明・影響のある行・修正案がセットで提示されます。修正案はコード差分の形式で表示されるため、提案内容を確認してそのまま適用できます。

修正適用の 3 ステップ

1. Finding の確認: 対象の finding を選択し、問題箇所と修正案を照合します。説明文に記載された「なぜ問題なのか」を理解してから進むと、誤った方向での適用を防げます。
2. 提案の適用: IDE パネルの「Apply fix」ボタン(または差分のコピーと貼り付け)で修正を適用します。一括適用と個別適用を切り替えられます。確実に内容を確認しながら進めたい場合は個別適用を選んでください。
3. 再レビューによる確認: 修正後に再度 /review を実行し、finding が解消されたことを確認します。修正の影響で別の箇所に新たな問題が生じていないかも合わせてチェックします。

実践ワークフロー: CI 前ローカルレビューと PR 補完

コミット前のローカルでの利用では、変更差分を対象に /review を実行することで、PR を出す前に自己完結したレビューが完了します。レビュワーが受け取る PR には最初から明らかな問題が除去された状態になり、設計や実装方針の議論に集中できます。

PR レビューの補完としては、PR 作成時に自動で /review を走らせ、結果を PR コメントとして添付する CI フックを登録する方法が実績として多く見られます。自動生成された findings リストを参照しながら人手のレビュワーが判断するため、重複検査がなくなりレビュー全体のスループットが向上します。

初めてチームに導入する場合は、まずローカルでの手動実行から始め、チームが findings への対処に慣れてきた段階で CI への組み込みに移行するステップアップが円滑に進みます。ツールの導入と運用ルールの整備を並行して進めることで、形骸化を防げます。

ベストプラクティス

チームのコードレビュープロセスに /review を組み込むことで、開発者がコードを書いた直後から品質フィードバックを受け取れる環境が整います。継続的に実行することで、新たな課題の混入を防ぎながらコードベース全体の品質を段階的に向上させていけます。

findings の件数が多いプロジェクトでは、最初から全件を解消しようとすると開発速度が落ちます。CRITICAL のみを対象にした「ゼロ CRITICAL ポリシー」を最初のゴールに設定し、安定してから HIGH・MEDIUM の対処に取り組む段階的アプローチが現実的です。findings への対処を sprint goal として定期的にスケジュールすることで、放置 finding が積み上がらない運用リズムを作れます。

6. セキュリティスキャン — SAST・Secrets・IaC

6-1. スキャンの3領域(SAST / Secrets / IaC)

Amazon Q Developer のセキュリティスキャン機能は、1,000 を超える検出ルールと十数言語への対応を備えています。スキャン対象は大きく 3 つの領域に分かれており、それぞれ検出の目的と対象ファイルが異なります。3 領域を組み合わせることで、ソースコードからインフラ定義まで開発成果物全体をカバーできます。

SAST — ソースコードの静的解析

SAST(Static Application Security Testing)は、実行せずにソースコードを静的に解析し、コード品質上の潜在的な問題を検出します。Java / Python / JavaScript / TypeScript / C# / Go / Ruby など、十数言語に対応しています。

主な検出カテゴリは以下のとおりです。

• リソースリーク: ファイルハンドルやデータベース接続が解放されずに残るコードパターンを検出します。長時間稼働のサービスでは接続数の枯渇につながります。
• 入力処理の欠陥: 外部からの入力値を適切に処理していないコードパターンを検出します。HTTP リクエストパラメータや外部 API レスポンスの扱いが主な対象です。
• 出力エンコードの不備: ブラウザへのレスポンスに対してエンコードが不十分なコードパターンを検出します。フロントエンドの描画箇所が主な対象で、適切なエスケープ処理の追加を提案します。

SAST は開発の早期段階(ローカルやビルドパイプライン)で動かすことで、本番リリース前に問題を閉じられます。検出結果には問題箇所のコードハイライトと修正の方向性が示されるため、開発者が自己完結して対処できます。

Secrets Detection — コードに混入した機密情報の発見

Secrets Detection は、ソースコードやコンフィグファイルに直接記述された機密情報を検出します。コードベースに認証情報が混入しても、リポジトリにコミットする前の段階で検出できれば被害を防げます。

検出対象の例:

• 主要クラウドサービスの API キーやアクセストークン
• データベースへの接続文字列(ユーザー名・パスワードを含むもの)
• 外部 SaaS サービスのシークレットトークン
• SSH 秘密鍵やサービスアカウントのキーファイル内の機密フィールド

検出後の対処フロー:

1. 対象の認証情報を直ちに無効化します。コードを修正する前に無効化を優先してください。
2. シークレット管理サービス(AWS Secrets Manager や AWS Systems Manager Parameter Store など)へ移行します。
3. .gitignore や Git pre-commit フックで再混入を防ぐ仕組みを整えます。
4. リポジトリの履歴に機密情報が残っている場合は、履歴の書き換えも検討してください。

IaC スキャン — インフラ定義の構成確認

IaC スキャンは、Terraform や AWS CloudFormation のコードを解析し、構成上の問題を検出します。インフラのコードレビュー段階でスキャンを実行することで、デプロイ後に修正が困難な構成の問題を事前につぶせます。

検出対象の例:

• ストレージサービスへのパブリックアクセスが意図せず有効になっている構成
• 暗号化設定が無効のままのデータストアやバックアップ
• ネットワークの開放範囲が過剰になっているルール設定
• 監査ログや証跡記録が無効になっているサービス構成

コンプライアンス基準(CIS Benchmark や AWS Security Hub の標準など)との照合も行われます。IaC スキャンの findings をコードレビューのチェックリストに組み込むことで、インフラ変更のたびに構成の健全性を自動確認できます。

6-2. スキャン方式と findings 対応フロー

Amazon Q Developer のスキャン機能は 2 つの方式を提供しており、使い分けることで開発サイクル全体をカバーできます。

Scan your project — プロジェクト全体スキャン

「Scan your project」は手動で実行するスキャンです。プロジェクト全体または指定ディレクトリを一括で検査します。

主なユースケース:

• リリース前の最終チェックとして実行する
• CI/CD パイプラインの特定ステージ(PR マージ前や本番デプロイ前)に組み込む
• 四半期ごとの定期スキャンとして計画的に実施する

実行方法は IDE の Amazon Q Developer パネルから「Scan」ボタンを押すか、CLI で q security-scan --project を実行します。スキャン完了後にレポートが表示され、findings の一覧と各問題の詳細が確認できます。

Scan as you code — リアルタイムスキャン

「Scan as you code」はコードを編集するたびに自動でバックグラウンドスキャンが走るモードです。

このモードでは以下の動作になります。

• ファイルを保存するたびにそのファイルが再スキャンされます
• 新たな問題が検出されると IDE のエディタ上にリアルタイムで警告が表示されます
• 開発者はコーディングの流れを止めずに、その場で問題に気づいて対処できます

リアルタイムスキャンを常時有効にすると、開発サイクルの最も早い段階で問題を検出できます。ただし、大規模プロジェクトでは CPU 負荷が高まるケースもあるため、パフォーマンスが気になる場合はファイル単位または特定ディレクトリのみを対象にするよう設定を調整してください。

スキャン結果の読み方と優先度判断

スキャン結果を処理する際の基本的な流れは以下のとおりです。

1. severity 別フィルタリング: CRITICAL と HIGH の findings を最初に確認します。これらは対処が急がれる問題です。
2. 影響範囲の確認: finding ごとに「どのデータやリソースが影響を受けるか」を把握します。同じ severity でも影響範囲が広いものを優先します。
3. 修正の適用: 修正案に従って対処し、再スキャンで解消を確認します。
4. 受け入れまたは抑制: ビジネス上の理由でリスクを受け入れる場合は、finding に抑制コメントを付与して管理対象から外します。抑制した内容は記録を残してください。

CI/CD パイプラインへの組み込み

CI/CD に組み込む場合、典型的なパターンはビルドパイプラインの早い段階に「Scan your project」を挟み、CRITICAL/HIGH の findings が 0 件でないとマージを通さないゲートを設ける方法です。

PR が作成された時点でスキャンを実行し、結果を PR のコメントに添付するまでを自動化するフローが多くの現場で採用されています。Amazon Q Developer の CLI を使うことで、スクリプトから findings 件数を取得してゲート判定に活用できます。

パイプラインに組み込む際はスキャン対象のファイルパスを明示的に指定することをお勧めします。テストコードや自動生成されたファイルが大量にある場合、それらを除外することでスキャン時間を短縮し、本番コードの問題に集中できます。

スキャン結果をチームのダッシュボード(Security Hub や同等の管理ツール)に集約することで、findings の傾向分析や対処の進捗管理がしやすくなります。どのモジュールに findings が集中しているかを可視化することで、次の改善スプリントのターゲットを決める材料にもなります。

7. コード変換・モダナイゼーション — Java / .NET

7-1. Java バージョンアップグレード(selective transformation)

Amazon Q Developer のコード変換エージェントは、Java アプリケーションのバージョンアップグレードを半自動化します。代表的なユースケースが Java 8 から Java 17 への移行で、これまで数週間を要していた作業を大幅に短縮できます。

変換の核心となるのが selective transformation の仕組みです。コードベース全体を一括で変換するのではなく、変換対象モジュールをファイル・クラス単位で選択し、段階的にアップグレードを進めます。大規模コードベースでのリスク分散と、段階的な品質確認を両立できます。

変換ジョブは VS Code の場合、コマンドパレットから「Amazon Q: Start Code Transformation」を選択して開始します。変換先バージョン(Java 17 等)を指定すると、Q Developer がコードを解析して変換計画を立案します。JetBrains IDE でも同様にサイドパネルから変換ジョブを起動できます。

変換が完了すると Q Developer は以下の成果物を自動生成します。

• ソースコードの差分(新旧の変更箇所を並べて確認可能)
• 既存ユニットテストの更新と未カバー箇所の補完
• ビルド検証レポート(依存関係の互換性確認結果を含む)

変換所要時間はコードベースの規模によって異なりますが、おおよそ 1,000 LOC あたり 10〜30 分が目安です。変換後は生成された成果物を確認し、手動修正が必要な箇所を特定してからメインブランチへマージするのが推奨フローです。

変換精度は高いですが 100% ではありません。次の構文や API は手動確認が必要になることがあります。

• Java 8 固有の非推奨 API(Date クラスの旧メソッド → java.time への移行等)
• リフレクションを多用するコード
• サードパーティライブラリの Java 17 非対応バージョン

大規模コードベース(10 万 LOC 超)への段階的適用戦略

段階的適用を成功させるために、以下の 4 ステップを順守します。

1. 境界モジュール先行: 外部依存が少ないユーティリティ層から変換を開始し、精度と所要時間を把握します
2. テストカバレッジの事前確保: 変換前に対象コードのユニットテストカバレッジを 70% 以上に引き上げます。変換後コードの正当性を自動検証するためです
3. 依存関係の事前棚卸し: mvn dependency:tree でサードパーティライブラリを確認し、Java 17 非対応版を事前に更新します
4. バッチ単位の進行: 30〜50 クラスを 1 バッチとして変換し、CI でビルドが通ることを確認してから次のバッチへ進みます

変換前の準備が変換品質を大きく左右します。依存関係の棚卸しとテストカバレッジの確保を先に行うことが、変換成功率を高める最短ルートです。

7-2. .NET モダナイゼーションと LOC 課金設計

.NET Framework アプリケーションの Linux 移植は、AWS Transform の agentic 実行により大幅に自動化されます。変換エンジンが .NET Framework のコードを .NET Core(.NET 6 または .NET 8)相当に書き換え、Linux コンテナ上での動作を可能にします。

AWS の計測によれば、従来の手動移植と比較して 最大 4 倍速 でプロジェクトを完了できます。また Windows Server ライセンスが不要になるため、ライセンスコストを最大 40% 削減 できるとされています。コンテナ化と組み合わせることで、スケーリングの柔軟性と運用コストの最適化を同時に実現できます。

.NET Framework → .NET Core/Linux の移植フロー

1. 依存関係スキャン  : NuGet パッケージの Linux 対応状況を自動調査
2. 互換性分析  : Windows 専用 API(COM, Win32 P/Invoke 等)の使用箇所を特定
3. コード変換  : .NET Core 互換コードへの自動書き換え
4. テスト生成  : Linux 動作確認用ユニットテストの生成・補完
5. Dockerfile 生成: Linux コンテナ向けビルドファイルの自動作成
6. ビルド検証  : コンテナイメージのビルドと動作確認

変換エージェントが対応できる範囲には限界があります。Windows 専用 API を多用しているコードは手動書き換えが必要です。変換前に .NET Upgrade Assistant で互換性スコアを確認することを推奨します。

Pro tier の LOC 課金設計

コード変換を計画的に進める上で、LOC 課金の仕組みを理解することが重要です。

月次枠を超えた場合、超過 LOC 数に $0.003 を乗じた金額が課金されます。例として、50,000 LOC のプロジェクトを 1 ユーザーが 1 ヶ月で変換しようとすると、超過 46,000 LOC × $0.003 = $138 となります。

大規模移行での課金を抑制するための実践的な方法を示します。

• 複数ユーザーへの分散: チームメンバーに担当モジュールを分けることで、各ユーザーの月次枠内に収めます
• 月をまたいだ分割: 単月に集中させず 2〜3 ヶ月へ分散します
• デッドコードの事前削除: 不要なコードを削除してから変換依頼することで、課金対象 LOC を減らします
• 変換優先度の設定: LOC が少なく移行効果の大きいモジュールから優先し、費用対効果を最大化します

変換前に wc -l などで対象 LOC を把握し、月次枠との差分を計算することが課金管理の第一歩です。計画なく変換すると予期しない課金が発生するため、必ず事前に見積もりを立てます。

8. 詰まりポイント・アンチパターン・まとめ

8-1. 詰まりポイント

詰まりポイント 1: q chat が応答しない / 遅い

q chat を起動しても応答が返ってこない、または非常に遅い場合、主に 3 つの原因が考えられます。

認証トークンの期限切れ

Builder ID や IAM Identity Center のトークンは定期的に期限切れになります。エラーメッセージに「Token expired」や「Authentication required」が含まれている場合はこのパターンです。

# 認証情報をリセットして再ログイン
q logout
q login

プロキシ設定の不備

社内ネットワーク経由でプロキシを使用している環境では、環境変数の設定が必要です。

export HTTPS_PROXY=http://proxy.example.internal:8080
export HTTP_PROXY=http://proxy.example.internal:8080
export NO_PROXY=localhost,127.0.0.1,169.254.169.254
q chat

プロキシ設定で応答が返るようになった場合は、~/.zshrc または ~/.bashrc に設定を追記して恒久化します。

リージョン設定の確認

Q Developer のサービスが提供されているリージョン(us-east-1 または us-west-2 が多い)に ~/.aws/config のデフォルトリージョンが設定されているか確認します。接続が遅い場合は curl -I https://q.us-east-1.amazonaws.com/ で疎通確認をするとよいです。

詰まりポイント 2: /dev で期待外れの変更が多い

/dev コマンドを使うと、意図とは異なる広範囲にわたるファイル変更を提案されることがあります。原因の多くはプロンプトのコンテキストが広すぎることです。

対処: 対象ファイルと変更内容を具体化する

# 曖昧な指示(避ける)
# /dev ユーザー認証を改善して

# 具体的な指示(推奨)
# /dev src/auth/AuthService.java の validateToken メソッドをリファクタリングして。
# 変更対象はこのファイルのみ。JWT の有効期限チェックロジックをメソッド分割で改善する。

対処: 実装を段階的に分割する

一度のプロンプトで全機能を実装しようとすると精度が落ちます。インターフェース定義 → 実装クラス → テスト の順に段階的に依頼することで、各ステップの品質を確認しながら進められます。

変更範囲が大きすぎる場合は Esc で中断し、より具体的なプロンプトで再試行するのが最も効果的です。

詰まりポイント 3: /review で CRITICAL 過検知

/review を実行すると CRITICAL 判定が大量に出て、実際には問題のないコードへの警告も表示される場合があります。

対処: レビュースコープをファイル単位に絞る

コードベース全体を対象にするのではなく、差分ファイルのみを対象にすることで過検知を減らせます。

対処: カスタムルール設定で重大度を調整する

プロジェクトルートに .amazonq/codereviewer.yaml を作成することで、特定ルールの重大度を調整または無効化できます。

# .amazonq/codereviewer.yaml
rules:
  - ruleId: "NO_HARDCODED_VALUES"
 severity: MEDIUM
  - ruleId: "MISSING_NULL_CHECK"
 enabled: false

プロジェクトの特性に合わせてルール調整することで、真に対処すべき問題にフォーカスできます。Q Developer のフィードバック機能から「This finding is incorrect」を選択することで、モデル改善にも貢献できます。

詰まりポイント 4: セキュリティスキャンの False Positive

セキュリティスキャンで検出された issue が実際には安全なコードである場合、コードへの suppress コメントや ignore 設定で除外できます。

対処: suppress コメントによるインライン除外

// amazon-q-suppress-rule: HARDCODED_CREDENTIALS
private static final String API_ENDPOINT = "https://api.example.com/v1";

# amazon-q-suppress-rule: SQL_INJECTION_RISK
query = f"SELECT * FROM {table_name}"  # table_name is validated upstream

対処: .amazonq/ignore ファイルによるパス除外

# .amazonq/ignore
test/fixtures/
src/dev/mockdata/
**/*_test_only.py

suppress を乱用するとリアルな検出が埋もれます。suppress を適用する際は必ずコードレビューを通し、suppress の理由をコメントに記載するチームルールを設けることを推奨します。

詰まりポイント 5: Java 変換後にビルドエラー

Java 変換後にビルドエラーが発生する場合、以下のパターンが多いです。

サードパーティ依存の非互換

pom.xml の依存関係が Java 17 非対応の古いバージョンのままになっているケースです。

# 依存関係のアップグレード候補を確認
mvn versions:display-dependency-updates

# Spring Boot、Hibernate、Log4j 等の主要ライブラリを Java 17 対応版へ更新

主要ライブラリの Java 17 対応最小バージョンの目安:
– Spring Boot: 2.7.x 以上(3.x 推奨)
– Hibernate: 5.6 以上(6.x 推奨)
– Log4j: 2.17.0 以上

内部 API へのアクセス制限

Java 17 では一部の内部 API へのアクセスが制限されます。次のコマンドで使用箇所を確認し、標準 API への書き換えが必要です。

# 内部 API 使用箇所の確認
grep -r "sun\." src/ --include="*.java"

手動修正が多くなる場合には、変換前に jdeps ツールで内部 API への依存を洗い出しておくと効率的です。

詰まりポイント 6: IAM Identity Center 組織展開後に一部ユーザーが Free tier 扱い

組織全体に Pro tier を展開したはずなのに、特定のユーザーが Pro 機能を使えない場合があります。

プロファイル設定の確認

ユーザーの CLI プロファイルが IAM Identity Center のプロファイルを参照しているか確認します。

# 現在の認証状態確認
q whoami

# IAM Identity Center プロファイルで再ログイン
aws configure sso --profile q-developer-sso
aws sso login --profile q-developer-sso
export AWS_PROFILE=q-developer-sso
q chat

割り当て確認

AWS の Amazon Q Developer コンソールの「Subscriptions」メニューから、組織内の割り当て状況を確認します。新規割り当て後 5〜10 分程度待ってから再ログインすると解消することがあります。

詰まりポイント 7: Scan as you code が VS Code で動作しない

コードを書きながらリアルタイムに検査する「Scan as you code」機能が VS Code で有効にならない場合の対処法です。

拡張バージョンの確認

この機能は比較的新しいため、Amazon Q Developer 拡張のバージョンが古いと利用できません。拡張機能パネルから「Amazon Q」を検索し、バージョンが最新であることを確認して更新します。

設定の確認

settings.json で機能が有効になっているか確認します。

{
  "amazonQ.scanAsYouCode.enabled": true,
  "amazonQ.scanAsYouCode.autoScanDelay": 5000
}

プロキシ環境での設定

プロキシ環境では VS Code の設定にもプロキシを指定する必要があります。

{
  "http.proxy": "http://proxy.example.internal:8080",
  "http.proxyStrictSSL": false
}

VS Code のワークスペース信頼機能で「制限モード」になっていると Q Developer の一部機能が制限されます。ワークスペース信頼を有効化して再試行します。

8-2. アンチパターン → 正解変換

❌ アンチパターン 1: /dev に「全部書いて」と大きな粒度で依頼する

# 避けるべき指示
/dev 決済機能全体を実装して

/dev は指示が曖昧・大きいほど変更範囲が広がり、意図しないファイルも修正される原因になります。

✅ 正解: 機能単位で分割して依頼する

/dev src/payment/PaymentProcessor.java のインターフェースを定義して。
ChargeメソッドとRefundメソッドの2つのみ。

インターフェース定義 → 実装クラス → テスト の順に 1 ステップずつ依頼し、各差分を確認してから次へ進みます。承認前に差分全体を確認することで、想定外の変更を防げます。

❌ アンチパターン 2: セキュリティスキャン結果を全件スキップする

スキャン結果が大量に出ると、全件 suppress して対処した気になるケースがあります。

✅ 正解: HIGH / CRITICAL は必ず個別に確認して対処する

判定の低いものは suppress 運用でコントロールしつつ、HIGH 以上の検出は必ず個別確認します。「意図的に受容するリスク」は suppress コメントに理由を明記し、コードレビューを通してチームで合意することが重要です。suppress を乱用すると、将来本物の問題を見落とすリスクが高まります。

❌ アンチパターン 3: コード変換結果を本番ブランチに直接適用する

変換後のコードを確認せずにメインブランチへマージしたことで、ビルド破壊の事例があります。

✅ 正解: フィーチャーブランチで変換し、CI 検証を通過してからマージする

変換ジョブの結果は必ずフィーチャーブランチで受け取り、CI/CD パイプラインのビルド・テストを通過したことを確認してからメインブランチへマージします。変換後コードの差分レビューを PR 上で行うことで、手動修正が必要な箇所をチームで確認できます。

❌ アンチパターン 4: Free tier のまま本番開発チームに展開する

Free tier は月次上限に達するとエージェント機能が制限されます。本番開発チームが月途中でコード補完やエージェント機能を使えなくなるケースがあります。

✅ 正解: Pro tier の費用対効果を計算してから昇格する

Pro tier の費用は 1 ユーザーあたり月 $19(2025 年時点)です。開発者 1 人が月に節約できる工数(コード補完・テスト生成・レビュー補助等)を時給換算すると、ほぼ確実に費用を上回ります。本番稼働チームには最初から Pro tier を割り当て、個人・学習用途は Free tier を使い分ける運用が合理的です。

❌ アンチパターン 5: Amazon Q Developer と Amazon Q Business を混同して導入する

「社内ナレッジをチャットで検索したい」というニーズに Q Developer を導入してしまい、期待と合わずに活用されないケースがあります。

✅ 正解: 用途で使い分ける

導入目的を整理してから選定することで、ライセンス費用の無駄と期待値ギャップを防げます。

8-3. まとめと Vol2 予告

Amazon Q Developer は IDE・CLI・エージェント・コードレビュー・セキュリティスキャン・コード変換という 6 つの機能軸で、開発ライフサイクル全体をカバーします。Vol1 で解説した活用の 3 本柱は以下のとおりです。

1. 日常コーディング支援: IDE インラインチャット・q chat・エージェントコマンド(/dev・/test・/doc)で実装・テスト・ドキュメント生成を高速化する
2. 品質保証の自動化: /review と セキュリティスキャン(SAST・Secrets・IaC)を開発サイクルに常設し、問題を早期発見・早期修正する
3. モダナイゼーション: Java/.NET のコード変換エージェントで技術的負債を計画的に解消する

チームへの段階的導入ロードマップとして、まず個人で Free tier を試用して体感を掴み、次に 2〜3 名のコアチームで Pro tier を評価し、最後に組織展開(IAM Identity Center 連携)へと拡張するステップが安定しています。

Vol2 では、組織展開の詳細(IAM Identity Center 設定・ポリシー管理)、大規模コードベースへの段階的移行戦略、カスタマイズ(カスタムモデル・ガイドライン設定)、そして Q Developer の CI/CD パイプライン統合を扱う予定です。

Amazon Q Developer / Bedrock の概要から学ぶ(生成AI Vol2)を読む

Q Business の運用改善編(Vol2)も読む