本記事は 2026 年 7 月 6 日 に公開された「 Deploying VCF 9.1 on Amazon EVS with End-to-End Automation 」を翻訳したものです。 はじめに Amazon Elastic VMware Service (Amazon EVS) を使用すると、Amazon VPC 内の AWS ベアメタル EC2 インスタンス上で VMware Cloud Foundation (VCF) を直接実行できます。EVS では、使い慣れた VMware スタックの運用一貫性を維持しながら、AWS クラウドサービスの弾力性、セキュリティ、豊富な機能を活用できます。 VCF 9 は VMware Cloud Foundation の最新リリースであり、以前の VCF 5.2 リリースとは根本的に異なる方法で Amazon EVS と連携します。VCF 5.2 では、EVS サービスがデプロイ全体をエンドツーエンドで処理していました。VLAN サブネットのデプロイ、ホストを含む EVS 環境、および完全な VCF スタックはすべて、サービスが自動的にプロビジョニングおよび設定していました。VCF 9 では、Amazon EVS はセルフデプロイモードと呼ばれる方式でのみ動作します。 セルフデプロイモードとは？ セルフデプロイモードでは、Amazon EVS が基盤となる AWS インフラストラクチャをプロビジョニングします。具体的には、VCF に必要な VLAN サブネットと、選択した ESXi バージョン（9.0 または 9.1）を実行するベアメタル EC2 ホストです。ただし、サービスが担うのはここまでです。EVS は VCF 自体のインストールや設定は行いません。EVS が代わりに VCF 9 をデプロイするオプションは存在しません。 つまり、EVS がホストとネットワークを提供した後は、VCF のインストールはお客様の責任となります。VMware のドキュメントに従って手動でインストールするか、自動化を使ってプログラム的に処理できます。本ブログ記事ではまさにその自動化を取り上げます。AWS が公開した エンドツーエンドの自動化ツールキット は、前提条件となる AWS インフラストラクチャと EVS 環境のプロビジョニングから、VCF のインストールおよび設定まで、ワークフロー全体を処理します。このツールキットは VCF 9.0 と 9.1 の両方に対応しています。 VCF デプロイを自動化する理由 セルフデプロイモードでは VCF 9 のインストールはお客様の責任であるため、自動化が特に効力を発揮します。VCF の手動インストールには、数十もの設定ステップ、複雑な JSON 仕様の作成、パスワード生成、そして数時間の待機が必要です。本ツールキットはそれを 3 つの CLI コマンドに集約します。 再現性：リージョンやアカウントをまたいで同一環境をデプロイ可能 スピード：数時間かかる手動プロセスを 3 コマンドに短縮 監査性：すべての設定判断がバージョン管理されたコードに記録 エラー削減：DNS レコード、VLAN CIDR、bringup 仕様における手動入力ミスを排除 セキュリティ：パスワードを自動生成して AWS Secrets Manager に保存 構築するもの 自動化ツールキットは VCF 9.0 と 9.1 の両方に対応していますが、本ブログでは VCF 9.1 のデプロイに絞って説明します。このウォークスルーを完了すると、以下が構築されます。 Route 53 DNS、BGP 対応 Route Server、必要なネットワーキングを備えた VPC ESXi 9.1 を実行する 3 台のベアメタルホストを持つ Amazon EVS 環境 完全に動作する VCF 9.1 スタック：vCenter、SDDC Manager、NSX Manager、VCF Operations、VCF Cloud Proxy、2 台の NSX Edge NSX オーバーレイセグメントと VPC ルートテーブル間で動的なルート伝播を行う Tier-0 および Tier-1 ゲートウェイ EVS サービス内の Ops Manager Connector コストの考慮事項 本自動化でデプロイされるリソースには、EC2 ベアメタルコンピューティング、Amazon EVS コントロールプレーン、VPC Route Server、Transit Gateway（有効化した場合）、NAT Gateway、EBS ボリューム、Route 53 ホストゾーンなど、相当な月額費用が発生します。デプロイ前に Amazon EVS 料金ページ を確認し、 AWS Pricing Calculator を使って環境全体のコストを把握することをお勧めします。 アーキテクチャの概要 本自動化は、完全な Amazon EVS 環境と VCF 9 を 3 つのステージにわたってデプロイします（1 ステージにつき 1 つのレイヤー）。最初に設定の詳細を入力するだけで、各ステージで生成されたリソース ARN などのメタデータとともに設定値が次のステージへ自動的に引き継がれます。同じ情報を 2 度入力する必要はなく、設定ミスを大幅に削減できます。各ステージの内容は次のとおりです。 AWS 前提条件とアンダーレイ： VPC、サービスアクセスサブネット、Route 53（フォワードおよびリバースゾーン）、2 つの BGP エンドポイントを持つ Route Server、セキュリティグループ、オプションの Transit Gateway、オプションの Windows ジャンプボックス（踏み台サーバー）、オプションのパブリックまたはプライベート HCX 接続などを構築します。 EVS レイヤー： まず、管理、vMotion、vSAN、vTEP、エッジアップリンクなどに使用する 10 個の VLAN サブネットを作成し、EVS 環境を構築します。次に、ESXi 9.1 で起動する 3 台のベアメタルホスト（ユーザーが指定する i4i.metal または i7i.metal-24xl）をプロビジョニングします。最後に、VCF Installer をステージングするデータストアとして EBS ボリュームを作成し、いずれかのホストにマウントします。 VCF のインストールと NSX ルーティング： VCF Installer のデポを設定し、ターゲット VCF バージョンに基づいてバイナリのダウンロードを自動的にトリガーします。次に vCenter、SDDC Manager、NSX Manager、VCF Operations、VCF Cloud Proxy、アクティブ/スタンバイ構成の 2 台の NSX Edge をデプロイします。エッジは BGP で AWS Route Server とピアリングし、NSX セグメントルートを VPC にアドバタイズします。 3 フェーズの自動化アプローチ 本自動化は 3 つの順次フェーズで構成されており、それぞれ独自のツールと目的を持ちます。 フェーズ スタック 内容 1 Terraform VPC、Route 53、Route Server、セキュリティグループ、オプションの Transit Gateway、オプションのジャンプボックス、オプションのパブリック接続など 2 Python (boto3) EVS 環境と VLAN サブネットの作成、ESXi 9.1 を搭載したベアメタルホストのプロビジョニング、インストーラーステージング用 EBS ボリュームの作成とアタッチ 3 Python (VCF SDK + boto3) デポの設定、バイナリのダウンロード、VCF bringup、インストーラーのクリーンアップ、NSX Edge Cluster とルーティングのデプロイ、Ops Manager Connector の作成 フェーズ 1 と 2 は Mac、Linux、または Windows ワークステーションからローカルで実行します。フェーズ 3 は VPC 内のジャンプボックスから実行します（VCF Installer および NSX Manager への直接接続に必要）。唯一の手動ステップは、フェーズ 2 と 3 の間に行う 2 つの簡単な ESXi 設定と VCF Installer OVA のデプロイです。デプロイ全体の所要時間はおよそ 3.5〜6 時間で、大部分はフェーズ 3 の VCF bringup プロセスが占めます。 前提条件 AWS アカウントと権限 以下を満たす AWS アカウント AWS Business Support 以上 EVS 環境あたりのホスト数サービスクォータが 3 以上に設定済み オンデマンドスタンダード（A、C、D、H、I、M、R、T、Z）インスタンスのサービスクォータが 256 以上に設定済み コードリポジトリのフェーズ 1 配下にある iam_policy.json ファイルで定義された権限ポリシーを持つ IAM ユーザーまたはロール ローカルワークステーションのツール Terraform 1.7 以降 Python 3.12 以降 AWS CLI v2 （AWS_PROFILE または環境変数でクレデンシャルを設定済み） pip （Python 依存関係のインストール用） git （コードリポジトリのクローン用） Broadcom デポトークン フェーズ 3 では Broadcom デポから VCF コンポーネントのバイナリをダウンロードします。Broadcom サポートポータルの「My Dashboard」→「Quick Links」→「Generate Download Token」からダウンロードトークンを生成してください。このトークンはフェーズ 3 の実行前に VCF_DEPOT_TOKEN 環境変数として設定します。 VCF Installer OVA Broadcom ダウンロードポータルから VCF 9.1 Installer OVA をダウンロードしてください。このアプライアンスはフェーズ 2 と 3 の間に、いずれかの ESXi ホスト上へ手動でデプロイします。 リポジトリのクローン 自動化リポジトリをクローン してローカルワークステーションに配置してください（このコマンドは Linux と Windows の両方で使用できます）。 git clone https://github.com/aws/solutions-for-amazon-evs.git cd solutions-for-amazon-evs/Deploy/VCF9-Phased-Deployment  フェーズ 0：デプロイ前の入念な計画 自動化を実行する前に、設定ファイルを慎重に計画して入力する必要があります。このステップは非常に重要です。インフラストラクチャをデプロイした後は、環境全体を解体して再構築しなければ変更できない値が多数あるため、時間をかけて正確に設定してください。 自動化では、最初に 1 度だけ入力する 2 つの設定ファイルを使用します。その後のフェーズはこれらのファイルから値を読み取り、次のフェーズへ自動的に引き継ぎます。 terraform.tfvars（フェーズ 1 の入力） このファイルは AWS インフラストラクチャの基盤を定義します。 terraform.tfvars.example を terraform.tfvars にコピーして以下を設定してください（Linux）。 cd Phase_1_Base_Infrastructure cp terraform.tfvars.example terraform.tfvars  Windows の場合： cd Phase_1_Base_Infrastructure copy terraform.tfvars.example terraform.tfvars  以下の値を実際の環境に合わせて更新してください。 region ：デプロイ先の AWS リージョン（例：us-east-2）。Amazon EVS が利用可能なリージョンを指定してください。 availability_zone ：リージョン内の特定の AZ（例：us-east-2a）。すべてのリソースは単一の AZ にデプロイされます。EC2 キャパシティ予約がある場合は、予約済みの AZ と一致させてください。 fqdn ：環境の完全修飾ドメイン名（例：mylab.evs.aws）。Route 53 フォワードホストゾーンとなり、すべての DNS レコードに使用されます。慎重に選択してください。 cidr_prefix ：VPC CIDR の最初の 2 オクテット（例：”10.0.”）。自動化はこのプレフィックスからすべての VLAN サブネット CIDR を導出します。Transit Gateway または Direct Connect で接続する予定のネットワークと重複しないようにしてください。 DNS ホスト名 ：各 VCF アプライアンスと ESXi ホストの短い DNS 名（esxi01_name から vcf_fleet_name まで）。 create_tgw ：他の VPC やオンプレミスネットワークへの Transit Gateway 接続が必要な場合は true に設定してください。 create_jumpbox ：Windows ジャンプホストを作成する場合は true に設定してください。VPC 内から実行する必要があるフェーズ 3 に必須です。このフラグを有効にすることをお勧めします。 enable_public_hcx ：HCX インターネット接続用のパブリック IP スペースを割り当てる場合は true に設定してください。false の場合、HCX はプライベート VLAN を使用します（Direct Connect または Transit Gateway 経由の HCX に適しています）。 VPC CIDR の分割方法 cidr_prefix で最初の 2 オクテットのみ指定します（例：”10.0.”）。自動化は /16 の VPC を作成し、ハードコードされた第 3 オクテットを使って /24 の VLAN サブネットに分割します。 <prefix>0.0/24 — サービスアクセスサブネット <prefix>10.0/24 — ホスト vmkernel 管理（vmkManagement） <prefix>20.0/24 — vMotion <prefix>30.0/24 — vSAN <prefix>40.0/24 — Host TEP (vTep) <prefix>50.0/24 — Edge TEP (edgeVTep) <prefix>60.0/24 — VM 管理（vmManagement） <prefix>70.0/24 — HCX <prefix>80.0/24 — NSX アップリンク（nsxUplink） <prefix>90.0/24 — 拡張 VLAN 1 <prefix>100.0/24 — 拡張 VLAN 2 config.json でこれらの VLAN サブネット CIDR を変更する場合は、NSX Edge IP、Route 53 インバウンドリゾルバーエンドポイント（<prefix>0.100 および <prefix>0.101）、BGP アップリンクアドレスなど、サブネット内に設定されるハードコードされた IP アドレスと競合しないよう注意してください。 config.json（フェーズ 2 の入力） このファイルは EVS 環境と VCF デプロイパラメーターを定義します。 config.example.json を config.json にコピーして以下を設定してください（Linux）。 cd Phase_2_evs_env/python cp config.example.json config.json Windows の場合： cd Phase_2_evs_env/python copy config.example.json config.json  以下の値を実際の環境に合わせて更新してください。 environmentName ：EVS 環境のわかりやすい名前。AWS コンソールに表示され、リソースのタグ付けに使用されます。 vcfInstallerProductVersion ：VCF Installer の製品バージョン番号のみ（ビルド文字列は含めない）。例：”9.1.0.0″。正確な値は OVA ファイル名またはインストーラー UI の設定ページで確認してください。 simpleDeployment ：単一ラック・シンプルデプロイ（最小 3 ホスト）の場合は true、単一ラック・HA デプロイ（最小 4 ホスト）の場合は false を設定してください。この設定は、デプロイされる NSX Manager と VCF Operations ノードの数に影響します。詳細は Single-Rack vSphere クラスターモデルのドキュメント を参照してください。 vcfSizing ：vCenter（vmSize、storageSize）、NSX（nsxSize）、VCF Operations（operationsApplianceSize、operationsCollectorApplianceSize）のアプライアンスサイジング。ほとんどのデプロイでは “medium” のデフォルト値が適切です。 ヒント： FQDN、CIDR プレフィックス、ホスト名の選択は事前に十分確認してください。フェーズ 1 のデプロイ後にも検証することをお勧めします。フェーズ 1 の削除と再デプロイは数分で完了するため、この時点であれば変更は容易です。フェーズ 2 で FQDN や CIDR などの値を組み込んだ EVS 環境がデプロイされると、変更には最初から再構築が必要になります。 フェーズ 1：基盤 AWS インフラストラクチャ（Terraform） フェーズ 1 で作成されるもの フェーズ 1 は、EVS が必要とする AWS ネットワークおよびサポートリソースをすべてプロビジョニングします。 terraform apply が完了すると（通常 3〜5 分）、以下が構成されます。 VCF アプライアンスと ESXi ホスト用の Route 53 プライベートホストゾーン フォワードホストゾーン（A レコード） リバースホストゾーン（PTR レコード） 2 つの IP を持つインバウンドリゾルバーエンドポイント Amazon VPC 専用サービスアクセスルートテーブルに関連付けられたプライベートサービスアクセスサブネット 専用パブリックアクセスルートテーブルに関連付けられたパブリックアクセスサブネット Elastic IP を持つ NAT Gateway Internet Gateway FQDN、Route 53 インバウンドリゾルバー IP、NTP（169.254.169.123：AWS NTP サーバー）を設定した DHCP オプションセット VPC CIDR からの受信を許可する専用 EVS サービスアクセスセキュリティグループ VPC Route Server VPC に関連付け済み それぞれピア IP、ピア ASN（65000）、BGP キープアライブを設定した 2 つの Route Server エンドポイント サービスアクセスルートテーブルとパブリックアクセスルートテーブルへの 2 つの Route Server 伝播 EVS ホスト用の EC2 キーペア （オプション）アンダーレイ VPC への VPC アタッチメントを持つ Transit Gateway （オプション）VPC 内の Windows ジャンプホスト ジャンプホスト用の VPC パブリックサブネット Internet Gateway へのルートを持つジャンプホスト用専用ルートテーブル 専用ルートテーブルへの Route Server 伝播 VPC CIDR と EVS サービスアクセスセキュリティグループからのすべてのトラフィックを許可するジャンプホスト用専用セキュリティグループ 50 GB 暗号化 gp3 ルートボリュームとパブリック IPv4 アドレスを持つ、Windows Server 2025 を実行する t3.2xlarge EC2 インスタンス ジャンプホスト用専用 EC2 キーペア 注：このキーペアは “Jumpbox-KeyPair” という名前です。同名のキーペアが既に存在する場合、このコードは失敗します。その場合はコード内でキーペア名を変更してください。 （オプション）パブリック HCX 接続 IPv4 IPAM プール 連続したパブリック IP スペースの /28 VPC CIDR へのパブリック /28 の追加 デプロイの実行（Linux）： export AWS_PROFILE=your-profile-name    terraform init  terraform plan  terraform apply  Windows の場合： $env:AWS_PROFILE = "your-profile-name" terraform init terraform plan terraform apply Terraform は VPC ID、サブネット ID、Route Server エンドポイント IP、セキュリティグループ ID などの値を出力します。フェーズ 2 はこれらを terraform.tfstate ファイルから直接読み取ります。フェーズ 1 のデプロイはおよそ 5〜10 分で完了します。 インフラストラクチャの検証 フェーズ 1 の完了後、AWS コンソールで以下を確認してください。 期待される CIDR で VPC が作成されていること Route 53 ホストゾーンに、すべての VCF アプライアンスと ESXi ホストの A レコードおよび PTR レコードが含まれていること Route Server の 2 つのエンドポイントが “Available” 状態であること ジャンプボックスを使用する場合：インスタンスが実行中でパブリック IP を持つこと ジャンプボックスをデプロイした場合は、以下の手順で RDP アクセスを確立してください。 Jumpbox-SG セキュリティグループに、自分の IP アドレスからの RDP（TCP 3389）を許可するインバウンドルールを追加する EC2 キーペアを取得して Windows Administrator パスワードを復号する。PEM ファイルをダウンロードする（Linux）： KEY_PAIR_ID=$(terraform output -raw jumpbox_key_pair_id) aws ssm get-parameter --name /ec2/keypair/$KEY_PAIR_ID --with-decryption \ --region us-east-2 --query 'Parameter.Value' --output text > jumpbox.pem chmod 400 jumpbox.pem Windows の場合： $KEY_PAIR_ID = terraform output -raw jumpbox_key_pair_id aws ssm get-parameter --name "/ec2/keypair/$KEY_PAIR_ID" --with-decryption ` --region us-east-2 --query 'Parameter.Value' --output text | Out-File -Encoding ascii jumpbox.pem icacls jumpbox.pem /inheritance:r /grant:r "$($env:USERNAME):(R)" この PEM ファイルを EC2 コンソール（Connect > Get Windows Password）で使用して Administrator パスワードを復号してください。 最後に、VCF Installer OVA をジャンプホストにダウンロードまたはコピーしてください。フェーズ 2 と 3 の間の手動作業ステップで必要になります。 フェーズ 2：EVS 環境のデプロイ（Python） フェーズ 2 の処理内容 フェーズ 2 は Python CLI で、AWS API 経由で EVS デプロイを調整し、SDDC bringup 仕様と NSX デプロイ仕様を構築します。単一の CLI コマンドで、以下の 6 つのサブステップを順番に実行します。 pre-evs-sync-config ：フェーズ 1 の Terraform ステートを読み取り、VCF bringup 仕様とエッジクラスター仕様の初期版を生成 create-environment-and-hosts ：AWS API を呼び出して EVS 環境を作成し、完了後にベアメタルホストをプロビジョニング（15〜20 分） すべてのホストが CREATED ステータスになるまで待機（20〜40 分） post-evs-sync-config ：環境とホスト ID から派生した名前で SDDC 仕様を確定し、対応する VCF パスワードを Secrets Manager にプロビジョニング associate-vlan-subnets ：10 個の EVS VLAN サブネットをすべてサービスアクセスルートテーブルに関連付け create-and-attach-ebs ：256 GB の gp3 EBS ボリュームを作成し、VCF Installer VMFS 用として 1 台のホストにアタッチ deploy-environment の実行 Python 環境をセットアップし、単一コマンドでフェーズ 2 のパイプライン全体を実行します（Linux）。 python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python -m src.main deploy-environment \ --profile your-aws-profile \ --config config.json \ --tfstate ../../Phase_1_Base_Infrastructure/terraform.tfstate \ --instance-type <INSTANCE_TYPE> # 'i4i.metal' or 'i7i.metal-24xl' Windows の場合： py -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements.txt python -m src.main deploy-environment ` --profile your-aws-profile ` --config config.json ` --tfstate ..\..\Phase_1_Base_Infrastructure\terraform.tfstate ` --instance-type <INSTANCE_TYPE> # 'i4i.metal' or 'i7i.metal-24xl' このコマンドは 6 つのサブステップを自動的に連結して実行します。合計所要時間はおよそ 30〜45 分で、大部分はベアメタルホストがプロビジョニングされて CREATED ステータスになるまでの待機時間が占めます。デバッグ用に各サブステップを個別に実行することも可能ですが、単一コマンドによるアプローチを 強く推奨 します。 Secrets Manager によるパスワード管理 フェーズ 2 の構築中、post-evs-sync-config サブステップがすべての VCF アプライアンス用の複雑なパスワードを自動生成し、AWS Secrets Manager に保存します。命名パターンは evs-<environment-id>_<role> です。 VCF のアカウントには vcenterRoot 、 vcenterSso 、 nsxRoot 、 nsxAdmin 、 nsxAudit 、 sddcManagerRoot 、 sddcManagerSsh 、 sddcManagerLocal 、 operationsAdmin 、 operationsMaster 、 operationsCollector 、 edgeAppliance が含まれます。 bringup 仕様はプレースホルダートークンを通じてこれらのパスワードを参照します。フェーズ 3 は実行時に Secrets Manager からパスワードを解決するため、平文パスワードがディスクに書き込まれることはありません。 手動による事前作業：ESXi 設定とインストーラー OVA フェーズ 2 と 3 の間に、いくつかの簡単な手順を手動で実施する必要があります。デプロイ全体を通じて唯一の非自動化部分であり、所要時間はおよそ 30 分です。以下の手順はすべて、フェーズ 2 で EBS ボリュームを受け取った 1 台の ESXi ホスト上で実施します。 EBS ボリュームへの VMFS データストアの作成 フェーズ 2 でいずれかの ESXi ホストに 256 GB の EBS ボリュームをアタッチしました。フェーズ 2 のコンソール出力で、どのホストがボリュームを受け取ったか確認できます。VCF Installer アプライアンスをホストするために、VMFS データストアとしてフォーマットする必要があります。 ESXi ホスト UI（ https://<esxi-host-ip> ）に root としてログインします。root パスワードは AWS Secrets Manager から取得してください（シークレット名は evs-<environment-id>_<role> のパターンです）。 Storage に移動し、New Datastore を選択する NVMe デバイス（256 GB EBS ボリューム）を選択して VMFS データストアを作成する VM Network ポートグループへの VLAN タグ付け EBS ボリュームを持つ ESXi ホストで、デフォルトの “VM Network” ポートグループに VLAN ID 20 をタグ付けし、VCF Installer が VM 管理ネットワークで通信できるようにします。 ESXi UI で Networking に移動し、Port groups を選択する “VM Network” ポートグループを編集する VLAN ID を 20 に設定する VCF Installer OVA のデプロイ VMFS データストアを持つホスト上に VCF Installer アプライアンスをデプロイします。 ESXi UI で Virtual Machines > Create/Register VM > Deploy OVF template に移動する VCF 9.1 Installer OVA ファイルをアップロードする 上記で作成した 256 GB VMFS データストアに配置する “VM Network” ポートグループにアタッチする 管理 IP を DNS 設定の SDDC Manager IP アドレスに設定する ネットマスクを 255.255.255.0 に設定する admin@local パスワードを設定する。手動で選択する唯一のパスワードです。独自のパスワードを作成するか、Secrets Manager に生成済みのパスワードを使用することもできます。フェーズ 3 で必要になるためパスワードを控えておいてください。 アプライアンスの電源を入れ、起動を待つ（ https://<sddcm_name>.<your-fqdn> でアクセスを確認） フェーズ 3：VCF Bringup と NSX Edge Cluster（Python） フェーズ 3 の処理内容 フェーズ 3 は EVS 環境をホストする VPC 内のジャンプホストから実行する必要があります。公式 VMware VCF Python SDK（vcf-installer、vcf-nsx）と vCenter 操作用 pyvmomi、および対応する AWS 操作用 boto3 ライブラリを使用します。単一の CLI コマンドで、以下の 7 つのサブステップを順番に実行します。 Secrets Manager 事前確認 ：開始前に必要なすべての Secrets Manager シークレットが存在することを確認。不足している場合、不足している VCF アカウントを明示したエラーでパイプラインを即座に終了。 prepare-depot ：Broadcom ダウンロードトークンをインストーラーに設定し、デポカタログを同期して必要なすべてのコンポーネントバイナリをダウンロード（約 30〜60 分） start-bringup --wait ：bringup 仕様を VCF Installer に送信し、ワークフローが完了するまでポーリング。vCenter、NSX Manager、SDDC Manager、VCF Operations をデプロイ（約 2〜4 時間） remove-installer-datastore ：手動で作成した 256 GB VMFS データストア上の VM を vSAN にストレージ vMotion し、データストアをアンマウント（約 5〜10 分） destroy-ebs-volume ：AWS 側からアンマウント済み VMFS データストアをホストしていた EBS ボリュームをデタッチして削除（約 30 秒） deploy-edge-cluster ：2 台の NSX Edge アプライアンスをデプロイし、エッジクラスターを作成し、Tier-0/Tier-1 ルーティングを設定し、AWS Route Server との BGP ピアリングを確立（約 30〜50 分） create-connector ：VCF Operations Manager コネクターを CreateEnvironmentConnector 経由で EVS に登録。 ACTIVE になるまでポーリング（約 2〜5 分） 以下のサブセクションでは、フェーズ 3 の内部処理をより詳細に段階的に説明します。 deploy-vcf-and-edge の実行 と題したセクションに、フェーズ 3 のワークフロー全体を実行する単一コマンドが記載されています。 デポとバンドルの管理 prepare-depot サブステップは、VCF Installer UI にログインして Broadcom デポを設定する手動プロセスを自動化します。具体的には以下を実行します。 VCF SDK 経由でデポトークンをインストーラーに保存 メタデータ同期をトリガーしてバンドルカタログを更新 ターゲットバージョンに一致するすべての INSTALL タイプバンドルを特定 必要なすべてのコンポーネントバイナリ（vCenter、NSX、SDDC Manager、VCF Operations、ESXi）をダウンロード すべてのダウンロードが完了するまでポーリングし、その後 bringup に進む ヒント ：デポの問題をデバッグする必要がある場合、list-bundles、get-depot-settings、sync-depot などの個別アクションをスタンドアロン CLI コマンドとして実行できます。 VCF bringup ワークフロー start-bringup アクションは型付きの SddcSpec を VCF Installer に送信し、ワークフローを監視します。bringup 中にインストーラーは以下を実行します。 ESXi ホストを VCF 管理ドメインにコミッション vCenter Server をデプロイして設定 NSX Manager をデプロイして仮想 IP アドレスでクラスター化 SDDC Manager をデプロイ VCF Operations をデプロイ すべてのホストで vSAN ESA を設定 必要なすべてのポートグループを持つ分散仮想スイッチを作成 ヒント： CLI は 10 分ごとにインストーラーをポーリングして進捗を報告します。bringup が失敗した場合は、 https://<sddcm_name>.<your-fqdn> のインストーラー UI でタスクごとの詳細なエラー情報を確認してください。 インストーラーのクリーンアップ bringup が正常に完了した後、自動化は 2 つのクリーンアップステップを実行します。 remove-installer-datastore ：ローカル VMFS データストアに配置された VM を vSAN にストレージ vMotion し、データストアをホストからアンマウントします。これにより EBS ボリュームが削除可能になります。 destroy-ebs-volume ：EC2 インスタンスから EBS ボリュームをデタッチして削除します。ボリュームは ManagedBy タグと EnvironmentId タグで識別され、他のボリュームを誤って削除しないよう保護されています。 NSX Edge Cluster のデプロイ 次のサブステップは NSX Manager と vCenter API を直接使用して NSX Edge Cluster をデプロイします。7 つのステージで実行されます。 prep-edge-cluster ：DVS TRUNK ポートグループ、IP プール、アップリンクプロファイル、VLAN トランスポートゾーンを作成 deploy-edge-nodes ：2 台のラージフォームファクター エッジトランスポートノードを作成（OVA デプロイをトリガー） create-edge-cluster ：両方のトランスポートノードをグループ化するエッジクラスターを作成 create-tier0 ：ロケールサービスと BGP を有効にした Tier-0 ゲートウェイを作成 create-tier1 ：Tier-0 とエッジクラスターにアタッチした Tier-1 ゲートウェイを作成 configure-routing ：アップリンクセグメント、インターフェース、BGP ネイバー、プレフィックスリスト、スタティックルート、再配布を設定 create-anti-affinity ：エッジ VM 用の vCenter DRS アンチアフィニティルールを作成 各エッジアプライアンスは ASN 65000（NSX 側）と 65022（AWS 側）を使って 1 つの AWS Route Server エンドポイントと BGP ピアリングします。ピアリングが確立されると、NSX オーバーレイセグメントが VPC ルートテーブルにルートとして自動的にアドバタイズされます。 Ops Manager Connector 最後のサブステップは VCF Operations Manager コネクターを Amazon EVS に登録します。これは仮想マシンの Windows Server ライセンスエンタイトルメントの作成など、後続のアクションに使用されます。 環境変数の設定 フェーズ 3 では Secrets Manager に保存されていない 2 つのシークレットが必要です。手動手順で設定した VCF_INSTALLER_PASSWORD と、Broadcom ポータルから取得した VCF_DEPOT_TOKEN です。以下のコマンドで環境変数として設定します（Linux）。 # The admin@local password you set when deploying the installer OVA: read -rs VCF_INSTALLER_PASSWORD ; export VCF_INSTALLER_PASSWORD # Your Broadcom depot download token: read -rs VCF_DEPOT_TOKEN ; export VCF_DEPOT_TOKEN Windows の場合： # The admin@local password you set when deploying the installer OVA: $env:VCF_INSTALLER_PASSWORD = Read-Host -MaskInput "VCF Installer Password" # Your Broadcom depot download token: $env:VCF_DEPOT_TOKEN = Read-Host -MaskInput "VCF Depot Token" 他のパスワード（vCenter、NSX、SDDC Manager など）はすべて Secrets Manager から自動的に解決されます。 deploy-vcf-and-edge の実行 Python 環境を作成し、単一の CLI コマンドでフェーズ 3 のパイプライン全体をエンドツーエンドで実行します（Linux）。 cd Phase_3_VCF9/python python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python -m src.main deploy-vcf-and-edge \ --installer-host sddcm.<your-fqdn> \ --target-version 9.1.0 \ --nsx-manager-host nsx.<your-fqdn> \ --vcenter-host vc.<your-fqdn> \ --aws-profile your-aws-profile Windows の場合： cd Phase_3_VCF9\python python -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements.txt python -m src.main deploy-vcf-and-edge ` --installer-host sddcm.<your-fqdn> ` --target-version 9.1.0 ` --nsx-manager-host nsx.<your-fqdn> ` --vcenter-host vc.<your-fqdn> ` --aws-profile your-aws-profile デバッグ用に各サブステップを個別に実行することも可能ですが、単一コマンドによるアプローチを 強く推奨 します。 検証と次のステップ deploy-vcf-and-edge が正常に返ったら、以下でエンドツーエンドの接続性を確認してください。 Route Server BGP ピアの確認 AWS コンソールで VPC > Route Servers > Peers に移動してください。両方の BGP ピアの BGP ステータスが “Up” になっているはずです。”学習済みルート” タブには NSX から発信された CIDR が表示されます（後で作成したセグメントも自動的にここに表示されます）。 テスト用 NSX セグメントの作成 NSX Manager（ https://nsx.<your-fqdn> ）にログインし、Tier-1 ゲートウェイにアタッチした新しいオーバーレイセグメントを作成します。 Networking > Segments > Add Segment に移動する セグメント名を test-segment とする 作成した Tier-1 ゲートウェイにセグメントをアタッチする サブネットを設定する（例：ゲートウェイ 172.16.1.1 の 172.16.1.0/24） このセグメントにテスト VM をデプロイし、IP アドレスを受け取ることを確認する オーバーレイからアンダーレイへの接続確認 NSX セグメント上のテスト VM から以下を実行します。 パブリックサブネット内のジャンプボックスに Ping する（デプロイ済みの場合） サービスアクセスサブネット内の EC2 インスタンスに Ping する セグメント CIDR（172.16.1.0/24）が VPC ルートテーブルに学習済みルートとして表示されることを確認する 3 つの確認がすべて成功すれば、NSX オーバーレイと AWS アンダーレイ間の動的なルート伝播が確立された、完全に動作する EVS 環境の構築完了です。 次のステップ： VMware HCX やその他の移行ツールを使用してオンプレミスからワークロードを移行する データセンターへのハイブリッド接続のために AWS Transit Gateway を設定する（フェーズ 1 でオプションとして作成しなかった場合） 補足ストレージとして Amazon FSx for NetApp ONTAP をセットアップする 運用監視のために AWS Systems Manager を統合する SDDC Manager 経由で追加のワークロードドメインをデプロイする トラブルシューティング よくある障害パターンと解決策を以下にまとめます。 フェーズ 1 および 2：AWS リソースエラー 対象リソースの AWS コンソールを確認してください。Terraform または boto3 のエラーテキストは通常、正しくプロビジョニングされなかった特定のリソース（AZ の誤り、サブネットの欠落、API コールのスロットリング）を指しています。 サービス制限を確認してください：EVS サービスクォータ、Dedicated Host の割り当て、VPC Route Server クォータ、EBS ボリューム制限。 ホストの実現がタイムアウトした場合（90 分超）、コンソールで EVS 環境のステータスを確認してください。FAILED 状態はキャパシティまたは設定の問題を示します。 フェーズ 3：デポの同期問題 Broadcom デポトークンが有効で有効期限が切れていないことを確認してください インストーラーアプライアンスが depot.broadcom.com へのアウトバウンドインターネットアクセス（ポート 443）を持つことを確認してください ダウンロードが止まった場合、自動化は指数バックオフで再試行し、5 回失敗後にエラーを報告します。その場合は download-all-product-binaries --wait で手動再試行できます フェーズ 3：Bringup の失敗 VCF Installer UI（ https://<sddcm_name>.<your-fqdn> ）はタスクごとの進捗と詳細なエラーメッセージを提供しており、API エラー本文よりも参考になります。 スタックトレースについてはインストーラーアプライアンスの /var/log/vmware/vcf/domainmanager/domainmanager.log を確認してください。 bringup が “VMwareProductVersion can not be null or empty” で失敗した場合、デポに必要なバイナリがキャッシュされていません。 prepare-depot を再実行して再試行してください。 フェーズ 3：Edge Cluster のデプロイ vSAN データストアに十分な空き容量がない場合、エッジノードのデプロイが失敗することがあります（各エッジ VM には約 200 GB が必要） BGP ピアリングの問題：エッジクラスター仕様の Route Server エンドポイント IP がフェーズ 1 の Terraform 出力と一致することを確認してください configure-routing が失敗した場合、クラスターが作成される前に両方のエッジノードが Success 状態に達していることを確認してください ヒント ：自動化の各アクションはべき等です。ステップが失敗した場合は、根本的な問題を修正して同じコマンドを安全に再実行できます。副作用は発生しません。 クリーンアップ 構築した環境を解体する場合は、以下の順序で実施してください。 EVS 内の仮想マシンを保持したい場合は、まず別の場所に移行してください。 AWS コンソールから EVS ホストを 1 台ずつ削除してください。 AWS コンソールから EVS 環境を削除してください。 フェーズ 1 を実行した元のワークステーションから Phase_1_Base_Infrastructure ディレクトリに移動し、 terraform destroy を実行してください。Terraform は既存の状態ファイルを使用してすべてのフェーズ 1 リソースを特定して削除します。 まとめ 本ウォークスルーでは、3 フェーズの自動化ツールキットを使って VMware Cloud Foundation 9.1 を Amazon EVS にデプロイしました。空の AWS アカウントから出発し、Terraform で前提条件となる AWS インフラストラクチャをすべてプロビジョニングし、AWS API 経由の Python CLI で EVS 環境とベアメタルホストをデプロイし、公式 VCF Python SDK を使って NSX Edge Cluster ルーティングを含む完全な VCF スタックを立ち上げました。 terraform apply から BGP ピアリングの確認まで、デプロイ全体でおよそ 3.5〜6 時間かかります。自動化により、作業は 3 つの CLI コマンドと ESXi 設定・OVA デプロイに必要な約 30 分の手作業のみに削減されます。 このアプローチの主な利点： Infrastructure as Code：すべてのリソースが Terraform または Python 自動化で定義されています デフォルトセキュア：すべての VCF パスワードが厳格な複雑性要件に従って生成され、AWS Secrets Manager に保存されます 安全な再実行：フェーズ 1 と 3 は完全にべき等であり、デバッグや復旧のためにどのステップも副作用なく安全に再実行できます SDK 駆動：フェーズ 3 は公式 VMware VCF Python SDK を使用し、手動による REST ペイロードの構築を排除します モジュラー設計：1 つのコマンドでパイプライン全体を実行するか、デバッグや部分的な再実行のために個別ステップを実行できます 開発環境のセットアップ、本番環境のデプロイ、顧客デモ用の再現可能なラボなど、あらゆるユースケースに対応できる堅牢な基盤として、バージョン管理・カスタマイズ・拡張が可能です。 著者について David Piet Amazon Web Services (AWS) のプリンシパルソリューションアーキテクトとして、VMware ベースのワークロードを持つエンタープライズのお客様が AWS へ移行し、モダナイズするための支援を担っています。2018 年にパートナーソリューションアーキテクトとして AWS に入社し、VMware Cloud on AWS を専門としてきました。以来、AWS 最大規模のエンタープライズ顧客を数多くサポートし、VMware ベースのワークロードのクラウド移行と最適化戦略を牽引してきました。長年にわたり、AWS での VMware ビジネスの成長とともに担当範囲を広げ、現在もお客様のモダナイゼーションジャーニーの支援に深く関わっています。ノースウェスタン大学で博士号を取得しており、応用数学とエンジニアリングを専門としています。AWS 入社前はシリコンバレーのストレージスタートアップでソフトウェアデベロッパーとして勤務していました。 翻訳はパートナーソリューションアーキテクト 豊田が担当しました。原文は こちら です。

はじめに こんにちは、Insight Edge の日下です。 ここ最近のコーディングAIエージェントの進化は目覚ましく、以下のような光景が当たり前になってきました。 プロダクトオーナーやUXデザイナがAIツールでプロトタイプを作る 議事録・仕様書・設計メモといったドキュメント系の成果物もAIで作成しgitで管理する 特にバイブコーディングの広がりで、エンジニア以外もソースコードの形で成果物を作ることが増えました。弊社では AIが文脈を理解しやすいように、プロダクトのソースコードだけでなくデザイン成果物や設計ドキュメント、意思決定の経緯などもGitやGitHubに集約しています 。こうしてソースコードとドキュメントの両面から、 Gitリポジトリを触るエンジニア以外のメンバー が増えてきています。 このとき、従来からGit/GitHubを使うエンジニア側と、新たに使い始めた側のそれぞれに悩みが生まれます。 エンジニア側 — 開発フローの説明や救援作業（作業支援、誤コミットの修正）など、エンジニア以外のメンバーが慣れるまでサポート負荷が高くなる 開発に参加するメンバー側 — Git/GitHubの作法や開発フローを学ぶ負担と、それを意識することによるアイデア具現化スピードの鈍化 「AIに任せればベストプラクティスが守られるのでは？」と思いきや、そうでもありません。最近のAIモデルはGitやGitHubの良い作法を知っていますし、インターネットを探せば素晴らしいスキルも多々あります。しかし、開発するプロダクトの特徴やフェーズ、チームの大きさなどに応じて、現場に適した開発フローは様々であり、そこに開発チームの工夫が表れます。だからこそ、 自分のチームに適した開発手順を言語化してスキルに固める 必要がありました。 本記事では、エンジニア以外のメンバーも含む開発チームで、バイブコーディングの速さや気軽さも尊重しつつ、GitやGitHubをお行儀よく活用した開発フローを実現するために私が作り育てたClaudeスキルを題材に、その設計思想と中身、実際の使い勝手を ニールセンのユーザビリティ10原則 に照らし合わせて紹介します。 ※本記事は Claude Code の Skill 機能 を前提としています。また、 /d の動作には git コマンドと GitHub CLI （ gh コマンド）がセットアップ済みであることが必要です。 目次 はじめに 設計の3本柱 /d スキルの構造 動かしてみる：2つの典型シナリオ スキル改善の経緯と考え方 おわりに 設計の3本柱 /d の d は develop からとっています。 このスキルの設計には3つの軸があります。共通するのは、 作業者が意識して開発フローに合わせるのではなく、スキルを使っているだけで自然にルールを守れる という発想です。 A. バイブコーディングの手を止めない アイデアを高速に具現化する人の手を、複雑な開発プロセスで遅くしない。 お行儀のためのチェックリストや規約を増やすほど、利用者は「考える前に手順を思い出す」モードに入ります。これは思いつきを高速に形にするUXデザイナやプロダクトオーナーには致命的です。 /d スキルは 思考のリズムを止めない ことを最優先にします。 具体的には、手順を覚えてもらうのではなく スキル側がすべて代行する 設計にしました。たとえば、利用者が /d issue 42 と打つことでIssueに着手するときの定型作業を実行し、作業ブランチ作成・push・方針コメント投稿まで自動で走ります。 B. 使いながらGit/GitHubの作法に慣れる 細かい作法を習ってから使うのではなく、使いながら徐々に作法を体得する。 ブランチ・コミット・PR・rebase…とGitの概念を最初に全部説明されると、それだけで利用者は挫折します。一方で「教えなくていい」とすると、利用者はずっと作法を知らないまま、エンジニアの救援が必要な状態が続きます。 /d スキルは 「必要最低限のコマンドを使うだけで、結果としてお行儀よく作業できていた」 状態を作りつつ、 裏で何が起こったかは可視化する 設計にしました。 /d issue 実行時に「ブランチを作りました」「PRを作成しました」とログが出るので、利用者は使い続けるうちに「これはブランチを切っていたのか」「これがDraft PRか」と自然に理解していきます。また、issueやcommitなど重要な用語はGit/GitHubのエコシステムに合わせることで、エンジニアと同じ言語で開発に参加できるようにしています。 C. 覚えなければならない知識を減らす 使う側が頭の中に抱える「知識量」をできる限り減らす。 利用者の負担は 「次に何のコマンドを打つか」「どのスキルを呼ぶか」を毎回思い出すこと にあります。これを減らすために2つの仕掛けを入れました。 個別スキルではなくサブコマンド方式 — /d todo /d issue /d commit …といった操作を /d 1つのスキルに統合することで、利用者は最低限 /d だけ覚えればよく、 /d 42番のIssueに着手 のように自然言語で意図を伝えるだけでも適切なサブコマンドが実行されます 次のアクションは選択肢で提示 — スキル実行の終わりには必ず次の候補を出すことで、利用者は「次に何をすればよかったっけ」と考えずに済みます（後述する「再生より再認」） 結果として、利用者が頭に抱える「Git作法 + コマンド体系 + チーム運用ルール」の知識セットが大幅に圧縮されます。 覚えるべきは /d という入口だけ という状態が、参加ハードルを最小化します。 /d スキルの構造 スキル本体は ~/.claude/skills/d/SKILL.md 1ファイルです。フロントマター + サブコマンドごとの手順記述で構成されます。全文は以下に折りたたんで載せておきます。 SKILL.md 全文（クリックで展開） --- name: d description: GitHub Issue・Pull Request・ブランチ操作・コミット等の作法を定義した開発ワークフロースキル argument-hint: " < todo |new|issue|commit|pr|review|improve|help> [args...]" allowed-tools: Bash, Agent, Read --- GitHub を起点とした開発ワークフローをサブコマンドを指定して実行する。引数なしで ` /d ` と実行された場合は ` /d help ` として動作した上で、次の行動を提案する。 サブコマンドが指定されずに文が続く場合（例: ` /d 42番のIssueに着手して ` ）は、テキスト内容から利用者の意図を解釈し、適切なサブコマンドにマッピングして実行する。利用者は厳密なサブコマンド名を覚えていなくてもよい。 ## 出力ルール ### yes/no 質問 AIによる「〜してよいですか？」「〜しますか？」のような closed questionや許可確認の末尾には ` (y/n) ` を付け、ユーザの回答負荷を軽減する。「他に修正はありますか？」のような実質的Open Questionには付けない。 ### 表・箇条書きへの識別子付与 表・箇条書き・選択肢など、複数項目が並ぶ出力には必ず連番や記号の識別子を振る。Issue番号やPR番号など既存の識別子がある場合はそれを使い、無い場合は左端に ` No ` 列を追加する。これにより、後の会話でユーザが番号で行を指定できるようにする。 ### 次のアクションの提示 サブコマンドの終わりには、可能な限り次のアクションの候補を選択肢として提示する。利用者に「次に何をすればよいか」を思い出させるのではなく、提示された選択肢から選ばせる（再生より再認）。 ## 不満・改善提案の案内 利用者が ` /d ` スキルの挙動に不満を表明した場合: ` /d improve <内容> ` でスキル改善Issueを起票する。 ## 共通ルール ### 並列実行 依存関係のない複数のコマンド・API呼び出しは常に並列実行する。逐次実行しない。独立したコマンドを見つけたら積極的に並列化する。 ### ブランチ切り替え前の確認 ` git checkout ` の前に ` git status --porcelain ` で未コミット変更を確認する。変更がある場合は選択肢を提示: 1. **コミットして続行** 2. **worktree で並列作業** — ` git worktree add ../<リポ名>-<新ブランチ> -b <新ブランチ> origin/main ` → 別セッションを案内 3. **中断** ### main 最新取り込み 作業ブランチで ` /d issue ` （既存ブランチ checkout 時）または ` /d commit ` （push 前）に実行する。originのmainブランチに対する遅れを確認し、遅れがあれば ` git merge origin/main ` を提案する。 ### ブランチ命名規則 ` CLAUDE.md ` に命名規則の定義があればそれに従う。なければデフォルトとして ` <prefix>/<issue番号>-<英語kebab-case 5語以内> ` を使用する。prefix はIssueのラベル・内容から判断: - ` feat/ ` — 新機能 - ` fix/ ` — バグ修正 - ` nf/ ` — 非機能（インフラ等） - ` doc/ ` — ドキュメント - ` process/ ` — 開発プロセス関連（CI、Claudeスキル等） - ` misc/ ` — その他 Issue 番号がない場合は ` <prefix>/<英語kebab-case 5語以内> ` とする。 ### PR マージ確認 PR が Ready かつ最新コミットに対するレビューでマージ可能と判定されている場合、 ` gh pr merge <PR番号> --merge --delete-branch ` を提案する。適用タイミング: ` /d commit ` で Ready PR 作成後、 ` /d review ` で Ready 化後、 ` /d pr ` で Ready 化後。 ### レビュー実行 レビューは **Claude のレビュー用サブエージェント** で実行する。実装したコンテキストとは別のサブエージェントで実行することで、客観的な指摘を得る。 他人の PR をレビューする場合は先に対象ブランチを取得する。 チェックアウト前に元ブランチ名を退避し、ダーティーツリーでないことを確認する: ```bash ORIG_BRANCH=$(git branch --show-current) git status --porcelain # 出力ありなら未コミット変更あり ``` 未コミット変更がある場合は「ブランチ切り替え前の確認」を適用する。クリーンな状態を確認したら既存ローカルブランチを破壊しない方法で取得する: #### レビュー手順 1. ` COMMIT_SHA=$(git rev-parse HEAD) ` で SHA を取得。 ` git fetch origin main ` 後、 ` git diff origin/main...HEAD ` + ` git log origin/main..HEAD --oneline ` を取得。 ` OWNER_REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) ` で owner/repo も取得 2. Agent ツールでレビュー用サブエージェントを起動する（ ` run_in_background: true ` ）。プロジェクトの設計基準やレビューガイドライン（ ` CLAUDE.md ` 、レビュー用エージェント定義、 ` docs/ ` 配下のガイドライン等があれば参照）に従ってレビューさせる。プロンプトに ` diff ` , ` commits ` , ` commit_sha ` , ` owner_repo ` , ` pr_number ` , ` pr_author ` , ` is_own_pr ` , ` is_draft ` , ` post_to_pr=false ` , ` defer_ready=true ` を渡す 3. 完了を待ち、結果を会話に表示（指摘一覧 + 総合判定） 4. 自分の PR の場合は各指摘の妥当性を評価する 5. ` post_to_pr=true ` の場合は次の「PR への投稿」を実行 #### PR への投稿 ( ` post_to_pr=true ` ) skill 側で投稿する（レビュー用サブエージェントは二重投稿回避のため ` post_to_pr=false ` ）: - **総評コメント**: ` gh pr review <PR番号> --comment --body "<本文>" ` （自分の PR）/ ` --approve ` / ` --request-changes ` （他人の PR） - **インラインコメント**: ` gh api repos/{owner}/{repo}/pulls/<PR番号>/comments ` を使用。各コメントに ` commit_id ` (= ` COMMIT_SHA ` ), ` path ` , ` line ` , ` side ` が必須 投稿後、自分の Draft PR でマージ可能（高指摘なし）なら Ready 化: 1. PR タイトルから ` WIP: ` 削除 2. 本文を ` Summary / Related Issue / Test plan ` テンプレートに更新（ ` Closes ` / ` Refs ` は「Related Issue とクローズ判定」に従う） 3. ` gh pr ready <番号> ` ### 変更確認 ` git status --porcelain ` 、 ` git diff ` 、 ` git diff --cached ` を3つ並列実行する。変更がなければエラー。 ### ステージング判断 以下の懸念がないか確認する: - ` .env ` 、クレデンシャル系（ ` credentials.json ` 、 ` cred-* ` 、 ` *.pem ` 、 ` *.key ` 等） - ` .gitignore ` すべきファイル（ ` node_modules/ ` 、 ` dist/ ` 、 ` __pycache__/ ` 、 ` .venv/ ` 等） - ブランチ名から推測される作業内容と無関係なファイル 懸念がなければ全ファイルを自動ステージング（確認不要）。懸念があれば明示してユーザーに確認する。 ### コミットメッセージ生成 変更内容から日本語で簡潔に自動生成する（確認不要）。ブランチ名に Issue 番号があれば ` #<番号> ` を含める。 ## サブコマンド ### ` /d todo ` 自分が対応すべきものを表示する。 現在作業中のタスクがあるかどうかと、GitHub上でアサインされたIssue、メンション、レビュー依頼を確認する。 1. **2つを並列実行**: - (A) gitコマンドで現在の作業状況を確認 ` git fetch origin && git branch --show-current && git status --porcelain ` - (B) ghコマンドでGitHubを確認。GraphQL で一括取得: ```bash OWNER_REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner) gh api graphql -f query="{ assignedIssues: search(query: \"repo:${OWNER_REPO} assignee:@me is:open is:issue\", type: ISSUE, first: 20) { nodes { ... on Issue { number title labels(first: 5) { nodes { name } } updatedAt } } } reviewRequested: search(query: \"repo:${OWNER_REPO} review-requested:@me is:open is:pr\", type: ISSUE, first: 20) { nodes { ... on PullRequest { number title author { login } updatedAt } } } mentions: search(query: \"repo:${OWNER_REPO} mentions:@me is:open\", type: ISSUE, first: 20) { nodes { ... on Issue { number title updatedAt } } } myOpenPRs: search(query: \"repo:${OWNER_REPO} is:open is:pr author:@me\", type: ISSUE, first: 20) { nodes { ... on PullRequest { number headRefName isDraft } } } }" ``` 2. **fetch 完了後の確認**: - 現在のブランチが main なら ` git rev-list HEAD..origin/main --count ` で同期状態を確認。作業ブランチなら ` gh pr view --json number,title,state,mergedAt,url ` で PR 状態を確認 - アサイン済み Issue について ` git branch -r ` を1回実行し、各 Issue 番号に対して ` origin/*/<issue番号>-* ` のパターンでブランチを探す → ` myOpenPRs ` から PR 有無を判定 → 未着手 / ブランチあり / PR #番号 (Draft|Ready) 3. **出力フォーマット**: ``` ## 現在のブランチ - ⚠️/✓/🔧 の状態表示 ## アサイン済み Issue | # | タイトル | 状態 | ラベル | 更新日 | ## レビュー依頼 | # | タイトル | 作成者 | 更新日 | ## メンション | # | タイトル | 更新日 | ``` 4. **次のアクション提案**: 優先度の高い順に次にやるべき作業を提案する。「main に戻りましょう」は提案しない（作業ブランチで ` /d issue ` を実行すれば自動的に origin/main ベースのブランチが作成されるため） ### ` /d new <タイトル> ` 新しい Issue を起票する（自分が取り組むとは限らない）。 1. 引数を要約してタイトルにする（なければユーザーに聞く） 2. ` gh issue list --state open --json number,title ` で既存の類似 Issue をチェック 3. 説明文の案を生成してユーザーに提示（経緯・現状・期待効果を含める） 4. ` gh label list --json name,description ` で適切なラベルを判定 5. ` gh issue create --title "..." --body "..." --label "..." ` で作成 6. URL を表示 7. **次のアクションを必ず選択肢として提示**（省略不可）: 1. 自分をアサインして今から取り組む → ` /d issue ` の処理を続行 2. 自分をアサインして作業に戻る → ` gh issue edit <番号> --add-assignee "@me" ` のみ 3. 他の人をアサインする（対象者を指定） 4. アサインせず終了 ### ` /d issue <番号またはURL> ` （エイリアス: ` /d i ` ） 既存 Issue に自分が取り組む。ブランチ作成・プッシュで着手を宣言してから方針コメントを投稿する。 1. Issue 番号を特定し、内容取得 + 自分をアサイン: ```bash gh issue view <番号> --json title,body,labels,assignees gh issue edit <番号> --add-assignee "@me" ``` 2. ` git fetch origin && git branch -a --list "*/<issue番号>-*" ` で既存ブランチを確認: - **あり**: 他人のコミットがあればユーザーに確認。なければチェックアウト + 「main 最新取り込み」を実行 - **なし**: Issue からブランチ名を生成（「ブランチ命名規則」参照）。**確認不要で** 作成・push する: ```bash git checkout -b "<prefix>/<番号>-<説明>" origin/main git push -u origin HEAD ``` 3. 方針・実装計画をユーザーに提示 → 承認後 ` gh issue comment ` で投稿（投稿の確認不要） **ここがポイント**: ブランチを push してIssueコメントを残すことで、他メンバーに「自分が #<番号> に着手中」が見えるようになる。重複着手を未然に防ぐ。 ### ` /d commit ` 変更をコミット・プッシュし、PR が未作成なら Draft PR も作成する。 **ブランチ判定:** - **`main` の場合**: 変更内容から prefix を判断し、ブランチ名を生成 → ` git checkout -b "<prefix>/<説明>" ` → 次の手順へ - **作業ブランチの場合**: そのまま次の手順へ **手順:** 1. 変更確認（共通ルール） 2. ステージング判断（共通ルール） 3. ブランチ名から Issue 番号を抽出（ ` feat/123-xxx ` の ` / ` の後の数字） 4. コミットメッセージ生成 → ` git add && git commit ` 5. main 最新取り込み（共通ルール） 6. ` git push -u origin HEAD ` 7. ` gh pr list --head <ブランチ> --json number,title,isDraft,url,author ` で PR 確認 8. **レビュー実行**（ ` is_own_pr=true ` , ` post_to_pr=true ` ）: - **PR がない場合**: ` /d pr ` に従ってDraft PR 作成 → レビュー実行 — 初回レビューは精度優先 - **PR が既存の場合**: 追加コミットの差分をレビュー 9. PR マージ確認（共通ルール） 10. 結果表示: コミットハッシュ・メッセージ、プッシュ先、PR URL、レビュー結果 ### ` /d pr ` Pull Requestを作成。または、作成済のPRに対して必要なアクションをする。 1. ブランチが ` main ` ならエラー 2. ` gh pr view --json number,title,isDraft,url ` で既存 PR 確認 3. **PR あり**: PR コメント確認 → 未対応あれば対応 4. ` git fetch origin main ` → ` git log origin/main..HEAD --oneline ` + ` git diff origin/main...HEAD --stat ` で差分取得 5. PR タイトル（70文字以内）と本文を生成（ ` 概要 / 関連Issue / やったこと / やっていないこと ` 。 ` 関連Issue ` は共通ルールに従い ` Closes ` / ` Refs ` ） 6. ` git push -u origin HEAD ` → PR なしなら Draft 作成、あればタイトル・本文を更新 7. レビュー実行（ ` is_own_pr=true ` , ` post_to_pr=true ` , ` effort=high ` ）→ 結果表示 8. URL 表示 9. PR マージ確認（共通ルール） ### ` /d review ` 作業ブランチの変更をレビュー。PR があればレビューとして投稿可能。 1. ブランチが ` main ` ならエラー 2. ` gh pr view --json number,title,url,isDraft,author ` で PR 確認。 ` gh api user --jq .login ` と ` author.login ` を比較して ` is_own_pr ` を決定 3. レビュー実行（ ` is_own_pr=<判定> ` , ` is_draft=<取得値、なければtrue> ` , ` post_to_pr=false ` , ` effort=high ` ）→ 結果表示 4. **PR あり**: 投稿するか確認 → 投稿する場合は「PR への投稿」を実行（ ` post_to_pr=true ` ）。Draft かつマージ可能なら Ready 化が走る 5. PR マージ確認（共通ルール） ### ` /d improve <改善内容> ` ` /d ` スキル自体の改善提案を Issue 起票する。 1. 引数があればそれを改善内容にする。引数がない場合は直前の会話の文脈（不満や違和感の表明、うまくいかなかった操作など）から推測する 2. 改善内容をもとに簡潔な Issue タイトル（日本語）を生成 3. Issue を作成: ```bash gh issue create --title "<タイトル>" --body "$(cat <<'EOF' ## 改善内容 <スキル改善内容> ## 代替案 <claudeの設定など、スキル自体の改善以外で実現可能な代替案> EOF )" ``` 4. 作成した Issue の URL を表示 ### ` /d help ` 以下をそのまま出力する: ``` ## 開発プロセス ### (1) アサインされたタスクに取り組む 1. `/d` で自分のタスクを確認する 2. `/d issue <番号>` で Issue に着手する（アサイン→ブランチ作成→方針コメント） 3. 実装する 4. `/d commit` でコミット・プッシュ・PR作成 5. `/d review` でレビュー・Ready化 ### (2) 新しい課題を起票する `/d new <タイトル>` で Issue を作成する。自分で取り組むかどうかはその場で選択できる。 ### (3) Issue を立てずに実装する 1. 実装する（main ブランチ上でも `/d commit` が自動でブランチを作成する） 2. `/d commit` でコミット・プッシュ・PR作成 3. `/d review` でレビュー・Ready化 ### (4) このスキルの改善リクエスト `/d improve <不満点や改善案>` で改善提案を Issue 起票する。 ## コマンド一覧 | コマンド | 説明 | |---|---| | `/d` | `/d help` と同じ（サブコマンド省略時） | | `/d todo` | 自分のアサインタスク・メンション・レビュー依頼を一覧 | | `/d new <タイトル>` | 新規 GitHub Issue を起票 | | `/d issue <番号>` (`/d i`) | 既存 Issue に着手（アサイン→ブランチ作成→方針コメント） | | `/d commit` | コミット→push→Draft PR作成→AIレビュー | | `/d pr` | PR 作成・更新 | | `/d review` | 作業内容のレビュー | | `/d improve <内容>` (`/d imp`) | スキル自身の改善提案を Issue 起票 | | `/d help` | このヘルプを表示 | ## ヒント - 厳密なサブコマンド名を覚えていなくても、`/d 42番のIssueに着手して` のように自然言語で指示すれば適切なサブコマンドが実行される - 困ったら `/d` だけ打って、表示された選択肢から選べばよい ``` サブコマンド一覧 サブコマンド 役割 /d （引数なし） /d help と同じ /d todo 自分のアサインタスク・メンション・レビュー依頼を一覧 /d new <タイトル> 新規Issueを起票 /d issue <番号> 既存Issueに着手（アサイン→ブランチ作成→push→方針コメント） /d commit コミット→push→Draft PR作成→AIレビュー /d pr PRの作成・更新 /d review 作業内容のレビュー /d improve <内容> スキル自身の改善提案をIssue起票 /d help 全コマンド一覧と典型フローを表示 個別スキルではなくサブコマンド方式にしたことで、利用者は 「困ったら /d に続けてやりたいことを伝える」だけ で、スキルで規定したルールに則れます。 主役は /d todo / /d issue / /d commit / /d review の4つ 主役サブコマンドは、 作業者がもともと意識している作業アクション に対応します。 自分のタスクを確認する 着手する 成果物を提出する レビューする いずれも Git/GitHubとは無関係に作業過程に存在するアクション です。これらを主役に据え、ブランチ作成・PR作成・mainブランチ取り込みといったGit/GitHub起因の操作は内側に隠してAIが自動化します。 さらに /d todo はIssueのアサイン情報に基づいて着手すべきIssueを提案し、 /d commit はコミットからPR作成、AIレビューまでまとめて実行するため、 典型フローで利用者が実際に打つのは /d todo → /d commit の2つで済むことも多い です。 動かしてみる：2つの典型シナリオ 入口は2通りありますが、 どちらも最後は /d commit に合流し、PRベースの開発フローが進む のがポイントです。 シナリオA：Issue駆動で開発を進める場合 UXデザイナの佐藤さんに「ログイン画面の入力欄の余白を調整してほしい」という Issue #58 がアサインされた。 Step 1: /d todo で確認し、そのまま着手する > /d todo スキルは「現在のブランチ・アサイン済みIssue・レビュー依頼・メンション」を並列取得して整形表示し、 最後に「次に何をすべきか」まで提案します 。 ## 現在のブランチ - ✓ main（クリーン） ## アサイン済み Issue | # | タイトル | 状態 | ラベル | |----|---------------------------------------|--------|--------| | 58 | ログイン画面の入力欄の余白を調整したい | 未着手 | feat | （レビュー依頼・メンションはありません） --- 未着手の Issue が1件あります。優先度の高い #58 から着手しますか？ （アサイン → ブランチ作成 → push → 方針コメント まで実行します） (y/n) /d todo は一覧を並べて終わりではなく、 「未着手の #58 から着手しますか？」と次の一手まで提案 します。利用者は表を眺めて「次に何をしよう」と考える必要がありません。ここで y と答えれば、着手処理がそのまま走ります。 # 「はい」と答えた後にスキルが実行する内部処理 gh issue edit 58 --add-assignee "@me" git checkout -b "feat/58-login-margin" origin/main git push -u origin HEAD gh issue comment 58 --body "<実装方針>" ブランチがpushされた瞬間、GitHubの他メンバーには「佐藤さんが #58 着手中」が見えます。 これだけで重複着手を大きく減らせます。 着手の入口は2通り、どちらでもよい — Issue番号が最初からわかっているなら、 /d todo を経由せず /d issue 58 を直接打っても同じ着手処理に入ります。「 /d todo の提案に乗る」か「 /d issue を直接打つ」かは、利用者が好きな方を選べます。 Step 2: 実装 → /d commit 佐藤さんはClaude Codeに実装を任せ、完了したら /d commit を実行。 コミット → push → Draft PR → AIレビュー → Ready化 → マージ → Issueクローズ までが一気に流れます。 結局、利用者が打つのは /d todo （提案に乗って着手）→ /d commit の実質2コマンドだけ。ブランチ名やコミットメッセージ、PR本文を書く場面はありません。 補足：Issueがまだ無いときは /d new で起票する シナリオAはアサイン済みの Issue #58 から始めましたが、そもそも取り組みたいことがまだIssueになっていないこともあります。その場合は /d new に概要を渡すだけで起票できます。 > /d new ログイン画面の入力欄の余白を調整したい スキルは既存の類似Issueを確認したうえで、タイトル・説明文・ラベルの案を生成して起票し、作成後に 「誰が取り組むか」を選択肢で提示 します。 Issue #59 を作成しました： https://github.com/<owner>/<repo>/issues/59 続けてどうしますか？ 1. 自分をアサインして今から取り組む（そのまま着手処理へ） 2. 自分をアサインして後で取り組む 3. 他の人をアサインする 4. アサインせず終了 1 を選べば、そのまま /d issue 相当の着手処理（アサイン → ブランチ作成 → push → 方針コメント）に流れます。 「起票 → 着手」がコマンドを打ち替えずに一本でつながる のがポイントです。起票だけして他の人に任せたい（ 3 ）、あとで自分でやる（ 2 ）といった分岐も、その場で選ぶだけで済みます。 また /d new は、機能追加のようなきちんとしたIssueだけでなく、 「このドキュメントを直してほしい」「Claudeのスキルを修正して」といったちょっとした作業依頼 にも気軽に使えます。口頭やチャットで流れがちな細かい依頼もIssueとして残り、依頼のハードルが下がります。さらに 受けた側が /d issue で着手するときには、AIがIssue本文（背景・経緯・期待する結果）を文脈として読み取れます 。チャットの断片的なやり取りと違い、要件がまとまっているぶん、AIは意図を汲んだ実装や方針コメントを返しやすくなります。これは冒頭で触れた 「AIが文脈を理解しやすいようにGit/GitHubへ集約する」 流れに、気軽な起票がそのまま乗る形です。 シナリオB：Issueを立てず、思いついた改善案をいきなり作り始める場合 UXデザイナの佐藤さんは、ふと思いついたUIの改善案をその場でClaude Codeに作らせてみた。Issueも立てず、ブランチも main のままローカルに修正案ができあがっている。仕上がりが良かったので、そのまま /d commit を実行する。 > /d commit このとき、スキルは変更内容を確認し、 変更内容から適切なブランチ名（ fix/update-signup-form-warning-message など）を判断 自動でブランチを切ってから コミット そのブランチをpushし、Draft PRを作成 続けて AIレビューが走り 、変更内容に問題がなければReady化 シナリオAと同じく、 /d commit の先はDraft PR作成からAIレビュー・Ready化まで一気に流れます。佐藤さんは「ブランチを切り忘れた」「Issueを立て忘れた」と慌てる必要がなく、思いついた改善案を形にすることだけに集中できます。 「アイデアを止めずに作り、後から正しい形に整える」 ── バイブコーディングのリズムを保ったまま、結果的にお行儀の良い形に着地します。 スキル改善の経緯と考え方 /d は最初から今の姿だったわけではありません。初期はもっと細かく「ブランチを作る」「Pull Requestを作る」といった Gitの操作にも1つずつコマンドを紐づけており、個々の操作をAIで補完しているだけでした。エンジニアにとっては違和感がなくとも、エンジニア以外の利用者から見ると どのコマンドを打つか選ぶ時点でGitの知識が必要 で、開発フローの作法を覚える負担が残っていました。 そこで 「ツールではなく目的中心でスキルのあり方を決める」 ことを強く意識し、使いやすさを追求して改善を重ねました。判断軸として参照したのが、UX設計の古典である ヤコブ・ニールセンのユーザビリティ10原則 です。スキル開発は「自分が便利な機能を足す」方向に流れがちですが、10原則に照らすことで「これは利用者目線の仕様になっているか？」を問い直せました。 10原則は以下のとおりです（和訳は本記事での表記）。 Visibility of system status / 状態の可視性 Match between the system and the real world / 現実世界との調和 User control and freedom / ユーザーコントロールと自由 Consistency and standards / 一貫性と標準 Error prevention / エラー予防 Recognition rather than recall / 再生より再認 Flexibility and efficiency of use / 柔軟性と効率性 Aesthetic and minimalist design / 最小限デザイン Help users recognize, diagnose, and recover from errors / エラー回復 Help and documentation / ヘルプとドキュメンテーション この章では、特に大きく効いた 4つの改善 を、対応する原則とともに紹介します。 改善1：コマンドを「Git操作」から「作業アクション」へ（原則2 現実世界との調和） 最大の改善が、コマンド体系そのものの組み替えです。 Before — ブランチ作成・コミット・PR作成…と、Git/GitHubの操作を利用者が1つずつ呼び出す体系 After — /d todo （見る）・ /d issue （着手）・ /d commit （提出）・ /d review （レビュー）の4つ。ブランチ作成やPR作成はこの内側に隠れる 原則2「現実世界との調和」は、 利用者が現実世界から類推するイメージにシステムを合わせよ という原則です。タスクを見る・着手する・成果物を提出する・レビューする ── いずれもGit/GitHubに関係なく開発の作業過程に存在するアクションであり、利用者が説明されなくてもする行動です。ここに揃えたことで「開発ツールの使い方を学ぶ」という壁が解消されました。 改善2：「誰が何をやっているか」が自然に見える（原則1 状態の可視性） 原則1「状態の可視性」は、 システムの状態を利用者に常に見えるようにせよ という原則です。 /d ではこれを個人の画面にとどめず、 チームに対する作業状況の可視化 に広げました。改善1で「着手」の内側に束ねた一連の操作が、そのまま 着手宣言プロトコル として機能します。 /d issue 58 を実行した時点で、 アサイン + 作業ブランチのリモートpush + 方針コメントの投稿 が走ります。コミットがまだ無くても「私が #58 やってます」が周囲に見えるようになります。地味ですが、これだけで 実装を二重に進めてしまう事故 を大きく減らせます。自分から「やってます」と声を上げなくても着手した時点で自然に共有され、チーム全体での作業状況が見えやすくなります。 改善3：誤操作は注意ではなく仕組みで防ぐ（原則5 エラー予防） 原則5「エラー予防」は、 丁寧な注意喚起よりも、そもそもエラーが起きない設計を優先せよ という原則です。Gitを使っていて起きがちな失敗に対して、「気を付けてね」と促すのではなく仕組みで潰します。 /d スキルを使いながら取り入れた予防の仕組みをいくつか紹介します。 # 起きがちな失敗 スキルでの解決 1 同じ内容のIssueを重複起票 起票前に既存Issueとの類似をチェック 2 mainで作業して直push 変更を検知し、自動でブランチを切ってからコミット 3 test tmp 等でブランチ名が乱立 Issue・変更内容から命名規則に沿って自動命名 4 同じIssueを別ブランチで重複着手 着手時に既存ブランチを確認、他人のコミットがあれば確認 5 .env ・ node_modules 等を誤commit ステージング前に自動検知して確認 6 Issueと無関係なファイルが混入 ブランチ名から推測した作業内容と照合して警告 7 未コミット変更を抱えたままcheckout 切り替え前に確認し、コミット/中断を提示 8 ローカルのmainが古いまま進めてconflict地獄 作業着手時やpush前にmainとの差を自動チェックし取り込みを提案 9 Issue・コミット・PRの説明の作文が面倒で省略・雑になる 変更内容からAIがタイトル・本文・コミットメッセージ・PR説明を自動作文 改善4：思い出させない・迷わせない（原則6 再生より再認） 原則6は、認知科学でいう 「再生（recall）より再認（recognition）の方が遥かに楽」 という性質に基づく原則です。「次に何をすべきか」を利用者が思い出す（再生）必要をなくし、 提示された選択肢から選ぶ（再認） だけで正しい手順を歩めるようにします。 「次にやること」を選択肢で提示する サブコマンドの終わりには、必ず 次の候補アクションを選択肢で提示 します。 /d todo の最後 → 優先度の高い順に次のタスクを提案 /d new で起票後 → 「自分をアサインして取り組む / アサインのみ / 他の人にアサイン / アサインしない」 /d commit のレビュー完了後 → 「マージしますか？ (y/n)」 利用者は「次に何をすればよかったっけ」と考える必要がなく、選ぶだけで正しい手順に乗れます。 リスト出力に必ず識別子を振る 「選ぶだけ」のやり取りを支えるため、表・箇条書き・選択肢など複数項目が並ぶ出力には、 必ず連番や記号の識別子を振る ルールにしました。Issue番号のような既存IDがあればそれを使い、無ければ連番を振ります。たとえば実装前に手順の計画を出させると、こうなります。 実装計画: 1. 入力欄コンポーネントの余白を変数化 2. ログイン画面へ適用 3. モバイル表示のスタイル調整 4. 他画面のフォームへ横展開 5. 不要になった旧スタイルの削除 どこまで進めますか？ 地味ですが効果は大きく、利用者は 「一旦3まで進めて」「4と5は不要」 のように番号だけで指示できます。AIとのチャットでは対象を言葉で説明し直したり長い引用をコピペしたりが負担になりがちですが、識別子があるとやり取りが一気に短くなります。 10原則ダイジェスト：残りの原則も設計に対応づける 改善1〜4で使った原則（1・2・5・6）以外も、 /d の設計判断のあちこちに対応しています。残り6つをダイジェストで紹介します。 原則3 ユーザーコントロールと自由 — Issue起点のフローに限定せず、mainでの思いつき着手も許容。破壊的操作の前には必ず (y/n) 確認 原則4 一貫性と標準 — issue commit などの用語は技術側に合わせ、利用者の用語習得やエンジニアとの意思疎通を重視 原則7 柔軟性と効率性 — 初心者は /d todo の提案に乗るだけで着手まで進み、慣れたら /d issue を直接打つ・エイリアス（ /d i ）を使うなど効率化できる。さらに /d improve でスキル自体を進化させられる 原則8 最小限デザイン — 覚えるべきコマンドを少なくし、自然言語でも動くようにすることで、スキルの使い方をシンプルに 原則9 エラー回復 — ワークフロー操作をAIが実施することで、エラー時もAIが能動的に調査・回復できる。使いづらさがあれば /d improve で不満を改善案としてIssue化できる 原則10 ヘルプとドキュメンテーション — /d help で全コマンドと典型フローを表示 おわりに 本記事では、Git/GitHubを使った開発フローをエンジニア以外のメンバーと協働して進めるためのスキルについて紹介しました。エンジニア以外のメンバーとともに開発するチームで、 全員が安心して開発できる環境づくりの一助になれば幸いです。 「こうしたらもっと良くなる」「自分のチームではこうしてる」などがあれば、是非コメントください！

はじめに 昨今、仕様駆動開発 (Spec-Driven Development) の名前を耳にする機会が増えてきたと感じています。MiiTel Phone チームにおいても数ヶ月ほど OpenSpec というツールを使用して仕様駆動開発を試みていました。結論として、OpenSpec の採用は取りやめることにしました。今回は OpenSpec をベースに仕様駆動開発を試してみて感じた課題や所感について共有いたします。 前提 フロントエンド開発における採用です 新規開発ではなく、既存プロダクトの開発における導入です ⚠️ 注意書き 本記事は仕様駆動開発の手法や OpenSpec などのツールそのものを非難する意図はありません。 あくまで「MiiTel Phone チームでは合わなかった」というだけであり、 仕様駆動開発が有益であるかどうかは、チームの文化や開発フローなどによっても異なってくると思います。 そのため、最終的には実際にツールや手法などを試してから判断いただくことを推奨いたします。 📚 仕様駆動開発 (Spec-Driven Development) について 概ね「まず Spec を書き、それをベースに AI エージェントにコードを書いてもらう手法」のことを指すことが多いのではないかと思います。 Spec は AI エージェントと人の双方に対して信頼できる情報源として振る舞うことが想定されます。 martinfowler.com OpenSpec について OpenSpec は Node.js 製の仕様駆動開発のためのフレームワークです。 github.com OpenSpec を採用したのは以下の理由からです。 まずは既存のツールを使用して進めた方が自分達で仕組みを整備するよりも手間が少ないと考えたこと Node.js 製であるため、フロントエンド開発においては普段使用しているパッケージマネージャーを使用して導入・管理ができること シンプルであり、導入にあたっての心理的障壁が比較的低いこと 様々な AI エージェント (Claude Code, Gemini, Codex など) をサポートしていること 使い方 # インストール $ mise use npm:@fission-ai/openspec@latest $ openspec init # Claude Code での利用例 $ claude > /opsx:new 仕様駆動開発を試みた背景 仕様駆動開発を試みたのは、下記が目的でした。 AI コーディングエージェントは実装や仕様の背景などに関する知識を保持していないことに加え、セッションごとに記憶がリセットされてしまう。必要なコードが削除・改変されてしまうなど、意図せぬコード生成が行なわれてしまうケースをできる限り防止したい。 新規メンバーでもプロジェクトのキャッチアップを行いやすくするために、暗黙知をきちんとドキュメント化する仕組みがあると便利ではないかと考えていました。 OpenSpec により仕様駆動開発を実践し、Git リポジトリ内に要求や過去の設計における意思決定の背景などが自然と蓄積されることにより、これらの課題が自然に解消されることを目論んでいました。そして、仕様駆動開発を支援してくれる特定のツールを採用することによって実践のハードルを低下させつつ、チーム内で方法を統一できるようにすることを期待して、まずは導入コストが低いと思われる OpenSpec を導入することにしました。 OpenSpec ってどうなの？ まず OpenSpec においては openspec/specs/<spec>/spec.md に信頼できる情報源としての仕様が蓄積されます。具体的には以下のようなフォーマットの Markdown によって仕様が記述されます。 # Example Specification ## Purpose This app supports a simple, reliable TODO management experience for individuals. ## Requirements ### Requirement: Creating and managing TODO items The TODO app MUST allow a user to create, view, and complete TODO items. #### Scenario: Creating a new TODO - **GIVEN** a user is signed in to the TODO app - **WHEN** the user enters a title and submits the form - **THEN** a new TODO item is created with status "Incomplete" - **AND** the new TODO item appears in the TODO list #### Scenario: Completing a TODO - **GIVEN** a TODO item exists with status "Incomplete" - **WHEN** the user marks the TODO item as completed - **THEN** the TODO item's status becomes "Completed" - **AND** the TODO item is visually distinguished as completed in the list 実装の開始時に /opsx:new コマンドを実行すると、OpenSpec は対話的にやり取りしたを内容ベースに openspec/changes/<change> ディレクトリへ以下のようなファイルを作成してくれます。 design.md - 実装予定の機能に関する設計をまとめたドキュメント proposal.md - 実装予定の機能に関するハイレベルな要約をまとめたドキュメント tasks.md - 実装時に行うべきタスクをチェックリスト形式でまとめたドキュメント <spec>/spec.md - 本実装を進めることによって openspec/specs/<spec>/spec.md に対して生じる仕様への差分をまとめたドキュメント 開発が完了したら、 /opsx:archive コマンドを実行することで、 openspec/changes/<change>/<spec>/spec.md が openspec/specs/<spec>/spec.md へマージされた後、 openspec/changes/<change> の各ドキュメントが openspec/changes/archive/<change> へ移動されます。 これにより、 openspec/specs/<spec>/spec.md が常に最新化されつつ、過去の実装における意思決定の背景や仕様に関する変化の過程などが openspec/changes/archive/<change> へ蓄積されてゆきます。 まず実装に取り掛かる前に design.md を作成してくれる点は良い点に感じました。事前にチーム内で design.md をレビューすることで、実装に取り掛かる前に考慮漏れがないか検討することができます。 また、OpenSpec は tasks.md のチェックリストに順次チェックをつけながら開発を進めてくれるため、途中まで開発を進めてもらった状態で一度セッションを中断し、後から新しくセッションを作り直して開発を再開してもらうような進め方などもやりやすかったです。 ただし、後述する課題により、少なくとも MiiTel Phone チームの開発においては「わざわざ OpenSpec などのツールを使ってもあまり期待した効果は得られなさそう」というのが率直な結論でした。 OpenSpec がマッチしないと感じた理由について なぜいまいちマッチしないのか考えたところ、4 つほど要因があるのではないかと思いました。 フロントエンド開発との相性がそこまでよろしくない 手間に見合うほどの効果を実感できなかった 他の手法によって代替可能であること 仕組みとしてはやや貧弱であること 1. フロントエンド開発との相性がそこまでよろしくない フロントエンド開発における関心ごとの大半はプレゼンテーションレイヤーに偏りがちです。ドメインレイヤーの関心ごとなどと比較して、自然言語によって「何が正しいか」を形式的に定義・記述することが難しいケースが多いと感じました。 また、プレゼンテーションレイヤーはドメインレイヤーにおける制約や振る舞いなどと比べて変化しやすく、頻繁に Spec の見直しが必要となってしまうケースが多いです。結果として手間がかかると感じてしまうケースがありました。 逆にドメインに関する関心ごとの比率が高いバックエンド開発においての方が仕様駆動開発との相性は良いのではないかと感じました。 2. 手間に見合うほどの効果を実感できなかった ※ そもそも MiiTel Phone チームにおいては、OpenSpec の導入以前から、要件定義の段階で要求や制約などをあらかじめ Notion ドキュメントにまとめてから開発に取り掛かるケースが多かったです。 OpenSpec における openspec/specs/<spec>/spec.md はあらかじめフォーマットが規定されているため、一貫したフォーマットを維持できるなどのメリットもあります。しかし、使い慣れている Notion ドキュメントと比較するとどうしても表現力に制限があると感じるケースが多々ありました。また、全体的にコーディングエージェントに生成してもらった文章はやや冗長になりがちで、人が仕様や要求を理解するためのドキュメントとしてはあまり効果を実感しづらかったという事情もあります。 OpenSpec がドキュメントを生成してくれることにより事前にレビューができるなどのメリットはあるものの、逆に更なるレビューや編集の必要性が発生することにより、却って手間がかかってしまうケースがあるとも感じました。 ※ ただし、この課題は OpenSpec の問題というよりは、MiiTel Phone チームにおける開発プロセスとの相性の問題であると思います。 3. 他の手法で代替可能であること OpenSpec をベースに仕様駆動開発を進めることで、以下のようなメリットが得られます。 過去の設計や実装における意思決定の履歴をリポジトリに記録として残すことができる。 開発に取り掛かる前に OpenSpec が生成した design.md をチーム内でレビューすることで、考慮漏れを探すことができる。 ただし、過去の意思決定の履歴をリポジトリへ記録することは、Git のコミットメッセージをきちんと記述することによって代替可能です。そしてコミットメッセージをきちんと記述することによるコストはコーディングエージェントによって大幅に緩和されています。 また、過去の意思決定の記録は、リポジトリ内に残さずとも、ADR を Notion データベースなどで管理しておき、Notion MCP などによって検索できるように整備しておくことによって代替可能です。 そして、過去の設計や実装における意思決定の履歴がリポジトリ内にファイルとして蓄積されていく ( openspec/changes/archive ) ことにより、コーディングエージェントが意図せぬタイミングで古いドキュメントを参照してしまい、却ってコード生成の精度が低下してしまうというデメリットが発生する懸念もあることに気づきました。 4. 仕組みとしてはやや貧弱であること ドキュメントはとても重要なものであるものの、仕様駆動開発における Spec はあくまで静的なドキュメントでしかありません。 そのため、AI エージェントが生成したコードが正しく仕様に則っている状況を維持し続けるためには、結局、信頼性の高いテストコードやコードレビューなどが必要です。 コストを掛けて投資をしていくのであれば、テストコードの信頼施の改善や拡充などにより力を入れ、テストコードを仕様として扱ってゆく方針で進めた方が効果が高いのではないか、という結論に至りました。 tech.revcomm.co.jp ただし、過去の意思決定の記録を残すために ADR を記述することは依然として価値があるとは感じており、このようなプラクティスは今後も実践し続ける想定です。 今後について 最終的に OpenSpec はいまいちチームにおける開発の進め方とマッチせず、メリットを活かし切ることもうまくできなかったこともあり、廃止をすることに決定しました。逆に OpenSpec が想定するやり方にチームの開発プロセスを合わせるという方法もありそうですが、そこまでして導入するメリットも薄い、との判断に至りました。 Notion で ADR や要求などをまとめたドキュメントを用意し、必要に応じて Notion MCP を活用して必要なドキュメントを参照できるようにすれば十分ではないかというのが結論です。 OpenSpec を試していく中で良かったと感じたこととしては、まず、要件や要求などをまとめたドキュメントを用意し、それに基づいて開発を進めるプロセスそのものはそこまで悪くはないと感じました。技術的な詳細はコーディングエージェントに委ねつつ、人はよりハイレベルなポイントに対して注力しやすくなります。 今後は ADR のより積極的な活用や、Notion との連携強化、テストコードの拡充や信頼性の改善などを進めていくことで、より効果的にコーディングエージェントを活用していきたいと考えています。