Amazon Q Developer CLIでインフラコードをレビューするカスタムエージェントを作成

はじめに

Amazon Q Developer CLI（以下、Q CLI）と 4 つの MCPサーバーを使用して、インフラコードをレビューするカスタムエージェントを作成しました。

カスタムエージェントは、特定のユースケースやワークフローに合わせてカスタマイズ可能な AIアシスタントです。シナリオに適したツール、権限、プロンプトを設定できます。また、実行を許可するコマンドを設定することで、意図しないコマンドの実行を防ぐことができます。

使用した MCP サーバーは以下の 4 つです。

• AWS Knowledge MCP Server
• AWS Documentation MCP Server
• AWS Pricing MCP Server
• AWS Terraform MCP Server

参考情報

この記事の内容で実現すること

以下のようにエージェントを指定して Q CLI を起動することで、カスタムエージェントの設定ファイルに記載した特定の MCP サーバーやツール、権限を反映したエージェントが起動します。

q chat --agent aws-infra-reviewer

設定ファイルにはあらかじめシステムプロンプトがあるので、以下のような単純なクエリでレビューを依頼できます。

> terraformコードを参照し、レビューを行ってください。

レビューが完了すると、このような結果が出力されます。ここでは、EC2 インスタンスに Web サーバーとメールサーバーを構築する Terraform コードを対象としたレビューを行いました。

レビュー結果 (長いので折りたたんでいます)

## AWS Well-Architected レビュー結果

### 🏗️ インフラストラクチャ概要
• **リージョン**: ap-northeast-1 (東京)
• **主要コンポーネント**: VPC、ALB、EC2 (t3.nano)、セキュリティグループ
• **用途**: メールサーバー

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## 🔒 セキュリティ (Security)

### ❌ 重大な問題
1. HTTPリスナーの設定不備
   • HTTPからHTTPSへのリダイレクトが未設定
   • セキュリティリスクが存在

### ✅ 良い点
• EBSボリュームの暗号化が有効
• 削除保護が有効
• 最小権限の原則に基づくセキュリティグループ設計

### 🔧 改善提案
hcl
# HTTPからHTTPSリダイレクト
resource "aws_lb_listener" "alb-listener-http-redirect" {
  load_balancer_arn = aws_lb.alb.arn
  port              = "80"
  protocol          = "HTTP"

  default_action {
    type = "redirect"
    redirect {
      port        = "443"
      protocol    = "HTTPS"
      status_code = "HTTP_301"
    }
  }
}


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## 🚀 可用性とスケーラビリティ (Reliability)

### ✅ 良い点
• マルチAZ構成 (ap-northeast-1c, 1b)
• ALBによる負荷分散
• EIPによる固定IP

### ⚠️ 改善が必要
1. 単一インスタンス構成
   • SPOFリスク
   • 自動復旧機能なし

2. ヘルスチェック未設定
  hcl
   # 現在コメントアウト
   # health_check {
   #   path = "/api"
   # }


### 🔧 改善提案
hcl
# Auto Scaling Group追加
resource "aws_autoscaling_group" "mail-asg" {
  name                = "mail-asg"
  vpc_zone_identifier = [aws_subnet.subnet-pri-first.id, aws_subnet.subnet-pri-second.id]
  target_group_arns   = [aws_lb_target_group.alb-target-group-http.arn]
  health_check_type   = "ELB"
  min_size            = 1
  max_size            = 3
  desired_capacity    = 2
}

# ヘルスチェック有効化
resource "aws_lb_target_group" "alb-target-group-http" {
  health_check {
    enabled             = true
    healthy_threshold   = 2
    interval            = 30
    matcher             = "200"
    path                = "/health"
    port                = "traffic-port"
    protocol            = "HTTP"
    timeout             = 5
    unhealthy_threshold = 2
  }
}


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## 💰 コスト最適化 (Cost Optimization)

### 📊 現在のコスト分析 (MCP価格データより)
• **EC2 t3.nano**: $0.0068/時間 = $4.90/月
• **ALB**: $0.0243/時間 = $17.50/月
• **合計**: 約 $22.40/月

### 🔧 コスト最適化提案
1. Reserved Instancesの検討
   • 1年契約で約30%削減可能

2. ALBの見直し
   • 単一インスタンスならClassic LBも検討
   • ただし機能制限あり

3. スケジューリング

hcl
   # 開発環境用の自動停止
   resource "aws_autoscaling_schedule" "scale_down" {
     scheduled_action_name  = "scale_down"
     min_size               = 0
     max_size               = 0
     desired_capacity       = 0
     recurrence            = "0 19 * * MON-FRI"  # 平日19時停止
     autoscaling_group_name = aws_autoscaling_group.mail-asg.name
   }



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## ⚡ パフォーマンス効率 (Performance Efficiency)

### ✅ 良い点
• GP3ストレージ使用
• EBS最適化有効
• 詳細モニタリング有効

### 🔧 改善提案
1. CloudWatchメトリクス追加

hcl
   resource "aws_cloudwatch_metric_alarm" "high_cpu" {
     alarm_name          = "mail-high-cpu"
     comparison_operator = "GreaterThanThreshold"
     evaluation_periods  = "2"
     metric_name         = "CPUUtilization"
     namespace           = "AWS/EC2"
     period              = "120"
     statistic           = "Average"
     threshold           = "80"
     alarm_description   = "This metric monitors ec2 cpu utilization"
   }



2. ログ集約

hcl
   # ALBアクセスログ有効化
   resource "aws_s3_bucket" "alb_logs" {
     bucket = "alb-access-logs-${random_string.bucket_suffix.result}"
   }

   # ALB設定でアクセスログ有効化
   access_logs {
     bucket  = aws_s3_bucket.alb_logs.id
     enabled = true
   }



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## 🎯 優先度別改善ロードマップ

### **高優先度 (即座に対応)**
1. HTTPからHTTPSリダイレクト設定
2. ALBヘルスチェック有効化

### **中優先度 (1-2週間以内)**
1. Auto Scaling Group導入
2. CloudWatchアラーム設定
3. ALBアクセスログ有効化

### **低優先度 (1ヶ月以内)**
1. Reserved Instances検討
2. バックアップ戦略策定
3. 災害復旧計画作成

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


## 📋 まとめ

現在の構成は基本的なセキュリティ要件は満たしていますが、**可用性とセキュリティの強化**が急務です。特にメールサーバーという重要な役割を考慮すると、単一障害点の排除と適切なアクセス制御の実装が必要です。

推定改善後コスト: 月額$35-45 (高可用性構成)
セキュリティスコア: 現在60% → 改善後85%
可用性: 現在95% → 改善後99.5%

この分析は最新のAWS公式ドキュメントとリアルタイム価格データに基づいて実施されました。

前提条件

以下の環境で動作を確認しました。

• WSL2 上の Ubuntu 24.04.3 LTS
• Q CLI v1.17.1

カスタムエージェントの作成

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

カスタムエージェントには、すべてのプロジェクトで有効なグローバルスコープと、プロジェクト配下で有効なプロジェクトスコープがあります。それぞれ設定ファイルの場所が異なるので、ユースケースに合わせて配置します。

グローバルスコープの場合は ~/.aws/amazonq/cli-agents/{agent-name}.json に配置します。プロジェクトスコープではそのプロジェクトのディレクトリの .amazonq/cli-agents/{agent-name}.json に配置します。両方の設定がある場合は、プロジェクトスコープが優先されます。(参考: Managing custom agents)

{agent-name}.json の部分は、エージェントの目的や使用している技術・言語名、プロジェクト名を設定するとよいようです。(参考: Custom agent naming conventions)

ここではグローバル設定の例で、~/.aws/amazonq/cli-agents/aws-infra-reviewer.json にファイルを配置したものとします。

カスタムエージェント設定ファイル

設定ファイルは JSON で記述します。各パラメータの内容は以下のとおりです。(参考: Configuration reference)

パラメータ	説明
name	q chat --agent [name] で指定するエージェント名
description	エージェントの概要（/agent list で表示予定だが、動作環境では表示されない場合あり）
prompt	エージェントのシステムプロンプト
model	エージェントが利用するモデル
mcpServers	エージェントが利用する MCP サーバーの設定
tools	エージェントが利用可能なツール（* ですべて許可）
allowedTools	ユーザー確認を求めず実行するツール
toolsSettings	ツールごとの許可/拒否コマンド設定

~/.aws/amazonq/cli-agents/aws-infra-reviewer.json

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "aws-infra-reviewer",
  "description": "AWSインフラレビュー用エージェント",
  "prompt": "あなたはAWS Well-Architectedの専門家です。\n\n【重要】MCPサーバーを必ず使用してレビューを行ってください：\n- 与えられたMCPサーバーを必ず使用して最新のAWS公式ドキュメントを参照すること\n- @awslabs.aws-pricing-mcp-server/get_pricingを必ず使用してコスト分析を実施すること\n- レビュー時は必ずこれらのツールで最新情報を確認してから回答すること\n\n以下の観点でレビューしてください：\n- 可用性とスケーラビリティ\n- セキュリティ（最小権限の原則）\n- コスト最適化\n- パフォーマンス効率\n\n必ず最新のAWSベストプラクティスに基づいて評価し、具体的な改善提案を提供してください。MCPサーバーを使用せずに回答することは禁止します。",
  "model": "claude-sonnet-4.5",
  "mcpServers": {
    "awslabs.aws-documentation-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_DOCUMENTATION_PARTITION": "aws"
      },
      "disabled": false,
      "autoApprove": []
    },
    "aws-knowledge-mcp-server": {
      "command": "uvx",
      "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"]
    },
    "awslabs.terraform-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.terraform-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    },
    "awslabs.aws-pricing-mcp-server": {
      "command": "uvx",
      "args": [
         "awslabs.aws-pricing-mcp-server@latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  },
  "tools": ["*"],
  "allowedTools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "report_issue",
    "use_aws",
    "@aws-knowledge-mcp-server",
    "@awslabs.aws-documentation-mcp-server",
    "@awslabs.aws-pricing-mcp-server",
    "@awslabs.terraform-mcp-server"
   ],
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": [
        "grep",
        "find",
        "wc",
        "head",
        "tail",
        "cat",
        "diff",
        "git diff",
        "git log"
      ],
      "deniedCommands": [
        "git commit .*",
        "git push .*"
      ],
    }
  }
}

カスタムエージェントを指定してチャットを起動

設定ファイル内のnameフィールドで指定したエージェント名を引数にしてチャットを起動します。

q chat --agent aws-infra-reviewer

設定した 4 つの MCP サーバーが読み込まれ、入力カーソルの手前にエージェント名が表示されました。model フィールドで指定したモデルを使用してチャットが開始されたことが分かります。

/tools を実行すると、このエージェントが使用可能なツール一覧が表示されます。このエージェントでは、allowedTools ですべての MCP サーバーをユーザーの確認を求めず実行可能なツールとして定義しているので、Permission が trusted となっています。ビルトインツールは、knowledge (セッション間で情報を保存、取得するツール) が not trusted となっています。

#この記事の内容で実現することにあるように、コードがあるディレクトリでチャットを起動しレビューを依頼すると、エージェントが詳細なレビュー結果を提供してくれました。

カスタムエージェントのサンプル

公式ドキュメントの Examples に用途別のサンプルが掲載されています。

/agent コマンドでカスタムエージェントを作成・編集

上記の例では、~/.aws/amazonq/cli-agents/aws-infra-reviewer.json を手動で作成し編集しました。Q CLI の /agent create や /agent generate を使うと、テンプレートファイルの生成や対話形式での設定ファイル生成が可能なようです。

試した限りでは、ドキュメントに記載のあるコマンド引数の指定とコマンドのヘルプの内容が異なっていました。いずれの内容も期待した動作ではありませんでした。(2025/10/05 現在)

カスタムエージェントの設定ファイルはエディタで直接作成・編集したほうが良さそうです。

たとえば、Defining a custom agentでは、カスタムエージェントの設定ファイルを作成するコマンドとして以下のように記載があります。

/agent create --name my-agent

これを実行すると No such file or directory となりました。実際は、~/.aws/amazonq/cli-agents 以下に my-agent.json と agent_config.json.example が生成されました。

> /agent create --name my-agent

Failed to execute command: No such file or directory (os error 2)

/agent create のヘルプをみると、-d もしくは --directory で出力先ディレクトリが指定できるようです。

> /agent create --help

Create a new agent with the specified name

Usage: /agent create [OPTIONS] --name <NAME>

Options:
  -n, --name <NAME>            Name of the agent to be created
  -d, --directory <DIRECTORY>  The directory where the agent will be saved. If not provided, the agent will be saved in the global agent directory
  -f, --from <FROM>            The name of an agent that shall be used as the starting point for the agent creation
  -h, --help                   Print help

しかし、このように出力先を指定しても /tmp 以下にはなにも生成されず、~/.aws/amazonq/cli-agents 以下に agent_config.json.example が生成されました。

> /agent create --name my-agent --directory /tmp

Failed to execute command: No such file or directory (os error 2)

対話形式でカスタムエージェント設定ファイルを生成する Creating agents with AI assistance (/agent generate) では、ドキュメントに以下の記載があります。

/agent generate agent-name [--global]

このコマンドは引数を取らないため、実際は以下のように進みます。エージェント名、説明文、スコープの選択、使用する MCP サーバーの選択を行うと、設定ファイルがデフォルトのエディタで開きます。エディタを閉じると ~/.aws/amazonq/cli-agents 以下に設定ファイルが生成されます。

> /agent generate

✔ Enter agent name:  · my-agent
✔ Enter agent description:  · help your coding.
✔ Agent scope · Global (all workspaces)
Select MCP servers (use Space to toggle, Enter to confirm):
> [ ] GitHub ()
  [ ] aws-knowledge-mcp-server (uvx)

/agent generate の MCP サーバーの選択は ~/.aws/amazonq/mcp.json の内容をもとに一覧を表示しているようですが、一部表示されていませんでした。

また、/agent edit コマンドは、引数にエージェント名を指定しても設定を開けませんでした。これについては Issue があり、エージェント名とファイル名を一致させると動作するとあるのですが、それでも動作しませんでした。

> /agent edit --help

Edit an existing agent configuration

Usage: /agent edit --name <NAME>

Options:
  -n, --name <NAME>  Name of the agent to edit
  -h, --help         Print help

> /agent list

* q_cli_default
  aws-infra-reviewer

> /agent edit --name aws-infra-reviewer

Failed to execute command: No such file or directory (os error 2)

まとめ

Q CLI のカスタムエージェントを作成し、それにインフラコードのレビューを行ってもらいました。カスタムエージェントが使用するツールやコマンドをこまかく指定できるので、汎用的なチャットエージェントにありがちな勝手なコード変更や意図しない削除を防止できます。また、システムプロンプトやモデルの指定もあり、用途にあわせたカスタマイズも可能です。

ただし、/agent コマンドに期待した動作とならなかったり、ドキュメントの記載と実際の動作が異なっているものがあるので、利用の際は注意が必要です。