Criei um orquestrador de agentes depois de torrar meu budget semanal do Claude Code

Por que eu parei de confiar em prompt bem escrito

Tempo estimado de leitura: 4 min

A gota d'água foi uma auditoria na empresa. A torre de tecnologia precisava de moral, e moral na prática significava código testado, vários projetos, prazo apertado, confiança alta. Eu fiz o que todo mundo faz: joguei tarefa gigante no Claude Code e confiei no prompt bem escrito.

Não deu certo. Aprendi umas coisas no processo.

1 - Não importa o quanto você refine o prompt, o agente tende a alucinar à medida que a quantidade de trabalho aumenta. 2 - Orquestração automática não te dá controle humano: tudo acaba delimitado pela IA, não por você. 3 - Claude Code, embora satisfatório, é caro, e o agente sempre vai encerrar antes de concluir uma tarefa gigantesca, mesmo que seja só pra pedir pra continuar. 4 - Escrever testes em legado é tão simples quanto demorado. 5 - Gerenciar múltiplos prompts em paralelo dá uma exaustão mental que te desvia da tarefa. 6 - Até mesmo a mais simples das LLMs retorna resultados incríveis em tarefa pequena de escopo fechado.

O número pessoal: antes eu torrava o budget semanal da assinatura. Hoje gasto uns cinco reais pra gerar testes de um projeto de 200+ arquivos.

O problema nunca foi o modelo. Foi a falta de método. Daí nasceu o huu.

O que o huu é

O huu (Humans Underwrite Undertakings, "humanos subscrevem empreitadas") é um orquestrador de agentes onde o método é seu e a inteligência é do modelo. Você escreve um pipeline em JSON listando os passos e os arquivos; ele vira N agentes paralelos, um por arquivo, cada um num git worktree isolado, mesclados a cada etapa com git merge --no-ff em ordem fixa, tudo dentro de Docker pra o agente nunca ver suas credenciais.

O foco é auditoria, geração de testes e extração de conhecimento. Feature nova, "conserta esse bug", não é com ele. No GIF do repo dá pra ver uma run real: 55 minutos gerando uma suíte de testes (100% de cobertura de linha naquela execução, sem garantia de que a sua repita o número).

Instalação

Você precisa de Node.js 20+, git e Docker. Docker é obrigatório, não opcional: o huu só roda dentro de container, então suas credenciais de shell ficam de fora. E uma OPENROUTER_API_KEY, que é por onde os modelos entram. Testei tudo aqui com a versão 5.2.0 do npm.

export OPENROUTER_API_KEY=sk-or-...  # chave do openrouter.ai/keys
npm install -g huu-pipe              # instala o CLI global
huu                                  # abre a web UI e re-executa no container

O huu sobe a interface em http://localhost:4888 e já materializa os pipelines default em ./pipelines/. Se preferir terminal, huu --cli.

Na prática: tarefa gigante vira N tarefas pequenas

O jeito comum de fazer isso é abrir o Claude Code e mandar: "escreva testes pro projeto inteiro". Eu fiz isso. Muitas vezes. O agente começa bem nos primeiros arquivos, aí o contexto degrada, ele alucina à medida que o trabalho aumenta e sempre encerra antes de concluir, mesmo que seja só pra pedir pra continuar.

O jeito huu é outro. A pipeline huu Test Suite primeiro faz um recon que descobre sozinho os arquivos test-worthy, sem você apontar nada. Daí um step com scope per-file faz o fan-out:

// pipelines/meu.pipeline.json
{
  "name": "Write tests for $file",
  "prompt": "Escreva testes unitários para $file seguindo o huu-tests.md.",
  "files": [],
  "scope": "per-file"
}

Mesmo prompt pra todo mundo, só $file muda. Trinta agentes em paralelo, cada um com uma missão única de escopo fechado. No fim, um juiz roda a suíte e devolve pra retrabalho se não passar.

Funciona por um motivo simples: cada agente recebe uma tarefa pequena de escopo fechado, que é exatamente onde até a mais simples das LLMs entrega resultado incrível.

Quando usar (e quando não usar)

A regra prática é uma frase só: se cada passo exige uma decisão aberta de design, não é trabalho pro huu; se o método é conhecido e só falta executá-lo com rigor, é exatamente o trabalho dele.

Serve pra auditoria, geração de testes, extração de conhecimento, migração mecânica em massa. Tipo migrar 40 testes de Mocha pra Vitest: o prompt é idêntico nos 40 arquivos, só muda o $file. Não serve pra "conserta esse bug" ou "constrói essa feature". Trabalho aberto pede agente interativo, e escrever pipeline pra isso é overhead puro.

O impacto concreto: hoje eu gasto uns cinco reais pra testar um projeto de 200 arquivos. Antes, torrava o budget semanal inteiro do Claude Code.

Cuidados

Antes de sair rodando em produção crítica, algumas ressalvas honestas.

O huu é um projeto jovem, essencialmente de autor único, com desenvolvimento fortemente assistido por IA. Tem mais de 1.100 testes em Vitest, mas não tem CI automatizado: rodar typecheck e testes antes do commit é convenção do contribuidor, não gate. Avalie como você avaliaria qualquer ferramenta nova de uma pessoa só.

Determinístico é o método, não o resultado. Duas runs do mesmo pipeline dão diffs diferentes, e conflito de merge cai num resolvedor LLM, por construção. E cobertura de linha só prova que o código rodou, não que as asserções pegariam um bug: trate 100% como ponto de partida, não como prova.

Por fim, Docker é obrigatório (as antigas flags --no-docker e --yolo foram removidas), e o custo dos passos de merge e judge ainda não entra no total reportado.

O convite

O próximo passo é simples: instala e roda o huu Test Suite num projeto seu, ou abre http://localhost:4888/simulation pra ver tudo funcionando sem chave e sem custo. Zero risco.

Mas, honestamente, o que eu queria mesmo deixar é a reflexão: repensa como a gente usa IA no dia a dia, porque isso tá ficando caro. Use a ferramenta que quiser. A tese é o método ser seu, a inteligência ser do modelo.

Se ajudar, uma estrela no github.com/frederico-kluser/huu é bem-vinda, e pipelines novos e issues também. E manda esse post pro seu time no Slack ou WhatsApp, principalmente pra quem controla o budget.