1. はじめに

こんにちは。Healthcare Innovation Group（HIG）の福島です。
本記事は、春の入門祭り2026の7日目の記事です。

Claude Design、最近話題になっていますね。

• https://qiita.com/ryu-ki/items/bca0ee8f15a13dfd8cfa

以下は上記記事の引用です。

Claude Design は「見た目を作って終わり」ではなく、Claude Code への橋渡しまで考えられています。
デザインができたら、設計情報一式をまとめたパッケージ（handoff bundle）として Claude Code に渡せるという仕組みで、エクスポート先としてローカルのコーディングエージェントや Claude Code Web への引き継ぎが示されています。

これを見た時に思いました。インフラ構成のお絵描きからリソース実装までを、Claudeで一本化できるのではないかと。

そこで、この記事ではClaude DesignとClaude Codeを使い、以下の一連の流れを検証します（前提として、インフラリソースはAWSに構築し、IaCツールはTerraformを利用します）。

1. 曖昧な要件からAWS構成図を作成する
2. 対話しながら構成図を修正する
3. 確定した構成図をもとにTerraformコードを生成する
4. 生成されたTerraformコードをレビューする
5. 実際にAWSリソースを構築できるか確認する
6. AI活用時に人間がレビューすべきポイントを整理する

2. 今回構築するインフラ構成

今回の主目的は、Claude DesignでAWS構成図を作成し、それをもとにTerraformコードを生成することなので、インフラ構成自体は最小構成とします。

• インターネット公開のWebサービス
• ALB経由でECS Fargate上のアプリケーションにアクセスする
• ALB、ECSタスクは複数AZのパブリックサブネットに配置する
• 最低限のセキュリティグループを設定する

今回作成する主なAWSリソースは以下です。

• VPC
• Public Subnet × 2
• Internet Gateway
• Route Table
• Security Group
• Application Load Balancer
• ECS Cluster
• ECS Service
• ECS Task Definition
• IAM Role
• CloudWatch Logs

3. ステップ1： 要件から設計資料・AWS構成図を作成する

まずはプロジェクトを作成します。

実務では、構成図と合わせて設計の前提や目的、設計内容を整理することが多いので、今回はスライドを作成します。左ペインの”Slide deck”タブを選択し、名前を入力してCreateボタンを押下します。

プロンプトに以下の内容を入力します（「今回の検証・設計内容」章は本記事前半の内容をそのまま貼り付け）。

検証および設計内容を説明するスライドの作成にあたり、事前情報を以下に記載します。
スライド作成指示は後でするので、スライド作成はまだ開始せず、検証・設計内容の把握のみ実施してください

・今回の検証・設計内容
Claude DesignとClaude Codeを使い、以下の一連の流れを検証します。（前提として、インフラリソースはAWSに構築し、IaCツールはTerraformを利用します。）
1. 曖昧な要件からAWS構成図を作成する
2. 対話しながら構成図を修正する
3. 確定した構成図をもとにTerraformコードを生成する
4. 生成されたTerraformコードをレビューする
5. 実際にAWSリソースを構築できるか確認する
6. AI活用時に人間がレビューすべきポイントを整理する

今回の主目的は、Claude DesignでAWS構成図を作成し、それをもとにTerraformコードを生成することなので、インフラ構成自体は最小構成とします。
インターネット公開のWebサービス
ALB経由でECS Fargate上のアプリケーションにアクセスする
ALB、ECSタスクは複数AZのパブリックサブネットに配置する
最低限のセキュリティグループを設定する

今回作成する主なAWSリソースは以下です。
VPC
Public Subnet × 2
Internet Gateway
Route Table
Security Group
Application Load Balancer
ECS Cluster
ECS Service
ECS Task Definition
IAM Role
CloudWatch Logs

まずは検証・設計内容のみ確認してくれました。

続いて、以下のプロンプトでスライド作成指示を出します。
（まとめて作成させるとエラーが頻発したため、実際には1ページずつ作成させました）

インフラ設計内容およびAWS構成図を記載するスライドを作成してください。

目的は、今回の検証目的・前提条件・設計方針・コスト配慮、および具体的なAWSインフラ構成について読み手が理解できるようにすることです。

・スライド全体の要件
AWSインフラ設計資料のような体裁にする
設計内容を説明するページとAWS構成図のページを分けて、一つのスライドを作成する
見出し、箇条書き、簡単な表を使って分かりやすく整理する

・作成するスライド
ページ1: 検証の目的
ページ2: 設計前提および設計方針
ページ3: 作成対象リソース
ページ4: AWS構成図

・デザイン要件
落ち着いた技術資料風のデザインにする
AWSカラーを意識しつつ、過度に派手にしない
各スライドは情報を詰め込みすぎない
4ページ目のAWS構成図に続く前提で、設計説明資料として自然につながる構成にする

スライド作成が始まります。

作成が完了しました！

以下が作成されたスライド4ページ分です。

指示に従い、検証・設計内容を忠実にスライドに反映してくれています。
また、リージョンやAZ、VPCやサブネットのCIDRなどは明確に指示していませんが、よしなに設定してくれています。今回は特に変更の必要がないので、この設定をそのまま採用します。

続いて、以下プロンプトで各リソースの主要設定値を整理してもらいます。

現在作成済みの4ページ分のスライドに続けて、5ページ目以降に「各AWSリソースの主要設定値」を整理するスライドを追加してください。

目的は、後続でこの設計資料をもとにTerraformコードを作成する際に、必要な主要設定値を読み取れるようにすることです。

ただし、すべての設定値を網羅するとスライドが多くなりすぎるため、Terraform実装時に特に重要となる設定値に絞ってください。
追加スライド数は必要に応じて増やして構いませんが、全体として多くなりすぎないようにし、1スライドに複数リソースをまとめられる場合はまとめてください。

・全体のデザイン要件
既存4ページのデザインとトーンを合わせてください
AWS設計資料らしい落ち着いた技術資料風にしてください
1スライドに情報を詰め込みすぎないでください
ただし、スライド数が増えすぎないように、関連するリソースはまとめてください
表を中心に、Terraform実装時に読み取りやすい構成にしてください
Terraform実装の前段資料として、設計内容が具体化された状態になるようにしてください
文章は簡潔にし、設定値と補足が分かりやすいようにしてください

Claude Designには使用量の週次リミットがあり、到達してしまいそうだったためスライド作成はここまでとします。
細かい不備は少々あれど、必要最低限の内容は表現できており、資料の叩き台としては十分なレベルです。
構成図については、AWSが公式に提供するアイコンアセットを事前に読み込ませると、より視認性の高い図になるかもしれません。興味のある方は試してみてください。

4. ステップ2： Terraformコードの生成

ここからは、Claude DesignがまとめてくれたAWS構成および各リソースの設定値をベースに、Terraformコードを作成していきます。
前提として、ローカル環境にはTerraform CLIとAWS CLIの事前インストールが必要です。
事前に以下で認証確認を行っています。

aws sts get-caller-identity
terraform version

まずはClaude Designの右上にあるShareボタンから、”Handoff to Claude Code”ボタンを押下します。

ここで一点注意が必要です。

今回出力されたDesign bundleのREADMEを見る限り、Handoff機能は、Claude DesignによりHTML/CSS/JSで作成されたデザインプロトタイプを、Claude Codeなどのコーディングエージェントに渡してそのままWeb UIとして実装することを想定しているようです。

具体的には、デザインプロトタイプをWeb UIとして実装する旨が記載されたREADME.mdをClaude Design側が自動で作成しており、Claude Codeはその指示を読み取り実装を行う、という仕組みです（README.mdはOPTIONSの”Download zip instead”からzipダウンロードすると確認できます）。

今回の目的はWeb UIの実装ではなく、設計資料に記載されたAWS構成をTerraformコードへ落とし込むことです。そのため、READMEの指示には従わずHTML内の設計内容を読み取ってTerraformコードを生成するよう、以下の通り追加で指示しました。

このHandoff bundleはClaude Designで作成したHTML/CSS/JSベースの設計資料ですが、今回の目的はWeb画面の再実装ではありません。

READMEにはデザインをpixel-perfectに再実装するよう書かれていますが、その指示は今回の目的には従わないでください。

今回の目的は、Design bundle内の `AWS構成説明.html` に記載されたAWS設計内容、構成図、リソース一覧、主要設定値を読み取り、それをもとにTerraformコードを作成することです。

HTML/CSS/JSのUIをReactやWebアプリとして再実装しないでください。
デザインの見た目再現ではなく、設計内容の抽出とTerraform実装を実施してください。

Copy commandボタンでコマンドをコピーし、Claude Code側に貼り付けます。

Claude Code側でDesign bundleを取得できない旨のエラーが出たため、今回はDesign bundleをzipダウンロードし、プロジェクトルートに配置します（この際なので、README.mdは最初から配置しないこととしました）。

気を取り直して、以下のプロンプトでTerraformコード作成の指示を行います。

designbundle/配下に格納されている設計スライドとAWS構成図をもとに、Terraformコードを作成してください。
作業対象は、このリポジトリの terraform/ ディレクトリ配下のみとしてください。

# 目的
Claude Designで作成したAWS構成図から、Terraformコードを生成し、実際にAWS上へapplyできるかを検証します。

# 要件
- Terraformコードは用途ごとにファイル分割してください
- 変数は variables.tf に定義してください
- 出力値は outputs.tf に定義してください
- コンテナイメージは public.ecr.aws/nginx/nginx:latest を使用してください
- terraform fmt / validate が通る構成にしてください

# 作成してほしいファイル例
terraform/
├── providers.tf
├── variables.tf
├── outputs.tf
├── vpc.tf
├── security_groups.tf
├── alb.tf
├── ecs.tf
├── iam.tf
└── cloudwatch.tf

terraformファイルが作成され始めました！

作成が完了し、設計書からの対応関係も出力してくれました。

terraform planで構築内容を確認します。

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # aws_cloudwatch_log_group.ecs will be created
  + resource "aws_cloudwatch_log_group" "ecs" {
      + arn               = (known after apply)
      + id                = (known after apply)
      + log_group_class   = (known after apply)
      + name              = "/ecs/claude-aws-demo"
      + name_prefix       = (known after apply)
      + retention_in_days = 30
      + skip_destroy      = false
      + tags              = {
          + "Name" = "/ecs/claude-aws-demo"
        }
      + tags_all          = {
          + "Name" = "/ecs/claude-aws-demo"
        }
    }

  # aws_ecs_cluster.main will be created
  + resource "aws_ecs_cluster" "main" {
      + arn      = (known after apply)
      + id       = (known after apply)
      + name     = "claude-aws-demo-cluster"
      + tags     = {
          + "Name" = "claude-aws-demo-cluster"
        }
      + tags_all = {
          + "Name" = "claude-aws-demo-cluster"
        }

      + setting (known after apply)
    }

  # aws_ecs_service.main will be created
  + resource "aws_ecs_service" "main" {
      + availability_zone_rebalancing      = "DISABLED"
      + cluster                            = (known after apply)
      + deployment_maximum_percent         = 200
      + deployment_minimum_healthy_percent = 100
      + desired_count                      = 2
      + enable_ecs_managed_tags            = false
      + enable_execute_command             = false
      + iam_role                           = (known after apply)
      + id                                 = (known after apply)
      + launch_type                        = "FARGATE"
      + name                               = "claude-aws-demo-service"
      + platform_version                   = (known after apply)
      + scheduling_strategy                = "REPLICA"
      + tags                               = {
          + "Name" = "claude-aws-demo-service"
        }
      + tags_all                           = {
          + "Name" = "claude-aws-demo-service"
        }
      + task_definition                    = (known after apply)
      + triggers                           = (known after apply)
      + wait_for_steady_state              = false

      + load_balancer {
          + container_name   = "claude-aws-demo"
          + container_port   = 80
          + target_group_arn = (known after apply)
            # (1 unchanged attribute hidden)
        }

      + network_configuration {
          + assign_public_ip = true
          + security_groups  = (known after apply)
          + subnets          = (known after apply)
        }
    }

  # aws_ecs_task_definition.main will be created
  + resource "aws_ecs_task_definition" "main" {
      + arn                      = (known after apply)
      + arn_without_revision     = (known after apply)
      + container_definitions    = jsonencode(
            [
              + {
                  + essential        = true
                  + image            = "public.ecr.aws/nginx/nginx:latest"
                  + logConfiguration = {
                      + logDriver = "awslogs"
                      + options   = {
                          + awslogs-group         = "/ecs/claude-aws-demo"
                          + awslogs-region        = "ap-northeast-1"
                          + awslogs-stream-prefix = "ecs"
                        }
                    }
                  + name             = "claude-aws-demo"
                  + portMappings     = [
                      + {
                          + containerPort = 80
                          + protocol      = "tcp"
                        },
                    ]
                },
            ]
        )
      + cpu                      = "256"
      + enable_fault_injection   = (known after apply)
      + execution_role_arn       = (known after apply)
      + family                   = "claude-aws-demo-task"
      + id                       = (known after apply)
      + memory                   = "512"
      + network_mode             = "awsvpc"
      + requires_compatibilities = [
          + "FARGATE",
        ]
      + revision                 = (known after apply)
      + skip_destroy             = false
      + tags                     = {
          + "Name" = "claude-aws-demo-task"
        }
      + tags_all                 = {
          + "Name" = "claude-aws-demo-task"
        }
      + track_latest             = false
    }

  # aws_iam_role.ecs_task_execution will be created
  + resource "aws_iam_role" "ecs_task_execution" {
      + arn                   = (known after apply)
      + assume_role_policy    = jsonencode(
            {
              + Statement = [
                  + {
                      + Action    = "sts:AssumeRole"
                      + Effect    = "Allow"
                      + Principal = {
                          + Service = "ecs-tasks.amazonaws.com"
                        }
                    },
                ]
              + Version   = "2012-10-17"
            }
        )
      + create_date           = (known after apply)
      + force_detach_policies = false
      + id                    = (known after apply)
      + managed_policy_arns   = (known after apply)
      + max_session_duration  = 3600
      + name                  = "claude-aws-demo-ecs-task-execution-role"
      + name_prefix           = (known after apply)
      + path                  = "/"
      + tags                  = {
          + "Name" = "claude-aws-demo-ecs-task-execution-role"
        }
      + tags_all              = {
          + "Name" = "claude-aws-demo-ecs-task-execution-role"
        }
      + unique_id             = (known after apply)

      + inline_policy (known after apply)
    }

  # aws_iam_role_policy_attachment.ecs_task_execution will be created
  + resource "aws_iam_role_policy_attachment" "ecs_task_execution" {
      + id         = (known after apply)
      + policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
      + role       = "claude-aws-demo-ecs-task-execution-role"
    }

  # aws_internet_gateway.main will be created
  + resource "aws_internet_gateway" "main" {
      + arn      = (known after apply)
      + id       = (known after apply)
      + owner_id = (known after apply)
      + tags     = {
          + "Name" = "claude-aws-demo-igw"
        }
      + tags_all = {
          + "Name" = "claude-aws-demo-igw"
        }
      + vpc_id   = (known after apply)
    }

  # aws_lb.main will be created
  + resource "aws_lb" "main" {
      + arn                                                          = (known after apply)
      + arn_suffix                                                   = (known after apply)
      + client_keep_alive                                            = 3600
      + desync_mitigation_mode                                       = "defensive"
      + dns_name                                                     = (known after apply)
      + drop_invalid_header_fields                                   = false
      + enable_deletion_protection                                   = false
      + enable_http2                                                 = true
      + enable_tls_version_and_cipher_suite_headers                  = false
      + enable_waf_fail_open                                         = false
      + enable_xff_client_port                                       = false
      + enable_zonal_shift                                           = false
      + enforce_security_group_inbound_rules_on_private_link_traffic = (known after apply)
      + id                                                           = (known after apply)
      + idle_timeout                                                 = 60
      + internal                                                     = false
      + ip_address_type                                              = (known after apply)
      + load_balancer_type                                           = "application"
      + name                                                         = "claude-aws-demo-alb"
      + name_prefix                                                  = (known after apply)
      + preserve_host_header                                         = false
      + security_groups                                              = (known after apply)
      + subnets                                                      = (known after apply)
      + tags                                                         = {
          + "Name" = "claude-aws-demo-alb"
        }
      + tags_all                                                     = {
          + "Name" = "claude-aws-demo-alb"
        }
      + vpc_id                                                       = (known after apply)
      + xff_header_processing_mode                                   = "append"
      + zone_id                                                      = (known after apply)

      + subnet_mapping (known after apply)
    }

  # aws_lb_listener.http will be created
  + resource "aws_lb_listener" "http" {
      + arn                                                                   = (known after apply)
      + id                                                                    = (known after apply)
      + load_balancer_arn                                                     = (known after apply)
      + port                                                                  = 80
      + protocol                                                              = "HTTP"
      + routing_http_request_x_amzn_mtls_clientcert_header_name               = (known after apply)
      + routing_http_request_x_amzn_mtls_clientcert_issuer_header_name        = (known after apply)
      + routing_http_request_x_amzn_mtls_clientcert_leaf_header_name          = (known after apply)
      + routing_http_request_x_amzn_mtls_clientcert_serial_number_header_name = (known after apply)
      + routing_http_request_x_amzn_mtls_clientcert_subject_header_name       = (known after apply)
      + routing_http_request_x_amzn_mtls_clientcert_validity_header_name      = (known after apply)
      + routing_http_request_x_amzn_tls_cipher_suite_header_name              = (known after apply)
      + routing_http_request_x_amzn_tls_version_header_name                   = (known after apply)
      + routing_http_response_access_control_allow_credentials_header_value   = (known after apply)
      + routing_http_response_access_control_allow_headers_header_value       = (known after apply)
      + routing_http_response_access_control_allow_methods_header_value       = (known after apply)
      + routing_http_response_access_control_allow_origin_header_value        = (known after apply)
      + routing_http_response_access_control_expose_headers_header_value      = (known after apply)
      + routing_http_response_access_control_max_age_header_value             = (known after apply)
      + routing_http_response_content_security_policy_header_value            = (known after apply)
      + routing_http_response_server_enabled                                  = (known after apply)
      + routing_http_response_strict_transport_security_header_value          = (known after apply)
      + routing_http_response_x_content_type_options_header_value             = (known after apply)
      + routing_http_response_x_frame_options_header_value                    = (known after apply)
      + ssl_policy                                                            = (known after apply)
      + tags_all                                                              = (known after apply)
      + tcp_idle_timeout_seconds                                              = (known after apply)

      + default_action {
          + order            = (known after apply)
          + target_group_arn = (known after apply)
          + type             = "forward"
        }

      + mutual_authentication (known after apply)
    }

  # aws_lb_target_group.main will be created
  + resource "aws_lb_target_group" "main" {
      + arn                                = (known after apply)
      + arn_suffix                         = (known after apply)
      + connection_termination             = (known after apply)
      + deregistration_delay               = "300"
      + id                                 = (known after apply)
      + ip_address_type                    = (known after apply)
      + lambda_multi_value_headers_enabled = false
      + load_balancer_arns                 = (known after apply)
      + load_balancing_algorithm_type      = (known after apply)
      + load_balancing_anomaly_mitigation  = (known after apply)
      + load_balancing_cross_zone_enabled  = (known after apply)
      + name                               = "claude-aws-demo-tg"
      + name_prefix                        = (known after apply)
      + port                               = 80
      + preserve_client_ip                 = (known after apply)
      + protocol                           = "HTTP"
      + protocol_version                   = (known after apply)
      + proxy_protocol_v2                  = false
      + slow_start                         = 0
      + tags                               = {
          + "Name" = "claude-aws-demo-tg"
        }
      + tags_all                           = {
          + "Name" = "claude-aws-demo-tg"
        }
      + target_type                        = "ip"
      + vpc_id                             = (known after apply)

      + health_check {
          + enabled             = true
          + healthy_threshold   = 2
          + interval            = 30
          + matcher             = "200"
          + path                = "/"
          + port                = "traffic-port"
          + protocol            = "HTTP"
          + timeout             = 5
          + unhealthy_threshold = 2
        }

      + stickiness (known after apply)

      + target_failover (known after apply)

      + target_group_health (known after apply)

      + target_health_state (known after apply)
    }

  # aws_route_table.public will be created
  + resource "aws_route_table" "public" {
      + arn              = (known after apply)
      + id               = (known after apply)
      + owner_id         = (known after apply)
      + propagating_vgws = (known after apply)
      + route            = [
          + {
              + cidr_block                 = "0.0.0.0/0"
              + gateway_id                 = (known after apply)
                # (11 unchanged attributes hidden)
            },
        ]
      + tags             = {
          + "Name" = "claude-aws-demo-public-rt"
        }
      + tags_all         = {
          + "Name" = "claude-aws-demo-public-rt"
        }
      + vpc_id           = (known after apply)
    }

  # aws_route_table_association.public_1 will be created
  + resource "aws_route_table_association" "public_1" {
      + id             = (known after apply)
      + route_table_id = (known after apply)
      + subnet_id      = (known after apply)
    }

  # aws_route_table_association.public_2 will be created
  + resource "aws_route_table_association" "public_2" {
      + id             = (known after apply)
      + route_table_id = (known after apply)
      + subnet_id      = (known after apply)
    }

  # aws_security_group.alb will be created
  + resource "aws_security_group" "alb" {
      + arn                    = (known after apply)
      + description            = "ALB: allow HTTP from internet"
      + egress                 = [
          + {
              + cidr_blocks      = [
                  + "0.0.0.0/0",
                ]
              + description      = "allow all outbound"
              + from_port        = 0
              + ipv6_cidr_blocks = []
              + prefix_list_ids  = []
              + protocol         = "-1"
              + security_groups  = []
              + self             = false
              + to_port          = 0
            },
        ]
      + id                     = (known after apply)
      + ingress                = [
          + {
              + cidr_blocks      = [
                  + "0.0.0.0/0",
                ]
              + description      = "HTTP from internet"
              + from_port        = 80
              + ipv6_cidr_blocks = []
              + prefix_list_ids  = []
              + protocol         = "tcp"
              + security_groups  = []
              + self             = false
              + to_port          = 80
            },
        ]
      + name                   = "claude-aws-demo-alb-sg"
      + name_prefix            = (known after apply)
      + owner_id               = (known after apply)
      + revoke_rules_on_delete = false
      + tags                   = {
          + "Name" = "claude-aws-demo-alb-sg"
        }
      + tags_all               = {
          + "Name" = "claude-aws-demo-alb-sg"
        }
      + vpc_id                 = (known after apply)
    }

  # aws_security_group.ecs will be created
  + resource "aws_security_group" "ecs" {
      + arn                    = (known after apply)
      + description            = "ECS tasks: allow HTTP from ALB SG only"
      + egress                 = [
          + {
              + cidr_blocks      = [
                  + "0.0.0.0/0",
                ]
              + description      = "allow all outbound (ECR pull, CloudWatch Logs)"
              + from_port        = 0
              + ipv6_cidr_blocks = []
              + prefix_list_ids  = []
              + protocol         = "-1"
              + security_groups  = []
              + self             = false
              + to_port          = 0
            },
        ]
      + id                     = (known after apply)
      + ingress                = [
          + {
              + cidr_blocks      = []
              + description      = "HTTP from ALB SG"
              + from_port        = 80
              + ipv6_cidr_blocks = []
              + prefix_list_ids  = []
              + protocol         = "tcp"
              + security_groups  = (known after apply)
              + self             = false
              + to_port          = 80
            },
        ]
      + name                   = "claude-aws-demo-ecs-sg"
      + name_prefix            = (known after apply)
      + owner_id               = (known after apply)
      + revoke_rules_on_delete = false
      + tags                   = {
          + "Name" = "claude-aws-demo-ecs-sg"
        }
      + tags_all               = {
          + "Name" = "claude-aws-demo-ecs-sg"
        }
      + vpc_id                 = (known after apply)
    }

  # aws_subnet.public_1 will be created
  + resource "aws_subnet" "public_1" {
      + arn                                            = (known after apply)
      + assign_ipv6_address_on_creation                = false
      + availability_zone                              = "ap-northeast-1a"
      + availability_zone_id                           = (known after apply)
      + cidr_block                                     = "10.0.1.0/24"
      + enable_dns64                                   = false
      + enable_resource_name_dns_a_record_on_launch    = false
      + enable_resource_name_dns_aaaa_record_on_launch = false
      + id                                             = (known after apply)
      + ipv6_cidr_block_association_id                 = (known after apply)
      + ipv6_native                                    = false
      + map_public_ip_on_launch                        = true
      + owner_id                                       = (known after apply)
      + private_dns_hostname_type_on_launch            = (known after apply)
      + tags                                           = {
          + "Name" = "claude-aws-demo-public-subnet-1"
        }
      + tags_all                                       = {
          + "Name" = "claude-aws-demo-public-subnet-1"
        }
      + vpc_id                                         = (known after apply)
    }

  # aws_subnet.public_2 will be created
  + resource "aws_subnet" "public_2" {
      + arn                                            = (known after apply)
      + assign_ipv6_address_on_creation                = false
      + availability_zone                              = "ap-northeast-1c"
      + availability_zone_id                           = (known after apply)
      + cidr_block                                     = "10.0.2.0/24"
      + enable_dns64                                   = false
      + enable_resource_name_dns_a_record_on_launch    = false
      + enable_resource_name_dns_aaaa_record_on_launch = false
      + id                                             = (known after apply)
      + ipv6_cidr_block_association_id                 = (known after apply)
      + ipv6_native                                    = false
      + map_public_ip_on_launch                        = true
      + owner_id                                       = (known after apply)
      + private_dns_hostname_type_on_launch            = (known after apply)
      + tags                                           = {
          + "Name" = "claude-aws-demo-public-subnet-2"
        }
      + tags_all                                       = {
          + "Name" = "claude-aws-demo-public-subnet-2"
        }
      + vpc_id                                         = (known after apply)
    }

  # aws_vpc.main will be created
  + resource "aws_vpc" "main" {
      + arn                                  = (known after apply)
      + cidr_block                           = "10.0.0.0/16"
      + default_network_acl_id               = (known after apply)
      + default_route_table_id               = (known after apply)
      + default_security_group_id            = (known after apply)
      + dhcp_options_id                      = (known after apply)
      + enable_dns_hostnames                 = true
      + enable_dns_support                   = true
      + enable_network_address_usage_metrics = (known after apply)
      + id                                   = (known after apply)
      + instance_tenancy                     = "default"
      + ipv6_association_id                  = (known after apply)
      + ipv6_cidr_block                      = (known after apply)
      + ipv6_cidr_block_network_border_group = (known after apply)
      + main_route_table_id                  = (known after apply)
      + owner_id                             = (known after apply)
      + tags                                 = {
          + "Name" = "claude-aws-demo-vpc"
        }
      + tags_all                             = {
          + "Name" = "claude-aws-demo-vpc"
        }
    }

Plan: 18 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + alb_arn                     = (known after apply)
  + alb_dns_name                = (known after apply)
  + cloudwatch_log_group_name   = "/ecs/claude-aws-demo"
  + ecs_cluster_name            = "claude-aws-demo-cluster"
  + ecs_service_name            = "claude-aws-demo-service"
  + ecs_task_execution_role_arn = (known after apply)
  + public_subnet_ids           = [
      + (known after apply),
      + (known after apply),
    ]
  + vpc_id                      = (known after apply)

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Saved the plan to: tfplan

To perform exactly these actions, run the following command to apply:
    terraform apply "tfplan"

plan結果を確認したところ、想定していた主要リソースが作成対象になっていることを確認できました。

CloudWatch Logsの保持期間やECSタスク数など、コストに関わる設定は環境に応じて調整余地がありますが、今回は検証後すぐにdestroyする前提のため、このままterraform applyで構築を実施します。

Apply complete! Resources: 18 added, 0 changed, 0 destroyed.

5. ステップ3： 疎通確認

AWSマネジメントコンソールから、構築されたリソースを確認します。

ALBからECSへの接続設定が完了していることがわかります。その他、VPC関連リソースやIAM、CloudWatch Logs等のリソースも正しく構築されていることを確認しました。

ブラウザからALBのデフォルトDNS名を指定しアクセスしてみます。

接続ができました！

なお、今回作成したALBやECS Fargateは料金が発生するため、疎通確認後は以下のコマンドで削除しました。

terraform destroy

6. おわりに

今回は、Claude DesignでAWS構成図を含む設計資料を作成し、その内容をClaude Codeへ引き継いでTerraformコードを生成し、実際にAWSリソースを構築するところまで検証しました。

最初に考えていた「インフラ構成のお絵描きからリソース実装までをClaudeで一本化できるのではないか」という仮説については、少なくとも今回のようなシンプルな構成であれば、十分に実現できる感触がありました。

特に良かった点は、設計資料・構成図・Terraformコード作成の流れを、自然言語ベースでつなげられることです。従来であれば、設計資料を作り、構成図を描き、それを見ながらTerraformコードを書く、という工程を人間が手作業でつないでいました。今回は、Claude Designで整理した設計情報をClaude Codeに読み取らせることで、Terraformコードのたたき台をかなり短時間で作成できました。

また、資料やコード生成の品質も高く、今回私が実施したのはClaudeへの指示と生成コードのレビュー、terraform plan、terraform applyの実行だけでした。Claude Designはスライドのテンプレートを指定したり、事前情報として画像やファイルをインプットしたりできるので、それらを活用すればさらなる品質向上が期待できます。

今回はあくまで検証用の簡易構成だったため、大規模なシステム基盤設計・構築にそのまま適用することは難しい（Claude Designの使用量制限も意外とすぐ来るし…）ですが、ちょっとした検証等には使えるのではないでしょうか。

構成図や設計資料のたたき台を作る、Terraformコードの初版を作る、レビュー観点を洗い出す、といった場面ではかなり有効だと思いました。

Claude Design、皆さんもぜひ活用してみてください！

はじめに

こんにちは。フューチャーアーキテクト 製造・エネルギーサービス事業部の柴田です😌 見真の心で本質を探求しています!

BigQuery上のデータに対して、外部APIを呼び出すことなく、クエリ内でGeminiによるテキスト生成やデータ解析する手順をまとめました。サービスに対する対応の手間を減らすために、エラー発生時の推奨アクションを提示しています。

普段のGemini利用と異なる利用料金などについても整理しています。

事前準備

BigQueryとVertex AIを連携させるための設定とモデルを作成します。

全体の構成図

モデル利用のためには、次の設定が必要です。

• 外部接続
• 外部接続で呼び出すモデル

構成図は以下の通りです。

graph LR    %% ノードの定義とラベル    Query[SQL クエリ
ML.GENERATE_TEXT]    subgraph BQ_RemoteModel [BQリモートモデル gemini_model]        direction TB        Model_Config[モデル設定]        Connection[外部接続 vertex_ai_conn
認証の通り道]    end    VertexAI[Vertex AI Gemini API]    %% フローの定義    Query -->|モデルを指定
Connection情報をロード| BQ_RemoteModel    %% 認証とAPI呼び出しのフロー (ここがデータの通り道)    Connection -->|セキュアに通信
API呼び出し| VertexAI    %% スタイリング（Google Cloudカラーをイメージ）    classDef bq fill:#e0f7fa,stroke:#01579b,stroke-width:1px,color:#01579b;    classDef conn fill:#ffccbc,stroke:#bf360c,stroke-width:1px,color:#bf360c,stroke-dasharray: 5 5;    class Query,BQ_RemoteModel,Model_Config bq;    class Connection conn;

外部接続（Connection）の作成

BigQueryコンソールの「データ 追加」 > 「Vertex AI」のデータソースを選択（vertex aiで検索）

外部データへのアクセスで、BiqQueryフェデレーションを選択します。

以下のように、外部データソースとの接続を作成します。

• 接続タイプ：Vertex AI リモートモデル、リモート関数、BigLake, Spanner（Cloud リソース）
• 接続ID：用途が分かりやすい名前にする（接続名なので*_connという命名を推奨）
• ロケーションタイプ：任意のリージョンを選択
• 分かりやすい名前：日本語OKなので利用方法が明確な名前にします
• 説明：より詳細な説明

作成した接続はBigQueryコンソールの「接続」で確認することができます。

リモートモデルの定義

BigQueryから外部のGemini APIを呼び出すための、設定情報（メタデータ）を登録します。
以下のCREATE OR REPLACE MODELクエリを実行してモデルを作成します。
BigQuery内に、Geminiを呼び出すためのモデルを定義します。これは1度だけ実行すればOKです。

CREATE OR REPLACE MODEL プロジェクト名.データセット名.モデル名
REMOTE WITH CONNECTION プロジェクト名.リージョン.先ほど作成した接続ID
OPTIONS (
-- 利用したいGeminiのエンドポイントを指定（例:gemini-2.5-flash, gemini-2.5-pro）
endpoint = '使用するモデル'
);

参考：クエリの具体例は以下の通りです。

CREATE OR REPLACE MODEL `project_id.logexplorer.gemini_model`
REMOTE WITH CONNECTION `project_id.asia-northeast1.logexplorer_ai_conn`
OPTIONS (
endpoint = 'gemini-2.5-flash'
);

クエリを実行すると、指定したデータセットの直下にモデルが作成されます。

モデルの利用

作成したモデルを利用して推論します。ここでは実際のクエリ例を示します。特定の処理で発生したエラーログをBigQueryにリアルタイムで取り込ませている状態で、このようなプロンプトでエラーに対する推奨アクションをAIに教えてもらおうとしています。

あなたは優秀なクラウドデータエンジニアです。
以下のエラーメッセージから原因を推測し、解決のための具体的な「推奨対応方法」を150文字以内で提示してください。
【対象ファイル】：対象ファイル名
【エラーメッセージ】：エラーメッセージ

以下の例はstatus_tag が ‘error’ のログを抽出し、Geminiに推奨アクションを推論させるというクエリです。

-- ====================================================================
-- 目的: status_tag が 'error' のログを抽出し、Geminiに推奨アクションを推論させる
-- ====================================================================
SELECT
timestamp_jst,
service_name,
target_file,
status_tag,
message,
-- JSONレスポンスからテキスト部分のみを抽出（回答の本文のみを取り出す必須処理）
JSON_VALUE(ml_generate_text_result, '$.candidates[0].content.parts[0].text') AS recommended_action
FROM ML.GENERATE_TEXT(
-- ==================================================================
-- モデルの指定
-- 事前に CREATE MODEL で作成した、Vertex AI（Gemini）を呼び出すためのモデルを指定します。
-- ==================================================================
MODEL project_id.logexplorer.gemini_model,
(
-- ================================================================
-- 1. AIに渡すためのデータ（プロンプト）を準備するサブクエリ
-- ================================================================
SELECT
timestamp_jst,
service_name,
target_file,
status_tag,
message,
CONCAT(
'あなたは優秀なクラウドデータエンジニアです。\n',
'以下のエラーメッセージから原因を推測し、解決のための具体的な「推奨対応方法」を150文字以内で提示してください。\n\n',
'【対象ファイル】', IFNULL(target_file, '不明'), '\n',
'【エラーメッセージ】\n', IFNULL(message, 'なし')
) AS prompt
FROM
project_id.logexplorer.logexplorer_errors
WHERE
status_tag = 'error'          -- 指定条件：エラーのみを対象
AND message IS NOT NULL       -- メッセージが空のものは除外（APIの無駄撃ち防止）
ORDER BY
timestamp_jst DESC
),
-- ==================================================================
-- 2. モデルの推論パラメータ設定
-- ==================================================================
STRUCT(
0.0 AS temperature,       -- 0.0にすると回答が固く・決定的になる（エラー分析に適している）
300 AS max_output_tokens  -- 出力される最大トークン数（コスト上限のストッパー）
)
);

利用料金を押さえるためのポイント

これまでの手順で各レコードに対してGeminiを実行できますが、好き放題に利用すると料金が膨らんでいきコストを圧迫してしまいます。

なので、ここでは利用料金を抑えるための解決方法の例を紹介しますす。

Geminiの料金体系（Gemini 2.5 2025年4月29日現在）

• トークン数の比例して課金される（日本語の場合は１文字２トークン）
• 入力・出力の合計トークン数で課金額が決まる

利用料金を抑える方法の例

1. 用途におけるモデルの選択
   上記の表が示すように、FlashとProでは利用料金が3倍以上変わります。普段使いではとりあえず一番性能がいいものを選びがちですが、コストに直結するため複雑な推論を必要としない場合などにはFlashや古いバージョンのモデルを利用します。
2. 同じ質問を何度もしない
   一度推論した結果（プロンプトと回答のセット）はBigQueryのテーブルに保存し、次回以降は JOIN で過去の回答を使い回す。
3. バッチ内重複排除
   2.とやや共通していますが、1回のスケジュール実行内で同じエラーが複数ある場合、GROUP BY や ROW_NUMBER() を使って代表の1件だけをGeminiに投げ、結果を他の行にコピーする。

さいごに

以上、BigQuery内で直接Geminiを実行する方法の紹介でした。

普段Gemiiniに何かを聞くときは料金を気にしないと思いますが、システムに組み込むときにはちゃんと事前にコストを計算しないと、思わぬ請求額へと膨れ上がってしまう可能性があります。特に入力プロンプトは長くなりがちですが、ここは料金にかなり大きく効いてきます。

これからのデータエンジニアリングにとっても、AIを組み込むことが必須になっていますので、その助力になれば幸いです。

参考リンク

• BIqQueryでのAI実行方法
  https://docs.cloud.google.com/bigquery/docs/generate-text?hl=ja
• Vertex AIの料金
  https://cloud.google.com/vertex-ai/generative-ai/pricing?hl=ja
• モデル一覧（実装時に必要なモデルIDを確認できる）
  https://console.cloud.google.com/vertex-ai/model-garden?hl=ja

開発へのAIの活用はまったなしというこで、仕事やら趣味でいろいろ開発しています。せっかくなので、従来の手法をアンラーニングAIをより生かした開発スタイルでやろいうことで、現時点で作法としてまとまっているAI-DLCとSDDなどに入門して試しつつ、普段の業務への適応方法を考えたり、最近してきたことの言語化をしてみます。

開発におけるAI活用はみんな今関心を持っていることかと思います。設計書を作ればコードは自動でできる、というのはよく言われますが、IPAの資料を見るとウォーターフォールだと実装の工数の割合の中央値は23%-32%ぐらい（新規なのか改良なのかで変わる）となっています。仮にここが3倍になっても得られるゲインは全体の7-10%ぐらい。AIで効率アップをしたい！という目標値はだいたいこんなものではないと思うので、そういう観点で見ています。

スペック駆動開発（SDD）

以前、スペック駆動開発(SDD)はFindyさんのイベントで発表させてもらったことがありました。Kiroが提唱した手法です。まずは対話しながらスペックと呼ばれるドキュメント群を作っていきます。Kiroではrequirements.md, design.md, tasks.mdです。その後、タスクに書かれているサブタスクごとに新しいセッションをオープンしながらタスクを進めていきます。

スペック駆動が画期的だった点はドキュメントを作る点ではなくサブタスクごとに新しいセッションを作ってコンテキストあふれが起きにくいようにする、そのために必要な、現在出てきているメモリー機能のようなものを自然に実現できるワークフローになっている点かなと思います。実際、当時のSonnet-3.5とかでもそうですし、コーディング能力が高くないモデルでもそこそこ動いてくれる点です。

ClaudeもCodexもCopilotも、現在はSDDをプランモードという形で取り込んでいます。ぽちっとプランモードを有効にすると、まずはソースコードの修正を封じて、plan.mdなどのドキュメントを作り、そのレビュー後に実装を進めます。今どきのモデルは以前よりは高性能ですし、コンテキスト圧縮でも性能は落ちにくくなっていると感じるのでこれでも十分動いてくれるのでしょう。Claude系モデルはドキュメントといいつつコードスニペットまみれのdesign.mdを書いていたので、ファイルを分ける意味もあまりなかったですし。

スペックの単位

なお、「スペック（仕様）駆動開発」という言葉があまりにも一般名詞の組み合わせすぎるせいか、「それ今までの開発と何が違うのか」みたいな言い方も登場時はされていました。また、仕様という言葉を見て、今までの仕様書相当のものを詰め込むみたいな解説も見られました。

実際にはAIが扱えるコンテキストサイズには限界があるので、システム一本分の要求を入れるということは現実的ではないです。システム開発を行う場合は機能分解をすると思いますが、そういう単位、あるいは大きなリファクタリング見たい感じごとにスペックを作って進めていくのがやりやすいですね。ウェブアプリだと画面ごと（バックエンド込み）とかで進めていくとか。

何を作るかの全体構想やタスクやモジュールに分割して外部仕様の一番外側ぐらいは人間がやりつつ、詳細設計や実装はAIがメインで進めていく、という感じかと思います。

テストを書かせる指示を入れるか？

これも定期的に話題になる気がしますが、今どきのモデルは何も指示しなくてもテストを書いてくれるし、コードを書いたあとに実行して壊れたところの修正もしてくれます。品質維持という点では最低限やってくれます。フロントエンドは何も言わなくてもTypeScriptになるし、型ののチェックも自動です。

テストをレビューするかどうかですが、自動で書かれたテストをレビューする価値はないかなと思います。人間が意思をこめたrequirementsに対してそれが実装されているかどうかは確認すべきですが、AIが勝手に決めた内部実装をレビューする価値はありません。

コーディング規約的なのもある程度の水準で最初から書いてくれます。とはいえ、ちょっとスタイルが古かったりするので、そこは意思入れしてもよいかなとは思います。ただ自然言語でLLMにやらせるとチェックと修正とかなりクレジットを消費するので静的チェックLinterのルールを作ってそれの実行とかがいいですね。

AI-DLC

AI-DLCはAmazonが提唱している、AI中心の開発ライフサイクルにしていくために提案しているあたらしいライフサイクルです。KiroもそうですがこちらもAmazonです。

• AI 駆動開発ライフサイクル:ソフトウェアエンジニアリングの再構築

アジャイルの1-2週間のイテレーションをさらにエクストリームにして1日1回、もしくは数回のボルトというイテレーションを導入します。そして、その中で、インセプションフェーズ（設計）、構築フェーズ（実装）、オペレーションフェーズ（デプロイ）という3つのフェーズを繰り返していきます。

ライフサイクルのすべてをAIが制御し、必要なことはAIが人間に尋ね、AIがどんどんやっていきますよ、とう方針です。なんだかすごそうです。既存のAIコーディングエージェントでAI-DLCを実現するためのハーネスがGitHubで提供で提供されています。個人的に普段使っているCodexは対象にはなかったので、GitHub Copilotに入れてやってみました。

レビューが重い

必要なことは全部AIが聞いてくるので、質問に答えていくだけで適切なエンジニアリングが行われてシステムが出てくる、みたいな感じとのことですが、やってみると、結構細かいところまでガシガシ聞かれて、それにこたえる必要がありました。AIが判断を下すために情報が必要とはいえ、考えるのを後回しにしたいな、というところまで細かく聞かれます。趣味開発なのにすごい仕事している気分というか、そんな気持ちになりました。あと、質問内容はかなりシステム観点での理解が求められるような質問が多い。

AIに大量のものを作らせるのは楽しいと感じるかもしれないが、AIが作った大量のコンテンツを消費させられるのはなんというか消耗が大きいし疲れるな、と。

ちょっと大きな開発に入れるにはアレンジが必要

元Amazonの人から教えてもらったのは、GitHubで提供しているワークフローはあくまでもAI-DLCの体験用プロンプトとのこと。公式READMEにもオペレーションフェーズは将来対応、と書かれています。論文に書かれているフローをきちんとやるには組織に合わせたアレンジだとかが必要とか。

今回、基本機能をまず作ってから追加の機能、みたいに一人で複数ボルトを体験してみようと思いフェーズを分けたのですが、どうもワークフローが複数イテレーションに対応していないのか、途中で前のフェーズの作業のタスクと混雑し始めて、途中で「ここの部分のドキュメントは前のイテレーションだから分けて（ボルトという言葉は通じなかった）」と整理させたりしました。提供されたまま使うのは1ボルト分のあまり大きくないプロダクトには良いがそれなりに工夫が必要かと思います。実際にはきちんとプロジェクト運営をしたことがあって、AIエージェントもわかって、ハーネスエンジニアリングできて、AI-DLCをアレンジできる人が必要そうです。

トークン消費が激しい

ちょっとした機能の修正もすべてドキュメントを整備してから動こうとします。そしてスペック駆動以上に大量に生成されるドキュメントをすべて読み込んで整合性を取ろうとします。たぶん、同じような機能を単純なスペック駆動で開発するのと比べると5倍ぐらいCopilotのプレミアムクレジットを消費しているように思います。

Markdownはちょっとした内容のやり取りにはいいかもしれませんが、大量の文章を横断的に確認して矛盾を検知するみたいなコンパイル言語における型チェックのような仕組みはなく、大量のクレジットを消費して無理くりやっている感じです。形式仕様記述言語も人間が読み書きで判断は難しいのですが、ヒューリスティックではない何かしらの静的解析ができるドキュメント記述フォーマットが生まれない限り、このまま大きくスケールさせるのはちょっと難しい気がします。

今後やるべき実験

普段からCodexが好きなのでCopilotでもCodexを選んでやっていました。エージェントを組み合わせて使う人もCodexはレビューに使って整合性をきちんと取らせるのによい、と言われるので、それだけインセプションフェーズの質問もヘビーよりだったのかもしれません。もっとイケイケでコードをガンガン書くというClaude系モデルにやらせるとまた印象は変わるのではないかと思います。

現時点での使い方

どちらもAIを活用したコーディング自動化の効果は得られます。どちらもAmazonがベースを作ったものですし、どちらも、動くシステムを日々作りながら育てていくという共通点があります。大きく違う点は、要件の整理やタスクの分解までAIにやらせるかどうかです。

現時点のモデルの能力などを考えると、AI-DLCをそのまま実現するにはまだ何段階か技術の進展が必要かも、とは思いますが、大きく活用方法を分けるとイメージとしては以下の2つかなぁと思います。

• アジャイルにタスク整理などを行って実装部分はSDD
• AI-DLCで高速ウォーターフォール

AI-DLCはドキュメントも多く、実装を後回しにしたい部分も要件を固めるためにAIにきちんと情報をインプットしていく必要があります。また、足りない情報はかなり突っ込んで聞いてきます。日次とかで回していくという考え方であってもかなりフロントヘビーな頭の使い方をします。そして、計画変更もそれなりに重くなります。今回のテストでは雑にバイブコーディングで作らせたプロトタイプがあったのでそれを読み込ませてみましたが、既存のコードの分析から要件を固める部分はなかなかよくできているな、と思いました。しかしそれは既存システムがあって、なおかつ大きく仕事の流れが変わらない前提ではうまくいく、ということでそうではない場合はかなり工夫が必要なんじゃないかと思います。ただ、ある程度やることが決まっているなら、頑張って質問に答え続ければ形になっていくので、これはこれで面白い体験でした。

SDDは逆に、現時点できちんとアーキテクチャを考えられて設計できる人からするとかなり気軽です。自分である程度モジュールや機能に分割し、必要な順番で実装していけばいいですし、そのタスクの遂行にだけ必要な情報をインプットすれば良いです。軽めに走らせて動くものができて、それをユーザーと確認して作っていくという流れとはかなりマッチしています。ただし、全体像を全部は作らないし、やってみて方針転換とかがしやすいという点では全体のスケジュール管理やプロジェクト推進はアジャイルに乗せるといいのかなと思っています。

今回のエントリーの出発点はウォーターフォール的なプロジェクトの進め方ではメリットがあまり出ないぞ、という感じで話を進めてきましたが、そもそもアメリカのウォーターフォールの採用割合がかなり少ないということもあり、アメリカ企業から出てくる開発支援のツールの思想がウォーターフォールに考慮していないで作られている点は想像に難くないです。ウォーターフォールかつAI活用だと要件定義とか前段のドキュメント類をいかに早く作るか、が勝負になってくるという点で、AI-DLCの一部適用を模索する必要はあるかと思います。ただ、AIによる開発はうまく歯車が噛み合えば爆速でいける一方、AIと人間のコミュニケーションがボトルネックで工数が読みにくいという扱いがされているのが現状かと思います。機能の境界をしっかり決め、予算も決め、スケジュールをしっかり決めて進みたいというウォータフォールのニーズが減ることはないと思いますが、実装フェーズ周りはアジャイルにしていかないとバッファーを取り過ぎてしまうのではないかという気がします。

まとめ

2つの手法は同じ会社から出てきたということもあり、だいぶ手触りは違いますが似ているものも多いと感じました。どちらもAIの活用度を大きく上げる方針であることは間違いありません。

SDDはお客さんへの技術支援案件ではすでに取り組んだことがあります。要件定義やシステムのユースケースの整理、DFDやERDの分析や設計をある程度形が整うまで伴走し、AI駆動開発の紹介や手ほどきを行ったり、SDDを実現するためのskillsを提供し、実際の実装はお客さんのIT部門の人がSDD（用のハーネスを設定したCopilot）で開発を進めていくという流れでやりましたが、思った以上にうまくいっています。今までのDXは、事業会社のIT人材不足というボトルネックがありましたが、このような伴走型の技術コンサルティングはそこの突破にはかなり追い風になりそうです。

どちらにしても、一筆書きできるような小さいシステムはともかく、大きなシステム、特に様々なシステム間の連携が必要となるような基幹システムだと、まだまだITのスキルが不要にはならなそうだなぁ、と思いました。

はじめに

こんにちは、自宅サーバの運用って実質盆栽だよなって思い始めてる、盆栽未経験の内堀です。今回は自宅サーバでネットワークフォルトを再現してみたよというお話です。

分散システムを勉強していると「ノードが完全に死ぬよりも、中途半端に死んでいるほうが厄介」という話に必ず出会います。完全に死ねばクラスタが検知して切り離せますが、半分生きているとシステムからは正常に見えてしまい、悪さをし続けるからです。というわけで、分散システム入門の第一歩として、今回はこの「中途半端に死んだノード」を自宅サーバ上で再現してみます。具体的には、50%パケロスする設定をノードに仕込み（本記事ではゾンビノードと呼びます）、クラスタへの影響を測定します。

結論から書くと、3ノードのKubernetesクラスタで1ノードのネットワークだけ半壊させたところ、クラスタ全体のスループットが1/14、p99レイテンシが15倍に悪化しました。以下、この数字に至るまでの話を書いていきます。

実験の概要

構成

3ノード（home-lab-1, home-lab-2, home-lab-3）のk3sクラスタで、以下を用意します。

• nginxのDeployment（replicas=3、各ノードに1Podずつ配置されるようtopologySpreadConstraintsで制約）
• 上記を束ねるClusterIP Service
• 計測用のデバッグPod（curlとohaが入ったalpineベース、control-planeで元々負荷の軽いhome-lab-1に固定）

実験の流れ

以下の3段階で計測し、それぞれを比較します。

1. ベースライン計測：パケットロスなしの状態で計測
2. 半壊状態の計測：worker2（home-lab-3）のOS上で tc qdisc add ... netem loss 50% を実行し、パケットロス50%を発生させた状態で計測
3. 完全停止状態の計測：worker2上で systemctl stop k3s-agent を実行し、Kubernetesから完全に切り離された状態で計測

各段階で、デバッグPodからService経由でnginxを叩いて挙動を観察します。具体的には、軽い疎通確認としてcurlを60回ループで回して各Podへの振り分けを見て、その後ohaで20000リクエスト投げてSuccess rate、RPS、レイテンシ分布を計測します。

実験

実験1：ベースラインの計測

まずはパケットロスなしの状態で計測します。比較対象になる数字を取るのが目的です。

Podが3ノードに1つずつ分散配置されていること、ServiceのEndpointsに3つのPod IPが揃っていることを確認します。

$ sudo kubectl -n zombie-exp get pod -o wide
NAME                     READY   STATUS    RESTARTS   AGE   IP            NODE
nginx-84888755c4-l7xtn   1/1     Running   0          13h   10.42.2.82    home-lab-3
nginx-84888755c4-vf9zs   1/1     Running   0          20h   10.42.1.213   home-lab-2
nginx-84888755c4-z94f4   1/1     Running   0          20h   10.42.0.31    home-lab-1

$ sudo kubectl -n zombie-exp get endpoints nginx
NAME    ENDPOINTS                                    AGE
nginx   10.42.0.31:80,10.42.1.213:80,10.42.2.82:80   20h

3Pod、3ノードに分散、Endpointsに全部入っている状態。期待通りです。

疎通確認

デバッグPodからcurlを60回ループで回して、各Podにほぼ均等に振り分けられていることを見ます。nginxはpostStartで自分のhostname（=Pod名）をindex.htmlに書き込んでいるので、レスポンスを見ればどのPodが応答したかわかります。

$ sudo kubectl -n zombie-exp exec debug -- sh -c 'for i in $(seq 1 60); do curl -s --max-time 2 http://nginx.zombie-exp.svc.cluster.local/ || echo FAIL; done | sort | uniq -c'
    19 nginx-84888755c4-l7xtn
    19 nginx-84888755c4-vf9zs
    22 nginx-84888755c4-z94f4

19/19/22でほぼ均等。FAILは0件。

定量計測

ohaで20000リクエスト、コネクション並列度30、--disable-keepalive でリクエストごとにTCP接続を張り直す設定で計測します。keep-aliveを切っているのは、後段の半壊状態でTCPハンドシェイクのSYNパケットがロスする様子をはっきり見るためです（keep-aliveを有効にすると同じコネクションを使い回してしまい、ロスの影響が見えにくくなります）。

$ sudo kubectl -n zombie-exp exec debug -- oha -n 20000 -c 30 -t 2s --disable-keepalive http://nginx.zombie-exp.svc.cluster.local/

Summary:
  Success rate: 100.00%
  Requests/sec: 1620.8811

Response time distribution:
  50.00% in 2.0985 ms
  90.00% in 69.1044 ms
  99.00% in 108.9357 ms

Status code distribution:
  [200] 20000 responses

20000リクエスト全成功、1620RPS、p50が2ms、p99が109ms。自宅サーバの3ノードk3sクラスタとしてはこんなもんかなと思います。
これがベースラインの数字。以降、半壊と完全停止の結果はこれと比較していきます。

ちなみに、実行中は以下の画像のように、レイテンシ分布が更新されながら進んでいくのが見えます。

実験2：home-lab-3をゾンビノードにして計測

worker2（home-lab-3）にパケットロス50%を注入します。Linuxの tc コマンドの netem モジュールを使います。

$ ssh worker2 "sudo tc qdisc add dev eth0 root netem loss 50%"

これでeth0から出入りするパケットの50%がランダムに落ちるようになります。

Kubernetesから見たノードの状態

ここが今回の実験の核心です。50%のパケロスを発生させた直後の状態を見ます。

$ sudo kubectl get nodes
NAME         STATUS   ROLES           AGE   VERSION
home-lab-1   Ready    control-plane   73d   v1.34.3+k3s3
home-lab-2   Ready    <none>          73d   v1.34.3+k3s3
home-lab-3   Ready    <none>          73d   v1.34.3+k3s3

$ sudo kubectl -n zombie-exp get endpoints nginx
NAME    ENDPOINTS                                    AGE
nginx   10.42.0.31:80,10.42.1.213:80,10.42.2.82:80   20h

home-lab-3はReadyのまま。Endpointsからも外れていません。これがゾンビノードです。

なぜこうなるかというと、Kubernetesはkubeletがapiserverに対して定期的にハートビートを送ることでノードの生死を判定しています。50%のパケロスがあっても、TCPの再送機構によってハートビートはなんとか届くので、Kubernetesから見ればノードは正常稼働中ということになります。

疎通確認

次に、curlでの各Podへの振り分け状況を確認します。FAILが7件発生。home-lab-3上のPod（l7xtn）に振り分けられたリクエストは、半分くらいは2秒のタイムアウト内に応答が返ってきますが、半分くらいはパケロスによって失敗してFAIL扱いになります。

ベースラインではFAIL=0だったところに、いきなり12%が失敗するようになりました。「ノードはReady、でもユーザのリクエストは落ちる」が起きている状態です。

$ sudo kubectl -n zombie-exp exec debug -- sh -c 'for i in $(seq 1 60); do curl -s --max-time 2 http://nginx.zombie-exp.svc.cluster.local/ || echo FAIL; done | sort | uniq -c'
      7 FAIL
     18 nginx-84888755c4-l7xtn
     18 nginx-84888755c4-vf9zs
     17 nginx-84888755c4-z94f4

定量計測

$ sudo kubectl -n zombie-exp exec debug -- oha -n 20000 -c 30 -t 2s --disable-keepalive http://nginx.zombie-exp.svc.cluster.local/

Summary:
  Success rate: 90.50%
  Total:        219.8244 sec
  Requests/sec: 90.9817

Response time distribution:
  50.00% in 0.0008 sec
  90.00% in 0.8245 sec
  99.00% in 1.6341 sec

Error distribution:
  [1899] timeout

数字を並べてみるとこんな感じ。

• Success rateが90.5%に低下
• 1899件のタイムアウトエラー
• RPSが1620→91と、ベースラインの5.6%まで激減
• 20000リクエスト消化に12秒だったのが、220秒
• p99が109ms→1634msと、約15倍に悪化

正直、ここまで悪化するとは思っていませんでした。1台のゾンビノードが混ざったことで、クラスタ全体のスループットが18分の1まで落ち込みました。
面白いのがp50で、0.8msとベースラインの2.1msより速く見えます。これは「運よくロスに当たらず1発で通ったリクエスト」が半分弱あって、それらは普通に高速だからです。ロスに当たったリクエストはTCPの再送タイムアウト(初期RTOが1秒)に引っかかってp90以降で秒オーダーまでぶっ飛びます。「半分は普通に速い、半分は秒オーダーで遅い」という2山型(バイモーダル)の分布になっています。

実験3：home-lab-3を完全停止させて計測

最後に、worker2のk3s-agentを完全に止めて計測します。「ネットワーク半壊」と「ノード完全停止」のどちらがマシか、という比較が目的です。

Kubernetesから見たノードの状態

実験2ではhome-lab-3はReadyでしたが、今回はNotReadyになりました。

$ sudo kubectl get nodes
NAME         STATUS     ROLES           AGE   VERSION
home-lab-1   Ready      control-plane   73d   v1.34.3+k3s3
home-lab-2   Ready      <none>          73d   v1.34.3+k3s3
home-lab-3   NotReady   <none>          73d   v1.34.3+k3s3

PodとEndpointsの状態も確認します。

$ sudo kubectl -n zombie-exp get pod -o wide
NAME                     READY   STATUS        RESTARTS   AGE   IP            NODE
nginx-84888755c4-blc65   0/1     Pending       0          27s   <none>        <none>
nginx-84888755c4-l7xtn   1/1     Terminating   1          14h   10.42.2.82    home-lab-3
nginx-84888755c4-vf9zs   1/1     Running       0          21h   10.42.1.213   home-lab-2
nginx-84888755c4-z94f4   1/1     Running       0          21h   10.42.0.31    home-lab-1

$ sudo kubectl -n zombie-exp get endpoints nginx
NAME    ENDPOINTS                      AGE
nginx   10.42.0.31:80,10.42.1.213:80   21h

home-lab-3上のPod（l7xtn）がTerminatingになり、EndpointsからもIP 10.42.2.82 が外れました。Service経由のトラフィックは健全な2Podだけに流れます。新しいPod（blc65）はPendingですが、各ノードに1Podまでの制約をかけているので置き場所がない、というだけで、Endpointsには影響しません。期待通りの挙動です。

疎通確認

curlで各Podへの振り分け状況を確認します。
FAIL=0。home-lab-3上のPod（l7xtn）はEndpointsから外れているので、振り分け先には現れません。健全な2Podだけで応答が返っています。

$ sudo kubectl -n zombie-exp exec debug -- sh -c 'for i in $(seq 1 60); do curl -s --max-time 2 http://nginx.zombie-exp.svc.cluster.local/ || echo FAIL; done | sort | uniq -c'
     34 nginx-84888755c4-vf9zs
     26 nginx-84888755c4-z94f4

定量計測

$ sudo kubectl -n zombie-exp exec debug -- oha -n 20000 -c 30 -t 2s --disable-keepalive http://nginx.zombie-exp.svc.cluster.local/

Summary:
  Success rate: 100.00%
  Requests/sec: 1267.3896

Response time distribution:
  50.00% in 1.9522 ms
  90.00% in 91.6390 ms
  99.00% in 193.9529 ms

Status code distribution:
  [200] 20000 responses

Success rateは100%に戻りました。RPSは1267で、ベースラインの78%程度。Pod数が3→2に減ったので、スループットは下がりましたが、それだけです。p99も194msとベースラインの109msから少し悪化していますが、実験2の1634msと比べれば誤差みたいなものです。
Kubernetesがhome-lab-3をNotReadyと判定し、Endpointsから自動で外してくれたおかげで、リクエストはちゃんと返ってきます。ゾンビノードが混ざっているときと比べると、随分と平和な数字です。

実験結果のまとめ

3つの実験結果を表にまとめます。

ゾンビノードありと完全停止を並べてみると、こうです。

• スループット:完全停止の1/14
• p99:完全停止の8.4倍
• Success rate:完全停止より9.5ポイント低下

ノードが「壊れている」という点はどちらも同じです。違うのは、Kubernetesがそれを検知できるかどうか。検知できれば勝手に退避してくれるけど、検知できなければ放置されたまま。たったそれだけの差で、結果がガラッと変わりました。

冒頭で書いた「中途半端に死んでるほうが厄介」を、実験を通して確認できました。

おわりに

今回はシンプルなHTTPリクエストのみを確認しましたが、これがDB接続のような状態を持つ処理であれば、コネクションを掴んだまま離さないリクエストがプールを食いつぶし、連鎖的な障害を招くことは容易に想像できます。

しかも厄介なことに、Kubernetes側の仕組みだけでは半壊状態を検知することが難しく、ノードがReadyである限り異常として処理されません。実際にネットワークフォルトを再現してみたことで、ゾンビノードが全体にどのような被害を及ぼすのか、解像度が上がりました。

それにしても、不調なのに「大丈夫です」と返すWorkerと、それを真に受けて普通に仕事を振り続けるControl plane。この関係はどこか見覚えがあって、なんだか親近感が湧くのは僕だけでしょうか。

春の入門祭り2026の3本目です。

1. はじめに

CSIGの星名です。今回は、お問い合わせ対応業務にLLM Agentを導入してみたお話です。

最近、開発の現場では、PdMやプログラミング、QAといった役割ごとにAgentを使い分ける手法が、当たり前のように語られるようになってきました。

一方で、非開発業務に目を向けてみると、議事録作成のような単発の活用は進んでいるものの、業務フロー全体をAgentが駆動するような事例は、まだまだ少ないと感じています。というのも、定型業務であればあるほど、そのチーム固有の知識や運用ルールに強く依存するため、外へ向けた知見として一般化しづらい、という側面があるからでしょう。

だからこそ、こうした現場でAgentを活かすには、「何を渡し、どう保つか」を設計する Context Engineering が重要になる。少なくとも私たちのケースではそういう結論になりました。

この記事では、私たちが実際に悩みながら取り組んだプロセスを共有します。

1.1 プロンプトを磨いても、エージェントは賢くならなかった

GitHub Copilot Agent を導入して、 問い合わせ対応の「調査～回答文作成～レビュー」を仕組み化 しようと試みたときの話です。いざ動かしてみると「さっき調べたことを忘れる」「指示を無視する」といった事象が頻発しました。当初はプロンプトの書き方の問題かなと考えていたのですが、プロンプトの書き方以前に、そもそも LLM に何をどう渡すかという「コンテキストの設計」に課題がありました。

本当の失敗モードはプロンプトが悪いことではなく、コンテキストの組み立て（context assembly）が悪いこと

— Andrej Karpathy

設計を見直す中で参考になったのが、LangChain 等で提唱されている Select, Write, Isolate, Compress の 4 戦略です。

Context Engineering for Agents — LangChain Blog

1.2 試行錯誤のポイントとなった 3 つの論点

この 4 戦略を軸に、取り組んだ内容を 3 つの観点で紹介します。

1. 何を渡せば仕事ができるか（情報の形式知化）
   散在する資料や暗黙知を、LLMが確実に読み取れる「知識」としてどう整えるか
2. どう思考の状態を保つか（文脈の引継ぎ）
   会話の長期化による劣化を防ぐために、一連のプロセスをどう区切り、成果物を引き継いでいくか
3. どう期待通りに動いてもらうか（振る舞いの実装）
   実現したい業務フローに対し、ツールの機能をどう組み合わせてAgentの動きを定義するか

1 や 2 でお話しすることは、開発者目線だと、目新しいテクニックというよりはこれまで大切にされてきた基本に近いものかもしれません。ただ、非開発業務で実践してみてもやっぱりこれが大事なんだな、という感覚がありました。そんな私たちの実践知もあわせて紹介します。

3 に関しては、GitHub Copilot Agent を前提としています。特に handoff は Copilot 固有の機能なので、他のツールでは別の工夫が必要になるかもしれません。私たちの業務（技術調査が中心など）に合わせた内容ですが、Agent を業務に組み込むときの考え方の一例として、何かのヒントになれば幸いです。

2. 何を渡せば仕事ができるか

エージェントも前提知識がないことには仕事のしようがないので、まずは何を読ませるかという視界をどう整えてあげるか。そこから話を始めることにします。

2.1 エージェントに「材料」をすべて渡す

最初に取り組んだのは、問い合わせ対応に必要な情報を git submodule で一つに集約した「巨大リポジトリ」を作ることでした。コードもマニュアルも、git clone 一発ですべてが手元に揃う。いわば、エージェントにまず物理的な視界（Select）を与える作業です。まずは必要な情報をすべてエージェントの目の前に置く。物理的な土台を作るだけでも、一定の成果はありました。

2.2 暗黙知となっていた「対応の作法」を言語化する

ただ、材料を揃えただけでは、的外れな回答が目立ちました。文脈を知らないエージェントが、足りない情報を勝手な推測で補って回答を作ってしまう。そういう状況でした。

原因は、ソースコードや Wiki といった「情報の断片」はあっても、それをどう扱うかという 「仕事の作法」 が欠けていたことでした。

問い合わせ対応は、調査結果をそのまま伝えればよいわけではありません。相手が求めている情報をどう選ぶか。どの順番で伝えるか。出してよい情報の境界線はどこか。どこまでを今回の合意の着地点とするか。

こうした対応の要諦は、熟練メンバーなら無意識にやっていることです。Wiki を作る際にも、わざわざ書くのは冗長だと感じて、あえて省いてきた部分でした。これを丁寧に言語化（Write）することが、非開発系の業務においては特に重要でした。

具体的には、いまはどのフェーズなのか。目的は何か。何を成果物として、どんな観点で取り組むのか。そういった業務フローを一つずつ書き出していきました。

2.3 業務フローを書いたら、そのままエージェントへのインプットになった

ポイントは、AI のための特別なファイルを作ったわけではない、ということです。複雑なスクリプトを書いたわけではなく、あくまで「こういうときはこうする」というレベルの業務知識を整えただけ。それがそのまま、Agent へのインプットになりました。

Agent 定義の設計では、Anthropic の Progressive Disclosure（段階的開示） の考え方も参考にしました。「新人向けオンボーディングガイド」のメタファで設計すると良いという話で、納得感がありました。

Skills は「新人向けオンボーディングガイド」のメタファーで考えると設計しやすい。

— Equipping agents for the real world with Agent Skills — Anthropic Engineering

3. どう思考の状態を保つか

「何を渡すか」を整えたら、次は「どうやり取りするか」の話です。

3.1 一つの長い会話は劣化する

はじめは何も考えず、手軽に1つのチャットセッションですべてを完結させようとしていました。調査から回答方針の作成、回答文作成、レビューまで。

ところが、会話が長くなるにつれ、エージェントの挙動が明らかに怪しくなりました。さっき調査したはずのことを忘れたり、同じことを何度も聞き返してきたり。あるいは、前後のつじつまが合わない回答を平気で出力し始める。

こうした劣化は Lost in Conversation という現象として知られています。Philippe Laban らによると、マルチターンの会話では、わずか 2 ターン目から性能低下が始まり、精度が大幅に落ちてしまうのだそうです。

LLMs Get Lost in Multi-Turn Conversation (2025)

これは2025年の調査ですが、一方で、いまの多くのモデルの挙動をみていると、コンテキストウィンドウが圧迫され始めると、会話を要約して空きを作っている様子がみてとれます。ただ、その要約の過程で必要な情報が抜け落ちてしまうことが頻繁に起こっていて困るなぁと思うときもあります。特に不具合調査では意外なところにヒントが落ちていたりするので。

また、Lost in the Middle と呼ばれるように、情報量が増えるほど「中ほどに書かれた情報」を軽視してしまう性質もあります。

Lost in the Middle: How Language Models Use Long Contexts (2024)

結局、一つの会話で全部をこなすのは、そもそも筋が悪かったということでした。現場で感じていた「なんだか話が通じなくなる」という感触の正体が見えました。

3.2 いつでもセッションを捨てられるよう、成果物をファイルに「逃がす」

長い会話が劣化するなら、いつでもセッションを切り直せる状態にすればいい。ということで、履歴という曖昧な記憶に頼るのをやめて、成果物を「記録」としてファイルに逃がす方針にしてみました（Compress & Isolate）。

具体的には、まず 会話履歴.md を用意し、調査工程ではそれを読み込んで 調査結果.md を吐き出す。後続の工程は、その2つのファイルだけを読めば仕事ができる状態にする。という構成にしました。

このファイルを介したリレー方針には、いくつか利点がありました。

• セッションの断絶を恐れなくていい
  調査フェーズなどは時間がかかり、セッションが切れがちです。こまめにファイルへ書き出しておけば、事故が起きても「最新のファイル」からいつでも再開できます。
• 情報の純度を保てる
  前の会話にあった「試行錯誤のノイズ」を捨て、整理された結果だけを次に渡せます。エージェントにとっても、その方が圧倒的に読みやすいはずです。
• 人間が「横入り」しやすい
  書き出されたファイルは人間も編集できます。エージェントの調査が甘ければ、人間がファイルを直接直して次へ進める。この「手戻りのしやすさ」が、実運用では大きな安心感になりました。

結局、履歴という過去の蓄積を無理に引きずるより、成果物という今の結論だけを引き継いでいく方が、設計としては筋が良かったと感じています。

4. どう期待通りに動いてもらうか

ファイルを「逃がす」方針が決まったら、次はそれを扱うAgentをどう作るかについてです。ここからはかなり今回の実装に寄った具体的な話に移っていきます。

4.1 要件整理：入出力の管理と人間との協調

Agent への業務指示に関しては、2.2で手順書を整備しているので、「このリンクを読んで指示に従ってください」で終わります。楽ちんです。

その上で、Agent に求める要件を改めて整理してみました。

• 要件①：セッションの入出力管理
  • 整備した業務指示を確実に読み込めること
  • 前の工程が吐き出した「成果物ファイル」を、新しいセッションのインプットとして引き継げること
  • 自分の仕事を終えたら、また結果をファイルに書き出すこと
• 要件②：人間との協調
  • フェーズの区切りで必ず立ち止まり、人間がレビューを挟めること（調査が間違えば回答も間違うため、あえて一気通貫にはしない）
  • 次にどの工程へ進むかは、勝手に判断せずに人間の指示を仰ぐこと

「フェーズごとに停止して人間が確認する」という運用を前提に、今回は業務フローを 「起票・調査・回答方針作成・回答文作成・レビュー」のフェーズに切り分け ました。

この管理上の「区切り」を、具体的に Copilot のどの機能で具現化するか、ここからはツールの仕様に基づいた具体の話になります。

4.2 技術選定：Custom Agent指定で指示を確実にロードさせる

要件①の入出力管理において、まず解決すべきは「プロンプト以前に、そもそも指示がAgentに届くか」という問題です。GitHub Copilot には指示を置く場所がいくつかありますが、仕様上の振る舞いがそれぞれ異なります。

どれが今回の実務に適しているのか、整理したのが以下の図です。

Agentの振る舞いをどう定義するか
│
├─ 常に適用したい（プロジェクト共通ルール）
│   ├─ 全Agent共通 → copilot-instructions.md / AGENTS.md
│   └─ 特定ファイル操作時のみ → *.instructions.md (applyTo)
│       └─ ⚠ ファイル操作を伴わない業務には不向き
│
├─ 特定タスクの時だけ使いたい
│   ├─ 定型プロンプトを再利用 → *.prompt.md
│   ├─ 専門ロールとして振る舞わせたい → *.agent.md ★
│   └─ 専門知識を必要時だけ読み込ませたい → skills/SKILL.md
│
└─ 外部ツール・APIと連携したい → MCP Servers / Hooks

結論から言えば、今回のケースでは .github/agents/*.agent.md（Custom Agent） を選ぶのが最も手堅いという判断になりました。

補足すると、当初は .github/instructions/*.instructions.md を試していましたが、無視される挙動が頻発しました。これは、applyTo で指定したファイルパターンを操作していないと指示がロードされないという仕様上の制約があるためです。コードファイルの操作を伴わない運用業務には向きませんでした。

UIから明示的に指定した瞬間に、コンテキストとして確実にロードされる。この確実性を買って、Custom Agent をベースにした構成を選んでいます。

4.3 全体像：handoff 機能による人間主導のフロー

これで要件①はクリアです。次は要件②、人間との協調です。

ここで使ったのが、GitHub Copilot の handoff 機能です。handoff とは、Agent が会話の中で次に推奨する Agent をボタンとして Copilot Chat のウィンドウに提示し、人間がワンクリックでそのエージェントを選択・起動できる仕組みです。

どの Agent を候補として提示するかは Agent 側が判断してくれるので、人間のフェーズ制御をサポートする立ち位置になります。各フェーズ（起票 → 調査 → 回答方針 → 回答文作成 → レビュー）に対応した agent.md をそれぞれ作成し、窓口となるオーケストレーター Agent がこれらを handoff 候補として提示します。人間がどのフェーズに進むかを選択する。これで、フェーズごとの停止と人間レビューが自然に実現できました。

加えて、handoff 先の Agent はメイン Agent としてフルのコンテキストウィンドウを使えます。成果物はファイルに書き出し、次の Agent がそれを読み込むので、会話履歴の蓄積による劣化もありません。

参考：利用イメージ

1. 会話開始時に GitHub Copilot チャットウィンドウから 「inquiry」Custom Agent を指定
2. 問い合わせ内容を貼り付け（機密情報はマスクしておく）

3. チャット下部に次フェーズ開始ボタンが現れるので、任意を押下
4. ボタン押下でagent、プロンプトが自動入力されるので送信するだけ

5. 各フェーズが終われば次ののhandoffボタンを押下で、次のフェーズへ移行

参考：SubAgent パターンとの比較

補足になりますが、他のパターンとして、Orchestrator が SubAgent を自動で呼び出す方式（runSubagent）も検討しましたが、不採用としています。

上記の比較はあくまで「人間がフェーズ間でレビューを挟む」という私たちの要件に照らしたものです。全自動化パイプラインや人間レビューが不要な定型タスク、高スループットが優先される場面では、SubAgent パターンの方が適しているケースも十分あります。

参考: GitHub Copilot サブエージェントによるオーケストレーター パターンの実践 — openjny

4.4 業務知識が整理されていれば、agent.md は薄くて済む

Custom Agent + handoff chain という構成が決まったところで、では agent.md に実際に何を書いたか。frontmatter と、整備した手順書ファイルへの参照リンク、成果物ファイルの入出力指示のみです。業務知識の本体はあくまで手順書ファイル側にあるので、agent.md 自体は非常に端的。高度なスクリプトも複雑なパイプラインも書いていません。業務知識を形式知化しておいたおかげで、Agent のために特別な仕組みを作り込む必要がなくなりました。業務フローの言語化がそのまま Agent へのインプットになっているので、ツールへの依存は薄く済んでいます。

scaffolding（モデル補助コード）は次のモデルで不要になる。
投資 vs 待機のトレードオフを常に意識

— Boris Cherny (Anthropic), Y Combinator インタビュー

個人的に納得感のある考え方で、今回 agent.md を薄く保ったのも同じ理由からです。モデルが進化すれば文言を調整するだけで済むはずで、過度にツール依存した自動化は次のモデルで丸ごと不要になるリスクがあると感じています。

まとめ

今回は、お問い合わせ対応の調査～回答作成の業務を 人間とLLMでうまく協調するための運用フローについて考えてみました。

1. 何を渡せば仕事ができるか（Select & Write）
   暗黙知をなくし業務フローを言語化したことが、そのまま Agent へのインプットになった
2. どう思考の状態を保つか（Isolate & Compress）
   長い会話ではコンテキスト管理が難しくなる傾向がある。会話履歴ではなくファイルをリレーすることで、新鮮なコンテキストを保てた。
3. どう期待通りに動いてもらうか（Select）
   handoff 機能で入出力管理と人間との協調を両立できた。
   業務知識が整理されていれば agent.md は薄くて済む

モデルの進化で最適解も変わっていくと思うので、引き続き試行錯誤しながらアップデートしていくつもりです。

問い合わせ業務に限らず、LLM を業務に組み込む際の参考になる部分があれば幸いです。

1. はじめに

はじめまして。TIG - Technology Innovation Group - の清水です。2016年3月に転職してきて、10年経ったインフラ屋さんです。前職コンピュータメーカーには15年いました。

4月は新社会人が街に目立つ季節です。桜と新しいスーツの組み合わせが素敵ですね。ということで、OJTを進める上で大事なこと、を「春の入門祭り2026」に合わせて共有します。Futureでは数ヶ月の新人研修の先にOJTがやってくるので、実際にはもう少し先の話ですね。

2. これだけやろうOJT　やること・目的

仕事をする中で、人びとが同じような落とし穴に、同じように嵌まってもがく状況をみてきました。もちろん私ももがいてきました。「これどうにかして丸っと全部解消できないかな」と考えていたら、OJTの進め方に行きつきました。

「これだけ」と言いながら3つ書きます。ずるいですね。

2.1. ともに希望を語る

目的： 新人さんも、チームもワクワクするため。だって楽しい方がいいから。

説明： 一歩目は希望を抱くところから。最初、新人さんは不安です。汝のなりたい姿を述べよ！と言っても難しいかもです。持っている情報も少ないですし。とりあえずあなたの2年後の姿想像したよ・こんなんどうかな、と先輩が提示してみると、そこから考えが進むかもしれません。互いに希望を話し合い、未来の姿をともに見えるようにしていくと、日々の活動が楽しくなります。

2.2. あの人はどうなったら嬉しいのだろう、をともに語る

目的： 仕事の勘所をつかむため　＆　できるかも、を感じるため

説明： 中核です。「こうすれば仕事はうまくいく」というゲームの基本ルールを理解する活動です。暗記テストで点をとるには、音読・黙読・筆記が有効ですが、仕事は違います。「あの人はどうなったら嬉しいだろう」を考える、が基本動作です。みんな消費者としてはベテランなので、やってみると大事な部分が分かるぞ！という感覚が得られます。全体が把握できるかも感も出てきて、ついでにこの仕事、すんごく意味あるじゃん！と楽しくなります。楽しいことはいいことです。

2.3. 美しさ、と仕事を同時に語る

目的： 道から外れないため　＆　使命を見つけるため

説明： 応用です。油断すると仕事は経済合理性と効率一辺倒になりやすいです。ビジネスなので一見正しく見えますが、倫理を忘れた追求により複数の企業で悲しい事件が起きています。それを起こさないためには、現場での美しさの感覚がもっとも大切です。美しさを意識して仕事をすると、道から外れないだけでなく、その先に何を見出すか、という使命に近づくことができ、仕事が楽しくなります。

これで全部です。シンプルー。

もうちょっと詳しく、と思ってくれた方のために細かく説明します。

3. これだけやろうOJT　詳しいやり方

具体何をするか、と考え方を書きます。

えーと、長いです。

3.1. ともに希望を語る

ある日、新人さんがチームにやってきます。

先輩のやること

2年後のその人の姿を絵にして見せましょう。こんなふうになっていたら、その人は楽しいんじゃないかな、と想像しながら用意します。絵が良いです。絵には解釈の余地を残せるのと、色使いで心持ちを想像させる良さがあります。私が使ったことのある主題はこちらです。

• 言葉の魔術師
• 兵站の鬼
• 俺的ベスト案マン

新人さんの頭の中とは、当然ずれがあります。時間をかけて、2年後の誰々さん像をチームで作っていきます。新人さんの中にすでに明確な像があったら素敵ですね。是非取り込みましょう。

新人さんのやること

自分に二つ名をつけましょう。気楽に。ちがうな、と思ったら後で変えればいいです。変えても世界は滅ばないので大丈夫です。過去にはこんなのがありました。

• 体力化け物ツヨツヨ論理マン
• 飛躍する思考力、土台の耐久力
• 心は熱く、頭はクールに、歩みは着実に

説明・どこを目指すか

いつか新人さんを送り出す日が来ます。その時にはもう”新人さん”ではないでしょう。

「次のプロジェクトに、私はこの人をどう自慢しながら送り出してあげられるだろう」

送り出すその日を考えて、OJTを過ごします。

• この人はどんな特性だろう
• 仕事をうまく進めるための力のうち、この人の得意はどれだろう
• この人の苦手は、どんな人との組み合わせでうまくいくだろう

これを新人さんとともに考えます。チームで作りあげていく希望です。2年後の像と二つ名は、それを考える助けになってくれます。

OJT開始、ということで案件の説明をし、タスクを実際にやってもらいます。何に心をおきながら日々活動すると良いか。以降説明します。

3.2. あの人はどうなったら嬉しいのだろう、をともに語る

やること

最初に任される仕事で嬉しさ分析をやりましょう。

画面開発・打鍵テスト・ハード設計・障害テスト、何でも良いです。でもその仕事をすると、絶対に誰かは嬉しいです。誰がどう嬉しいか、を書き出します。

• 自チームメンバー
• 自チームリーダー
• 隣のチーム
• プロジェクト全体のリーダー
• お客さんの担当の方
• その上司の方
• 部長さん、社長さん
• 最後の最後の、本当のお客さん

新人さんがいきなりやるのは大変なので、まず先輩がやってみせます。もし先輩が分からなかったら大チャンスです。兎に角みんなで想像を言い合って仮説を作り、分かりそうな人に聞いてみましょう。コツは「最後の最後の、本当のお客さん」から考え出すことです。みなさん消費者としてはベテランなので、実は一番大事なところの知見・実感を既に持っています。

この嬉しさ分析を色んなタスクで繰り返すと、自分たちがおおよそどちらの方角に進むのが正しそうか、が分かるようになります。鼻が効くようになります。風が読めるようになる、と言ってもいいでしょう。すんごい毒々しい黄色と黒のナマコみたいなものを、俺はマフラーとして売りたいんだ、と誰かが言い出したとして、それって誰が嬉しいの？と周りが言えるチームになっているでしょう。ちょっと変な例ですが、でもそういうことです。

先輩は、分からんなぁ、ということがあったらどんどん、分からん！と言いましょう。その瞬間、後輩がともに戦う仲間になってくれます。自分も気が楽になります。自分が先輩を助けたいのと同じように、後輩はあなたを助けたいと思ってくれています。

説明

しごと、が誰かの幸せを叶えるものである以上、IT・飲食・不動産と何でも良いのですが、その活動で必ず誰かが幸せになっています。サービス提供側もまた喜んでいます。ひとつの仕事が続いているのは、全体の喜びのバランスが取れているということです。

（　あの人はどうなったら嬉しいのだろう　）

これが仕事の北極星です。

ステークホルダー分析とか、カスタマーサティスファクションとかカタカナを使ってもいいのですが、でも要するにそういうことです。嬉しさが波のように伝わっているのです。

分業の時代です。1つのサービスが誰かの元に届くまでに、多くの人が関わっています。ハンバーガーが食べられるまで、を考えると分かりやすいですよね。元は誰かが大切に育ててくれていた牛であり、レタスであり、小麦でした。そして当然、東京で生産していたわけじゃないです。なのに東京で美味しいハンバーガーが食べられます。とにかく仕事に関わるすべての人の気持ちを想像し、書き出す。これがOJTでやることです。

全体構想、要件定義、- 中略 - 、運用と様々な工程がありますが、どの工程でも必ず成長できます。なぜか。全ての仕事は誰かの嬉しさのために存在しており、同じ構造だからです。最終的なお客さんである誰かが実際に嬉しい、と思うまでの「嬉しさの伝搬」を中心に考れば、現時点の自分の担当がたまたまどこか、というだけの話です。担当、というのはそこだけやっていればいい、という話ではなく、価値を伝搬し実現することが最上位にあり、その文脈の中で担当分に専門性を持つということです。その専門性から見て全体の構造を変えた方がより価値を生み出せる、と気がついたならば、そこに仲間とともに立ち向かいます。仲間は自社だけでなく「嬉しさの伝搬」に関わる全ての生産者です。みなで価値を生んでいるのですから。

価値、つまり最終的なお客さんの嬉しさと自分のタスクの関係性をみんなで深く考える。そこで培われた考え方・嗅覚は別の工程でも活かせる技能です。長い間、私たちを助けてくれます。

嬉しさの伝搬をたどって仕事の全体像が見えてくると、よくこんな一連の「動くネットワーク」ができたもんだな、と驚きます。そこに自分も参加して、嬉しさの維持と合わせて新しい喜びを生み出せるのは、とても心躍ることではないでしょうか。

なおエンジニアとビジネス、という観点で非常に優れた記事があるのでぜひご覧ください。悩める私を折りにふれ励ましてくれた記事です。

3.3. 美しさと仕事、を同時に語る

やること

タスクをする際、美しさ分析をしましょう。

このタスクをすることは、人として美しいのか。

これをチームで話し合います。時間を使って仕事をするわけですが「時間を使う」は命を削る、と同義です。仲間の命を削ってまで、そのタスクはやる意義・価値があるのか。美しい行為なのか。人として。いきものとして。意義が感じられないなら、立ち止まって考える必要があります。

意義を、仲間と日常的に話し合いましょう。意義がないと分かったなら、活動はやめましょう。意義が見えにくいだけ、というケースもあります。価値の構造を皆で納得できるまで話し合いましょう。その活動を始めた人、は多くの背景と文脈を知っています。自分たちの仮説を是非話してみてください。数年に渡る壮大な計画かもしれません。それが読み解けたとき、物事の多層性が実感を持って理解でき、事象を精度高く捉える力と、未来を想像する力が増しているでしょう。

説明

社会人になる ＝ 消費者から生産者に変身する、というのはつまり、よくよく考えないと間違ったことに直接手を貸しかねない、ということです。報道で、どうしてこうなった、という悲しい例を耳にします。そうならないようにしたいですね。自分の良心に照らして、その行為は恥ずかしくないか？という物差しを持つことです。

我々の仕事は美しい、なぜならば、を語れるようになったチームは頭の中に、より多くの戦い方が浮かぶようになっています。同時に、仕事の楽しさも増しているはずです。なおこの「意義を考える」活動は、意義を問う後輩 vs 答える先輩、という構図でなく、タスクに対してチームで問いかけ・思考実験をする姿勢が良いです。正解などないが、皆で着想を出し合って正解らしきものに近づいていく、という動きを作り出すのにも役立ちます。

そして仕事をする上で、最終的なお客さん、関わる人たちのことだけではなく、その先の未来に自分たちが何を反映したいのか、を合わせて考えたなら、その仕事が自分にとってひとつの物語として立ち上がってくるのではないでしょうか。消費者の目線をもち生産し、現在に幸せを作りながら、未来に何を渡していくかを考える。私たちの先輩はそうしてきたのだし、私たちもまた、そうしてバトンを渡していきたいものです。

4. まとめ

今回は、OJTを進める上で大切なことを書きました。

• ともに希望を語る ・ ２年先の姿をともに描く
• あの人はどうなったら嬉しいだろう、をともに語る
• 美しさと仕事、を同時に語る

先輩役の人も、後輩役の人も、どちらも完璧超人ではなくて人なので、支え合いながら前に進めるといいですよね。

私が働きだして長い月日が経ちました。目にした苦しみの多くは、「自分の頭で自由に考える力」を奪われたことに起因するものでした。受験教育の弊害、と私は考えています。人がよく生きる上で、もう有効に機能しない仕組みだ、と。

それでも今と同じ教育の仕組みが続くならば、それに対抗するために、私たちにどのような方法が取りうるのか、の私なりの答えの一つが、このOJTの話です。この話が、みなさんの助けになることを願っています。

最後に、OJTに関わるみなさんへアラゴンの詩をおくります。

教えるとは　共に希望を語ること

学ぶとは　真実を胸に刻むこと ¹

双方に実り多きOJTとなりますよう。

TL;DR

• 調査データや発見を GitHub リポジトリにひたすら追加していく。スライド・原稿・ブログへの反映は Claude に任せる
• 新しいデータが出たらリポジトリに入れるだけで、Claude が成果物を更新してくれる。準備中にデータが増え続けても、成果物は追いつく
• VulnCon 2026 の登壇準備を通じてたどり着いた、リポジトリ駆動のやり方

はじめに

こんにちは、フューチャー株式会社の棚井龍之介です。2026年4月、アリゾナ州スコッツデールで開催された VulnCon 2026 で初めてアメリカのセキュリティカンファレンスに登壇してきました（登壇レポートはこちら）。60分の英語セッションで、発表スライドと登壇原稿の両方を準備する必要がありました。

面白かったのは、準備期間中にも新しい発見が次々と出てきたことです。登壇内容に関わるデータが日々増えていく。それを逐次スライドと原稿に反映していくことになります。

この状況で採ったやり方が、調査データや発見をまず GitHub リポジトリに追加して、スライドや原稿への反映は Claude に任せる、というものでした。データの置き場をリポジトリに決めてしまえば、自分は新しいデータを入れることに集中できる。そこから先の成果物への落とし込みは Claude がやってくれる。

なお、この記事で「Claude」と書いているのは、ターミナルから claude コマンドで起動する Claude Code のことです。

ターミナルで起動すると、カレントディレクトリのファイルを直接読み書きできます。Git 操作も gh コマンドも叩けます。リポジトリを作業場所にして Claude Code を立ち上げれば、リポジトリの中身を全部見た上で作業してくれます。

準備中にデータが増え続けるなかで

VulnCon の登壇準備で必要だったのは、発表スライドと登壇原稿です。加えて、FutureVuls ブログの技術記事も書く予定でした。

CFP が通った段階で、素材と方向性はおおよそ見えていました。ポイントは、そこから先です。

準備期間中に trivy へのサプライチェーン攻撃が発生し、これをきっかけに FutureVuls ブログとして複数の記事を執筆することになりました。

• FutureVuls 配布バイナリの安全性を SHA256・ビルドタイムスタンプ・Sigstore 署名の3軸で検証
• 攻撃者が狙った7リポジトリの攻撃直前の OpenSSF Scorecard を分析
• Sigstore・cosign による改ざん検証の仕組みを体系的に整理
• 第2波の攻撃が GitHub Actions・Docker Hub・npm・PyPI に波及し、影響確認ガイドを公開

どれも登壇内容に直結するテーマです。情報を収集しながらスライドと原稿に反映し、同時にブログとしても公開していました。スライド、原稿、ブログ——複数の成果物を並行して、継続的に更新し続ける状況です。

ここで力を発揮したのが、Claude を活用したワークフローでした。

やり方: データをリポジトリに入れて、Claude に反映させる

採ったやり方は単純です。新しいデータや発見が出たら、まず GitHub リポジトリに追加する。形式は何でもいい。Markdown でも、テキストファイルでも、画像でも、PDF でも。とにかくリポジトリに入れておく。スライドや原稿への反映は Claude に頼む。

リポジトリの中は、大きく「素材」と「成果物」に分けています。

リポジトリ/
├── 素材       # 調査データ、分析メモ、リサーチ結果
├── 成果物     # ブログ記事、登壇原稿、スライド
└── CLAUDE.md  # Claude への指示書

素材の中身は自分が管理しやすい粒度で分ければいい。ファイル1つにまとめてもいいし、テーマごとにディレクトリを切ってもいい。実際、自分のリポジトリでは最初は大雑把にファイルを放り込んでいましたが、データが増えてきたタイミングで Claude と壁打ちしながら構成を見直しました。「このデータとこのデータは分けたほうが扱いやすいか？」「ブログ用のプランはどこに置く？」といった相談を Claude にして、ディレクトリ構成自体を育てていく。最初から完璧な設計を決める必要はありません。

たとえば、攻撃者が狙った7リポジトリの Scorecard 分析が終わったら、まず素材として追記する。

case-studies/ に 7リポジトリの攻撃直前 Scorecard 分析結果を追加しました。
登壇原稿の適切な場所に反映してください。
スライドにも追加してください。

今回の VulnCon 2026 の準備では、自分と共同登壇者の神戸さんが、それぞれの調査結果や発見を次々と同じリポジトリに追加していきました。日によって誰がどのデータを入れるかはバラバラです。でも、データの置き場がリポジトリに決まっているので、スライドのどこに入れるか、原稿のどの段落を書き換えるかは、Claude がリポジトリ全体を見て判断してくれます。

Claude にリポジトリごと見せておけば、原稿に新しいデータを追加したときにスライド側の整合性も一緒に確認してくれます。スライドと原稿の整合性チェックを丸ごと任せられたのは助かりました。

さらに言えば、Claude はデータが増えたときに単に差分を反映するだけではなく、新しい情報を踏まえてより良い構成を提案してくれることもありました。「この発見を入れるなら、Part 5 と Part 6 の順番を入れ替えたほうが流れがいい」といった提案です。データが増えるたびに構成が良くなっていく、という体験は、手作業ではなかなかできません。

また、準備中に過去の自社ブログや公開情報を思い出して「そういえば、これも関連するな」と気づくことがあります。そういうときは、とりあえずリポジトリに入れておく。あとは Claude に任せます。使うかどうか、どこに入れるかは Claude が判断してくれます。素材の投入に迷わなくていいので、思いついたらすぐリポジトリに放り込む癖がつきました。

なぜ Slidev か

VulnCon のスライドは Slidev で作りました。Markdown でスライドが書けるツールです。

Slidev を選んだ一番の理由は、Claude との相性です。Claude はテキストファイルの読み書きが得意なので、Markdown で書かれたスライドなら中身を理解して直接編集できます。PowerPoint でも扱えますが、テキストベースのほうが編集がスムーズです。リポジトリのデータからスライドへの流れを Claude に任せたいなら、スライドも Markdown で書いておくのが自然でした。

たとえば、VulnCon で実際に使ったスライドを2枚紹介します。

1枚目は、サプライチェーン攻撃で CVE が採番されなかった理由を整理したスライドです。

# Why No CVE?

| What happened                          | Why it falls outside CVE scope                       |
| -------------------------------------- | ---------------------------------------------------- |
| Workflow misconfiguration exploited    | Site-specific misconfiguration, not a product defect |
| Repository hijacked via stolen PAT     | Platform behavior abuse, not a code flaw             |
| RCE on CI/CD runner                    | Environment-specific, not tied to a software version |
| Malicious code / compromised artifacts | ✅ CVE-2026-28353, CVE-2026-33634                    |

> CVEs captured the **artifacts**, but missed the **attack chain** that produced them.

この Markdown が、こういうスライドになります。

2枚目は、この攻撃をどうやって知ったかを聴衆に問いかけるスライドです。

---
layout: center
---

# How Did We Learn About This Attack?

~~CVE~~   ~~NVD~~   ~~Vulnerability Scanner~~   ~~CSPM~~

<v-click>

## We learned about it on **X**

</v-click>

<v-click>

## This is the CVE Blind Spot

</v-click>

実際のスライドはこうなります。

<v-click> は Slidev の機能で、クリックするたびに次の要素が表示されます。まず CVE や NVD が取り消し線で並んでいて、クリックすると「X（旧 Twitter）で知った」が出てくる。もう一度クリックすると「これが CVE の盲点だ」と結論が出る。こういうプレゼンの「間」を、Markdown で書ける。Claude はこの Markdown を直接読み書きできるので、「この v-click の順番を入れ替えて」といった修正もそのまま頼めます。レイアウトの調整も Markdown と CSS の範囲で完結するので、ストレスなく進められました。

VulnCon の準備では、登壇原稿からスライドを起こすこともあれば、スライドを先に直して原稿に反映させることもありました。どちらが先でもいい。原稿とスライドの両方がリポジトリにあるので、Claude が双方向に反映してくれます。

今回は英語での登壇だったので、スライドと原稿の役割分担にも気を配りました。スライドには情報を多めに載せて、聴衆が視覚的に追えるようにする。一方で原稿の英語表現はシンプルに抑えて、ノンネイティブでも話しやすくする。こういう「整合性は保ちつつ、それぞれの役割に合わせてアレンジする」ことも、両方のファイルを同時に見られる Claude だからできることでした。

ブログ記事も同じリポジトリから

VulnCon の登壇内容をブログ記事にする場合も、同じリポジトリから直接書けます。データはすでにリポジトリにある。登壇原稿もある。ブログ用に新たにデータを集め直す必要がありません。

やることは、リポジトリの中の素材を踏まえて、どういうブログを書いてほしいかを Claude に伝えるだけです。

リポジトリの素材を使って、サプライチェーン攻撃の影響確認ガイドをブログ記事として書いて。
対象読者は FutureVuls ユーザ。

Claude はリポジトリ内のファイルを直接読めるので、数値をコピペし直す手間がありません。素材に書いてある数値を、Claude がそのまま引用してくれます。

もちろん、生成された記事をそのまま公開するわけではありません。生成した原稿に対して Claude 自身にセルフチェックさせたり、PR を作成して GitHub Copilot をレビュアーにアサインしたりしながら推敲を重ねています。複数の AI の視点を入れることで、一人では気づきにくい表現の不自然さや論理の飛躍を拾えます。

ブログの執筆途中で新しい発見があったときも同じです。素材をリポジトリに追加して、「この情報を既存の記事に入れて」と頼めば、Claude が記事の流れを読んで適切な場所に追加してくれる。つまり、最初の執筆だけでなく「編集」も任せられる。スライドと原稿のときと同じ話で、新しいデータが出てきたら、自分はリポジトリに入れるだけでいい。

CLAUDE.md で表記を揃える

成果物が増えてくると、スライドとブログで数値の書き方を揃えたくなります。そこで CLAUDE.md をリポジトリのルートに置いています。

Claude Code はセッション開始時にこのファイルを自動で読み込みます。

## ブログ文体ルール
- 主張・論考・体験記系 → だ・である体
- 実務 How-to・解説系 → です・ます体

## よく使う数字（実測値）
| 指標 | 値 |
|------|-----|
| Scanner バイナリサイズ | 106.6 MB → 34.1 MB（-68%） |
| trivy 由来の依存 | 352 → 144（-59%） |

ここに正規の数値を載せておくと、スライドでもブログでも「-68%」で統一されます。「約7割減」ではなく正確な数値で統一できます。出典が PR なのか Issue なのかも、ここで決めておけばブレません。

最初は「まあ書いておくか」くらいの気持ちで作りましたが、成果物の本数が増えるほど効果を実感しました。

リポジトリ操作も Claude に任せる

ファイルの作成・編集、git commit、git push、Issue の起票——こういったリポジトリ操作は基本的に Claude に任せています。

Claude Code は gh コマンドも叩けるので、Issue の起票は gh issue create で済みます。自分は「データを集める」「指示を出す」「出来上がりを確認する」に絞れます。

壁打ちの結果を Issue に残す

Claude との壁打ちで出た気づきや方針変更は、そのまま GitHub Issue にしておく。これが地味に効きました。

たとえば、VulnCon の Q&A 準備をしているとき。

Issue #xx: Q&A セッション用のバックアップスライドを追加する

Issue の起票自体も Claude に頼みます。翌日の別セッションで「Issue #xx の内容を踏まえてスライドを追加して」と言えば、前回の議論を引き継げる。

Claude とのセッションは消えますが、リポジトリに書いたものは消えません。Issue やコミットログが、セッション間の記憶の代わりになります。

Perplexity で素材を足す

一次データの補強に Perplexity を使いました。

ブログに書く数値の裏取り——「endoflife.date のカバレッジは2026年4月時点で何件か」「gorilla/mux はいつアーカイブされたか」——こういった確認を Perplexity に投げて、返ってきた結果を出典ごとリポジトリに追記しておく。

Claude はリポジトリの中身しか見ないので、Perplexity で集めた情報もリポジトリに入れておかないと使えません。リポジトリに素材が増えるほど、Claude が書ける内容の幅が広がります。

実践を通じた所感

1ヶ月やってみて思ったのは、結局自分の仕事は「自分で試行錯誤して、それを記録すること」だった、ということです。こういうデータは自分で手を動かさないと生まれない。でも逆に、試行錯誤の記録さえリポジトリにあれば、そこから先は Claude に任せられる。

リポジトリに入れる素材は、Markdown で書くこともあれば、画像や PDF をそのまま放り込むこともありました。きれいに整形してから入れる必要はない。ただ、スライドや原稿のように Claude に直接編集させたい成果物は Markdown にしておくと、この流れが途切れません。

ディレクトリ構成は最初の数日で試行錯誤しましたが、構成が固まってからは、データを入れて反映を頼むだけのループになりました。VulnCon の直前まで新しい発見を出し続けられたのは、このループが軽かったからだと思います。

運用上の留意点

Claude が書いた文章は、必ず自分でレビューしています。CLAUDE.md で数値を揃えていても、文脈に合わない場所で引用されることはあるので、数値と前後の文脈の両方を確認する。

また、Claude の修正を完全には信用せず、適用漏れや横展開漏れがないかをチェックし続けることも大事です。たとえば「この表現を全箇所修正して」と頼んでも、一部が抜けていることがある。このチェック自体に、Claude 自身のセルフチェックや GitHub Copilot の PR レビューなど、複数の AI を組み合わせると抜け漏れを拾いやすくなります。

なお、Claude に git push や gh issue create を任せる以上、リポジトリはプライベートで運用し、機密情報は直接書かないようにしています。

おわりに

VulnCon 2026 の準備を通じてたどり着いたやり方は、データを GitHub リポジトリに集めて、成果物への落とし込みは Claude に任せる、というものでした。

新しい発見が出たらリポジトリに追加する。スライドや原稿への反映は Claude がやる。準備期間中にデータが増え続けても、リポジトリにさえ入れておけば、成果物は追いつく。

共通の情報源から、スライド・原稿・ブログといった複数の成果物を作る必要があり、しかもデータが継続的に増えていく——今回の VulnCon 準備は、まさにこのやり方が合うケースでした。同じような状況に直面している方の参考になれば幸いです。

なお、この記事自体も同じリポジトリから Claude で書いています。コミットログを見ると Co-Authored-By: Claude の記録が残っています。VulnCon の登壇準備でスライドや原稿を作るつもりで始めたリポジトリが、試行錯誤の記録が溜まった結果、こうしてワークフロー自体を紹介するブログ記事にまで繋がりました。リポジトリに記録を残しておくと、思わぬ形で次の成果物が生まれることがあります。

1. はじめに

こんにちは。HealthCare Innovation Group (HIG)の清水雄一郎です。
本記事は、春の入門祭り2026の1日目の記事です。

新年度・新チーム配属のこの季節、「開発環境のセットアップで丸一日溶かした」という経験をされている方も多いのではないでしょうか。特にエンタープライズ企業の「プロキシ・VPN配下」での開発環境構築は、ドキュメント通りに進めても謎のエラーに阻まれがちです。
プロキシに関しては、過去の記事¹²³もぜひご確認ください。

少し前（2026/01頃）に私が遭遇した事象は、WSL2環境で「自宅に帰るとapt updateできない」というものです。
当時を振り返ると、次のような状況でした。

• オフィスに出社してネットワークに繋ぐと、apt update が成功する
• 自宅（無線/有線LAN&VPN接続中）だと、 apt update が失敗する
• ただし、iPhoneのテザリング＋VPN の場合、apt update が成功する

結論から言うと、今回のケースではDNSの順序を変えることで解決しました。
その頃のSlackスレッドやGeminiとのチャット履歴を遡りつつ、体験記兼トラブルシューティングログとして残します。

2. 調査編: 泥沼のトラブルシューティング

2.0. 前提

本記事は、次の環境下で確認したものです。
※Windows側のバージョンは、事象発生時から少し変わっているかもしれません。

# Windows
エディション Windows 11 Pro
バージョン 24H2
OS ビルド 26100.8037

# WSL2（Ubuntu）
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04.5 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy

2.1. エラーログ

まずは事象を整理するため、発生していたエラーログを確認します。

$ sudo apt update
...
エラー:5 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
  サーバからの読み込みに失敗しました - read (104: 接続が相手からリセットされました) [IP: 10.x.x.x 8080]
エラー:6 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
  10.x.x.x:8080 (10.x.x.x) へ接続できませんでした。接続がタイムアウトしました [IP: 10.x.x.x 8080]
エラー:3 http://security.ubuntu.com/ubuntu jammy-security InRelease
  サーバからの読み込みに失敗しました - read (104: 接続が相手からリセットされました) [IP: 10.x.x.x 8080]
...
W: いくつかのインデックスファイルのダウンロードに失敗しました。 これらは無視されるか、古いものが代わりに使われます。

10.x.x.x:8080は、社内プロキシサーバーです。
「タイムアウト」と「接続が相手からリセットされました」が混在しており、この時点では原因が全く特定できていません。

試しに同じ社内プロキシを経由している wget / curl コマンドを試しましたが、成功することを確認できました。

$ wget google.com
# → 200 OK で正常に取得できる

$ curl -I -L google.com
# → 200 OK

※いま振り返ると、http://archive.ubuntu.com/ubuntu宛にwget / curl コマンドを試した方が良かったかもしれません。

ここで一人では抱え込めないと判断し、Slackでチームメンバーに助けを求め、Geminiにも相談しながら仮説検証を始めました。
他の人に相談することは、私の環境だけの問題かどうか切り分けるという一つの検証と言えると思います。

2.2. 仮説① プロキシ設定が間違っている？

最初に疑ったのは、やはりプロキシ周りです。aptはwget/curlとは別経路の設定を見るため、apt自体のプロキシ設定を確認します。

cat /etc/apt/apt.conf
Acquire::http::Proxy  "http://username:password@proxy.example.com:8080";
Acquire::https::Proxy "http://username:password@proxy.example.com:8080";

設定済みでした。環境変数もaptと同じ設定値が入っています。

env | grep -i proxy
...
http_proxy=http://username:password@proxy.example.com:8080
https_proxy=http://username:password@proxy.example.com:8080
...

aptのプロキシ設定は、問題なさそうです。
またこの時、環境変数を引き継ぐため、sudo -E apt updateを実行してみましたが、最初と同様のエラーになりました。

2.3. 仮説②～⑤ プロキシ設定以外はどう？

プロキシ設定以外に考えられる原因をGeminiやメンバーに聞いて片っ端から試しました。結論から言うと、いずれも空振りでした。

仮説② 社内プロキシの証明書が未インストール？

証明書周りはプロキシの次にトラブルが多い印象なので、試しに手動で入れ替えて確認します。
→ 変化なし

# 非推奨。次のコードブロックの手順を推奨。
sudo rm /etc/ssl/certs/ca-certificates.crt
sudo cp path/to/ca.crt /etc/ssl/certs/ca-certificates.crt
sudo apt update  # 変化なし

原因特定のために/etc/ssl/certs/配下の証明書を直接操作しましたが、本来はupdate-ca-certificatesを使う方が正しいです。
推奨される方法は、次の通りです。

sudo cp path/to/ca.crt /usr/local/share/ca-certificates/corp-proxy.crt
sudo update-ca-certificates
sudo apt update

仮説③ WSLのHyper-Vファイアウォールが遮断している？

「デフォルトでオンになっているHyper-V FirewallをOFFにするとaptが通ることがある」という情報を教えてもらい、「WSL Settings」のGUIから無効化してみました。
→ 変化なし

仮説④ MTUの設定が経路と合っていない？

Geminiにエラーログを渡して相談すると、MTU（Maximum Transmission Unit）⁴の影響を疑うよう提案を受けました。VPN環境下では実効MTUが小さくなり、デフォルト1500バイトのままだと通信に失敗するケースがあるとのこと。
→ こちらも変化なし

sudo ip link set dev eth0 mtu 1300
sudo apt update  # 変化なし

後から振り返ると、MTU調整は「大きいパケットだけ落ちる」症状に有効な対策で、数十KBのリクエストで失敗する今回の症状とは整合しません。生成AIの提案を鵜呑みにして試した回り道でした。

仮説⑤ archive.ubuntu.comが遠いから？

リポジトリを日本のミラーサーバーに変更してみます。
→ ログは割愛しますが、タイムアウトエラーになってしまいます。

sudo sed -i.bak -E 's!http://(archive|security)\.ubuntu\.com!http://jp.archive.ubuntu.com!g' /etc/apt/sources.list
sudo apt update  # タイムアウトエラー

2.4. 仮説⑥ 接続するネットワークの問題？

出社する日が多く、自宅でのみ発生する問題の解消を後回しにしていたのですが、オフィスにいる時に時間ができたので再度向き合ってみることにしました。
VPN接続時に発生するため、オフィスにいながらBYODであるiPhoneのテザリングに切り替えて、VPN接続してみます。
なんと、apt updateが正常終了することに気が付きます。整理すると次の状況です。

• オフィス無線LAN → OK
• 自宅（無線/有線）LAN＋VPN → NG
• iPhoneテザリング＋VPN → OK 🤔

ひとまず成功したことに喜びつつ、ずっとテザリングで業務するわけにはいきません。
VPNがすべてダメというわけではないと分かったので、他の手立てを考えてみました。

3. 原因編: 名前解決を疑う

wgetは通ってaptは通らない、かつ、同じVPNを使っていても回線（自宅LAN/テザリング）によって成否が変わることが分かりました。
つまり原因は「どの回線でも共通に使われる設定」ではなく、「回線ごとに切り替わる何か」 にあると考えました。

回線ごとに切り替わるものの一つに、ホストであるWindowsが参照するDNSがあります。
WSL2は、デフォルトでWindows側のDNSを継承するため、回線が変わればWSLが使うDNSも変わります。

ここから、名前解決（DNS）の速度を疑うことにしました。
※名前解決とは、ドメイン名（例: archive.ubuntu.com）をIPアドレスに変換する処理のことです。

apt updateは、内部で複数のリポジトリに問い合わせているため、1問い合わせあたりの名前解決が遅いとそれが積み重なり、接続タイムアウトに抵触しやすいのではないかと考えました（最初に試したwget / curl は単発リクエストなので、1回の遅延くらいは待てる、という仮説）。

実際に、名前解決の時間を計測してみます。getent hostsは、指定したホストの情報を取得するコマンドです。

time getent hosts proxy.example.com
10.x.x.x    proxy.example.com

real    0m15.225s
user    0m0.001s
sys     0m0.004s

それがたった1件の社内ホスト情報取得に15秒かかっていました。

ちなみに、その時の/etc/resolv.confの中身はこうでした。

cat /etc/resolv.conf
nameserver 172.x.x.x    # Windowsホスト側の仮想ルーター
nameserver 10.x.x.x     # 開発環境構築時に追記したもの
search example.com      # 開発環境構築時に追記したもの

172.x.x.xは、WSL2がデフォルトで参照するWindowsホスト側の仮想ルーターです。
Windows側の設定を引き継いで名前解決してくれる便利な仕組みですが、私の環境かつVPN接続状態ではボトルネックになっていると考えました。

4. 解決編: /etc/resolv.confへの記載順序を変える

原因が掴めれば対処は単純です。WSLのデフォルト仮想DNS（172.x.x.x）より先に、社内DNSに直接問い合わせるよう、/etc/resolv.confのnameserver順序を並び替えます。

Linuxのリゾルバは、/etc/resolv.confのnameserverを上から順に試すようです。⁵⁶先頭から応答が返ればそこで終了、タイムアウトすれば次へフォールバックする仕組みです。1問い合わせあたりデフォルト5秒 × 複数回リトライすることで⁷、先頭が遅いと十数秒単位で待たされていたと推測します。
つまり、社内DNSを先頭に置くだけで、ほぼ全ての問い合わせが1行目で即解決するようになるはずです。

sudo vim /etc/resolv.conf

# /etc/resolv.conf
nameserver 10.x.x.x   # 一番上に変更
nameserver 172.x.x.x
search example.com

効果を計測します。

time getent hosts proxy.example.com
10.x.x.x    proxy.example.com

real    0m0.033s
user    0m0.003s
sys     0m0.007s

15.225秒 → 0.033秒。約460倍の改善です。
この状態でapt updateを叩くと、自宅（無線/有線）LAN＋VPN環境で、一発で成功することを確認できました🎉

ここで忘れてはいけないのですが、/etc/resolv.confは、WSLを再起動するとデフォルトで自動再生成され、上の変更が上書きされて消えてしまいます。
「せっかく直したのに翌朝また詰まった」を防ぐため、/etc/wsl.confで自動生成を無効化しておきます。

sudo vim /etc/wsl.conf

# /etc/wsl.conf
[network]
generateResolvConf = false

5. おわりに

今回の泥沼を振り返ると、最も反省すべき点は、「十分な評価をしないまま、ありがちな原因を手当たり次第試し続けた時間」 の長さでした。

生成AIにエラーログを投げると、どんなに長くても中身を読んで自分が思いつかない次の一手を考えてくれます。
特に、環境構築周りは色々な層に原因が潜んでいるため、これまで自分よりも生成AIの方が得意な分野だと思っていました。
もちろん多くの場合その通りだと思いますが、今回のケースのようにうまくいかない時もあります。
改めて、開発環境構築において「何ができて何ができなかったか」を整理することはもちろん、「何が『どこまで』できているか」を「計測する」 ことが重要だと実感しました。

これから開発環境を構築する皆さんは、詰まった際に生成AIに「何をやるといいか」と同時に、「何を計測すると原因が測れるか」を聞いてみると解決の近道になるかもしれません。
そしてぜひ、詰まった経緯と解決策を記事にしてネットに公開してください！
今度は、生成AIが学習して解決がもっと早まるかもしれません……！

参考

春の入門連載は2020年から始めた連載で、以下のテーマで行う技術ブログリレーです。

• 新年度、新たなことをチャレンジする機会として、「入門」がテーマ
• 今まで触って無かった技術の体験記
• 先輩・同期・後輩宛に、知っておいて欲しい技術記事
• 好きな技術の布教活動をする記事

上記の前提であるため、具体的に取り上げる技術領域は自由ということが特徴です。人によってテーマである入門の解釈も自由自在で、お気に入りの記事に思いがけず出会うキッカケとしても機能するでしょう。

他の連載に比べて、ジャンルを問わずに応募していることもあり、毎年初の寄稿となる社員も多く参加しています。参加者の中にはブログを書いてみたい、とブログ運営に直接連絡をくれたやる気に溢れた社員もいるほどです。

参加者一覧&投稿タイトル

今年はインデックス記事を含めて10名が参加します！ 間にゴールデンウィークを挟みつつ、5月中旬にかけて平日ほぼ毎日更新していく予定です。

技術ブログにはお馴染みの顔から、今回の連載で初寄稿の社員まで幅広いメンバーで投稿していきます。テーマがまだ決まっていないところや変わる場合がありますが、運営チャットでは各メンバーの気合が漲っております。

※ 各記事が公開され次第、順次リンクをアップデートしていきます。

さいごに

良いと思った記事などはシェアなどのリアクションをいただければと思います！

• 2025年の連載記事
• 2024年の連載記事
• 2023年の連載記事
• 2022年の連載記事
• 2021年の連載記事
• 2020年の連載記事

はじめまして！フューチャー株式会社の田中裕真と申します。

私は2025年10月に新卒として入社し、2026年2月にAIXG(AI戦略推進グループ)のNLPチームに配属されました。配属からちょうど2ヶ月が経ち、これまでのゆったりとした生活から一変して、忙しくも目まぐるしく新しい情報が得られ、知的好奇心を満たしながら働く充実した毎日を送っています。

大学院での研究ではAIの性能調査などを通じてAI自体には触れていたものの、自然言語処理（NLP）分野はあまり経験がありませんでした。現在はNLP関連のキャッチアップを進めながら、チャットシステムの構築業務に携わっています。

本記事では、2026年3月9日(月)〜3月13日(金)にかけて栃木県宇都宮市で開催された言語処理学会第32回年次大会 (NLP2026) の参加報告をお届けします。

当社はプラチナスポンサーとして協賛し、総勢8名がオンサイトで参加しました。スポンサーブースでの企業紹介や、メンバーによる研究発表など、非常に活気あふれる5日間となりました。

言語処理学会とは

言語処理学会は、自然言語処理（NLP）分野における国内最大の学会で、毎年3月に開催されています。第32回となる今年の年次大会は、栃木県宇都宮市でのオンサイト開催とオンライン配信のハイブリッド形式で行われました。

今回の大会は、事前＋直前参加登録者が2236人（歴代2位）に上り、当日参加者を合わせると歴代1位の参加者数を記録しました。さらに、発表件数は797件（歴代1位）、スポンサー数は100団体（歴代2位）と過去最大級の規模となりました。生成AIや大規模言語モデル（LLM）の社会実装が急速に進む中、産学問わず非常に多くの研究者が集い、基礎研究から応用事例まで幅広い議論が交わされる熱気のある学会です。NLP初学者の私にとっても、最前線の研究トレンドを直接肌で感じることができる非常に貴重な機会となりました。

スポンサーブースの様子

企業ブースでは、NLP関連の過去の導入事例や、そのほかのAIXG担当領域についての紹介を行いました。連日多くの方々に足を運んでいただき、NLPの社会実装に関するディスカッションや、学生の皆さんとの交流で大いに盛り上がりました。

今回はノベルティとして眼鏡やディスプレイを拭ける「クロス」と折りたたみ可能な「トートバッグ」を用意しご好評をいただきました。

▲ 企業ブースの様子

祝・若手奨励賞受賞！

本大会では、同じAIXGメンバーである藤井の主著論文『TimeMachine-bench: LLMは「あの日」のコードを最新環境に適応できるか？』が、見事若手奨励賞に選出されました！
当論文の背景や解説については、著者の藤井自身が執筆したブログ記事が公開されておりますので、ぜひ併せてご覧ください。

• 【著者解説】NLP2026 若手奨励賞受賞論文 “TimeMachine-bench” を著者が解説する

投稿論文の紹介

当社は、NLP2026において著者・共著者を含めて合計4件の論文を投稿しました。

本章ではこれらの4件の論文について簡単に紹介します。

• [B8-1]UI-Redline-bench: 赤入れ指示によるWebUIコード修正ベンチマーク
  この論文では、WebUI開発における、スクリーンショットに直接手書きで修正指示を書き込む「赤入れ」プロセスに着目し、視覚的指示に基づくコード修正タスクのベンチマーク「UI-Redline-bench」を構築しています。人間にとって直感的な形式の指示に対するVLM（視覚言語モデル）の処理能力に焦点を当て、VLMを活用した開発作業の能率向上への寄与を目指すものです。
  　既存研究が主に言語的指示を扱っているのに対し、本研究は図形や文字を使って描きこまれた視覚的指示を扱う点が特徴です。著者らが視覚的指示を描きこみ作成した、計350件のHTML/CSSコード修正データセットにより、GPT-5等の主要なVLMの視覚的指示に基づくコード修正能力を検証しました。
  検証の結果、GPT-5等は全体として高い修正能力を示した一方で、矢印を使って示された離れた位置に、概形で描かれたUIを実装する事例では、修正に失敗する傾向が見られました。この結果から、今後VLMの空間推論能力の強化が不可欠であると言えます。具体的には、矢印の指し示す位置を正しく認識する、個々の図形を意味のあるまとまりとしてグループ化するなど、空間的に分散した視覚的指示を統合するタスクの必要性が示唆されています。（肥合）
• [B8-3]TimeMachine-bench: LLMは「あの日」のコードを最新環境に適応できるか？
  この論文は本学会において若手奨励賞に選出されました！こちらの技術ブログで詳しく説明されていますので、ぜひご覧ください。
• [B9-19]WikiOriginQA: 知識の起源を組み込んだ文化的バイアス分析用QAデータセットの自動構築
  この論文では、LLMの性能における文化的バイアスを検証するためのQAデータセットと、その自動構築手法を提案しています。LLMの学習データは、英語をはじめとした使用者の多い主要な言語に偏っています。そのため、主要言語圏の知識は良く知っている一方で、マイナーな言語圏の知識は適切に扱えないという文化的バイアスが起こることが知られています。しかし、既存の手法では該当する文化に詳しい協力者を必要とするため、多言語・多文化にわたる調査用データセットの構築は困難でした。そこで本論文では、「ある文化に特有の知識は、その文化と関係の深い言語において最も早くドキュメント化される」という仮説に基づき、文化的知識と言語の結びつきをWikipediaの記事作成日を用いて表現することで、文化的知識を問うQAデータセット「WikiOriginQA」を自動構築しました。
  WikiOriginQAを用いた実験の結果、先行研究と同様にLLMの性能における英語圏の文化へ偏重傾向が確認され、これにより、多様な文化におけるバイアス検証を人手を介さずに行う上で、本手法が有効であることが示唆されました。（羽根田）
• [C9-20]項の復元は必要か？日英機械翻訳における省略された項の扱いの分析
  この論文では、主語や目的語等の述語の項が省略されやすい日本語のような言語 (pro-drop言語) から英語への機械翻訳において、従来重視されてきた「省略された項の同定および復元」が本当に必要かという問題に対し、その必要性を実証的に検証しています。
  具体的には、LLM (GPT-4o) を用いた日英翻訳を対象に、省略項の同定 (ゼロ照応解析) の成否と翻訳品質の関係、および翻訳時に項がどの程度復元されるかを分析しています。また、省略項が復元されなかった場合の構文選択なども含め、多角的な事例分析が行われています。
  その結果、GPT-4oは省略項の同定が困難な事例や項を復元せずに訳した場合においても文意が伝達できる翻訳が行えていました。ただし、項の同定が困難な事例では復元を避ける傾向が見られるなど項の同定可否に伴って翻訳の性質には差が見られました。しかし、省略項を復元しない場合、GPT-4oは述語の名詞化や受動態などを用いることで構文的に自然な翻訳が行えていました。これらの結果から、項の同定・復元は必須ではなく、日英翻訳において最先端のLLMには項の省略はもはや主要な障壁ではないことが示唆されました。 (野末)

社員が選ぶNLP2026の注目論文の紹介

ここからは、NLP2026に参加したメンバーが各自の視点で「これは面白い！」「業務に活かせそう！」と感じたイチオシの論文やセッションを3件ピックアップして紹介します。

• [P8-20] 多言語文埋め込みの意味と言語の分離のための損失関数の分析
  日本語や英語など、言語が違っても似た意味の文同士が近くなるようにベクトル化する「多言語文埋め込み」は、情報検索や機械翻訳の品質推定など幅広い領域で使われています。
  この技術では「言語によらず」意味の近さが反映されることが理想ですが、実際には言語情報に引っ張られてクラスタが分離してしまい、言語横断的なタスクでの性能低下を招くことが知られています。そのため先行研究では、文埋め込みを「意味表現」と「言語表現」に分離し、意味表現のみを用いる手法が提案されてきました。
  この分離のための学習手法（損失関数の設計）には、各要素内で完結する「要素内制約」と、両者に跨る「要素間制約」が存在しますが、これらが分離にどう寄与するかは十分に分かっていませんでした。本研究でこれらを比較した結果、従来のエンコーダ由来モデル（LaBSEなど）では両者の併用が有効な一方、近年のデコーダ由来モデル（Gemini Embeddingなど）では「要素間制約」のみを用いる方が高い性能を示すことが明らかになりました。
  　LLMベースのモデルが普及する中で、従来のモデルとは適した学習アプローチが異なることを実証した事実は興味深いと考え、こちらの発表を取り上げました。（森下）
• [Q3-10] マルチモーダルかつ長い文脈の処理が求められる語用論的推論ベンチマーク
  大規模言語モデル（LLM）や大規模視覚言語モデル（VLLM）において、言語の辞書的な意味ではなく文脈依存の意味を理解するための「語用論的推論能力」の向上は社会実装を目指すうえで重要な課題です。この研究では、特にマルチモーダルかつ長期文脈の処理が必要な設定における語用論的推論のベンチマークを提案しています。
  特徴として、漫画データを題材として採用し、著者が人手で問題・選択肢を作成することで計101問の多肢選択式QAデータセットを構築しています。実際にVLLMと人間による評価実験を行った結果、最新のVLLMであっても正解率は人間を大きく下回り、語用論的推論能力には課題が残っていることが示されました。
  マルチモーダル・長期文脈の処理が必要な設定として漫画を活用している点や、評価実験を通して昨今著しい性能向上が見られるVLLMの弱点を浮き彫りにした点が非常に興味深く、挙げさせていただきました。(岸波)
• [B6-7] クロスコーダーを用いた脳と言語モデルにおける内部表現の特徴量比較
  本研究は、ポッドキャスト聴取時の脳活動（fMRIデータ）と言語モデル（LM）の内部表現を「クロスコーダー」という手法で比較し、両者の情報処理における類似点や相違点を検証した論文です。従来の研究では、LMの表現から脳応答を予測するエンコーディングモデルが主流でしたが、これはLMから脳への一方向的な写像に留まり、予測の根拠となる要因を人間が理解できる形で抽出できない（解釈性が低い）という課題がありました。
  本手法では、脳応答とLM表現の両方を同一のスパース（疎）な潜在空間に写像し、そこからそれぞれの表現を再構成するプロセスを学習します。この仕組みにより、抽出された特徴量が脳とLMのどちらに強く寄与しているかを定量的に評価することが可能になりました。実験の結果、「場所」に関する描写は脳とLMで共通して表現されている一方、「負の情動」は脳側に、フィラー（言いよどみ）などの「口語表現」はLM側に特有の反応として抽出されました。
  fMRIの解像度の限界や、因果関係の特定といった課題はあるものの 、AIの内部表現と人間の理解を直接比較し、その差を数値で示せる点は非常に画期的です。知性の在り方を定量的に議論できる可能性に興味を惹かれ、本論文を取り上げました。（田中）

会場の様子・オフタイムのエピソード

オンサイト参加ならではの、現地の雰囲気やエピソードも少しご紹介します。

最も印象的だったのは、学会オープニングでの出来事です。全プログラム終了後に「重要な注意事項」と銘打たれたスライドで宇都宮餃子の正しい食べ方のレクチャーがありました。開催地である宇都宮ならではの粋な計らいに、会場全体が温かい笑いと拍手に包まれました。

▲ オープニングでの「重要なお知らせ（餃子の食べ方）」

また、天候に関しては驚きの連続でした。開催2日目には、3月であるにもかかわらずなんと大雪に見舞われました。会場周辺の道も真っ白に雪が積もり、ある意味で非常に記憶に残る学会となりました。

▲ 3月とは思えない大雪に見舞われた2日目

一方で、天気の良いお昼時には会場の外にキッチンカーが出店しており、日差しを浴びながら外でランチを楽しむこともできました。

おわりに

NLP初学者としての参加でしたが、日々の業務に直結する知見や、LLMの最新動向など、膨大なインプットを得ることができました。何より、最前線で活躍する研究者やエンジニアの熱量に直接触れることができ、「自分もさらに技術を磨いていこう」と強くモチベーションを刺激されました。

現在、AIXGのNLPチームでは、以下のような環境・制度を整え、NLPの基礎・応用技術開発を積極的に推進しています。

• 大学との共同研究
• 社会人博士制度
• 新規参画者への教育プログラム
• GPUクラスタ

こうした環境のもと、ともに働くメンバーを積極的に募集しています！

学生の皆様へ
夏季インターンやアルバイトについては、4月20日 (月) に下記のウェブサイトから募集を開始いたします。
また、博士課程向けのResearch Internは通年募集中です。

https://www.future.co.jp/recruit/summer_intern/2026/

昨年のインターンシップ参加者へのインタビューもぜひご確認ください。

https://future-architect.github.io/articles/20260323a/

新卒・キャリア採用について
NLP分野における社会実装のニーズは拡大し続けており、自然言語処理の力で顧客のビジネス課題を解決していく仲間を求めています。少しでも興味を持っていただけた方は、ぜひ以下の採用リンクからご応募をお待ちしております！

• 新卒採用 : https://www.future.co.jp/recruit/recruit/rec-fresh/
• キャリア採用 : https://www.future.co.jp/recruit/recruit/rec-career/

Markdownでプロジェクトの進捗報告やチームの振り返り資料をまとめていると、定量的な部分にはグラフを入れたくなります。Excelなど外部ツールでグラフを作成して画像を挿入しても良いですが、画像ファイルの管理がちと面倒です。

Mermaid.js はUMLを描けることで有名ですが、実はいくつかのグラフ表示もサポートされています。どうせあまりオシャレじゃないんでしょう？..と、あまり期待していなかったのですが、想定よりオシャレ化ができることが分かったので、この感動を伝えさせてください。

もちろん、見た目や構成ではいくつか制約があります。それさえ許容できれば、テキストでグラフを記述でき、VS Codeなどでのプレビュー以外にも、GitHub・GitLab・Notionなど多くのプラットフォームでプレビューできますし、何よりAIからの支援も受けやすくなりお勧めです。

試してみたナレッジをいくつか紹介します。

環境

• Mermaid.js v11+（radar-beta、xychart-betaが利用可能）
• 表示確認: VS Code（Markdown Preview Mermaid Support拡張）、GitHub

レーダーチャート

2025年3月にリリースされたv11.6からレーダーチャートが利用可能になりました。ドキュメントもあります。レーダーチャートは、多軸の評価結果を一目で比較したいといった用途に便利ですよね。

Tips 1: レーダーチャートの装飾

例えば、チームの「開発チーム成熟度」を複数の観点で評価し、2つのチームの強みを重ねて比較してみます。

このとき、以下の設定がおすすめです。デフォルトでもそこそこオシャレですが、細かい調整をしたくなります。

1. graticule polygon を指定して目盛線を多角形にする
   • デフォルトの曲線もオシャレだが、言いたいことが伝わりにくい…
2. 絶対評価の基準となる max（満点）と min（最低点）を指定する
   • 指定しない場合は、入力から自動で補正するが揃えた方が無難
3. curve のラベルにチーム名だけでなく、括弧書きで「平均スコア」等のサマリを埋め込んで凡例とする
   • テキストでの追加情報は、ラベルに足すしかない
4. デフォルトの配色を変えたい場合、configで変更可能
   　 - cScale0/cScale1で1番目、2版目のレーダーの色を調整。 curveOpacity で透過度を指定する

---config:  theme: default  themeVariables:    cScale0: "#FF5252"    cScale1: "#4CAF50"    radar:      axisColor: "#9E9E9E"      graticuleColor: "#E0E0E0"      curveOpacity: 0.25      curveStrokeWidth: 1---radar-beta    graticule polygon    axis v["ベロシティ"], q["品質"], a["自律性"]    axis c["コミュ力"], p["計画精度"], t["技術力"]    curve d["チームA (4.4)"]{4.4, 4.2, 4.8, 4.7, 3.9, 4.3}    curve c["チームB (4.2)"]{4.5, 3.7, 4.5, 3.9, 4.8, 4.4}    max 5    min 0

---
config:
  theme: default
  themeVariables:
    cScale0: "#FF5252"
    cScale1: "#4CAF50"
    radar:
      axisColor: "#9E9E9E"
      graticuleColor: "#E0E0E0"
      curveOpacity: 0.25
      curveStrokeWidth: 1
---
radar-beta
    graticule polygon
    axis v["ベロシティ"], q["品質"], a["自律性"]
    axis c["コミュ力"], p["計画精度"], t["技術力"]
    curve d["チームA (4.4)"]{4.4, 4.2, 4.8, 4.7, 3.9, 4.3}
    curve c["チームB (4.2)"]{4.5, 3.7, 4.5, 3.9, 4.8, 4.4}
    max 5
    min 0

棒グラフ

Tips 2: 積み上げグラフの実現

xychart-betaは ネイティブの積上げ棒グラフをサポートしていません。複数のbarシリーズを定義すると、並列ではなく重ね描画されます。

例として、機能別・優先度別の残タスク数を可視化したいとします。

素朴にそのまま書くと、本来「6」「6」「4」の高さになるはずの棒グラフが、ただ同じ位置から重ねて描画されてしまい、意味不明な状態になります（積み上げグラフになっているじゃん…と思いますが、高さをよく見ると合計値に達していません）。

xychart-beta    title "❌️重なって描画される"    x-axis ["検索機能", "決済機能", "ユーザー管理"]    y-axis "タスク数" 0 --> 10    bar "高" [0, 2, 0]    bar "中" [2, 4, 3]    bar "低" [4, 0, 1]

xychart-beta
    title "NG: そのままの数値（重なって描画される）"
    x-axis ["検索機能", "決済機能", "ユーザー管理"]
    y-axis "タスク数" 0 --> 10
    bar "高" [0, 2, 0]
    bar "中" [2, 4, 3]
    bar "低" [4, 0, 1]

3本のグラフが重なっていますが、逆手にとって考えると、累積値で、擬似的に積上げ棒グラフにできるということです。悪い回避策だという指摘はいったん脇に..。

棒グラフは “最後”に書いた定義が “手前” に表示されます。そのため、一番最初に積み上げたい「低」を最初に書いて、「高」を最後に書きます。

こうすると、「中」の棒は「低」の棒の「内側」に重なり、「高」の棒はさらにその内側に重なります。結果として色が層になり、積上げに見えるわけです。

xychart-beta    title "✅️積み上げには成功、❌️0件が微妙な表示"    x-axis ["検索機能", "決済機能", "ユーザー管理"]    y-axis "タスク数" 0 --> 10    bar "低" [6, 6, 4]    bar "中" [2, 6, 3]    bar "高" [0, 2, 0]

xychart-beta
    # ...中略...
    bar "低" [6, 6, 4]
    bar "中" [2, 6, 3]
    bar "高" [0, 2, 0]

積み上げは成功しましたが、0件である「高」が微妙に表示されてしまいノイジーです（0なのにわずかに表示されてしまってます）。いろいろ試したのですが、配列の中間の0は -1 に置換することで回避可能です。末尾の記述も-1にするか省略で回避できました。-1 にしておくことで、グラフ上にはレンダリングされませんが、「データが存在する」という判定になるため、色の割当順序が正しく維持されるため、都合が良いです。

xychart-beta    title "✅️ 意図した通りに疑似積上げされる"    x-axis ["検索機能", "決済機能", "ユーザー管理"]    y-axis "タスク数" 0 --> 10    bar "低" [6, 6, 4]    bar "中" [2, 6, 3]    bar "高" [-1, 2]

xychart-beta
    x-axis ["検索機能", "決済機能", "ユーザー管理"]
    # ...中略...
    bar "高" [-1, 2]  ← 中間は-1、末尾は省略でも良い

Tips 3: 色の指定は plotColorPalette と凡例

さきほど、積み上げ棒グラフ化には成功しましたが、優先度が高い順に、目立たせたいと思うはずです。疑似積上げでは「外側ほど薄く、内側ほど濃く」するのが自然です。「高」を最も濃い色にすると、対応すべきタスクが視覚的に目立ちます。棒グラフの色はplotColorPaletteで指定します。シリーズの定義順（barの記述順）に対応します。

色を付けると、色の意味は何だ？となりますが、xychart-betaには凡例機能はありません（！）。そのため、Markdownが許容する環境であれば、Mermaidブロックのすぐ下にHTML書いてしまうのがてっとり早い回避手段です。

---config:  theme: base  themeVariables:    xyChart:      plotColorPalette: "#fff4dd, #ffd8b1, #FF6E40"---xychart-beta    x-axis ["検索機能", "決済機能", "ユーザー管理"]    y-axis "タスク数" 0 --> 10    bar "低" [6, 6, 4]    bar "中" [2, 6, 3]    bar "高" [-1, 2]

---
config:
  theme: base
  themeVariables:
    xyChart:
      plotColorPalette: "#fff4dd, #ffd8b1, #FF6E40"
---
xychart-beta
...
    bar "低" [6, 6, 4]    ← 1番目（#fff4dd: 薄い黄色）
    bar "中" [2, 6, 3]    ← 2番目（#ffd8b1: 薄いオレンジ）
    bar "高" [-1, 2]  ← 3番目（#FF6E40: 濃いオレンジ）

HTMMLは以下のようなものを、mermaid.jsのすぐ下にそのまま配置します。

<div style="display: flex; justify-content: center; gap: 24px; font-size: 14px; color: #424242; font-family: sans-serif; margin-top: -8px;">
  <div style="display: flex; align-items: center; gap: 6px;">
    <span style="color: #FF6E40; font-size: 18px;">■</span> 高
  </div>
  <div style="display: flex; align-items: center; gap: 6px;">
    <span style="color: #ffd8b1; font-size: 18px;">■</span> 中
  </div>
  <div style="display: flex; align-items: center; gap: 6px;">
    <span style="color: #fff4dd; font-size: 18px; text-shadow: 0 0 1px #ccc;">■</span> 低
  </div>
</div>

ポイントは、薄い色（優先度「低」）の凡例の四角（■）に text-shadow: 0 0 1px #ccc; を付けて輪郭線を出すことです。これにより、白背景でも凡例の視認性をしっかり確保できます。

Tips 4: Before/Afterの表示

xychart-betaはグループ化（横並べ）ができません。そのため、リファクタリング前（Before）と後（After）のバグ発生数を比較したい場合などは、グラフを2つ並べます。

---config:  theme: base  themeVariables:    xyChart:      plotColorPalette: "#FF8A80"---xychart-beta    title "バグ発生数 (リファクタリング前)"    x-axis ["検索機能", "決済機能", "ユーザー管理", "共通基盤"]    y-axis "件数" 0 --> 80    bar [8, 39, 41, 24]

---config:  theme: base  themeVariables:    xyChart:      plotColorPalette: "#81C784"---xychart-beta    title "バグ発生数 (リファクタリング後)"    x-axis ["検索機能", "決済機能", "ユーザー管理", "共通基盤"]    y-axis "件数" 0 --> 80    bar [0, 8, 70, 34]

ポイントはY軸の上限を揃えること（0 --> 80）です。これにより、棒の長さだけで直感的に「改善したかどうか」を比較できるようになります。

おわりに

Mermaid.jsは「テキストで書ける手軽さ」が最大の強みですが、積上げ棒グラフや凡例、スライスの順序制御といった実務で欲しい機能に一部制約があります。

しかし、今回紹介した疑似積上げ・-1置換・HTML凡例・上下2段比較といったテクニックを使えば、これらの制約を回避して、メンテナンス性の高い「それっぽい」レポートをMarkdown内で完結させることができます。

特にAIツールとの相性は抜群です。「このタスクデータをMermaidの疑似積上げ棒グラフにして」と頼めば、累積値の計算からコード生成まで一瞬で終わります。ぜひ、日々の進捗報告や振り返り資料に取り入れてみてください。

はじめに

2025年10月新卒入社で、製造・エネルギー事業部所属の古賀です。
2026年3月19日（木）に開催されたGoogle Cloud 主催の「Agentic AI Summit ‘26 Spring」に参加してきました。

本イベントでは、単なるタスクの自動化を行うAIから進化した、自律的に思考し行動する「Agentic AI」をメインテーマとしており、自律型AIがいかに業務プロセスを変革し、ビジネス成果をもたらすかを学びました。

今回は、イベントで発表された多岐にわたる技術を「5つの領域」に整理し、それぞれの領域で「どのような変革が起きるのか」と「それを支える具体的な技術・サービス」を紐づけてまとめました。

1. 業務改革の領域

変革

これまで
現在のAIは非常に優秀ですが、ユーザや組織の文脈を知らないため、毎回ゼロから詳細な背景を説明する必要があります。また、情報のサイロ化が起き、データが様々なシステムに分断されている状態です。そのため、現在のAIは例えるなら「中途入社初日の新人」のような状態であり、プロンプトを出せる限られた従業員しか恩恵を受けられないという問題を抱えています。

これから
Gemini Enterpriseを使用することで、AIを新人から文脈を理解できる「育てるチームメイト」にしていくことが可能です。これにより、個別の作業を自動化する「点の自動化」から、分断されたプロセス全体をカバーする「プロセスの自律化」へと移行することが可能になります。

技術・サービス

Gemini Enterprise
社内外のデータソースと安全に接続できる基盤であり、AIエージェント（自社開発、購入したもの、Google標準）が稼働するプラットフォームとして機能するSaaSプロダクトです。長期記憶（オフィスアプリ等のパーソナライズドデータソース）とパーソナライズによってユーザの過去の行動や好み、特性を記憶し、個別の状況に合わせた提案等が可能になります。さらに、マルチモーダルRAGや各種コネクタを用い、散在する社内データ（CRM、Drive、メール等）にアクセスし、人間と同じように情報を検索・統合できる環境を構築できます。

2. エンジニアリングの領域

変革

これまで
「Gemini 3」モデルでは、アーキテクチャの相談、リファクタリング、テストコード生成、仕様書作成など、開発ライフサイクル全体を支えることが可能です。しかし、LLMでのコード生成はブラウザや専用アプリ上で行われているため、開発環境（IDE）との往復が手間という問題もあります。さらに、人間の処理能力（タイピング速度や思考スピード）が依然として開発のボトルネックになるという構造的な限界が存在しています。

これから
人間がコードを書き、AIがそれを支援する時代から、AIが自律的な部下としてワークフロー全体を主導する時代へとシフトしています。これにより人間の役割は「コードを書くこと」から「何を開発するか」「AIが立てた計画の承認」「最終的な成果物のレビュー」へとシフトし、圧倒的なスピードとスケーラビリティでの開発が可能となります。

技術・サービス

Gemini Code Assist（支援型）
エンジニアが使い慣れたIDE（開発環境）とAIを統合し、シームレスな体験を提供するサービスです。開発者が開いているファイルやプロジェクト構造（コンテキスト）を自動で認識し、的確な提案を実施します。またインライン補完やチャットベースでのコード生成・解説が可能です。

Antigravity（自律型）
エージェント主導の開発プラットフォームです。VS CodeベースのUIを使用しており、Gemini 3だけでなく、ClaudeやOSSモデルなどマルチモデルに対応しています。また、フロントエンド用、バックエンド用など複数のエージェントを立ち上げ、並列で同時開発を進行できます。さらに、エージェントが自律的にブラウザを立ち上げ、描画崩れやロジックの動作確認を自動で実施（動画やスクリーンショットで人間に報告）することが可能です。

3. エージェント運用の領域

変革

これまで
企業において複数のAIエージェントが開発・導入されるマルチエージェント時代を迎えるに伴い、「本当に使われているのか」「ROIは出ているのか」「現在のエージェントが最適か」などの懸念が生まれています。また、従来のBIツール（ダッシュボード）では、定型的な指標の確認は可能ですが、想定外の事象に対する深掘り分析には、データアナリストへ依頼が必要となり「タイムロス」が発生していました。

これから
エージェントの行動を可視化し、評価と改善のサイクルを回すこと、そして得られた対話データをビジネスインサイトに繋げることが成功要因の一つとなってきます。さらに、構造化データだけでなく、画像・動画・PDFやグラフデータなどの非構造化データを駆使し、誰もがデータからインサイトを得られる「データの民主化」を実現し、データを統合的に扱える基盤を構築することが不可欠になります。

技術・サービス

Vertex AI Agent Builder
AIエージェントの開発から運用までをエンドツーエンドで支援する統合プラットフォームです。AgentOps機能が含まれており、プロンプトとレスポンスの文脈からAIが自動で採点基準を生成する「適応型ルーブリック」による回答品質の評価や、安全性・ハルシネーションの監視などを行えます。これによって継続的な改善のループを回し続けることが可能です。

BigQuery Agent Analytics
AIエージェントの行動ログ（ユーザとの対話履歴など）をリアルタイムでBigQueryに収集し、Gemini Enterpriseのような分析用エージェントを使って高度な分析を行うための機能です。開発時に数行のコードを追加するだけでログ収集が始まり、その後は自然言語で問いかけるだけでAIが自律的にSQLを生成し、対話ログから顧客のペインポイント（VoC）を直接検知するだけでなく、「なぜAIが答えられなかったのか」といったエラー原因の特定（AgentOps）までを行ってくれます。

4. 顧客体験の領域

変革

これまで
従来の顧客接点は、ユーザ自身が手動で情報を入力して検索や購買を行う「機能的」なサイトが主流でした。検索やコマースのプロセスは断片化されており、消費者が期待するパーソナライズされた結果や代行アクションに十分に応えられていませんでした。

これから
これからは、AIがユーザに寄り添う「没入型（イマーシブ）」な顧客体験への移行が実現します。断片化された検索やコマースはシームレスな体験へと変わり、AIエージェントがユーザに代わって自律的に情報収集や代行（購買）アクションを実行します。

技術・サービス

Gemini Enterprise for Customer Experience（GECX）
断片化された検索やコマースをシームレスな顧客体験へと変える統合ソリューションスイートです。CX Agent Studioを含めた様々な要素で構成されており、自社データに基づく正確な回答を導く次世代検索エンジン（Vertex AI Search）や、会話データの分析と可視化を行うCustomer Experience Insightsが含まれています。

CX Agent Studio
エージェント構築・テスト・デプロイを担う基盤です。自然言語による指示だけでAIがフローを自動生成するローコード開発により、開発期間を短縮します。また、他社SaaS等と連携した実務アクションの実行や、自然な「割り込み」に対応する高品質な音声対話機能も備えています。さらに、不適切な発言やプロンプトインジェクションを防ぐガードレール機能といったエンタープライズ品質の安全性を標準搭載しつつ、推論プロセスの可視化や「Quality AI」による全対話の自動評価を行えます。

ADK Gemini Live API Toolkit
リアルタイム音声AIエージェントの開発ツールキットです。これまで開発の壁となっていた複雑なストリーミング通信の制御を簡略化し、AIが話している途中でユーザが「割り込み」できる、人間のように自然な双方向の会話を実現します。また、ネイティブオーディオモデルが声のトーンから感情を読み取る機能や、スマートフォンのカメラ映像をリアルタイムに処理するマルチモーダル機能も備えています。

5. セキュリティの領域

変革

これまで
攻撃者による生成AIの利用が一般化し、フィッシングメールの巧妙化や、脆弱性分析の自動化など攻撃手法が高度化しています。そのため、従来の人間主体の監視・対応では、AIによる高度な攻撃スピードに追い付くことが困難になりつつあります。

これから
AIエージェントを活用してSOCのワークロードを低減し、検知・対応の質を向上させる「Agentic SOC」への移行が求められます。現在はアラート発生時のトリアージ・調査・マルウェア解析の支援を実現していますが、将来的には、調査結果への対応、自動ルールチューニングまでをAIが一貫して実行し、ライフサイクル全般をAIが自律的に実行する世界に変わっていくことになります。さらに、AIを防御に活用するだけでなく、AIモデルや学習データそのものを守るための保護策も不可欠になります。

技術・サービス

トリアージ・エージェント
アラート発生時の初期調査を自動化するAIエージェントです。これまで人間が約30分かけて行っていた約20ステップの調査を、約1分で完了させることが可能になり、アラートが陽性か偽陽性かの一次判定を迅速に行えます。

Model Armor
生成AIアプリケーションを脅威から守るためにGoogle Cloudが提供している保護機能です。プロンプトインジェクションのブロックや、不適切な回答を抑制するためのフィルタリング機能を持っています。組織全体のガバナンス基準を適用でき、感度のチューニングも可能となっています。

まとめ

業務改革やエンジニアリングの現場では、AIが自社の文脈を理解して自律的なチームメイトとして働き、顧客接点においてはAIが主体となってユーザに寄り添う没入型の体験が実現しつつあります。 一方で、こうした自律型AIをビジネスで確実に機能させるためには、エージェントの行動を可視化して継続的に改善を回す「運用基盤」と、AIモデルやデータそのものを脅威から守る強固な「セキュリティ体制」が両輪として不可欠であると学びました。

今回の学びを活かし、自律型AIをどのように日々の業務に適応させ、新しいプロセスをデザインしていくかについて、考えていきたいと思います。

初めまして、實藤陸（さねふじりく）です。
2025年新卒入社で、現在は製造エネルギーサービス事業部に所属しています。

今回は新卒入社の私がプロジェクト効率化ツールとして、GAS（文字起こし自動追加GAS）の開発をAIと共同で行いましたので、その内容について共有できればと思います！

開発の背景と課題

今回の開発に至った経緯は、PJにおいて下記のような背景と課題があったためです。

そこで、この一連の作業を自動化するGASの開発に着手しました。

文字起こし自動追加GASの概要

まずは作成したツールの概要を紹介します。
文字起こし自動追加GASは簡潔に言うと、Google Meetの文字起こしや録画ファイルを、所定のフォルダに自動で整理し、Slackに通知するGASです！

2つのGASを用いて、Google Meet（のGemini機能）によって自動生成され、個人のマイドライブに保存される『文字起こし・録画・チャット』ファイルを、PJ共有ドライブ内の各フォルダへ移動し、Slackへ通知します。

GASのざっくり構成図

それぞれのGASの内容

1. GAS（1）：各自のマイドライブから「一時プール」へ（各自で実行）
   • 各自のマイドライブから30分おきに自動で実行。
   • ファイル名の先頭に YYYYMMDD_ を追加し、特定キーワード（顧客名など）を含む会議だけを共有ドライブ内の「一時プールフォルダ」へ移動させます。
2. GAS（2）：プールから各フォルダへ仕分け＆通知（管理者が実行）
   • 毎日夜間に自動実行。
   • プール内のファイルを「顧客会議用」「内部会議用」などに自動で振り分け、移動件数やエラー結果をSlackに通知します。

これにより、どのメンバーが会議の主催者であっても、「文字起こし・録画・チャット」ファイルをPJの共有ドライブの正しいフォルダへ自動で蓄積できるようになり、当初の課題が解決できました！

AIとの共同開発のプロセス

今回の開発において大いに助けられたのが、Geminiの存在でした。

自分はIT未経験入社の新卒で、GASに関する知見はまったくない状態でした。そのため、最初から完璧な設計をするのではなく、とりあえずAIに作ってもらい、動くものを見ながらツッコミを入れて改善していくというアジャイル的な開発プロセスをとりました。

ここではコードを1行も書くことなく、GASを完成させたプロセスをご紹介します。

（1） まずは「動くGAS」を作る！

開発のスタートは、「どうすればいいんだ」というざっくりとした質問をGeminiに投げることでした。
当時の私は何をすればいいかよくわかっていなかったため、綿密な要件定義は行わず、以下のようなニュアンスで指示を出しました。

💬 Geminiへの指示のイメージ
「Google Meetの文字起こしファイルを、マイドライブから共有ドライブに集めたい。とりあえず進め方と動くGASのコードを考えて」

こんな抽象度の高いプロンプトでも、Geminiは大枠の方針を示し、最低限動くコードを一瞬で作成してくれました。

（2） 人間が「観点」を与え、AIにブラッシュアップさせる

動くものができたことで、実際に運用するには何が足りないかが明確に見えてきました。ここからは、上長とも相談しながら、Geminiが作った初期コードに対して人間ならではの観点を追加していく反復作業に入りました。

具体的にGeminiにぶつけた観点を2つ紹介します。

観点1：セキュリティと可視化

初期のコードでは、Slackへの通知機能がなく移動結果が確認しにくかったり、フォルダのID等がコードに「ベタ打ち」されていたりと、セキュリティ観点がほぼ抜け落ちていました。
そこで、コードをレビューさせたり、ポイントで以下のようにツッコミを入れました。

💬 Geminiへのツッコミのイメージ
「ここのフォルダIDやSlackのURL、コードに直接ベタ打ちで書いてるけどセキュリティ的に大丈夫？ベタ打ちを避ける方法で書き直して」

この指示により、外部から見えない「スクリプトプロパティ」を使ってIDを隠す、安全なシステムへと改善してくれました。

観点2：本番運用に向けたアーキテクチャの変更

当初の開発では、「1つのGASを各メンバーにデプロイしてもらい、各自のマイドライブから直接共有ドライブの各フォルダに振り分ける形式」となっていました。
しかし、この構成で本番展開しようとすると、SlackのWebhookやトリガー設定など各メンバーの初期設定の手間が大きすぎることが判明しました。
そこで上長と相談し、横展開のしやすさを最優先して「各自が投げるGASと、管理者が仕分けるGASの2つに分ける」という方針に変更しました。

💬 Geminiへの指示のイメージ
「このツールをチームに横展開することを考えて、各自が投げるGASと管理者が仕分けるGASの2つにコードを分割して」

このように、ざっくりとした要件でまず動くものを作り、必要な観点を後からぶつけていくというプロセスを繰り返すことで、無事に実運用できるツールを完成させることができました。

本開発における学び

ここからは今回のAIとの共同開発における学びを共有できればと思います。

Geminiってすごい

まずは、IT未経験で研修を受けた程度の自分が、今回の開発を業務と並行して短期間で完遂できたのは間違いなくGeminiのおかげです。
今回はGASということもあり、ほとんどエラーのない正確なコードを提供してくれました。
大感謝です。

アジャイルな進め方がAI時代のスタンダード？

今回のように未経験者がAIと協働開発をするには、最初から完璧な設計をするのではなく、とりあえずAIに作ってもらい、動くものを見ながらツッコミを入れて改善していくべきであると感じました（というかそれしか方法がない)。

さらに今後、AIとの共同開発が当たり前になる世界の中では、どんな難易度の開発であっても、コーディングにかかる時間が激減するため、こういったアジャイルな進め方が主流になっていくのではないかと思っています。

そう考えてみると、今回の進め方はまさにAIとの共同開発におけるスタンダードだったのではと個人的には感じています。

人間がやるべきこと

AIとの共同開発が当たり前になる世界のなかで、人間がやるべきこととして、主に下記2点が重要だと感じています。

• なぜその機能が必要なのかを考えること
  Geminiは指示された通りのコードを作るのは得意な一方で、やはり背景を察したりすることはできません。
  そのため、「この機能作って」というプロンプトではなく、「現状こんな課題があって、それを解決するためにこんな機能を作りたい」というプロンプトにする方が圧倒的に求めているものに近いアウトプットができます。
  すなわち、実現したいことの背景や目的、ゴールを整理して示すことがAIとの共同開発においては重要だと学びました。
• コードを理解し観点を与えること
  前述の通り、Geminiは最低限のコードは生成してくれますが、不足している観点があることも多いです（自分の知識不足も原因ではありますが）。
  そこで人間に求められるのは、コードの内容を正しく理解しレビューをする力だと思っています。
  実際にその機能を運用することを想定して、多くの観点からレビューをすることで、AIとの共同開発でも品質の高いアウトプットが出せることを学びました。

終わりに

今回は文字起こし自動追加GASの概要と、AIとの共同開発での学びについて共有させていただきました。

PJ効率化ツールとして文字起こし自動追加GASに興味を持っていただけていたら、非常にうれしいです！
また、自分と同じ若手メンバーなど、IT初学者の方にとってAIとの共同開発の進め方が何かの役に立てば幸いです。

最後まで読んでいただきありがとうございました！

/**
 * ■■■ 文字起こし・録画ファイル選別＆投げ込みボット（メンバー用） ■■■
 * */

const CONFIG = {
  // 1. 検索元フォルダ名
  sourceFolderName: 'Meet Recordings',

  // 2. 移動先プールID（プロパティから取得）
  poolFolderId: PropertiesService.getScriptProperties().getProperty('POOL_FOLDER_ID'),

  // 3. 移動対象キーワード（正規表現）
  targetKeywords: [
    '^\\d{8}_【顧客名A】',
    '^\\d{8}_【顧客名B】',
    '^\\d{8}_【内部プロジェクトA】',
    '^\\d{8}_【内部プロジェクトB】'
  ],

  // 4. 対象ファイル形式
  targetMimeTypes: [MimeType.GOOGLE_DOCS, 'video/mp4', MimeType.PLAIN_TEXT]
};

function moveToPoolWithFilter() {
  if (!CONFIG.poolFolderId) {
    console.error('❌ 設定エラー: POOL_FOLDER_ID が設定されていません。');
    return;
  }

  const props = PropertiesService.getScriptProperties();
  const lastRunStr = props.getProperty('LAST_RUN_TIME');
  const now = new Date();

  // デフォルト検索開始日（過去すべて）
  let searchDateStr = '2000-01-01T00:00:00';

  if (lastRunStr) {
    const lastDate = new Date(lastRunStr);
    if (!isNaN(lastDate.getTime())) {
      // タイムラグ対策（1分前から）
      lastDate.setMinutes(lastDate.getMinutes() - 1);
      searchDateStr = Utilities.formatDate(lastDate, 'GMT', "yyyy-MM-dd'T'HH:mm:ss");
    }
  }

  const query = `modifiedDate > '${searchDateStr}'`;
  console.log(`🔎 高速検索クエリ: ${query}`);

  const sourceFolders = DriveApp.getFoldersByName(CONFIG.sourceFolderName);
  const poolFolder = DriveApp.getFolderById(CONFIG.poolFolderId);
  const regexPatterns = CONFIG.targetKeywords.map(k => new RegExp(k));

  let movedCount = 0;

  while (sourceFolders.hasNext()) {
    const folder = sourceFolders.next();

    try {
      const files = folder.searchFiles(query);

      while (files.hasNext()) {
        const file = files.next();

        if (file.isTrashed()) continue;
        if (!CONFIG.targetMimeTypes.includes(file.getMimeType())) continue;

        try {
          const isMoved = processFile(file, poolFolder, regexPatterns);
          if (isMoved) {
            movedCount++;
          }
        } catch (e) {
          console.error(`❌ ファイル処理エラー: ${file.getName()} (${e.message})`);
        }
      }
    } catch (e) {
      console.error(`❌ 検索エラー(query: ${query}): ${e.message}`);
    }
  }

  props.setProperty('LAST_RUN_TIME', now.toISOString());

  if (movedCount > 0) {
    console.log(`✅ 処理完了: ${movedCount}件のファイルを転送しました。`);
  } else {
    console.log(`✅ 新規転送なし（${searchDateStr} 以降）`);
  }
}

function processFile(file, poolFolder, regexPatterns) {
  const originalName = file.getName();
  let datePrefix = '';

  const dateMatch = originalName.match(/(\d{4})[\/\-\s](0[1-9]|1[0-2])[\/\-\s](0[1-9]|[12]\d|3[01])/);

  if (dateMatch) {
    datePrefix = `${dateMatch[1]}${dateMatch[2]}${dateMatch[3]}`;
  } else {
    const createdDate = file.getDateCreated();
    datePrefix = Utilities.formatDate(createdDate, 'Asia/Tokyo', 'yyyyMMdd');
  }

  let newName = originalName;

  if (!originalName.startsWith(datePrefix)) {
    newName = `${datePrefix}_${originalName}`;
  }

  const isMatch = regexPatterns.some(regex => regex.test(newName));
  if (!isMatch) return false;

  if (file.getName() !== newName) {
    file.setName(newName);
  }

  if (poolFolder.getFilesByName(newName).hasNext()) {
    console.log(`⚠️ [スキップ] プールに同名ファイルが存在: ${newName}`);
    return false;
  }

  file.moveTo(poolFolder);
  console.log(`⭕️ [転送成功] ${newName}`);
  return true;
}

/**
 * ==============================================================================
 * ■■■ 議事録・仕分け＆通知マスターボット（管理者用） ■■■
 * ==============================================================================
 */

const CONFIG = {
  poolFolderId:     PropertiesService.getScriptProperties().getProperty('POOL_FOLDER_ID'),
  internalFolderId: PropertiesService.getScriptProperties().getProperty('INTERNAL_FOLDER_ID'),
  externalFolderId: PropertiesService.getScriptProperties().getProperty('EXTERNAL_FOLDER_ID'),
  slackWebhookUrl:  PropertiesService.getScriptProperties().getProperty('SLACK_WEBHOOK_URL'),

  rules: [
    {
      name: '外部',
      propKey: 'EXTERNAL_FOLDER_ID',
      keywords: ['^\\d{8}_【顧客名A】','^\\d{8}_【顧客名B】']
    },
    {
      name: '内部',
      propKey: 'INTERNAL_FOLDER_ID',
      keywords: ['^\\d{8}_【内部プロジェクトA】','^\\d{8}_【内部プロジェクトB】']
    }
  ]
};

function runBatchSort() {
  Logger.log('--- 管理者バッチ処理開始 ---');

  if (!CONFIG.poolFolderId || !CONFIG.internalFolderId || !CONFIG.externalFolderId || !CONFIG.slackWebhookUrl) {
    Logger.log('❌ エラー: スクリプトプロパティが不足しています。');
    return;
  }

  const slackLogs = [];
  const poolFolder = DriveApp.getFolderById(CONFIG.poolFolderId);
  const files = poolFolder.getFiles();

  let moveCount = 0;
  let remainCount = 0;
  let errorCount = 0;

  const rules = CONFIG.rules.map(r => ({
    folder: DriveApp.getFolderById(PropertiesService.getScriptProperties().getProperty(r.propKey)),
    regex: r.keywords.map(k => new RegExp(k)),
    name: r.name
  }));

  while (files.hasNext()) {
    const file = files.next();
    const fileName = file.getName();
    let isMoved = false;

    try {
      for (const rule of rules) {
        if (rule.regex.some(r => r.test(fileName))) {

          if (rule.folder.getFilesByName(fileName).hasNext()) {
            const msg = `⚠️ [重複] ${fileName} は ${rule.name} に既に存在するためスキップしました`;
            Logger.log(msg);
            slackLogs.push(msg);
            isMoved = true;
            break;
          }

          file.moveTo(rule.folder);

          const logMsg = `✅ [移動] ${fileName} ➡ ${rule.name}`;
          Logger.log(logMsg);
          slackLogs.push(logMsg);

          moveCount++;
          isMoved = true;
          break;
        }
      }

      if (!isMoved) {
         Logger.log(`⚠️ [残留] ${fileName} (条件不一致)`);
         remainCount++;
      }

    } catch (e) {
      const errorMsg = `❌ [エラー] ${fileName}: ${e.message}`;
      Logger.log(errorMsg);
      slackLogs.push(errorMsg);
      errorCount++;
    }
  }

  Logger.log(`処理終了: 移動${moveCount}件 / 残留${remainCount}件 / エラー${errorCount}件`);

  if (slackLogs.length > 0) {
    sendDailyReport(slackLogs, moveCount, remainCount);
  } else {
    Logger.log('通知対象なしのためSlack送信をスキップします。');
  }
}

function sendDailyReport(logs, moveCount, remainCount) {
  const message = {
    "text": "📊 *議事録 自動仕分けレポート*",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": `📊 *本日の仕分け結果*\n実行完了: ${moveCount}件 / プール残留: ${remainCount}件`
        }
      },
      { "type": "divider" },
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": logs.join("\n")
        }
      }
    ]
  };

  try {
    UrlFetchApp.fetch(CONFIG.slackWebhookUrl, {
      "method": "post",
      "contentType": "application/json",
      "payload": JSON.stringify(message)
    });
  } catch (e) {
    Logger.log('Slack送信エラー: ' + e.message);
  }
}

Flyway とは

Flyway はデータベースのスキーマ変更をバージョン管理するマイグレーションツールです。V1__create_table.sql、V2__add_column.sql のようにバージョン番号付きの SQL ファイルを用意しておくと、アプリケーション起動時に未適用のマイグレーションを自動的に検出・実行してくれます。Spring Boot では spring-boot-starter に Flyway が統合されており、依存関係を追加するだけで自動構成が有効になります。

本記事の背景

私たちのプロジェクトでは長らく Flyway なしで運用してきました。テーブル追加やカラム変更は手動で DDL を流していたのですが、環境が増えてきて正直面倒になってきたので、重い腰を上げて導入することにしました。

ところが、いざ導入してみるとすんなりとはいきませんでした。というのも、このプロジェクトはテナント用と管理用の2つの DataSource を持つ構成で、Flyway を適用したいのは管理 DB だけ。Spring Boot の Flyway 自動構成は primary DataSource にしか紐づかないため、手動で Flyway Bean を構成する必要がありました。さらに、既存のテーブルがある状態への後付け導入でいくつかハマりポイントがあったので、本記事ではその辺りの知見を共有します。

• secondary DataSource に手動で Flyway を構成する方法
• baselineOnMigrate(true) の正しい理解と V1 に書くべき内容
• @ConditionalOnProperty を使った環境別の有効/無効切り替え

なぜ Flyway を選んだか — Liquibase との比較

DB マイグレーションツールとしては Liquibase も候補に挙がりました。参考までに両者の比較を載せておきます。

Liquibase は宣言的な定義で RDB の差異を吸収してくれる点が魅力です。単一の RDB 製品で完結するシステムや、ロールバックの自動化が必要なケースでは有力な選択肢になるでしょう。

一方、私たちのプロジェクトでは Oracle と PostgreSQL の両方をサポートしており、DB 固有の構文（CLOB / TEXT の違いや PL/SQL 等）を多用していました。宣言的な定義だけでは対応しきれない場面が多いと判断し、素の SQL をそのまま書ける Flyway を採用しました。Flyway はロールバックをサポートしていないため、マイグレーションに失敗した場合は手動で逆の DDL を流す運用になりますが、管理 DB のスキーマ変更頻度はそこまで高くないのでこれで十分と割り切りました。

システム構成

今回のシステムは以下の2つの DataSource を持ちます。
今考えると、primaryとsecondaryは逆にすべきでした・・・反省。

graph LR    App[Spring Boot アプリケーション]    App -->|primary| TenantDB[(テナントDB
データ)]    App -->|secondary| ManagerDB[(管理DB
設定・マスタ管理)]    style TenantDB fill:#2e7d32,color:#fff    style ManagerDB fill:#1565c0,color:#fff

Spring Boot では spring.datasource.* プロパティで定義された DataSource が primary DataSource として扱われます。Flyway の自動構成（FlywayAutoConfiguration）はこの primary DataSource に紐づいて動作するため、spring.datasource.* 以外で定義した secondary DataSource にはマイグレーションが適用されません。

やりたいことを整理すると以下の通りです。

実装: secondary DataSource に手動で Flyway Bean を構成する

yml 設定

まず application.yml（共通設定）で Spring Boot の自動構成 Flyway を無効化します。

spring:
  # Spring Boot自動構成の Flyway（= primary DataSource に適用）の有効/無効。
  # primary DataSource はテナント用でマイグレーション不要のため無効化。
  # 管理DB（secondary）へのマイグレーションはこの設定とは独立して
  # Java 側で手動構成・実行される。
  flyway:
    enabled: false
    locations: classpath:db/migration/common,classpath:db/migration/oracle

ポイントは2つです。

1. enabled: false で自動構成 Flyway を無効化（primary DataSource にはマイグレーション不要）
2. locations は設定しておく（後述の手動構成 Bean で @Value 経由で再利用）

Java 実装

secondary DataSource の設定クラスに Flyway Bean を手動で定義します。

@Component
@ConfigurationProperties(prefix = "app.manager.datasource")
public class ManagerSqlConfig {

    @Value("${spring.flyway.locations:classpath:db/migration/common}")
    private String[] flywayLocations;

    @Bean(name = "managerDataSource")
    public DataSource managerDataSource() {
        // secondary DataSource の構成（省略）
    }

    /**
     * 管理DB用の Flyway マイグレーションを実行する.
     *
     * Spring Boot の Flyway 自動構成は primary DataSource に紐づくため、
     * secondary DataSource には手動で Flyway を構成する必要がある.
     */
    @Bean(name = "managerFlyway", initMethod = "migrate")
    public Flyway managerFlyway(
            @Qualifier("managerDataSource") DataSource managerDataSource) {
        return Flyway.configure()
                .dataSource(managerDataSource)
                .locations(flywayLocations)
                .baselineOnMigrate(true)
                .load();
    }
}

@Bean(initMethod = "migrate") により、Bean 生成時に自動的に Flyway#migrate() が呼ばれます。

spring.flyway.locations を @Value で参照することで、yml 側でマイグレーションファイルのパスを管理でき、Oracle / PostgreSQL などの Dialect 切り替えにも対応できます。

落とし穴: baselineOnMigrate と V1 マイグレーションの関係

問題

上記の実装でデプロイしたところ、V1 マイグレーションが実行されないという問題が発生しました。

マイグレーションファイル（V1__add_column.sql）に差分DDL（ALTER TABLE）を書いていたにもかかわらず、管理DB にカラムが追加されていませんでした。flyway_schema_history テーブルを確認すると、V1 に対して TYPE=BASELINE のレコードが記録されており、実際のSQLは実行されていませんでした。

baselineOnMigrate とは

baselineOnMigrate(true) は 既にテーブルが存在するスキーマに対して、途中から Flyway を導入するための設定です。

Flyway は通常、空のスキーマに対して V1 から順にマイグレーションを適用することを前提としています。しかし既にテーブルが存在するスキーマに Flyway を導入する場合、Flyway は「このスキーマは管理下にない」としてエラーを出します。baselineOnMigrate(true) を指定すると、Flyway は既存スキーマに対して「ここまでは適用済み」というベースラインを自動的に作成し、それ以降のバージョンからマイグレーションを開始します。

baselineVersion のデフォルトは “1”

ベースラインを「どのバージョンで作成するか」を決めるのが baselineVersion です。デフォルト値は "1" です。

つまり baselineOnMigrate(true) を指定すると:

• flyway_schema_history テーブルが自動作成される
• V1 = ベースライン（＝適用済み扱い） として記録される
• 実際に実行されるのは V2 以降のみ

私たちのような既存スキーマに途中からflywayを導入する場合はこんな流れになります。

1. 既存スキーマ(初期状態)
   • flyway_schema_historyテーブルなし
2. flywayがbaselineOnMigrate=true で初回実行
   • flyway_schema_historyテーブル作成
   • V1をベースラインとして記録
     • TYPE=BASELINE のレコードが作成されるのみ
     • この段階ではマイグレーションSQLは実行されない
3. flywayがV2以降のマイグレーションを実行

実際に flyway_schema_history を見ると、V1 が TYPE=BASELINE として記録されていることが確認できます。execution_time は 0、つまり SQL は実行されていません。

V1 に何を書くべきか

Flyway の baselineOnMigrate は 「V1 の内容は既にスキーマに反映済みである」 という前提で動作します。したがって、V1 には現在のスキーマ状態を再現する全DDL（CREATE TABLE 等）を記述するのが正しい設計です。

db/migration/common/
├── V1__initial_schema.sql       ← 既存スキーマの全DDL（既存環境ではスキップされる）
├── V2__add_is_default.sql       ← ここから実際の差分マイグレーション
├── V3__add_index.sql
└── ...

V1 に全DDLを書いておくことで、環境によって2つの動作が実現できます。

新規環境では baselineOnMigrate はデフォルトの false のままで、V1 の全DDLから順に実行されます。既存環境では baselineOnMigrate(true) により V1 がスキップされ、V2 から差分が適用されます。

V1 に差分DDLを書いてしまった

上記のことが理解できてなかったため、V1 に差分DDL（ALTER TABLE）を書いてしまいました・・・

V1__add_column.sql  ← ALTER TABLE（差分DDL）を記述 → ベースラインでスキップされた

既存環境に途中から Flyway を導入する場合、V1 は「既にスキーマに存在する状態の記録」であり、差分マイグレーションは V2 から開始するのが正解です。

修正後のマイグレーション構成

db/migration/common/
├── V1__initial_schema.sql       ← 全DDL（新規環境構築用に配置）
└── V2__add_is_default.sql       ← 差分マイグレーション（V1 からリネーム）

修正後にアプリを再起動すると、V1 は TYPE=BASELINE のまま、V2 が TYPE=SQL として実行されます。

もし V1 に差分を書いてデプロイしてしまったら

既に baselineOnMigrate(true) で V1 が BASELINE として記録されてしまった場合でも、flyway_schema_history をリセットすることでやり直しが可能です。
私は誤解釈をしていたためやってしまいました・・・みなさんは気をつけてください。

-- V1 で適用された差分DDLを手動で巻き戻す（例: カラム追加の場合は削除）
ALTER TABLE テーブル物理名 DROP COLUMN カラム物理名;

-- flyway_schema_history を初期化
TRUNCATE TABLE "flyway_schema_history";

COMMIT;

リセット後にアプリを再起動すれば、Flyway が BASELINE(V1) を再作成し、V2 から差分マイグレーションを実行します。

なお、flyway_schema_history は Flyway が小文字でテーブルを作成するため、もしOracleを利用してる場合は ダブルクォートで囲まないと ORA-00942: table or view does not exist になります。Flyway 内部では JdbcTemplate 経由で小文字固定のテーブル名が使われており、Oracle のデフォルトの大文字変換とは異なる名前で格納されています。

-- NG: Oracle が大文字の FLYWAY_SCHEMA_HISTORY を探しに行く
TRUNCATE TABLE flyway_schema_history;

-- OK: 小文字のテーブル名を明示指定
TRUNCATE TABLE "flyway_schema_history";

ただし、この手順は Flyway の管理情報を直接操作するため 自己責任 でお願いします。本番環境では十分に検証してから実施してください。

Java コードは baselineVersion の明示指定なし（デフォルト “1”）のままで正しく動作します。

@Bean(name = "managerFlyway", initMethod = "migrate")
public Flyway managerFlyway(
        @Qualifier("managerDataSource") DataSource managerDataSource) {
    return Flyway.configure()
            .dataSource(managerDataSource)
            .locations(flywayLocations)
            .baselineOnMigrate(true)  // 既存環境向け: V1 をベースラインとしてスキップ
            .load();
}

複数の RDB 製品をサポートする場合の tips

Oracle と PostgreSQL の両方をサポートしている場合、マイグレーション SQL の書き方に少し工夫が必要です。

共通 SQL で書ける範囲は意外と広い

Oracle は VARCHAR で宣言すると内部的に VARCHAR2 として扱い、NUMERIC は NUMBER に対応します。そのため、カラム定義を VARCHAR / NUMERIC で統一しておけば、Oracle でも PostgreSQL でも同じ SQL が通ります。

-- Oracle/PostgreSQL 共通で動く
ALTER TABLE LLM ADD IS_DEFAULT VARCHAR(1) DEFAULT '0' NOT NULL;

共通化できない場合は location を分ける

CLOB（Oracle）と TEXT（PostgreSQL）のように自動変換されない型や、DB 固有の構文（CREATE SEQUENCE のオプション、COMMENT ON の書き方の違い等）がある場合は、同じ SQL ファイルでは対応できません。

Flyway の locations 設定で共通と DB 固有のディレクトリを分けて管理します。

db/migration/
├── common/                         ... Oracle/PostgreSQL 共通
│   ├── V2__add_is_default.sql
│   └── V3__insert_default_llm.sql
├── oracle/                         ... Oracle 固有
│   └── V4__add_clob_column.sql
└── postgresql/                     ... PostgreSQL 固有
    └── V4__add_text_column.sql

# application.yml
spring:
  flyway:
    locations: classpath:db/migration/common,classpath:db/migration/oracle

ポイントは、共通と固有の両方に同じバージョン番号を置かないことです。DB 固有の構文が必要な場合は common/ には置かず、oracle/ と postgresql/ の両方に同じバージョンの SQL をそれぞれの方言で配置します。共通の V4 と Oracleもしくはpostgresql の V4 の両方あると、Flyway が重複バージョンとしてエラーにします。

環境ごとの locations 切り替えは yml のプロファイル分割で対応します。

# application-oracle.yml
spring:
  flyway:
    locations: classpath:db/migration/common,classpath:db/migration/oracle

# application-postgresql.yml
spring:
  flyway:
    locations: classpath:db/migration/common,classpath:db/migration/postgresql

dev 環境だけ Flyway を無効にする

開発中はテーブル定義が確定するまで DDL を試行錯誤することが多く、Flyway が自動で走ると不便です。@ConditionalOnProperty を使って、Bean 登録自体を条件付きにします。

@ConditionalOnProperty とは

Spring Boot のアノテーションで、プロパティの値に応じて Bean の登録自体をスキップできます。

@Bean(name = "managerFlyway", initMethod = "migrate")
@ConditionalOnProperty(
    name = "app.manager.flyway.enabled",
    havingValue = "true",
    matchIfMissing = true)
public Flyway managerFlyway(...) { ... }

3つのパラメータの意味は以下の通りです。

この3つの組み合わせにより、以下の挙動になります。

matchIfMissing = true がポイントです。これにより、staging / prod の yml にわざわざ enabled: true を書く必要がなく、dev だけ false を明示指定すればよい設計になります。

Bean 単位で効く

@ConditionalOnProperty はメソッドレベルのアノテーションです。クラス全体ではなく、そのメソッドで定義される Bean だけが条件の対象になります。

// 例；管理DB用のConfiguration
@Component
public class ManagerSqlConfig {

    @Bean
    public DataSource managerDataSource() { ... }      // ← 常に登録

    @Bean
    @ConditionalOnProperty(...)                         // ★ ここだけ条件付き
    public Flyway managerFlyway(...) { ... }
}

これにより、Flyway を無効にしても管理DB への接続や SQL 実行は通常通り動作します。

yml 設定

dev 環境用の yml にだけプロパティを追加します。

# application-dev.yml
app:
  manager:
    flyway:
      enabled: false  # マイグレーション DDL を手動確認してから適用する

staging / prod では未定義のまま（= matchIfMissing = true によりデフォルト有効）にします。

設定の全体像まとめ

最終的な設定の対応関係を整理します。

プロパティの役割分担

環境別設定

Java コード最終形

@Component
@ConfigurationProperties(prefix = "app.manager.datasource")
public class ManagerSqlConfig {

    @Value("${spring.flyway.locations:classpath:db/migration/common}")
    private String[] flywayLocations;

    @Bean(name = "managerDataSource")
    public DataSource managerDataSource() {
        // DataSource 構成（省略）
    }

    /**
     * 管理DB用の Flyway マイグレーション.
     *
     * {@code app.manager.flyway.enabled=false} で無効化できる（dev 環境向け）.
     */
    @Bean(name = "managerFlyway", initMethod = "migrate")
    @ConditionalOnProperty(
        name = "app.manager.flyway.enabled",
        havingValue = "true",
        matchIfMissing = true)
    public Flyway managerFlyway(
            @Qualifier("managerDataSource") DataSource managerDataSource) {
        return Flyway.configure()
                .dataSource(managerDataSource)
                .locations(flywayLocations)
                .baselineOnMigrate(true)
                .load();
    }
}

おわりに

マルチ DataSource 構成で Flyway を使う際のポイントをまとめます。

1. Spring Boot の Flyway 自動構成は primary DataSource 専用。secondary DataSource には @Bean(initMethod = "migrate") で手動構成が必要
2. baselineOnMigrate(true) は既存スキーマへの Flyway 後付け導入用。V1 は「現在のスキーマ状態」を記録する全DDLを配置し、実際の差分マイグレーションは V2 から開始する
3. @ConditionalOnProperty で Bean 単位の有効/無効切り替えが可能。matchIfMissing = true により、無効にしたい環境だけ false を指定すればよい

特に 2 は Flyway のドキュメントを読んでいても見落としがちなポイントだと感じました。baselineOnMigrate の意味を正しく理解せずに V1 に差分DDLを書いてしまうと、既存環境ではスキップされ、新規環境でしか実行されないという事態になります。

Appendix: Flyway 公式ドキュメント

本記事で扱った Flyway の設定項目に関する公式ドキュメントへのリンクです。

このあたり、minioがDockerイメージの配布をやめてメンテナンスモードになったり、LocalStackがユーザー登録必須になってCIで使いにくくなったりでにわかに話題になっていたところですね。

• さくらんぼの技術備忘録: 手軽に使えるS3互換ストレージを求めて
• minioがdockerイメージを配布しなくなったので新しいS3互換ストレージを探す

ちょっとしたウェブアプリのバックエンドのストレージとしてオブジェクトストレージが欲しくなったのですが、これまではminioをたまに使ったりしていたものの、別のものを検討するにあたり、docker composeで一緒に起動するという使い方で使いやすいものということで、いろいろ比べてrustfsを選んでみました。

compose.yamlでの利用方法

rustfsの公式イメージをそのまま使うだけです。一瞬で起動します。

• デフォルトで9000ポートでAPIのエンドポイントを、9001で管理画面(RUSTFS_CONSOLE_ENABLEが必要)を公開します
• 複数ボリュームのレプリケーションとか色々複雑な機能もありますが、テスト用で可用性はいらなかったので1ボリュームにしています
• 起動時にはバケットができて欲しいところなので、amazon/aws-cliイメージを使って起動時にバケットを作るようにします

services:
  rustfs:
    image: rustfs/rustfs:latest
    environment:
      RUSTFS_CONSOLE_ENABLE: "true"
      RUSTFS_ACCESS_KEY: rustfsadmin
      RUSTFS_SECRET_KEY: rustfsadmin
      RUSTFS_VOLUMES: /data/rustfs0
    volumes:
      - rustfs-data:/data
      - rustfs-logs:/logs
    ports:
      - "9000:9000"
      - "9001:9001"
    healthcheck:
      test: ["CMD", "sh", "-c", "curl -sS http://localhost:9000/ >/dev/null"]
      interval: 1s
      timeout: 5s
      retries: 20

  rustfs-init:
    image: amazon/aws-cli:2.31.15
    entrypoint: ["/bin/sh", "-c"]
    command:
      - |
        set -eu
        until aws --endpoint-url http://rustfs:9000 s3api list-buckets >/dev/null 2>&1; do
          sleep 2
        done
        for bucket in data-bucket log-bucket; do
          aws --endpoint-url http://rustfs:9000 s3api create-bucket --bucket "$$bucket" || true
        done
    environment:
      AWS_ACCESS_KEY_ID: rustfsadmin
      AWS_SECRET_ACCESS_KEY: rustfsadmin
      AWS_REGION: us-east-1
    depends_on:
      rustfs:
        condition: service_healthy

volumes:
  rustfs-data:
  rustfs-logs:

使い方を調べると、RUSTFS_ADDRESSなどの環境変数でアドレスを定義しているものなどもありますが、なくてもデフォルトで9000番（UIは9001番）ポートで開いたので省略しました。

管理画面は動作も軽快だしなかなか良いですね。今まで触ったことのあるウェブを使ったファイル管理画面の中では一番スピードが速くて体験が良いですね。

Presigned URL

これでAWS SDKを使ったデータの読み書きは問題ありませんでしたが、Presigned URLの発行で問題が発生しました。rustfsの問題というかDockerを使っているから起きた問題ですが、rustfsでは、Presigned URLで発行されるURLはリクエスト時のホスト情報をもとに作られます。Dockerの中からはhttp://rustfs:9000というドメインでアクセスしますが、外からはhttp://localhost:9000なので、発行されたURLのままではアクセスできないということが起きました。

これは発行時にクライアントを新規で作って、ホストをhttp://localhost:9000に設定してそれで発行し直す必要がありました。

   // この環境変数があったらそのホストでURLを発行
endpoint := os.Getenv("RUNTASK_RUSTFS_OBJECT_PUBLIC_ENDPOINT")
if endpoint != "" {
tempOptions := s.options
tempOptions.Endpoint = endpoint
tempClient, err := newS3Client(context.Background(), tempOptions)
if err == nil {
presigner := s3.NewPresignClient(tempClient)
presigned, err := presigner.PresignGetObject(context.Background(), &s3.GetObjectInput{
Bucket: aws.String(s.bucket),
Key:    aws.String(key),
}, func(opts *s3.PresignOptions) {
opts.Expires = expiry
})
if err == nil {
return presigned.URL, nil
}
// fallthrough to try using the existing client
}
}
   // 設定がない場合は普通に発行
presigner := s3.NewPresignClient(s.client)
presigned, err := presigner.PresignGetObject(context.Background(), &s3.GetObjectInput{
Bucket: aws.String(s.bucket),
Key:    aws.String(key),
}, func(opts *s3.PresignOptions) {
opts.Expires = expiry
})
if err != nil {
return "", err
}
return presigned.URL, nil

Endpointを上書きしてしまったら逆にバックエンドのサーバーからrustfsに繋がらないからダメなのでは？と思い込んでましたが、このPresigned URLの発行はS3 APIを実際に叩いているわけではなく、SDKの中で発行しているらしい。

使う技術はその名の通り「署名」です。TLSは機密の秘匿化(外から読めない)、完全性保証(改竄検知)、認証(証明書によるサーバーの身元確認)などを行いますが、Presigned URLの場合はこのうちの完全性の保証をベースに、いつ誰が許可したのかの情報が後からわかるようにしています。

サービスにアクセスするのに使うURLに「誰が」というのを明らかにするキーIDと期限が付与されて、シークレットアクセスキーを使って署名されます。署名されているので期限や誰が、といった情報の改ざんは許しません。

クライアントはそのURLを使ってS3からファイルをダウンロードしたり、ファイルをアップロードします。S3(ここではrustfs)はその署名をみて、改竄されていないことの確認とともに、誰が署名したのかを確認します。ブラウザ自身はクレデンシャルを持っていなくても、その署名をもとにして認可制御が行われ、読み書きが成功するという流れです。

Endpointを書き換えたクライアントを一時的に作るという方針でも、実際にそのクライアントでS3にリクエストを投げることはなくてURLの発行にしか使わないので問題なく利用できるんですね。てっきり、一時的に利用可能なトークン的なURLとして発行されてサーバー側に情報を持っているのかと思いましたが、そんなことはないんですね。勉強になりました。

まとめ

S3以外もいろいろ必要となる場合は他のAWSエミュレータ（motoとかflociとか)の方が良いかもしれませんが、今回はS3だけが欲しかったのでrustfsを選んでみて使ってみたメモでした。

今まではminioを考えずに使っていましたが、今回別のものを検討してrustfsを使ってみました。seaweedfsとかも良さそうでしたが、filterとかたくさんコンテナが必要そうだったので1つで済むrustfsにしました。コンテナのメモリ消費90MBぐらいですね。動きも軽快なので今後も使ってみようと思いました。

はじめに

最近、コンテナオーケストレーションの技術領域に興味をもち、Kubernetesを触り始めました。早速自宅で飼ってるMiniPC（ホームサーバ）にArgoCDやLonghornを入れてみたものの、Deployment、Pod、Serviceなど初めましての概念ばかり。気づいたら、AIの指示通りにただコマンド打つマンになっていました。

このままではまずいと思い、Kubernetesの基礎的な挙動を追うことにしました。今回は、どのような流れでPodが作られているのかを実験し、そのアウトプットとしてこの記事にまとめています。

※実験にはMinikubeを使っています。初学者が調べながらまとめたものなので、誤りがあればご指摘ください。

Pod起動までの流れの概要

Podが起動するまでの流れを紹介します。複数のKubernetesコンポーネントが登場しますが、この記事のメインテーマではないため、用語は簡単な説明に留めます。詳細が気になる方は、既存の解説記事や公式ドキュメントをご参照ください。

kubectl run
  ↓
API Server → etcd（Podデータ保存、ノード未割り当て）
  ↓
Scheduler（最適なノードを割り当て）
  ↓
kubelet（コンテナイメージのPull・起動）
  ↓
podが起動

• etcd：Kubernetesの全状態を保存するデータベース
• API Server：全コンポーネントからのリクエスト受付と、状態変更の通知する窓口
• Scheduler：Podをどのノードで動かすかを決定するスケジューラ
• kubelet：各ノード上で実際にコンテナを起動・管理する実行エンジン

補足：kubectl runはPodを直接作成します。Deployment経由の場合は、Controller ManagerがDeploymentデータ → ReplicaSetデータ → Podデータ と各種データを作成するステップが加わります。この記事では、簡略化のためkubectl runによる直接的な作成を追いかけます。

実験1：イベントログでPod作成の流れを確認する

最初の実験として、実際にkubectl runを実行し、出力されるイベントログを確認してみます。

% kubectl run log-test --image=nginx
pod/log-test created
% kubectl get events -w
LAST SEEN   TYPE     REASON      OBJECT         MESSAGE
23m         Normal   Scheduled   pod/log-test   Successfully assigned default/log-test to minikube
22m         Normal   Pulling     pod/log-test   Pulling image "nginx"
22m         Normal   Pulled      pod/log-test   Successfully pulled image "nginx" in 1.481s (1.481s including waiting). Image size: 180545980 bytes.
22m         Normal   Created     pod/log-test   Container created
22m         Normal   Started     pod/log-test   Container started

REASON列とMESSAGE列を見ると、まずScheduledでPodがノード（ここではminikube）に割り当てられ、その後にコンテナの立ち上げ処理が始まっていることがわかります。

さらにkubectl get events -o yaml とオプションを追加すると、各イベントがどのコンポーネントから出力されたのかを詳しく確認できます。

% kubectl get events -o yaml
apiVersion: v1
items:
- action: Binding
  apiVersion: v1
  eventTime: "2026-03-17T08:45:27.742811Z"
  firstTimestamp: null
  involvedObject:
    apiVersion: v1
    kind: Pod
    name: log-test
    namespace: default
    resourceVersion: "62245"
    uid: c79a534d-9c74-45bf-acf4-5a9985c39c14
  kind: Event
  lastTimestamp: null
  message: Successfully assigned default/log-test to minikube
  metadata:
    creationTimestamp: "2026-03-17T08:45:27Z"
    name: log-test.189d9485200842b1
    namespace: default
    resourceVersion: "62247"
    uid: 822856bb-0e26-4942-8d78-ac1eff975cb0
  reason: Scheduled
  reportingComponent: default-scheduler
  reportingInstance: default-scheduler-minikube
  source: {}
  type: Normal
- apiVersion: v1
  count: 1
  eventTime: null
  firstTimestamp: "2026-03-17T08:45:28Z"
  involvedObject:
    apiVersion: v1
    fieldPath: spec.containers{log-test}
    kind: Pod
    name: log-test
    namespace: default
    resourceVersion: "62246"
    uid: c79a534d-9c74-45bf-acf4-5a9985c39c14
  kind: Event
  lastTimestamp: "2026-03-17T08:45:28Z"
  message: Pulling image "nginx"
  metadata:
    creationTimestamp: "2026-03-17T08:45:28Z"
    name: log-test.189d94853f8ec93d
    namespace: default
    resourceVersion: "62249"
    uid: 212f6090-34de-46dd-82eb-d721ace1b32a
  reason: Pulling
  reportingComponent: kubelet
  reportingInstance: minikube
  source:
    component: kubelet
    host: minikube
  type: Normal
- apiVersion: v1
  count: 1
  eventTime: null
  firstTimestamp: "2026-03-17T08:45:30Z"
  involvedObject:
    apiVersion: v1
    fieldPath: spec.containers{log-test}
    kind: Pod
    name: log-test
    namespace: default
    resourceVersion: "62246"
    uid: c79a534d-9c74-45bf-acf4-5a9985c39c14
  kind: Event
  lastTimestamp: "2026-03-17T08:45:30Z"
  message: 'Successfully pulled image "nginx" in 2.135s (2.135s including waiting).
    Image size: 180542930 bytes.'
  metadata:
    creationTimestamp: "2026-03-17T08:45:30Z"
    name: log-test.189d9485beda4a95
    namespace: default
    resourceVersion: "62252"
    uid: 3eb2fd61-7b0b-4f62-b7c3-e5a4be893399
  reason: Pulled
  reportingComponent: kubelet
  reportingInstance: minikube
  source:
    component: kubelet
    host: minikube
  type: Normal
- apiVersion: v1
  count: 1
  eventTime: null
  firstTimestamp: "2026-03-17T08:45:30Z"
  involvedObject:
    apiVersion: v1
    fieldPath: spec.containers{log-test}
    kind: Pod
    name: log-test
    namespace: default
    resourceVersion: "62246"
    uid: c79a534d-9c74-45bf-acf4-5a9985c39c14
  kind: Event
  lastTimestamp: "2026-03-17T08:45:30Z"
  message: Container created
  metadata:
    creationTimestamp: "2026-03-17T08:45:30Z"
    name: log-test.189d9485c0e87bde
    namespace: default
    resourceVersion: "62253"
    uid: df68a670-7684-4573-beff-b92e5a6bbdec
  reason: Created
  reportingComponent: kubelet
  reportingInstance: minikube
  source:
    component: kubelet
    host: minikube
  type: Normal
- apiVersion: v1
  count: 1
  eventTime: null
  firstTimestamp: "2026-03-17T08:45:30Z"
  involvedObject:
    apiVersion: v1
    fieldPath: spec.containers{log-test}
    kind: Pod
    name: log-test
    namespace: default
    resourceVersion: "62246"
    uid: c79a534d-9c74-45bf-acf4-5a9985c39c14
  kind: Event
  lastTimestamp: "2026-03-17T08:45:30Z"
  message: Container started
  metadata:
    creationTimestamp: "2026-03-17T08:45:30Z"
    name: log-test.189d9485c5d61a22
    namespace: default
    resourceVersion: "62254"
    uid: edf2dbb3-11e1-49e6-bb91-6dbca2d51edb
  reason: Started
  reportingComponent: kubelet
  reportingInstance: minikube
  source:
    component: kubelet
    host: minikube
  type: Normal
kind: List
metadata:
  resourceVersion: ""

出力されたイベントログの reportingComponent フィールドを確認すると、各イベントの出力元は以下です。

• Scheduled → reportingComponent: default-scheduler
• Pulling / Pulled / Created / Started → reportingComponent: kubelet

概要で確認した通り、まずSchedulerがノードを割り当てた後、そのノードのkubeletがコンテナの起動処理を行っていることが、実際のログからも確認できました。

Static PodとMirror Pod

ここまででpodが起動するまでの流れはわかったのですが、ここで1つ疑問が湧きました。

先ほど確認した通り、Podが起動するにはSchedulerによるノード割り当てが必要です。しかし、そのScheduler自身もPodとして動いています。となると、Schedulerを起動するためのSchedulerが必要で、そのSchedulerを起動するためにさらにSchedulerが必要で、、、と無限ループに陥ってしまいます。最初のSchedulerは一体どのように起動されているのでしょうか？

結論から言うと、 SchedulerはAPI Serverや別のSchedulerを経由せず、kubeletがマニフェストファイルから直接起動していました。

実際のSchedulerのマニフェストファイルを確認すると、以下のようになっています。kindが Deployment ではなく Pod となっており、Podデータそのものが定義されていることがわかります。

% minikube ssh
$ sudo cat /etc/kubernetes/manifests/kube-scheduler.yaml
apiVersion: v1
kind: Pod
metadata:
  labels:
    component: kube-scheduler
    tier: control-plane
  name: kube-scheduler
  namespace: kube-system
spec:
  containers:
  - command:
    - kube-scheduler
    ...

このように、特定のディレクトリにマニフェストを配置し、API Serverを経由せずにkubeletが直接起動・管理するPodをStatic Podと呼びます。Kubernetesの起動時には、コントロールプレーンのkubeletがこの仕組みを利用して、API Serverやetcd、Schedulerなどの主要なコンポーネントをStatic Podとして起動しています。

ただ、このStatic PodはAPI Serverを経由しないため、etcd上に実体がありません。そのままでは、kubectl get podsで確認できず、クラスタ全体の状態を一元管理する上で不便です。そこでkubeletは、Mirror Podと呼ばれる読み取り専用のPodを作成します。kubectl get pods -n kube-systemで見えるkube-scheduler-minikubeは、実はこのMirror Podでした。

実験2：Schedulerを止めてみる

ここまでの話が本当なら、以下が成り立つはずです。

• Mirror Podを削除しても、Schedulerは止まらない（本体はマニフェストファイルだから）
• マニフェストファイルを削除（移動）すると、Schedulerが止まる
• Schedulerが止まると、新しいPodはノードに割り当てられずPendingのままになる

というわけで、さっそく試してみましょう。

1. Mirror Podを削除する

kubectl delete podでkube-scheduler-minikubeを削除してみます。しかし、何度削除しても、即座に復活し、kubectl get podsの結果に出てきます。

% kubectl delete pod kube-scheduler-minikube -n kube-system
pod "kube-scheduler-minikube" deleted from kube-system namespace
% kubectl get pods -n kube-system
NAME                               READY   STATUS    RESTARTS   AGE
...
kube-scheduler-minikube            1/1     Running   0          5s
...

2. マニフェストファイルを移動する

次にminikube sshでMinikubeのノード内入り、マニフェストファイルを他の場所に動かしてみます（削除すると戻すのが面倒なのでmvにしました）。

すると、あれだけ何度削除しても復活していたkube-scheduler-minikubeが、kubectl get podsから消えました。

% minikube ssh
$ sudo mv /etc/kubernetes/manifests/kube-scheduler.yaml /tmp/
$ exit
% kubectl get pods -n kube-system
NAME                               READY   STATUS    RESTARTS   AGE
coredns-7d764666f9-bbkvl           1/1     Running   0          11h
etcd-minikube                      1/1     Running   0          11h
kube-apiserver-minikube            1/1     Running   0          11h
kube-controller-manager-minikube   1/1     Running   0          11h
kube-proxy-fj8zg                   1/1     Running   0          11h
storage-provisioner                1/1     Running   0          11h

3. Schedulerなしで新しいPodを作成する

このSchedulerがいない状態で、新しいPodを作成してみます。Podデータ自体は作成できましたが、STATUSがPendingのまま動かず、NODEも<none>のままです（必要な情報を出力するためcustom-columnsオプションをつけています）。

% kubectl run new-pod --image=nginx
pod/new-pod created
% kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName
NAME                         STATUS    NODE
hello-node-64fc5894d-57r8s   Running   minikube
hello-node-64fc5894d-7cqrw   Running   minikube
hello-node-64fc5894d-jl4pb   Running   minikube
new-pod                      Pending   <none>

どれだけ待ってもRunningになることはありませんでした。

Schedulerがいないと、Podデータは作成されても、ノードが割り当てられないため、冒頭で確認したフローのSchedulerのステップで処理が止まってしまうことが実際の挙動でも確認できました。

おわりに

解説動画や記事を見ても、Kubernetesの各概念やその関係性がピンとこず、「デプロイするとPodが作れてその中にコンテナがいるらしい」くらいの認識でした。そんな状態だったので、当然kubectlコマンドの意味がわかるはずもなく、結果としてAIの指示通りにコマンド打つマンと化していました。

しかし今回、小さな実験を通して手を動かしてみたことで、裏側で各コンポーネントがどのように連携して動いているのかを具体的に追うことができ、一気に理解が深まりました。特にSchedulerは、こうして実験してみなければ存在すら知らなかった概念だったため、非常に学びになりました。

今回の実験で、何度も消されたりファイルを移動させられたりと散々な目に遭わせてしまったSchedulerには、この場を借りて感謝と謝罪を述べて締めくくりたいと思います。

今回はAWS上のLambdaで自作したプライベートなMCPサーバーをDify上で使用する手順について記事にします。これから社内でもどんどん広がっていくであろうMCPを使っていてとても面白かったので、ぜひ皆さんも本記事を参考に試してみてください！

概要

「社内でLLMに様々なスキルを持たせたい」というのは、多くの企業が抱える要望です。本記事では、AWS Lambda上に自作のプライベートなMCP（Model Context Protocol）サーバーを構築し、それをDifyから呼び出す手順を解説します。

セキュリティを担保しつつ、誰もが簡単にAIアプリを構築できる環境の「第一歩」を目指します。

最終的には以下のようにDifyからMCPサーバーにアクセスできます。

以下のツールではこんにちはに対してHELLOを返すcalculate_helloというmcpツール、計算について、足し算、掛け算、引き算を行うcalculate_add,calculate_product,calculate_subというmcpツールが使われています。

これを応用してWeb検索を行ったり、Googleカレンダーに予定を自動で入れることができます。

本記事のキーテクノロジー

Dify

• Dify公式サイト

Difyは、LLMアプリを直感的に開発できるオープンソースのLLMアプリ開発プラットフォームです。RAG（検索拡張生成）やエージェント機能を手軽に実装できるのが特徴です。

本記事では社内ネットワークのEC2でDifyを動かすことでプライベートな構築を実現しています。

MCP

Anthropicが公開したMCPは(参考：Model Context Protocol（MCP）とは)、LLMと外部データ（DB、API、ローカルファイル等）を接続するためのオープンプロトコルです。これまではツールごとに専用の繋ぎ込みが必要でしたが、MCPという「共通規格」を通すことで、一つのMCPサーバーを作るだけで様々なAIクライアントからデータを利用可能になります。似ているものでRAGがありますがRAGは「知識の検索・参照」に特化しているのに対し、MCPは「機能（ツール）の呼び出し・実行」に特化しています。

API Gateway+Lambdaによるプライベートな環境

社内DBや秘匿性の高い情報が流出するリスクを排除するため、社内ネットワーク内での運用が求められるケースがあります。

今回は上記を実現するべく、API Gatewayのアクセスを社内ネットワークからに制限し、すべてのリソースを社内に置いておくことでプライベートな環境を実現することを目指しました。
※前提として、社内ネットワークとAWS環境がVPN接続されていることとします。

通信方式

MCPには、ローカルMCP（stdio）とリモートMCP（Streamable HTTP）の2種類があります。ローカルMCPの場合、同じ環境を相手のPCにも構築する必要があり、共有に手間がかかってしまうので、リモートMCPを採用しました。

また、リモートMCPをサーバレスで実行するために通信方式は以下の設定にしています。(参考：MCPの通信方式)

• stateless_http: stateless_http=True に設定し、本来Statefulな通信を前提とするMCPプロトコルをステートレスなHTTP通信に変換することでLambdaのような1回切りのリクエストに対応させます
• Streamable_http：Lambdaでの1回限りの重い処理を、タイムアウトで切断される前に小出しで届けて完結させる

構成図

本構成では、セキュリティを最優先し、API Gatewayを「プライベート」モードでデプロイします。これにより、社内ネットワークからのみAIツールを呼び出すことが可能になります。

Lambda採用理由

EC2でMCPサーバをホストした場合、常時EC2を起動しておく必要があり、利用していない期間も不要な料金が発生します。そこでサーバレスなLambdaでホストすることで、MCPサーバーが呼ばれた時だけ料金が発生するので、コストを抑えられます。

本構成のデメリット

大量のログ解析や複雑なデータ集計など、完了までに時間がかかるタスクを依頼すると、AIに結果が返る前にAPI Gatewayのタイムアウト制限より、接続が切れてエラーになる可能性があります。

また、VPCエンドポイントは月10ドルほどの固定費がかかるというデメリットも挙げられます。

構築手順

1. まずは開発環境（EC2）にAWS SAM CLIやPython 3.11をインストールし、必要なIAMロールを付与します
2. コードを作成してAWSにデプロイ

ファイル構成は以下の通りです。

.
├── mcp_server
│   ├── __init__.py
│   └── __main__.py
├── requirements.txt
├── run.sh
└── template.yaml

mcp_server/__init__.py は空ファイルで大丈夫です。

touch mcp_server/'__init__.py'

import uvicorn
from fastmcp import FastMCP

# FastMCPの初期化
# stateless_http=True にすることで、Lambdaのような1回切りのリクエストに対応させます
mcp = FastMCP("MyRemoteMCP", stateless_http=True)

# ツール定義：型ヒントとドキュメント文字列がそのままMCPの定義になります
@mcp.tool()
def calculate_add(a: float, b: float) -> str:
    """2つの数値を足し合わせます"""
    result = a + b
    return f"計算結果: {a} + {b} = {result}"

# @mcp.tool()でいくつでもツールを追加可能

# FastMCPが内部で生成したFastAPIアプリを抽出
app = mcp.http_app()

if __name__ == "__main__":
    # Lambda Web Adapterが待機する8080ポートで起動
    uvicorn.run(app, host="0.0.0.0", port=8080)

#!/bin/bash
exec python -m mcp_server

run.shに実行権限を付与。

chmod +x run.sh

fastmcp==2.14.5
fastapi==0.128.1
uvicorn==0.40.0

3. AWSリソースの構築

以下のSam templateを実行すれば本記事のAWSリソースが構築できます。
[]内は各々の環境に合わせて変更してください。

Transform:
  - AWS::Serverless-2016-10-31
  - AWS::LanguageExtensions

Parameters:
  VpcId: { Type: String, Default: vpc-[VPCID] }
  SubnetId1: { Type: String, Default: subnet-[サブネットID] }
  SubnetId2: { Type: String, Default: subnet-[サブネットID] }

Resources:
  # --- セキュリティグループ ---
  InternalServiceSG:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: Allow internal traffic for MCP Server
      VpcId: !Ref VpcId
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 443
          ToPort: 443
          CidrIp: [CiderIp]

  # --- VPCエンドポイント (API Gateway用) ---
  MyVpce:
    Type: AWS::EC2::VPCEndpoint
    Properties:
      ServiceName: !Sub "com.amazonaws.${AWS::Region}.execute-api"
      VpcEndpointType: Interface
      VpcId: !Ref VpcId
      SubnetIds: [ !Ref SubnetId1, !Ref SubnetId2 ]
      SecurityGroupIds: [ !Ref InternalServiceSG ]
      PrivateDnsEnabled: true

  # --- API Gateway (Private) ---
  MyApi:
    Type: AWS::Serverless::Api
    DependsOn: MyVpce
    Properties:
      Name: mcp-api
      StageName: prod
      EndpointConfiguration:
        Type: PRIVATE
        VPCEndpointIds:
          - !Ref MyVpce
      Auth:
        ResourcePolicy:
          CustomStatements:
            - Effect: Allow
              Principal: "*"
              Action: "execute-api:Invoke"
              Resource: "execute-api:/*/*/*"
            - Effect: Deny
              Principal: "*"
              Action: "execute-api:Invoke"
              Resource: "execute-api:/*/*/*"
              Condition:
                StringNotEquals:
                  "aws:SourceVpce": !Ref MyVpce
      DefinitionBody:
        openapi: "3.0.1"
        paths:
          /{proxy+}:
            x-amazon-apigateway-any-method:
              x-amazon-apigateway-integration:
                httpMethod: POST
                type: aws_proxy
                uri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${Function.Arn}/invocations"
              responses: {}

  # --- Lambda関数(VPC内) ---
  Function:
    Type: AWS::Serverless::Function
    Properties:
      Architectures: [arm64]
      Runtime: python3.11
      Timeout: 30
      CodeUri: .
      Handler: run.sh
      Layers:
        - !Sub arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:18
      VpcConfig:
        SecurityGroupIds: [ !Ref InternalServiceSG ]
        SubnetIds: [ !Ref SubnetId1, !Ref SubnetId2 ]
      Environment:
        Variables:
          AWS_LAMBDA_EXEC_WRAPPER: /opt/bootstrap
          PORT: 8080
      Events:
        ProxyApiRoot:
          Type: Api
          Properties:
            RestApiId: !Ref MyApi
            Path: /{proxy+}
            Method: ANY

  # --- API GatewayからLambdaを呼ぶ許可 ---
  LambdaInvokePermission:
    Type: AWS::Lambda::Permission
    Properties:
      Action: lambda:InvokeFunction
      FunctionName: !Ref Function
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${MyApi}/*"

Outputs:
  FunctionArn:
    Description: "Lambda Function ARN"
    Value: !GetAtt Function.Arn
  VpceId:
    Description: "VPC Endpoint ID"
    Value: !Ref MyVpce
  ApiUrl:
    Description: "API Gateway URL"
    Value: !Sub "https://${MyApi}.execute-api.${AWS::Region}.amazonaws.com/prod/"