Cómo mantener tus secretos fuera del código generado por IA y de los commits de Git

Los agentes de codificación con IA son rápidos, pero tienen un punto ciego: pegan alegremente una clave de API en un archivo, vuelcan un token en un log o hacen commit de un .env que pretendías mantener en local. Todo agente con acceso a la terminal —Claude Code, Cursor, Gemini CLI, Codex— también puede leer la configuración de tu shell y los archivos de tu proyecto, que es exactamente donde tienden a esconderse las credenciales. Esta guía recorre una configuración práctica y por capas para que tus secretos permanezcan fuera del código generado por IA y fuera de tu historial de Git.

Por qué esto importa más con la IA

Una clave filtrada es uno de los errores más comunes y más caros en el software, y los asistentes de IA elevan lo que está en juego de dos maneras. Primero, generan código rápidamente, así que una clave incrustada en el código puede acabar en una docena de archivos antes de que te des cuenta. Segundo, los agentes ingieren contexto de forma agresiva: como lo expresa un artículo sobre gestión de secretos, la configuración de tu shell debería referenciar las claves, no contenerlas, porque el agente puede leer todo lo que tus dotfiles expongan. La solución no es desconfiar de la herramienta; es asegurarte de que no haya secretos en texto plano para que los encuentre, en primer lugar.

Paso 1: Guarda los secretos en variables de entorno, nunca en el código

La regla base: ninguna clave de API, contraseña o token debería aparecer nunca como una cadena literal en el código fuente. Ponlos en un archivo .env en la raíz de tu proyecto y léelos en tiempo de ejecución.

# .env  — never committed
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgres://...

// app.js — reads from the environment, no secret in the file
const apiKey = process.env.ANTHROPIC_API_KEY;

De este modo, el código que tú (y tu agente de IA) editáis contiene solo el nombre del secreto, nunca su valor.

Paso 2: Asegúrate de que .env nunca pueda incluirse en un commit

Añádelo a .gitignore antes de escribir un solo secreto:

.env
.env.local
*.env

En su lugar, haz commit de un .env.example con marcadores de posición vacíos, para que los colaboradores sepan qué variables configurar:

ANTHROPIC_API_KEY=
DATABASE_URL=

Si ya hiciste commit de un .env real, eliminarlo en un nuevo commit no es suficiente: vive en el historial. Rota la clave expuesta de inmediato y trátala como comprometida.

Paso 3: Activa la protección de push de GitHub

La protección de push de GitHub escanea los commits a medida que haces push y bloquea el push si detecta un secreto, deteniendo la filtración antes de que llegue al remoto. Reconoce más de 200 patrones de secretos de proveedores como AWS, OpenAI, Stripe y muchos más, y las actualizaciones de 2026 ampliaron los patrones bloqueados de forma predeterminada. Es gratuita para los repositorios públicos: actívala en los ajustes de tu repositorio, en Settings → Code security. Piénsalo como un cinturón de seguridad para el momento en que un agente (o tú) cometa un desliz.

Paso 4: No dejes que los agentes recolecten la configuración de tu shell

Los agentes con acceso al shell pueden leer .zshrc, .bashrc y .zshenv. Si has exportado claves ahí por comodidad, el agente puede verlas. Mantén los secretos de toda la máquina fuera de tus dotfiles: cárgalos desde un gestor de secretos o el llavero del sistema operativo bajo demanda, en lugar de exportar texto plano al iniciar el shell.

Paso 5: Limita el alcance y rota

Dos hábitos limitan el daño si algo llega a filtrarse, un consejo que también recoge la guía de seguridad de claves de API de OpenAI:

• Privilegio mínimo: dale a cada clave el alcance más reducido que necesite y usa claves separadas por proyecto y por entorno, de modo que una filtración no lo exponga todo.
• Rota con regularidad: rota las claves según un calendario e inmediatamente cuando sospeches que hubo una exposición. Una clave rotada convierte una brecha en un no-evento.

Una lista de comprobación rápida

Antes de soltar un agente sobre un repositorio:

1. Los secretos viven en .env y se leen mediante process.env, nunca incrustados en el código.
2. .env está en .gitignore; solo se hace commit de .env.example.
3. La protección de push está activada en el remoto.
4. No hay claves en texto plano en los dotfiles del shell.
5. Las claves tienen un alcance reducido y se rotan según un calendario.

Nada de esto te ralentiza una vez configurado, y te permite delegar más trabajo a tu agente de IA con mucho menos de qué preocuparte.