Claude Code x Docker Compose完全ガイド：フルスタック環境構築

2026.04.10 公開 13分で読める

この記事の結論

Claude CodeでPostgreSQL+FastAPI+Next.jsのマルチコンテナ開発環境をDocker Composeで構築。devcontainer連携まで実践コードで解説します。

「Claude Codeにコードを書かせたら動かない——あ、DBが起動してなかった」

こういうことが頻繁に起きるのは、Claude CodeのコンテキストにデータベースやAPIサーバーが含まれていないからです。実際に構築してみると、Claude CodeをDocker Composeで管理されたマルチコンテナ環境に接続するだけで、この問題は一気に解決します。エージェントがPostgreSQLにクエリを投げ、FastAPIを呼び出し、Next.jsのビルドを走らせる——全部ひとつのComposeファイルで管理できます。

この記事では、PostgreSQL + FastAPI + Next.jsの3サービス構成を例に、Claude Code連携まで含めたフルスタック開発環境をゼロから構築する手順をコピペ可能なファイルとともに解説します。

まず試したい「5分即効」セットアップ3選

全体像に入る前に、すぐ試せる設定を3つ紹介します。

即効テクニック1：最小構成のdocker-compose.yml

PostgreSQL + APIサーバーの最小構成です。これだけでClaude Codeからデータベースにアクセスできるようになります。

# docker-compose.yml（最小構成）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 動作環境: Docker Desktop 4.x+, Docker Compose v2.x+

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpassword
      POSTGRES_DB: app_db
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://dev:devpassword@db:5432/app_db
    depends_on:
      db:
        condition: service_healthy  # DBの準備完了を待つ
    volumes:
      - ./backend:/app  # ホットリロード用

volumes:
  postgres_data:

ポイント：condition: service_healthyを使うことで、PostgreSQLが完全に起動する前にAPIサーバーが起動して接続失敗するという典型的なレースコンディションを防ぎます。

即効テクニック2：FastAPIのDockerfile（開発用）

# backend/Dockerfile
# 動作環境: Python 3.11+
FROM python:3.11-slim

WORKDIR /app

# 依存パッケージを先にインストール（レイヤーキャッシュ効率化）
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# uvicornで起動、--reloadでホットリロード有効
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

即効テクニック3：devcontainer.jsonでClaude Codeを接続

Claude Codeの公式devcontainerサポートを使うと、Composeで管理したサービスにClaude Codeをシームレスに接続できます。

// .devcontainer/devcontainer.json
// 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
{
  "name": "Fullstack Dev",
  "dockerComposeFile": ["../docker-compose.yml", "docker-compose.devcontainer.yml"],
  "service": "claude-code",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/python:1": {}
  },
  "forwardPorts": [3000, 8000, 5432],
  "postCreateCommand": "pip install -r requirements.txt && npm install"
}

フルスタック3サービス構成の全体像

サービス	役割	イメージ / ビルド	ポート	ホットリロード
db	PostgreSQL 16	postgres:16-alpine	5432	—
api	FastAPI バックエンド	./backend/Dockerfile	8000	uvicorn –reload
frontend	Next.js フロントエンド	./frontend/Dockerfile	3000	next dev
claude-code	AI開発エージェント	ghcr.io/anthropics/claude-code	—	—

完全版docker-compose.yml（3サービス構成）

本番でも使えるヘルスチェック・ボリューム・ネットワーク設定を含めた完全版です。

# docker-compose.yml（フルスタック完全版）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 動作環境: Docker Desktop 4.35+, Docker Compose v2.24+

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER:-dev}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-devpassword}
      POSTGRES_DB: ${DB_NAME:-app_db}
    ports:
      - "${DB_PORT:-5432}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-dev}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend-net

  api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://${DB_USER:-dev}:${DB_PASSWORD:-devpassword}@db:5432/${DB_NAME:-app_db}
      ENVIRONMENT: development
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./backend:/app
    networks:
      - backend-net
      - frontend-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_URL: http://localhost:8000
      INTERNAL_API_URL: http://api:8000  # コンテナ間通信
    depends_on:
      api:
        condition: service_healthy
    volumes:
      - ./frontend:/app
      - /app/node_modules  # node_modulesはホストと同期しない
    networks:
      - frontend-net

networks:
  backend-net:
    driver: bridge
  frontend-net:
    driver: bridge

volumes:
  postgres_data:

Claude Codeとの接続方法

Claude Codeの公式ドキュメント（code.claude.com/docs/en/devcontainer）によると、devcontainerを使った接続が推奨されています。追加のcomposeオーバーライドファイルでClaude Codeサービスを加えます。

# .devcontainer/docker-compose.devcontainer.yml
# 動作環境: Claude Code 1.x+

services:
  claude-code:
    image: ghcr.io/anthropics/claude-code:latest
    volumes:
      - ../:/workspace:cached
    working_dir: /workspace
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    networks:
      - backend-net
      - frontend-net
    # 全サービスが起動してからClaude Codeを起動
    depends_on:
      - api
      - frontend

これにより、Claude Codeのコンテキスト内でAPIサーバーに対して直接HTTPリクエストを投げたり、データベースに接続してスキーマを確認したりできるようになります。

Claude Codeへの指示プロンプト例

マルチコンテナ環境が立ち上がったら、Claude Codeに以下のような指示が通るようになります。


# プロンプト例: データベーススキーマの確認とAPIエンドポイント生成

以下のタスクを順番に実行してください：

1. PostgreSQL（localhost:5432, DB: app_db）に接続し、既存のテーブル一覧を確認
2. usersテーブルのCRUDエンドポイントをFastAPIで実装（/users, /users/{id}）
3. Pydanticモデルと依存性注入を使い、SQLAlchemyでDBに接続する実装にすること
4. 実装後、docker compose exec api pytest tests/ でテストを実行

動作環境: FastAPI 0.115+, SQLAlchemy 2.0+, Python 3.11+

本番環境への展開を見据えた設計

開発環境と本番環境を分けるために、Composeファイルをオーバーレイ方式で管理するのが最善です。

# 開発環境
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# 本番環境
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# テスト環境
docker compose -f docker-compose.yml -f docker-compose.test.yml run --rm api pytest

【要注意】よくある失敗パターンと回避策

失敗1：depends_onだけで起動順序を制御しようとする

❌ depends_on: - dbだけで設定（サービス起動 ≠ 準備完了）

⭕ condition: service_healthyとhealthcheckをセットで設定

なぜ重要か：PostgreSQLのコンテナが起動しても、受け入れ可能になるまで数秒かかります。healthcheckなしでは接続エラーが頻発します。

失敗2：node_modulesをボリュームマウントに含める

❌ ./frontend:/appだけでマウント

⭕ - /app/node_modulesを追加して匿名ボリュームで分離

なぜ重要か：ホストとコンテナのアーキテクチャが異なる場合（M1 Macなど）、ネイティブバイナリが混在してビルドが壊れます。

失敗3：APIキーをdocker-compose.ymlに直書き

❌ ANTHROPIC_API_KEY: sk-ant-xxxx

⭕ .envファイルに書いてdocker composeが自動読み込み、または${ANTHROPIC_API_KEY}で環境変数参照

なぜ重要か：docker-compose.ymlをgitに含めた瞬間にシークレットが漏洩します。

失敗4：コンテナ間通信にlocalhostを使う

❌ フロントエンドからhttp://localhost:8000/apiでAPIを呼び出す

⭕ コンテナ間はhttp://api:8000（サービス名）、ブラウザからはhttp://localhost:8000

なぜ重要か：コンテナ内のlocalhostはコンテナ自身を指すため、別コンテナには到達できません。

参考・出典

Development containers — Claude Code Docs — Anthropic公式ドキュメント（参照日: 2026-04-09）
Generate Docker Compose Files with Claude Code and Docker MCP Toolkit — Docker公式ドキュメント（参照日: 2026-04-09）
Build a Multi-Container DevContainer for Claude Code — Medium（参照日: 2026-04-09）

まとめ：今日から始める3つのアクション

今日やること：既存プロジェクトにdocker-compose.ymlを追加し、DBとAPIを1コマンドで起動できるようにする
今週中：.devcontainer/devcontainer.jsonを設定してClaude Codeをマルチコンテナ環境に接続する
今月中：開発/テスト/本番の3環境をComposeオーバーレイで管理し、本番同等の環境でClaude Codeにレビューさせる

あわせて読みたい:

AIエージェント構築完全ガイド — エージェント設計の基本から学ぶ
Claude Code × GitHub Actions CI/CD — Docker Compose環境をCIに組み込む

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。100社以上の企業向けAI研修・導入支援。著書累計3万部突破。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。

Need help moving from reading to rollout?

この記事を読んで導入イメージが固まってきた方へ

Uravationでは、AIエージェントの要件整理、PoC設計、社内導入、研修まで一気通貫で支援しています。

30分無料相談を予約支援実績を見る

※ 本記事の情報は2026年4月時点のものです。サービスの料金・仕様は変更される可能性があります。最新情報は各サービスの公式サイトをご確認ください。