Claude Code: até onde delegar? A regra dos 4 níveis de autonomia segura

Numa sexta à noite, pedi ao Claude Code: “conserta só os links quebrados dos posts antigos do blog” e fui dormir. Na manhã seguinte, abri o histórico de commits e 12 artigos tinham sido reescritos. Os links estavam corrigidos, é verdade. Mas, de quebra, ele “ajeitou” o texto de vários títulos e sobrescreveu até expressões antigas que eu tinha deixado ali de propósito.

Levei duas horas para reverter tudo. Por que um Claude Code que deveria ser tão esperto faz esse tipo de coisa a mais? A resposta é simples: eu nunca tinha dito a ele “até onde você pode ir”.

Existe também o padrão oposto. Com medo, mudei a configuração para que ele perguntasse “posso executar isso?” a cada linha alterada. Em meia hora eu estava esgotado de apertar o botão de aprovar e acabei concluindo que era mais rápido escrever eu mesmo. Delegar demais e causar um acidente, ou travar demais e cansar. Muita gente se perde entre esses dois extremos.

Este artigo é sobre como acabar com essa indecisão: os “4 níveis de autonomia”. Só leitura, edição reversível, publicação, e o que só humano toca. Definir essas quatro linhas logo no começo faz quase toda a decisão diária desaparecer.

Pontos principais

• Divida o que você delega ao Claude Code em 4 níveis por grau de risco e a decisão fica mais fácil: só leitura / edição reversível / publicar e implantar / exclusivo do humano.
• Para cada nível, defina sempre uma “prova de que terminou”. Sai um diff, o build passa, a URL publicada está correta, e assim por diante.
• Exclusão, dados de produção, cobrança e force push: nunca automatize, mesmo depois de pegar prática. Só nesses casos é o humano que aperta o botão, toda vez.
• Escreva os níveis em um único arquivo YAML ao lado do CLAUDE.md e o próprio Claude Code passa a declarar “em qual nível estou agora”.
• Comece um nível abaixo do que parece seguro e só promova depois as operações que você confirmou serem seguras. O caminho inverso, nunca.

Por que “delimitar” importa mais que “ser esperto”

Quem tropeça com o Claude Code, na maioria das vezes, falha não pela performance do modelo, mas por como o trabalho é encerrado. Foi o meu caso lá no começo. A instrução em si não era ruim. Só que eu comuniquei o escopo de “apenas os links” usando só texto. Um pedido em texto é como uma instrução verbal dada a um colega ocupado numa manhã corrida: a interpretação escorrega com facilidade.

É aí que entra a delimitação por grau de risco. Você decide o que é permitido não pela “redação do pedido”, mas pelo “nível”. Assim, toda vez que o Claude Code vai fazer algo, dá para conferir “essa operação é de que nível?”. A disputa de interpretação sobre um português ambíguo vira uma checagem mecânica.

Essa ideia não é nova. Numa fábrica, o visitante que só observa, quem monta as peças, quem aperta o botão de expedição e quem abre o cofre têm permissões separadas desde o início. Com o Claude Code é só traçar as mesmas linhas.

O que tem dentro dos 4 níveis

Os 4 níveis que eu uso de verdade são os seguintes. Vou mostrar o panorama na tabela primeiro.

Nível	O que deixar fazer	Prova de que terminou
0 só leitura	Entender a estrutura de arquivos, levantar riscos, sugerir comandos de verificação	A nota final tem uma “lista dos arquivos lidos”
1 edição reversível	Corrigir 1 artigo, atualizar 1 teste	Sai um diff e o build passa
2 publicar e implantar	Deploy após o build, conferir a URL publicada	h1, URL canônica, links internos e plano de rollback estão prontos
3 exclusivo do humano	(não deixar o Claude Code fazer)	—

Entram no nível 3: chaves secretas, cobrança, dados de produção e force push. Aqui não automatizamos por mais prática que se tenha. O prejuízo de um erro não compensa o esforço que você economizaria.

O importante em cada nível é definir sempre uma “prova de que terminou”. Sem prova, mesmo que o Claude Code diga “pronto”, você não sabe se realmente acabou. Sai um diff, o build passa, abrir a URL publicada e ver que o h1 está certo: escolha como prova essas coisas verificáveis por máquina.

O que delegar à IA e o que o humano decide

Quando a delimitação fica clara, a divisão de papéis também se resolve sozinha.

O que você pode delegar ao Claude Code são tarefas com muitos passos cujo resultado dá para conferir por máquina. Ler muitos arquivos e resumir, corrigir um artigo num formato fixo, rodar os testes e ler os logs. Nisso ele faz mais rápido e com mais precisão que o humano.

O que o humano deve decidir são as decisões irreversíveis e as operações de prejuízo grande. Posso mesmo publicar este artigo? Posso apagar esta expressão antiga? Posso sobrescrever os dados deste cliente? Aqui você até deixa o Claude Code “propor”, mas quem aperta o “executar” é o humano.

O critério na dúvida é um só: “se der errado, eu consigo reverter em 10 minutos?”. Se dá para reverter, é nível 1; se não dá, é nível 2 ou 3. O meu acidente do começo levou 2 horas para reverter, ou seja, era na verdade um trabalho que exigia o cuidado do nível 2.

Definição de níveis pronta para copiar

Se você mantém os níveis só na cabeça, no fim eles oscilam. Escreva tudo em um único arquivo YAML e coloque na raiz do projeto como autonomy.yml. Ao referenciá-lo a partir do CLAUDE.md, o próprio Claude Code passa a declarar “agora estou no nível 1, então não vou publicar”.

# autonomy.yml — a delimitação de autonomia entregue ao Claude Code
safe_autonomy_ladder:
  level_0_read_only:
    allowed: ["entender a estrutura de arquivos", "levantar riscos", "sugerir comandos de verificação"]
    proof: "a nota final tem a lista dos arquivos lidos"
  level_1_reversible_edit:
    allowed: ["corrigir 1 artigo", "atualizar 1 teste"]
    proof: "sai git diff e o build passa"
  level_2_publish_or_deploy:
    allowed: ["deploy após o build", "conferir a URL publicada"]
    proof: "h1, URL canônica, links internos e plano de rollback estão prontos"
  level_3_owner_only:
    allowed: []
    examples: ["chaves secretas", "cobrança", "force push", "dados de clientes"]

No CLAUDE.md basta acrescentar uma única frase:

Antes de trabalhar, leia autonomy.yml e declare logo de início em que nível este trabalho se enquadra.
Operações de nível 2 ou acima não devem ser executadas: aguarde a aprovação do humano.

Script de verificação para checar o nível por máquina

Só pedir que ele declare me deixa inseguro, então eu vigio por máquina se “uma operação de nível 2 (publicação) não aconteceu sem prova”. O script abaixo busca a URL publicada após o deploy e confere se o h1 não está vazio e se a URL canônica aponta para o seu próprio slug. Roda direto no Node.js 18 ou superior.

// verify-publish.mjs — confere por máquina a "prova de que terminou" do nível 2
// Uso: node verify-publish.mjs https://claudecode-lab.com/blog/seu-slug

const url = process.argv[2];
if (!url) {
  console.error("Passe a URL publicada como argumento");
  process.exit(1);
}

const res = await fetch(url);
if (res.status !== 200) {
  console.error(`HTTP ${res.status}: ainda não está publicado`);
  process.exit(1);
}

const html = await res.text();

// O h1 existe e tem conteúdo?
const h1 = html.match(/<h1[^>]*>(.*?)<\/h1>/s);
const hasH1 = Boolean(h1 && h1[1].replace(/<[^>]+>/g, "").trim());

// A URL canônica aponta para esta própria página?
const canonical = html.match(/<link[^>]+rel=["']canonical["'][^>]*>/i);
const canonicalOk = Boolean(canonical && canonical[0].includes(new URL(url).pathname));

console.log(`tem h1:           ${hasH1 ? "OK" : "FALHA"}`);
console.log(`URL canônica bate: ${canonicalOk ? "OK" : "FALHA"}`);

if (hasH1 && canonicalOk) {
  console.log("Provas do nível 2 reunidas. Pode considerar a publicação concluída.");
} else {
  console.error("Faltam provas. Ainda não marque como concluído.");
  process.exit(1);
}

Se você acredita que só o HTTP 200 significa sucesso, não vai perceber quando aparecer o fallback da home ou um artigo antigo. Só depois de olhar o h1 e a URL canônica dá para dizer “este nível terminou”.

Cenários em que isso funciona (3 exemplos)

1. Logo depois de entrar num repositório novo Mandar editar sem conhecer a estrutura nem os comandos costuma quebrar arquivos de configuração. No início, permita só o nível 0 e peça que ele relate a estrutura de arquivos, os comandos disponíveis e os pontos perigosos de mexer. Depois que o mapa existe, suba para o nível 1.

2. Corrigir um erro de digitação num artigo Aqui o nível 1 basta. Saindo o diff e passando o build, a prova está completa. O meu acidente do começo teria sido evitado se eu tivesse deixado claro o escopo: “corrija só os erros de digitação. Não mude a redação do texto”. O modelo de pedido para entregar ao Claude Code é este:

Trabalhe no nível 1.
Alvo: apenas erros óbvios de digitação em content/blog/foo.mdx
Não faça: reescrever títulos, alterar a redação do texto, editar outros arquivos
Ao terminar, mostre git diff e confirme você mesmo se a mudança é só correção de digitação.

3. Pouco antes da publicação em produção No nível 2, peça que ele verifique sempre se o build passa, se as variáveis de ambiente estão completas, se o diff está conforme o esperado e se existe plano de rollback. Rodar o script de verificação acima por último permite checar até o conteúdo da URL publicada.

Três erros que eu mesmo cometi

Sendo honesto, até chegar a esses 4 níveis eu causei acidentes várias vezes.

O primeiro foi pular níveis de uma vez. Pulei o nível 0 e fui direto editar em massa no nível 1; saiu um diff tão grande que era impossível verificar, e eu mesmo não sabia mais o que estava certo. Hoje subo sempre na ordem, do 0 em diante.

O segundo foi marcar como “concluído” só com o build local. Como passou na minha máquina, publiquei. Mas em produção a página antiga estava sendo exibida e eu só percebi meio dia depois. Desde então, não considero concluído até ver o h1 e a URL canônica da URL publicada.

O terceiro foi confiar a aprovação só aos meus próprios olhos. “É só eu conferir no final” sempre desmorona numa noite em que estou cansado. Depois que incorporei como “prova” do nível checagens verificáveis por máquina (contagem de caracteres, links quebrados, erros de tipo), os deslizes da madrugada caíram drasticamente.

Como começar

Não tente mirar de cara num agente esperto e totalmente automático. Escolha uma tarefa pequena que dá para reverter se der errado. Conferir erros de digitação num rascunho, uma primeira revisão de uma mudança, a checagem antes de publicar no staging. Esse tamanho é o ideal.

A ordem é sempre a mesma. (1) Defina um escopo de leitura estreito. (2) Deixe claro o entregável. (3) Deixe os comandos fazerem a verificação sempre que possível. (4) Coloque todas as operações perigosas (exclusão, dados de produção, cobrança, force push) como “pergunte ao humano” no início. Só promova depois, um nível por vez, as operações que você confirmou serem seguras. Rebaixar no sentido inverso, não.

Se você travar na configuração fina de permissões, veja antes Como começar com o Claude Code; para escrever as regras de nível no CLAUDE.md, veja Como escrever o CLAUDE.md, e estes 4 níveis caem direto na configuração. Se a ideia é colocar pessoas que não são engenheiras no time, veja também Como usar o Claude Code para não engenheiros.

Perguntas frequentes

P. Preciso configurar os níveis na mão toda vez? Não. Crie um único autonomy.yml e referencie-o a partir do CLAUDE.md; daí em diante o próprio Claude Code declara “agora estou no nível 1”. A configuração é só na primeira vez.

P. Dá para automatizar até a “publicação” do nível 2? Se as provas forem reunidas por máquina, depois de pegar prática você pode automatizar. Mas insira sempre um mecanismo que confira o conteúdo da URL publicada, como o script de verificação acima. Acreditar só no HTTP 200 é o mais perigoso.

P. Como identificar as operações que devem entrar no nível 3? Pense rápido com “dá para resolver pedindo desculpas, ou exige indenização?”. Sobrescrever dados de clientes, cobrança e exclusão em produção são do segundo tipo, então é nível 3. Não automatize nem com prática.

P. Times pequenos também precisam de delimitação? Funciona ainda mais quanto menos gente houver. Como fica fácil ficar nebuloso quem aprovou o quê, compartilhar a tabela de níveis deixa claro num relance “esta operação é de quem dá o OK?”.

P. Não dá para dispensar a divisão em níveis só caprichando no prompt? O prompt oscila na interpretação. A habilidade de escrever bons pedidos você desenvolve à parte em Prompt engineering avançado; a divisão em níveis é a “rede de segurança que não depende do capricho da redação”. Ter as duas coisas é o mais forte.

O que confirmei ao testar de verdade

Depois que coloquei esses 4 níveis na operação do meu blog, os acidentes do tipo “fez até o que eu não pedi” do começo foram a zero. Confirmei dois pontos.

Um: ao referenciar o autonomy.yml a partir do CLAUDE.md, o Claude Code passou a declarar por conta própria, antes de trabalhar, “desta vez é nível 1, então não vou publicar”. Senti na prática que entregar a delimitação por nível, e não por texto, evita a oscilação de interpretação.

O outro: ao passar a rodar o verify-publish.mjs sempre depois de publicar, consegui detectar logo após a publicação aquele fenômeno de “página antiga aparecendo em produção” que antes me passava despercebido por meio dia. Só de olhar o h1 e a URL canônica, a armadilha do HTTP 200 fica tapada.

Em vez de caçar um modelo mais esperto, defina antes os níveis nos quais você não se machuca ao cair. Parece o caminho mais longo, mas, na minha experiência atual, é o mais rápido. Se você está no ponto de organizar as regras de permissão do Claude Code em time, podemos desenhar a delimitação juntos no treinamento e consultoria. Para a configuração oficial de permissões, confira também a documentação da Anthropic.