Guia prático para gerenciar variáveis de ambiente e segredos com Claude Code

Fazer commit acidental de uma API key no GitHub e começar a suar frio — todo desenvolvedor já passou por isso. 90% dos vazamentos de segredos são erro humano. Conecte o Claude Code e você consegue impor segurança de forma mecânica, do setup do .env à detecção, rotação e resposta a incidentes.

1. Automatize o setup do .env

Novos desenvolvedores sofrem ao reunir as variáveis de ambiente. Gere a partir do .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 drasticamente o onboarding de novos desenvolvedores.

2. Bloqueie commits acidentais via pre-commit

Capture segredos no exato momento em que alguém roda 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.
"

O gitleaks é o padrão da indústria — combinado com o Claude Code pode remediar automaticamente as ocorrências.

3. Audite o histórico de commits existente

Verifique se ainda há vazamentos antigos.

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 Segredos vazados = revogar e rotacionar imediatamente

Mesmo purgando o histórico, assuma que forks e caches já têm o valor. :::

4. Mantenha o .env.example sincronizado

Atualize o .env.example automaticamente quando o .env mudar.

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. Migre segredos de produção para um Secrets Manager

Mova os segredos de produção do .env para o 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: nenhum segredo de produção vivendo em código ou repositório.

6. Agende rotação periódica de segredos

Rotacionar a cada 90 dias, automaticamente.

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.
"

A rotação em 90 dias também costuma ser exigência de compliance.

7. Playbook de incidentes para vazamentos

Prepare-se para não entrar em pânico quando acontecer.

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.
"

Codifique as regras de segurança no CLAUDE.md

Restrinja o comportamento do próprio 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

Isso reduz a chance de o Claude Code hardcodear uma chave por acidente.

Anti-padrões

❌ Deixar o .env.example defasado

Os novos membros não conseguem rodar a aplicação e o caos se instala. Mantenha ambos em sincronia.

❌ Compartilhar API keys no Slack / Zoom

Elas vivem para sempre no histórico. Use ferramentas de compartilhamento de segredos (1Password / Doppler).

❌ Logar dados sensíveis

console.log(req.headers) expõe o header Authorization. Mascare com rigor.

❌ Achar que “ninguém vai notar”

Bots detectam e exploram chaves em 5 segundos. Trate cada commit como público.

Conclusão

• Configurar o .env de forma interativa
• Pre-commit detecta vazamentos de segredos
• Auditar commits históricos
• Manter o .env.example sincronizado
• Migrar segredos de prod para um Secrets Manager
• Automatizar a rotação de 90 dias
• Preparar um playbook de incidentes
• Restringir o comportamento da IA no CLAUDE.md

Gestão de segredos é um problema sistêmico. O Claude Code permite sair das checagens ad hoc para redes de segurança mecânicas.

Relacionados: Auditoria de segurança / Cabeçalhos de segurança web / Guia de Hooks

Documentação oficial: Anthropic Claude Code / gitleaks