🏔️

コード品質を高めるAIエージェント開発フローを15分で簡易体験 : Amazon Q Developer

山田航司（Koji Yamada）

2025/10/21に公開

所要時間: 約15分

難易度: 初級

対象者: Amazon Q Developer（IDE版）の主要機能を素早く一通り体験したい方

 このチュートリアルで学べることソフトウェア開発ライフサイクル（SDLC）の主要フェーズでAmazon Q Developerを活用する方法を体験します。
✅ コード理解 - @workspaceでプロジェクト全体を把握
✅ 設計・実装 - /devで新機能追加（履歴機能）
✅ テスト - /testでユニットテスト生成
✅ レビュー・修正 - /reviewでセキュリティ脆弱性検出→自動修正
✅ ドキュメント - /docでREADME生成
以下の赤太字部分が体験できるイメージです。

続編記事では以下も体験できるので、興味のある方はご参照ください。
✅ デプロイ - 自然言語指示でAWSアカウントにデプロイ実行
https://zenn.dev/aws_japan/articles/595e857e5969fe

 前提条件Visual Studio Code
Amazon Q Developer  VS Code拡張機能がインストール済み
Python 3.7以上

 前提条件の補足説明 : Amazon Q Developer  VS Code拡張機能の準備Amazon Q Developer Pro版をお使いの場合は、以下手順に従ってAWS IAM Identity Centerの設定をお願いします。
https://aws.amazon.com/jp/blogs/psa/getting-started-with-aws-iam-identity-center-for-amazon-q-developer-in-organizations/
VS CodeにAmazon Q Developer 拡張機能をインストールしてログインする手順については、上記リンク内の「Amazon Q Developer の利用」の箇所をご参照ください。
無償版のAmazon Q Developer Free版をお使いの方は、Amazon Q DeveloperサインインオプションにてPersonal accountを選択いただき、AWS Builder IDでログインしてください。

 前提条件の補足説明 : Python環境の準備
 1. VS Codeでターミナルを開くVS Codeを起動し、上部メニューから「ターミナル」→「新しいターミナル」

 2. Pythonがインストールされているか確認ターミナルに以下を入力してEnter：
# macOS/Linux
python3 --version

# Windows
python --version
Python 3.7以上が表示されたらステップ4へ。

 3. Pythonのインストール（表示されない場合のみ）macOS:
brew install python3
Homebrewがない場合: https://brew.sh/ の指示に従ってインストール
Windows:

https://www.python.org/downloads/ を開く
「Download Python」をクリック
ダウンロードしたインストーラーを実行
インストール画面で「Add Python to PATH」にチェックを入れる
「Install Now」をクリック
完了後、VS Codeのターミナルを閉じて新しいターミナルを開く（「ターミナル」→「新しいターミナル」）

python --version で確認

 4. Python拡張機能のインストール左サイドバーの拡張機能アイコンをクリック
検索欄に「Python」と入力
Microsoft製のPython拡張機能をインストール
トラブルシューティング:
Pythonが見つからないエラー → VS Code右下でPythonバージョンが表示されているか確認。表示されていない場合は Ctrl+Shift+P (macOS: Cmd+Shift+P) → 「Python: Select Interpreter」→ Python 3.7以上を選択
Windowsでpythonコマンドが認識されない → VS Codeのターミナルを閉じて新しいターミナルを開く。それでも解決しない場合はPythonを再インストールし、「Add Python to PATH」に必ずチェックを入れる

 フェーズ0: VS Codeの初期セッティング
 ステップ1: 新規ワークスペースを作成任意の場所に新しいフォルダを作成（例: q-tutorial）
VS Codeでそのフォルダを開く（「ファイル」→「フォルダーを開く」）

calculator.pyという名前で新規ファイルを作成
以下のコードをコピー＆ペースト
ファイルを保存（Cmd+S / Ctrl+S）
calculator.py のコード（クリックして展開）"""
シンプル計算機アプリケーション

注意: このコードには意図的にセキュリティ上の問題が含まれています。
eval()の使用は実際の開発では推奨されません。
"""


def calculate(expression):
    """
    数式を計算する
    
    注意: eval()を使用しているため、任意のPythonコードが実行される危険性があります。
    実際の開発では使用しないでください。
    
    Args:
        expression (str): 計算式（例: "2 + 3"）
    
    Returns:
        float: 計算結果
    """
    # 注意: eval()の使用はセキュリティリスクがあります
    return eval(expression)


def main():
    """メイン関数"""
    print("=== シンプル計算機 ===")
    print("計算式を入力してください（例: 2 + 3）")
    print("終了するには 'q' を入力")
    
    while True:
        try:
            expression = input("\n> ").strip()
            
            if expression.lower() == 'q':
                print("終了します")
                break
            
            if not expression:
                continue
            
            result = calculate(expression)
            print(f"結果: {result}")
            
        except Exception as e:
            print(f"エラー: {e}")


if __name__ == "__main__":
    main()

 ステップ2: 動作確認ターミナルで実行：
# macOS/Linuxの場合
python3 calculator.py

# Windowsの場合
python calculator.py
計算式を入力してテスト：
> 2 + 3
結果: 5

> 10 * 5
結果: 50

> q
終了します

 フェーズ1: コード理解@workspaceコマンドとは:

プロジェクト内の全ファイルを対象に質問できるコマンドです。ファイル名、ディレクトリ構造、コード内容を分析して回答します。

 1-1. Amazon Q パネルを開くVS Code 左サイドバーの Amazon Q アイコン をクリック
「+ New tab」で新しいチャットを開始

 1-2. プロジェクト全体を理解する@workspace このアプリケーションは何をするものですか？
期待される応答:
計算機アプリの説明
calculate関数の説明
main関数の動作
実際の出力例（クリックして展開）このアプリケーションはシンプルな計算機プログラムです。

主な機能：
- ユーザーから数式（例：2 + 3、10 * 5など）を入力として受け取る
- 入力された数式を計算して結果を表示する
- qを入力すると終了する
- エラーが発生した場合はエラーメッセージを表示する

ただし、コード内にも明記されているように、このコードには重大なセキュリティ上の問題があります：

⚠️ セキュリティリスク
- eval()関数を使用しているため、任意のPythonコードが実行される危険性があります
- 悪意のあるユーザーが__import__('os').system('rm -rf /')のようなコードを入力すると、
  システムに深刻な被害を与える可能性があります

このコードは学習目的やデモンストレーション用と思われますが、実際の開発環境では使用すべきではありません。
安全な実装には、専用の数式パーサーライブラリ（例：sympy、numexpr）の利用が推奨されます。

 フェーズ2: 設計・実装/devコマンドとは:

新機能の追加やコード変更を自動で行うコマンドです。実装計画を提示し、コードを生成して変更を提案します。
複数ファイルがある場合:

特定のファイルを指定したい場合は、/dev #file:ファイル名 指示内容 の形式で指定できます。

例: /dev #file:calculator.py 履歴機能を追加

 2-1. 新機能を追加するチャットで以下を入力：
/dev 計算履歴機能を追加してください。各計算結果を履歴として保存し、'history'コマンドで過去の計算を表示できるようにしてください。
Amazon Q の動作:
実装計画を提示
コードを生成
実際の出力例（クリックして展開）計算履歴機能を追加するため、履歴リストと履歴表示機能を実装します

calculator.py
+13
-0

Undo
計算履歴機能を追加しました！

変更内容：
- historyリストを追加して、各計算の式と結果をタプルで保存
- 'history'コマンドを入力すると、過去の計算履歴を番号付きで表示
- 履歴がない場合は「履歴はありません」と表示
- 起動時のメッセージに履歴機能の説明を追加

 2-2. 変更を承認して適用提案された変更内容を確認
コードが自動的に書き換えられる
ターミナルで動作確認：
python3 calculator.py  # macOS/Linux
# または
python calculator.py   # Windows

> 2 + 3
結果: 5
> 10 * 2
結果: 20
> history
=== 計算履歴 ===
1. 2 + 3 = 5
2. 10 * 2 = 20

 フェーズ3: テスト/testコマンドとは:

開いているファイルに対してユニットテストを自動生成するコマンドです。テストファイルを作成し、実行まで行います。

 3-1. ユニットテストを生成calculator.pyファイルを開いた状態で、チャットに入力：
/test
Amazon Q の動作:
テストファイル（test_calculator.pyのような名前）を自動生成
履歴機能を含むテストケースを作成
calculate関数と履歴機能の両方をテスト
自動的にテストを実行して結果を表示する場合もあります
💡: /devで履歴機能を追加した後なので、履歴機能のテストも含まれます。これは正常な動作です。
実際の出力例（クリックして展開）calculator.pyのテストを生成します。calculate関数と履歴機能をテストします。

calculator.pyの機能をテストするユニットテストファイルを作成します

test_calculator.py
+64
-0

Undo
python3コマンドでテストを実行します

shell
Completed
python3 -m pytest test_calculator.py -v
============================= test session starts ==============================
platform darwin -- Python 3.9.6, pytest-8.4.1, pluggy-1.6.0
cachedir: .pytest_cache
rootdir: /Users/XXXX/Desktop/AWS/XXXXX
plugins: cov-6.2.1, mock-3.14.1, anyio-3.7.1, typeguard-2.13.3
collecting ... 
collected 8 items

test_calculator.py::TestCalculate::test_addition PASSED                  [ 12%]
test_calculator.py::TestCalculate::test_complex_expression PASSED        [ 25%]
test_calculator.py::TestCalculate::test_division PASSED                  [ 37%]
test_calculator.py::TestCalculate::test_multiplication PASSED            [ 50%]
test_calculator.py::TestCalculate::test_subtraction PASSED               [ 62%]
test_calculator.py::TestMain::test_empty_history PASSED                  [ 75%]
test_calculator.py::TestMain::test_history_feature PASSED                [ 87%]
test_calculator.py::TestMain::test_single_calculation PASSED             [100%]

============================== 8 passed in 0.07s ===============================

テストが完成しました！✅ 全8テストがパスしました。

 3-2. テストを手動で実行（オプション）Amazon Qが自動実行しない場合は、生成されたテストファイル名を確認して手動で実行してください：
# 生成されたファイル名を確認（例: test_calculator.py）
# macOS/Linuxの場合
python3 -m unittest test_calculator.py -v

# Windowsの場合
python -m unittest test_calculator.py -v
期待される結果: 全テストが通る（機能は正常）

 フェーズ4: レビュー・修正/reviewコマンドとは:

コードのセキュリティ脆弱性や品質問題を検出するコマンドです。プロジェクト全体をスキャンし、問題を報告します。
このフェーズでは、セキュリティ脆弱性の検出と自動修正を体験します。

 4-1. セキュリティレビューを実行チャットで入力：
/review
Amazon Q の動作:
プロジェクト全体をスキャン
セキュリティ脆弱性を検出
eval()の使用を検出
実際の出力例（クリックして展開）I will scan the diff for the following files/folders:
/Users/XXXX/Desktop/AWS/XXXX/calculator.py

差分がなかったため、ファイル全体のレビューを実行しました。

calculator.pyのレビューが完了し、いくつかの問題が見つかりました。
詳細を確認し、修正案を取得するには、Code Issuesパネルの説明ボタンと修正ボタンをご利用ください。

主な検出内容：
- Critical（重大）: eval()関数の使用による任意コード実行の脆弱性（CWE-94）
- High（高）: OSコマンドインジェクションのリスク（CWE-77,78,88）
- Medium（中）: 不適切なエラーハンドリング

 4-2. 検出された問題を確認VS Code 左サイドバーで AMAZON Q → CODE ISSUES を開く
検出された問題を確認
検出される問題:
Critical: eval()の使用
任意コード実行の危険性
重要度: Critical

 4-3. 問題の詳細を確認問題をクリックして詳細を表示：
なぜ危険か
どう修正すべきか

 4-4. 修正を適用問題の右側にある 「Fix」ボタン をクリック（表示される場合）
Amazon Qが修正案を生成
修正内容を確認して適用
注意: 問題によってはFixボタンが表示されない場合があります。その場合は、チャットで「この問題を修正してください」と依頼することもできます。
実際の出力例（クリックして展開）CWE-94の脆弱性を修正します。eval()の代わりに、安全な数式評価方法を実装します。

eval()をast.literal_eval()とoperatorモジュールを使用した安全な実装に置き換えます

calculator.py
+13
-9

Undo
修正後のコードが正しく動作するかテストを実行して確認します

shell
Completed
python3 -m pytest test_calculator.py -v
============================= test session starts ==============================
collected 8 items

test_calculator.py::TestCalculate::test_addition PASSED                  [ 12%]
test_calculator.py::TestCalculate::test_complex_expression PASSED        [ 25%]
test_calculator.py::TestCalculate::test_division PASSED                  [ 37%]
test_calculator.py::TestCalculate::test_multiplication PASSED            [ 50%]
test_calculator.py::TestCalculate::test_subtraction PASSED               [ 62%]
test_calculator.py::TestMain::test_empty_history PASSED                  [ 75%]
test_calculator.py::TestMain::test_history_feature PASSED                [ 87%]
test_calculator.py::TestMain::test_single_calculation PASSED             [100%]

============================== 8 passed in 0.07s ===============================

CWE-94の脆弱性を修正しました！✅

修正内容：
- 危険なeval()を削除し、astモジュールを使用した安全な実装に変更
- 許可された演算子（+, -, *, /）のみを処理するホワイトリスト方式を採用
- 任意のPythonコードの実行を防止

すべてのテストが引き続きパスしており、機能は維持されたまま、セキュリティが大幅に向上しました。
修正内容:

eval()を削除

astモジュールを使用した安全な実装に置き換え
任意コード実行を防止

 フェーズ5: ドキュメント/docコマンドとは:

プロジェクトのドキュメント（README等）を自動生成するコマンドです。コードを分析して、使い方や機能説明を含むドキュメントを作成します。

 5-1. READMEを生成チャットで入力：
/doc このプロジェクトのREADME.mdを日本語で生成してください。使い方、機能説明、技術スタックを含めてください。
Amazon Q の動作:

修正後のコードを分析
安全な実装を反映したREADMEを生成
使い方、機能、技術情報を記載
実際の出力例（クリックして展開）プロジェクトのREADME.mdを生成します。

プロジェクトの使い方、機能、技術スタックを含むREADME.mdを日本語で作成します

README.md
+80
-0

Undo
README.mdを生成しました！

ドキュメントには以下の内容を含めました：
- 機能説明: 四則演算、履歴機能、安全な実装
- 使い方: 起動方法、基本操作、コマンド一覧
- 具体的な使用例: 計算と履歴表示の実例
- 技術スタック: Python 3.9+、使用している標準ライブラリ
- テスト方法: pytestの実行コマンド
- セキュリティ: ASTパーサーによる安全な実装の説明
- サポート演算: 利用可能な演算子のリスト

 5-2. 生成されたREADMEを確認生成されたREADME.mdを確認：
履歴機能が記載されている

安全な実装が説明されている
セキュリティセクションが正確

 まとめ15分で体験したこと:


フェーズ
コマンド
学んだこと


コード理解
@workspace
プロジェクト全体の把握

設計・実装
/dev
履歴機能の追加

テスト
/test
機能テストの自動生成

レビュー・修正
/review
セキュリティ脆弱性の検出と修正

ドキュメント
/doc
修正後のREADME生成

開発ライフサイクル（SDLC）の5フェーズの重要性:
コード理解の重要性
既存コードの構造と動作を正確に把握することが、安全な変更の第一歩
プロジェクト全体を俯瞰することで、変更の影響範囲を予測できる

@workspaceで効率的にコードベース全体を理解
設計・実装の重要性
要件を満たす機能を計画的に実装することで、保守性の高いコードを作成
段階的な機能追加により、デバッグが容易になる

/devで実装計画とコード生成を同時に行い、設計の一貫性を保つ
テストの重要性
実装した機能が正しく動作することを検証し、バグの早期発見につながる
自動テストにより、将来の変更時にも既存機能の動作を保証

/testで網羅的なテストケースを自動生成し、テスト作成の負担を軽減
レビュー・修正の重要性
セキュリティ脆弱性や品質問題を早期に発見し、リスクを低減
コードレビューにより、ベストプラクティスに沿った実装を維持

/reviewで自動スキャンし、人間が見落としがちな問題も検出
ドキュメントの重要性
他の開発者（未来の自分を含む）がコードを理解し、使用できるようにする
プロジェクトの目的、使い方、技術的な詳細を明確に伝える

/docで常に最新のコードに同期したドキュメントを自動生成
Amazon Q Developerの価値:

これら5つのフェーズすべてをAIがサポートすることで、開発者は創造的な作業に集中でき、品質の高いソフトウェアを効率的に開発できます。
続編記事では以下も体験できるので、興味のある方はご参照ください。
✅ デプロイ - 自然言語指示でAWSアカウントにデプロイ実行
https://zenn.dev/aws_japan/articles/595e857e5969fe

フェーズ	コマンド	学んだこと
コード理解	`@workspace`	プロジェクト全体の把握
設計・実装	`/dev`	履歴機能の追加
テスト	`/test`	機能テストの自動生成
レビュー・修正	`/review`	セキュリティ脆弱性の検出と修正
ドキュメント	`/doc`	修正後のREADME生成

アマゾンウェブサービスジャパン (有志)Publication

この Publication に投稿している記事は、アマゾンウェブサービスジャパン合同会社または Amazon Web Services, Inc. 所属社員による個人の見解であり、所属する組織の公式見解ではありません。参加したい従業員の方は、Sugiyama Suguru までお知らせください。

このチュートリアルで学べること

前提条件

前提条件の補足説明 : Amazon Q Developer VS Code拡張機能の準備

前提条件の補足説明 : Python環境の準備

1. VS Codeでターミナルを開く

2. Pythonがインストールされているか確認

3. Pythonのインストール（表示されない場合のみ）

4. Python拡張機能のインストール

フェーズ0: VS Codeの初期セッティング

ステップ1: 新規ワークスペースを作成

ステップ2: 動作確認

フェーズ1: コード理解

1-1. Amazon Q パネルを開く

1-2. プロジェクト全体を理解する

フェーズ2: 設計・実装

2-1. 新機能を追加する

2-2. 変更を承認して適用

フェーズ3: テスト

3-1. ユニットテストを生成

3-2. テストを手動で実行（オプション）

フェーズ4: レビュー・修正

4-1. セキュリティレビューを実行

4-2. 検出された問題を確認

4-3. 問題の詳細を確認

4-4. 修正を適用

フェーズ5: ドキュメント

5-1. READMEを生成

5-2. 生成されたREADMEを確認

まとめ

Discussion