はじめに
最近、社内でClaude Codeを使ったIaCコード(CloudFormation/Ansibleなど)を標準化する取り組みを進めています。
以前は各案件の担当者が任意のコーディングエージェントを使ってコードを書いていました。ただ、正直なところトークン効率が非常に悪く、似たようなリソースを毎回ゼロから生成しているような状態でした。また、利用者の技術的な経験値によって保守のしやすさがまちまちとなり、このまま行くと将来的に苦労する人が出てくる可能性が高い状況になっていました。そこで、一定以上の知見を持った人によるコードの標準化を行うという取り組みを開始しました。
この記事では、その取り組みの中身と狙い、そして「コードを渡すだけで終わらないための工夫」について書いていきます。
なお、実際のテンプレートやCLAUDE.md、Skillsの詳細は社内の設計方針を含むため、本記事では具体的な中身は記載しておりませんのでご容赦ください。
想定読者
- Claude Codeなどの生成AIをIaCに活用したい、または活用し始めている方
- 複数案件を抱えるチームで、IaCの標準化や効率化を検討している方
この記事でわかること
- 案件ごとにバラバラだったIaCコード生成を一括化しようとしている背景と理由
- 標準化できる部分とできない部分の切り分け方
- Claude Codeの具体的な活用方法と設定の統一
- コードを渡すだけで終わらせないための教育コンテンツの考え方
この取り組みの背景と狙い
手動構築の撲滅
そもそもの出発点は手動構築で対応している案件を減らしたいというところにあります。
マネジメントコンソールからポチポチ作っていく構築方法は、環境の再現性がなく、手順書のメンテナンスも大変です。オペミスのリスクも高くなります。これは今さら言うまでもない話です。お恥ずかしい話ですが、自社の案件であっても今現在AIはおろかIaCすら取り入れていない案件というのも存在しています。
ただ、「IaCでやりましょう」と言うだけでは現場は変わりません。CloudFormationやAnsibleを書ける人が限られている状況で「自分で書いてね」と丸投げすると、結局「手動のほうが早い・慣れているから」という判断になりがちです。
コードを書くハードル自体をClaude Codeで下げつつ、さらに標準化されたテンプレートを用意することで「手動でやる理由」を完全になくすのが狙いです。
本当に時間をかけるべきところに集中する
IaCコードを書く時間を削減することで、担当者には以下のような「本当に時間をかけるべき領域」に注力してほしいと考えています。
※構築工程が無駄と言いたいわけではありません。筆者本人も構築工程は好きですし、コーディングも好きな方です。ただ、Claude CodeのようなAIを活用することで定型的なコード作成を効率化できるようになった以上、人間は設計判断やレビュー、要件整理といった領域により多くの時間を使うべきだと考えています。
| 領域 | 内容 | なぜ時間をかけるべきか |
|---|---|---|
| 設計 | アーキテクチャの選定、非機能要件の実現性検討 | ここの判断を間違えると後工程すべてに影響する |
| 要件定義 | 顧客の業務要件、非機能要件の整理 | 曖昧な要件のまま構築に入ると手戻りが発生する |
| 性能検証 | 負荷テスト、チューニング | 本番稼働後に問題が発覚すると影響が大きい |
コードを書くこと自体は重要ですが、これらの領域と比較すると「同じようなVPCテンプレートを毎回ゼロから書く」ことに時間を使うのはもったいないです。
コードを書く部分を効率化して、設計の質を上げるための時間を確保する。これがこの取り組みの最終的な狙いです。
また、設計における勘所(何を意識するのか、特定の領域だけ過剰になっていないかなど)を早い段階で身につけて欲しいという狙いもあります。
なぜ「一括生成」に切り替えたのか
各案件でバラバラに生成していた時の問題
各担当者が独自にClaude Codeでコードを生成していると、以下のような問題が起きていました。
- トークン効率が悪い: 似たような構成のVPCやセキュリティグループを毎回ゼロから生成させている。案件Aで作ったものとほぼ同じものを案件Bでもイチから作っていた
- 品質のばらつき: 担当者によってコードの書き方、命名規則、分割単位がバラバラ。レビューする側もその都度違うスタイルに対応しないといけない
- ナレッジが蓄積されない: 各案件で閉じてしまうので、ある案件で得た知見が他の案件に展開されない
特にトークン効率の話はバカになりません。6人のチームで全員がそれぞれ別の案件でClaude Codeを回してVPCテンプレートを書かせていたら、単純に6倍のトークンを消費しているわけです。しかも出てくるものは大体同じようなコードです。
一括生成の体制
そこで、IaCコードの生成は「わかっている人・経験値ある程度ある人が一括して作る」という体制に切り替えました。
具体的には、CloudFormation/Ansibleの経験があるメンバーが各案件分のコードをまとめて作成し、担当者はそれを利用する形です。全部を毎回書き起こすのではなく、一度作ったものをベースに案件固有の部分だけを調整していきます。
この体制のメリットは以下の通りです。
| 観点 | 以前(各担当者が個別生成) | 現在(一括生成) |
|---|---|---|
| トークン消費 | 案件数×担当者数分 | 共通部分は1回で済む |
| コード品質 | 担当者のスキルに依存 | 経験者が統一した基準で作成 |
| レビュー負荷 | スタイルがバラバラで都度確認 | 統一されているので差分だけ見ればいい |
| ナレッジ蓄積 | 各案件で閉じる | 共通コードに改善が蓄積される |
標準化の考え方
標準化できる部分
IaCコードの中には、案件が変わってもほぼ同じ内容になる部分があります。これを「標準化できる部分」として切り出し、使い回せるようにしています。
CloudFormationの場合
- VPC、サブネット、インターネットゲートウェイなどのネットワーク基盤
- セキュリティグループの基本構成(SSH踏み台、ALB、RDSなど定番パターン)
- CloudWatch Alarmの基本セット(CPU、メモリ、ディスクなど) ※メモリ、ディスクはCloudWatch Agentによるカスタムメトリクスの送信が前提
- IAMロール・ポリシーの基本パターン(ECSタスク実行ロール、EC2インスタンスプロファイルなど)
Ansibleの場合
- OS初期設定(タイムゾーン、NTP、ロケールなど)
- ミドルウェアのインストール・初期設定(Apache、Nginxなど)
- ログ転送設定(CloudWatch Agentなど)
- セキュリティ設定(SSHの設定、ファイアウォール設定など)
これらは案件ごとにパラメータ(CIDR、インスタンスタイプ、環境名など)が異なるだけで、構造自体はほぼ同じです。パラメータ部分だけを変数化しておけば、新しい案件でもパラメータを埋めるだけで使えるようになります。
標準化できない部分
一方で、案件固有の要件に依存する部分は標準化が難しいです。
- 顧客固有のネットワーク要件: オンプレミスとのVPN接続構成、Transit Gatewayの接続先など
- アプリケーション固有の設定: ECSのタスク定義(コンテナイメージ、環境変数、ポートマッピングなど)
- セキュリティ要件: WAFのルールセット、NACLの細かい制御など
これらは案件ごとに要件をヒアリングした上で個別に作成する必要があります。ここをムリに標準化しようとすると、Conditionsだらけのテンプレートになってしまい、かえって読めないコードが出来上がります。
ディレクトリ構成のイメージ
標準化できる部分とできない部分を分離するために、以下のようなディレクトリ構成で管理しています。
# CloudFormation用リポジトリ ※イメージです。
cfn-templates/
├── standard/ # 標準化された共通テンプレート
│ ├── network/
│ │ ├── vpc.yaml
│ │ ├── subnet.yaml
│ │ └── security-group.yaml
│ ├── compute/
│ │ ├── ecs-cluster.yaml
│ │ └── ecs-service.yaml
│ ├── database/
│ │ └── rds.yaml
│ └── monitoring/
│ ├── ecs-alarms.yaml
│ └── rds-alarms.yaml
├── project-specific/ # 案件固有のテンプレート
│ ├── project-a/
│ │ ├── vpn-connection.yaml
│ │ └── waf-rules.yaml
│ └── project-b/
│ └── custom-scaling.yaml
└── docs/ # 設計の考え方・学習コンテンツ
├── design-principles.md
├── cfn-stack-splitting.md
└── naming-conventions.md
# Ansible用リポジトリ ※イメージです。
ansible-templates/
├── standard/ # 標準化された共通Playbook
│ ├── os-setup/
│ ├── middleware/
│ └── security/
├── project-specific/ # 案件固有のPlaybook
│ ├── project-a/
│ └── project-b/
└── docs/
└── playbook-guide.md
IaCの種類ごとにリポジトリを分けています。CloudFormationとAnsibleでは扱うレイヤーも変更頻度も異なるため、同じリポジトリに混ぜるよりも管理しやすくなります。
各リポジトリ内のstandard/配下は案件をまたいで使い回すものなので、変更する際は影響範囲を考慮して慎重に行います。逆にproject-specific/配下は案件ごとに自由に作成・変更して問題ありません。
標準テンプレートの品質担保
標準テンプレートは複数案件で使い回すものなので、品質の担保は特に重要です。壊れたテンプレートがそのまま展開されると、複数案件に同時に影響が出てしまいます。
そのため、standard/配下のテンプレートは以下のプロセスを経てから配置するようにしています。
- Linterによる静的チェック: CloudFormationであればcfn-lint、AnsibleであればAnsible Lintを通して、構文エラーやベストプラクティスからの逸脱を事前に検出する
- 検証環境での動作確認: Linterを通しただけでは実際にデプロイできるかはわからないので、検証環境で実際にスタックを作成・更新して動作確認を行う
Linterで構文レベルの問題を潰し、検証環境で実際の動作を確認する。この2段階を踏んでからstandard/に配置するというルールにしています。Claude Codeが生成したコードをそのまま標準テンプレートとして配置することはありません。
地味なプロセスですが、ここを省略すると「標準テンプレートを使ったのにデプロイでコケた」という状況が発生して、標準化への信頼が一気に崩れます。使う側に「このテンプレートは動く」と安心して使ってもらうためにも、この手間は惜しまないようにしています。
Claude Codeの活用方法
コード作成とコンテンツ作成
この取り組みではClaude Codeを主に2つの用途で活用しています。
1つ目はIaCコードの作成です。標準テンプレートの新規作成や、案件固有部分のカスタマイズにClaude Codeを使っています。一度作ったテンプレートをベースに「この案件ではNAT Gatewayを2つにしたい」「RDSのパラメータグループにこの設定を追加したい」といった差分をClaude Codeに指示して反映させる、という使い方です。
2つ目は設計に関するコンテンツの作成です。後述する社内GitHubの学習コンテンツ(設計ガイド、トラブルシューティングなど)もClaude Codeを使って作成しています。設計の考え方や判断基準を言語化する作業は地味に時間がかかるので、ここをClaude Codeで効率化できるのはありがたいです。
設定の統一
Claude Codeを複数人で使う場合に問題になるのが「人によって設定がバラバラ」という点です。同じClaude Codeを使っていても、CLAUDE.mdの内容が違えば出力も変わります。
そこで、各リポジトリにCLAUDE.mdやSkillsをあらかじめ用意し、さらに利用すべきMCPサーバも記載しておくことで、自分と同じ設定がすぐに使えるようにしています。
cfn-templates/
├── CLAUDE.md # プロジェクト共通の指示
├── .claude/
│ └── skills/
│ ├── create-template/
│ │ └── SKILL.md # テンプレート生成用Skill
│ ├── review-template/
│ │ └── SKILL.md # テンプレートレビュー用Skill
│ └── customize-for-project/
│ └── SKILL.md # 案件向けカスタマイズ用Skill
├── standard/
│ ...
CLAUDE.mdにはテンプレートの命名規則、スタック分割の方針、コーディング規約などを記載しています。Skillsには「テンプレートを生成する」「テンプレートをレビューする」「案件向けにカスタマイズする」といったタスクごとのプロンプトを定義しておき、担当者はスラッシュコマンドを叩くだけで統一された品質のコードが生成されるようにしています。
MCPサーバについても、社内で利用すべきサーバの情報をドキュメントに記載しておくことで、各担当者が自分で調べて設定する手間を省いています。
この仕組みのおかげで、新しくClaude Codeを使い始めるメンバーでもリポジトリをクローンした時点で同じ環境が手に入ります。「Claude Codeの使い方がわからない」という導入時のハードルを大幅に下げることができました。
これは普段案件業務をこなしながら、生成AIの情報までキャッチアップするのが辛いという要望から生まれた取り組みです。
コードを渡すだけで終わらせないための工夫
「流すだけ」問題
ここまでの話だけ聞くと「IaCコードを一括で作って渡すだけでしょ?」と思われるかもしれません。確かに効率化という意味ではそれで目的は達成できます。
ただ、それだけだと各案件の担当者はコードを流すだけの人になってしまいます。
以下のような設計思想を理解しないまま、渡されたコードをデプロイして終わりという状態は避けたいわけです。
- VPCのCIDRはなぜこの設計にしたのか
- セキュリティグループのルールはどういう考え方で設計されているのか
- 監視の閾値はどういう基準で決めたのか
これは長い目で見ると非常にまずいです。担当者自身の成長が止まるのはもちろん、いざトラブルが起きたときに「なぜこの構成になっているのか」を説明できない人間が運用しているという状態になってしまいます。
社内GitHubに設計学習コンテンツを配置
そこで、IaCコードと合わせて設計の考え方を学べるコンテンツを社内のGitHubリポジトリに配置しています。
具体的にはこんな内容です。
設計判断の「なぜ」を説明するドキュメント
- なぜスタックをこの単位で分割しているのか
- なぜこの命名規則を採用しているのか
- なぜExport/ImportValueではなくスタックパラメータで渡す方式にしているのか
- なぜConditionsを使わない方針にしているのか
構成パターンごとの設計ガイド
- ALB + ECS + RDS構成の場合の設計ポイント
- マルチアカウント構成での注意点
- DR構成を考慮する場合の追加設計
よくある質問・トラブルシューティング
- スタック更新時にリソースが置換される条件
- Export/ImportValueで変更がブロックされた場合の対処法
- Change Setで予期しない変更が表示された場合の確認手順
コードだけを渡すのではなく「なぜこのコードがこうなっているのか」を理解するための資料をセットで提供することで、担当者が設計の考え方ごと吸収できるようにしています。
正直なところ、このコンテンツを作る工数は結構かかっています。ただ、同じことを何度も口頭で説明する手間を考えると、一度ドキュメントに起こしておいたほうが長い目で見て効率的です。「これ読んでから質問してね」と言えるようにしておくのは大事だと思っています。
やってみての変化
この取り組みはまだ始めたばかりで、手動構築の案件が減ったかどうかはこれからの話です。ただ、すでに実感している変化としてレビューがかなり楽になったというのがあります。
以前はコードの書き方や命名規則、分割単位についてあれこれ指摘する必要がありましたが、標準テンプレートを使う形にしたことでその手の指摘はほぼなくなりました。レビューの焦点がコードの細かい書きぶりからアーキテクチャの妥当性に移ったことで、本来時間をかけるべきところに集中できるようになっています。
現時点ではまだ自分の担当案件で試している段階なので、他の担当者からのフィードバックはこれからです。今後チームに展開していく中で出てくる声も踏まえて、仕組み自体をブラッシュアップしていく予定です。
現時点での課題
課題もあります。
一括生成する側の負荷が高い・人が足りない
当然ですが、複数案件分のコードを一括で作成する側の負荷は高いです。案件ごとの要件差異を理解した上でテンプレートを調整する必要があるので、IaCと各案件のアーキテクチャ両方の知識が求められます。
リアルな話をすると、現状CloudFormationのリポジトリをメンテナンスできる人間は2人しかいません。この2人で普段の案件業務をこなしながら複数案件分の標準テンプレートの作成・更新・レビューを回しているので、正直なところかなりカツカツです。
「一括生成で効率化した」とは言いつつも、その効率化の恩恵を支えている側の人数が圧倒的に少ないという構造的な問題があります。どちらかが別案件にアサインされたり、長期休暇を取ったりしたら回らなくなるリスクは常にあります。
ここは本当に危機感を持っていて、CloudFormationをちゃんと書ける・レビューもできる判断できる人間を増やしていかないとこの仕組み自体が破綻します。前述の教育コンテンツも、単に「担当者が流すだけにならないように」という目的だけでなく、将来的にリポジトリのメンテナンス側に回れる人材を育てるという意味合いも含んでいます。
標準テンプレートのメンテナンス
AWSのサービスは頻繁にアップデートされるため、標準テンプレートも定期的に見直す必要があります。新しいベストプラクティスが出たら反映する、非推奨になった設定を修正するなど、テンプレート自体の保守コストは継続的に発生します。
教育コンテンツの鮮度維持
設計ガイドやトラブルシューティングの内容も、サービスのアップデートに合わせて更新する必要があります。古い情報が残ったままだとかえって混乱を招くため、定期的な棚卸しが必要です。
「読む動機」を作る仕組みが足りない
コンテンツを置いただけで全員が読んでくれるかというとそんなことはなく、ここは正直まだ模索中です。環境は準備したんだから、あとは本人次第でしょという意見もあるとは思いますが、最低限の努力は続けていこうと考えています。
まとめ
この記事で紹介した取り組みのポイントを整理します。
- 案件ごとにバラバラだったIaCコード生成を、経験者が一括で作成する体制に切り替えた
- 標準化できる部分(ネットワーク、監視など)と案件固有の部分を明確に分離した
- Claude CodeのCLAUDE.md・Skills・MCPサーバの設定を統一し、誰でも同じ環境で使えるようにした
- コードだけでなく設計の「なぜ」を学べるコンテンツをセットで提供している
| 取り組み | 内容 | 狙い |
|---|---|---|
| IaCコードの一括生成 | 経験者が案件横断でコードを作成し、各担当者に展開 | トークン効率の改善、品質の統一 |
| 共通部分と固有部分の分離 | 標準化できるテンプレートと案件固有の部分を明確に切り分け | 使い回しの効率化、メンテナンス性の向上 |
| Claude Codeの設定統一 | CLAUDE.md・Skills・MCPサーバを事前に用意 | 導入ハードルの低下、出力品質の統一 |
| 設計学習コンテンツの整備 | コードの「なぜ」を説明するドキュメントを社内GitHubに配置 | 担当者の成長、「流すだけ」の防止 |
生成AIの登場でコードを書くこと自体は楽になりました。だからこそ、コードを書く以外の部分にどれだけ時間を使えるかが、これからのインフラエンジニアにとって大事になってくるのかなと思っています。筆者自身も要件定義工程や設計に割く時間がかなり増えました。
まずは自チームで「標準化できる部分」と「案件固有の部分」を洗い出すところから始めてみてください。そこが整理できれば、一括生成や設定統一の仕組みは自然と見えてくるはずです。
この取り組みはまだ道半ばですが、同じような課題を持っている方の参考になれば幸いです。