Programação com IA

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

Guia prático para restringir permissões do Claude Code: isolar segredos, controlar comandos Git e shell e testar as barreiras de segurança antes de acessar um repositório de produção.

BT

BetterToken

Equipe editorial
4 min de leitura

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ívelOperaçõesPolítica padrãoExemplos
1. Inspeção de códigoLer arquivos do projetoPermitido (sem confirmação)cat, grep, visualizar código em src/
2. Segredos e configuraçãoAcessar .env, chaves e tokensEstritamente proibido.env*, id_rsa, *.pem, credentials.json
3. Edição de arquivosCriar e modificar códigoPermitido dentro do workspacewrite_to_file, replace_file_content
4. Shell e Git perigososGerenciadores de pacote e operações destrutivasAprovação manual obrigatóriarm -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](https://docs.bettertoken.ai/ai-tools/claude-code).

---

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

Quer otimizar seu fluxo de trabalho com LLMs?

Conecte modelos por uma única API, gerencie chaves e controle os gastos com IA.