Antes de entregar as chaves pra IA: 5 cuidados pra iniciante “não causar acidente”

“Dá uma organizada geral neste projeto.”

Digitei isso de bobeira e fui passar um café. Quando voltei, o terminal estava parado a um passo de executar um rm -rf. E o meu dedo, no automático, já se esticava pro botão de aprovar.

Se eu tivesse apertado o “sim” naquela hora, o .env e os arquivos de configuração teriam ido embora, tudo junto.

O Claude Code é esperto. Mas esperteza e segurança são coisas completamente diferentes. Aliás, justamente por ser esperto e rápido de mão, ele corre com tudo também na direção errada. É como a faca: quanto melhor ela corta, mais você se machuca antes de aprender a manusear.

Este artigo se limita só aos cuidados de segurança que um iniciante precisa fixar primeiro. O papo difícil fica pra depois. Os 5 que você protege primeiro, escritos de forma fácil, junto com os meus vacilos.

Pra começar, o que é tão perigoso assim?

Um editor de texto comum só exibe caracteres. Mas o Claude Code é diferente. Dentro do seu computador, ele é uma ferramenta que “consegue fazer” coisas assim.

Ler, escrever e apagar arquivos.
Executar comandos do terminal (rm também dá).
Acessar a internet e postar em serviços externos.

E tudo isso, funciona se você aprovar com um “sim”. O problema é que, de tanto apertar o botão de aprovar dezenas de vezes, você para de olhar o conteúdo. No instante em que você entra no ritmo do “sim, sim, OK”, a operação perigosa passa batida.

Por isso, cuidado de segurança não é “tomar cuidado”. É montar antes um mecanismo em que, mesmo sem você tomar cuidado, não dá acidente. Vamos ver na ordem.

Onde dá o frio na espinha (3 casos)

Três “situações perigosas” que iniciante costuma fazer. Nenhuma tem nada de especial.

Situação 1: querendo o conserto de um erro, você cola o log inteiro.

Quando pede “conserta este erro”, você copia e cola tudo que saiu no terminal, né? Mas no meio desse log às vezes se infiltra uma linha tipo DATABASE_URL=postgresql://user:senha_de_verdade@.... Você achou que entregou só pra IA, mas a senha crua fica no histórico da conversa e no log.

Situação 2: você larga no modo “deixa tudo comigo”.

Aprovar dá preguiça, então você põe no modo que executa qualquer coisa sem confirmar, e se levanta da cadeira. A IA, com boa intenção, dá um git push --force, e o trabalho de alguém do time vai pelos ares. Maldade, zero. Mas o resultado é o pior.

Situação 3: você troca um banco de nome parecido pelo outro.

myapp_dev e myapp_prod. É uma letra de diferença. Se você pede só “apaga os dados velhos do banco” e a IA não confere a qual dos dois está conectada — o que some pode ser o dado do seu cliente, lá na produção.

O que esses três têm em comum é: no instante em que o humano “vacila”, a IA executa com tudo. Então basta deixar tudo seguro mesmo que você vacile. Esse é o cuidado.

3 vacilos que eu mesmo cometi

Escrevo aqui todo metido, mas eu também, no começo, era só acidente. Confesso três, com honestidade.

Primeiro. Quando montava o post automático pro Qiita, colei o token direto no prompt. “Posta usando o QIITA_TOKEN=xxxx.” Funcionou, fiquei satisfeito, mas depois caí em mim. Aquela string fica também no log da conversa e no histórico da IAzinha que roda nos bastidores (o subagent). Saí correndo gerar o token de novo. Hoje, pensando nisso, dá um suor frio.

Segundo. Pra investigar, pedi “confere o conteúdo do .env”. A IA, obediente, leu tudo em voz alta. Chave de API, senha do banco, tudo na tela e no log. No instante em que você deixa ler, é o mesmo que “vazou”. O .env nem eu, o humano, costumo abrir.

Terceiro. Copiei a configuração frouxa de um projeto-hobby pro repositório do trabalho. Resultado: a “proibição de escrever na produção”, que devia existir no lado do trabalho, foi sobrescrita pela frouxidão do hobby. Percebi antes de dar acidente, mas reaproveitar configuração é perigoso de verdade.

Nenhum desses foi por falta de conhecimento, e sim por eu não ter barrado com mecanismo. É daqui que começa o âmago.

É só estes 5 que você protege. Faça na ordem

Cuidado 1: deixe a chave de API “fora do código”

É o mais importante. Chave de API e token, jamais escreva direto no código ou no prompt. Isole num arquivo dedicado chamado .env e tire esse arquivo do controle do Git. Só isso já evita a maior parte dos vazamentos.

Primeiro, o exemplo do que não fazer.

// NÃO: escrever direto no código-fonte (se commitar, já era na hora)
const client = new Anthropic({ apiKey: "colar a chave de API de verdade direto aqui" });

// NÃO: misturar no prompt
// "Posta usando o QIITA_TOKEN=token_de_verdade" <- o que eu vacilei

O certo é juntar as chaves num arquivo chamado .env.

# .env (não suba este arquivo pro Git. deixe só no seu computador)
ANTHROPIC_API_KEY=aqui o valor de verdade
QIITA_TOKEN=aqui o valor de verdade
DATABASE_URL=postgresql://...

E aí declare que esse .env “o Git jamais vai pegar”. Isto é o cabo de vida.

# escreva sem falta no .gitignore (o seguro pra não commitar a chave sem querer)
.env
.env.*
!.env.example   # só o exemplo pode ser compartilhado
*.pem
*.key
*-service-account.json   # não esqueça da chave de service account da nuvem

Quando você quer avisar o time só “quais chaves são necessárias”, ponha um exemplo com os valores vazios.

# .env.example (este pode subir pro Git. o conteúdo é vazio)
ANTHROPIC_API_KEY=
QIITA_TOKEN=
DATABASE_URL=

Do código, em vez de escrever o valor do arquivo direto, você o lê como “variável de ambiente”. A chave em carne e osso não aparece em lugar nenhum do código.

// OK: ler da variável de ambiente. nenhum valor escrito no código
import { config } from "dotenv";
config();

const token = process.env.QIITA_TOKEN;
if (!token) {
  // se não tem a chave, não diga o valor; diga só "você esqueceu de configurar"
  throw new Error("QIITA_TOKEN não está configurado. Confira o .env.");
}

O ponto é um só. A chave em carne e osso só é tocável dentro do .env. O código, o prompt e o log ficam num estado em que conhecem só o “nome” da chave. Esse é o bê-á-bá.

Cuidado 2: não deixe o comando perigoso ser “aprovado no automático”

Em seguida, comandos sem volta como rm -rf (exclusão em lote) ou git push --force (sobrescrever o trabalho do time). Configure esses pra “sempre perguntar ao humano antes de executar” ou pra “não poder executar de jeito nenhum”.

O Claude Code tem um mecanismo pra você decidir, comando a comando, “OK / precisa confirmar / proibido”. Em .claude/settings.json, você escreve assim.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(curl * | bash)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)"
    ]
  }
}

Ler é simples. É só distribuir em três caixas.

Caixa	Significado	O que pôr
`allow`	Executar sem confirmar, OK	Operação segura, só de leitura
`ask`	Perguntar direitinho toda vez	Escrita, commit, push
`deny`	Não deixar fazer de jeito nenhum	Exclusão, force push, banco de produção

Na dúvida, decore assim. Só ler, allow; se escreve, ask; se apaga, deny. No começo, aperte tudo bem firme e só promova pra ask ou allow, depois, a operação que você descobriu ser segura. O sentido contrário (frouxo no começo, apertar depois) só vem depois do acidente, então comece, sem exceção, pela direção de apertar.

Cuidado 3: estreite o “alcance” de leitura e escrita

Olhe bem o deny do cuidado 2. No topo tem estas linhas.

"deny": [
  "Read(./.env)",
  "Read(./.env.*)",
  "Read(./secrets/**)"
]

Isto é a configuração “a pasta .env e secrets é proibido até de ler”. Aquele acidente que eu cometi, “deixar ler o .env”, não teria acontecido com esta única linha. Porque, mesmo que você peça “confere aí”, a IA leva um “acesso negado”.

Estreitar o alcance é traçar de antemão a linha entre o lugar que pode ser mostrado e o que não pode. A pasta com as chaves, a configuração da produção, o dado dos clientes. Se você deixa esses num estado de “nem dá pra encostar”, mesmo que peça sem querer, é seguro.

Além disso, os arquivos que você jamais quer que sejam editados, escreva-os também em português na regra do projeto (CLAUDE.md), pra ficar tranquilo.

## Arquivos proibidos de editar (escrever no CLAUDE.md)

Os abaixo jamais edite. Se precisar, confirme sempre comigo (humano).
- .env (contém chaves e senhas)
- wrangler.toml (configuração de publicação da produção)
- .github/workflows/*.yml (configuração do deploy automático)

Bloquear de forma mecânica pelo arquivo de configuração e transmitir a intenção também à IA pelo texto de regra. Em duas camadas, as brechas diminuem.

Cuidado 4: não jogue informação secreta no log

Este é menos uma configuração e mais um pequeno hábito de escrita. Quando escrever a mensagem de erro, não imprima junto o “valor” da chave.

// NÃO: a chave de API sai direto no log de erro
throw new Error(`Falha na autenticação: token=${process.env.TOKEN}`);

// OK: não diga o valor; diga só onde olhar
throw new Error("Falha na autenticação: confira a variável de ambiente TOKEN");

É a diferença de uma linha só, mas a de cima vaza a chave no instante em que você mostra o log pra alguém.

E mais uma. Quando entregar o log à IA, não cole cru. As linhas de chave e senha, substitua o valor por censura antes de entregar.

# reescreva assim antes de entregar. à IA basta entender a estrutura "tem info de conexão do banco"
DATABASE_URL=***censurado***
QIITA_TOKEN=***censurado***

“O que pode entregar” e “o que não pode”, no atacado, numa tabela. Se você colar isto no CLAUDE.md, lembra do critério toda vez que pedir.

Pode entregar	Não pode entregar
Tipo do erro, passo pra reproduzir, nome do arquivo	Chave de API, senha, cookie de sessão
`.env.example`, o “nome” do item de configuração	URL do banco de produção, dado dos clientes
Log com o valor censurado	Token real, arquivo .json de service account

Cuidado 5: dê tratamento “à parte” às coisas de produção

Por último. Separe bem o de treino (desenvolvimento) e o de produção. Pra evitar a troca de myapp_dev por myapp_prod, exigir uma mãozinha a mais pra escrever na produção funciona.

// scripts/db-query.mjs
const env = process.env.NODE_ENV ?? "development";

// se tentar escrever na produção, para a não ser que tenha a flag dedicada
if (env === "production" && process.argv.includes("--write")) {
  console.error("Para escrever na produção é preciso a flag --force-production.");
  process.exit(1);
}

Bloquear de forma física o “produção sem querer” com a mãozinha a mais que é a flag. Esse incômodo é o cabo de vida. O dado da produção, se você apaga, não volta.

Se for começar, comece por aqui (passo a passo)

Você não precisa fazer os 5 hoje. Na ordem, termina em 30 minutos.

Crie um .env no projeto e mova todas as chaves pra lá.
Adicione .env ao .gitignore (cuidado 1).
Crie .claude/settings.json e ponha no deny o rm -rf e a leitura de .env (cuidados 2 e 3).
Ponha no ask as coisas de escrita e commit (cuidado 2).
Cole no CLAUDE.md a tabela “pode/não pode entregar” e os arquivos proibidos de editar (cuidado 4).

Só com os 3 primeiros passos, o acidente de rm -rf da abertura e o vazamento do .env já param. Não mire a perfeição, faça primeiro um. Já é avanço de sobra.

Quando bater vontade de afinar mais a configuração de permissões, leia o guia de configuração de permissões do Claude Code, e se quiser as histórias cruas de acidentes que aconteceram de verdade, os casos de falha de segurança do Claude Code. A especificação exata da configuração é sempre melhor na documentação oficial.

O que aconteceu quando testei na prática

Desde aquele frio na espinha com o rm -rf da abertura, eu parei de me atormentar com “será que confio na IA”. No lugar disso, o que eu olho é: em qual porteiro ela travou.

Quando somei a leitura de .env ao deny, mesmo pedindo “confere a variável de ambiente”, a IA passou a recuar, obediente. Aquele constrangedor “lê tudo em voz alta” não acontece mais.

Sendo honesto, no dia em que escrevi a configuração, pensei “será que é exagero?”. Mas era o contrário. É justamente por ter a guarda que dá pra relaxar com tranquilidade. Apertar o botão de aprovar de leve só é possível porque eu sei que a operação perigosa trava antes, no deny. Em vez de me esforçar pra dominar a IA esperta, forrar antes o chão pra cair sem se machucar. Esta é, hoje, a minha conclusão: é o mais fácil e o mais rápido.

Resumo

O que um iniciante protege primeiro, basta serem estes 5.

O que proteger	Como fazer
Não vazar a chave de API	Isolar no `.env` + `.gitignore`
Não deixar o comando perigoso fora de controle	`rm -rf` / force push no `deny`
Estreitar o alcance de leitura e escrita	`.env` e secrets no `deny`, arquivo de produção proibido de editar
Não jogar info secreta no log	Não imprimir o valor; entregar censurado
Dar tratamento à parte à produção	Bloquear a escrita na produção com flag

Segurança soa como algo que dá frio na barriga, mas o que você faz é só “montar antes um mecanismo em que o acidente não acontece”. Uma vez instalado, depois ele protege mesmo deixado por conta própria. Hoje, 30 minutos. Com isso, você apaga um grande acidente do futuro.

Se ficar na dúvida de “até onde a gente, no nosso time, deve amarrar?”, também tenho materiais e suporte preparados. Comece dando uma espiada na lista de materiais.