Antes de darle las llaves a la IA. Las 5 protecciones para que un principiante no provoque accidentes

“Este proyecto, organízalo un poco por encima.”

Tecleé eso a la ligera y me fui a prepararme un café. Cuando volví, la terminal estaba a un paso de ejecutar rm -rf. Y mi dedo, sin darme cuenta, se acercaba al botón de aprobar.

Si en aquel momento llego a pulsar “sí”, el .env y los archivos de configuración habrían desaparecido todos juntos.

Claude Code es listo. Pero inteligencia y seguridad son cosas completamente distintas. Más bien, justo por ser listo y tener la mano rápida, también corre a toda velocidad en la dirección equivocada. Es lo mismo que un cuchillo: cuanto mejor corta, antes te haces un corte si lo coges sin saber usarlo.

Este artículo se centra solo en las protecciones que un principiante debe asegurar primero. Lo difícil, para después. Te escribo, fácil y con mis propias cagadas al lado, las 5 cosas que hay que defender desde ya.

Para empezar, ¿qué es lo que da tanto miedo?

Un editor de texto normal solo muestra letras. Pero Claude Code es otra cosa. Es una herramienta que, dentro de tu ordenador, “es capaz de hacer” cosas como estas:

Leer, escribir y borrar archivos.
Ejecutar comandos de la terminal (rm incluido).
Acceder a internet y publicar en servicios externos.

Y todo esto, además, funciona si tú apruebas con un “sí”. El problema es que, a base de pulsar el botón de aprobar decenas de veces, dejas de mirar lo que pone. En el momento en que entras en el ritmo de “sí, sí, vale”, una operación peligrosa se cuela sin que te enteres.

Por eso las protecciones no consisten en “tener cuidado”. Consisten en montar de antemano un sistema en el que, aunque no tengas cuidado, no haya accidente. Vamos por orden.

Dónde te da el vuelco en el estómago (tres casos)

Tres “escenas peligrosas” típicas de principiante. En ninguna se hace nada del otro mundo.

Escena 1: quieres que te arregle un error y pegas el log entero

Cuando pides “arréglame este error”, copias y pegas todo lo que salió en la terminal, ¿verdad? Pero en ese log puede haberse colado una línea como DATABASE_URL=postgresql://usuario:contraseña_real@.... Creías que se la pasabas solo a la IA, pero la contraseña en crudo se queda también en el historial de la conversación y en los logs.

Escena 2: lo dejas en modo “de todo, encárgate tú” y te vas

Aprobar te da pereza, así que pones el modo que ejecuta lo que sea sin confirmar y te levantas de la mesa. La IA, con su mejor intención, suelta un git push --force y vuela el trabajo de alguien del equipo. Cero mala fe. Pero el resultado es pésimo.

Escena 3: confundes dos bases de datos con nombres parecidos

myapp_dev y myapp_prod. Una letra de diferencia. Si pides solo “borra los datos viejos de la base de datos” y la IA no comprueba a cuál está conectada, lo que se borra podrían ser los datos reales de tus clientes.

Lo que las tres tienen en común es que la IA ejecuta a toda potencia justo en el instante en que el humano “se despista”. Pues entonces, basta con dejarlo todo a prueba de despistes. En eso consisten las protecciones.

Tres metidas de pata que cometí yo

Escribo todo esto muy digno, pero yo también empecé lleno de accidentes. Confieso tres con honestidad.

La primera. Montando la publicación automática en Qiita, pegué el token directo en el prompt. Un “publica usando QIITA_TOKEN=xxxx”. Como funcionó, me quedé contento, pero luego caí: esa cadena se queda también en el log de la conversación y en el historial de la pequeña IA que corre por detrás (el subagente). Corriendo a regenerar el token. Ahora que lo pienso, sudores fríos.

La segunda. Para investigar, pedí “comprueba el contenido del .env”. La IA, muy obediente, me lo leyó todo en voz alta. Las claves de API y la contraseña de la base de datos, todo a la pantalla y a los logs. En el instante en que dejas que lo lea, es como si ya se hubiera “filtrado”. El .env ni siquiera yo, que soy humano, lo abro normalmente.

La tercera. Copié la configuración relajada de un proyecto personal a un repositorio de trabajo. Resultado: el “prohibido escribir en producción” que debía estar en el lado de trabajo quedó sobrescrito con la laxitud del proyecto de hobby. Me di cuenta antes de que pasara nada, pero reutilizar configuraciones es de verdad peligroso.

En todas, la causa no fue tanto falta de conocimiento como no haberlo frenado con un sistema. Y aquí empieza lo importante.

Defiende estas 5. Basta con hacerlas por orden

Protección 1: pon las claves API “fuera del código”

Es la más importante. Las claves API y los tokens, jamás los escribas directos en el código ni en el prompt. Aíslalos en un archivo dedicado llamado .env y sácalo de la gestión de Git. Solo con esto evitas la mayoría de las fugas.

Primero, el ejemplo de lo que NO hay que hacer.

// MAL: escrita directa en el código fuente (en cuanto haces commit, ya la has liado)
const client = new Anthropic({ apiKey: "pegar aquí la clave API real" });

// MAL: mezclarla en el prompt
// "publica usando QIITA_TOKEN=token_real" ← justo lo que yo metí la pata

Lo correcto es reunir las llaves en un archivo .env.

# .env (este archivo NO se sube a Git. Se queda solo en tu propio ordenador)
ANTHROPIC_API_KEY=aquí el valor real
QIITA_TOKEN=aquí el valor real
DATABASE_URL=postgresql://...

Y luego declaras que ese .env “Git no lo recoja jamás”. Este es el cabo de vida.

# Escríbelo siempre en .gitignore (el seguro para no hacer commit de las llaves sin querer)
.env
.env.*
!.env.example   # solo el ejemplo sí se puede compartir
*.pem
*.key
*-service-account.json   # no te olvides tampoco de las claves de cuenta de servicio de la nube

Cuando solo quieras decirle al equipo “qué llaves hacen falta”, colocas un ejemplo con los valores vacíos.

# .env.example (este sí se sube a Git. El contenido va vacío)
ANTHROPIC_API_KEY=
QIITA_TOKEN=
DATABASE_URL=

Desde el código, en lugar de escribir el valor del archivo directo, lo lees como “variable de entorno”. La llave de verdad no aparece por ninguna parte del código.

// BIEN: leer de la variable de entorno. El valor no se escribe nunca en el código
import { config } from "dotenv";
config();

const token = process.env.QIITA_TOKEN;
if (!token) {
  // Si no hay llave, no muestres el valor; di solo "se te olvidó configurarla"
  throw new Error("QIITA_TOKEN no está configurado. Revisa el .env.");
}

La clave es una sola. Lo único que toca la llave de verdad es el interior del .env. El código, el prompt y los logs solo conocen el “nombre” de la llave. Esto es el abecé.

Protección 2: no dejes que los comandos peligrosos se “aprueben solos”

Lo siguiente: comandos sin marcha atrás como rm -rf (borrado en bloque) o git push --force (sobrescribir el trabajo del equipo). Estos se configuran como “antes de ejecutarlos, pregúntale siempre al humano” o directamente como “imposible de ejecutar”.

Claude Code tiene un mecanismo para decidir, comando a comando, “OK / requiere confirmación / prohibido”. Lo escribes así en .claude/settings.json.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(curl * | bash)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)"
    ]
  }
}

Leerlo es simple. Solo repartes en tres cajas.

Caja	Significado	Qué metes
`allow`	Ejecutar OK sin confirmar	Operaciones seguras de solo lectura
`ask`	Preguntar siempre como es debido	Escribir, commit, push
`deny`	No dejar hacerlo nunca	Borrar, force push, base de datos de producción

Si dudas, quédate con esto: leer solo, allow; escribir, ask; borrar, deny. Al principio apriétalo a tope, y solo las operaciones que confirmes “ah, esto sí es seguro”, las asciendes después a ask o allow. El sentido contrario (empezar laxo y apretar después) llega siempre después del accidente, así que empieza sí o sí por la dirección de apretar.

Protección 3: acota el “alcance” de lectura y escritura

Mira bien el deny de la protección 2. Arriba del todo hay unas líneas así.

"deny": [
  "Read(./.env)",
  "Read(./.env.*)",
  "Read(./secrets/**)"
]

Esto configura que “el .env y la carpeta secrets está prohibido hasta leerlos”. El accidente de “dejar que leyera el .env” que yo provoqué no habría ocurrido con esta sola línea. Porque aunque pidas “compruébalo”, le da con la puerta en las narices.

Acotar el alcance es trazar de antemano la línea entre el sitio que se puede enseñar y el que no. La carpeta con las llaves, la configuración de producción, los datos de los clientes. Si los dejas “directamente intocables”, aunque pidas algo sin querer, estás a salvo.

Además, los archivos que no quieres que edite por nada del mundo, conviene escribirlos también en las reglas del proyecto (CLAUDE.md), en tu idioma.

## Archivos prohibidos de editar (escribir en CLAUDE.md)

Lo siguiente, no editar jamás. Si hace falta, confirma siempre conmigo (humano).
- .env (contiene llaves y contraseñas)
- wrangler.toml (configuración de publicación de producción)
- .github/workflows/*.yml (configuración del despliegue automático)

Bloqueas mecánicamente con el archivo de configuración y, con el texto de reglas, le transmites también la intención a la IA. Con esta doble red, bajan los huecos.

Protección 4: no saques información secreta a los logs

Esto, más que configuración, es una pequeña costumbre al escribir. Cuando escribas un mensaje de error, no saques junto el “valor” de la llave.

// MAL: la clave API sale tal cual en el log de error
throw new Error(`Fallo de autenticación: token=${process.env.TOKEN}`);

// BIEN: no muestres el valor, di solo dónde mirar
throw new Error("Fallo de autenticación: revisa la variable de entorno TOKEN");

Es una diferencia de una sola línea, pero la de arriba filtra la llave en el momento en que le enseñas el log a alguien.

Y una cosa más. Cuando le pases un log a la IA, no lo pegues en crudo. Las líneas con llaves o contraseñas, sustituye el valor por censura antes de pasarlo.

# Reescríbelo así antes de pasarlo. A la IA le basta con entender la estructura "hay datos de conexión a la BD"
DATABASE_URL=***censurado***
QIITA_TOKEN=***censurado***

“Lo que se puede pasar” y “lo que no”, a grandes rasgos, en una tabla. Si la pegas en CLAUDE.md, recuerdas el criterio cada vez que pides algo.

Se puede pasar	NO se puede pasar
Tipo de error, pasos para reproducir, nombre de archivo	Clave API, contraseña, cookie de sesión
`.env.example`, el “nombre” de los campos de configuración	URL de la BD de producción, datos de clientes
Logs con el valor sustituido por censura	Token real, archivo .json de cuenta de servicio

Protección 5: trata lo de producción “aparte”

Lo último. Separa con claridad lo de práctica (desarrollo) y lo de producción. Para evitar confundir myapp_dev con myapp_prod, funciona obligar a un paso extra para escribir en producción.

// scripts/db-query.mjs
const env = process.env.NODE_ENV ?? "development";

// Si intenta escribir en producción, lo para salvo que exista una bandera dedicada
if (env === "production" && process.argv.includes("--write")) {
  console.error("Escribir en producción requiere la bandera --force-production.");
  process.exit(1);
}

Bloqueas físicamente el “producción sin querer” con el paso extra de una bandera. Esa molestia es el cabo de vida. Los datos de producción, si los borras, no vuelven.

Si vas a empezar, empieza por aquí (procedimiento)

No hace falta hacer las 5 hoy. Si lo haces por orden, lo terminas en 30 minutos.

Crea un .env en el proyecto y mueve todas las llaves ahí.
Añade .env a .gitignore (protección 1).
Crea .claude/settings.json y mete en deny el rm -rf y la lectura del .env (protecciones 2 y 3).
Mete en ask lo de escribir y hacer commit (protección 2).
Pega en CLAUDE.md la tabla de “se puede / no se puede pasar” y los archivos prohibidos de editar (protección 4).

Con solo los tres primeros pasos ya frenas el accidente del rm -rf y la fuga del .env del principio. No busques la perfección; primero, uno. Con eso ya avanzas suficiente.

Cuando te entren ganas de afinar más los permisos, mira la guía de configuración de permisos de Claude Code; y si quieres conocer las historias crudas de accidentes que pasaron de verdad, lee los casos de fallos de seguridad de Claude Code. Para las especificaciones exactas de la configuración, lo mejor es siempre la documentación oficial.

Lo que pasó cuando lo probé de verdad

Desde el susto del rm -rf del principio, dejé de torturarme con si me fío o no de la IA. Lo que miro ahora es otra cosa: en qué guardián se frenó.

Cuando añadí al deny la lectura del .env, la IA empezó a retirarse obediente aunque le pidieras “comprueba las variables de entorno”. Aquel incómodo “te lo leo todo en voz alta” no vuelve a ocurrir.

Te seré sincero: el día que escribí la configuración pensé “igual me estoy pasando”. Pero fue al revés. Justo porque hay guardas, puedo relajarme con tranquilidad. Si puedo pulsar el botón de aprobar a la ligera es porque sé que las operaciones peligrosas las frena antes el deny. En vez de esforzarme por dominar una IA lista, tender primero un suelo en el que, si me caigo, no me hago daño. Esa es, a día de hoy, mi conclusión: es lo más cómodo y lo más rápido.

En resumen

Para un principiante, con defender estas 5 es suficiente.

Qué defender	Cómo
No filtrar las claves API	Aislar en `.env` + `.gitignore`
No descontrolar los comandos peligrosos	`rm -rf` / force push en `deny`
Acotar el alcance de lectura y escritura	`.env` y secrets en `deny`, archivos de producción prohibidos de editar
No sacar secretos a los logs	No mostrar el valor, pasar censurado
Tratar producción aparte	Bloquear la escritura en producción con una bandera

Cuando oyes “seguridad” te pones en tensión, pero lo que hay que hacer es solo “montar de antemano un sistema en el que no haya accidentes”. Una vez metido, te protege solo aunque lo dejes estar. Hoy, 30 minutos. Con eso borras de un plumazo un futuro accidente gordo.

Y si dudas de “¿hasta dónde debemos atar esto en mi equipo?”, también tengo materiales y soporte preparados. Para empezar, asómate al listado de materiales.