Claude Code Dev Container Docker devcontainer.json CLAUDE.md 開発ツール 再現性のある環境

Dev Container + Claude Code: 再現性のある AI 開発環境の構築

The Prompt Shelf ·

Claude Code の動作は実行される環境に大きく依存します。利用可能なツール・ファイルパス・シェルエイリアス・言語ランタイム — これらすべてが Claude Code にできることとその信頼性に影響します。Dev Container は Claude Code の動作がマシンとチームメンバーをまたいで一貫する再現性のある環境を提供します。

Dev Container の中で Claude Code を実行するための実践的なセットアップを解説します。

Dev Container がルール設計を変える理由

Claude Code が開発者のローカルマシンで動作する場合、そのマシンの環境を継承します。インストールされた特定の Node バージョン、存在するグローバルパッケージ、ローカルのエイリアスと PATH の追加。別の開発者が同じプロジェクトを自分のマシンで開くと、Claude Code は微妙に異なる環境で動作します。

これは CLAUDE.md の問題を引き起こします。「変更を検証するには npm run test を実行する」というルールは、一方のマシンが Node 18 でもう一方が Node 20 の場合や、npm run test が一部のチームメンバーしか持っていないグローバルインストール済みパッケージに依存している場合、サイレントに壊れます。

Dev Container は Claude Code が動作する環境を標準化します。基盤となる環境が同一なので、同じ CLAUDE.md ルールが機能します。

基本的な devcontainer.json セットアップ

TypeScript/Node.js プロジェクトのミニマルなセットアップ:

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20",
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropics.claude-code"
      ]
    }
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
  ]
}

重要なポイント: ホストから ~/.claude をコンテナにマウントすること。Claude Code のセッションデータ・設定・スキルをイメージに焼き込まずにコンテナ環境に持ち込めます。

Claude 設定のマウント

Claude Code の設定は ~/.claude/ に保存されます。デフォルトでは、このディレクトリはコンテナ内に存在しません。2つの選択肢があります。

オプション1: ホストからバインドマウント（個人開発者に推奨）

"mounts": [
  "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
]

コンテナ内で個人の Claude Code 設定を使えます。スキル・settings.json・セッション履歴がすべて引き継がれます。

オプション2: プロジェクトスコープの設定のみ（チームに推奨）

~/.claude をマウントしません。代わりに、プロジェクトルートの .claude/settings.json のみに頼ります。これにより、個人設定に関わらずすべてのチームメンバーで Claude Code が同一に動作することを保証します。

// .claude/settings.json — リポジトリにコミット
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(docker *)"
    ]
  }
}

コンテナ環境向け CLAUDE.md

Claude Code がコンテナ内で動作する場合、標準的な CLAUDE.md のアドバイスの一部が変わります。

## 環境

このプロジェクトは Node 20 LTS ベースの Dev Container で動作します。開発はすべてコンテナ内で行います。

### 利用可能なツール
- Node 20.x、npm 10.x
- Git（SSH エージェント転送経由でホスト認証情報を使用）
- GitHub CLI (`gh`) — GITHUB_TOKEN 環境変数経由で認証済み
- Docker CLI（ソケットマウント経由でホストの Docker デーモンに接続）

### テストの実行
- `npm run test` — Jest テストスイートを実行
- `npm run test:watch` — ウォッチモードで実行（CI スクリプトでは使用しない）
- `npm run test:coverage` — カバレッジレポートを生成

### この環境での一般的な落とし穴
- ホストマシンを指すのに `localhost` を使わない。代わりに `host.docker.internal` を使う。
- `/workspace` パスがプロジェクトルート。`/Users/...` パスが存在すると仮定しない。
- コンテナから転送されるポート: 3000 (アプリ)、5432 (データベース)、6379 (Redis)。

### データベース
- PostgreSQL がコンテナのサービスとして動作中
- 接続: `postgresql://postgres:postgres@localhost:5432/mydb`
- マイグレーション: `npm run db:migrate`
- シード: `npm run db:seed`

「一般的な落とし穴」セクションは重要です。コンテナ環境はローカルマシンで機能する前提を壊し、明示的にリストアップすることでコンテナ内で失敗する localhost 参照を Claude Code が生成するのを防ぎます。

Docker Compose でサービスを追加する

複数のサービス（データベース・キャッシュ・外部 API）が必要なプロジェクトには、devcontainer と並行して docker-compose.yml を使います。

# docker-compose.yml
version: '3.8'
services:
  app:
    build:
      context: .
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - .:/workspace:cached
      - ~/.claude:/home/node/.claude:cached
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/mydb
      - REDIS_URL=redis://redis:6379

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  postgres_data:

devcontainer.json でこれを参照します。

{
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "app",
  "workspaceFolder": "/workspace"
}

CLAUDE.md を実際のホスト名を反映するよう更新します。

### サービスエンドポイント（コンテナ内）
- データベース: `postgresql://postgres:postgres@db:5432/mydb`
- Redis: `redis://redis:6379`
- 注意: コンテナ間通信には `localhost` ではなくサービス名（`db`、`redis`）を使う

コンテナ環境での MCP サーバー

ローカルファイルパスを参照する MCP サーバーはコンテナ環境向けに調整が必要です。/Users/alice/projects 向けに設定されたファイルシステム MCP サーバーはコンテナ内でそのパスを見つけられません。

解決策はコンテナ内に存在するパスを使って MCP サーバーを設定することです。

// .claude/settings.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://postgres:postgres@db:5432/mydb"
      }
    }
  }
}

このファイルをコミットします。プロジェクトを Dev Container で開くすべてのチームメンバーが同じ MCP 設定を受け取ります。

Dev Container によるチームオンボーディング

Claude Code にとっての Dev Container の主要な価値はオンボーディング速度です。プロジェクトを Dev Container で開く新しいチームメンバーは以下を得ます。

  • 正しい言語ランタイムとツールバージョン
  • プロジェクトの CLAUDE.md ルールが既に配置済み
  • .claude/settings.json のパーミッションが設定済み
  • 正しいエンドポイントに接続された MCP サーバー

Dev Container なしでは、それぞれがどこかにドキュメント化されていて、部分的に古くなっていて、開発者ごとに異なる形でスキップされる手動セットアップ手順を必要とします。

CLAUDE.md にオンボーディングフローをドキュメント化します。

## オンボーディング

このリポジトリをクローンしたばかりの場合は、作業を始める前に Dev Container で開いてください:
1. Dev Containers VS Code 拡張機能をインストール
2. コマンドパレット → "Dev Containers: Reopen in Container" を開く
3. コンテナのビルドと `postCreateCommand` の完了を待つ
4. `npm run dev` で開発サーバーを起動

コンテナには必要なものがすべて含まれています。追加のグローバルパッケージをインストールしないでください — 代わりに Dockerfile に追加してください。

チーム間での Claude Code スキルの共有

スキルはデフォルトで ~/.claude/skills/ — プロジェクト外、リポジトリにコミットされていない場所に置かれます。チーム共有スキルには代わりにプロジェクトレベルのスキルを使います。

.claude/
  skills/
    review.md
    deploy-check.md
    db-migration.md
  settings.json

これらはリポジトリにコミットされ、プロジェクトを開く誰でも利用可能です。ホストの ~/.claude をマウントして Dev Container を実行している場合、Claude Code は個人スキルとプロジェクトスキルの両方を見ます。

チームへの推奨セットアップ: 共有ワークフローにはプロジェクトスキル、個人設定には個人スキル。

Claude Code プロジェクト向け Dockerfile ベストプラクティス

Dev Container 用のカスタムイメージを構築する場合:

FROM mcr.microsoft.com/devcontainers/typescript-node:1-20

# Claude Code が呼び出す可能性のあるプロジェクト固有のツールをインストール
RUN npm install -g tsx @anthropic-ai/claude-code

# 一貫したロケールを設定（Claude Code 出力でのエンコーディング問題を防ぐ）
ENV LANG=en_US.UTF-8
ENV LC_ALL=en_US.UTF-8

# MCP サーバーの依存関係をプリインストール
RUN npm install -g @modelcontextprotocol/server-filesystem \
                   @modelcontextprotocol/server-github

# プロジェクト固有のツールを追加（リンター・フォーマッター等）
RUN npm install -g prettier eslint

Dockerfile でツールをプリインストールすることで、Claude Code はランタイムにダウンロードせずに呼び出せるようになり、パーミッション問題を回避して信頼性を向上させます。

まとめ

Dev Container は Claude Code の動作をチーム間で再現可能にします。主要な実践:

  • 個人設定には ~/.claude をマウント、厳格なチーム統一動作のためには省略
  • コンテナ固有の環境事実（ホスト名・パス・ポート）を CLAUDE.md にドキュメント化
  • 共有設定のために .claude/settings.json と .claude/skills/ をコミット
  • ホストパスではなくコンテナ相対パスで MCP サーバーを設定
  • Claude Code が呼び出す必要があるツールを Dockerfile でプリインストール

先行投資は Dockerfile と devcontainer.json です。見返りは全員の Claude Code セットアップが実質的に同一なチームです。

Share on X

Related Articles

Dev Containers + Claude Code: Reproducible AI Development Environments

How to configure Dev Containers alongside Claude Code for consistent AI-assisted development. Covers devcontainer.json setup, CLAUDE.md for container environments, MCP servers in containers, and team onboarding.

Claude Code 向け MCP サーバーを自作する実践ガイド（2026年版）

Claude Code をプロジェクト固有のツールで拡張するカスタム MCP サーバーの構築方法。TypeScript SDK・ツールスキーマ設計・リソースエンドポイント・エラーハンドリング・settings.json による接続まで解説。

Claude Code をコードレビュアーとして使う実践ワークフロー（2026年版）

Claude Code で体系的なコードレビューを実施する方法。PR分析・セキュリティチェック・アーキテクチャフィードバック、そしてレビューモードと実装モードで動作を変えるCLAUDE.md設定まで解説。

Claude Code as Your Code Reviewer: A Practical Workflow for 2026

How to use Claude Code for systematic code review — PR analysis, security checks, architectural feedback, and how to configure CLAUDE.md so review mode behaves differently from implementation mode.

Explore the collection

Browse all AI coding rules — CLAUDE.md, .cursorrules, AGENTS.md, and more.

Browse Rules