32blogby StudioMitsu
claude-code12 min read

Claude Code × Docker — 開発環境をAIに丸ごと構築させる

DockerとClaude Codeを組み合わせた開発環境の構築を完全解説。devcontainer設定・docker-compose生成・サンドボックス内での安全なAIエージェント実行まで実践的に紹介する。

claude-codedockerdevcontainer開発環境コンテナ
目次

「本番では動くのに開発環境では動かない」問題に何度も悩まされた。Node.jsのバージョンが違う、環境変数の設定が微妙に異なる、依存パッケージのバージョンが合わない——こういった問題に消耗するたびに「環境を統一したい」と思っていた。僕がたどり着いた答えが、DockerとClaude Codeの組み合わせだ。

DockerとClaude Codeを組み合わせたら、環境構築から本番同等の再現まで丸投げできるようになった。この記事では、その具体的なセットアップ方法を解説する。

Claude CodeとDockerを組み合わせると何が変わるか?

Claude Codeは優秀なコード生成ツールだが、「ホスト環境に直接変更を加える」という側面を持つ。意図しないパッケージのインストール、設定ファイルの書き換え、ポートの占有——これらがホストマシンに影響すると問題になることがある。

Dockerと組み合わせると以下のメリットが得られる。

環境の完全分離 Claude Codeがどれだけファイルを書き換えても、コンテナの外には影響しない。破壊的な変更もコンテナを捨てればリセットできる。

再現性の保証 docker-compose up 一発で誰でも同じ環境が立ち上がる。「自分のPCでは動く」問題がなくなる。

本番環境との一致 本番と同じOSイメージ・同じミドルウェアバージョンで開発できる。ステージング環境を別途用意しなくても差異が小さくなる。

Claude Codeへの安全な権限付与 コンテナ内でClaude Codeにファイルシステムへの広い権限を与えても、ホストへのダメージを最小化できる。

DevContainerのセットアップ手順は?

VS CodeのDevContainer機能はDockerを使った開発環境の標準的な仕組みだ。Claude Codeもこの設定を読み込み、コンテナ内で動作できる。

必要なもの

  • Docker Desktop(またはDocker Engine + Docker Compose)
  • VS Code + Dev Containers拡張機能
  • Claude Code CLI

セットアップ手順

プロジェクトルートに .devcontainer/ ディレクトリを作成する。

bash
mkdir -p .devcontainer

.devcontainer/devcontainer.json を作成する。

json
{
  "name": "32blog Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    },
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  },
  "postCreateCommand": "npm install && npm run build",
  "remoteUser": "node"
}

.devcontainer/docker-compose.yml を作成する。

yaml
version: "3.8"

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ..:/workspace:cached
      - node_modules:/workspace/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    command: sleep infinity

volumes:
  node_modules:

.devcontainer/Dockerfile を作成する。

dockerfile
FROM node:22-bookworm-slim

RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Claude Code CLI のインストール
RUN npm install -g @anthropic-ai/claude-code

WORKDIR /workspace

VS CodeでプロジェクトフォルダをDevContainerで開くと、自動でコンテナが起動して開発環境が整う。

docker-compose.ymlをClaude Codeに生成させるには?

実際のプロジェクトでは、データベース・キャッシュ・メッセージキューなど複数のサービスが絡む場合がある。このような複雑な構成をゼロから書くのは面倒だが、Claude Codeに任せると高い精度で生成してくれる。

プロンプト例を示す。

このNext.jsプロジェクト用のdocker-compose.ymlを作成してほしい。
要件:
- Next.js 15 (Node.js 22)
- PostgreSQL 16
- Redis 7
- 開発環境用(ホットリロード対応)
- 本番環境の設定は不要
- ヘルスチェックを各サービスに設定する
- 環境変数は .env.local から読み込む

Claude Codeが生成するdocker-compose.ymlの例。

yaml
version: "3.8"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: npm run dev

  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=myapp_dev
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
  redis_data:

ヘルスチェック・依存関係・ボリュームの設定まで適切に生成される。生成後に「PostgreSQLのバージョンを17に変えて」「バックアップ用のサービスを追加して」と追加依頼するだけで修正してくれる。

Claude Codeをコンテナ内で安全に動かすには?

Claude Codeをコンテナ内で動かす最大のメリットは破壊的な操作のリスク管理だ。

Claude Codeに「このファイルを削除して」「全ファイルをリファクタして」と依頼する場合、コンテナ内なら最悪のケースでもコンテナを再作成すれば元に戻る。

コンテナ内でClaude Codeを起動する

bash
# コンテナ内に入る
docker exec -it myproject_app_1 bash

# コンテナ内でClaude Codeを起動
claude

あるいはVS CodeでDevContainerを開いていれば、ターミナルは最初からコンテナ内になっている。

認証情報の安全な受け渡し

コンテナ内でClaude Codeを使うにはAPIキーが必要だ。ハードコードは絶対にしない。

yaml
# docker-compose.yml
services:
  app:
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
bash
# ホスト側の .env から読み込む
ANTHROPIC_API_KEY=sk-ant-...

ホスト側の環境変数をコンテナに渡す形が最も安全だ。

WSL2でDockerとClaude Codeを使うときの注意点は?

WSL2(Windows Subsystem for Linux)上でDockerとClaude Codeを動かす場合、いくつか注意点がある。

推奨構成

  • Docker Desktop for Windows(WSL2バックエンド)を使う
  • ファイルはWSL2のファイルシステム(/home/username/)に置く
  • WindowsのCドライブ(/mnt/c/)にはプロジェクトを置かない

Windowsファイルシステム上にプロジェクトを置くと、Dockerのボリュームマウントが著しく遅くなる。Next.jsのホットリロードが5-10秒かかるようなら、プロジェクトをWSL2側に移動すると劇的に改善する。

WSL2でのClaude Codeインストール

bash
# WSL2 Ubuntu内で実行
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @anthropic-ai/claude-code

VS CodeとWSL2の連携

VS CodeのRemote - WSL拡張機能を使うと、WSL2内のファイルをWindowsのVS Codeから編集できる。DevContainer拡張機能もWSL2内で動作するため、Windowsでも違和感なくコンテナ開発ができる。

プロジェクトごとに開発環境を完全分離するには?

複数のプロジェクトを扱う場合、プロジェクトごとに専用のDockerイメージを用意することで環境を完全分離できる。

projects/
├── project-a/
│   ├── .devcontainer/
│   │   └── devcontainer.json  # Node.js 18 + PostgreSQL 14
│   └── src/
├── project-b/
│   ├── .devcontainer/
│   │   └── devcontainer.json  # Node.js 22 + MySQL 8
│   └── src/
└── project-c/
    ├── .devcontainer/
    │   └── devcontainer.json  # Python 3.12 + Redis
    └── src/

各プロジェクトのdevcontainer.jsonに、そのプロジェクトで使うClaude Codeの設定(CLAUDE.md)も含めておく。

json
{
  "postCreateCommand": "npm install && echo 'Dev environment ready for Claude Code'"
}

このアプローチの利点は、新メンバーが参加したとき。git clone → VS CodeでDevContainerを開く、この2ステップだけで環境が揃う。Claude Codeも同じバージョン・同じ設定で動く。

コンテナ内でMCPサーバーを設定するには?

MCP(Model Context Protocol)サーバーをコンテナ内で動かすことで、Claude Codeのツール使用もサンドボックス化できる。

json
// .claude/settings.json(コンテナ内)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:password@db:5432/myapp_dev"
      ]
    }
  }
}

filesystemサーバーの許可パスを /workspace のみにすることで、Claude Codeがアクセスできる範囲をプロジェクトディレクトリに限定できる。

postgresサーバーを設定すると、「usersテーブルのスキーマを確認して」「クエリのN+1問題を探して」といった依頼をClaude Codeが直接データベースに問い合わせながら解決してくれる。

本番環境との乖離をClaude Codeで防ぐには?

本番環境との乖離が起きる原因の多くは「開発中に便宜上の設定を追加して、本番に反映するのを忘れる」パターンだ。

Claude Codeに定期的に環境の一致を確認させることで、この問題を防げる。

docker-compose.yml(開発環境)と
k8s/deployment.yaml(本番環境)を比較して、
環境変数・ポート・ヘルスチェックの設定に
差異がないか確認してほしい。
差異があれば一覧表形式でまとめて。

あるいは、CI/CDパイプラインの設定もClaude Codeに生成・維持させる。

.github/workflows/deploy.yml を作成してほしい。
- docker build してイメージをGHCRにpush
- docker-compose.prod.yml の内容でデプロイ
- デプロイ後にヘルスチェックを実行
- 失敗したらSlackに通知

環境設定ファイルの管理をClaude Codeに委ねることで、人間が見落としがちな設定の差異を継続的に検出できる。

まとめ

DockerとClaude Codeの組み合わせで得られるものは「安心して大胆に依頼できる環境」だ。

  • コンテナの分離により、Claude Codeが破壊的な変更をしても影響範囲が限定される
  • DevContainer設定でチーム全員が同じ環境でClaude Codeを使える
  • docker-composeの複雑な設定もClaude Codeに生成させれば数分で完成する
  • WSL2環境もWSL2ファイルシステムにプロジェクトを置けば快適に動く

まず .devcontainer/ ディレクトリを作って、Claude Codeに「このプロジェクト用のdevcontainer.jsonとdocker-compose.ymlを作って」と依頼するところから始めよう。15分もあれば本番同等の開発環境が手に入る。