Relatório: Shelf, com o Hunch e sem o Hunch

Data: 2026-10-10. Commit do Hunch usado para gerar o pacote: fc97369.

O teste

O app: Shelf, empréstimo de livros num escritório. É um monolito Node.js com API JSON e SQLite, usando só os módulos do Node 24 (node:http, node:sqlite e node:test), sem pacotes do npm.

Dois agentes do mesmo modelo, em paralelo, sem saber um do outro. A avaliação foi feita depois, por mim.

Resultado

A sonda (eval/probe.mjs) sobe cada app como processo, com banco novo, e roda os mesmos cenários: adicionar livro, validação, permissões, emprestar com vencimento em 14 dias, livro já emprestado, limite de 3, devolver por outra pessoa, devolver duas vezes, "meus empréstimos", atrasados e chamada sem identidade.

As decisões, olhando uma por uma

Sem Hunch (11): 5 eram decisões de produto que o board do Hunch já tinha tomado:

• como a API sabe quem chama;
• quem pode devolver;
• se a lista de livros é aberta a todos;
• como os testes controlam o relógio;
• o que "meus empréstimos" mostra.

As outras 6 eram de implementação: caminho do banco, pasta dos testes, transação.

Com Hunch (19):

• 3 vieram de contradições dentro do pacote do Hunch, e são defeitos do Hunch:
• os testes de aceite usavam token Bearer, enquanto a decisão do board diz X-Member-Id;
• duas tarefas diziam "nenhum endpoint ligado" a histórias que tinham endpoint;
• as tarefas citavam server/src/routes/*.ts num projeto JavaScript em src/.
• 1 veio de uma inconsistência do meu board: o endpoint de livros dizia member, e a matriz de permissões deixava o bibliotecário ler.
• As outras eram de implementação: texto dos erros 401 e 403, formato dos itens das listas, leitura de ids, ordem das checagens, logs, Dockerfile, limite do corpo da requisição.

Nenhuma delas foi uma regra de produto inventada.

Então o Hunch foi melhor?

No resultado, sim, com ressalvas. Os dois apps funcionam e cumprem todas as regras de negócio. O com Hunch:

• segue o contrato da API ao pé da letra (códigos, rotas e formato de erro);
• tem quase o dobro de testes, um por história e mais os de permissões e dados;
• separa as regras do banco como a arquitetura pedia, e o check confirma;
• deixou o desenho atualizado;
• não precisou inventar nenhuma regra de produto.

O simples é menor, mais direto e igualmente correto no comportamento.

No custo, não: o agente com Hunch gastou 1,9 vez mais tokens e 13% mais tempo, porque leu 41 arquivos e escreveu mais código e testes.

O que isso quer dizer:

• Para um app de 250 linhas, um parágrafo bem escrito basta. O Hunch não muda o comportamento; muda a disciplina: contrato, testes, arquitetura e o desenho sincronizado.
• O valor do Hunch aparece quando o comportamento precisa bater com algo combinado antes: uma API que outro time consome, uma arquitetura que o time decidiu, regras que não podem ser "escolhidas pela IA". Ali, os 5 itens de produto que o agente simples decidiu sozinho viram risco.
• O pacote do Hunch ainda tem atrito. As 3 contradições custaram tempo e tokens ao agente. Corrigidas depois desta rodada (ver abaixo), a próxima rodada deve gastar menos.

Defeitos do Hunch encontrados e corrigidos

Ao montar o teste (antes de rodar os agentes):

• Os boards de dentro das caixas não iam para o pacote nem para o prompt. Agora vão, com "Where code goes in…".
• O pacote ignorava a stack: Vitest, Playwright e Prisma apareciam numa stack node:test sem telas. Agora o runner, a linguagem dos arquivos, o teste de navegador e o Prisma seguem a stack.
• Detalhes menores:
• o nome de ADR terminando em hífen;
• a instrução de rodar npx depcruise agora diz o que fazer quando instalar não é permitido;
• um monolito vira src/ nas convenções.

Pelo agente com Hunch (depois da rodada):

• Os testes de aceite inventavam token Bearer. Agora usam um auxiliar signedInAs(role) que segue a decisão do board.
• Histórias sem endpoint de mesmo nome ficavam "sem endpoint". Agora o id da história no caminho (/loans/mine) também liga.
• Os caminhos fixos server/src/routes/*.ts agora seguem a linguagem da stack, com a nota de que o "Where code goes" manda.

Limites deste teste

• Uma rodada de cada lado, com um modelo, e modelos variam de uma rodada para outra.
• O board foi escrito por mim, que conheço bem o Hunch. Um board pior daria outro resultado.
• Quem avaliou também construiu o Hunch. Para compensar, separei na sonda o que é comportamento (vale para os dois) do que é contrato (só o board definia).
• Os tokens são só os do agente que construiu. Desenhar o board no Hunch não gasta tokens: é trabalho da pessoa, que não foi medido.

Arquivos

• design/: o board (board.hunch e boards/app.hunch)
• with-hunch/: o pacote do Hunch e o app que o agente construiu
• simple/: o prompt e o app que o agente construiu
• eval/probe.mjs e eval/result-*.json: a sonda e os resultados