Entorno de desarrollo con Claude Code: seguro y reproducible

Un PC nuevo o un repositorio recién clonado no deberían consumir media jornada antes del primer cambio útil. Los fallos casi siempre se repiten: versión incorrecta de Node.js, mezcla de npm y pnpm, .env desactualizado, volúmenes de Docker con datos antiguos y pasos locales que nadie documentó. Claude Code acelera el trabajo, pero solo es seguro si antes defines límites claros.

La meta no es pedir “configúralo todo” y confiar. La meta es que cada persona y cada sesión de Claude Code usen la misma versión de Node, el mismo gestor de paquetes, las mismas reglas para secretos y los mismos comandos de verificación.

Usa documentación oficial como referencia: Claude Code setup, settings, permissions y hooks. Para ampliar dentro de ClaudeCodeLab, revisa guía inicial, buenas prácticas de CLAUDE.md y guía de hooks.

flowchart TD
  A["Comprobar herramientas"] --> B["Fijar Node y gestor de paquetes"]
  B --> C["Crear dependencias y .env.example"]
  C --> D["Guardar instrucciones en CLAUDE.md"]
  D --> E["Limitar permisos en settings.json"]
  E --> F["Bloquear comandos peligrosos con hooks"]
  F --> G["Ejecutar doctor, env check y tests"]

Política de entorno

Trata el entorno de desarrollo como código de producción. Si una regla importa, debe quedar en el repositorio. Si un secreto importa, no debe entrar en el contexto del agente. Si un comando puede borrar datos o publicar código, debe pedir aprobación humana.

Área	Archivo o comando	Motivo
Runtime	.nvmrc, packageManager, Corepack	Evita diferencias de Node y pnpm
Secretos	.env.example, .gitignore, permissions.deny	Mantiene credenciales reales fuera de prompts y commits
Memoria del proyecto	CLAUDE.md	Claude Code lee las reglas en cada sesión
Permisos	.claude/settings.json	Controla lecturas, Bash y modo por defecto
Hooks	.claude/hooks/*	Ejecutan bloqueos deterministas antes de las herramientas
Verificación	doctor, check:env, test	Sustituyen “parece bien” por evidencia

Bootstrap copiable

Este script funciona en Git Bash, WSL, macOS o Linux. Crea un proyecto TypeScript mínimo, valida variables de entorno, fija pnpm, impide leer secretos y añade un hook PreToolUse contra comandos arriesgados.

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="${1:-claude-dev-lab}"
mkdir -p "$APP_DIR"
cd "$APP_DIR"

command -v node >/dev/null || { echo "Falta Node.js"; exit 1; }
command -v claude >/dev/null || { echo "Falta Claude Code CLI"; exit 1; }

corepack enable
corepack prepare [email protected] --activate

cat > package.json <<'JSON'
{
  "name": "claude-dev-lab",
  "private": true,
  "type": "module",
  "packageManager": "[email protected]",
  "scripts": {
    "doctor": "node --version && pnpm --version && claude --version",
    "check:env": "tsx src/env.ts",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "dotenv": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}
JSON

mkdir -p src .claude/hooks .vscode
printf "22\n" > .nvmrc
cat > .gitignore <<'EOF'
node_modules
.env
.env.*
!.env.example
dist
coverage
EOF

cat > .env.example <<'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://app:app@localhost:5432/app
REDIS_URL=redis://localhost:6379
EOF

cat > src/env.ts <<'TS'
import { config } from "dotenv";
import { z } from "zod";

config();

const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional()
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

console.log("env ok", {
  nodeEnv: parsed.data.NODE_ENV,
  hasRedis: Boolean(parsed.data.REDIS_URL)
});
TS

cat > CLAUDE.md <<'EOF'
# Instrucciones del proyecto

## Configuración del entorno
- Usa la versión de Node indicada en `.nvmrc`.
- Usa pnpm mediante Corepack. No cambies a npm ni yarn.
- Copia `.env.example` a `.env` en local y edita los valores manualmente.
- Nunca leas, imprimas ni confirmes `.env` o archivos secretos.
- Antes de cambiar código, ejecuta `pnpm run doctor` y `pnpm run check:env`.
- Después de cambiar código, ejecuta la prueba más estrecha y registra el resultado.

## Reglas de trabajo
- Empieza explorando y proponiendo un plan corto.
- No ejecutes comandos destructivos ni despliegues sin aprobación humana explícita.
- Deja los cambios de setup en archivos reproducibles, no solo en el historial del terminal.
EOF

cat > .claude/hooks/block-dangerous.mjs <<'JS'
import { readFileSync } from "node:fs";

const input = JSON.parse(readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command ?? "");

const blockedPatterns = [
  /rm\s+-rf\s+(\/|~|\$HOME)/,
  /git\s+push\b/,
  /curl\b.+\|\s*(bash|sh)/,
  /Invoke-WebRequest\b.+\|\s*iex/i
];

if (blockedPatterns.some((pattern) => pattern.test(command))) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Comando peligroso bloqueado. Una persona debe revisar objetivo y alcance."
    }
  }));
} else {
  console.log("{}");
}
JS

cat > .claude/settings.json <<'JSON'
{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read",
      "Bash(pnpm install)",
      "Bash(pnpm run *)",
      "Bash(git status *)",
      "Bash(claude --version)",
      "Bash(claude doctor)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous.mjs"
          }
        ]
      }
    ]
  }
}
JSON

pnpm install
cp .env.example .env
pnpm run doctor
pnpm run check:env
pnpm test

En Windows nativo, valida primero la cadena de herramientas:

winget install Anthropic.ClaudeCode
claude --version
claude doctor
node --version
corepack enable
pnpm --version

Si falla pnpm --version, corrige Node/Corepack antes de tocar el proyecto. Si claude doctor muestra problemas de proxy, certificado o login, guarda el error exacto y pide a Claude Code un diagnóstico con esa restricción.

Prompt más seguro

claude -p "
Audita y completa la configuración del entorno de desarrollo de este repositorio.

Reglas:
- No leas .env, .env.* ni archivos dentro de secrets/
- Respeta packageManager; no cambies pnpm por npm o yarn
- No borres volúmenes de Docker ni ejecutes git push

Permitido:
- Leer README, package.json, CLAUDE.md y .claude/settings.json
- Ejecutar pnpm install, pnpm run doctor, pnpm run check:env y pnpm test

Devuelve un recibo breve con comandos ejecutados, archivos cambiados, fallos encontrados y pasos manuales pendientes.
"

Casos de uso concretos

Caso	Aplicación práctica
Prototipo SaaS nuevo	Añade Docker Compose para PostgreSQL y Redis sin perder reproducibilidad
Repositorio de equipo	Claude Code lee documentación, ejecuta checks permitidos y mejora el onboarding
Sitio de contenido o producto	Protege CTA, eventos de analítica, OGP y páginas sensibles para AdSense
Herramienta interna	Estandariza seed de base de datos, colas, mocks y pruebas

Para proyectos con mucho Docker, sigue con Docker Compose. Para trabajo en equipo, lee colaboración con Claude Code. Para CI, conecta estos comandos con configuración CI/CD.

Errores frecuentes

No mezcles gestores de paquetes. Si existe pnpm-lock.yaml, no permitas npm install. Escribe la regla en CLAUDE.md y conserva packageManager en package.json.

No dejes que Claude Code lea .env. El archivo revisable es .env.example; los valores reales se editan a mano. Usa .gitignore y permissions.deny juntos.

Ten cuidado con Docker. Un volumen antiguo puede hacer que una migración parezca rota. Pide primero explicación del volumen afectado y del riesgo antes de borrar nada.

Evita bypassPermissions en tu máquina principal. Úsalo solo dentro de contenedores o máquinas virtuales aisladas. Además, revisa los hooks de repositorios no confiables antes de iniciar una sesión.

Lista de verificación

• claude --version y claude doctor funcionan
• Existe .nvmrc o .node-version
• package.json incluye packageManager
• Solo hay un lockfile
• .env.example está actualizado y .env se ignora
• CLAUDE.md documenta setup, prohibiciones y checks
• .claude/settings.json bloquea secretos, git push y comandos destructivos
• El recibo final incluye comandos y resultados

CTA y resultado

Un entorno roto puede dañar enlaces de compra, formularios, analítica o páginas con anuncios. Para convertir este flujo en un sistema reutilizable, empieza por la chuleta gratuita, revisa productos o lleva el proceso al equipo con formación.

Probé el flujo creando el proyecto mínimo, instalando dependencias, copiando .env.example y ejecutando pnpm run doctor, pnpm run check:env y pnpm test. Lo que más redujo riesgo fue negar lectura de .env y bloquear git push o comandos destructivos mediante hook. En el trabajo real de Masa, los fallos de setup suelen venir de supuestos no documentados, no de comandos difíciles.