Claude Code × Docker: Deja que la IA Construya Tu Entorno de Desarrollo

"Funciona en mi máquina" es la frase más desmoralizante del desarrollo de software. Versiones de Node.js que no coinciden, variables de entorno sutilmente diferentes, conflictos de dependencias — he perdido más horas en esto de las que me gustaría admitir.

Eso cambió cuando empecé a combinar Docker con Claude Code. Ahora puedo delegar toda la configuración del entorno a Claude Code y obtener un entorno de desarrollo equivalente a producción en minutos. Así es cómo.

¿Por Qué Claude Code + Docker Es una Combinación Tan Poderosa?

Claude Code es una excelente herramienta de generación de código, pero opera directamente en tu máquina host — instalando paquetes, modificando archivos de configuración, ocupando puertos. En la mayoría de los casos eso está bien, pero para refactorizaciones a gran escala o cambios exploratorios, los efectos secundarios a nivel de host pueden ser un problema.

Añadir Docker cambia la ecuación por completo.

Aislamiento completo No importa cuántos archivos Claude Code reescriba dentro de un contenedor, nada se filtra al host. Los cambios destructivos son reversibles recreando el contenedor.

Reproducibilidad garantizada docker-compose up le da a cada miembro del equipo un entorno idéntico. El problema de "funciona en mi máquina" desaparece.

Paridad con producción Desarrolla sobre la misma imagen de SO y las mismas versiones de middleware que producción. La divergencia del entorno de staging se reduce drásticamente.

Permisos amplios y seguros para Claude Code Puedes dar a Claude Code acceso amplio al sistema de archivos dentro de un contenedor sin preocuparte por dañar el host. Eso significa menos puntos de fricción, iteración más rápida.

¿Cómo Configuras un DevContainer para Claude Code?

La funcionalidad DevContainer de VS Code es el enfoque estándar para desarrollo basado en Docker. Claude Code puede leer esta configuración y ejecutarse dentro del contenedor.

Requisitos previos

• Docker Desktop (o Docker Engine + Docker Compose)
• VS Code con la extensión Dev Containers
• CLI de Claude Code

Pasos de configuración

Crea el directorio .devcontainer/ en la raíz de tu proyecto.

mkdir -p .devcontainer

Crea .devcontainer/devcontainer.json.

{
  "name": "My Project Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    },
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  },
  "postCreateCommand": "npm install && npm run build",
  "remoteUser": "node"
}

Crea .devcontainer/docker-compose.yml.

version: "3.8"

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ..:/workspace:cached
      - node_modules:/workspace/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    command: sleep infinity

volumes:
  node_modules:

Crea .devcontainer/Dockerfile.

FROM node:22-bookworm-slim

RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

WORKDIR /workspace

Abre la carpeta del proyecto en VS Code con "Reopen in Container" y el entorno se levanta automáticamente.

¿Cómo Haces que Claude Code Genere docker-compose.yml?

Los proyectos reales frecuentemente involucran bases de datos, caches, colas de mensajes y otros servicios. Escribir el docker-compose.yml completo desde cero toma tiempo. Claude Code maneja esto bien.

Este es el tipo de prompt que obtiene excelentes resultados:

Create a docker-compose.yml for this Next.js project.
Requirements:
- Next.js 15 (Node.js 22)
- PostgreSQL 16
- Redis 7
- Development environment (hot reload enabled)
- No production config needed
- Health checks on all services
- Environment variables loaded from .env.local

Un output típico de Claude Code:

version: "3.8"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: npm run dev

  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=myapp_dev
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:
  redis_data:

Health checks, dependencias de servicios, volúmenes nombrados — todo correctamente configurado. A partir de ahí, puedes iterar: "Cambia PostgreSQL a la versión 17," "Añade un servicio de backup," y Claude Code actualiza el archivo correctamente.

¿Cómo Ejecutas Claude Code de Forma Segura Dentro de un Contenedor?

Ejecutar Claude Code dentro de un contenedor es principalmente sobre contener el radio de explosión de operaciones destructivas.

Cuando le pides a Claude Code que "elimine estos archivos" o "refactorice todo en este directorio," hacerlo dentro de un contenedor significa que el peor caso es perder el contenedor — no el sistema de archivos de tu máquina host.

Inicia Claude Code dentro del contenedor

# Enter the running container
docker exec -it myproject-app-1 bash

# Run Claude Code from inside
claude

Si estás usando DevContainers en VS Code, la terminal integrada ya está dentro del contenedor. No se necesitan pasos adicionales.

Pasar credenciales de API de forma segura

Claude Code necesita tu clave de API. Nunca la codifiques directamente.

# docker-compose.yml
services:
  app:
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

# .env on the host side
ANTHROPIC_API_KEY=sk-ant-...

Pasar credenciales desde el entorno del host al contenedor mantiene los secretos fuera del control de versiones y fuera de la imagen Docker.

¿Qué Necesitas Saber Sobre Docker + Claude Code en WSL2?

En Windows con WSL2 (Windows Subsystem for Linux), hay algunas consideraciones importantes para que Docker y Claude Code funcionen bien juntos.

Configuración recomendada

• Usa Docker Desktop para Windows con el backend WSL2
• Mantén tus proyectos en el sistema de archivos WSL2 (/home/username/)
• No coloques proyectos bajo /mnt/c/ (el sistema de archivos de Windows)

Montar rutas del sistema de archivos de Windows en volúmenes Docker causa una degradación severa del rendimiento. Si el hot reload de Next.js tarda 5–10 segundos, mover el proyecto al sistema de archivos WSL2 lo solucionará inmediatamente.

Instala Claude Code en WSL2

# Run inside WSL2 (Ubuntu)
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @anthropic-ai/claude-code

Integración VS Code + WSL2

La extensión Remote - WSL te permite editar archivos WSL2 desde Windows VS Code. La extensión Dev Containers también funciona dentro de WSL2. El resultado es una experiencia nativa de Windows respaldada por un entorno Linux.

¿Cómo Aíslas Completamente los Entornos de Desarrollo por Proyecto?

Al trabajar en múltiples proyectos, dar a cada uno su propia configuración DevContainer crea un aislamiento limpio y completo.

projects/
├── project-a/
│   ├── .devcontainer/
│   │   └── devcontainer.json  # Node.js 18 + PostgreSQL 14
│   └── src/
├── project-b/
│   ├── .devcontainer/
│   │   └── devcontainer.json  # Node.js 22 + MySQL 8
│   └── src/
└── project-c/
    ├── .devcontainer/
    │   └── devcontainer.json  # Python 3.12 + Redis
    └── src/

El DevContainer de cada proyecto puede incluir su propia configuración de Claude Code (CLAUDE.md), haciendo que toda la configuración de trabajo sea portable.

{
  "postCreateCommand": "npm install && echo 'Dev environment ready for Claude Code'"
}

El verdadero beneficio llega cuando un nuevo miembro del equipo se incorpora. git clone → abrir en VS Code → "Reopen in Container." Ese es todo el proceso de onboarding. Claude Code funciona de manera idéntica para todos.

¿Cómo Configuras Servidores MCP Dentro de un Contenedor?

Los servidores MCP (Model Context Protocol) también pueden ejecutarse dentro del contenedor, encapsulando el acceso a herramientas de Claude Code junto con todo lo demás.

// .claude/settings.json (inside the container)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:password@db:5432/myapp_dev"
      ]
    }
  }
}

Restringir el servidor de sistema de archivos a /workspace limita el acceso a archivos de Claude Code solo al directorio del proyecto.

El servidor de postgres permite que consultas como "verifica el esquema de la tabla users" o "encuentra el problema N+1 en estos endpoints" sean manejadas por Claude Code directamente contra tu base de datos real.

¿Cómo Usas Claude Code para Prevenir la Divergencia Dev/Prod?

La divergencia dev/prod generalmente sucede gradualmente: una configuración de conveniencia añadida durante el desarrollo nunca llega a producción. Claude Code puede monitorear activamente esto.

Compare docker-compose.yml (development) with
k8s/deployment.yaml (production).
Look for differences in environment variables,
port configurations, and health check settings.
Present any discrepancies in a table.

También puedes pedirle a Claude Code que genere y mantenga tu pipeline de CI/CD.

Create .github/workflows/deploy.yml:
- Build Docker image and push to GHCR
- Deploy using docker-compose.prod.yml
- Run health checks after deployment
- Send Slack notification on failure

Al delegar la configuración del entorno a Claude Code, obtienes detección continua de la divergencia sutil que los humanos tienden a pasar por alto.

Conclusión

Combinar Docker con Claude Code te da algo valioso: un entorno donde puedes hacer solicitudes audaces de forma segura.

• El aislamiento del contenedor limita el impacto de los cambios destructivos de Claude Code al contenedor mismo
• Las configuraciones DevContainer permiten que cada miembro del equipo ejecute Claude Code en entornos idénticos
• Configuraciones complejas de docker-compose pueden ser generadas por Claude Code en minutos
• Los usuarios de WSL2 obtienen los mismos beneficios siempre que los proyectos vivan en el sistema de archivos WSL2

Para empezar: crea un directorio .devcontainer/ y pídele a Claude Code que genere devcontainer.json y docker-compose.yml para tu proyecto. Tendrás un entorno de desarrollo equivalente a producción en quince minutos.