Sumário · 11 seções0% lido
Resumo
Para criar um agente no Claude Code, você escreve um arquivo Markdown em .claude/agents com nome, descrição, ferramentas liberadas e instruções claras do que é a tarefa e do que é considerado pronto. Comece com uma tarefa pequena, libere só as ferramentas necessárias, rode, confira o resultado e ajuste as instruções, não o modelo.
O que o vídeo mostra
O vídeo explica a diferença entre fluxo e agente e mostra os três níveis de criar um agente. Depois cria, na prática, um agente que lê uma pasta de anotações e gera um arquivo pendencias.md só com o que ainda está em aberto, rodando no Claude Code desktop. No fim, aponta os erros mais comuns de quem começa.
- 0:00 O agente pronto, rodando
- 0:47 Fluxo ou agente: qual a diferença
- 1:38 Agente de IA em uma frase
- 2:03 O que um agente não é
- 2:22 Os três níveis de criar um agente
- 4:49 O plano em 5 passos
- 6:37 Criando a pasta .claude/agents
- 7:36 O arquivo do agente: frontmatter, tarefa e limites
- 10:24 Salvando o agente e as anotações de exemplo
- 11:37 Rodando o agente no Claude Code
- 13:24 O resultado: pendencias.md
- 14:10 Depois: subagentes
- 14:23 Os erros de quem começa
- 15:22 O meu plano com agentes
- 16:35 Resumindo
Qual a diferença entre fluxo e agente de IA?
Num fluxo, o caminho é fixo: passo A, B, C, D. A IA pode até ser chamada no meio, para resumir ou classificar algo, mas quem decide a direção é o desenho do fluxo. Se o resultado depende de a ordem das etapas ser sempre a mesma, você quer um fluxo.
Num agente, o modelo recebe a tarefa, escolhe a ferramenta, executa, olha o resultado e decide o próximo passo, em ciclos, até concluir. No exemplo do vídeo, o agente listou a pasta, leu as notas e escreveu o arquivo sem que ninguém tivesse escrito essa ordem.
Um agente não é autônomo no sentido de fazer o que quiser. Ele trabalha com as ferramentas que você liberou e dentro das regras que você escreveu. A qualidade do resultado depende mais da sua instrução do que de qualquer característica misteriosa do modelo.
- Use fluxo quando o caminho é conhecido e se repete igual.
- Use agente quando o próximo passo depende do que foi encontrado no passo anterior.
- Misturar os dois é comum: um fluxo que dispara um agente, ou um agente que roda dentro de uma etapa do fluxo.
Quais são os três níveis de criar um agente?
O primeiro nível é usar um agente que já existe. O Claude Code já é um agente: você pede uma tarefa e ele lê arquivos, escreve código e decide o que fazer. Você não criou nada, só usou.
O segundo nível é especializar. Você dá a um agente uma descrição de cargo: o que ele faz, quais ferramentas pode usar, o que conta como pronto e quais são os limites. É o nível que a maioria das pessoas usa no dia a dia e é o foco do vídeo.
O terceiro nível é construir do zero: escrever o ciclo, definir as ferramentas, integrar com a API de um modelo. Faz sentido quando a solução precisa ser muito específica, por exemplo para uma empresa com um requisito que nenhuma ferramenta pronta atende. Para começar, o nível dois costuma resolver.
Como criar um agente no Claude Code, passo a passo?
Dentro da pasta do projeto, crie a pasta .claude e, dentro dela, a pasta agents. Cada agente é um arquivo Markdown (.md) nessa pasta. Markdown é só texto com marcações simples: hashtag vira título, duas hashtags viram subtítulo. Qualquer editor serve, do bloco de notas à sua IDE.
O arquivo começa com um cabeçalho (frontmatter) entre linhas de três traços. No exemplo do vídeo, ele tem três campos: name (o nome do agente, aqui pendencias), description (o que ele faz, em uma frase, incluindo o nome da pasta que ele vai ler) e tools (Read, Glob e Write). Read lê arquivos, Glob encontra arquivos por padrão de nome e Write escreve.
Abaixo do cabeçalho vem o corpo, em texto normal. No exemplo, ele tem três blocos: a tarefa (ler todas as notas da pasta e escrever o arquivo pendencias.md), a definição de pronto (uma linha por pendência, em formato de lista com checkbox e a nota de origem) e os limites (se a nota diz que algo já foi resolvido, não entra).
Para rodar, abra a pasta no Claude Code desktop, digite @ e o nome do agente, complete com tab e peça que ele faça a tarefa. No vídeo, ele leu as notas, devolveu 10 pendências, listou as que ficaram de fora por já estarem resolvidas e gerou o arquivo na pasta do projeto.
- Pasta: .claude/agents na raiz do projeto.
- Arquivo: nome-do-agente.md, com frontmatter e corpo em Markdown.
- Frontmatter: name, description e tools.
- Corpo: tarefa, definição de pronto e limites.
Quais ferramentas liberar para o agente?
Libere só o que a tarefa exige. Um agente que lê uma pasta e escreve um arquivo não precisa de internet, de consulta a API nem de execução de comandos. Cada permissão a mais é uma chance a mais de ele fazer algo que você não queria.
Uma forma prática de decidir: escreva a tarefa em uma frase e liste os verbos. Ler, achar arquivos, escrever. Cada verbo vira uma ferramenta. Se aparecer um verbo que você não sabe se é necessário, comece sem ele e adicione depois, se o teste mostrar que faltou.
Isso também ajuda na confiança. Se o agente só consegue ler uma pasta e escrever um arquivo, o pior erro possível é um arquivo mal escrito, algo fácil de perceber e desfazer.
Como saber se o agente está funcionando e como ajustar?
Rode, abra o resultado e compare com a sua definição de pronto. Se o formato saiu diferente do pedido, ou se entrou uma pendência que já estava resolvida, o problema quase sempre está na instrução. Troque de modelo só depois de esgotar a instrução.
A regra do vídeo é ser óbvio com a IA. Ela não tem o seu senso comum. Se você quer ordem de prioridade, uma mensagem no final ou outro layout, escreva isso no arquivo do agente. Na próxima execução ele segue a nova versão.
Um bom ciclo é: rodar, conferir, ajustar uma coisa, rodar de novo. Mudar várias coisas de uma vez dificulta saber o que resolveu e o que piorou.
- Resultado fora do formato: detalhe o formato, com um exemplo de linha.
- Itens que não deveriam aparecer: escreva a regra de exclusão como uma frase direta.
- Resultado incompleto: confira se a descrição da tarefa cobre todos os arquivos que ele deve ler.
Quais são os erros mais comuns de quem começa?
O primeiro é escolher uma tarefa grande demais. Quanto maior a descrição, mais chances de o agente errar, inventar algo ou fazer o que não devia. Prefira uma tarefa pequena, repetitiva e fácil de conferir, e só depois pense em combinar várias.
O segundo é dar permissão demais, na lógica de liberar tudo para não ter que pensar nisso. O agente pode acabar mexendo no que não devia, inclusive no seu computador. Comece com o mínimo.
Quando for encadear agentes, o vídeo recomenda começar com você mesmo sendo o elo: um agente termina, você confere e chama o próximo. Só depois de rodar bastante vale automatizar também o gatilho e a passagem entre eles.
Para aplicar
- Escolha uma tarefa pequena e repetitiva do seu dia que dê para conferir em um minuto.
- Escreva em uma frase o que conta como pronto, incluindo o formato do arquivo de saída.
- Crie a pasta .claude/agents e um arquivo .md com name, description e tools.
- Libere só as ferramentas dos verbos da tarefa, como Read, Glob e Write.
- Rode o agente no Claude Code com @ e o nome dele, e compare o resultado com a sua definição de pronto.
- Ajuste uma instrução por vez e rode de novo até o resultado sair como você espera.
- Só depois de vários usos estáveis, pense em encadear com outro agente ou em automatizar o gatilho.
Perguntas frequentes
Preciso saber programar para criar um agente no Claude Code?
Para o nível de especialização mostrado no vídeo, não. O agente é um arquivo de texto em Markdown com um cabeçalho e instruções em português. Saber programar ajuda quando você quiser construir um agente do zero, com ciclo próprio e integrações por API.
Posso usar o Claude Code pelo terminal em vez do desktop?
Sim. O agente é o mesmo arquivo em .claude/agents. No vídeo, o desktop foi escolhido porque é mais visual e menos técnico, mas a mesma pasta funciona pela linha de comando.
Quanto tempo leva para criar o primeiro agente?
O exemplo do vídeo, com um arquivo de poucas linhas e uma pasta de anotações, cabe em uma sessão curta. O tempo maior costuma ir para ajustar a definição de pronto e os limites depois do primeiro teste.
O que fazer quando o agente erra?
Releia a sua instrução antes de culpar o modelo. Verifique se a tarefa, o formato esperado e as regras de exclusão estão escritos de forma explícita, ajuste uma coisa e rode de novo.
Quando faz sentido ter mais de um agente?
Quando a tarefa ficou grande e dá para separar em etapas bem definidas, cada uma com seu agente. Comece sendo o elo entre eles, conferindo cada saída, e só automatize a passagem depois de ter confiança no resultado de cada etapa.
Para continuar
- Revisão humana em automação com IA: quando e como fazer: Mostra quando colocar uma pessoa para conferir o resultado, como no vídeo, em que você é o elo entre um agente e o próximo.
- O que não automatizar: 6 sinais de que o processo deve esperar: Ajuda a decidir quais tarefas ainda não devem ser entregues a um agente.
- O que automatizar primeiro: comece pelo gargalo da operação: Complementa a escolha da primeira tarefa: por onde começar quando há vários candidatos.
// Curso · WDS Builders
Video Builder IA
Você grava o seu vídeo e dirige um agente de IA que transcreve, corta, legenda, anima e renderiza. Nada avança sem a sua aprovação. Do bruto ao vídeo publicado.
// Canal no YouTube
Inscreva-se no canal
IA aplicada, automação e os bastidores do que estou construindo, mostrados na prática.
Inscrever-se no canal →







