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. Se você quer transformar essa automação em produto, veja nossas ideias de micro SaaS para fundadores solo. 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.