Permissões do Claude Code: proteja .env, Git e comandos perigosos

Ao configurar o Claude Code, desenvolvedores costumam cair em uma escolha falsa: confirmar sem parar comandos de leitura triviais ou ativar o bypass completo (--dangerously-skip-permissions) e arriscar um vazamento de .env, um git push --force acidental ou um ambiente de projeto quebrado.

Nenhum dos extremos é eficaz. Uma configuração segura segue o princípio do menor privilégio: acesso de leitura, permissões de escrita, execução de shell e controle de versão precisam estar claramente separados.

---

1. Mapa de permissões: da leitura ao impacto externo

Organize arquivos e comandos em quatro níveis de acesso:

Nível	Operações	Política padrão	Exemplos
1. Inspeção de código	Ler arquivos do projeto	Permitido (sem confirmação)	cat, grep, visualizar código em src/
2. Segredos e configuração	Acessar .env, chaves e tokens	Estritamente proibido	.env*, id_rsa, *.pem, credentials.json
3. Edição de arquivos	Criar e modificar código	Permitido dentro do workspace	write_to_file, replace_file_content
4. Shell e Git perigosos	Gerenciadores de pacote e operações destrutivas	Aprovação manual obrigatória	rm -rf, git push --force, npm publish, DROP TABLE

---

2. Isole arquivos .env e segredos do projeto

Transport Layer Security (TLS) criptografa o tráfego de API enquanto ele percorre a rede. Isso não impede que credenciais confidenciais entrem na janela de contexto do modelo, em logs de erro ou em resumos de handoff.

Para impedir que o Claude Code ingira credenciais privadas:

1. Adicione ao .gitignore todos os arquivos de ambiente que contenham segredos.
2. Forneça um modelo .env.example limpo, com valores fictícios. Assim, o agente entende os nomes das variáveis sem ver valores de execução.
3. Registre uma regra de limite rígida no CLAUDE.md ou AGENTS.md:

## Regra de proteção de segredos

- Nunca inspecione, exiba ou transmita conteúdo de `.env`, `.env.local` ou arquivos de chave privada.
- Para verificar as chaves de configuração necessárias, examine `.env.example`.

[!IMPORTANT] Gerenciamento de chaves de API: sua chave de API do Claude Code é configurada no ambiente local e jamais deve ser commitada em arquivos do repositório. Siga o fluxo de integração da documentação BetterToken para Claude Code.

.gitignore evita um commit acidental, mas não impede o agente de ler o arquivo. Instruções em CLAUDE.md ou AGENTS.md registram intenção, não uma barreira técnica. Combine-as com regras atuais de permissão e o sandbox do sistema:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": [
        "./**/.env",
        "./**/.env.*",
        "./secrets"
      ]
    }
  }
}

O deny Read cobre ferramentas internas e comandos de arquivo reconhecidos. Um subprocess arbitrário em Python ou Node pode ler de outra forma, portanto o sandbox fornece a barreira no sistema operacional. failIfUnavailable e allowUnsandboxedCommands falham de forma fechada, sem fallback não isolado. O sandbox não é compatível com Windows nativo; use WSL2 ou contêiner. Em ambiente gerenciado, o administrador deve impedir que a configuração do projeto enfraqueça a policy.

---

3. Checklist priorizado para Git e comandos

Ao executar tarefas com Claude Code, siga primeiro esta hierarquia:

O agente propõe um comando
  │
  ├─> Ele contém padrões destrutivos (rm -rf, drop, force push)?
  │     └─> SIM: Rejeite ou execute manualmente sob supervisão do desenvolvedor
  │
  └─> Ele toca em internos de .git, arquivos .env ou redes externas?
        │
        ├─> SIM: Exija justificativa explícita e limite o escopo
        │
        └─> NÃO: Aprove a execução na branch de destino

Barreiras passo a passo

1. Passo 1: bloqueie mutações de Git. Nunca permita pushes automatizados diretamente para main sem um git diff --check manual e a execução dos testes.
2. Passo 2: isole a instalação de pacotes. Comandos como npm install <package> ou scripts curl remotos precisam de verificação manual para evitar dependências não confiáveis e riscos na cadeia de suprimentos.
3. Passo 3: restrinja o escopo de diretórios. Limite o workspace do agente a uma pasta específica da funcionalidade ou a um Git worktree dedicado.

---

4. Acesso à produção é outra barreira

Permissões locais não substituem IAM, política de rede ou aprovação do sistema de produção. Prefira nenhum acesso. Se o diagnóstico exigir, forneça um papel read-only curto e limitado ao recurso. Escrita exige aprovação separada com comando, alvo, janela, validação, observador e rollback. Se o resultado for incerto, leia o estado real antes de repetir. O audit log registra identidade, recurso, ação e resultado sem segredos nem payloads sensíveis; depois, revogue a credencial temporária. Nunca copie uma credencial para HANDOFF.md.

5. Valide as permissões em um workspace de teste

Antes de conceder ao Claude Code acesso a repositórios importantes, faça uma validação em sandbox:

1. Crie uma branch de teste descartável: git checkout -b test/permission-check.
2. Adicione um arquivo .env de exemplo com um segredo de teste fictício.
3. Peça ao agente para refatorar o módulo de autenticação.
4. Verifique se:
   • o agente não leu o .env fictício durante a exploração;
   • nenhum token secreto apareceu em logs de erro, comentários ou git diff;
   • os testes unitários são executados sem acessar arquivos não autorizados.
5. Limpe a branch de teste depois de confirmar os limites.

Essa fronteira de permissões protege as credenciais e preserva uma execução autônoma rápida.