Permissões do Claude Code: como desenhar autonomia sem abrir a produção · andersonlimadev

English summary: A practical framework for using Claude Code permissions, settings, allow/deny rules, hooks, human approval, and verification to give agents useful autonomy without granting production-level access by default.

TL;DR

Separe leitura, escrita e side effects.
Modele permissões como política executável e revisável.
Mantenha produção atrás de aprovação humana e evidência.

Exemplo concreto: uma alteração em código local pode ser automática; um deploy precisa de escopo e aprovação explícitos.

O comando que mais assusta num agent não é rm -rf. É o que parece inofensivo: uma correção de configuração, um kubectl apply, uma migração “pequena”, um git push para a branch errada. Quase nunca há uma intenção maliciosa. Há contexto incompleto, uma suposição errada e uma ferramenta com poder demais.

Claude Code acelera trabalho porque pode ler, editar e executar. Essa mesma capacidade torna permissões um problema de arquitetura, não uma preferência de interface. Se a segurança depende de o modelo sempre interpretar corretamente uma frase como “não mexa em produção”, o sistema já começou frágil.

A tese deste artigo é simples: autonomia útil nasce de permissões pequenas, efeitos reversíveis, gates humanos explícitos e evidência de verificação — não de desligar confirmações. O objetivo não é fazer o Claude Code trabalhar com medo. É tornar seguro deixar que ele trabalhe rápido onde o risco é baixo, e impossível ou deliberadamente lento onde o risco é alto.

As páginas de permissões, configurações e hooks do Claude Code são a fonte primária para a sintaxe discutida aqui; como modos e campos podem mudar entre releases, confira a documentação e a versão instalada antes de promover este desenho para um ambiente real. As referências foram verificadas para esta edição em agosto de 2026.

O que permissões são — e o que não são

Permissão é a decisão operacional sobre quais tools podem ser usadas, contra quais alvos e sob quais condições. Em Claude Code, isso inclui leitura de arquivos, escrita, comandos de shell e tools externas, inclusive MCP. Regras podem permitir, pedir confirmação ou negar chamadas específicas; o sistema avalia deny, depois ask, depois allow, portanto uma negação correspondente prevalece sobre uma permissão mais ampla (Configure permissions).

Isso não é o mesmo que instrução. Um CLAUDE.md dizendo “nunca faça deploy” é contexto valioso, mas continua sendo texto que o modelo precisa interpretar. Uma regra deny e um hook PreToolUse são controles executáveis. Eles reduzem o poder efetivo da tool antes que uma ação ocorra.

Também não é o mesmo que identidade. Uma credencial AWS com AdministratorAccess, um token GitHub com escopo amplo ou uma conexão de banco com escrita transforma qualquer erro de permissão local em incidente externo. O Claude Code decide se tenta uma tool; o provedor remoto ainda precisa conceder o menor conjunto possível de privilégios. As duas camadas são necessárias.

Por fim, não é uma justificativa para usar um agent em qualquer processo. Um workflow fixo — CI que executa testes e publica um artefato assinado — costuma ser melhor para passos previsíveis e repetitivos. Claude Code é mais útil quando precisa investigar, navegar contexto e propor mudanças. Quanto maior a liberdade de decidir a sequência, mais importante se torna limitar o raio de ação.

Uma forma prática de separar as responsabilidades é esta:

Camada	Pergunta que responde	Exemplo
Instrução	Qual comportamento esperamos?	`CLAUDE.md` exige testes e proíbe deploys autônomos
Permissão	Qual tool e alvo podem ser usados?	`Read(src/*)` e `Bash(pnpm test )` permitidos
Identidade	O que a credencial externa consegue fazer?	papel cloud apenas de leitura no ambiente de produção
Gate	Quem aprova efeito irreversível?	dono do serviço aprova uma migração ou publicação
Verificação	Como sabemos que a ação foi correta?	testes, diff, logs, change record e observabilidade

Se uma dessas linhas estiver vazia, as outras não compensam completamente. Um hook não salva uma credencial administrativa fora do seu escopo. Uma aprovação humana não é boa auditoria se ninguém consegue explicar o que foi aprovado. E testes verdes não tornam aceitável um comando executado no cluster errado.

As quatro falhas que abrem produção por acidente

Antes de desenhar a solução, vale reconhecer os quatro atalhos que mais aparecem em repositórios reais.

1. Tratar modo de permissão como política de segurança

Os modos do Claude Code definem a experiência de aprovação: default, acceptEdits, plan, auto, dontAsk e bypassPermissions têm comportamentos diferentes documentados pela Anthropic. Eles são úteis, mas não substituem uma política. plan reduz execução enquanto se explora o problema; acceptEdits remove atrito para alterações locais; dontAsk só permite o que já foi pré-aprovado. Nenhum deles, isoladamente, define o que uma organização considera operação crítica.

O caso mais perigoso é tratar bypassPermissions como atalho de produtividade. A documentação diz que ele pula prompts de permissão e recomenda uso apenas em ambientes isolados, como containers ou VMs. Mesmo que alguns comandos extremos acionem um circuito de proteção, isso não é uma fronteira de produção. Um diretório de trabalho com tokens, acesso a rede e credenciais montadas não vira seguro só porque está dentro de um container.

Use um modo para reduzir fricção em uma classe de trabalho; use regras, identidade e ambiente para definir a política. Em particular, a configuração de uma repository não deve ter o poder de ligar automaticamente uma experiência mais permissiva para todo desenvolvedor. Consulte a precedência documentada de configurações antes de depender de defaultMode em um escopo compartilhado.

2. Uma allowlist ampla que vira “pode executar tudo”

Bash(*) parece simples até você lembrar que shell é uma linguagem de composição: redirecionamentos, pipes, scripts chamados por scripts, variáveis e ferramentas remotas. Uma permissão ampla não é só “rodar comandos de desenvolvimento”; ela pode alcançar publicação de pacote, push, infraestrutura ou dados dependendo da máquina e das credenciais disponíveis.

O erro costuma vir de pensar em nomes de binários em vez de efeitos. git pode ser leitura de histórico ou pode publicar um branch. npm pode rodar lint ou executar um postinstall inesperado. kubectl pode listar pods ou aplicar uma mudança irreversível. A regra deve nomear o menor comando útil e, quando possível, restringir argumentos e contexto.

Também evite permitir segredos por conveniência. A própria documentação recomenda permissions.deny para impedir descoberta e leitura de .env, arquivos de credenciais e diretórios secretos. Isso reduz exposição acidental no contexto do modelo, mas não substitui secret management: o segredo idealmente nem está disponível na sessão que não precisa dele (Claude Code settings).

3. Usar hook como enfeite depois do efeito

Um PostToolUse que registra “deploy executado” é útil para observabilidade, mas não bloqueia o deploy: o efeito já aconteceu. Para prevenir um ato, o lugar relevante é antes da tool, tipicamente PreToolUse. Um comando de hook pode bloquear uma ação com saída 2; alternativamente, um hook pode retornar JSON estruturado para permitir, negar ou pedir confirmação, conforme o evento suporta (Hooks reference).

Isso cria uma consequência de design: hooks também têm superfície de ataque e de falha. Se um hook escreve logs, envia HTTP ou chama outro script, esses efeitos ocorrem mesmo quando outro hook decide negar a tool. A documentação alerta que hooks correspondentes são executados antes de os resultados serem combinados. Portanto, hooks que auditam precisam ser seguros para repetir e não devem produzir efeitos que você não aceitaria numa tentativa bloqueada.

4. Confirmação humana vaga e tarde demais

“Pergunte antes de algo perigoso” é uma regra mal definida. Quem responde? O que conta como perigoso? O humano vê o ambiente, o diff, a query e o blast radius, ou recebe uma caixa de diálogo genérica? Uma aprovação sem pacote de decisão vira um reflexo de clicar em “permitir”.

Approval humano funciona quando é um gate de mudança, não uma cerimônia. Defina um dono do serviço, o ambiente, o plano de reversão, a evidência de teste e a janela de impacto. Para operações de escrita em produção, o agente deve preparar o pacote e parar; o executor humano ou um pipeline com identidade controlada realiza a última ação.

O harness de segurança do Claude Code

Pensar em Claude Code como um harness ajuda a não concentrar toda a segurança em uma configuração. O harness junta contexto, tools, permissões, ambiente, verificação e observabilidade. Permissões são só uma camada, mas são a que transforma intenção em capacidade operacional.

Contexto: instruções deixam o comportamento legível

Use CLAUDE.md para declarar a fronteira do trabalho: ambientes permitidos, comandos de validação, donos de serviços e casos que exigem escalonamento. Ele não deve conter tokens, regras gigantes ou listas de exceções que só uma pessoa entende. O objetivo é diminuir ambiguidade antes de uma tool ser escolhida.

Exemplo de contrato curto:

# Operating agreement

- Este workspace é de desenvolvimento; produção é somente leitura.
- Alterações em `services/payments/**` exigem `pnpm test payments` e revisão do time Payments.
- Nunca aplique migrações, publique pacotes ou faça deploy a partir desta sessão.
- Para incidentes, colete evidência, proponha o plano e pare antes de qualquer escrita externa.

O contrato faz duas coisas: orienta o raciocínio e estabelece o momento de parar. Mas as linhas que realmente precisam resistir a erro devem reaparecer como regras ou hooks.

Tools e ambiente: reduza o que existe, não só o que é permitido

Least privilege fica mais forte quando o processo nem enxerga ferramentas e credenciais desnecessárias. Prefira:

container ou VM efêmera para tarefas de alto risco;
volume de trabalho sem diretórios de chaves montados;
variáveis de ambiente mínimas;
perfis cloud separados por ambiente;
credenciais curtas e read-only para investigação;
banco de produção acessível por uma réplica ou API de leitura, não por uma URL de escrita.

Esse desenho muda a pergunta de “o modelo vai obedecer?” para “qual é o pior efeito possível se ele errar?”. A segunda pergunta é verificável. E é nela que threat modeling começa a ser útil.

Permissões: escolha um default conservador e regras explícitas

No dia a dia, uma combinação comum é explorar em plan, editar localmente após revisão de plano e pré-aprovar apenas comandos de validação previsíveis. Para automação não interativa, dontAsk com allowlist pequena é mais defensável do que aceitar qualquer prompt automaticamente: uma tool fora da lista falha em vez de abrir uma nova superfície sem revisão.

As regras têm escopo e precedência. Configurações de usuário podem servir preferências locais; .claude/settings.json é compartilhável no projeto; .claude/settings.local.json deve conter experimentos ou escolhas pessoais e normalmente não entra no Git. Organizações com exigências fortes precisam de política gerenciada e identidade externa; não delegue controles mandatórios a um arquivo que o próprio repositório pode alterar. Veja a hierarquia em Settings.

Hooks: imponha invariantes objetivos

Hooks são apropriados para regras que podem ser avaliadas em dados da chamada da tool: bloquear um contexto de cluster, impedir git push, exigir que um arquivo de mudança exista ou registrar um identificador de aprovação. Eles não são bons para decidir se uma mudança “parece segura”; isso pede dono humano e contexto do negócio.

Para PreToolUse, a decisão de hook tem precedência restritiva entre hooks (deny vence ask, que vence allow). Porém regras deny e ask continuam sendo avaliadas mesmo que o hook tente permitir algo. Esse detalhe é excelente: mantenha proibições absolutas em regras e use hooks para política contextual ou logging.

Verificação e observabilidade: prove antes, durante e depois

Uma alteração local deve terminar com teste, typecheck, lint, diff revisto e uma declaração honesta do que não foi verificado. Uma mudança que toca um sistema externo exige também um registro de mudança, identidade do aprovador e sinais pós-ação. Para Claude Code, telemetria baseada em OpenTelemetry pode correlacionar decisões de tool com o tool_use_id exposto a hooks, quando habilitada e adequada à política de privacidade da empresa (Monitoring).

Não registre prompt integral, segredos, conteúdo de clientes ou comandos sensíveis apenas porque “é auditoria”. Auditoria boa é minimizada, retida pelo tempo necessário e acessível a quem precisa investigar.

Uma escada incremental de autonomia

O caminho seguro não começa com um agent autônomo em produção. Ele sobe por degraus e só avança quando cada degrau produz evidência.

Degrau	O agent pode fazer	Limite obrigatório	Evidência para avançar
Trabalho	Ler um problema e propor próximos passos	Sem tool externa	plano revisado por humano
Contrato	Usar contexto e comandos documentados	`CLAUDE.md` com stop conditions	tarefas repetíveis sem ambiguidade
Skill	Executar um playbook local	saída estruturada e testes definidos	taxa de sucesso e falhas conhecidas
Agent	Editar workspace isolado	diff, testes e revisão	mudanças reversíveis verificadas
Hooks/MCP	Consultar ou integrar sistemas	tools mínimas, escopo read-only	logs e teste do controle
Autonomia limitada	Fazer ações pré-aprovadas	allowlist, orçamento e kill switch	incidentes e exceções revisados
Evals	Repetir cenários adversariais	promoção bloqueada por regressão	métricas de segurança e qualidade

O ponto crucial é que autonomia não é um estado binário. Um agent pode ter alta autonomia para criar uma branch efêmera e baixa autonomia para tocar uma tabela financeira. Essa assimetria é saudável. O mesmo modelo pode operar com diferentes conjuntos de tools por tarefa, agente especializado ou ambiente.

Artefato copiável: baseline de projeto para desenvolvimento seguro

O exemplo abaixo é um ponto de partida para um repositório de aplicação. Ele permite leituras e validações locais comuns, torna efeitos de publicação explícitos em ask e bloqueia segredos e alguns comandos destrutivos. Não é uma política universal: adapte caminhos, package manager e comandos reais do seu projeto. Antes de adotá-lo, teste as regras em uma cópia do repositório e valide a sintaxe contra a versão instalada de Claude Code.

Arquivo .claude/settings.json:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm test *)",
      "Bash(pnpm typecheck)",
      "Bash(git diff *)",
      "Bash(git status)",
      "Bash(git log *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)",
      "Bash(pnpm publish *)",
      "Bash(kubectl *)",
      "Bash(terraform apply *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-production-side-effects.sh"
          }
        ]
      }
    ]
  }
}

E o arquivo executável .claude/hooks/block-production-side-effects.sh:

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
command="$(jq -r '.tool_input.command // empty' <<<"$input")"

# Ajuste os padrões ao vocabulário e aos contextos reais da sua plataforma.
if grep -qiE \
  'kubectl .*(apply|delete|patch|scale)|terraform (apply|destroy)|\
   (psql|mysql).*(production|prod)|npm publish|pnpm publish' \
  <<<"$command"; then
  echo "Blocked: external write requires an approved change outside Claude Code." >&2
  exit 2
fi

O script requer bash e jq. Ele lê o JSON do hook em stdin, examina a intenção de shell e usa exit 2 para bloquear a chamada antes de ela ocorrer. Não o trate como detector infalível: shell é complexo e nomes de ambientes variam. Por isso o baseline também usa ask, nega comandos ou leituras claramente proibidos e, principalmente, pressupõe que a sessão não tenha credenciais de escrita em produção.

Há duas escolhas deliberadas aqui. A primeira é pedir confirmação para classes inteiras de side effect, mesmo quando algumas instâncias seriam inofensivas. É uma pequena taxa de atrito em troca de uma fronteira fácil de explicar. A segunda é não usar uma regra de allow genérica para Bash; qualquer comando novo aparece como decisão, em vez de virar capacidade implícita.

Depois de instalar, abra /permissions para inspecionar de qual arquivo cada regra veio e /hooks para verificar os hooks carregados. Execute casos inofensivos que exercitem allow, ask e deny, e registre o resultado no runbook. Uma política não testada é só uma hipótese.

Como desenhar aprovação humana que realmente protege

Há três bons momentos para uma pessoa entrar no fluxo.

Aprovação de plano: depois que o agent coletou contexto, antes de editar uma área sensível. O humano avalia abordagem, arquivos, riscos e validações.
Aprovação de efeito externo: depois de testes e diff, antes de push, deploy, publicação, migração ou mudança de permissão. O humano recebe o alvo exato, o comando, o impacto e a reversão.
Revisão posterior: para ações pré-aprovadas e reversíveis, como atualização de dependência em branch efêmera. Aqui a revisão de PR e os sinais de CI são o gate.

Uma solicitação de aprovação deve responder, no mínimo:

qual ambiente, serviço, tenant ou branch será afetado;
que comando ou API será chamada;
quais dados podem ser modificados ou expostos;
quem é o dono que aprova;
qual é o plano de reversão;
quais testes e sinais já foram verificados;
o que o agent não conseguiu verificar.

Se o agent não consegue montar esse pacote, ele ainda não tem contexto suficiente para pedir a aprovação. Deve investigar ou escalar, não pressionar o usuário com um prompt opaco.

Threat model: do que estamos nos defendendo?

Threat modeling de agent não exige uma matriz gigantesca. Comece por ativos, atores, caminhos de abuso e consequências.

Ameaça	Caminho típico	Controle principal	Dono
Exfiltração de segredo	leitura de `.env`, histórico, logs ou MCP	`deny`, isolamento de credencial, redaction	Security + platform
Escrita em produção	tool permissiva + token amplo	identidade read-only, `ask`/`deny`, gate externo	dono do serviço
Prompt injection	texto não confiável instrui o agent a agir	separar dados de instruções, tool mínima, revisão	owner da integração
Supply chain	script, skill ou MCP malicioso	allowlist de origem, revisão e pin de versão	platform/security
Erro de ambiente	comando correto no cluster errado	contexto explícito, hook e credencial por ambiente	SRE/platform
Auditoria insuficiente	ação sem registro ou aprovador	change record, logs mínimos e retenção	engineering manager