はじめに
NTT ドコモソリューションズの松田と申します。
本連載「Claude Code で環境構築」では、実際に使用するサーバの環境構築を Claude Code を活用して自動化する中で得られた気付きやノウハウをまとめていきます。
AI エージェントに環境構築を任せると何ができて、どこでつまずくのか。つまずかないためにどう指示すればよいのか。筆者の失敗と立て直しの実例を通じて、これらをお伝えすることを目指しています。Claude Code のような AI エージェントを日常の業務に活用した例としてご覧ください。
第 1 回の本記事では、本連載をするきっかけとなったプロジェクト全体のストーリーを紹介します。
後続の記事では、指示の出し方や GUI 操作の自動化、トラブルシュート事例など、個別のテーマを掘り下げます (各回のテーマは末尾の「後続記事について」を参照) 。
対象読者
- AI エージェントを業務で使い始めた方
- これから環境構築・運用作業への適用を検討しているインフラ・運用担当のエンジニアの方
1. 概要
Claude Code を活用し、Ansible を併用してベアメタルサーバの環境構築作業を自動化しつつ、更新しました。
業務的な成果としては、ざっくりまとめると次の 3 点となります。
- 構築の検証で使用する仮想マシン (VM) の作成、VM への OS インストールの自動化
- OS インストール後の環境構築作業の自動化
- 構築した環境の実運用
元々更新作業はやる予定だったのですが、正直忙しくて手が回らず、頓挫しかかっていました。この状態から、「自動構築が完了し、実運用に移行した」状態へ持ち上げることができ、AI エージェントの威力を改めて実感した次第です。
しかし、実現までの道のりは、決して平坦ではありませんでした。
今回は Claude Code の明るい面だけではなく、下手をすると環境を破壊しかけるという手ひどい失敗も経験しました。この失敗した点と、そこからの構築ワークフロー再設計と再実装、実機適用といったプロジェクトの全容を通じて AI エージェントの実務適用イメージをお伝えします。
なお、本作業は 2025 年末～2026 年 6 月頃に行ったもので、Ubuntu 26.04 がリリースされた前後の話です1。この点を踏まえてお読みください。
検証環境
| 項目 | 内容 |
|---|---|
| AI エージェント | Claude Code |
| 構築の自動化 | Ansible (実行環境は uv で構築) |
| 検証用 VM の基盤 | Kubernetes + KubeVirt (Kubernetes 上で VM を動かすための拡張)、ストレージは Rook-Ceph |
| 構築対象 OS | Ubuntu 24.04 Desktop、Ubuntu 26.04 Desktop |
| 構築対象 | 検証用 VM、ベアメタルサーバ (OS は PXE 経由でインストール) |
用語の補足
本記事で使う主な用語を簡単に補足します。
| 用語 | 説明 |
|---|---|
| VM (仮想マシン) | 1 台の物理サーバの上に、ソフトウェアで作る仮想的なコンピュータ |
| ベアメタルサーバ | 仮想化せず、物理サーバに OS を直接インストールして使うサーバ |
| Ansible | サーバの設定作業を YAML 形式の手順書 (Playbook) に記述し、SSH 経由で自動実行する構成管理ツール。同じ手順を何度でも同じ結果で再現できる |
| Kubernetes (K8s) | コンテナで動くアプリケーションの配置や運用を自動化する基盤 |
| KubeVirt | Kubernetes 上で、コンテナと同じように VM を作成・管理できるようにする拡張機能 |
| Rook-Ceph | 分散ストレージ Ceph を Kubernetes 上で運用するための仕組み。本記事の環境では、VM のディスクの置き場所として使用 |
| PXE | ネットワーク経由でサーバを起動し、OS をインストールする仕組み |
| uv | Python の実行環境とパッケージを管理するツール |
2. 背景、経緯 ── 頓挫しかかっていた更新作業
筆者のチームはオンプレミス環境で、検証用にベアメタルサーバを数台保有しています。大分年季の入りつつあるサーバなので、当然手作業で構築し、メンテナンスも手作業でした。正直手数はかかります。手間がかかる子ほど可愛いかもしれませんが、相手は厳ついサーバです。愛でるのも限界があり、一部古い OS バージョンのまま動いているサーバは半分塩漬けの状態でした。
しかし、OS の更新が止まった状態はセキュリティ上好ましくありません。ミドルウェアを更新していても、OS の入れ替えを含むアップグレードを行わなければ、セキュリティ上のリスクは残ります。
とはいえ OS の入れ替えやアップグレードのような作業となると、構築するのも大変、動作検証も大変です。筆者のチームの古い OS で動いていたサーバには、セキュリティ関連のミドルウェアを多数導入していました。OpenSSL・OpenSSH・アンチウィルス、ファイアウォールや IPS (侵入防御システム) などです。そのため、構築の難易度はそれなりに高いものでした。
このような背景から、手作業での構築検証、動作検証は長らく進められませんでした。
そのような時に現れたのが、AI エージェント「Claude Code」です。筆者は AI エージェント初心者ながら、これまで「Claude Code を使った文書レビュー」「Claude Code を使った AI 駆動開発」といった検証をしてきました。その中で「これは・・・更新作業も Claude Code でイケるのでは・・・？」と直感しました。
これまで Claude Code を使ってきた中で、Python やシェルスクリプト、PowerShell のようなコード生成ができることはわかっています。LLM ベースの AI エージェントだけあって、文章を扱うことも得意です。幸いにして Ubuntu であれば手元に環境構築手順が部分的にあります。
手元の構築手順メモと、やりたいことを伝え、古い OS から Ubuntu への更新を実現する。自動で。イケるんじゃないかこれは。その後に待ち受ける壁を考えず、その頃はそう考えていました。
3. 失敗 ── 環境破壊寸前
更新対象であるサーバはベアメタルサーバです。いきなり OS を入れ替えてしまっては、うまく行かなかったときに困ります。このため、次のような段階を踏んで更新作業を進めることとしました。
- 検証環境 (Kubernetes + KubeVirt) に作った VM を用いて環境構築検証
→OS の基本的な設定と、OpenSSL 、OpenSSH 、アンチウィルス、ファイアウォール、IPS などのミドルウェア導入および設定 - ベアメタルサーバに OS インストール ※手動
→どうせなので上記の VM を用いて PXE (ネットワークブート) サーバを動かし、PXE 経由でインストール - ベアメタルサーバの環境構築
環境構築は自動化したいです。過去に「Claude Code を使った文書レビュー」を行ったときの経験から、構築時のコマンドを逐一 AI (大規模言語モデル / LLM) で生成するのは精度が悪くなると感じていました。このため、基本的には Ansible スクリプトを併用する形で実装するという方針にしました。
筆者自身が認識していた全体の構成は次のようになります。VM とベアメタル、どちらも OS 設定やミドルウェアは同じものを仕込んでもらいます。
図1 全体構成
意気揚々と git プロジェクトを作成し、Claude Code を立ち上げ、プロンプトを打ち込みます。手を抜ける所は手を抜く方針で、プロンプトで伝えた要望をもとに仕様書を作成してもらう腹積もりです。仕様書の作成には、当時自作していた、仕様と実装の作成を支援するカスタムコマンドを使いました (まだスキルという概念もよくわかっていなかった時期です) 。コマンドの質問 (Assistant) に答える (User) 形で、次のように要望を伝えています。なお、本記事に掲載するプロンプトは、パスや製品名の表記をそろえるなど、一部を編集しています。
### What (何を作るか)
Assistant: まず、実装する機能について教えてください：
User:
Kubernetes 上の KubeVirt 環境、またはベアメタルサーバに対し、
PXE サーバを自動構築するための Ansible スクリプトおよび操作の助けとなるシェルスクリプト
### Why (なぜ必要か)
Assistant: ありがとうございます。次に背景を教えてください：
User:
+ 手動での PXE サーバ構築が煩雑で時間がかかるため
+ 複数環境への展開を効率化したい
+ ベアメタル / KubeVirt 環境の両対応が必要
### 機能要件
Assistant: 次に要件を教えてください。
**機能要件** (3-5 個リストアップ):
実装する機能の具体的な要件をリストアップしてください
User:
+ 本環境への Ansible 動作環境のセットアップを行ってください。uv を使用してください。
+ 基本的なパッケージ類の構築内容および手順は @構築手順書.md を参照してください。
ただし PXE サーバ部分は手順に含まれていないため、構築した環境上で docker を用いて PXE サーバを起動するものとします。
+ 構築対象の OS は Ubuntu LTS のデスクトップ環境とします。
+ 使用する OS、パッケージ、および構築対象にセットアップするパッケージは、可能な限り最新版を使用してください。
+ Kubernetes KubeVirt 環境用に、VM の構築、OS インストールを行う Ansible Playbook も作成してください。
+ ベアメタルサーバの場合、構築対象となるサーバは OS インストール完了済、鍵認証による ssh 接続ができるものとします。
概ね、上図の構成を意識し、必要十分な情報を与えているように見えます。
上記の情報を入力すると、ほどなくして仕様書、設計書が作成されました。ざっと中身を見て問題がないことを確認し、実装を指示。でき上がったら Claude Code に「実装したものを用いて、Kubernetes 上に VM を作成し、VM に環境構築を行ってください」と指示します。すばらしい、これだけの期間塩漬けだった案件が、あっという間に進んでいきます。
感動すら覚えつつ、処理ログが流れる様を見つめること数分。
<Kubernetes ホスト> のホスト名を修正します
という感じのログが流れました。読み間違いかと思い、見直すこと 3 回。キーを連打し処理を停止。ここまでコンマ 5 秒程度。かろうじて処理が停止します。コンマ 5 秒で 3 回見直してキー連打する様は、傍から見れば神速の領域だったのではないでしょうか。
改めてログを見直すと、VM を作成し、VM の中を処理するはずが、なぜか VM ホストサーバの構築をしようとしていました。何をどう間違えたのかわかりませんが、VM を作成しようとする気配は欠片もありません。
念のため手動で ps や kill を使用し、怪しい処理が残っていないか確認し処理。その後 Claude Code を停止。呆然としながらプロジェクトを閉じます。
4. 再始動 ── 要件定義からの再出発
最初の試みが失敗してから 2 ヶ月。他の作業もあり、更新プロジェクトに手をつけずに放置しました。再度の塩漬けです。
しかしいつまでも放置していられません。年度の切り替わりを機に、再始動します。
失敗を振り返ると、この失敗の根本原因は、VM とベアメタルではワークフローが分岐するという部分にあるように思えました。VM の場合は「VM を作成してから OS を入れて構築する」工程が先にあり、ベアメタルの場合は「すでに OS が入ったサーバに SSH で接続して構築する」工程から始まります。この境界を AI に伝えきれていなかったのではないか。それを意識し、次の方針を立てました。
- 「何に対して作業するか」を、より明確にする。
- ワークフローを明確にし、検証用 VM に対して行う作業と、ベアメタルサーバに対して行う作業の境界を示す。
- VM とベアメタルサーバの分岐を確認しつつ、段階的に作業を進める。
- 本プロジェクトでは、Claude Code が既存ファイルの修正で対応しようとする傾向が見られたため、以前の成果物は一旦捨てる。
再始動し、今度こそ完遂するため、再始動一発目のプロンプトを入力します。以前の全成果物 5,322 行も削除。正直胃が痛いです。
本プロジェクトで作成した仕様書、成果物について、想定と大幅に異なるものができてしまったため、再度仕様から検討しなおします。
実装コードの動作が、想定していた動作と異なりました。設計書に書いた内容では不足があるため、仕様書、設計書の作り方から見直しを行いたいです。
具体的には、本プロジェクトで作成した Ansible スクリプトを用いて、構築対象となる環境の構築を行う際、構築対象の確認が明確にできていません。また構築対象がベアメタルサーバかサーバ上の VMの確認ができておらず、VM を作成した上で VM 内の環境構築をするつもりが、VM ホストの環境構築をはじめようとしていました。
まず、こちらで作成したファイルをすべて削除します。
実は上記の指示を入力した後、「わかりました。では今のファイルをこれこれこのように修正します」と言い出したので、「いえ、一度ファイルを消去し、やり直します」と押し切ったりしています。Claude Code も必死ですが、こちらも不退転の覚悟で押し切りました。
続いて仕様作成。今回は丁寧に指示し、段階的に作っていきます。
これから、Kubernetes 上の KubeVirt 環境、またはベアメタルサーバに対し、PXE サーバを自動構築するための Ansible スクリプトおよび操作の助けとなるシェルスクリプトを作成するプロジェクトの仕様書と設計書を作成します。
Ansible で実装させたい作業は、従来 Markdown @構築手順書.md を用いて、手動で行っていた作業です。
これを Ansible を用いて、自動化したいと思います。
最初に仕様書を作成します。仕様書は doc ディレクトリの下に、requirements.md として作成してください。
また構築対象サーバの情報詳細を示します。
+ 構築対象となるサーバの情報
+ ベアメタルサーバの場合、ssh接続のための情報確認(IPアドレス、ユーザ名、証明書など)を確認し、ssh経由でベアメタルサーバに接続する。
+ Kubernetes KubeVirt上で稼働するVMの場合、VMが作成済か否か。
+ 未作成、作成済、いずれの場合も、Kubernetesホストへのssh接続情報を確認する。
+ 未作成の場合、VMを作成する。VM作成は、可能であればAnsible化する。不可能な場合、Kubernetesデプロイ用のyamlのテンプレートを作成しておき、作成に必要な情報を後から埋め込んだうえで、VMホストからkubectlなどを用いてデプロイする。作成後、ホストサーバ経由でVMに接続する。
+ 作成済の場合、ホストサーバ経由でVMに接続する。
+ ベアメタルサーバ、VMのいずれも、接続方法を記憶しておき、以後の作業を行う際には、記憶した接続方法を用いて構築を実施することとする。
+ 以降は @構築手順書.md に書かれた内容に従います。
@構築手順書.md に書かれた内容については、1つずつ仕様を確認し、実装を行うこととします。
ここまでの内容を仕様としてまとめてください。不明な点があれば、質問してください。
次の点を仕様に反映してください。
+ 使用する OS は、Ubuntu 26.04 とします。
+ 適用範囲について、VM の場合、ISO ファイルから VM を作成する部分は構築対象としてください。
+ KubeVirt 環境の K8s ホストは ******** です。
+ 前提条件となる python、uv、ansible については、ワークフローの最初に環境構築済か確認し、未構築の場合は環境構築するものとしてください。
仕様として、今回実装する内容を、大きく 4 つのスキルに分割し、実装したいと思います。
+ python、uv、ansible など、以降の作業を実施するために必要な環境を構築する「pxe-env」スキル
+ VM を作成する場合、KubeVirt 上に VM を作成する「pxe-vm-kubevirt」スキル
+ ベアメタルサーバまたは VM の中に Ansible を用いて環境構築する「pxe-build-base」「pxe-build-pxe」スキル
pxe-env スキルについては、Ansible 環境を実装するスキルのため、Ansible Playbook では構築できないと思います。Claude Code skills (スキル) で構築することとしてください。
これらのやり取りを経て、約 800 行の要件定義書を作成しました。
失敗した時の仕様書と異なり、今回は次の点を細かく定めています。
- 構築対象が VM かベアメタルかを起点に据えたワークフロー
- 機能要件として定めた個々の設定項目
- 「どこに繋いで何をするか」をスキル単位で分離した構成
ワークフローの全体像は次のとおりです。
図2 ワークフローの全体像
5. VM 検証からベアメタル実機適用まで
本プロジェクトの基本戦略は「VM で検証してからベアメタルに適用する」です。しかし、「いきなり VM ホストをいじりだす」という悪夢を見た以上、VM への施工も、まず VM を作り、次に OS 初期設定をひとつずつ進める形にしました。この段階的アプローチにより、実機適用時のリスクを下げることができました。
Ubuntu 24.04 Desktop (KubeVirt VM) での検証
最初の検証対象です。再始動直後は Ubuntu 26.04 がまだリリースされていないこともあり、Ubuntu 24.04 で VM を作成しました。これは後に Ubuntu 26.04 を同様に構築させることにより、VM とベアメタルの複数環境に加え、複数バージョンの OS にも柔軟に対応させることを狙っています。
Kubernetes と KubeVirt 環境に VM を作成する部分は、実装までにかなりの修正を行いました。詳細はここでは割愛しますが、そもそも Kubernetes と KubeVirt を用いた環境で VM を作成するという行為自体が、人間でも難易度が高い作業です。加えて、バックエンドストレージには Rook-Ceph (Kubernetes 上で分散ストレージ Ceph を運用する仕組み) を使用しています。このため、PV (PersistentVolume) と PVC (PersistentVolumeClaim) を経由しないと VM 用ストレージを作成できないという条件もありました。これらの機構をひとつひとつ解析させ、どのようにすれば VM を作れるのか、段階的に調整することで実装を行いました。
OS 初期設定は、参考にした構築手順書 (Markdown) の時点で各作業項目単位に章立てされていることもあり、ワークフローの段階で手順が分割できていました。このため、段階毎にひとつずつ仕様を詳細化→実装→動作検証のサイクルを繰り返し、全作業項目を実装しました。
Ubuntu 26.04 Desktop (KubeVirt VM) での検証
Ubuntu 24.04 の検証の終わり際にリリースされたため、通して全項目を再確認する意味も込めて検証しました。
Ubuntu 26.04 は 24.04 からの変更点が多く1、10 件の非互換性を発見し対処しましたが、比較的スムーズに検証を完了しています。
ベアメタルサーバへの実機適用
VM 検証を経て、本番のベアメタルサーバに適用しました。
OS インストールは、先に検証で構築した Ubuntu 26.04 上に PXE サーバを構築し、PXE サーバ経由でベアメタルサーバにインストールしています。
VM 構築部分はスキップし、OS 初期設定からきちんと作業を開始することができています。ベアメタル固有の問題も発見しましたが、(Claude Code が) 調査し、数時間で問題なく構築を完了しています。
6. まとめ
構築したベアメタルサーバは、すぐに実運用に投入されました。一度環境を破壊しかけましたが、長い期間塩漬けとなっていた案件を片づけることができました。
本プロジェクトを振り返り、3 つのポイントをまとめます。
AI ツールが解決したのは「工数不足」と「コンテキスト管理」
1000 行程度の構築手順書による手作業を、Ansible コードとして自動化できました。
AI ツールの効果は「コードを速く書ける」だけではありません。手順書に含まれる設定の依存関係、実行順序、OS バージョンによる差異といった大量のコンテキストを保持しながら、整合性のある実装を進められた点が重要です。この大量のコンテキストの保持については、第 5 回 (メモリシステム) で掘り下げてお話しします。
環境を破壊しかけるという失敗から学んだポイント
AI ツールに指示をする際、「何に対して作業するか」をワークフローとして明確にする必要があります2。
環境を破壊しかけた失敗は、筆者側の要件や操作対象の指定が不足していたことに加え、AI 側でも操作対象を十分に確認しないまま処理を進めたことが重なって起きたと考えられます。
構築対象が VM かベアメタルかでワークフローが分岐すること、各スキルの接続先と操作範囲を明示すること。あわせて、作業前に接続先 (ssh 接続情報や VM の作成状況) を確認する手順をワークフローに組み込みました。これらを要件定義書とスキル定義に落とし込んだことで、再始動後は安全に実装を進められました。
段階的確認
各作業をワークフローの段階で明確に分割し、段階的に詳細化→実装→動作検証をすることで、途中で発生した不具合や事故の影響を抑えやすくなります。AI ツール側のコンテキスト長を考慮しても、段階を区切った方が、精度よく動作すると考えられます2。
何より全仕様を完全に詳細化し、内容を確認することは、確認する側の負担が大きくなります。その結果、確認の抜け漏れが生じます。
7. 後続記事について
本記事では全体のストーリーを駆け足で紹介しました。後続の記事では、個別のテーマを掘り下げます。
| 回 | テーマ | 内容 |
|---|---|---|
| 第 2 回 | Claude Code への「指示の技術」 | 効果的な指示のパターンについて |
| 第 3 回 | エージェントに「目と手」を与える | 画面を見て操作する能力を与える |
| 第 4 回 | トラブルシュートへの応用 | ネットワークブートや RDP 接続などの障害解析事例 |
| 第 5 回 | メモリシステム | 長期プロジェクトのコンテキスト維持戦略 |
| 第 6 回 | 環境移行 | セッション・メモリの引っ越し |
| 第 7 回 | 外部ツール併用 | Claude Code と外部ツールの併用戦略 |
| 第 8 回 | 効果 | Claude Code を環境構築作業へ適用した効果 |
次回の第 2 回では、Claude Code への「指示の技術」を取り上げます。環境を破壊しかけた「丸投げ」方式と、再始動後に成功した「要件定義書 + 段階的指示」方式の違いを、実際のプロンプト例を交えて深掘りします。
本記事の内容は筆者個人の見解であり、所属組織の公式見解ではありません。
本記事の執筆には生成 AI を利用し、最終的な記述および内容の確認は筆者が行っています。
記載されている会社名、製品名、サービス名は、各社の商標または登録商標です。
-
Ubuntu 26.04 LTS は 2026 年 4 月 23 日のリリースです。24.04 LTS から上げる場合の主な変更点は、LTS 利用者向けのサマリーにまとまっています。出典：Canonical「Ubuntu 26.04 LTS release notes」
https://documentation.ubuntu.com/release-notes/26.04/、Canonical「Ubuntu 26.04 LTS summary」https://documentation.ubuntu.com/release-notes/26.04/summary-for-lts-users/(参照日：2026 年 10 月 26日) ↩ ↩2 -
Anthropic「Best practices for Claude Code」
https://code.claude.com/docs/en/best-practices(参照日：2026 年 10 月 26日) には、次の内容があります（筆者による要約）。コンテキストウィンドウはすぐに埋まり、埋まるほど性能が落ちる／「まず調べ、次に計画し、それから実装する」／プロンプトに具体的なコンテキストを与える／早めにこまめに軌道修正する。 ↩ ↩2