Agentes no Claude Code: um time que produz seu boletim macro

Um agente, no Claude Code, é um arquivo Markdown que descreve um funcionário especializado: o nome dele, as ferramentas que pode usar, o modelo de IA que o executa e as instruções permanentes do cargo. Com cinco desses arquivos, um conjunto de permissões e um comando de disparo, você monta um time que produz um boletim macroeconômico semanal do Brasil, com IPCA, câmbio, Selic e IBC-Br, sem que você redigite instrução nenhuma a cada divulgação.

Este tutorial mostra a arquitetura completa desse time: cinco subagentes especializados coordenados por um agente principal, cada um com ferramentas restritas ao próprio papel, um mecanismo de auditoria que registra tudo o que o time faz e um comando que dispara a sequência inteira. O foco aqui é o método e as decisões de projeto, não os arquivos prontos para copiar.

Repare que cada card define três coisas: a entrega, a entrada e o limite. É essa divisão de trabalho que o restante do post explica: o conceito de agente, os papéis e seus limites, as permissões, o hook de auditoria e o comando que orquestra a sequência inteira.

O que é um agente no Claude Code

Um agente é a combinação de cinco elementos gravados num único arquivo Markdown dentro da pasta .claude/agents/ do projeto: name (o apelido usado para invocá-lo), description (quando ele deve ser acionado), tools (o que pode fazer), model (qual modelo o executa) e o prompt (as instruções permanentes do cargo). O cabeçalho do arquivo carrega os metadados; o corpo, o prompt.

O cabeçalho de um agente coletor, por exemplo, cabe em quatro linhas:

name: pesquisador-dados
description: Baixa séries do SGS/BCB e grava CSV padronizado
tools: Read, Write, Bash
model: haiku

Abaixo desse cabeçalho vem o prompt: o texto que define o objetivo, o formato de saída e a política de falha do agente. Como tudo é arquivo versionado no repositório, o time inteiro viaja com o projeto e funciona igual em qualquer máquina.

Subagente é um agente invocado por outro. Ele roda em contexto isolado: não enxerga a conversa principal, recebe apenas o objetivo passado pelo coordenador e devolve um resumo do que fez. O agente principal (o chefe) é a própria sessão que você abre no terminal; é ele quem decide qual especialista chamar e consolida os resultados.

O ganho de dividir o trabalho em papéis

Três mecanismos justificam o time no lugar de um Claude generalista. O primeiro é o contexto isolado: um subagente que lê 40 mil tokens de CSV devolve ao chefe um resumo de 500 tokens, e o coordenador nunca polui a própria memória de trabalho com dados que não precisa ver.

O segundo é a configuração por papel: o coletor roda num modelo barato (Haiku) com acesso restrito ao terminal, enquanto o redator roda num modelo mais capaz (Sonnet) sem acesso nenhum ao terminal. Num único Claude, todos os pedidos dividem o mesmo modelo e as mesmas permissões.

O terceiro é a automação: como o time inteiro está descrito em arquivos, a mesma sequência que você dispara interativamente roda dentro de um agendador, sem você no loop. A comparação lado a lado resume a diferença:

Assistente único versus time de agentes especializados no Claude Code.

Nem toda tarefa merece um especialista. O subagente compensa quando a tarefa se repete, tem entrada e saída claras, usa um subconjunto de ferramentas e consome contexto que não precisa voltar ao chefe; se o pedido é único, linear e pequeno, o próprio coordenador resolve. Na prática, equipes de 3 a 6 agentes cobrindo etapas bem definidas são o padrão que se sustenta.

Os cinco papéis e a regra do "não faz"

Cada papel do boletim responde a três perguntas: o que entrega, de onde vem a entrada e o que ele não faz. O limite é tão estrutural quanto a função, porque sem ele todo agente vira generalista: o revisor começa a reescrever o texto, o redator começa a fazer contas, e o time perde o foco.

O pesquisador-dados baixa as séries do SGS, o sistema de séries temporais do Banco Central, usando o pacote R rbcb, e grava um CSV padronizado por série; ele não calcula nada. O analista transforma esses CSVs numa tabela-resumo com as variações no mês, no ano e em 12 meses de cada indicador; ele não escreve uma linha de texto. O redator transforma a tabela em narrativa, citando cada número por referência direta à tabela, sem digitar valor algum à mão.

O revisor compara o texto com a tabela e emite um parecer: "ok" ou a lista numerada de correções. As ferramentas dele permitem ler e registrar o parecer, mas não editar o boletim, já que quem corrige é o redator; se ele pudesse editar, viraria um segundo redator e a checagem independente desapareceria. Por fim, o publicador renderiza o HTML com o Quarto e registra a versão no repositório, com uma pré-condição gravada no prompt: só executa se o parecer do revisor começar exatamente com "ok".

Fluxo de trabalho do time do boletim macro semanal.

A escolha do modelo segue o custo da etapa: Haiku para as tarefas mecânicas de coleta e publicação, Sonnet para análise, redação e revisão. Um pipeline com coletores baratos e um redator mais capaz custa uma fração do mesmo pipeline rodando inteiro no modelo mais caro, e você decide onde cada real vai.

A estrutura que sustenta o time

Todo o time vive dentro do repositório do projeto: os cinco agentes em .claude/agents/, o comando de disparo em .claude/commands/, as permissões e o hook em settings.json, os scripts R de coleta e tratamento, e as pastas de saída e de logs.

O time compartilha conhecimento por três canais. O CLAUDE.md da raiz funciona como briefing permanente que todo agente lê ao iniciar: é lá que ficam as séries a coletar, as convenções de escrita e as regras do pipeline, como "nenhum agente inventa número" e "o publicador só roda com revisão aprovada". Os arquivos do repositório são o segundo canal, já que cada agente lê as saídas dos anteriores. O terceiro são os resumos que cada subagente devolve ao chefe ao terminar.

Essa comunicação por arquivo tem um efeito colateral valioso: o pipeline vira auditável. O chefe guarda a visão geral, os especialistas guardam o detalhe, e tudo o que passou de um para o outro está escrito em disco.

Permissões: o que roda sem perguntar

As permissões do projeto separam a capacidade declarada da capacidade autorizada. Um agente pode ter o terminal entre as ferramentas, mas o que ele consegue executar é controlado por três listas no settings.json: allow (executa sem perguntar), ask (para e pede confirmação) e deny (bloqueado sempre).

No boletim, rodar scripts R e renderizar o Quarto ficam em allow, porque são o dia a dia do pipeline. Publicar no repositório remoto fica em ask, porque tem efeito externo e merece um olhar humano caso a caso. Comandos destrutivos como apagar arquivos e elevar privilégio ficam em deny, valendo para o time inteiro. A regra prática é preferir escopos estreitos: autorizar apenas o comando específico que o agente precisa é mais seguro que liberar o terminal inteiro.

Hooks: a auditoria que não depende do modelo

Um hook é um script que o Claude Code executa em pontos fixos do ciclo de trabalho, fora do julgamento do modelo. O modelo pode esquecer de registrar uma ação; o hook registra sempre, porque é a própria ferramenta que o dispara em pontos determinados do ciclo.

Cada hook define um evento (antes ou depois de uma ferramenta rodar, ao fim do turno), um filtro que diz sobre qual ferramenta ele age e o comando a executar. No boletim, um hook dispara depois de cada invocação de subagente e anexa uma linha a um arquivo de log com o horário, o nome do agente chamado e a instrução recebida. Depois de algumas rodadas, esse arquivo é uma trilha de auditoria completa: quem trabalhou, quando e com qual ordem de serviço.

Um cuidado acompanha o recurso: o hook roda com as permissões do seu usuário, então nunca cole um hook copiado da internet sem ler o que ele faz.

O slash command que dispara a semana

Um slash command é um atalho de prompt: um arquivo Markdown em .claude/commands/ cujo conteúdo é expandido quando você digita /nome na sessão. Em vez de redigitar toda semana "invoque o pesquisador, depois o analista, depois o redator...", você escreve essa sequência uma vez e passa a disparar tudo com /gerar-boletim seguido da data de referência.

O corpo do comando é o roteiro do chefe: invocar o pesquisador e conferir os CSVs, invocar o analista e conferir a tabela-resumo, invocar o redator com a data da semana, invocar o revisor e ler o parecer. Se o parecer aprova, o publicador entra; se aponta correções, o texto volta ao redator, com limite de dois ciclos antes de parar e pedir intervenção humana. Nunca pular a revisão e nunca publicar sem aprovação são regras escritas no próprio comando.

Da sua máquina para o agendador

Como o time inteiro são arquivos num repositório, levá-lo para o GitHub Actions fecha a automação: um workflow agendado para toda segunda-feira de manhã prepara o ambiente (R, Quarto, Claude Code), dispara o mesmo /gerar-boletim em modo não interativo e registra o boletim gerado de volta no repositório. A chave da API fica guardada como segredo do repositório e nunca aparece em código ou log.

Um detalhe decide o sucesso do agendamento: em modo automático não há ninguém para responder confirmações, então qualquer permissão em ask trava a execução. Antes do primeiro disparo agendado, ou você promove a publicação remota para allow, confiando na barreira do revisor, ou remove a etapa de publicação e mantém o resultado como artefato para revisão humana. Os logs de cada rodada sobem como artefato do workflow, e é por eles que você depura quando algo falha de madrugada.

O que a primeira execução entrega

Uma rodada completa do time produz uma cadeia de artefatos verificáveis: os CSVs das cinco séries com data e valor, a tabela-resumo com as quatro linhas de indicadores, o boletim em Quarto com os números citados por referência, o parecer do revisor e o HTML final registrado no repositório com um commit datado. O log do hook mostra a linha de cada subagente invocado na sequência.

A primeira rodada leva o dobro do tempo, e é nela que você ajusta os prompts com base no que saiu errado: o redator que citou um número fora da tabela ganha uma regra nova no próprio arquivo, o analista que errou um acumulado ganha a fórmula explícita. Prompt de agente é documento vivo, e depois de duas ou três semanas o time estabiliza.

Estabilizado, o padrão coletor → analista → redator → revisor → publicador se transfere com trocas pequenas:

O mesmo padrão de time serve a outros produtos recorrentes com ajustes pontuais.

O time não substitui o profissional na interpretação: um agente escreve que o IPCA subiu, e é você quem decide se aquilo é ruído ou mudança de regime. O que ele tira da sua semana é a parte mecânica de coletar, calcular, formatar e publicar, devolvendo horas para a análise que só você faz.

Considerações finais

Montar um time de agentes no Claude Code é um investimento que se paga na recorrência: o primeiro time custa algumas horas de projeto e ajuste, o segundo custa metade, porque a arquitetura, as permissões e o briefing já estão resolvidos. O produto final é um processo que antes ocupava uma manhã inteira, entre planilha, script e copy-paste, reduzido a um comando com trilha de auditoria.

A arquitetura vale mais que o exemplo: papéis com limites explícitos, ferramentas restritas por função, comunicação por arquivo, revisão obrigatória antes de publicar. Esse desenho se aplica a qualquer rotina recorrente de informação, e cada perfil profissional tem a sua:

• Economistas: boletins de conjuntura, notas de política monetária e acompanhamento de indicadores que se atualizam sozinhos a cada divulgação, com os números sempre citados a partir da fonte.
• Administradores: relatórios gerenciais e painéis periódicos em que a coleta, o cálculo e a formatação saem do caminho, sobrando tempo para a decisão que o relatório sustenta.
• Contadores: rotinas de fechamento e conferência em que a checagem cruzada vira um agente revisor dedicado, com parecer registrado e bloqueio automático do que não bate.

Em todos os casos, o ganho vem do mesmo lugar: transformar um processo que morava na sua cabeça em arquivos que um time de agentes executa, audita e repete.

Leia também:

• Pipeline de relatório de IPCA com agentes no Claude Code
• Routines: um agente trabalhando sem você