Permissões do Claude Code: settings.json seguro para iniciantes

Você quer apenas que o Claude Code rode os testes, mas uma janela de confirmação aparece a cada comando. No extremo oposto, liberar Bash por completo também pode deixar passar exclusões, hard reset e push --force sem revisão.

Não é preciso escolher entre confirmar tudo e liberar tudo. Uma configuração inicial segura permite leituras e testes, pede confirmação para edições e publicação de mudanças, e bloqueia segredos e operações destrutivas. Esses três níveis ficam no settings.json.

O que você precisa saber

A avaliação segue a ordem deny → ask → allow: primeiro bloqueia, depois pergunta e só então permite automaticamente.
Leituras dentro do projeto já dispensam confirmação. Coloque apenas testes revisados em allow, edição, acesso externo e push em ask, e segredos e operações destrutivas em deny.
Bash(git *) é amplo demais. Ele também alcança git reset --hard e git push --force.
Bloquear Read(.env) não contém qualquer processo filho. Para uma barreira forte, combine as regras com o sandbox.
Depois de salvar, use /permissions e /status para confirmar quais regras estão ativas e de qual arquivo elas vieram.

O que delegar ao Claude Code e o que uma pessoa deve decidir

O Claude Code pode executar	Uma pessoa deve revisar	Sempre bloquear
Buscar arquivos, conferir diferenças e rodar testes	Editar arquivos, fazer commit ou push, instalar dependências	Ler segredos, forçar push, executar hard reset ou excluir em massa
`Read`, `Grep`, `git diff`	`Edit`, `git commit`, `npm install`	`.env`, `git push --force`, `git reset --hard`, `rm -rf`

Operações difíceis de desfazer, envio de dados para fora do ambiente e acesso a credenciais devem ficar em ask ou deny.

Um settings.json seguro para começar

Crie .claude/settings.json na raiz do projeto e use esta configuração como ponto de partida. Ela é conservadora o bastante para ser compartilhada pelo time no Git.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)"
    ],
    "ask": [
      "Edit",
      "WebFetch",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git clean *)",
      "Bash(git restore *)",
      "Bash(npm install *)",
      "Bash(npm uninstall *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(**/secrets/**)",
      "Edit(.env)",
      "Edit(.env.*)",
      "Edit(**/secrets/**)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)",
      "Bash(rm *)",
      "PowerShell(Remove-Item *)"
    ]
  }
}

Esta base pressupõe que você revisou os scripts do package.json. Em um repositório desconhecido, deixe allow vazio até entender o que o teste executa. Bash(npm test *) corresponde a npm test e às formas com argumentos.

Onde colocar o settings.json

Escopo	Local	Uso
User	`~/.claude/settings.json`	Preferências comuns a todos os seus projetos
Project	`.claude/settings.json`	Padrão do time, compartilhado pelo Git
Local	`.claude/settings.local.json`	Ajustes pessoais desta máquina; não entram no Git
Managed	Configuração distribuída por um administrador	Política organizacional que não pode ser sobrescrita pelo usuário

A precedência é Managed, linha de comando, Local, Project e User. Arrays como permissions.allow são concatenados entre escopos, não substituídos por inteiro. Uma correspondência em deny vem antes de ask e allow. Coloque bloqueios comuns em Project e políticas imutáveis em Managed.

Como interpretar allow, ask e deny

Regra	Significado
`Read`	Corresponde a todas as leituras integradas; um allow global costuma ser desnecessário dentro do projeto
`Bash(npm test)`	Corresponde exatamente a `npm test`
`Bash(npm test *)`	Corresponde a `npm test` e a argumentos posteriores
`Bash(ls*)`	Também pode corresponder a `lsof`; é mais amplo do que parece
`Read(//Users/me/secrets/**)`	Caminho absoluto a partir da raiz do sistema de arquivos
`Edit(/src/*/.ts)`	Em Project, corresponde aos arquivos TypeScript abaixo de `src` do projeto
`WebFetch(domain:docs.anthropic.com)`	Corresponde a acessos WebFetch ao domínio informado

Uma regra como Bash(git *) inclui git push origin main, mas também inclui git reset --hard. Autorize comandos específicos em vez de liberar todo o Git.

Por que Read e Edit não protegem segredos sozinhos

Os padrões de caminho de Read e Edit seguem a sintaxe do gitignore.

Sintaxe	Referência	Exemplo
`//path`	Raiz do sistema de arquivos	`Read(//Users/me/secrets/**)`
`~/path`	Diretório pessoal	`Read(~/.ssh/**)`
`/path`	Local-base do arquivo de configuração	Em Project: `Edit(/src/**)`
`path` ou `./path`	Diretório de trabalho atual	`Read(.env)`

Uma única barra no início não significa caminho absoluto. Read(.env) impede que a ferramenta integrada Read abra o arquivo, mas não serve como barreira geral para qualquer comando Bash ou processo filho. Um script Node.js, por exemplo, ainda pode abrir um arquivo diretamente se o sistema operacional permitir.

Quando o repositório contém credenciais, ative também o sandbox do Claude Code e aplique restrições no nível do sistema operacional. Regras de permissão e sandbox são camadas complementares.

Três casos de uso

Caso de uso 1: automatizar apenas os testes em um projeto pessoal

Entrada: código-fonte, testes e diferenças do Git. Saída: sugestão de correção e resultado dos testes. Revisão humana: edição, instalação de dependências, commit e push.

Use a configuração mínima e mantenha Edit em ask. Mova para allow somente uma operação segura que já se repete e cujo efeito você entende. Não libere Bash inteiro apenas para remover uma confirmação incômoda.

Caso de uso 2: bloquear operações perigosas para todo o time

Entrada: lista de comandos necessários e ações proibidas. Saída: configuração versionada no Git. Revisão humana: novas regras deny e exceções temporárias.

No escopo Project, bloqueie .env, push --force e reset --hard. Se a organização precisa impedir alterações nessas regras, mova a política para Managed settings.

Caso de uso 3: investigar um repositório de produção sem alterá-lo

Entrada: logs do incidente e histórico do Git. Saída: hipóteses de causa e plano de correção. Revisão humana: qualquer edição, deploy ou transmissão externa de dados.

Inicie o Claude Code em Plan Mode:

claude --permission-mode plan

Se a investigação exigir escrita, vá primeiro para uma branch de trabalho ou para um ambiente isolado. Só depois aprove a mudança.

Quatro falhas concretas e como corrigir

Falha	Causa	Correção
Liberar `Bash(git *)`	O padrão também inclui push e hard reset	Libere só comandos cujos efeitos foram revisados
Adicionar `allow: Bash(aws s3 ls)` sob `deny: Bash(aws *)`	Deny vence antes de ask e allow; especificidade não cria exceção	Reduza o deny ou separe a operação segura em outro comando
Tratar `Read(.env)` como isolamento do sistema	Processos arbitrários de Node.js ou Python não ficam totalmente bloqueados	Use `denyRead` ou credenciais do sandbox
Apagar um allow Local e ainda vê-lo ativo	Arrays são combinados entre User, Project e Local	Confira a origem em `/permissions` e os escopos em `/status`

Veja os casos de falha de segurança para incidentes e as boas práticas de segurança para revisar a implantação completa.

Como escolher o permission mode

Modo	Quando usar	Atenção
`default`	Primeiro contato com um repositório	Solicita confirmação quando necessário
`acceptEdits`	Desenvolvimento com escopo já compreendido	Aprova edições e operações comuns de arquivos
`plan`	Investigação, arquitetura ou leitura de incidente	Não altera o código-fonte
`auto`	Teste de tarefas longas com avaliação de segurança em segundo plano	É um recurso em evolução; confira a documentação atual
`dontAsk`	Automação sem interação e com operações pré-aprovadas	Rejeita o que não foi autorizado, sem perguntar
`bypassPermissions`	Contêiner ou VM descartável	Não use no computador de trabalho nem em produção

Com sandbox.autoAllowBashIfSandboxed: true, um comando Bash executado dentro do sandbox pode rodar sem pergunta mesmo que haja uma regra ask para Bash. Regras deny explícitas continuam valendo. Confirme essa interação antes de contar com uma tela de aprovação.

Pitfall: liberar demais e depender só de um hook

Um erro comum é colocar todo Bash em allow e usar um único hook PreToolUse para bloquear operações perigosas. Se o hook não carregar, tiver uma condição incompleta ou usar um matcher errado, a única barreira desaparece.

Causa: a permissão-base é ampla demais e toda a proteção depende de uma verificação dinâmica.

Correção: escreva primeiro os deny explícitos e mantenha os allow estreitos. Use hooks apenas como camada adicional para decisões dinâmicas. Uma correspondência em deny ou ask continua prevalecendo mesmo que o hook devolva allow.

JSON e JavaScript prontos para copiar

Salve o JSON do início do artigo em .claude/settings.json. Depois crie scripts/check-claude-permissions.mjs com o código abaixo. Ele verifica se o JSON é válido e se quatro bloqueios mínimos ainda estão presentes.

// scripts/check-claude-permissions.mjs
import { readFileSync } from "node:fs";

const path = ".claude/settings.json";
const settings = JSON.parse(readFileSync(path, "utf8"));
const deny = new Set(settings.permissions?.deny ?? []);
const required = [
  "Read(.env)",
  "Edit(.env)",
  "Bash(git push --force *)",
  "Bash(git reset --hard *)",
  "Bash(rm *)",
  "PowerShell(Remove-Item *)",
];

const missing = required.filter((rule) => !deny.has(rule));
if (missing.length > 0) {
  console.error(`Regras deny ausentes: ${missing.join(", ")}`);
  process.exit(1);
}

console.log("Verificação mínima de permissões: OK");

Execute na raiz do projeto:

node scripts/check-claude-permissions.mjs

Esse teste não prova que o repositório é seguro. Ele apenas permite detectar no CI quando alguém remove por engano um dos bloqueios mínimos.

O que verificar quando a configuração não funciona

Abra /permissions e confira a regra efetiva e o arquivo de origem.
Use /status para ver quais camadas de configuração foram carregadas.
Revise diferenças pequenas, mas importantes, como Bash(ls *) e Bash(ls*), ou /path e //path.
Confira a aprovação automática do sandbox e regras deny ou ask em escopos superiores.
Leve para .claude/settings.json toda regra que o time precisa compartilhar, em vez de deixá-la apenas em uma opção temporária da CLI.

Resumo

Comece colando a configuração mínima em .claude/settings.json e use /permissions para confirmar de onde cada regra veio.

Deixe apenas testes revisados em allow, edição e operações externas em ask, e segredos e comandos destrutivos em deny. Amplie as permissões apenas quando souber o efeito exato do comando.

Para adotar essa política junto com outras regras de desenvolvimento, consulte os materiais de Claude Code, que reúnem templates e checklists prontos.

Fontes oficiais

Resultado do teste realizado

Em 22 de julho de 2026, analisamos com JSON.parse o bloco JSON dos dez idiomas e executamos o controle Node.js em um projeto temporário. Com os seis deny obrigatórios, o processo terminou com código 0; sem Bash(git reset --hard *), terminou com código 1 e listou a regra ausente.

O teste usou apenas um fixture inventado: não havia credenciais, repositórios de clientes nem dados de produção, e o resultado não representa uma implantação real. Como a interface de permissões pode variar conforme o sistema operacional e a versão do Claude Code, confirme também /permissions e /status no seu ambiente.