CLAUDE.md + permissões seguras: a configuração que evita o primeiro desastre

O primeiro desastre no Claude Code quase nunca vem de falta de estudo. Ele vem de uma permissão aberta demais na primeira semana. Você pede um ajuste simples, o agente sugere apagar uma pasta, rodar um comando destrutivo ou ler um arquivo com chave, e a pressa faz você confirmar sem ler. Essa cena se repete porque muita gente pula a configuração para chegar logo na parte produtiva.

Este guia trava as duas peças que evitam esse susto: o modo de permissão e o arquivo CLAUDE.md. Você vai sair com o permission-mode plan ativo, uma lista pronta de allow, ask e deny para copiar, um modelo curto de CLAUDE.md com comando de teste e uma rotina de revisão de dois minutos. Se você ainda não fez o treino inicial, comece pelo mapa geral em Claude Code do zero. O modo plan e a estrutura de permissions em JSON com bloqueio de .env e de comandos destrutivos seguem o roteiro publicado em 08/abr/2026 no guia de primeiros passos.

O permission-mode plan é o ponto de partida seguro porque ele inverte a ordem do risco. Primeiro o agente mostra o plano, depois pede aprovação nos pontos sensíveis, e só então executa. Essa sequência está descrita como modo indicado para quem está começando no guia de primeiros passos, de 08/abr/2026.

Na prática, o plan muda seu dia em três detalhes. Pedidos de leitura e explicação chegam rápido, sem trava. Pedidos de edição chegam como proposta, com arquivos citados e diff previsto. Pedidos com comando sensível param para confirmação, com o comando exato na tela. Você mantém velocidade onde não há risco e ganha uma pausa onde há.

Ative o modo com o comando abaixo dentro da sessão e confirme na lista de permissões:

/permissions

Abra /permissions, escolha plan como modo ativo e leia a lista atual antes do próximo pedido. Se algum item parece amplo demais, mova para ask na hora. A regra dos primeiros dias é simples: na dúvida, deixe a opção mais restritiva.

Saia do plan somente quando dois sinais aparecem juntos. Primeiro, você já revisa diffs curtos com calma e entende cada linha. Segundo, a lista de ask só repete comandos que você aprovou várias vezes sem susto. Mesmo nesse ponto, mova um comando por vez para allow, nunca libere tudo de uma vez.

As três camadas têm funções distintas que você deve decorar. Allow libera sem perguntar e serve só para leitura e comandos inofensivos do dia a dia. Ask pede confirmação caso a caso e serve para tudo que altera arquivos ou envia código. Deny bloqueia de vez e serve para segredos e comandos destrutivos. Essa divisão em allow, ask e deny com uso de permissions em JSON aparece no guia de primeiros passos, de 08/abr/2026.

Copie o modelo abaixo como ponto de partida e ajuste os comandos de teste para o seu projeto:

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Bash(npm test:*)",
      "Bash(npm run build:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)"
    ],
    "ask": [
      "Edit",
      "Bash(git commit:*)",
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Read(.env)"
    ]
  }
}

Cada grupo tem um motivo claro. Allow guarda leitura com Read e Grep, conferência com git status e git diff, e validação com npm test e npm run build. Ask guarda escrita com Edit e envios com git commit e git push, porque esses pontos merecem seus olhos antes de seguir. Deny trava remoção com rm -rf, envio forçado com push com force e leitura de segredos com Read de .env. O bloqueio de .env e dos comandos de remoção e envio forçado é o padrão seguro citado no guia de 08/abr/2026.

Use a tabela abaixo para revisar sua lista em dois minutos:

Quando um comando novo aparece em ask e você não reconhece o efeito, peça explicação antes de aprovar. Uma frase resolve: explique o que este comando faz neste projeto, sem executar. Se a explicação cita arquivos e pastas reais do seu contexto, aprove. Se a resposta é vaga ou cita caminhos estranhos, recuse e ajuste o pedido com a pasta exata.

O CLAUDE.md é um arquivo de instruções que fica na raiz do projeto e diz ao agente como trabalhar ali. Arquivo curto funciona melhor porque é fácil de revisar e tem menos chance de ordens contraditórias. A recomendação de manter esse arquivo pequeno, com 5 a 10 linhas no início, aparece no tutorial publicado em 28/jan/2026 no tutorial para iniciantes.

A primeira informação útil desse arquivo é como validar o trabalho. Sem o comando de teste ali, cada resposta sugere um jeito diferente de conferir. Com ele, o agente já propõe o comando certo do seu projeto. Essa função da primeira linha com testes aparece no guia publicado em 27/abr/2026 no guia completo para começar.

Copie o modelo mínimo abaixo e troque o nome e o comando pelos dados reais do seu projeto:

# nome-do-projeto

Projeto em Node com testes em Jest.

## Como validar
Rode `npm test` antes de concluir qualquer mudança.

## Estilo
Respostas curtas, um diff pequeno por vez.

## Limites
Nunca leia `.env`. Nunca rode `rm -rf` nem `git push --force` sem permissão explícita.

Cada bloco tem um papel direto. Contexto diz o que o projeto é em uma frase. Validação diz o comando exato que prova que a mudança funciona. Estilo pede diff pequeno, que é mais fácil de revisar linha por linha. Limites listam o que nunca acontece sem aval explícito, com .env e comandos destrutivos no topo.

Gere a base com o comando abaixo e depois edite para menor, não para maior:

/init

O /init cria um rascunho a partir dos arquivos do projeto. Abra o resultado, corte frases genéricas, deixe o comando de teste exato e mantenha os limites em poucas linhas. Se o arquivo passa de uma tela curta, corte de novo. Arquivo enxuto protege mais porque você realmente lê o conteúdo antes de cada sessão.

Esse hábito de validar com teste vem do treino inicial. Se você ainda não rodou o ciclo de ler, mudar pouco e revisar o diff com teste, siga o roteiro dos primeiros 30 minutos antes de endurecer as regras. O teste ali é o mesmo comando que agora mora na primeira linha do seu CLAUDE.md.

Configuração segura não é tarefa única. Ela pede uma revisão curta toda semana no começo, porque seu repertório cresce e a lista precisa acompanhar. Reserve dois minutos, abra /permissions e leia cada item em voz alta. Para cada linha, pergunte se ela precisa mesmo rodar sem avisar.

Mova um comando de ask para allow somente quando ele cumpre três condições juntas. Ele se repete quase todo dia, o efeito é limitado a leitura ou validação, e você nunca sentiu medo ao aprovar. Exemplos típicos são rodar a suíte de testes e ver o diff. O caminho inverso também vale na hora: se um comando deu frio na barriga, volte para ask ou deny sem debate.

Pedidos bem feitos reduzem perguntas repetidas e diffs grandes. Todo pedido forte tem três partes curtas: onde, o que e como conferir. Onde indica a pasta ou o arquivo. O que descreve a mudança em uma frase. Como conferir diz qual leitura ou teste prova que funcionou. Esse formato aparece como base do ciclo de leitura antes da edição no guia de primeiros passos, de 08/abr/2026.

Use estes dois modelos literais no dia a dia:

Nesta pasta, explique quais arquivos cuidam de login, sem alterar nada.

Neste arquivo, ajuste este texto de ajuda e mostre o diff antes de finalizar.

O detalhe que protege está no fim de cada frase. Sem alterar nada mantém o agente em leitura. Mostre o diff antes de finalizar exige prova antes de concluir. Quando o agente faz perguntas de volta, responda curto com o nome do arquivo e o resultado esperado. Boas respostas geram mudanças certas na primeira tentativa.

Algumas chaves removem todas as travas de uma vez e só fazem sentido em ambiente descartável. Os nomes para guardar são bypassPermissions e a flag --dangerously-skip-permissions. Fora de uma pasta de teste que pode ser apagada sem perda, deixe essas opções desligadas.

Autorizar tudo para andar mais rápido é um dos erros centrais descritos nos 3 tropeços do guia de 27/abr/2026 no guia completo para começar. O atalho parece produtivo porque elimina confirmações. O custo aparece depois, quando um comando atinge .env, apaga arquivos ou envia código com force sem pausa para revisão.

Adote esta regra prática para nunca cair nesse atalho. No projeto real, rode sempre em plan ou com asks ligados. Em pasta descartável de treino, você pode testar um comando específico com menos travas para aprender o efeito, e depois apaga a pasta. Essa separação mantém a curiosidade sem expor o trabalho real.

Se você já liberou tudo uma vez, volte ao seguro em três passos. Primeiro, reative o plan em /permissions. Segundo, confira que Read de .env, rm -rf e push com force estão em deny. Terceiro, abra o CLAUDE.md e confirme que o comando de teste e os limites continuam lá. Depois peça uma tarefa pequena para sentir o ritmo com as travas ligadas.

Para situar essa trava no quadro geral de ferramentas, guarde este atalho para depois da configuração: Claude Code vs Cursor vs Copilot.

Qual é a primeira linha útil do CLAUDE.md?

O comando de teste do seu projeto. Ele diz ao agente como provar que a mudança funciona antes de concluir. No modelo deste guia, essa linha é npm test na seção Como validar. Essa função da primeira linha com testes está descrita no guia de 27/abr/2026 no guia completo para começar. Troque pelo comando real do seu contexto e mantenha o resto curto.

Quando posso mover um comando de ask para allow?

Quando ele é repetitivo, tem efeito limitado e nunca gerou dúvida na aprovação. Leitura com Read e Grep, conferência com git status e git diff, e validação com npm test costumam migrar primeiro. Edição com Edit e envios com git commit e git push devem ficar em ask por mais tempo. Na dúvida, mantenha em ask por mais uma semana.

Posso usar bypassPermissions para andar mais rápido?

Evite no projeto real. Essas chaves removem as pausas que protegem segredos e comandos destrutivos. Use somente em pasta descartável que pode ser apagada sem perda, para aprender o efeito de um comando específico. No trabalho real, o ganho de velocidade não compensa o risco de expor .env ou apagar arquivos.

Com que frequência devo revisar as permissões?

Uma vez por semana no começo. Abra /permissions, leia cada item e pergunte se ele precisa rodar sem avisar. Mova para allow só o que é repetitivo e seguro, e traga de volta para ask ou deny tudo que gerou dúvida. Essa revisão curta mantém a lista alinhada com seu repertório e evita que uma liberação antiga vire risco novo.

Configuração segura se resume a quatro movimentos em ordem. Ative o permission-mode plan, copie a lista de allow, ask e deny com .env travado, deixe o CLAUDE.md curto com comando de teste e limites, e revise /permissions uma vez por semana. Esse conjunto elimina os erros que mais assustam no começo e deixa o diff como prova de cada passo.

Quando bater dúvida no meio de uma tarefa, volte às três perguntas do pedido bom. Onde estou, o que quero mudar e como vou conferir. Se as respostas cabem em frases curtas, o pedido está pronto. Se alguma resposta está vaga, peça explicação antes de pedir mudança.

Siga nesta ordem a partir daqui. Revise o treino guiado em roteiro dos primeiros 30 minutos quando quiser reforçar o ciclo de diff com teste. Depois compare ferramentas em Claude Code vs Cursor vs Copilot somente após travar a base deste guia.

• guia de primeiros passos
• guia completo para começar
• tutorial para iniciantes