Guía práctica para gestionar variables de entorno y secretos con Claude Code

Subir por accidente una API key a GitHub y empezar a sudar frío — todos los desarrolladores lo hemos vivido. El 90% de las filtraciones de secretos son error humano. Si integras Claude Code puedes imponer seguridad de forma mecánica, desde el setup del .env hasta la detección, rotación y respuesta a incidentes.

1. Automatizar el setup del .env

Los nuevos desarrolladores sufren recopilando las variables. Genera desde .env.example.

claude -p "
Read .env.example and interactively create a .env for this project.

For each variable:
1. What it's for
2. Where to get it (with URLs)
3. Recommended local dev value
4. Required or optional

Confirm .env is gitignored before saving.
"

Acelera muchísimo el onboarding de nuevos desarrolladores.

2. Bloquear commits accidentales con pre-commit

Atrapa los secretos en el momento en que alguien ejecuta git commit.

claude -p "
Create .husky/pre-commit.

Requirements:
- Check staged files for:
  - AWS access keys: AKIA[0-9A-Z]{16}
  - Stripe: sk_live_[0-9a-zA-Z]{24}
  - GitHub PAT: ghp_[0-9a-zA-Z]{36}
  - Generic API-key-looking strings
- Reject commit and show file/line on detection
- Allow // secrets-ignore comment for false positives

Also compare with trufflehog and gitleaks, and
recommend a team-friendly setup.
"

gitleaks es el estándar del sector — combinado con Claude Code puede remediar hallazgos automáticamente.

3. Auditar el historial de commits existente

Comprueba si quedan filtraciones pasadas.

claude -p "
Scan the entire commit history for secrets:

1. Run gitleaks detect --source . --no-git
2. Categorize findings (active / already revoked / false positive)
3. For active leaks, show immediate rotation steps
4. Git history purge steps (git filter-branch or BFG Repo Cleaner)

Output to docs/security/secret-audit.md (treat as confidential).
"

:::message alert Secretos filtrados = revocar y rotar de inmediato

Aunque limpies la historia, asume que los forks y cachés ya lo tienen. :::

4. Mantener .env.example sincronizado

Actualiza .env.example automáticamente cuando cambie .env.

claude -p "
Compare .env and .env.example:

1. Vars in .env but not .env.example → add with placeholders
2. Vars in .env.example but not .env → propose removal if obsolete
3. Improve comments (purpose docs)
4. Confirm secret values remain as placeholders

Save .env.example in a git-diff-reviewable state.
"

5. Migrar secretos de producción a un Secrets Manager

Mueve los secretos de prod desde .env a AWS Secrets Manager / Cloudflare Secrets / Doppler.

claude -p "
Migrate 10 production secrets from .env to AWS Secrets Manager:

1. aws secretsmanager create-secret commands
2. Least-privilege IAM read policy
3. App-side fetch code (with caching)
4. Deploy procedure (cut over from .env)
5. Rollback plan

Output Terraform definitions too.
"

Estado final: ningún secreto de producción vive en el código ni en los repos.

6. Programar rotación periódica de secretos

Rotar cada 90 días, de forma automática.

claude -p "
Design a script to auto-rotate API keys for Stripe, OpenAI, Resend every 90 days:

1. Issue new keys via each service's API
2. Save to Secrets Manager / Cloudflare Secrets
3. Trigger deploy to pick up new keys
4. Revoke old keys
5. Append to docs/security/rotation-log.md

Provide a monthly GitHub Actions schedule YAML.
"

La rotación a 90 días suele ser además un requisito de compliance.

7. Playbook de incidentes ante filtraciones

Prepárate para no entrar en pánico cuando pase.

claude -p "
Write docs/security/incident-playbook.md for:

Scenario: AWS access key accidentally committed to a public GitHub repo

0-15 min:
- Revoke key in AWS Console
- Make the repo private

15 min - 1 hour:
- Check CloudTrail for unauthorized use
- Remove key from git history (git filter-branch)
- Issue new key, register in Secrets Manager

1 hour+:
- Notify security team
- Decide on customer disclosure

Include exact commands and designated owners.
"

Codifica las reglas de seguridad en CLAUDE.md

Limita el comportamiento del propio Claude Code.

## Secret Handling Rules

### Forbidden
- Hardcoding .env values in source code
- Logging API keys (including console.log)
- Putting secrets in comments
- Putting secrets in README / docs

### Required
- Update .env.example whenever API keys change
- Register new external service keys in Secrets Manager
- Pre-commit secret scan must pass

### AI Instructions
- Always use process.env.XXX for key values in generated code
- Never copy .env contents elsewhere
- Route secret-related changes through human review

Así se reduce la probabilidad de que Claude Code hardcodee una key por accidente.

Anti-patrones

❌ Dejar que .env.example quede desactualizado

Los nuevos miembros no pueden arrancar la app y se arma el caos. Mantenlos sincronizados.

❌ Compartir API keys por Slack / Zoom

Viven para siempre en el historial. Usa herramientas de secret-sharing (1Password / Doppler).

❌ Loggear datos sensibles

console.log(req.headers) expone el header Authorization. Enmascara con agresividad.

❌ Pensar “nadie lo notará”

Los bots detectan y explotan claves en 5 segundos. Trata cada commit como público.

Conclusión

• Configurar el .env de forma interactiva
• Pre-commit detecta filtraciones de secretos
• Auditar commits históricos
• Mantener sincronizado .env.example
• Migrar secretos de prod a un Secrets Manager
• Automatizar la rotación cada 90 días
• Preparar un playbook de incidentes
• Limitar el comportamiento de la IA en CLAUDE.md

La gestión de secretos es un problema sistémico. Claude Code te permite pasar de comprobaciones ad hoc a redes de seguridad mecánicas.

Relacionados: Auditoría de seguridad / Cabeceras de seguridad web / Guía de Hooks

Documentación oficial: Anthropic Claude Code / gitleaks