Relatório: Clinic, com o Hunch, com um prompt simples e com o grill-me

Data: 2026-10-10. Commit do Hunch usado para gerar o pacote: 112144b (já com as correções que o benchmark Shelf revelou).

O teste

O app: Clinic, agenda de uma clínica pequena. Médicos abrem horários de 15 a 120 minutos, sem sobreposição; pacientes marcam (no máximo 2 consultas futuras) e cancelam até 24 horas antes; o médico cancela até o início. É um monolito Node.js com API JSON e SQLite, só com os módulos do Node 24. Dentro da caixa do app, o board desenha a arquitetura hexagonal.

A pessoa simulada sabe exatamente o que o board sabe. Assim, a comparação entre Hunch e grill-me mede como o conhecimento chega à IA (um pacote pronto ou uma entrevista), não quem sabe mais.

Resultado

Os números vêm de node benchmark/tools/measure.mjs benchmark/clinic e da sonda eval/probe.mjs. O que cada medida quer dizer está em ../README.md.

O que os números dizem

Comportamento: os três acertam as regras. O único cenário que falhou no Hunch ("um paciente não vê a agenda do médico") foi causado por um padrão que eu escrevi no Hunch nesta rodada: "quem pode chamar" alargava o acesso pela tabela de permissões. O agente seguiu o padrão à risca. O defeito era do Hunch e já foi corrigido (ver abaixo).

Contrato: Hunch e grill-me empatam em 10 de 10; o simples acerta 4. Sem o board, o agente simples escolheu códigos razoáveis, mas diferentes: 400 em vez de 422 para horário inválido, 404 em vez de 403 para quem não pode cancelar. Quem consome a API percebe essa diferença.

Custo: o Hunch custa 1,9 vez o simples; o grill-me, 5,9 vezes, mais a pessoa. A entrevista sozinha gastou mais tokens que a construção inteira com o Hunch. Pela pessoa, foram 39 perguntas em 3 rodadas, e cada rodada exigiu ler, pensar e responder. No Hunch, esse trabalho é desenhar o board, que não foi medido em tokens (nem aqui nem no Shelf).

Escopo: só o Hunch construiu exatamente o que foi pedido. O grill-me recomenda uma resposta para cada pergunta, e a pessoa aceitou o que o board não dizia. Assim entraram quatro coisas que ninguém pediu: apagar horário, filtros na lista, sobreposição de consultas do paciente e horários em múltiplos de 5 minutos. É o mesmo "inventar" que o Hunch tenta evitar, só que com um "sim" da pessoa no meio.

Qualidade: os três estão bem. Ninguém tem erro de sintaxe, nem arquivo misturando HTTP e SQL, nem 5xx com entrada ruim. A cobertura passa de 94% em linhas nos três. As diferenças são de forma:

• O simples concentra tudo em 4 arquivos (o maior com 214 linhas) e tem a maior complexidade média.
• Hunch e grill-me seguem a forma hexagonal sem nenhum import fora do lugar. No grill-me, a forma veio da pessoa, que a leu no board.
• O grill-me escreveu mais código (826 linhas, por causa do escopo extra) e tem as únicas funções acima de 40 linhas.

Decisões: o Hunch não reduziu o número. Foram 26 contra 22 e 20. Olhando uma por uma:

• Muitas repetem os padrões do pacote ("seguindo o padrão…", "a mensagem do 500 é…"). Não são escolhas novas: são registros do que o agente aplicou.
• Nenhuma é uma regra de produto inventada.
• No simples, cerca de metade são de produto: como os usuários passam a existir, se a lista de horários é pública, o que a agenda e "minhas consultas" mostram, se dá para apagar horário e se quem não pode ver uma consulta recebe 404. No Hunch e no grill-me, quem respondeu isso foi o board ou a pessoa.

Então, qual foi melhor?

• Para chegar ao contrato combinado, Hunch e grill-me empatam no resultado. O Hunch chega lá com um terço dos tokens, metade do tempo, nenhuma pergunta à pessoa e sem escopo extra. Em troca, alguém precisa desenhar o board antes.
• Para um app que só precisa funcionar, o prompt simples ainda é o mais barato. Acertou todo o comportamento com metade dos tokens do Hunch. O que ele não garante é o que foi combinado com quem vai usar a API, nem a forma do código.
• O grill-me é bom para descobrir o que a pessoa quer, e a entrevista dele encontrou as mesmas lacunas que o board fecha. Mas é caro, cansa a pessoa (39 respostas) e tende a acrescentar escopo quando a pessoa aceita as recomendações. Ele e o Hunch se completam: a entrevista para escrever o board pela primeira vez, e o board para todas as vezes seguintes, sem repetir a entrevista.

Defeitos do Hunch encontrados e corrigidos

Antes da rodada, olhando o Shelf (commit 112144b):

• O pacote fazia o agente abrir dezenas de arquivos. Agora o AGENTS.md traz a spec inteira (histórias, dados, API, regras, permissões, decisões e forma do código) e uma seção de padrões para o que todo projeto repete. Documentos vazios saem do pacote.
• `seed` só guardava uma linha por entidade. No Shelf, a sócia "Ada" sumiu do pacote. Agora todas as linhas ficam.
• Os exemplos de JSON eram texto. Saía "bookId": "1" para um inteiro, e isso levou o agente do Shelf a aceitar ids como texto. Agora saem números, booleanos, listas e valores de enum.
• Uma ação no caminho (POST /appointments/{id}/cancel) era tratada como um endpoint sem corpo, e virava 3 "perguntas".
• Um endpoint não podia aceitar dois papéis. Agora [auth=patient,doctor] funciona.

Pela rodada (commit f267f03):

• O padrão "quem pode chamar" alargava o acesso. Era a causa da única falha do Hunch. Agora só os papéis do endpoint entram, e a tabela de permissões diz quais linhas cada um vê.
• A história "Doctor cancels an appointment" não se ligava a `/appointments/{id}/cancel`. Agora uma palavra do id ou do título da história também liga. No board de exemplo do checkout, a história "see paid orders" passou a se ligar a GET /orders.
• Uma história sem endpoint nem tela não aparecia como pergunta. Agora aparece em OPEN_QUESTIONS.md e em "o que a IA teria de adivinhar".

Do meu board (não do Hunch): o board não dava mensagem para o médico que cancela depois do início, e o agente reaproveitou a mensagem das 24 horas.

Limites deste teste

• Foi uma rodada de cada lado, com um modelo, e os resultados variam de rodada para rodada.
• A pessoa simulada é um agente que leu o board. Uma pessoa de verdade erraria, mudaria de ideia ou diria "tanto faz". Por regra, ela aceitava a recomendação quando o board não dizia nada, e isso favorece o escopo extra do grill-me.
• Os tokens do grill-me são a soma do que cada rodada informou. A entrevista foi feita em várias mensagens ao mesmo agente.
• Desenhar o board não está medido, nem em tokens nem em tempo da pessoa.
• Quem desenhou o board, escreveu a sonda e avaliou também construiu o Hunch. Para compensar, a sonda separa comportamento (vale para todos) de contrato (só o board definia), e a robustez não vem do board.
• As medidas de qualidade são aproximadas, contadas por expressões regulares e sem pacotes, mas são iguais para os três.

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
• grill-me/: o prompt, a skill, a entrevista (GRILL.md), o plano (PLAN.md) e o app
• eval/probe.mjs e eval/result-*.json: a sonda e os resultados
• runs.json e metrics.json: os números