はじめに
devcontainerでのローカル環境設定でも、Kubernetes本番デプロイ管理でもない。「動くDockerfileから本番品質のDockerfileへ」——マルチステージビルド・キャッシュ最適化・非rootユーザー設定と、Docker MCP ToolkitでDocker Composeを自然言語から生成する話だ。
devcontainer記事が「VS CodeやJetBrainsと連携したローカル開発環境の再現性」を扱うのに対して、この記事は「本番コンテナイメージとしての品質」と「Docker MCP Toolkitを使ったCompose設定の自動化」を扱う。
多くのエンジニアは「コンテナが動く」Dockerfileを書く。しかし本番品質のDockerfileには追加の要件がある。開発用の依存関係が含まれたまま本番イメージが1GB超になる問題、キャッシュ設計が悪く毎回全依存関係を再インストールするビルド時間の問題、rootユーザーで動作してセキュリティリスクがある問題——これらはDocker公式のベストプラクティスとして解決策が存在するが、「知っている人には当たり前、知らない人には分からない」ギャップがある。
Claude CodeとCLAUDE.mdを組み合わせることで、このギャップをチーム全体で埋められる。
CLAUDE.mdでDockerポリシーを定義する——チーム全員が本番品質のDockerfileを書く
DockerfileのベストプラクティスをCLAUDE.mdで定義しておくと、Claude Codeがコードを生成するたびにそのポリシーに従う。「Dockerfileレビューで毎回同じ指摘をする」問題をなくす出発点だ。
# CLAUDE.md（Dockerfileポリシー）
## Docker Build Policy
### ベースイメージ
- node: node:20-slim を使用（alpine は musl libc 互換性問題のため原則禁止）
- python: python:3.12-slim-bookworm
- Go: マルチステージビルドでscratch or distroless/static を最終イメージとして使用
### マルチステージビルド（必須）
- BuildステージとReleaseステージを分離
- 開発依存（devDependencies・test tools）はBuildステージのみ
- Releaseステージにはビルド成果物と本番依存のみコピー
### キャッシュ最適化（必須）
- package.json / package-lock.json を先にCOPYし、npm ciを実行
- ソースコード（COPY . .）はnpm ciより後に配置
### セキュリティ（必須）
- 非rootユーザー（appuser）を作成してUSER切り替え
- .dockerignoreに node_modules, .env, .env.*, .git, dist を必ず含める
- 本番イメージにシークレット・認証情報を含めない
- HEALTHCHECKを長時間稼働サービスに必須
### docker-compose
- 環境変数は .env ファイルで管理（docker-compose.yml にハードコード禁止）
- volumeは開発環境のみ。本番compose-override不使用alpineをベースイメージで禁止している理由は、alpine がmusl libcを使うため、glibc前提のネイティブモジュール（Node.jsのネイティブアドオン等）で互換性問題が発生しやすいことだ。slimイメージはイメージサイズを抑えつつglibc環境を維持するため、本番用途に適している。
マルチステージビルド × キャッシュ最適化——Claude Codeが生成する本番Dockerfileの解剖
Node.js本番Dockerfileの完全な例はこうなる。
# Buildステージ：devDependenciesを含む全ての依存関係でビルド
FROM node:20-slim AS builder
WORKDIR /app
# キャッシュ最適化: package.jsonを先にコピーしてnpm ciを実行
# ソースコードを変更してもこのレイヤーは無効化されない
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
# ===========================
# Releaseステージ：本番用の最小イメージ
FROM node:20-slim AS production
WORKDIR /app
# 本番依存のみインストール（devDependencies除外）
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
# ビルド成果物のみコピー（ソースコードは含まない）
COPY --from=builder /app/dist ./dist
# セキュリティ: 非rootユーザーで実行
RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \
CMD node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"
CMD ["node", "dist/server.js"]まずキャッシュ層の設計だ。COPY package.json → RUN npm ci → COPY . . の順序にすることで、ソースコードを変更しても依存インストールのレイヤーが無効化されない。毎回全依存関係を再インストールするビルドから、ソースコード変更だけを再ビルドする高速ビルドに変わる。
BuildステージでTypeScriptのコンパイルやテストに使ったdevDependenciesは、Releaseステージには含まれない。イメージサイズの大幅な削減と、本番に不要なツールが含まれるセキュリティリスクの排除を同時に達成する。
非rootユーザーでの実行は、コンテナが侵害された際の影響範囲をアプリプロセスに限定するためだ。
Claude Codeへの指示パターンはシンプルだ。
「このNode.jsアプリのDockerfileを本番品質に改善して。
要件:
- マルチステージビルド（builder + production）
- package.jsonを先にコピーしてnpm ciを実行（キャッシュ最適化）
- 本番ステージでdevDependenciesを除外
- 非rootユーザー（appuser）で実行
- HEALTHCHECKを追加（/healthエンドポイント）
- .dockerignoreも生成して」CLAUDE.mdにポリシーが定義されていれば、「このDockerfileを本番品質に改善して」だけでも同等の出力が得られる。
Docker MCP Toolkit——Docker Compose自動生成と公式統合
DockerがClaude Code向けに提供する公式MCP Toolkit（docs.docker.com/guides/genai-claude-code-mcp/）は、Docker HubへのリアルタイムアクセスとDocker Compose生成を統合している。
コア機能は、Docker Hubから最新の公式イメージタグをリアルタイム取得するDocker Hub検索、自然言語からdocker-compose.ymlを生成するCompose生成、そしてClaude Codeからコンテナの起動・停止・ログ確認を操作するコンテナ管理だ。
自然言語からdocker-compose.ymlを生成する流れはこうなる。
指示:「Node.js + PostgreSQL + RedisのDocker Compose環境を作って。
PostgreSQLはデータを永続化、Redisはセッション管理用。
本番とdev環境のoverride設定も分けて」Docker MCP Toolkitがこの指示を受けると、Docker Hubで最新のPostgreSQL・Redisイメージタグを確認してからdocker-compose.ymlを生成する。古いイメージタグを手書きして使い続けてしまうリスクが減る。
DockerはClaude Code向けに公式統合を発表し（www.docker.com/blog）、200以上のMCPサーバーをコンテナ化して1クリックで起動できるDocker MCP Toolkitが提供されている。Claude Codeと組み合わせたコンテナ開発の標準的なアプローチになりつつある。
Claude Code自体をDockerコンテナ内で実行する活用も注目される。
# Claude Codeをヘッドレスモードでコンテナ実行
docker compose run --rm claude \
claude --dangerously-skip-permissions \
"このリポジトリのDockerfileをマルチステージビルドに変換して"AIエージェントのアクセス範囲をコンテナ内に限定することで、「どこまでClaude Codeに触れさせるか」の境界をDockerで設定できる。CI/CDでClaude Codeをエージェントとして使う場合のセキュリティ設計として有効だ。claudebox（github.com/RchGrav/claudebox）はこのアプローチを実装したコミュニティプロジェクトだが、採用前にメンテナンス状態を確認することを推奨する。
まとめ
DockerfileをClaude Codeで本番品質に引き上げる起点はCLAUDE.mdへのポリシー定義だ。マルチステージビルド必須・package.json前置きキャッシュ・非rootユーザー・HEALTHCHECKを書いておけば、以降Claude Codeが生成するDockerfileは最初からそれらが含まれる。Dockerfileレビューで毎回同じコメントをする時間がなくなる。
Docker MCP Toolkitは「docker-compose.ymlを手書きする」作業を自然言語指示に置き換える。Docker Hubの最新タグを参照しながら生成するため、イメージの陳腐化リスクも抑えられる。
まず試すなら、CLAUDE.mdに「マルチステージビルド必須・非rootユーザー必須・.dockerignore必須」の3行を追加してから既存Dockerfileの改善をClaude Codeに依頼してみてほしい。生成前後のDockerfileを比較することで、CLAUDE.mdが設計判断にどう影響するかを実感できる。
コメント