Claude Code + Terraformでインフラ構築を進めるための準備をしてみた

概要

この記事はClaude Code + Terraformでインフラ構築を進めるための準備を実施した際の備忘録になります。

目次

• やったこと
• 手順
• まとめ
• 参考

やったこと

1. .mcp.jsonを用意する
2. CLAUDE.mdを用意する

手順

具体的な手順をステップバイステップで説明します。

ステップ1: .mcp.jsonを用意する

.mcp.jsonをプロジェクト配下に用意します。
Terraformでインフラ構築を進める上で使用したいMCPサーバーは以下2つになります。

MCPサーバー	説明
terraform-registry	Terraform Registry検索、モジュール詳細取得、プロバイダー情報取得
aws-knowledge	AWS公式ドキュメント検索・取得、サービス推奨情報
drawio	AWSアーキテクチャ図やインフラ構成図の自動生成・更新

3つのMCPサーバーを使用するために以下のように定義します。

{
  "mcpServers": {
    "terraform-registry": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AWS_PROFILE=default",
        "-e",
        "AWS_REGION=ap-northeast-1",
        "-e",
        "FASTMCP_LOG_LEVEL=ERROR",
        "hashicorp/terraform-mcp-server:latest"
      ],
      "description": "HashiCorp Terraform MCP Server latest"
    },
    "aws-knowledge": {
      "command": "/usr/local/bin/uvx",
      "args": [
        "fastmcp",
        "run",
        "https://knowledge-mcp.global.api.aws"
      ],
      "description": "AWS Knowledge MCP Server - 公式ドキュメント"
    },
    "drawio": {
      "command": "npx",
      "args": [
        "@drawio/mcp"
      ]
    }
  }
}

ステップ2: CLAUDE.mdを用意する

CLAUDE.mdをプロジェクト配下に用意します。

今回はClaude CodeがTerraformリポジトリで作業する際のルールブックとして活用したいので、以下4点について細かく指示を定義しています。

• プロジェクトの概要を説明する
• 作業を実施する際にMCPサーバーを使用するためのルールを定義
• Terraformの作業ルールを定義
• Claude Codeへの指示

# CLAUDE.md

## 言語の優先設定

**重要: このリポジトリで作業を行う際は、必ず日本語で応答してください。**
ユーザーとのやり取りは必ず日本語で行ってください。

## プロジェクト概要

このリポジトリはAWSリソースを管理するための Terraform インフラリポジトリです。
- クラウド: AWS
- IaCツール: Terraform
- AWSリージョン: ap-northeast-1（東京）
- Terraformのバージョン: 1.14.5
- **AWSプロファイル**: default（`provider "aws"` ブロックで `profile = "default"` を指定）

## 利用可能なMCPサーバー

このプロジェクトでは以下の3つのMCPサーバーが利用可能。
**コードを書く前に必ず以下2つのMCPツールで情報を取得すること。**
- terraform-registry
- aws-knowledge

**draw.ioで構成図を作成する際に必ず以下2のMCPサーバーを使用すること。**
- drawio
- aws-knowledge

### 1. `terraform-registry`（hashicorp/terraform-mcp-server）

HashiCorp公式のTerraformレジストリサーバー。

- `resolveProviderDocumentation`: プロバイダーのリソース・データソース仕様を取得
- `searchModules`: Terraform Registryのモジュールを検索
- `getModule`: モジュールの詳細情報・変数・サブモジュールを取得

**使いどころ**: `aws_*` リソースの正確な引数・ブロック構造の確認（ハルシネーション防止）

### 2. `aws-knowledge`（AWS Knowledge MCP Server）

AWS公式ドキュメント・ナレッジベースサーバー。

**使いどころ**: AWSサービスの仕様確認、Well-Architectedガイダンス、ベストプラクティスの調査

### 3. `drawio`（Draw.io MCP Server）

Draw.ioを使ったダイアグラム作成・編集サーバー。

**使いどころ**: AWSアーキテクチャ図やインフラ構成図の自動生成・更新（Terraformリソース構成の可視化）

## 作業フロー

### Terraformコード作成時のフロー

1. プロジェクト直下のdraw.ioファイルを読み込み、構成内容を把握
2. aws-knowledge でAWSサービスの要件・制約を確認
3. terraform-registry でリソース仕様（引数・型・必須項目）を取得
4. コードを作成
5. terraform init（プロバイダー・モジュール変更時）
6. terraform fmt → terraform validate
7. terraform plan → (承認後) terraform apply

### Draw.ioダイアグラム作成時のフロー

1. README.md を読み込み、構成内容を把握
2. README.md で不明・曖昧なサービス仕様は aws-knowledge で補完
3. drawio でダイアグラムを新規作成 or 既存ファイルを開く
4. AWSアイコン・コンポーネントを配置し、リソース間の接続・依存関係を図示
5. VPC・サブネット等のグルーピングを適用してスコープを明確化
6. ファイルをプロジェクト直下に保存（`.drawio` or `.xml`）

### エラー時の対処

- MCPツールが応答しない場合は、terraform-registry の代わりに公式ドキュメント (registry.terraform.io) を参照する
- terraform validate / plan が失敗した場合は apply を中止し、ユーザーに報告する

### NG行動（やってはいけないこと）

- **記憶だけでリソース引数を書かない** → 必ず `terraform-registry` で仕様を確認する
- **apply/destroyを無断実行しない** → 必ずユーザーの承認を得る

## Terraformの作業ルール

### 基本方針
- リソースはできる限り**モジュール化**する
- ハードコードは禁止。値は必ず `variables.tf` + `terraform.tfvars` で管理する
- `terraform plan` の出力を必ず確認してから `apply` する
- `terraform.tfvars` に機密情報を含む場合は `.gitignore` に追加すること
- モジュールの出力値は必ず `outputs.tf` に定義し、直接リソース参照を避ける

### ディレクトリ構成

作業対象はこのリポジトリの配下にある`terraform`ディレクトリになります。
ディレクトリ及びファイル作成は以下に**倣って**実施してください。

.
├── CLAUDE.md
├── README.md
└── terraform/
    ├── modules/
    │   └── <module_name>/
    │       ├── main.tf
    │       ├── variables.tf
    │       └── outputs.tf
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    └── terraform.tfvars

### 命名規則
- リソース名: `<環境>-<サービス名>-<リソース種別>`（例: `dev-app-ec2`）
- モジュール名: スネークケース（例: `vpc_module`）
- 変数名: スネークケース（例: `instance_type`）
- タグは必ず付与する（`Environment`, `Project`, `ManagedBy = "Terraform"` は必須）

### Stateファイル管理

- バックエンド: **ローカル**（デフォルト設定）
- stateファイルの保存場所: `terraform/terraform.tfstate`
- **`terraform.tfstate` および `terraform.tfstate.backup` は `.gitignore` に追加し、Gitで管理しない**
- stateファイルを直接編集しない（変更が必要な場合は `terraform state` コマンドを使用）

### .gitignore の必須設定

以下のファイルは必ず `.gitignore` に追加すること：

# State files
terraform/terraform.tfstate
terraform/terraform.tfstate.backup

# Variables（機密情報を含む場合）
terraform/terraform.tfvars

# その他
terraform/.terraform/
terraform/.terraform*

## Claude Codeへの指示

### やること
- コード作成後に `terraform fmt` でフォーマットを整え、`terraform validate` で構文チェックを行うこと
- 新しいリソースを追加する際は対応するモジュールが存在するか確認すること
- セキュリティグループは最小限のポートのみ開放すること
- `terraform plan` の出力を解析して変更点を要約して報告すること

### 禁止事項
- `terraform apply` を無断で実行しない（必ず確認を取る）
- `terraform destroy` は原則実行しない（ユーザーから明示的な指示がある場合のみ許可）
- AWSアクセスキーやシークレットをコードに直書きしない
- stateファイルを直接編集しない

まとめ

今回はClaude Code + Terraformで開発する上での前準備として、MCPサーバーの使用とCLAUDE.mdを定義を行いました。
これらの成果物をベースにAI駆動開発を円滑に実施できれば良いなと思います。

参考

https://zenn.dev/ukkyon/articles/claude-code-import-aws
https://zenn.dev/rasshii/articles/5fc85bcb270c0e