Claude Code e Agentes

1.1 De um assistente para um time

Em Claude Code: como instalar e começar a usar  e Claude Code para Economistas você usou o Claude Code como um assistente: abre o terminal, conversa, pede uma coisa de cada vez, revisa o resultado, segue. Isso funciona bem para o dia a dia — escrever um script, ajustar um gráfico, ler um arquivo. Mas rotinas recorrentes que envolvem coleta, cálculo, redação e publicação em sequência começam a pesar: o prompt cresce, o contexto enche, você repete instruções toda semana.

A saída é parar de conversar com um Claude e começar a coordenar vários — cada um especializado em uma etapa.

1.2 O que você vai construir nesta aula

Um time de cinco agentes que produz um boletim macro semanal do Brasil sem que você precise redigitar nada a cada divulgação:

• pesquisador-dados baixa IPCA, câmbio, Selic e IBC-Br
• analista calcula variações no mês, no ano e em 12 meses
• redator escreve o .qmd do boletim com narrativa econômica
• revisor confere números e estilo antes da publicação
• publicador renderiza o HTML, faz o commit e publica

Um agente principal (chefe) coordena a sequência, decidindo quando cada especialista entra.

1.3 O que muda quando você tem um time

2.1 O que é um agente no Claude Code

Um agente é um funcionário especializado do time. Formalmente, é a combinação de quatro elementos:

Esses elementos ficam em um único arquivo Markdown dentro de .claude/agents/. O frontmatter YAML carrega os metadados, o corpo carrega o prompt.

Exemplo de frontmatter e instruções para o agente pesquisador-dados:

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

Você é um pesquisador de dados macro. Ao receber nomes de séries,
crie um script R que use rbcb::get_series(), valide se o retorno
não está vazio, e grave CSV em output/dados/<nome>.csv com
colunas data (Date) e valor (num).

Se alguma série falhar, grave em logs/erros.md e pare.

2.2 Como o agente decide o próximo passo

Todo agente do Claude Code segue o mesmo ciclo a cada turno:

1. Lê o objetivo e o contexto.
2. Planeja a próxima ação dentro das ferramentas permitidas.
3. Executa (lê arquivo, roda comando, busca web).
4. Observa o retorno e decide se terminou ou precisa iterar.

O economista define o escopo (ferramentas, permissões) e o objetivo (prompt). O agente se encarrega do “como”, passo a passo. O que muda entre “assistente interativo” e “agente rodando sozinho” é quem fecha o ciclo: no uso interativo, você revisa cada passo; no pipeline, a combinação de permissões allow e de hooks permite fechar o ciclo sem intervenção.

2.3 O chefe e os especialistas

Isso é poderoso para o economista: um subagente pode consumir 50 mil tokens lendo CSVs enormes e processando dados, e devolver ao chefe apenas 500 tokens com o resultado. O chefe nunca vê o meio do trabalho — só o que importa para coordenar o próximo passo.

O chefe invoca subagentes via ferramenta Task, que cria um processo filho do Claude Code com o prompt, as ferramentas e o modelo definidos no arquivo do agente.

2.4 Quando criar um especialista

Se a tarefa é única, linear e pequena, deixe o chefe fazer. Criar subagente custa um arquivo a mais e um prompt a mais para manter. O padrão útil são equipes pequenas e estáveis (3 a 6 agentes) cobrindo etapas bem definidas do processo.

2.5 Escolhendo o modelo certo para cada agente

Cada agente pode declarar o próprio modelo no frontmatter. Isso reduz custo sem perder qualidade.

Um pipeline com quatro coletores Haiku + um redator Sonnet custa uma fração do mesmo pipeline todo em Opus. Você decide onde cada real vai.

2.6 Ferramentas: o que cada agente pode fazer

No frontmatter tools:, você restringe o que o agente acessa. Princípio do menor privilégio: dê só o necessário.

Um pesquisador de dados não precisa de Edit no código R — só Read e Write de CSVs. Um redator não precisa de Bash. Um revisor só precisa ler. Restringir evita acidentes e deixa o papel de cada agente mais claro para o próprio time.

2.7 Memória compartilhada do time

O time compartilha contexto por três canais:

• CLAUDE.md do projeto — briefing permanente que todo agente lê ao iniciar
• Arquivos do repositório — cada agente pode ler output/, R/, dados/
• Resumos trocados entre agentes — o redator recebe o que o analista produziu, via retorno de Task

2.8 Permissões: o que o time pode executar

O arquivo .claude/settings.json controla o que qualquer agente do time pode fazer sem pedir autorização. Três listas:

• allow — executa sem perguntar
• ask — para e pergunta antes
• deny — bloqueia completamente

2.9 Hooks: comportamento determinístico fora do modelo

Hooks são scripts que rodam em eventos do Claude, configurados em settings.json. Eles executam fora do modelo — você controla comportamento determinístico sem depender do julgamento do agente.

No Projeto3 você vai usar um hook PostToolUse que grava cada invocação de subagente (Task) em logs/execucao.jsonl, permitindo auditar quem foi chamado, quando e com qual prompt.

2.10 Comandos, skills e MCP — o que também existe

Além de agentes e hooks, o Claude Code expõe mais três mecanismos de extensão:

• Slash commands customizados (.claude/commands/<nome>.md) — atalhos que o usuário dispara digitando /nome. Úteis para orquestrar o time (ex.: /gerar-boletim).
• Skills (.claude/skills/<nome>/SKILL.md) — playbooks que o próprio modelo decide quando usar, com base na descrição do frontmatter. Bons para padrões reaplicáveis de estilo.
• MCP (Model Context Protocol) — protocolo que conecta o Claude a fontes externas padronizadas (filesystem, SQL, GitHub, APIs financeiras). Instala-se com claude mcp add ... e expõe ferramentas extras para os agentes.

Nesta aula, focamos em agentes + comando-raiz + hook de log. Skills e MCP são extensões que você adiciona conforme a necessidade.

3.1 O problema que o time resolve

Um economista que acompanha a conjuntura brasileira precisa, toda semana, consolidar os principais indicadores: IPCA mais recente, câmbio, Selic, atividade. Hoje, isso é planilha + script velho + copy-paste + ajuste de gráfico + PDF. Alvo: um relatório HTML de uma página, gerado por um único comando, com a tabela comparativa e três parágrafos comentando.

3.2 Definição dos papéis

Para cada agente, três perguntas estruturam o papel:

1. O que ele entrega? — arquivo, tabela, resumo, número.
2. De onde vem a entrada? — pedido do usuário, saída de outro agente, arquivo do repo.
3. O que ele NÃO faz? — o limite é tão importante quanto a função.

Sem limite claro, todo agente vira generalista: o revisor começa a reescrever o texto, o redator começa a fazer contas, e o time perde foco.

3.3 Fluxo de trabalho do time

3.4 Estrutura do projeto

boletim-macro/
├── .claude/
│   ├── agents/                 # 5 arquivos .md
│   │   ├── pesquisador-dados.md
│   │   ├── analista.md
│   │   ├── redator.md
│   │   ├── revisor.md
│   │   └── publicador.md
│   ├── commands/
│   │   └── gerar-boletim.md    # comando-raiz do chefe
│   └── settings.json           # permissões e hook
├── R/
│   ├── coleta.R
│   └── tratamento.R
├── output/
│   ├── dados/                  # CSVs brutos
│   └── tabelas/                # resumo.csv
├── logs/                       # erros, revisao, execucao
├── boletim.qmd                 # fonte do relatório
├── CLAUDE.md                   # briefing permanente
└── .gitignore

4.1 Pré-requisitos

Antes de começar, confirme no terminal:

claude --version    # Claude Code instalado
quarto --version    # Quarto instalado
R --version         # R disponível
jq --version        # usado pelo hook de log

No R, instale os pacotes que os agentes vão usar:

install.packages(c("rbcb", "dplyr", "readr", "lubridate",
                   "tibble", "knitr"))

4.2 Passo 1 — Criar a estrutura do projeto

mkdir -p boletim-macro && cd boletim-macro
mkdir -p .claude/agents .claude/commands R \
         output/dados output/tabelas logs
touch CLAUDE.md .claude/settings.json boletim.qmd

4.3 Passo 2 — Escrever o CLAUDE.md

O CLAUDE.md é o briefing permanente: objetivo, fontes, convenções. Todo agente lê este arquivo ao iniciar. Se você escreve uma regra aqui, não precisa repetir em cada prompt.

Crie CLAUDE.md na raiz do projeto com o seguinte conteúdo:

# Boletim Macro Semanal

**Objetivo**: relatório HTML de uma página com IPCA, câmbio,
Selic e atividade, com tabela comparativa e três parágrafos
comentados, gerado por time de agentes.

**Fontes** (todas via rbcb::get_series):
- IPCA mensal: SGS 433, em % a.m.
- Câmbio R$/US$ venda: SGS 1, diário
- Selic meta: SGS 432, % a.a.
- IBC-Br: SGS 24363, índice

**Convenções**:
- snake_case em funções, colunas e arquivos
- Código e comentários em pt-BR
- Paleta Análise Macro nos gráficos

**Vícios a evitar no texto**: "cirúrgico", "que funcionam",
"do zero", "próximo nível", "virada de chave", "destrava",
"regra de ouro", "caso prático", analogias em títulos,
construção "não é X, é Y".

**Regras**:
- Se qualquer coleta falhar, o pipeline para e registra em
  logs/erros.md
- Nenhum agente inventa número — toda citação no texto vem
  de resumo.csv via inline code
- O publicador só roda se logs/revisao.md começar com "ok"

4.4 Passo 3 — Agente pesquisador-dados

Crie .claude/agents/pesquisador-dados.md com frontmatter YAML e corpo (instruções):

---
name: pesquisador-dados
description: Baixa séries macro (SGS/BCB) via rbcb e grava CSV
             padronizado em output/dados/. Acionar sempre que
             o boletim precisa ser atualizado com dados novos.
tools: Read, Write, Bash
model: haiku
---

No corpo, o agente deve:
1. Baixar 4 séries do SGS/BCB via rbcb::get_series
   (códigos listados no CLAUDE.md)
2. Gravar um CSV por série em output/dados/<nome>.csv com
   colunas data (Date) e valor (num)
3. Validar que o arquivo não está vazio e que o último valor
   não é NA
4. Se qualquer validação falhar, gravar em logs/erros.md e
   parar — nunca estimar, interpolar ou chutar

Limites: não calcula variações, não escreve texto, não edita
boletim.qmd.

Retorno: lista de CSVs gerados com data máxima de cada, e
alertas encontrados.

4.5 Passo 4 — Agente analista

Crie .claude/agents/analista.md:

---
name: analista
description: Calcula variações, acumulados e comparativos a
             partir dos CSVs coletados. Acionar depois do
             pesquisador-dados.
tools: Read, Write, Bash
model: sonnet
---

No corpo, o agente deve:
1. Ler os 4 CSVs em output/dados/
2. Produzir output/tabelas/resumo.csv com colunas:
   indicador, valor_atual, data_ref, var_mes, var_ano, var_12m
3. Regras de cálculo:
   - IPCA: var_12m via prod(1 + x/100) - 1 com janela móvel
     de 12 meses
   - Câmbio: variações percentuais entre níveis
   - Selic: variações em pontos-base (diferença * 100), não
     percentual
   - IBC-Br: variação percentual direta do índice
4. Validar que resumo.csv tem exatamente 4 linhas preenchidas

Limites: não inventa número, não escreve narrativa, não edita
boletim.qmd. Se faltar dado, NA + registro em logs/erros.md.

4.6 Passo 5 — Agente redator

Crie .claude/agents/redator.md:

---
name: redator
description: Escreve boletim.qmd com narrativa econômica a
             partir de resumo.csv. Acionar após o analista.
tools: Read, Write, Edit
model: sonnet
---

No corpo, o agente deve:
1. Ler output/tabelas/resumo.csv em um chunk de setup
2. Gerar ou atualizar boletim.qmd com estrutura fixa:
   - YAML (cosmo, self-contained, pt-BR)
   - Seção "Quadro da semana" com knitr::kable da tabela
   - Seção "Inflação" (3-5 linhas)
   - Seção "Câmbio e juros" (3-5 linhas)
   - Seção "Atividade" (3-5 linhas)
3. Todos os números citados no texto via inline code
   apontando para resumo.csv — nunca hardcode

Estilo: tom direto, sem previsão própria, sem os vícios de
linguagem listados no CLAUDE.md.

Limites: não executa render, não edita R/, não edita output/.

4.7 Passo 6 — Agente revisor

Crie .claude/agents/revisor.md:

---
name: revisor
description: Revisa boletim.qmd conferindo números, coerência
             e estilo. Acionar após o redator.
tools: Read, Write
model: sonnet
---

No corpo, o agente deve conferir em boletim.qmd:
1. Números — cada valor citado bate com resumo.csv?
2. Unidades — percentual vs. pontos-base, mensal vs. anual?
3. Coerência — texto fala em "alta" quando o valor é negativo?
4. Estilo — contém algum dos vícios proibidos no CLAUDE.md?
5. Tom — há previsão/opinião injustificada?

O parecer vai em logs/revisao.md começando com:
- "ok" se tudo está correto
- OU lista numerada de correções com trecho + motivo + sugestão

Regra: qualquer divergência numérica impede o "ok".

Limites: não edita boletim.qmd — só aponta. O redator corrige.

4.8 Passo 7 — Agente publicador

Crie .claude/agents/publicador.md:

---
name: publicador
description: Renderiza boletim.qmd e faz commit no repositório.
             Só rodar se logs/revisao.md começar com "ok".
tools: Bash, Read
model: haiku
---

No corpo, o agente deve:
1. Verificar que a primeira linha de logs/revisao.md é "ok"
   — caso contrário, parar e avisar o chefe
2. Executar: quarto render boletim.qmd
3. git add output/ boletim.qmd boletim.html logs/revisao.md
4. git commit -m "Boletim macro <data_ref>"
5. git status para confirmar árvore limpa

Sobre git push: está em modo "ask" no settings.json. O agente
faz o commit mas só executa push se autorizado pelo chefe.

Tratamento de falhas: render que falha → saída do quarto
gravada em logs/erros.md + parar.

Retorno: caminho do boletim.html, hash curto do commit, status
do push.

4.9 Passo 8 — Permissões e hook de log

Crie .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(Rscript:*)", "Bash(quarto:*)",
              "Bash(git add:*)", "Bash(git commit:*)",
              "Bash(git status:*)", "Bash(git log:*)",
              "Read(**)", "Write(**)", "Edit(**)",
              "WebFetch"],
    "ask":   ["Bash(git push:*)", "Bash(gh:*)"],
    "deny":  ["Bash(rm:*)", "Bash(sudo:*)", "Bash(curl:*)"]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Task",
      "hooks": [{
        "type": "command",
        "command": "jq -c '{ts: now, agent: .tool_input.subagent_type, prompt: .tool_input.prompt}' >> logs/execucao.jsonl"
      }]
    }]
  }
}

O bloco hooks grava uma linha JSON a cada invocação de subagente (Task) em logs/execucao.jsonl. Depois de alguns dias, esse log dá uma visão clara de quem trabalhou, quando e com qual instrução.

4.10 Passo 9 — Comando-raiz do chefe

Crie .claude/commands/gerar-boletim.md:

---
description: Roda o time completo para gerar o boletim macro
             da semana informada
---

Coordene o time para gerar o Boletim Macro Semanal com data
de referência $ARGUMENTS (use hoje se vazio).

Sequência:
1. Invoque pesquisador-dados. Confira a lista de CSVs.
2. Invoque analista. Confira resumo.csv com 4 linhas.
3. Invoque redator passando a data $ARGUMENTS.
4. Invoque revisor. Leia logs/revisao.md.
5. Se primeira linha é "ok" → invoque publicador.
   Caso contrário → volte ao passo 3 com as correções.
   Máximo 2 ciclos de ida e volta.
6. Mostre: caminho do boletim.html, hash do commit, conteúdo
   final de logs/revisao.md.

Regras:
- Pare imediatamente em qualquer falha e mostre logs/erros.md.
- Nunca pule a revisão. Nunca publique sem "ok".
- Após 2 rodadas sem "ok", pare e peça intervenção humana.

4.11 Passo 10 — Primeira execução guiada

cd boletim-macro
claude

# Dentro do Claude Code:
> /gerar-boletim 2026-04-22

Acompanhe cada subagente no terminal:

1. pesquisador-dados baixa as 4 séries — confira output/dados/.
2. analista processa — abra output/tabelas/resumo.csv e verifique que as 4 linhas estão preenchidas.
3. redator monta o boletim.qmd — inspecione o arquivo.
4. revisor grava logs/revisao.md — leia o parecer.
5. Se “ok”, publicador renderiza e faz commit. Abra boletim.html no navegador.

4.12 Passo 11 — Iterando o time

Depois da primeira rodada, você ajusta os prompts com base no que observou. Sintomas típicos e onde corrigir:

4.13 Passo 12 — Rodar sem você presente

Com o time estável, automatize a execução semanal via cron:

# crontab -e — toda segunda, 7h BRT
0 7 * * 1 cd ~/boletim-macro && \
  claude -p "/gerar-boletim" \
  --allowedTools Bash,Read,Write,Edit,Task \
  >> logs/cron.log 2>&1

Para ambientes corporativos, o mesmo comando roda dentro de um runner GitHub Actions usando o Claude Agent SDK, com a chave da API guardada como secret e a saída publicada num site estático ou Posit Connect Cloud.

5.1 Observabilidade

Um time que trabalha sem supervisão precisa deixar rastro. Você já configurou três canais de log no Projeto3:

• logs/execucao.jsonl — uma linha JSON por subagente invocado, preenchida pelo hook PostToolUse.
• logs/erros.md — append-only, escrito pelos agentes quando algo falha.
• logs/revisao.md — parecer da rodada corrente, sobrescrito a cada ciclo.

Além disso, monitore:

• Custo — dentro do Claude Code use /cost; em cron, extraia do log.
• Tempo por agente — timestamp de entrada e saída em cada linha de execucao.jsonl.
• Saídas versionadas — cada rodada gera um commit datado, histórico completo em git log.

5.2 Quando o time não basta

Agentes automatizam o fluxo, mas não substituem o economista em:

• Interpretação econômica — um subagente escreve “IPCA subiu para 4,5%”; você é quem decide se é ruído ou regime novo.
• Fontes pagas ou licenciadas — Bloomberg, bases proprietárias, APIs com SLA próprio.
• Julgamento editorial final — o que entra no boletim é decisão humana, mesmo que revisada por agente.
• Mudanças de escopo — se o boletim mudar de foco, você reescreve prompts; o time não se reinventa sozinho.

5.3 Reaproveitando o padrão para outros produtos

O padrão coletor → analista → redator → revisor → publicador serve com pequenas trocas: