Pense em um cofre com várias camadas de segurança. O que o agente consegue fazer
é determinado pelas ferramentas que você lista no campo tools
— não pelo texto do prompt. O prompt diz "o que fazer"; as ferramentas dizem "com o que".
Misturar os dois é o erro mais comum ao criar subagentes.
Conteudo detalhado
🎯 Dar só o necessário
O princípio do mínimo privilégio é simples: um agente que não precisa escrever não deve ter permissão de escrever. Parece óbvio, mas é violado o tempo todo. O custo de ser generoso demais nas ferramentas não aparece no primeiro uso — aparece quando o agente toma uma decisão inesperada em produção.
Principio do minimo privilegio aplicado a subagentes
Cada ferramenta que voce adiciona ao campo tools
expande o raio de acao do agente. Expanda apenas quando o agente precisar da ferramenta para cumprir
o objetivo especifico. Quando em duvida, comece sem — voce pode adicionar depois; desfazer dano em
producao e muito mais caro.
Rascunho — sem restricao
Voce inclui tudo: Read, Write, Bash, WebSearch. O agente funciona mas nao e auditavel.
Refino — so o que usa
Voce observa quais ferramentas o agente realmente chamou. Remove o restante.
Producao — minimo validado
Apenas as ferramentas necessarias. O comportamento e previsivel e o risco, contido.
📖 Agentes read-only: Read, Grep, Glob
A maior parte dos agentes de analise, revisao e pesquisa nao precisa escrever nada.
O trio Read, Grep
e Glob cobre praticamente todo caso de uso de leitura —
inspecionar arquivos, buscar padroes, listar estrutura. Com apenas essas tres voce cria um agente
que pode aprender tudo sobre o repositorio sem mudar um byte.
✓ O que o trio cobre
- ✓Read — ler qualquer arquivo do projeto, incluindo configs e segredos (cuidado ao reportar)
- ✓Grep — buscar padrao em texto, ideal para achar funcoes, TODOs, imports
- ✓Glob — listar arquivos por padrao, mapear estrutura de pastas
- ✓Combinados: mapeamento completo + busca semantica + leitura de contexto
✗ O que eles nao fazem
- ✗Criar ou modificar arquivos (Write)
- ✗Executar comandos do sistema (Bash)
- ✗Fazer requests HTTP (WebFetch, WebSearch)
- ✗Interagir com MCP servers externos
Dica: Glob + Read em sequencia
Um padrao muito util: use Glob para descobrir quais arquivos existem, depois Read para ler apenas os relevantes. Isso e muito mais eficiente do que pedir para o agente "ler tudo" — ele vai priorizar pelo padrao que voce definiu no Glob.
⚖️ Allowed x disallowed — a lista concreta
O arquivo .md de um subagente tem um campo
tools que recebe uma lista. Tudo que esta na lista
e permitido — tudo fora dela e bloqueado automaticamente, sem nenhuma configuracao adicional.
Nao existe "negar explicitamente": voce inclui o que pode, o resto nao existe para o agente.
| Ferramenta | Categoria | Risco se incluida sem necessidade | Incluir quando... |
|---|---|---|---|
| Read | Leitura | Baixo (pode ler segredos) | Precisa inspecionar conteudo de arquivos |
| Grep | Busca | Baixo | Precisa buscar padroes no codebase |
| Glob | Listagem | Baixo | Precisa mapear estrutura de arquivos |
| Write | Escrita | Medio (modifica arquivos) | Agente precisa gerar ou editar artefatos |
| Edit | Escrita | Medio (patch em arquivos) | Agente precisa fazer edicoes precisas |
| Bash | Execucao | Alto (roda qualquer comando) | Agente precisa rodar scripts/testes |
| WebFetch | Rede | Alto (acesso externo) | Agente precisa buscar dados externos |
🔌 MCP permitidos — acesso a mundo externo
Ferramentas MCP (Model Context Protocol) dao ao agente acesso a sistemas externos: bancos de dados, APIs, navegadores, serviços. Sao mais poderosas — e mais arriscadas — que as ferramentas nativas. A decisao de incluir um MCP num subagente deve ser intencional e especifica: o agente precisa deste servidor MCP para completar sua funcao?
Como MCP servers sao herdados
Por padrao, subagentes herdam os MCP servers do contexto pai. Isso significa que se voce tem
um servidor de banco de dados configurado globalmente, o agente filho tambem pode acessa-lo
— a menos que voce restrinja explicitamente com mcpServers: []
(lista vazia = nenhum MCP) ou liste apenas os permitidos.
- →Heranca padrao: todos os MCP do contexto pai ficam disponiveis
- →Restricao total:
mcpServers: []— sem acesso a nenhum MCP - →Lista especifica: somente os servidores listados ficam disponiveis
✓ MCPs geralmente seguros para subagentes
- ✓MCP de leitura de banco de dados (somente SELECT)
- ✓MCP de busca (Brave, tavily) com rate limit
- ✓MCP de acesso a documentacao interna (read-only)
- ✓MCP de GitHub para leitura de PRs e issues
✗ MCPs que precisam de revisao cuidadosa
- ✗MCP que pode enviar e-mails ou mensagens
- ✗MCP com acesso de escrita a banco de dados
- ✗MCP de execucao de deploys ou infra
- ✗MCP de pagamentos ou faturamento
🛡️ Permissao real supera prompt "nao faca"
Uma das armadilhas mais comuns: colocar no prompt instrucoes como "nunca delete arquivos"
ou "nao execute comandos do sistema" enquanto o campo tools
ainda inclui Bash.
O prompt e orientacao; o campo tools e lei.
Instrucoes em texto natural podem ser mal-interpretadas, ignoradas sob pressao ou contornadas —
a lista de ferramentas nao.
Nao confie so no prompt para seguranca
O agente recebe o prompt como contexto de alto nivel, mas o LLM e um sistema probabilistico. Em cenarios de alta pressao, instrucoes ambíguas ou cadeias longas, ele pode:
- —Raciocinar que "a excecao se aplica a este caso especifico"
- —Interpretar uma instrucao vaga de maneira inesperada
- —Ser manipulado por prompt injection no conteudo que ele processa
Remova a ferramenta. Nao instrua o agente a nao usa-la.
Regra pratica: tools como contrato, prompt como estilo
Use o campo tools para definir o que o agente pode fazer (contrato imutavel). Use o prompt / description para definir como ele deve fazer (tom, formato, criterios). Misturar os dois — usar o prompt para proibir o que o tools permite — e uma falsa seguranca.
👁️ "Se pode ler, assuma que vai"
Quando voce inclui Read no campo tools,
o agente pode ler qualquer arquivo acessivel no projeto — inclusive .env,
chaves SSH, tokens em configs. Isso e esperado e util, mas exige que voce saiba o que o agente
pode fazer e que os relatorios que ele gera nao vazem dados sensiveis.
✗ Ruim: agente leu e reproduziu os valores no relatorio
Instrua o agente a nao reproduzir dados sensiveis
Para agentes com acesso a Read em projetos reais, inclua no prompt: "Nunca reproduza valores de variaveis de ambiente, chaves, tokens ou senhas nos relatorios. Mencione apenas que existem e se estao configuradas corretamente." Aqui o prompt SIM e o lugar certo — voce nao esta proibindo uma ferramenta, esta orientando o comportamento dentro do que e permitido.
🔬 Granularidade — Bash e o caso especial
Bash e a ferramenta mais poderosa e a que
exige maior cuidado. Com Bash, o agente pode rodar qualquer comando do sistema — instalar pacotes,
deletar arquivos, fazer requests com curl, iniciar processos. Quando Bash e necessario,
a granularidade vem da descricao precisa no prompt sobre
quais comandos sao esperados, combinada com allowedTools no settings.json
do projeto para restringir quais binarios podem ser chamados.
---
name: code-reviewer
description: |
Revisor de codigo que analisa qualidade, padroes e problemas potenciais.
Leia arquivos .ts, .js e .py no caminho indicado. Reporte: (1) problemas
criticos, (2) sugestoes de melhoria, (3) pontos positivos. Nao altere
nenhum arquivo. Nao execute comandos. Entregue um relatorio estruturado.
tools:
- Read
- Grep
- Glob
# Sem Write, sem Edit, sem Bash, sem WebFetch
# Nenhum MCP server necessario para este agente
---Prompts prontos
"Crie um subagente chamado doc-auditor que seja completamente read-only. Ele deve ler arquivos Markdown no diretorio /docs, verificar se cada um tem frontmatter com 'title', 'date' e 'author', e gerar um relatorio de compliance. Liste as ferramentas necessarias e explique por que nao precisa de Write ou Bash."
"Leia o arquivo .claude/agents/meu-agente.md e avalie se as ferramentas listadas em tools sao todas necessarias para a tarefa descrita em description. Para cada ferramenta, diga: necessaria, desnecessaria, ou depende. Sugira uma versao enxuta da lista de tools."
"Quero um agente que verifique se o arquivo package.json tem a dependencia X. Explique como fazer isso com apenas Read (sem Bash) e quando seria necessario adicionar Bash. Qual e o risco de cada abordagem?"
Exercicio
Crie o arquivo .claude/agents/log-analyzer.md
para um agente que analisa arquivos de log (.log, .txt) em busca de erros criticos
e gera um relatorio com: quantidade de erros por nivel (ERROR, WARN, FATAL), os 5 erros mais frequentes,
e uma linha de recomendacao. O agente nao pode modificar nenhum arquivo.
Passos
- 1Defina o campo
tools— liste APENAS as ferramentas necessarias para leitura e busca em arquivos de texto. - 2Escreva o campo
descriptioncom instrucoes claras de como relatar os resultados (sem reproduzir linhas completas de log). - 3Verifique: o agente precisa de Bash? Precisa de Write? Se nao, remova.
- 4Teste invocando: "use o agente log-analyzer para inspecionar os arquivos em /tmp/logs"
Criterio de verificacao — como saber que acertou
O agente esta correto se atender a todos os criterios abaixo:
- ✓Minimo necessario: tools contem apenas Read, Grep e Glob — sem Write, Edit, Bash ou ferramentas de rede.
- ✓Description precisa: o campo description especifica os tres itens do relatorio (contagem, top-5, recomendacao).
- ✓Sem falsa seguranca: nao ha instrucao no prompt proibindo Write — Write simplesmente nao esta em tools.
- ✓Dados sensiveis: description orienta a nao reproduzir linhas completas de stack trace com dados de usuario.
- ✓Testavel: ao invocar o agente, ele completa sem solicitar permissoes extras e sem tentar editar arquivos.
Proximo modulo:
2.5 — Projeto x Global. Quando colocar o agente em .claude/agents/ do projeto versus na pasta global do usuario.