Lição 6 de 7 · 15 min · Verificado em 10 de Outubro de 2026
Subagentes, modelos e custos
No fim desta lição vais conseguir:
- Criar um subagente só de leitura e explicar quando compensa usá-lo
- Escolher o modelo pela tarefa: o maior para pensar, o menor para o volume
- Ver quanto gastaste e evitar dois agentes a escrever no mesmo ficheiro
- Experimentar num ramo do Git e juntá-lo ao principal só quando estiver bom
O Tiago vende queijo de São Jorge numa loja online pequena. O preço do queijo curado subiu e ele pede ao agente: «Procura em todos os ficheiros do site onde aparece o preço antigo.»
O agente abre os 40 ficheiros, um a um. A resposta é boa, mas a conversa ficou cheia de páginas que o Tiago nunca mais vai ver. Como viste na lição 2/05, uma janela cheia faz o agente trabalhar pior no resto da tarde.
O conceito: um ajudante com a sua própria folha
Um subagente é um segundo agente que o principal lança para uma tarefa à parte. Tem a sua própria janela de contexto. Lê o que tiver de ler e devolve só o resumo: «o preço antigo aparece em 3 ficheiros, nestas linhas». A tua conversa recebe dez linhas, não 40 ficheiros.
Compensa quando a tarefa produz muito texto que não vais reutilizar: procurar, ler muitos ficheiros, rever, analisar registos de erros.
Não é de graça. Cada subagente faz o seu próprio trabalho com o modelo, e isso gasta. A documentação do Codex diz que estes fluxos consomem mais tokens do que um agente sozinho.
Como se faz hoje: um revisor só de leitura
Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome.
Claude Code. Cria o ficheiro .claude/agents/revisor.md antes de abrires o agente:
---
name: revisor
description: Revê código e textos e aponta problemas, sem alterar nada.
tools: Read, Glob, Grep
---
És um revisor. Lê os ficheiros indicados e devolve no máximo 10 linhas com os problemas encontrados, cada uma com o nome do ficheiro. Não alteres nada.
A linha tools só lhe dá ferramentas de leitura. O Claude escolhe sozinho quando usar um subagente, pela description. Para o chamar tu, escreve @ e escolhe-o da lista, ou pede: «Usa o subagente revisor para…»
Codex. Cria .codex/agents/revisor.toml:
name = "revisor"
description = "Revê código e textos e aponta problemas, sem alterar nada."
sandbox_mode = "read-only"
developer_instructions = """
És um revisor. Lê os ficheiros indicados e devolve no máximo 10 linhas com os problemas encontrados, cada uma com o nome do ficheiro. Não alteres nada.
"""
O sandbox_mode = "read-only" impede-o de escrever. O Codex só lança subagentes quando lhe pedes, e /agent mostra os que estão a correr. Como nos hooks (lição 2/03), só lê a pasta .codex/ de projectos em que confias.
Modelos: o maior para pensar, o menor para o volume
As duas ferramentas deixam-te escolher o modelo e, em muitos casos, o esforço de raciocínio. A regra é simples:
- Para pensar (planear, decidir, encontrar um erro difícil): o modelo maior, com mais esforço.
- Para o volume (procurar, renomear, resumir, tarefas repetidas e claras): um modelo mais pequeno, com menos esforço. É mais rápido e gasta menos.
O guia do Codex resume assim: fica com a opção mais leve que ainda te dá a qualidade de que precisas. O do Claude Code sugere um modelo pequeno para subagentes com tarefas simples.
Em ambos, /model muda o modelo da sessão. No Claude Code, /effort muda o esforço. No Codex, o próprio /model pergunta o esforço, quando o modelo o permite. Num subagente, acrescenta a linha model ao ficheiro; sem ela, usa em regra o modelo da sessão. Os nomes dos modelos mudam várias vezes por ano: consulta a página Estado actual.
Dica
Começa com menos esforço. Se a resposta não chegar, sobe. Muitas tarefas do dia-a-dia correm bem sem o máximo.
Ver quanto gastaste
- Claude Code:
/usagemostra o uso da sessão e, nas subscrições, as barras do plano. O valor em dinheiro é uma estimativa; o que conta é a página de uso da consola. - Codex:
/usagemostra o uso da conta por dia ou por semana;/statusmostra o da sessão.
Se pagas por uso, liga o tecto de gasto (lição 1/06). Preços e limites: consulta a página Estado actual.
Cuidado
Vários subagentes a ler ao mesmo tempo é seguro. Vários a escrever no mesmo ficheiro não é: um apaga o trabalho do outro, ou ficam em conflito. A documentação do Codex pede o mesmo cuidado. Usa agentes em paralelo para ler, procurar e rever; para escrever, um de cada vez.
Ramos do Git: experimentar sem estragar
Na lição 1/05 ficaste a saber que cada commit é uma fotografia. Um ramo é uma linha paralela de fotografias. O ramo principal fica como estava; experimentas noutro.
git branch # mostra os ramos; o * marca onde estás
git switch -c desconto # cria o ramo desconto e muda para ele
# ... o agente trabalha, corres os testes, fazes commits ...
git switch main # volta ao principal
git merge desconto # junta o ramo ao principal
git branch -d desconto # apaga o ramo, já juntado
Se a experiência correr mal, volta ao principal e apaga o ramo sem o juntar: git branch -D desconto. O D maiúsculo força a apagar, e isto não é um «desfazer»: os commits desse ramo deixam de estar à mão. Antes, confirma com git status que não há alterações por guardar e, se algo valer a pena, faz commit ou copia-o para fora.
Se o teu ramo principal se chamar master, escreve master onde está main. O git branch diz-te o nome.
Dica
Pede ao agente que trabalhe num ramo: «Cria o ramo desconto e trabalha só nele. Não faças merge.» O merge fazes tu, depois de leres o diff e correres os testes.
Exercício
Como sei que ficou bem o revisor devolve uma lista curta e a tua conversa mostra só esse resumo. Depois do git switch main, o ficheiro do revisor desaparece da pasta; depois do git merge revisao, volta.
Se não deu
- O Claude Code não encontra o revisor: a pasta
.claude/agents/foi criada com a sessão aberta. Fecha e abre o agente. - O Codex não encontra o revisor: o projecto não está marcado como de confiança, ou o ficheiro tem um erro de TOML. Fecha, corrige e abre de novo.
- «pathspec 'main' did not match»: o teu ramo principal chama-se
master. Vê comgit branch. - O
git switchrecusa mudar de ramo: há alterações por guardar. Faz commit primeiro.
Fontes:
Vídeos
Tutorial em português sobre como usar subagentes no Claude Code.
No troço indicado: subagentes personalizados no Claude Code. O resto do vídeo trata de outras funcionalidades avançadas.
Testa o que aprendeste
Correcções a esta lição (1)
- : Segunda revisão externa: `git branch -D` não é um «desfazer»; antes de apagar o ramo, confirma-se com `git status` e guarda-se o que valer a pena.