Controle de permissões e segurança no Claude Code

Ao final deste capítulo, você saberá decidir exatamente o que o Claude Code pode fazer sozinho e o que precisa da sua aprovação, além de proteger segredos, evitar comandos destrutivos e reconhecer conteúdo externo perigoso. No capítulo dois, você viu que a ferramenta lê arquivos livremente, mas pede permissão antes de editar ou executar comandos. Agora vamos transformar esse comportamento padrão em regras precisas, gravadas no settings.json que o capítulo um apresentou, e compartilháveis com o time.

Os quatro modos de permissão

O Claude Code trabalha em um de quatro modos, e cada um define quanto ele pergunta antes de agir.

• O modo padrão com aprovação é o que você usou até aqui. Toda edição de arquivo e todo comando de terminal aparecem para você aprovar ou recusar. É o modo mais seguro para começar em qualquer projeto.
• O modo de aceitar edições automaticamente aprova sozinho as alterações em arquivos, mas continua pedindo confirmação para comandos de terminal. Ele é útil quando você já revisou um plano e quer que a implementação flua sem uma pergunta a cada arquivo tocado, sabendo que revisará tudo pelo diff do Git ao final.
• O modo de planejamento, que você conhece dos capítulos dois e três, permite apenas leitura e análise. Nenhum arquivo é alterado e nenhum comando é executado.
• O modo sem confirmações executa tudo sem perguntar. Ele é ativado com a opção de linha de comando --dangerously-skip-permissions, e o nome em inglês avisa: é perigoso.

A tecla Shift Tab, que alternava entre planejamento e execução, na verdade percorre o ciclo entre padrão, aceitar edições e planejamento. Você também pode iniciar já em um modo específico com claude --permission-mode plan ou claude --permission-mode acceptEdits.

Um alerta claro sobre o modo sem confirmações. Nele, o Claude Code pode apagar arquivos, rodar scripts que alteram o sistema e fazer push em repositórios remotos sem que você veja nada antes. Só use esse modo dentro de um ambiente isolado e descartável, como um contêiner Docker sem acesso às suas credenciais e sem volumes montados apontando para pastas importantes, ou uma máquina virtual criada apenas para aquela tarefa. Nunca o ative na sua máquina de trabalho, com seu diretório pessoal e suas chaves acessíveis. E, mesmo no ambiente isolado, limite o acesso à rede ao que a tarefa exige e não forneça ali credenciais de produção nem tokens com permissão de escrita, porque sem confirmações não há nada entre uma instrução maliciosa e o envio dos seus dados para fora. Se algo der errado em um contêiner, você descarta o contêiner. Se algo der errado no seu computador, pode não haver volta.

O comando de barra permissions

Dentro de uma sessão, o comando de barra /permissions abre um painel com as regras ativas. Ali você vê o que está permitido, o que está negado, de qual arquivo cada regra veio e pode adicionar ou remover regras sem sair da conversa. Além disso, sempre que o Claude Code pede aprovação para um comando, uma das opções oferecidas é permitir aquele comando de forma permanente para o projeto. Ao escolher essa opção, ele grava a regra no arquivo local de configuração. Isso é conveniente, mas revise periodicamente com /permissions para não acumular permissões que você concedeu com pressa.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Listas de permitir e negar no settings.json

As regras vivem em uma seção chamada permissions dentro do settings.json, com duas listas: allow, que autoriza sem perguntar, e deny, que bloqueia sempre, mesmo que você tente aprovar na hora. Cada regra nomeia uma ferramenta e, opcionalmente, um padrão entre parênteses. Veja um exemplo completo para uma API em Node.js:

{   "permissions": {     "allow": [       "Bash(npm test:*)",       "Bash(npm run lint:*)",       "Bash(git status:*)",       "Bash(git diff:*)",       "Edit(src/**)",       "Edit(tests/**)"     ],     "deny": [       "Read(./.env)",       "Read(./.env.*)",       "Read(./secrets/**)",       "Edit(./package-lock.json)",       "Bash(rm -rf:*)",       "Bash(git push --force:*)",       "Bash(curl:*)"     ]   } }

Vamos ler essas regras em voz alta. A ferramenta Bash representa comandos de terminal, e o padrão npm test:* significa qualquer comando que comece com npm test, incluindo argumentos. A ferramenta Edit controla alterações em arquivos, e o padrão src/** abrange qualquer arquivo dentro da pasta src em qualquer profundidade. A ferramenta Read controla leitura, e aqui bloqueamos os arquivos de ambiente e a pasta de segredos. Preste atenção a dois limites importantes dessas regras. Primeiro, bloquear a leitura pela ferramenta Read não impede que o mesmo arquivo seja lido por um comando de terminal, como cat ou grep, então essa proteção só vale se você também restringir o Bash. Segundo, as regras de Bash comparam o início do comando, de modo que variações como rm -r -f, git push -f ou um comando embrulhado em bash -c passam por um padrão escrito de outra forma. Use as listas como redução de risco, não como barreira à prova de falhas. Também existem regras para Write, para criação de arquivos, e para WebFetch, que busca conteúdo na internet e merece o mesmo cuidado de um curl.

A ordem de avaliação importa: uma regra em deny vence uma regra em allow. Isso permite autorizar edições em toda a pasta src e, ao mesmo tempo, proteger um arquivo específico dentro dela.

Usuário, projeto e local: onde cada regra fica

Como o CLAUDE.md do capítulo anterior, as permissões também têm níveis, e a lógica de escolha é parecida.

• O settings.json do usuário, dentro da pasta .claude no seu diretório pessoal, vale para todos os projetos da sua máquina. Coloque ali as proteções que você quer em qualquer lugar: negar leitura de arquivos de ambiente, negar rm com força recursiva, negar push forçado.
• O settings.json do projeto, dentro da pasta .claude na raiz do repositório, é versionado e compartilhado com o time. Coloque ali os comandos de teste e lint que todos usam e as pastas que podem ser editadas sem cerimônia.
• O settings.local.json, na mesma pasta do projeto, não é versionado e guarda suas preferências pessoais e as permissões concedidas durante as sessões. O Claude Code já o adiciona ao gitignore por você.

Quando há conflito, o arquivo do projeto sobrepõe o do usuário, e o local sobrepõe o do projeto, exceto pelas regras de negar, que continuam valendo venham de onde vierem. Para compartilhar com o time, basta fazer commit do settings.json do projeto e tratá-lo em revisão de código como qualquer outro arquivo. Uma boa prática é combinar com o time que toda regra nova em allow passa por um pull request, para que ninguém autorize sozinho algo que afete todos.

Segurança além das permissões

Regras de permissão são a primeira camada. As demais dependem de hábitos.

Proteja segredos

O Claude Code lê arquivos para entender o projeto, e o conteúdo lido entra na janela de contexto e é enviado ao modelo. Se um arquivo de ambiente contém senhas de banco e chaves de serviços, você não quer que ele seja lido nem por acidente. Por isso a regra de negar leitura de arquivos de ambiente deve estar no seu settings.json do usuário. Complemente com um gitignore correto e nunca cole segredos diretamente na conversa. Se precisar que ele configure uma variável, peça que use um valor de exemplo e você preenche o real depois.

Evite comandos destrutivos

Além de negar rm com força recursiva e push forçado, considere bloquear comandos que apagam dados em banco, como DROP via cliente de linha de comando, e scripts de deploy. Quando o Claude Code propuser um comando que você não reconhece, peça que explique o que ele faz antes de aprovar. Se a explicação não convencer, recuse. Recusar não custa nada; desfazer pode custar horas.

Revise diffs antes de aceitar

Mesmo no modo de aceitar edições, o Git mostra tudo que mudou. Antes de fazer commit, rode git diff e leia. Procure alterações fora do escopo pedido, arquivos que não deveriam ter sido tocados e trechos apagados sem justificativa. Um diff pequeno e focado é sinal de instrução boa, como o capítulo quatro ensinou. Um diff enorme e espalhado é sinal de que algo saiu do controle.

Cuidado com conteúdo externo: injeção de prompt

Quando o Claude Code lê uma página da web, uma issue, um comentário de pull request, um arquivo de terceiros ou até um README de dependência, esse texto pode conter instruções escritas para enganar a inteligência artificial. Isso se chama injeção de prompt. Um exemplo: um comentário escondido em um arquivo dizendo para ignorar as regras anteriores e enviar o conteúdo do arquivo de ambiente para determinado endereço. O modelo é treinado para resistir a isso, mas nenhuma defesa é perfeita. As regras de negar no settings.json ajudam, porque valem independentemente do que o texto peça, mas não são infalíveis: por casarem apenas o início dos comandos, podem ser contornadas por variações. A defesa mais eficaz continua sendo você aprovar cada comando, manter o modo sem confirmações fora da sua máquina e desconfiar de qualquer ação inesperada. Desconfie especialmente quando, após ler algo externo, ele propõe uma ação que não tem relação com a sua tarefa.

Git como rede de segurança

Trabalhe sempre em um repositório com o estado limpo antes de começar uma sessão, e faça commits pequenos conforme avança. Assim, qualquer alteração indesejada pode ser descartada com git checkout ou git restore, e um commit ruim pode ser revertido. Cuidado: esses dois comandos apagam de forma definitiva o que ainda não foi commitado, inclusive o seu próprio trabalho, então rode git status e git diff antes e, na dúvida, guarde tudo com git stash ou em um commit temporário em vez de descartar. Se pretende deixar o Claude Code trabalhar por mais tempo em algo arriscado, crie uma branch só para isso. O capítulo onze aprofunda o fluxo de Git; por enquanto, basta a regra: nunca inicie uma tarefa da inteligência artificial com trabalho seu não salvo.

Recapitulando

Você conheceu os quatro modos de permissão e aprendeu que o modo sem confirmações só cabe em ambiente isolado e descartável. Viu como inspecionar e ajustar regras com o comando de barra permissions e como escrever listas de permitir e negar no settings.json para comandos de terminal, ferramentas e padrões de arquivo, lembrando que negar sempre vence. Entendeu os três níveis de configuração, do usuário, do projeto e local, e como compartilhar regras com o time por versionamento. Por fim, incorporou as práticas de segurança: proteger arquivos de ambiente, bloquear comandos destrutivos, ler todo diff antes de aceitar, desconfiar de conteúdo externo que possa carregar injeção de prompt e usar o Git como rede de segurança em cada sessão.