Claude Code Docker Multi-Stage Builds Guide

Docker multi-stage builds have become essential for creating lean, production-ready container images. When combined with Claude Code’s AI capabilities, you can generate optimized multi-stage Dockerfiles that reduce image size, improve build times, and follow security best practices. This guide shows you how to use Claude Code effectively for Docker multi-stage build workflows.

Why Multi-Stage Builds Matter

Traditional Dockerfiles bundle everything needed to build your application into a single image, resulting in bloated containers that contain compilers, build tools, and source code that production doesn’t need. Multi-stage builds solve this by using multiple FROM statements, where each stage can copy artifacts from previous stages while discarding everything unnecessary.

A typical Node.js application built with a single Dockerfile might result in a 1.2GB image. The same application with multi-stage builds can shrink to under 150MB. This reduction matters significantly in containerized environments where storage, pull times, and security surface area all benefit from smaller images.

Claude Code understands these patterns and can generate appropriate multi-stage configurations based on your project’s language, framework, and requirements.

Generating Multi-Stage Builds with Claude Code

When working with Claude Code, you have several approaches to generate multi-stage Dockerfiles. The most effective method involves providing context about your project structure and requirements.

Project Context for Claude Code

Before asking Claude Code to generate a multi-stage Dockerfile, ensure you provide relevant context. This includes your programming language, framework version, build tools, and any specific requirements like production versus development configurations.

For a typical TypeScript Next.js application, you might describe your needs like this:

Generate a multi-stage Dockerfile for a Next.js application with TypeScript. 
The build stage should install dependencies, run type checking, and build 
the production application. The runtime stage should use a minimal base image 
with only the production dependencies.

Claude Code will then generate a Dockerfile similar to this:

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files and install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source and build
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine AS production

WORKDIR /app

# Copy only necessary files from builder
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production

EXPOSE 3000

CMD ["node", "server.js"]

Working with Different Language Ecosystems

Claude Code adapts its multi-stage build generation based on your technology stack. Here’s how it handles common scenarios.

Python Applications

For Python applications using pip and potentially Poetry or uv for dependency management:

# Build stage
FROM python:3.11-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# Production stage
FROM python:3.11-slim AS production

WORKDIR /app

# Create non-root user
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser

# Copy installed packages from builder
COPY --from=builder /root/.local /home/appuser/.local

# Copy application code
COPY --chown=appuser:appgroup . .

USER appuser

ENV PYTHONUNBUFFERED=1 \
    PATH=/home/appuser/.local/bin:$PATH

CMD ["python", "main.py"]

React Frontend Applications

For a React application built with Vite, multi-stage builds separate the Node.js build environment from a lightweight Nginx serving stage:

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci

# Copy source and build
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine

# Copy built assets from builder
COPY --from=builder /app/dist /usr/share/nginx/html

# Copy custom nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

This approach reduces the final image size dramatically since Node.js is not included in the production image—only the compiled static assets and Nginx are present.

Python FastAPI Applications (Virtual Environment Approach)

For a Python FastAPI application, Claude Code can use a virtual environment pattern that cleanly separates build-time dependencies from the runtime image:

# Build stage
FROM python:3.12-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Create virtual environment
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Copy and install requirements
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# Runtime stage
FROM python:3.12-slim

WORKDIR /app

# Copy virtual environment from builder
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Create non-root user
RUN useradd --create-home appuser && \
    chown -R appuser:appuser /app
USER appuser

# Copy application code
COPY --chown=appuser:appuser . .

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

The virtual environment is copied wholesale from the builder stage, preserving all installed packages without reinstalling them in the runtime stage.

Node.js with Prisma ORM

For a Node.js Express API with TypeScript and Prisma ORM, Claude Code generates a configuration that handles schema generation in the build stage:

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files first for better layer caching
COPY package*.json ./
RUN npm ci --only=production

COPY prisma ./prisma/
RUN npx prisma generate

COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine AS production

WORKDIR /app

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy only necessary files from builder
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/prisma ./prisma
COPY --from=builder --chown=nodejs:nodejs /app/package*.json ./

# Set environment for production
ENV NODE_ENV=production
ENV PORT=3000

USER nodejs

EXPOSE 3000

CMD ["node", "dist/main.js"]

Python Applications with uv

Modern Python projects benefit from uv for faster dependency resolution. Claude Code can generate a multi-stage build that uses uv with a compiler stage for packages requiring native extensions:

# Compiler stage (for packages needing native extensions)
FROM python:3.11-slim AS compiler

WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

RUN pip install uv
RUN uv venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

COPY requirements.txt .
RUN uv pip install --system -r requirements.txt

COPY . .

# Production stage
FROM python:3.11-slim AS production

WORKDIR /app

# Copy virtual environment from compiler
COPY --from=compiler /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

# Copy application code
COPY --from=compiler /app /app

# Run as non-root user
RUN useradd -m -u 1000 appuser && chown -R appuser /app
USER appuser

EXPOSE 8000

CMD ["python", "main.py"]

Go Applications

Go applications benefit enormously from multi-stage builds since the compilation produces a single binary. For maximum image minimalism, Claude Code can target the scratch base image and copy CA certificates directly from the builder:

# Build stage
FROM golang:1.21-alpine AS builder

WORKDIR /app

# Install build dependencies
RUN apk add --no-cache git make

# Copy go mod files first for caching
COPY go.mod go.sum ./
RUN go mod download

# Copy source and build
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /appbinary ./cmd/app

# Production stage (scratch for absolute minimal image)
FROM scratch AS production

WORKDIR /app

# Copy the binary
COPY --from=builder /appbinary /appbinary

# Copy static assets if needed
COPY --from=builder /app/static /app/static

# Copy CA certificates for HTTPS
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8080

ENTRYPOINT ["/appbinary"]

When HTTPS calls are not needed and no static assets are required, using FROM scratch produces the smallest possible image with zero OS overhead. Alternatively, use FROM alpine:3.18 and RUN apk --no-cache add ca-certificates if you prefer a shell for debugging.

Integrating Claude Code into Your Build Pipeline

Beyond generating Dockerfiles, Claude Code can help you integrate multi-stage builds into CI/CD pipelines and optimize the entire container workflow.

Automation with GitHub Actions

Claude Code can generate GitHub Actions workflows that use multi-stage builds:

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Docker image
        run: docker build --target production -t myapp:latest .
      
      - name: Run tests
        run: |
          docker build --target test -t myapp:test .
          docker run --rm myapp:test

Advanced Multi-Stage Patterns

Claude Code understands advanced patterns that further optimize your container strategy.

Test Stage Integration

You can add intermediate stages for running tests before building production images:

FROM node:20-alpine AS dependencies
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:20-alpine AS dev
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
CMD ["npm", "run", "dev"]

FROM node:20-alpine AS test
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
RUN npm run test

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
CMD ["node", "dist/index.js"]

Build Arguments in Multi-Stage Contexts

Claude Code can help you design multi-stage builds that accept build arguments for flexibility:

ARG NODE_VERSION=20-alpine

FROM node:${NODE_VERSION} AS base
WORKDIR /app

FROM base AS deps
COPY package*.json ./
RUN npm ci

FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM base AS production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

Combining with Claude Code Skills

The true power emerges when combining multi-stage build generation with other Claude Code skills. The pdf skill can generate documentation about your container architecture. The tdd skill helps ensure your tests run correctly within container stages. For frontend projects, the frontend-design skill works alongside Docker optimization to deliver efficient development and production workflows.

The supermemory skill maintains context about your organization’s Docker patterns, enabling consistent multi-stage configurations across projects. When working with monorepos, the relevant skills help manage complex multi-stage builds that serve different applications from a single repository.

Best Practices for Claude Code-Generated Dockerfiles

When using Claude Code to generate multi-stage builds, keep these considerations in mind:

Always specify exact versions in your base images rather than using floating tags like latest. This ensures reproducible builds and prevents unexpected changes when base images update.

Layer caching optimization: Place COPY commands for dependency files (e.g., package*.json, requirements.txt) before copying source code. Docker rebuilds only the layers that changed, so this ensures dependency installation is cached when only source files change.

Minimal base images: Prefer alpine or scratch for production stages. Smaller base images reduce vulnerability exposure and attack surface. The scratch image is ideal for statically compiled Go binaries.

Consider security implications when copying files between stages. The production stage should never contain source code, development dependencies, or build tools. The USER directive setting a non-root user should appear before CMD or ENTRYPOINT.

Use .dockerignore files to exclude unnecessary files from your build context. This reduces build context transfer time and prevents accidentally including sensitive files.

Consider adding health checks to your multi-stage Dockerfiles. Claude Code can generate HEALTHCHECK instructions appropriate for your application type, which improves reliability in container orchestration environments like Kubernetes or Docker Swarm.

Multi-platform builds: If deploying across CPU architectures (e.g., amd64 and arm64), use buildx to produce multi-platform images:

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

Test your multi-stage builds locally before deploying. The --target flag allows you to build specific stages for testing:

docker build --target test -t myapp:test .

Automating Dockerfile Updates

As your project evolves, regenerate Dockerfiles when dependencies change significantly. Track the Dockerfile alongside your code in version control so changes are reviewed alongside application code. Review Claude Code’s output against the Docker Bench Security checklist to ensure compliance with hardening guidelines.

When base image versions receive security patches, Claude Code can help you evaluate the impact and update FROM references across your stages consistently. This keeps the iteration loop tight as application requirements grow.

Conclusion

Claude Code transforms multi-stage Dockerfile generation from a manual, error-prone process into an AI-assisted workflow that produces optimized, secure containers. By providing clear context about your project and requirements, you get production-ready configurations that follow industry best practices.

The combination of AI assistance and multi-stage builds delivers smaller images, faster deployments, and improved security—all while reducing the cognitive load on developers. As containerized applications grow more complex, this approach becomes increasingly valuable for teams that want efficiency without sacrificing quality.

Related Reading

• Claude Code for Beginners: Complete Getting Started Guide
• Best Claude Skills for Developers in 2026
• Claude Skills Guides Hub

Built by theluckystrike — More at zovo.one