docker-development

Docker 開発

小さなイメージ。高速なビルド。安全なコンテナ。もう推測に頼る必要はありません。

肥大化した Dockerfile を本番環境向けのコンテナに変える、独自の方針に基づいた Docker ワークフローです。最適化、マルチステージビルド、Compose によるオーケストレーション、セキュリティ強化を扱います。

Docker のチュートリアルではありません。時間、容量、攻撃対象領域を無駄にしないコンテナのビルド方法について、具体的な判断をまとめたものです。

---

スラッシュコマンド

コマンド	内容
/docker:optimize	サイズ、速度、レイヤーキャッシュの観点から Dockerfile を分析、最適化します
/docker:compose	ベストプラクティスに沿って docker-compose.yml を生成、改善します
/docker:security	Dockerfile または実行中のコンテナのセキュリティ問題を監査します

---

このスキルが有効になる状況

ユーザーの次のようなパターンを認識します。

• 「この Dockerfile を最適化して」
• 「Docker のビルドが遅い」
• 「このプロジェクト用の docker-compose を作成して」
• 「この Dockerfile は安全？」
• 「Docker イメージのサイズを小さくして」
• 「マルチステージビルドを設定して」
• 「[言語／フレームワーク] 向けの Docker ベストプラクティス」
• Dockerfile、docker-compose、コンテナ、イメージサイズ、ビルドキャッシュ、Docker セキュリティに関するあらゆるリクエスト

ユーザーが Dockerfile を持っている場合、または何かをコンテナ化したい場合は、このスキルが適用されます。

---

ワークフロー

/docker:optimize — Dockerfile の最適化

1. 現在の状態を分析

   • Dockerfile を読み取る
   • ベースイメージとそのサイズを特定する
   • レイヤー数を数える（各 RUN/COPY/ADD = 1 レイヤー）
   • よくあるアンチパターンを確認する

2. 最適化チェックリストを適用

   BASE IMAGE
   ├── Use specific tags, never :latest in production
   ├── Prefer slim/alpine variants (debian-slim > ubuntu > debian)
   ├── Pin digest for reproducibility in CI: image@sha256:...
   └── Match base to runtime needs (don't use python:3.12 for a compiled binary)
   
   LAYER OPTIMIZATION
   ├── Combine related RUN commands with && \
   ├── Order layers: least-changing first (deps before source code)
   ├── Clean package manager cache in the same RUN layer
   ├── Use .dockerignore to exclude unnecessary files
   └── Separate build deps from runtime deps
   
   BUILD CACHE
   ├── COPY dependency files before source code (package.json, requirements.txt, go.mod)
   ├── Install deps in a separate layer from code copy
   ├── Use BuildKit cache mounts: --mount=type=cache,target=/root/.cache
   └── Avoid COPY . . before dependency installation
   
   MULTI-STAGE BUILDS
   ├── Stage 1: build (full SDK, build tools, dev deps)
   ├── Stage 2: runtime (minimal base, only production artifacts)
   ├── COPY --from=builder only what's needed
   └── Final image should have NO build tools, NO source code, NO dev deps
   

3. 最適化された Dockerfile を生成

   • 該当する最適化をすべて適用する
   • 各判断を説明するインラインコメントを追加する
   • 推定サイズ削減量を報告する

4. 検証

   python3 scripts/dockerfile_analyzer.py Dockerfile
   

/docker:compose — Docker Compose の設定

1. サービスを特定

   • アプリケーション（web、API、worker）
   • データベース（postgres、mysql、redis、mongo）
   • キャッシュ（redis、memcached）
   • キュー（rabbitmq、kafka）
   • リバースプロキシ（nginx、traefik、caddy）

2. Compose のベストプラクティスを適用

   SERVICES
   ├── Use depends_on with condition: service_healthy
   ├── Add healthchecks for every service
   ├── Set resource limits (mem_limit, cpus)
   ├── Use named volumes for persistent data
   └── Pin image versions
   
   NETWORKING
   ├── Create explicit networks (don't rely on default)
   ├── Separate frontend and backend networks
   ├── Only expose ports that need external access
   └── Use internal: true for backend-only networks
   
   ENVIRONMENT
   ├── Use env_file for secrets, not inline environment
   ├── Never commit .env files (add to .gitignore)
   ├── Use variable substitution: ${VAR:-default}
   └── Document all required env vars
   
   DEVELOPMENT vs PRODUCTION
   ├── Use compose profiles or override files
   ├── Dev: bind mounts for hot reload, debug ports exposed
   ├── Prod: named volumes, no debug ports, restart: unless-stopped
   └── docker-compose.override.yml for dev-only config
   

3. Compose ファイルを生成

   • ヘルスチェック、ネットワーク、ボリュームを含む docker-compose.yml を出力する
   • 必須変数をすべて説明した .env.example を生成する
   • 開発／本番のプロファイル注釈を追加する

/docker:security — コンテナのセキュリティ監査

1. Dockerfile の監査

   項目	重要度	修正方法
   root として実行	Critical	ユーザーを作成した後に USER nonroot を追加する
   :latest タグを使用	High	特定のバージョンに固定する
   ENV/ARG にシークレットを記載	Critical	BuildKit のシークレットを使用する：--mount=type=secret
   広範な glob を指定した COPY	Medium	個別のパスを指定し、.dockerignore を追加する
   不要な EXPOSE	Low	アプリが使用するポートのみを公開する
   HEALTHCHECK がない	Medium	適切な間隔で HEALTHCHECK を追加する
   特権付き命令	High	--privileged を避け、ケイパビリティを削除する
   パッケージマネージャーのキャッシュが残っている	Low	同じ RUN レイヤー内でクリーンアップする

2. 実行時のセキュリティチェック

   項目	重要度	修正方法
   root としてコンテナを実行	Critical	Dockerfile または Compose でユーザーを設定する
   ルートファイルシステムが書き込み可能	Medium	Compose で read_only: true を使用する
   すべてのケイパビリティを保持	High	すべて削除し、必要なものだけ追加する：cap_drop: [ALL]
   リソース制限がない	Medium	mem_limit と cpus を設定する
   ホストネットワークモード	High	bridge またはカスタムネットワークを使用する
   機密性の高いマウント	Critical	本番環境では /etc、/var/run/docker.sock を絶対にマウントしない
   ログドライバーが未設定	Low	サイズ制限を指定して logging: を設定する

3. セキュリティレポートを生成

   SECURITY AUDIT — [Dockerfile/Image name]
   Date: [timestamp]
   
   CRITICAL: [count]
   HIGH:     [count]
   MEDIUM:   [count]
   LOW:      [count]
   
   [Detailed findings with fix recommendations]
   

---

ツール

scripts/dockerfile_analyzer.py

Dockerfile の静的解析を行う CLI ユーティリティです。

機能:

• レイヤー数と最適化の提案
• ベースイメージの分析とサイズの推定
• アンチパターンの検出（15 個以上のルール）
• セキュリティ問題の検出
• マルチステージビルドの検出と検証
• JSON およびテキスト形式での出力

使用方法:

# Analyze a Dockerfile
python3 scripts/dockerfile_analyzer.py Dockerfile

# JSON output
python3 scripts/dockerfile_analyzer.py Dockerfile --output json

# Analyze with security focus
python3 scripts/dockerfile_analyzer.py Dockerfile --security

# Check a specific directory
python3 scripts/dockerfile_analyzer.py path/to/Dockerfile

scripts/compose_validator.py

docker-compose ファイルを検証する CLI ユーティリティです。

機能：

• サービス依存関係の検証
• ヘルスチェックの有無の検出
• ネットワーク設定の分析
• ボリュームマウントの検証
• 環境変数の監査
• ポート競合の検出
• ベストプラクティスのスコアリング

使用方法：

# Validate a compose file
python3 scripts/compose_validator.py docker-compose.yml

# JSON output
python3 scripts/compose_validator.py docker-compose.yml --output json

# Strict mode (fail on warnings)
python3 scripts/compose_validator.py docker-compose.yml --strict

---

マルチステージビルドのパターン

パターン 1：コンパイル言語（Go、Rust、C++）

# Build stage
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

# Runtime stage
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]

パターン 2：Node.js / TypeScript

# Dependencies stage
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

# Build stage
FROM deps AS builder
COPY . .
RUN npm run build

# Runtime stage
FROM node:20-alpine
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
COPY --from=builder /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

パターン 3：Python

# Build stage
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Runtime stage
FROM python:3.12-slim
WORKDIR /app
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
COPY --from=builder /install /usr/local
COPY . .
USER appuser
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

---

ベースイメージの選択フローチャート

Is it a compiled binary (Go, Rust, C)?
├── Yes → distroless/static or scratch
└── No
    ├── Need a shell for debugging?
    │   ├── Yes → alpine variant (e.g., node:20-alpine)
    │   └── No → distroless variant
    ├── Need glibc (not musl)?
    │   ├── Yes → slim variant (e.g., python:3.12-slim)
    │   └── No → alpine variant
    └── Need specific OS packages?
        ├── Many → debian-slim
        └── Few → alpine + apk add

---

先回りして指摘する項目

質問される前に、以下の項目を指摘してください。

• Dockerfile で :latest を使用している → 特定のバージョンタグに固定することを提案します。
• .dockerignore がない → 作成します。最低限、.git、node_modules、__pycache__、.env を含めます。
• 依存関係のインストール前に COPY . . を実行している → キャッシュが無効になります。依存関係を先にインストールするよう順序を入れ替えます。
• root として実行している → USER 命令を追加します。本番環境では例外はありません。
• ENV または ARG にシークレットが含まれている → BuildKit のシークレットマウントを使用します。シークレットをイメージレイヤーに埋め込まないでください。
• イメージが 1GB を超えている → マルチステージビルドが必須です。本番用イメージをこれほど大きくする理由はありません。
• ヘルスチェックがない → 追加します。オーケストレーター（Compose、K8s）がライフサイクルを適切に管理するには、ヘルスチェックが必要です。
• 同じレイヤー内でクリーンアップせずに apt-get を実行している → 同じ RUN 内で rm -rf /var/lib/apt/lists/* を実行します。

---

インストール

ワンライナー（任意のツール）

git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/docker-development ~/.claude/skills/

複数ツールのインストール

./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw

OpenClaw

clawhub install cs-docker-development

---

関連スキル

• senior-devops — より幅広い DevOps の領域（CI/CD、IaC、モニタリング）を扱います。docker-development はコンテナー固有の作業に、senior-devops はパイプラインやインフラストラクチャに使用します。互いに補完するスキルです。
• senior-security — アプリケーションセキュリティを扱います。docker-development はコンテナーセキュリティを、senior-security はアプリケーションレベルの脅威を扱います。互いに補完するスキルです。
• autoresearch-agent — Docker のビルド時間やイメージサイズを、測定可能な実験を通じて最適化できます。
• ci-cd-pipeline-builder — パイプラインの構築を扱います。docker-development でコンテナーをビルドし、ci-cd-pipeline-builder でデプロイします。互いに補完するスキルです。