Cómo solucionar que la IA olvide la validación de variables de entorno

Los agentes de IA leen los valores de process.env directamente sin validación, lo que provoca errores silenciosos de undefined y la ausencia de errores de inicio cuando faltan variables de entorno.

El agente accede a process.env.SOME_KEY directamente, por lo que cuando la variable falta, la aplicación se inicia silenciosamente rota — sin crash, sin advertencia, solo undefined fluyendo a través de la lógica de negocio.

El síntoma

Lecturas de process.env dispersas por el código base sin esquema, sin seguridad de tipos y sin aserción al inicio.

// lib/stripe.ts — WRONG
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});
// If STRIPE_SECRET_KEY is undefined, Stripe SDK accepts it and every
// charge silently fails at runtime instead of at startup.

Por qué sucede

El agente optimiza por brevedad y por alcanzar código funcional rápidamente. La validación de variables de entorno es un boilerplate que no aparece en la mayoría de los ejemplos de entrenamiento, por lo que el modelo lo omite y va directo a la integración.

Cómo detectarlo

process.env.FOO usado sin una aserción no nula o comprobación de fallback.
No hay un archivo de validación env.ts / env.mjs en el proyecto.
El tipo TypeScript de un valor de entorno es string | undefined en el punto de uso.
La aplicación arranca sin error incluso cuando .env.local está vacío.

Cómo solucionarlo

Valida todas las variables de entorno requeridas al inicio usando un esquema Zod para que el proceso falle con un mensaje claro antes de atender una sola petición.

// lib/env.ts — CORRECT
import { z } from "zod";

const envSchema = z.object({
  STRIPE_SECRET_KEY: z.string().min(1),
  DATABASE_URL: z.string().url(),
  NEXTAUTH_SECRET: z.string().min(32),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
});

export const env = envSchema.parse(process.env);
//                             ^^^^^ throws at startup if any var is missing

// lib/stripe.ts — CORRECT (import validated env)
import Stripe from "stripe";
import { env } from "@/lib/env";

export const stripe = new Stripe(env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

[ ] Create lib/env.ts with a Zod schema covering every required variable
[ ] Import env from lib/env everywhere — never use process.env directly
[ ] Add lib/env.ts to the module graph so it runs at server startup (import in next.config.ts)
[ ] Document all variables in .env.example with placeholder values
[ ] Use z.string().url() / z.string().min(n) for format constraints, not just presence

Prompt de corrección

Every raw process.env access in this file is unvalidated. Create a lib/env.ts
module that parses and validates all required environment variables with Zod at
startup. Replace every process.env.FOO reference in the codebase with the
typed env.FOO import. Add a .env.example file listing every variable with a
placeholder value and comment.

Prueba

# Find any remaining raw process.env reads outside of lib/env.ts
grep -rn "process\.env\." --include="*.ts" --include="*.tsx" . \
  | grep -v "lib/env.ts" \
  | grep -v "next.config" \
  | grep -v "node_modules" \
  && echo "FAIL: raw process.env reads found" || echo "OK"