Antes de deixar o agente rodar o setup, trate o repositório como não confiável

Tem um pedido que parece totalmente inocente:

"Clona esse projeto, instala as dependências e roda os testes."

Se você faz isso manualmente, talvez dê uma olhada no package.json, veja se tem um postinstall, confira o README, desconfie de um script estranho. Talvez não faça nada disso, porque todo mundo já rodou npm install no automático alguma vez na vida.

Agora coloca um agente nessa história.

Ele não está só lendo o projeto. Ele pode abrir terminal, instalar pacote, rodar script, seguir instrução de README, tentar corrigir erro de setup e executar mais comandos para "ajudar". O que antes era uma etapa meio chata de onboarding vira uma fronteira de segurança.

A pergunta prática não é "agentes são perigosos?". Essa pergunta é grande demais e ajuda pouco. A pergunta melhor é:

quais comandos o agente pode rodar antes de você entender o repositório?

Setup também é execução de código

A gente costuma falar de segurança olhando para o código que vai para produção. Faz sentido. É onde ficam bug, vazamento, autenticação mal feita, regra de negócio quebrada.

Mas o setup acontece antes disso tudo.

É ali que o projeto pede para você instalar dependências, rodar bootstrap, gerar arquivo local, iniciar banco, aplicar migration, compilar assets, baixar binário, configurar hook, copiar .env.example e por aí vai.

Para um humano atento, cada passo desses tem algum atrito. Você vê o comando. Decide se aceita. Pode parar e abrir o arquivo antes.

Para um agente prestativo, o fluxo pode virar uma sequência rápida:

npm install
npm run setup
npm test

Se falhar:

npm run fix
curl alguma-coisa | sh

Estou exagerando um pouco no exemplo, mas não tanto quanto eu gostaria.

O ponto é simples: um repositório recém-clonado ainda não ganhou sua confiança. Então o agente também não deveria tratar aquele setup como confiável só porque o README parece bem escrito.

Onde o risco costuma se esconder

O risco nem sempre vem de um arquivo chamado malware.sh.

Seria até fácil se viesse.

Na prática, ele aparece em lugares que parecem normais dentro de um projeto:

• scripts de install, postinstall, prepare e bootstrap;
• comandos copiados do README sem inspeção;
• hooks de package manager;
• ferramentas que baixam ou executam binários;
• arquivos de configuração que disparam automação;
• comandos de diagnóstico que acessam rede, shell ou variáveis de ambiente;
• testes que assumem serviços locais, chaves ou arquivos fora do repo.

Nada disso é automaticamente ruim. Muito projeto legítimo precisa de scripts de setup.

O problema é permissão sem contexto.

Quando você entrega o terminal para um agente e diz "resolve", ele pode atravessar esses pontos antes de você perceber que o repositório está pedindo mais acesso do que deveria.

E tem um detalhe importante: agente não sente desconfiança. Ele pode simular cautela se for instruído, mas a cautela precisa estar no processo. Sem isso, a tendência dele é completar a tarefa.

O meio termo não é travar tudo

Também não dá para transformar cada comando em uma audiência pública.

Se toda vez que o agente quiser rodar npm test você precisar aprovar três telas, a produtividade morre. A ideia de usar agente é justamente tirar peso operacional da mão do dev.

O meio útil é uma política curta de permissão.

Não precisa ser um documento gigante. Pode começar com algo assim:

• comandos de leitura estão liberados;
• comandos de teste conhecidos podem rodar;
• instalação de dependências em repo novo precisa de revisão;
• scripts de setup precisam ser lidos antes;
• qualquer comando com rede, shell amplo ou efeito destrutivo pede aprovação;
• tokens e variáveis sensíveis não entram no ambiente por padrão.

Isso já muda bastante o jogo.

Você não está dizendo para o agente "não faça nada". Está dizendo: "faça dentro desses trilhos".

Peça plano antes de comando

Um hábito simples ajuda muito: antes do agente executar setup em um repo novo, peça um plano.

Algo direto:

Antes de rodar comandos, leia os arquivos de setup e me diga:
- quais scripts pretende executar;
- se algum script acessa rede, shell, binários externos ou variáveis de ambiente;
- quais comandos são apenas leitura;
- quais comandos precisam da minha aprovação.

Esse tipo de prompt não resolve tudo. Mas força uma pausa.

A pausa é valiosa porque o problema do agente não é só errar. É errar rápido, com confiança e dentro do seu terminal.

Quando ele descreve o plano, você consegue separar o que é rotina do que merece olhar com calma. npm test em um projeto que você já conhece é uma coisa. npm run setup:local em um repo desconhecido é outra. curl ... | sh deveria acender luz vermelha em qualquer contexto.

Use ambiente descartável quando o repo é novo

Se o repositório é desconhecido, eu evitaria rodar o primeiro setup no mesmo ambiente onde ficam seus tokens, chaves SSH, sessão de cloud, arquivos pessoais e configs do trabalho.

Pode ser um container. Pode ser uma VM. Pode ser uma máquina descartável. Pode ser um workspace com variáveis mínimas.

O nome da tecnologia importa menos que a regra:

o primeiro contato com um projeto novo deve ter pouco a perder.

Isso vale ainda mais quando o agente está no comando. Ele pode abrir arquivos, tentar comandos alternativos e seguir pistas do próprio projeto. Se o ambiente já vem cheio de segredo, você está dando ao setup um prêmio grande demais.

Um fluxo mais saudável seria:

1. clonar o repo em ambiente limpo;
2. pedir ao agente para mapear scripts e dependências;
3. aprovar manualmente os comandos de instalação;
4. rodar testes sem tokens reais;
5. só depois aproximar o projeto do ambiente de desenvolvimento principal.

Não é glamour. É higiene.

Segredo local não deveria ser brinde de setup

Muita gente usa agente no mesmo terminal em que já está logada em tudo.

GitHub, npm, cloud, banco, analytics, ferramenta interna, chave em .env, token em variável global. Para o humano, isso é conveniente. Para um agente rodando comando de repo desconhecido, é uma superfície enorme.

Minha regra seria chata de propósito: agente começa sem segredo.

Se uma tarefa precisa de token, você injeta o mínimo necessário e pelo menor tempo possível. Se precisa de acesso à rede, você entende por quê. Se precisa escrever fora do diretório do projeto, isso vira aprovação explícita.

De novo: não é paranoia. É reduzir o estrago possível.

Um setup malicioso, quebrado ou só descuidado não deveria conseguir ler mais do que precisa para instalar e testar aquele projeto.

Registre o que foi executado

Depois que o agente roda comandos, o rastro importa.

Não precisa guardar cada linha de log. Mas vale deixar registrado:

• comandos executados;
• comandos recusados;
• arquivos de setup inspecionados;
• testes que passaram;
• testes que falharam;
• qualquer acesso a rede, segredo ou caminho fora do repo.

Isso ajuda em duas situações.

Primeiro, no review. Se o agente abriu PR depois do setup, quem revisa consegue entender o ambiente em que a mudança nasceu.

Segundo, no incidente pequeno. Sabe aquele momento em que algo estranho acontece e você pensa "será que esse script mexeu em alguma coisa?" Sem rastro, vira adivinhação.

Com rastro, você pelo menos sabe por onde começar.

Um checklist pequeno para usar hoje

Se você usa Codex, Claude Code, Cursor ou qualquer agente que consiga operar no terminal, eu começaria com este checklist para repo novo:

• peça um plano antes de rodar comandos;
• leia package.json, scripts de setup e hooks antes de instalar;
• rode o primeiro setup em ambiente descartável quando possível;
• não exponha tokens por padrão;
• aprove comandos com rede, shell amplo ou efeito destrutivo;
• recuse curl | sh automático;
• registre comandos executados e validações;
• se o agente precisar improvisar, faça ele parar e explicar antes.

Nada disso impede você de usar agente. Pelo contrário: deixa o uso mais tranquilo.

O agente continua fazendo o trabalho chato. Só não ganha permissão para transformar um README simpático em execução cega.

Autonomia boa tem limite claro

Eu gosto de agentes de código justamente porque eles tiram atrito de tarefas que antes consumiam uma manhã inteira.

Mas quanto mais eles entram no fluxo real, menos faz sentido tratá-los como autocomplete esperto. Um agente que configura projeto, roda teste e mexe no terminal já está operando parte do seu ambiente.

Então o setup precisa mudar de categoria mental.

Não é "só instalar e ver no que dá". É execução de código não confiável até prova em contrário.

Autonomia boa não é deixar o agente fazer qualquer coisa. É dar trilhos claros para ele errar barato, pedir aprovação quando o risco sobe e deixar você no controle das decisões perigosas.

Notas de fonte

• Tom's Hardware sobre demonstração da Mozilla 0din envolvendo agentes de código e setup aparentemente limpo.
• "From Determinism to Delegation" como apoio conceitual para o papel do dev como supervisor de workflows.
• "The Shift to Agentic AI: Evidence from Codex" e cobertura da Axios como contexto de adoção de agentes em fluxos reais.
• "Coding Beyond Your Training" como apoio para o tradeoff entre ampliar a stack e aumentar a necessidade de supervisão.