Agente no Claude Code: o que é um subagente e quando criar um

O que é um agente no Claude Code

Um agente, ou subagente, é um assistente dentro do Claude Code que tem prompt de sistema próprio, ferramentas próprias e permissões próprias. A diferença que mais pesa no dia a dia: ele roda numa janela de contexto separada da sua conversa principal, e quando termina, devolve só um resumo. O que ele leu no meio do caminho, como uma busca com cem resultados ou um log inteiro, fica no contexto dele, não no seu.

Isso serve para duas coisas que a skill comum não resolve bem. Primeiro, isolar o custo: se uma tarefa precisa ler muita coisa para decidir pouco, o agente evita que essa leitura encha o seu contexto principal e deixe a conversa lenta. Segundo, separar a permissão: você pode dar a um agente de revisão de código só leitura, sem ele poder escrever ou rodar comandos, mesmo que a sua sessão principal tenha mais acesso.

Onde fica o arquivo do agente

O lugar onde o arquivo é salvo decide onde o agente vale:

Onde	Caminho	Vale para
Pessoal	~/.claude/agents/<nome>.md	todos os seus projetos nesta máquina
Projeto	.claude/agents/<nome>.md	só aquele repositório, e vai no git para quem trabalha nele
Sessão	flag --agents na linha de comando	só a sessão atual
Organização	configuração gerenciada pela empresa	todo mundo, com prioridade sobre as outras

Para quem atende mais de um cliente, a lógica é a mesma das skills: o agente que conhece o tom de um cliente fica no repositório daquele cliente, nunca no pessoal.

Agente e skill: qual a diferença

As duas coisas são arquivos .md com um cabeçalho que diz quando usar. A diferença é onde elas rodam e o que carregam.

A skill entra na sua conversa atual. O corpo dela só é lido quando a tarefa combina com a description, mas, uma vez lido, fica no mesmo contexto que o resto da conversa. É leve e rápida para uma tarefa que você já explicou mais de duas vezes, como escrever um relatório num formato fixo.

O agente abre uma conversa própria, com as ferramentas e o modelo que o cabeçalho dele define, e volta só com o resultado final. É a escolha certa quando a tarefa tem muitos passos de busca, muita leitura descartável, ou quando você quer travar o que aquele agente pode fazer, por exemplo deixando um agente de auditoria só com permissão de leitura.

Na prática: se a tarefa é “faça X do jeito que sempre faço”, é skill. Se é “investigue Y e me diga o que achou”, sem precisar ver o caminho da investigação, é agente.

Como criar o seu primeiro agente

O exemplo abaixo é um agente de revisão de segurança, que só lê o código e nunca escreve nele.

1. Crie o arquivo: .claude/agents/revisor-seguranca.md, dentro do repositório onde ele vai trabalhar.
2. Escreva o cabeçalho e o prompt:

---
name: revisor-seguranca
description: Audita código por falhas de segurança antes do deploy. Use
  quando pedirem revisão de segurança ou antes de mergear PR que toca em
  autenticação, pagamento ou dados do cliente.
tools: Read, Grep, Glob
model: sonnet
---

Você é um auditor de segurança. Procure injeção de SQL, XSS, falha de
autenticação, segredo gravado no código e criptografia fraca.

Para cada achado, explique a falha, mostre o trecho e sugira a correção.
Nunca edite o código: só leia e relate.

3. Chame de um dos três jeitos: escreva “use o agente revisor-seguranca nas mudanças de hoje” na conversa, digite @ e escolha ele na lista, ou rode claude --agent revisor-seguranca para a sessão inteira seguir essas regras.

Dois cuidados que fazem o agente valer o isolamento:

• A description é o que decide a delegação automática. Se ela for vaga, o Claude não vai saber quando chamar o agente sozinho; você vai precisar nomear ele toda vez.
• Restrinja as ferramentas ao que o agente precisa. Um agente de leitura com tools: Read, Grep, Glob não escreve em nada por engano, mesmo que a conversa principal tenha mais acesso.

Quando vale criar um agente, e quando a skill resolve

A pergunta não é qual é melhor: é qual separa o trabalho certo.

• Skill para o que você repete toda semana e cabe num procedimento fixo: um relatório, um formato de post, uma resposta padrão.
• Agente para o que exige investigação com volume de leitura que você não quer na sua conversa: uma auditoria, uma varredura de logs, uma pesquisa com muitas páginas antes da resposta final.
• Os dois juntos quando uma tarefa grande se divide em partes: um agente que só pesquisa e devolve um resumo, e uma skill que usa esse resumo para montar a peça final, no formato que você já define.

Um pacote pronto, se você não quer montar do zero

O NutekOS chega com 17 skills de marketing instaladas e o /diretor, que recebe o seu pedido em português e escolhe qual delas usar: site, blog, carrossel ou anúncio do Google. Você não precisa escrever o cabeçalho de nada disso: o /instalar configura a máquina e o /mapear-rotinas cria skill nova para a tarefa que você repete e que ainda não está na lista.

Ele não ensina a programar e não substitui o Claude Code: precisa da sua assinatura do Claude Code, do Node e do git instalados.