Até onde devemos conceder permissões ao meu computador para as ferramentas de desenvolvimento de agentes?

A era em que os editores apenas sugeriam código acabou. Agora, agentes como o Claude Code abrem o terminal diretamente, vasculham o sistema de arquivos e modificam o código. É conveniente, mas por outro lado, é assustador. Um único prompt injection poderia vazar arquivos .env ou chaves SSH para o exterior. Precisamos de métodos de controle específicos que deem autonomia ao agente, mas o impeçam de cruzar a linha.

Escrevendo uma "Constituição" para o Agente na Raiz do Projeto

Por padrão, os agentes tentam varrer todo o projeto para executar comandos. Se deixarmos isso sem supervisão, há o risco de lerem configurações sensíveis. A defesa mais segura é criar um arquivo de regras exclusivo para o agente no diretório raiz do projeto.

1. Crie um arquivo CLAUDE.md ou .agent-rules na raiz.
2. Especifique caminhos de acesso proibidos dentro do arquivo. Regras deny devem ser inseridas para que caminhos como .env, ~/.ssh e ~/.aws/credentials sequer sejam visualizados.
3. Ao executar o agente, use a opção --allowedTools para permitir apenas as funcionalidades necessárias. É uma forma de ativar apenas ferramentas mínimas, como Bash, Read ou Write.

Ao usar o modo Default das permissões do Claude Code, que exige aprovação do usuário para todas as operações de escrita, você pode bloquear fisicamente o risco de vazamento de código-fonte. Um único arquivo de configuração é suficiente para evitar acidentes onde o agente envia variáveis de ambiente para fora sem a sua permissão.

Como evitar que um agente em loop esvazie sua carteira

Ferramentas centradas em agentes planejam e executam por conta própria. O problema surge quando eles caem em erros lógicos. Um agente que não consegue encontrar uma solução pode entrar em um loop infinito, repetindo chamadas de API e gerando cobranças de dezenas de dólares em instantes. De acordo com dados de pesquisa da Anthropic, definir critérios de saída (Exit Criteria) explícitos no prompt pode reduzir o tempo de execução em até 62%.

Para evitar a explosão de custos, você deve projetar um "disjuntor" diretamente no prompt:

• Limite de tentativas: Adicione uma restrição ao final do comando como: "Se não for resolvido após no máximo 5 tentativas, pare imediatamente e reporte a causa da falha".
• Critérios de sucesso objetivos: Instruções subjetivas como "termine quando o código parecer bom" são as piores. Em vez disso, especifique o npm test ou a passagem em testes de unidade específicos como o critério absoluto de conclusão.
• Restrição de contexto: Use padrões glob (Glob patterns) no arquivo .cursorrules para limitar o agente a ler apenas regras de diretórios específicos, como src/api/**/*, evitando o desperdício desnecessário de tokens.

Configurar esses portões de saída suprime o consumo de tokens causado por instruções ambíguas, economizando mais de 40% no custo médio mensal de API.

Fluxo de trabalho isolado para não poluir o branch principal

O método onde o agente modifica arquivos locais diretamente é rápido, mas perigoso, pois um código não verificado pode quebrar o branch principal. A equipe de engenharia do Shopify, ao operar sua própria ferramenta de agente chamada Sidekick, introduziu um método de validação cruzada dos resultados com um modelo separado. Nós também devemos separar uma área de trabalho exclusiva para o agente.

A maneira mais limpa é usar o git worktree. Crie um diretório e um branch independentes exclusivos para a sessão do agente e atribua o trabalho a ele. Quando o trabalho terminar, peça para ele executar um git diff e relatar um resumo das alterações, e faça com que execute testes de unidade automaticamente com ferramentas como Playwright ou Vitest. Seguindo este processo, você pode reduzir o tempo de revisão manual em 70%, integrando apenas código verificado ao branch principal.

Ajustando as configurações do IDE que atrapalham a velocidade do agente

A velocidade com que um agente escreve código é muito superior à digitação humana. Se a função editor.formatOnSave do VS Code estiver ativada, o formato do arquivo pode mudar forçadamente enquanto o agente está escrevendo, causando erros de correspondência de texto (text matching). É como se a ferramenta estivesse tropeçando nos próprios pés.

Além disso, shells não interativos executados por agentes muitas vezes falham ao executar ferramentas por não conseguirem ler as variáveis de ambiente configuradas no .zshrc.

1. Desative editor.formatOnSave definindo como false no .vscode/settings.json do projeto colaborativo.
2. Configurações de PATH ou chaves de API devem ser movidas do .zshrc para o arquivo .zshenv, que é carregado independentemente do modo de execução do shell.
3. Em vez disso, use o Husky para configurar hooks de pré-commit, de modo que o linter e o formatador rodem apenas quando o agente terminar o trabalho e fizer o commit.

Se você não quer ver um agente parado de forma estúpida por não encontrar variáveis de ambiente, deve revisar as configurações do shell primeiro.

Categoria de Configuração	Nome do Arquivo	Conteúdo Recomendado	Visibilidade do Agente
Variáveis de Ambiente Globais	.zshenv	PATH, API_KEY, caminhos de SDK	Carregado em todas as sessões
Configurações Interativas	.zshrc	alias, prompt, theme	Pode ser ignorado na execução do agente
Configurações de Login	.zprofile	Scripts de inicialização global do sistema	Válido apenas em shells de login