Claude Code × AWS CloudFormation/CDK 完全ガイド|インフラをコードで自動生成

「このAWS構成、手動でポチポチ作るの嫌だ」——こう思ったことは誰でもあるはずです。CloudFormation や CDK でインフラをコード化すれば再現性が上がりますが、テンプレートを書く時間がかかる。

私はこのサイト (claudecode-lab.com) のインフラ (Cloudflare Pages + Workers + D1) を Claude Code で管理していますが、AWS 側の業務インフラ設計でも CloudFormation / CDK の生成を Claude Code に任せています。手動で書いていた時の1/5の時間でテンプレートが完成するようになりました。

---

CloudFormation vs CDK どちらを選ぶか

CloudFormation: JSON/YAML でインフラを記述する AWS ネイティブのサービス
CDK (Cloud Development Kit): TypeScript/Python 等でインフラを記述し、
                              CloudFormation に変換するフレームワーク

比較軸	CloudFormation	CDK
言語	JSON / YAML	TypeScript, Python, Java 等
型安全性	なし	◎ (TypeScript なら完全型安全)
再利用性	低 (コピペ)	高 (クラス・関数で抽象化)
学習コスト	低	中
Claude Codeとの相性	◎	◎◎

新規プロジェクトなら CDK TypeScript が断然おすすめです。Claude Code との相性が抜群で、型補完と合わせて品質の高いコードが生成されます。

---

Step 1: 既存AWSリソースをCloudFormationでコード化

既存のAWS環境を後からコード化したいときに使えるパターン。

claude -p "
以下の AWS 構成を CloudFormation テンプレート (YAML) にして。

【現在の構成】
- VPC: 10.0.0.0/16、パブリックサブネット×2、プライベートサブネット×2
- EC2: t3.medium、Amazon Linux 2023、パブリックサブネットに配置
- RDS: MySQL 8.0、db.t3.micro、プライベートサブネットに配置
- ALB: HTTPS (ACM証明書)、EC2へのフォワード
- セキュリティグループ: ALBから443、EC2からRDS3306のみ許可

【要件】
- 環境 (dev/staging/prod) をパラメータで切り替え可能
- リソース名に環境名をプレフィックスとして付ける
- CloudFormation の Output に ALB の DNS 名を出力
"

生成される CloudFormation テンプレート (抜粋):

AWSTemplateFormatVersion: "2010-09-09"
Description: "Web Application Infrastructure"

Parameters:
  Environment:
    Type: String
    AllowedValues: [dev, staging, prod]
    Default: dev
  DBPassword:
    Type: String
    NoEcho: true  # パスワードはマスク

Resources:
  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/16
      EnableDnsHostnames: true
      Tags:
        - Key: Name
          Value: !Sub "${Environment}-vpc"

  PublicSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: 10.0.1.0/24
      AvailabilityZone: !Select [0, !GetAZs ""]
      MapPublicIpOnLaunch: true
      Tags:
        - Key: Name
          Value: !Sub "${Environment}-public-1"

  # ALBセキュリティグループ
  ALBSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: ALB Security Group
      VpcId: !Ref VPC
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 443
          ToPort: 443
          CidrIp: 0.0.0.0/0

Outputs:
  ALBDnsName:
    Value: !GetAtt ApplicationLoadBalancer.DNSName
    Export:
      Name: !Sub "${Environment}-alb-dns"

---

Step 2: CDKでサーバーレス構成を構築

CDK の場合は TypeScript で書けるので、ロジックの再利用が簡単です。

# CDKプロジェクトの初期化
mkdir my-infra && cd my-infra
npx cdk init app --language typescript

claude -p "
lib/my-infra-stack.ts に以下のサーバーレス構成を CDK TypeScript で実装して。

【構成】
- API Gateway (REST API) + Lambda (Node.js 20)
- DynamoDB テーブル (PAY_PER_REQUEST)
- S3 バケット (プライベート、バージョニング有効)
- CloudFront (S3オリジン、カスタムドメイン対応)
- Lambda の環境変数に DynamoDB テーブル名と S3 バケット名を渡す
- Lambda に最小権限の IAM ロールを自動付与

各リソースに適切なタグを付与し、
本番環境 (NODE_ENV=production) では削除保護を有効にすること。
"

生成されるCDKコード:

// lib/my-infra-stack.ts
import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigateway from "aws-cdk-lib/aws-apigateway";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as cloudfront from "aws-cdk-lib/aws-cloudfront";
import * as origins from "aws-cdk-lib/aws-cloudfront-origins";

export class MyInfraStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const isProd = process.env.NODE_ENV === "production";

    // DynamoDB テーブル
    const table = new dynamodb.Table(this, "AppTable", {
      partitionKey: { name: "PK", type: dynamodb.AttributeType.STRING },
      sortKey: { name: "SK", type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      pointInTimeRecovery: true,
      deletionProtection: isProd,
      removalPolicy: isProd ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
    });

    // S3 バケット
    const bucket = new s3.Bucket(this, "AssetsBucket", {
      versioned: true,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      encryption: s3.BucketEncryption.S3_MANAGED,
      deletionProtection: isProd,
      removalPolicy: isProd ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
    });

    // Lambda 関数
    const apiLambda = new lambda.Function(this, "ApiLambda", {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: "index.handler",
      code: lambda.Code.fromAsset("src/lambda"),
      environment: {
        TABLE_NAME: table.tableName,
        BUCKET_NAME: bucket.bucketName,
        NODE_ENV: process.env.NODE_ENV ?? "development",
      },
      timeout: cdk.Duration.seconds(30),
      memorySize: 512,
    });

    // Lambda に最小権限を付与
    table.grantReadWriteData(apiLambda);
    bucket.grantReadWrite(apiLambda);

    // API Gateway
    const api = new apigateway.RestApi(this, "AppApi", {
      restApiName: "MyApp API",
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
      },
    });

    api.root.addProxy({
      defaultIntegration: new apigateway.LambdaIntegration(apiLambda),
    });

    // CloudFront
    const distribution = new cloudfront.Distribution(this, "Distribution", {
      defaultBehavior: {
        origin: new origins.S3Origin(bucket),
        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
      },
    });

    // Output
    new cdk.CfnOutput(this, "ApiUrl", { value: api.url });
    new cdk.CfnOutput(this, "CloudFrontUrl", { value: distribution.distributionDomainName });
  }
}

---

Step 3: 既存スタックの更新と差分確認

# デプロイ前に差分を確認
npx cdk diff

# Claude Code に差分を説明してもらう
claude -p "
cdk diff の出力を読んで、今回の変更内容を日本語で説明して。
特にセキュリティグループ・IAMポリシーの変更は詳しく説明すること。

$(npx cdk diff 2>&1)
"

---

Step 4: マルチスタック構成の設計

本番規模のインフラはスタックを分割して管理します。

claude -p "
以下のマルチスタック構成を CDK TypeScript で設計して。

【スタック分割方針】
- NetworkStack: VPC、サブネット、セキュリティグループ
- DatabaseStack: RDS、ElastiCache (NetworkStack に依存)
- ApplicationStack: ECS、ALB、AutoScaling (NetworkStack, DatabaseStack に依存)
- MonitoringStack: CloudWatch ダッシュボード、アラーム、SNS通知

スタック間の依存関係と CfnOutput / Fn.importValue の使い方も含めて
"

// bin/app.ts
import * as cdk from "aws-cdk-lib";
import { NetworkStack } from "../lib/network-stack";
import { DatabaseStack } from "../lib/database-stack";
import { ApplicationStack } from "../lib/application-stack";
import { MonitoringStack } from "../lib/monitoring-stack";

const app = new cdk.App();
const env = { account: process.env.CDK_ACCOUNT, region: "ap-northeast-1" };

const network = new NetworkStack(app, "NetworkStack", { env });
const database = new DatabaseStack(app, "DatabaseStack", { env, vpc: network.vpc });
const application = new ApplicationStack(app, "ApplicationStack", {
  env,
  vpc: network.vpc,
  database: database.cluster,
});
new MonitoringStack(app, "MonitoringStack", {
  env,
  alb: application.alb,
  database: database.cluster,
});

---

Step 5: CloudFormation / CDK のデバッグを任せる

デプロイ失敗時のエラーも Claude Code に解決してもらえます。

claude -p "
CDK deploy が以下のエラーで失敗している。
原因と修正方法を教えて:

$(npx cdk deploy 2>&1 | tail -30)
"

よくある失敗パターン:

• ROLLBACK_COMPLETE: 前のデプロイが失敗してスタックが壊れている → cdk destroy してから再デプロイ
• UPDATE_ROLLBACK_FAILED: 手動変更と競合 → AWS Console で手動解消
• Resource already exists: 既存リソースとの名前衝突 → リソース名を変更するか import

---

落とし穴4選

1. cdk destroy で削除保護を回避してしまう

開発環境では removalPolicy: DESTROY にしておかないと cdk destroy でリソースが残ります。本番では RETAIN にして誤削除を防ぎましょう。

2. CloudFormation のドリフト検出を無視する

手動でAWSコンソールからリソースを変更すると CloudFormation と実態がズレます (ドリフト)。月1回 CloudFormation コンソールでドリフト検出を実行しましょう。

3. シークレットを template に直書きする

# ❌ 危険: パスワードがテンプレートに残る
DBPassword: "mysecretpassword"

# ✅ 安全: Secrets Manager または Parameter Store から取得
DBPassword: !Sub "{{resolve:secretsmanager:prod/db-password}}"

4. CDK のバージョン固定を怠る

package.json の CDK バージョンをチームで揃えないと、差分が発生します。package-lock.json をコミットして統一しましょう。

---

まとめ

タスク	Claude Code の貢献
CloudFormation生成	要件を伝えるだけで完成したYAML
CDK実装	TypeScriptで型安全なインフラコード
スタック設計	マルチスタックの依存関係設計
差分説明	cdk diff の出力を日本語で解説
デバッグ	エラーログから原因と修正方法を提示

インフラのコード化は「やらなきゃと思いつつ後回し」になりがちです。Claude Code を使えば**「こういうAWS構成が欲しい」と言うだけでテンプレートが完成**するので、IaC導入のハードルが劇的に下がります。

関連記事

• Claude Code × AWS Lambda 完全ガイド
• Claude Code × AWS IAM 完全ガイド
• Claude Code × AWS DynamoDB 完全ガイド

参考資料

• AWS CDK 公式ドキュメント
• CloudFormation ベストプラクティス
• CDK API Reference