Phase 14 - Lesson 41

A Bancada de Trabalho em um Repositório Real

Onze lições de superfícies não valem nada se elas não sobreviverem ao contato com uma base de código real. Esta lição executa a mesma tarefa duas vezes em um pequeno aplicativo de exemplo: apenas com prompt versus guiado pela bancada de trabalho. Os números falam por si.

Tipo: Build Linguagens: Python (stdlib) Pré-requisitos: Fases 14 · 32 a 14 · 40 Tempo: ~60 minutos

Objetivos de Aprendizado

Reunir as sete superfícies da bancada de trabalho em uma pequena aplicação.
Executar a mesma tarefa duas vezes (apenas com prompt e guiada pela bancada de trabalho) e medir cinco resultados.
Ler o relatório antes/depois e decidir quais superfícies forneceram maior alavancagem.
Defender a bancada de trabalho contra a objeção de "mas meu modelo já é bom o suficiente".

O Problema

Uma demonstração em uma tarefa de brinquedo não convence ninguém. O caso a favor da bancada de trabalho se consolida quando uma tarefa que parece real em um repositório que parece real chega à produção com menos falhas, menos reversões e com um pacote que a próxima sessão pode usar.

Esta lição fornece esse repositório que parece real e executa a mesma tarefa através dos dois pipelines. O resultado é um relatório antes/depois que você pode entregar a um cético.

O Conceito

flowchart TD
  Task[Tarefa: validar /signup e adicionar testes] --> A[Execução apenas com prompt]
  Task --> B[Execução guiada pela bancada de trabalho]
  A --> M[Medir: 5 resultados]
  B --> M
  M --> Report[before-after-report.md]

O aplicativo de exemplo

Um manipulador minimalista no estilo FastAPI em sample_app/:

app.py com /signup (sem validação ainda).
test_app.py com um teste de caminho feliz (happy-path).
README.md e scripts/release.sh como isca para zona proibida.

A tarefa

Adicione validação de entrada a /signup: rejeite senhas menores que 8 caracteres, retorne 422 com um envelope de erro tipado. Adicione um teste que comprove o novo comportamento.

Os dois pipelines

Apenas com prompt:

Ler o README.
Ler app.py.
Editar arquivos.
Declarar como concluído.

Guiado pela bancada de trabalho:

Executar script de inicialização (Lição 35).
Ler contrato de escopo (Lição 36).
Ler estado (Lição 34).
Editar apenas arquivos permitidos.
Executar comando de aceitação via executor de feedback (Lição 37).
Executar barreira de verificação (Lição 38).
Executar revisor (Lição 39).
Gerar handoff (Lição 40).

Os cinco resultados medidos

Resultado	Por que isso importa
`tests_actually_run`	A maioria das alegações de "testes aprovados" não são verificáveis
`acceptance_met`	O teste que comprova o objetivo deve ser o teste que foi executado
`files_outside_scope`	O desvio de escopo (scope creep) é a falha silenciosa dominante
`handoff_quality`	A próxima sessão paga por isso ou se beneficia disso
`reviewer_total`	Julgamento qualitativo além da barreira

Build It

code/main.py orquestra os dois pipelines contra o mesmo fixture do aplicativo de exemplo. Ambos os pipelines são roteirizados (sem LLM no loop) para que a medição seja reproduzível. O script grava a comparação em before-after-report.md e comparison.json.

Execute-o:

python3 code/main.py

Saída: uma tabela de console com os resultados por pipeline, o relatório em markdown salvo ao lado do script e o JSON para quem quiser gerar gráficos dele.

Padrões de produção no mundo real

A pergunta do cético é "quanto a bancada de trabalho realmente ajuda?" Os números de 2026 dizem muito mais do que a explicação.

Terminal Bench do Top-30 para o Top-5 no mesmo modelo. Anatomy of an Agent Harness da LangChain (abril de 2026): um agente de codificação saltou de fora do top 30 para o quinto lugar no Terminal Bench 2.0 mudando apenas o harness. Mesmo modelo. Diferentes superfícies. Delta de vinte e cinco posições.

Vercel de 80% para 100% deletando ferramentas. A Vercel relatou que deletar 80% das ferramentas do seu agente mudou a taxa de sucesso de 80% para 100%. Menor superfície de ferramentas, escopo mais definido, menos maneiras de falhar. O espaço negativo vence.

Harvey com o dobro de precisão apenas via harness. Agentes jurídicos mais do que dobraram sua precisão por meio da otimização do harness, sem alteração no modelo.

88% dos projetos de agentes de IA empresariais falham em chegar à produção. O artigo Harness Engineering for Language Agents da preprints.org (março de 2026) rastreia as falhas até o runtime, não o raciocínio: estado desatualizado, tentativas frágeis, contexto sobrecarregado, recuperação ruim de erros intermediários.

Colapso de contexto longo. A taxa de sucesso de referência de 40-50% do WebAgent cai para menos de 10% em condições de contexto longo, principalmente devido a loops infinitos e perda de objetivo. O Ralph Loop e o pacote de handoff existem para absorver isso.

Falsos negativos ainda existem. Tarefas factuais de etapa única, lints de uma linha, execuções de formatador, qualquer coisa que o modelo tenha memorizado literalmente — essas rodam mais rápido apenas com prompt. O benchmark deve enumerá-las honestamente para que a bancada de trabalho não seja rotulada como exagero.

A conclusão não é que "o harness vence para sempre". Os modelos absorvem os truques de harness com o tempo. A conclusão é que hoje a carga de engenharia reside nas sete superfícies, e os números provam isso.

Use It

Esta lição é o caso de estudo que você cita quando:

Alguém pergunta por que cada PR carrega um agent-rules.md e um contrato de escopo.
Uma equipe deseja abandonar a barreira de verificação "apenas para esta sprint".
Um novo produto de agente é lançado e você precisa de um benchmark portátil para saber se ele realmente economiza tempo.

Os números vão mais longe do que a explicação.

Ship It

outputs/skill-workbench-benchmark.md é um harness de avaliação portátil que executa qualquer produto de agente por ambos os pipelines contra o próprio aplicativo de exemplo do projeto e relata os cinco resultados.

Exercícios

Adicione um sexto resultado: tempo até a primeira edição significativa. Como você mede isso de forma limpa?
Execute a comparação em uma tarefa real de segundo dia em sua base de código. Onde os números da bancada de trabalho caem?
Adicione uma passagem de "falso negativo": tarefas onde apenas o prompt teria sido mais rápido e a sobrecarga da bancada de trabalho é um custo real. Defenda a manutenção da bancada de trabalho mesmo assim.
Substitua o "agente" roteirizado por uma chamada real de LLM. Quais resultados ficam mais instáveis?
Escreva um resumo de uma página voltado para um não engenheiro. O que sobrevive ao corte?

Termos-Chave

Termo	O que as pessoas dizem	O que realmente significa
Sample app	"Repositório de brinquedo"	Pequeno, mas realista o suficiente para exercitar todas as sete superfícies
Pipeline	"Fluxo de trabalho"	Sequência ordenada de leituras/gravações de superfície que o agente segue
Before/after report	"Os recibos"	O artefato que você entrega a um cético
False negative	"Exagero da bancada"	Tarefas em que usar apenas o prompt é mais rápido; útil para enumerar honestamente
Workbench benchmark	"Pontuação de confiabilidade"	Harness portátil que executa a comparação em sua base de código

Leitura Adicional

LangChain, The Anatomy of an Agent Harness — Recibo de Top-30 para Top-5 no Terminal Bench
MongoDB, The Agent Harness: Why the LLM Is the Smallest Part of Your Agent System — Números da Vercel + Harvey
preprints.org, Harness Engineering for Language Agents — Taxa de falha empresarial de 88%, causas raiz em tempo de execução
HN: Improving 15 LLMs at Coding in One Afternoon. Only the Harness Changed — replicado em 15 modelos
Cloudflare, Orchestrating AI Code Review at Scale — 131 mil execuções de revisão / 30 dias em produção
Anthropic, Building Effective Agents
Fases 14 · 32 a 14 · 40 — as superfícies que esta lição exercita de ponta a ponta
Fase 14 · 19 — SWE-bench, GAIA, AgentBench como os macro-benchmarks que esta lição complementa
Fase 14 · 30 — desenvolvimento de agentes orientado a avaliação em que o mesmo harness se conecta