Terraform リポジトリを読ませて、環境把握用 HTML ページを作成してくれる Claude スキルを作って検証してみた
こんにちは。
構成図なき道をゆく
運用イノベーション部のかわいです。
筆者は日々、お客様環境の運用面全般を広く見るような業務に携わっています。
社内外問わず、一般的に環境把握には時間がかかります。
管理しているのは人間なので、例えば構成図が古くなってしまっていたり、過去対応した担当者が既に退職していたりと、現状把握が難しいケースも往々にして発生します。
環境をコード管理できている場合、コードを読むことでも最新の状態を追うことは可能ですが、参照し合う関係性を読み解く必要などあるため、時間を要します。
今回、Terraform コードを読んで環境を把握する作業を Claude Code の Agent Skills を作って検証してみました。リポジトリを渡すと、初見の人でも読めば環境の概要が分かるHTML ページを生成してくれるシンプルな内容で、おまけとして、AWs Well-Architected Framework をベースに、環境内で改善すべき点を検出してもらえるようにしました。
本記事では、サンプルリポジトリを作成し、スキルを使ってみた流れを紹介します。
（※今回スキル本体は検証段階ということもあり共有していません。検証過程と考え方の紹介のみになります）
検証環境
以下のように、架空の企業のサンプルリポジトリを用意しました。
| 項目 | 内容 |
|---|---|
| 検証対象 | 架空の EC サイト運営企業を想定したサンプル Terraform リポジトリ |
| 規模 | 8 ルートモジュール、.tf ファイル 49 件 |
| 実行環境 | Claude Code（Agent Skills 機能） |
このリポジトリは検証のために自分で用意したもので、実在する顧客環境の情報は含んでいません。また、意図的に運用現場でありがちな問題を 14 箇所仕込んであります。
事前準備
スキル本体は以下の構成。
iac-map/
├── SKILL.md # 本体
├── assets/ # AWS 公式のサービスアイコン集（社内利用のみ）
├── checklist/
│ └── findings_checklist.md # 見直し箇所のチェックリスト
└── templates/
└── map_template.html # HTMLのベース
~/.claude/skills/iac-map/ に配置しておけば、Claude Code から自然言語で「iac-map スキルを使って、このリポジトリの環境マップを生成して」と指示するだけで動きます。
検証
おおまかな流れ
SKILL.md には、大きく分けて以下の手順を書きました。
- チェック —
.tfファイルをすべて洗い出し、リソースをレイヤ別（IAM/ネットワーク/コンピュート/CICD 等）に分類する - 解析 — レイヤごとに何のための構成か？を言語化する。リソース名の参照関係を辿って、パイプラインからデプロイ先までの一連の流れを組み立てる
- 所見の検出 — チェックリストと照合し、環境内の見直し候補を洗い出す
- チェックリスト再照合 — 手順3とは独立させ、チェックリストの全項目を機械的に見直す
- 生成 — HTML を出力する
- 自己検証 — 出力前に整合性を確認する
強いて工夫した点を挙げるとすれば、手順3と4を分けたところです。
読みながら並行して気づいた点を拾っていく作業と、チェックリストをもとに考慮漏れを確認する作業は視点が違うので、1回で済ませようとすると見落としが発生する可能性を考慮しました。
実際、初期に作ったバージョンでは本文の説明文中で問題点として書いた箇所が、検出結果の一覧表に反映されていない、という漏れが発生していました。
ダブルチェックについて
手順4のチェックリスト照合後に 生成されたHTMLページとの整合性が取れない問題が発生しました。
この対策として、HTML 生成の直前にもう一度、本文と検出結果のリストを突き合わせる工程を手順6に追加しました。
生成直後の本文を読み直し、問題点として書いた箇所がリスト上に載っているかを再度チェック工程を追加することで、生成物のクオリティが向上しました。
（あくまでも所感レビューではなく、精確にページへ反映できるか？のチェック）
検証結果
この環境では10分以内で生成まで完了しました。
途中でコンパクトを挟んだので、これより小規模な環境では5分前後で完了可能と思います。
生成環境後、HTMLページのオーバービューに全体のアーキテクチャが表示されました。
まだまだ見づらさがある点は改善予定ですが、大まかな繋がりが把握できます。
ダッシュボードにはタブを配置しており、検出した所感やネットワークなど、カテゴリ別に環境の概要が確認できます。
例えばネットワークでは、Security Gateway や 利用者からの接続経路などが確認できます。ここでは、リスクの高いルールが表示されていました。
（SSHポートに対して全許可）
findings ページでは、前述の点を含む、リスクの高い要因がリストとして確認できます。
チェックリストに基づき、重要度順に提示されます。
まとめ的な
一般的なケースとして、環境把握用のドキュメントがない場合、環境のリポジトリを読み解く作業を Agent Skills に任せてみた話でした。まだまだ改善が必要で全部鵜呑みにすると危険ですが、概要把握ができる点や、リスクになりえる部分を検出できた点が検証できてよかったと思います。
完
