Tech Memo

はじめに

この技術メモは、GitHub Pagesで独自ドメインを設定し、HugoとGoogle Cloud Storage（GCS）を利用して構築しています。記事のビルドとデプロイはGitHub Actionsで自動化しており、ようやく「記事を書く」という本来の運用フェーズに乗ってきました。
運用の土台が整った今、私がまず最初に取り組んだのは、管理リポジトリにおける「構成図の自動生成」の仕組み化です。なぜ、たかが個人のブログ管理にそこまでこだわるのか。それは、現職でSREとして格闘する中で「構成図という名の海図」の絶対的な価値を痛感しているからです。

そして何より、ドキュメントという名の技術的負債は「後から一括返済しようとしても不可能に近い」という恐ろしさを知っているからです。今回は、構成図に対する私の考えと、AIを活用した「海図の自動化」について、一つの「Note」として書き残しておきます。

構成図を残す意義について

構成図がないということは「地図のない船」である

エンジニアにとって、構成図がない状態でのシステムのキャッチアップは「暗闇の中の航海」に他なりません。私自身の経験をお話しすると、過去に入社した現場に図が一枚もなかったとき、圧倒的なキャッチアップの遅れと認知負荷（Cognitive Load）の増大を経験しました。
AWSやGCPのコンソールを一つずつ辿り、サービス同士の繋がりをパズルのように解き明かす作業は困難を極めました。特にネットワーク（VPCやSubnet、Peering）は、目に見えない「潮流」のようなものであり、自分の推測が正しいかどうかもわからないまま全容を把握するには、多大なエネルギーを要しました。
AIがコードを書いてくれる時代であっても、「AIに聞く前にまず自分で考える」ためには、最低限の地図が必要です。地図のない船では、目的地（ゴールにたどり着く前に、現状把握のフェーズで遭難しかねません。

なぜ構成図がないと「詰む」のか

• 障害時の「遭難」: トラブルが起きたとき、影響範囲を誰も即答できず無駄な調査に時間を奪われます。暗闇の中で手探りでスイッチを探すような恐怖と焦燥感は、SREの精神とエラーバジェットを容赦なく削り取ります。
• Dev/Opsの「見えない壁」: 共通の地図がないことは、開発（Dev）と運用（Ops）の間に致命的な分断を生み出します。Devが作ったものをOpsが手探りで運用する状態では「同じ船に乗っているのに、見ている海域が違う」という悲劇が起きます。共通の海図があって初めて、両者は同じ目的のもとに協調できるのです。
• 未来の仲間への「招待状」の欠如: 採用やカジュアル面談で、インフラの規模やトラフィックの導線が見えない現場に誰がワクワクするでしょうか？「我々は今、どんな海を渡っているのか」を可視化する構成図は、未来のチームメンバーへの最高の招待状になります。
• トイルと心理的負債: 誰も全容を知らないシステムは、いつしか誰も触りたくない「暗礁（呪われた領域）」に変わります。これは変更の心理的ハードルを上げ、チームのベロシティを著しく低下させます。

0から海図を描く「苦行」

既存のシステムを解読し、後から構成図を描き起こす（リバースエンジニアリングする）作業は、もはやエンジニアリングではなく、遺物から過去の意図を推測する「考古学」に近い苦行になります。
私も過去、把握した範囲から少しずつ手書きで図を起こしてきましたが、そこには常に「本当にこれで正しいのか？」という孤独な葛藤や不安がありました。誰も正解を知らない以上、自分が描いた「暫定的な地図」がチームの「唯一の真実（Single Source of Truth）」になってしまう責任の重さ。そこには常に、手書きの図が描いたそばから現実（コード）と乖離（ドリフト）していく虚しさがありました。

コラム：過去の敗北 ―― 巨大なtfstateと「後出し」の限界

過去に、運用されているシステムでTerraformの定義（tfstate）から直接、構成図を自動生成しようと試み、見事に失敗した経験があります。
原因は、tfstateの肥大化と複雑な構成もありましたが、最大の敗因は「ある程度育ってしまったシステムに対して、後から機械的な自動化を適用しようとしたこと」でした。機械的な自動生成（terraform graph など）は、抽象化のレベルを考慮せず、蓄積されたすべてのリソースを等しく描画してしまいます。

結果としてツール側でも処理を捌ききれず、永遠に実行が続いて図が出力すらされませんでした。「0から巨大な地図を作る」という試みは、ノイズという情報の洪水に飲み込まれて遭難するという結末を迎えました。構成図の自動化は、システムが小さくシンプルなうちから積み重ねていかなければ、真の価値を発揮できないのです。

「今」からAIに海図を描かせる

過去の敗北から学んだ教訓はシンプルです。「システムが小さく、アーキテクチャの意図が明快なうちから、継続的な更新の仕組みを組み込むこと」。

今回構成図を作るにあたり、ただの機械的な描画ではなく、AI（LLM）という「解釈者」をソナー（探信儀）として採用しました。

実装のヒント：Diagrams as Code による抽象化

手作業での描画はもちろん、ツールによる機械的な全リソースの転記も避けました。代わりに採用したのが、Pythonライブラリを用いた 「Diagrams as Code (DaC)」 です。

AIに「SREとしての意図」を汲み取らせ、人間が理解しやすい適切な抽象度でコードを生成させることで、メンテナンス性を確保しつつ、公式アイコンを用いた高品質な図を維持しています。

• エンジン: diagrams (Python)
• 環境管理: uv
• AI（ソナー）への命令: 「熟練 SRE として、現在のソースコード（Hugo 設定、GitHub Actions、GCP リソース）からエッセンスを抽出し、diagrams ライブラリのコードを生成・更新せよ」とプロンプトを固定。
• 仕組み化: GitHub Actionsで記事デプロイ時にこのコードを実行し、常に最新の「海図」を自動出力。

実際に生成された海図（構成図）

以下が、実際に AI が生成したコードから出力された構成図です。

アーキテクト図

ここまでのベース（土台）が自動でできあがっていれば、あとはAIに任せきりにせず、人間（SRE）が必要な微修正を加えるだけで済みます。このように「コード」として管理することで、システムの変更に合わせて海図を調整し続けることができます。運用負荷を一定に保ちながら（Toilの削減）、現実との乖離を防ぐ。これが、後からの「苦行」を避ける最適解だと確信しています。

システムという「生物」の脈動を記録する

システムは一度構築して完成する「静的な建造物」ではありません。日々新しいコードがデプロイされ、トラフィックが変動し、姿形を変え続ける「生物（いきもの）」です。

だからこそ、構成図は「気が向いた時に1から描き直す静物画」であってはならないのです。システムの成長という脈動に合わせて、継続的に、そして自動的に更新され続ける「生きた海図」でなければ、すぐに現実と乖離して腐敗してしまいます。Diagrams as CodeとAIの組み合わせは、この生物の変化に追従するためのアプローチなのです。

まとめ

構成図を「残す」ことはやることに意義があります。構成図を自動化して残すことは、未来の自分たちへの投資であり、システムを安定稼働させるための礎です。

システムが巨大化してから「さあ図を作ろう」と思っても、そこには膨れ上がった負債が待っているだけです。最初から完璧な海図である必要はありません。AIという強力な相棒と共に、「今、この瞬間」のシステムの姿を少しずつ記録していくこと。

その絶え間ない積み重ねこそが、SREとして「地図なき海」を「安全に航海できる自分の庭」に変えていく、唯一にして確実な航海術なのです。