Claude Code Agents: como criar seu primeiro subagent

Claude Code Agents são subagents especializados que você cria com um arquivo Markdown em .claude/agents/, cada um com system prompt, tools restritas e modelo próprios. Basta escrever o frontmatter YAML com name e description, salvar e o Claude passa a delegar tarefas pra ele sozinho. Neste guia você monta seu primeiro subagent do zero, aprende a dar skills, agendar com cron e orquestrar vários agentes ao mesmo tempo, do básico ao avançado.

Aliás, a pressa faz sentido. Segundo a Stack Overflow Developer Survey 2024, 76% dos desenvolvedores já usam ou planejam usar IA no fluxo de trabalho, e ferramentas como o Claude Code lideram esse movimento. Portanto, entender Claude Code Agents deixou de ser curiosidade e virou vantagem prática. Além disso, o recurso serve tanto pra quem nunca abriu um terminal quanto pra quem já orquestra pipelines inteiros com IA.

O que são Claude Code Agents?

Na prática, um agente no Claude Code é uma instância paralela do Claude com janela de contexto separada, system prompt próprio e uma lista de tools que você define. Na prática, ele funciona como um assistente dentro do assistente. Quando a conversa principal encontra uma tarefa lateral, ela dispara o agente, que trabalha isolado e devolve só o resultado final. Dessa forma, o conteúdo intermediário nunca polui a thread principal.

Por exemplo, pense numa redação de jornal. Por exemplo, o editor-chefe não escreve cada matéria, ele delega a repórteres especializados. Um cobre esportes, outro cobre economia. Além disso, cada repórter tem sua própria mesa e suas próprias fontes. Assim funcionam os Claude Code Agents: cada subagent domina um assunto, mantém seu contexto limpo e responde ao agente principal. Por isso o ganho vem de arquitetura melhor, não de prompt maior.

Para o iniciante, a leitura é simples: agente é um especialista que você configura uma vez e reusa sempre. Para o dev avançado, a definição importa mais: segundo a documentação oficial da Anthropic, cada subagent herda as permissões da sessão principal, mas pode receber restrições adicionais. Ou seja, você delega uma tarefa de leitura a um modelo barato sem nunca expor capacidade de escrita.

Agentes vs subagents: qual a diferença?

Na prática, essa dúvida aparece cedo, então vale esclarecer. No vocabulário da Anthropic, os Claude Code Agents nascem do agente principal, que é o Claude Code em si, o programa que conversa com você no terminal. Já o “subagent” é cada especialista que esse agente principal pode invocar. Na conversa do dia a dia, muita gente usa os dois termos como sinônimo, e tudo bem. Contudo, na hora de configurar, a distinção fica clara: você cria subagents, e o agente principal os despacha.

Inclusive, além dos que você cria, o Claude Code já vem com subagents embutidos. O Explore roda em modelo Haiku e só lê arquivos, ideal pra vasculhar a base de código sem gastar tokens. O Plan pesquisa antes de propor uma estratégia. O general-purpose é o canivete suíço, com todas as tools liberadas. Por isso, antes de criar qualquer agente, experimente os built-in. Eles cobrem boa parte dos casos onde isolar contexto já resolve.

Como criar seu primeiro subagent no Claude Code (passo a passo)

Agora chegou a parte prática. Dessa forma, os Claude Code Agents personalizados moram em dois lugares. Dentro do projeto, em .claude/agents/, ele fica versionado no Git e vale pro time inteiro. No seu home, em ~/.claude/agents/, ele acompanha você em todos os projetos. Portanto, a regra é simples: agente do time vai pro projeto, agente pessoal vai pro home.

Primeiro, crie a pasta e um arquivo Markdown. Além disso, cada arquivo tem duas partes: o frontmatter YAML no topo (a configuração) e o corpo abaixo (o system prompt). Veja a seguir um subagent revisor de código completo, pronto pra copiar:

Depois de salvar, reinicie a sessão do Claude Code. Em seguida, o agente já aparece disponível. Você pode pedir “revise as mudanças” e o Claude despacha pro code-improver automaticamente, porque a description casa com a tarefa. De fato, esse campo é o mais importante do arquivo: é por ele que o Claude decide quando delegar. Por isso escreva descriptions específicas, com gatilhos claros como “use após modificar código”.

Aliás, um detalhe crucial para quem está começando: o corpo Markdown vira o system prompt, e o subagent não enxerga o histórico da conversa principal nem o CLAUDE.md do projeto. Ou seja, ele só recebe o que você escreveu no arquivo e a instrução da invocação. Dessa forma, as instruções precisam ser autossuficientes. Na prática, supor contexto externo é o erro número um de quem cria o primeiro agente.

Configuração avançada: tools, model e invocação

Em seguida, com o básico funcionando, três campos do frontmatter dão poder real ao agente. O campo tools restringe o que ele pode fazer. Ao listar só Read, Grep, Glob, você garante que o revisor jamais edita nada. Por outro lado, se omitir o campo, o subagent herda todas as tools da sessão principal. Na prática, allowlist curta é o que separa agente útil de agente perigoso.

O campo model controla custo e velocidade. Tarefas de leitura e triagem vão bem em haiku, que é mais rápido e barato. Já revisões complexas ou geração de código pedem sonnet ou opus. Assim, rotear cada tarefa pro modelo certo evita queimar tokens caros num trabalho simples. Inclusive, esse é um trade-off que a própria documentação recomenda: barato para o volume, potente para o gargalo.

Por fim, existe a invocação. Além do roteamento automático pela description, você pode chamar um agente na mão. No chat, escreva @code-improver para forçar o despacho. Já no modo headless, que veremos adiante, a flag --agent aponta direto pro subagent. Veja o esqueleto de um agente de pesquisa, o researcher, simplificado:

Inclusive, repare no contrato de saída: JSON puro. Dois subagents podem conversar justamente por esse formato: um researcher devolve o briefing, e um writer consome esse briefing pra escrever o texto. Ou seja, a saída de um agente é a entrada do próximo. É esse contrato que torna o pipeline previsível e fácil de depurar.

Skills: como dar habilidades aos seus agentes

Se o subagent é um trabalhador, a skill é o manual de procedimento que ele consulta. Uma skill vive em .claude/skills/<nome>/SKILL.md, como detalha a documentação de skills da Anthropic, e segue o padrão aberto agentskills.io. Na essência, ela empacota um passo a passo reutilizável que os Claude Code Agents carregam apenas quando precisam. Por isso o custo é baixo: o corpo da skill só entra no contexto no momento do uso, num mecanismo chamado progressive disclosure.

Na prática, para o iniciante, pense na skill como uma receita salva. Você escreve uma vez “como fazer deploy” e, sempre que pede deploy, o Claude segue a receita sem você repetir os passos. Veja a seguir uma skill simples:

Além disso, para o dev avançado, os campos do frontmatter mudam o comportamento. Com disable-model-invocation: true, a skill só roda quando você digita /deploy, nunca de forma automática. Sem esse campo, o Claude a carrega sozinho quando a description casa. O allowed-tools restringe as ferramentas, e o context: fork faz a skill rodar dentro de um subagent separado. Assim, você combina os dois conceitos: uma skill que executa em contexto isolado.

Inclusive, vale uma nota histórica: os antigos custom commands viraram skills. Um arquivo .claude/commands/x.md equivale hoje a .claude/skills/x/SKILL.md. Portanto, se você já usava comandos, sua migração é quase automática. Para um catálogo do que a comunidade já publicou, veja as skills mais populares do Claude Code e economize trabalho.

Subagent, skill ou MCP: quando usar cada um

Ao desenhar Claude Code Agents, os três termos se confundem, mas resolvem problemas diferentes. Por exemplo, o subagent é um trabalhador com contexto próprio. A skill é um procedimento reutilizável que os Claude Code Agents consultam no mesmo contexto. No entanto, o MCP conecta ferramentas e dados externos, como bancos e APIs. A tabela abaixo resume a escolha para não errar na hora de desenhar seu setup.

Na prática, os três se combinam. Um subagent usa skills como procedimento e MCP como fonte de dados. Se você quer se aprofundar em conectar ferramentas externas, veja nosso guia de MCP Server no Claude Code. Dessa forma, você entende a peça que falta pra montar agentes que tocam o mundo real.

Schedule, loops e cron: agende tarefas dos agentes

Criar Claude Code Agents é metade do caminho. Na prática, a outra metade é fazer eles rodarem sozinhos, sem você digitar nada. Aqui entra o modo headless, o coração da automação. Com a flag -p (ou --print), o Claude Code roda sem interface interativa, executa a tarefa e devolve o resultado. Portanto, é isso que você agenda num cron ou dispara num pipeline de CI.

Por exemplo, veja a seguir o comando que aciona um agente específico de forma não interativa:

Na prática, cada flag tem um papel. A --agent escolhe qual subagent conduz a sessão. A --permission-mode acceptEdits evita que o Claude pare pra pedir confirmação, essencial em execução automática. A --allowedTools limita o que ele pode fazer, e a --output-format json traz até o campo total_cost_usd, útil pra monitorar gasto. Assim, você tem uma execução previsível e auditável.

Por exemplo, para o iniciante, o jeito mais fácil de agendar mora dentro da própria sessão. O comando /loop repete uma tarefa em intervalos, e o /scheduled-tasks lista o que está agendado. Você abre o Claude Code, digita /loop 30m "checa novos comentários" e pronto, ele repete a cada 30 minutos. Além disso, nenhuma configuração de sistema é necessária.

Do /loop ao cron: agendamento no sistema

Por outro lado, para o dev avançado, o cron do sistema operacional dá controle total. Basta envolver o comando claude -p num script e apontar o cron pra ele. Veja um exemplo que roda a auditoria toda manhã às 9h:

No macOS, o launchd cumpre o mesmo papel do cron com mais robustez. Se quiser um passo a passo dedicado a essa parte, temos um guia inteiro sobre cron jobs no Claude Code. E para automações que disparam a partir de outros sistemas, vale ver como integrar o n8n com o Claude Code. Dessa forma, seus agentes deixam de depender da sua presença no teclado.

Orquestração: vários subagents trabalhando juntos

Por fim, o poder real aparece quando os agentes cooperam. Um agente principal pode disparar vários subagents, receber os resultados e consolidar tudo. Um pipeline assim funciona como uma linha de montagem onde cada subagent cuida de uma etapa. Veja como as peças se encaixam:

Contudo, existe uma regra de ouro que muda o desenho: um subagent não pode chamar outro subagent. Inclusive, a Anthropic bloqueia isso de propósito, pra evitar recursão infinita e custo descontrolado. Por isso o squad precisa ser linear, não uma árvore. Assim, o agente principal despacha os N subagents, e cada um trabalha isolado. Se você precisa de hierarquia, roda um claude --agent em um shell separado.

Portanto, recomendamos começar os seus Claude Code Agents com três subagents focados, como pesquisador, escritor e auditor, antes de virar um zoo de dez agentes. De fato, cada agente extra dilui o ganho de contexto isolado se o principal não souber roteá-los bem. Por isso, preferimos poucos agentes com contratos claros a muitos agentes vagos. Para entender a filosofia por trás de dividir tarefas em IA, vale a leitura sobre agentic engineering, e sobre o Claude Cowork, que leva a autonomia adiante. O próprio uso do Claude Code dentro da Anthropic mostra o quanto esse padrão de orquestração escala.

Conclusão e próximos passos

Os Claude Code Agents não são um enfeite do terminal. Eles reorganizam a forma como você usa IA pra trabalho técnico. Por outro lado, quem trata o agente como “assistente extra” perde o ponto. Quem desenha um squad com contratos JSON, tools restritas e agendamento entrega resultado em produção com previsibilidade. Portanto, o pulo do gato está na arquitetura, não no tamanho do prompt.

Um ponto que nenhuma automação dispensa: a responsabilidade final é sua. O agente executa a etapa, mas quem comanda precisa auditar a saída e validar se está tudo conforme o esperado antes de confiar nela. Além disso, os subagents e as skills automatizam o trabalho pesado, porém a decisão, a revisão e a qualidade continuam nas suas mãos. No fim, o trabalho é seu; eles só aceleram as etapas.

Por fim, comece hoje mesmo, do jeito mais simples. Primeiro, crie um único subagent revisor em .claude/agents/. Em seguida, transforme uma tarefa repetitiva numa skill. Por fim, agende esse fluxo com /loop ou cron e observe o tempo que você economiza. Dessa forma, você sai do zero pra um pipeline funcional em uma tarde, e depois é só refinar cada peça.