Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
refactor: Add lecture on why capable agents fail despite strong models in Portuguese
João Paulo Fricks05288115995d
diff --git a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.tsnew file mode 100644index 0000000..188d450--- /dev/null+++ b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts@@ -0,0 +1,242 @@+/**+ * failure-pattern-demo.ts+ *+ * Simula o padrão de falha em 4 etapas no qual agentes capazes frequentemente caem:+ * 1. Contexto incompleto+ * 2. Mudanças localmente razoáveis+ * 3. Ausência de verificação global+ * 4. Conclusão prematura+ *+ * Execute:+ * npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts+ */++// ---------------------------------------------------------------------------+// Tipos+// ---------------------------------------------------------------------------++interface StepState {+ step: number;+ name: string;+ contextAvailable: string[];+ contextMissing: string[];+ actionTaken: string;+ localOutcome: string;+ globalImpact: string;+ completed: boolean;+}++// ---------------------------------------------------------------------------+// "Modelo" simulado — uma função simples de decisão que baseia sua saída+// apenas no contexto que recebeu.+// ---------------------------------------------------------------------------++function modelDecide(context: string[], task: string): string {+ const has = (s: string) => context.some((c) => c.includes(s));++ // A tarefa é "adicionar um endpoint de busca na API".+ // A resposta correta exige conhecimento sobre middleware de autenticação+ // e limitação de taxa (rate limiting).++ if (!has("auth")) {+ return "Criou a nova rota /search sem verificações de autenticação";+ }++ if (!has("rate-limit")) {+ return "Adicionou a rota de busca com autenticação, mas esqueceu o rate limiting";+ }++ if (!has("test-standards")) {+ return "Implementou a busca com autenticação e rate limiting, mas sem testes";+ }++ return "Implementou completamente o endpoint de busca com autenticação, rate limiting e testes";+}++// ---------------------------------------------------------------------------+// Simulação de falha+// ---------------------------------------------------------------------------++function simulateFailurePattern(): StepState[] {+ const steps: StepState[] = [];++ // ---- Etapa 1: Contexto incompleto ----+ const step1Context = ["estrutura do projeto", "definições de rotas"];+ const step1Missing = [+ "middleware de autenticação",+ "política de rate limiting",+ "padrões de testes",+ ];++ const step1Decision = modelDecide(+ step1Context,+ "adicionar endpoint de busca"+ );++ steps.push({+ step: 1,+ name: "Contexto Incompleto",+ contextAvailable: step1Context,+ contextMissing: step1Missing,+ actionTaken: step1Decision,+ localOutcome: "Parece correto -- a rota compila e retorna dados",+ globalImpact:+ "A ausência de autenticação permite acesso não autenticado à busca",+ completed: false,+ });++ // ---- Etapa 2: Mudanças localmente razoáveis ----+ // O agente adiciona autenticação após uma dica,+ // mas ainda sem outros contextos importantes.+ const step2Context = [...step1Context, "middleware de autenticação"];+ const step2Missing = ["política de rate limiting", "padrões de testes"];++ const step2Decision = modelDecide(+ step2Context,+ "adicionar endpoint de busca"+ );++ steps.push({+ step: 2,+ name: "Mudanças Localmente Razoáveis",+ contextAvailable: step2Context,+ contextMissing: step2Missing,+ actionTaken: step2Decision,+ localOutcome: "A rota possui autenticação -- parece completa localmente",+ globalImpact:+ "Sem rate limiting, o endpoint pode ser abusado",+ completed: false,+ });++ // ---- Etapa 3: Ausência de verificação global ----+ const step3Context = [...step2Context, "política de rate limiting"];+ const step3Missing = ["padrões de testes"];++ const step3Decision = modelDecide(+ step3Context,+ "adicionar endpoint de busca"+ );++ steps.push({+ step: 3,+ name: "Ausência de Verificação Global",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: step3Decision,+ localOutcome: "A funcionalidade parece totalmente implementada",+ globalImpact:+ "Sem testes -- risco de regressão e violação dos padrões do projeto",+ completed: false,+ });++ // ---- Etapa 4: Conclusão prematura ----+ steps.push({+ step: 4,+ name: "Conclusão Prematura",+ contextAvailable: step3Context,+ contextMissing: step3Missing,+ actionTaken: 'Agente responde: "Concluído. Endpoint de busca adicionado."',+ localOutcome: "O agente está satisfeito e marca a tarefa como concluída",+ globalImpact:+ "A tarefa está incompleta -- faltam testes e verificação E2E",+ completed: true,+ });++ return steps;+}++// ---------------------------------------------------------------------------+// Tabela comparativa+// ---------------------------------------------------------------------------++function printComparisonTable(steps: StepState[]): void {+ console.log("\n" + "=".repeat(90));+ console.log(" DEMONSTRAÇÃO DO PADRÃO DE FALHA -- 4 Etapas até uma entrega quebrada");+ console.log("=".repeat(90));++ for (const s of steps) {+ console.log(`\n Etapa ${s.step}: ${s.name}`);+ console.log(" " + "-".repeat(60));++ console.log(+ ` Contexto disponível : ${s.contextAvailable.join(", ")}`+ );++ console.log(+ ` Contexto ausente : ${+ s.contextMissing.join(", ") || "(nenhum)"+ }`+ );++ console.log(` Ação executada : ${s.actionTaken}`);+ console.log(` Resultado local : ${s.localOutcome}`);+ console.log(` Impacto global : ${s.globalImpact}`);++ console.log(+ ` Marcado como concluído? : ${+ s.completed ? "SIM (prematuramente)" : "Não"+ }`+ );+ }++ // Resumo comparativo+ console.log("\n" + "=".repeat(90));+ console.log(+ " COMPARAÇÃO: O que o agente viu vs. o que realmente era necessário"+ );+ console.log("=".repeat(90));++ const totalRequired = [+ "estrutura do projeto",+ "definições de rotas",+ "middleware de autenticação",+ "política de rate limiting",+ "padrões de testes",+ ];++ const finalAvailable =+ steps[steps.length - 1].contextAvailable;++ const header =+ "| Critério | Disponível | Ausente | Status |";++ const sep =+ "|-------------------------|------------|----------|----------|";++ console.log("\n" + header);+ console.log(sep);++ for (const item of totalRequired) {+ const avail = finalAvailable.includes(item);++ const row = `| ${item.padEnd(24)}| ${(+ avail ? "Sim" : "Não"+ ).padEnd(11)}| ${(!avail ? "Sim" : "").padEnd(9)}| ${(+ avail ? "OK" : "LACUNA"+ ).padEnd(9)}|`;++ console.log(row);+ }++ const gapCount = totalRequired.filter(+ (i) => !finalAvailable.includes(i)+ ).length;++ console.log(+ "\n Resultado: o agente concluiu com " ++ gapCount ++ " de " ++ totalRequired.length ++ " itens de contexto ausentes."+ );++ console.log(+ " Este é o padrão central de falha: cada etapa parecia razoável isoladamente.\n"+ );+}++// ---------------------------------------------------------------------------+// Execução+// ---------------------------------------------------------------------------++printComparisonTable(simulateFailurePattern());\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.mdnew file mode 100644index 0000000..dd4ff08--- /dev/null+++ b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md@@ -0,0 +1,9 @@+# Checklist de Sinais de Falha++Utilize este checklist ao revisar uma execução com um harness fraco.++- O agente perguntou, ou inferiu incorretamente, como iniciar a aplicação?+- Ele criou diretórios ou abstrações que não correspondem ao produto pretendido?+- Ele parou após criar apenas uma interface visual sem um fluxo completo funcionando?+- Ele deixou notas ou artefatos que ajudam uma futura execução a continuar o trabalho?+- Uma nova sessão conseguiria entender o que aconteceu em menos de cinco minutos?\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdnew file mode 100644index 0000000..76e15c7--- /dev/null+++ b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -0,0 +1,7 @@+# Código da Aula 01++Utilize esta pasta para pequenos exemplos que demonstrem:++- um modelo forte falhando em um ambiente fraco+- configuração de repositório subespecificada+- ausência de loops de feedback\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.mdnew file mode 100644index 0000000..f1f6c1c--- /dev/null+++ b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md@@ -0,0 +1,18 @@+# Exemplo de Tarefa Subespecificada++Crie um aplicativo desktop de base de conhecimento com perguntas e respostas utilizando IA.++Restrições:++- Nenhuma especificada+- Nenhum comando de inicialização fornecido+- Nenhuma orientação sobre estrutura de pastas+- Nenhum modelo de dados definido+- Nenhum critério explícito de conclusão++Resultados típicos desse tipo de prompt:++- o agente inventa uma estrutura de forma improvisada+- o aplicativo pode compilar, mas não iniciar de forma consistente+- a interface pode aparecer antes de existir um fluxo utilizável de ingestão/consulta+- o agente frequentemente para após um sucesso apenas cosmético\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.mdnew file mode 100644index 0000000..4351ae5--- /dev/null+++ b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -0,0 +1,103 @@+[中文版 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)++> Exemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/)+> Projeto prático: [Projeto 01. Apenas Prompt vs. Regras Primeiro: Quanta Diferença um Harness Faz](./../../projects/project-01-baseline-vs-minimal-harness/index.md)++# Aula 01. Modelos Fortes Não Significam Execução Confiável++No final de 2025, os agentes de programação mais fortes no SWE-bench Verified alcançam aproximadamente uma taxa de sucesso entre 50% e 60%. À primeira vista, esse número parece razoável — mas ainda não comemore. Essas são tarefas cuidadosamente selecionadas, com descrições claras de problemas e testes prontos. Agora entregue ao agente os requisitos do dia a dia — especificações vagas, ausência de testes existentes, regras de negócio implícitas espalhadas pela base de código — e essa taxa cai ainda mais. Você delega uma tarefa cheio de confiança, o agente trabalha por 20 minutos e responde “tudo pronto”, mas ao olhar o código: ele adicionou a funcionalidade e quebrou os testes, corrigiu um bug e introduziu outros, e ainda nem era exatamente o que você pediu.++Quando isso acontece, a primeira reação da maioria das pessoas é: “o modelo não é bom o suficiente — vou tentar um mais caro”. Antes de abrir a carteira, considere que talvez o problema não seja o modelo.++## Mesmo Cavalo, Destinos Diferentes++A Anthropic realizou um experimento controlado que ilustra perfeitamente esse ponto. Mesmo prompt (“crie um editor de jogos retrô 2D”), mesmo modelo (Opus 4.5), duas execuções. Primeira execução: ambiente cru, sem suporte — 20 minutos, US$9, e as funcionalidades principais do jogo não funcionavam. Segunda execução: harness completo — arquitetura de três agentes com planejador, gerador e avaliador — 6 horas, US$200, e o jogo ficou totalmente jogável.++Eles não mudaram o modelo. Opus 4.5 continuava sendo Opus 4.5. O que mudou foi o equipamento.++O artigo de Harness Engineering da OpenAI em 2025 foi ainda mais direto. Eles disseram que o Codex em um repositório com um bom harness deixa de ser “não confiável” e passa a ser “confiável”. Repare na escolha das palavras — não “um pouco melhor”, mas uma mudança qualitativa. Harness aqui significa **toda a infraestrutura de engenharia além dos pesos do modelo.**++## Onde os Agentes Realmente Falham++Os modos de falha específicos se resumem basicamente a alguns pontos:++- **Requisitos vagos — o agente só consegue adivinhar.** “Adicione uma funcionalidade de busca” — essa frase significa quase nada. Buscar o quê? Texto completo ou consultas estruturadas? Os resultados devem ser paginados? Destacados? Você não especificou, então o agente precisa adivinhar. Acertar é sorte; errar significa retrabalho que custa muito mais do que teria custado ser específico desde o início.+- **Convenções implícitas não documentadas — o agente não tem como seguir.** Todo o seu time usa a nova sintaxe do SQLAlchemy 2.0, mas o agente gera código 1.x por padrão. Todos os endpoints da API devem utilizar OAuth 2.0, mas essa regra existe apenas na sua cabeça e em uma mensagem no Slack de três meses atrás. O agente não faz ideia disso — não é que ele não queira seguir a regra, ele literalmente nunca a viu.+- **Configuração de ambiente incompleta — o agente desperdiça energia corrigindo o ambiente.** Setup de desenvolvimento incompleto, dependências ausentes, versões erradas de ferramentas — o agente gasta contexto precioso lidando com erros de `pip install` e conflitos de versão do Node em vez de fazer o trabalho real.+- **Ausência de métodos de verificação — o agente considera concluído quando acha que terminou.** Sem testes, sem lint ou comandos de verificação nunca comunicados ao agente. O agente escreve o código, revisa superficialmente, acha que está tudo certo e declara conclusão. A Anthropic também observou um fenômeno interessante: quando os agentes percebem que o contexto está acabando, eles aceleram para terminar, pulam etapas de verificação e escolhem soluções simples em vez das melhores soluções. Eles chamam isso de “ansiedade de contexto”.+- **Perda de estado entre sessões — toda nova sessão começa do zero.** Todas as descobertas da sessão anterior são perdidas. Cada nova sessão precisa redescobrir a estrutura do projeto e entender novamente a organização do código. Agentes sem estado persistente apresentam aumento significativo nas falhas em tarefas que ultrapassam 30 minutos.++## Terminologia Essencial++Com os cenários acima em mente, estes conceitos deixam de ser apenas jargões:++- **Capability Gap**: O enorme abismo entre o desempenho do modelo em benchmarks e o desempenho em tarefas reais. Uma taxa de sucesso de 50–60% no SWE-bench Verified significa que quase metade dos problemas reais continuam sem solução.+- **Harness**: Tudo que está fora do modelo — instruções, ferramentas, ambiente, gerenciamento de estado e feedback de verificação. Se não são os pesos do modelo, então é harness. O que chamamos anteriormente de “equipamento”.+- **Harness-Induced Failure**: O modelo possui capacidade suficiente, mas o ambiente de execução possui defeitos estruturais. O experimento controlado da Anthropic já demonstrou isso.+- **Verification Gap**: A diferença entre a confiança do agente em sua resposta e a correção real. O agente diz “terminei” quando ainda não terminou — esse é o modo de falha mais comum.+- **Diagnostic Loop**: Executar, observar a falha, atribuir a uma camada específica do harness, corrigir essa camada e executar novamente. Essa é a metodologia central da harness engineering.+- **Definition of Done**: Um conjunto de condições verificáveis por comando — testes passando, lint limpo, type checks aprovados. Sem uma definição explícita de conclusão, o agente inventará a própria definição.++## Quando Algo Falhar, Corrija o Harness Primeiro++Existe apenas um princípio central: **quando algo falhar, não troque o modelo primeiro — verifique o harness.** Se o mesmo modelo consegue resolver tarefas semelhantes e bem estruturadas, assuma que o problema está no harness.++Como isso funciona na prática? Atribua cada falha a uma camada específica. Não diga apenas “o modelo não é bom o suficiente”. Pergunte-se: a tarefa estava clara? O contexto era suficiente? Existiam métodos de verificação? Mapeie cada falha para uma das cinco camadas de defesa — especificação da tarefa, fornecimento de contexto, ambiente de execução, feedback de verificação e gerenciamento de estado. Desenvolva esse hábito e você verá “o modelo não é bom o suficiente” aparecer cada vez menos nos seus logs.++Depois, escreva uma Definition of Done explícita para cada tarefa. Não diga apenas “adicione uma busca”. Seja específico:++```txt+Critérios de conclusão:+- Novo endpoint GET /api/search?q=xxx+- Suporte à paginação, 20 itens por padrão+- Resultados incluem trechos destacados+- Todo novo código passa no pytest+- Verificação de tipos aprovada (mypy --strict)+```+Adicione um arquivo `AGENTS.md` na raiz do repositório informando ao agente a stack do projeto, convenções arquiteturais e comandos de verificação. Esse é o primeiro passo da harness engineering — e também o de maior retorno sobre investimento. Um único `AGENTS.md` pode ser mais eficiente do que migrar para um modelo mais caro — e isso não é exagero.++A partir daí, construa um loop de diagnóstico. Não trate falhas como “o modelo sendo burro novamente”. Trate-as como sinais de que o seu harness expôs um defeito. A cada falha, identifique a camada, corrija-a e evite falhar da mesma forma novamente. Após algumas iterações, o harness fica mais forte e o desempenho do agente se estabiliza. Um log simples já basta — para cada tarefa, registre se ela teve sucesso ou falhou e qual camada causou a falha. Depois de algumas rodadas, ficará claro qual camada é o gargalo, permitindo concentrar energia nela.++## O Experimento do Milhão de Linhas++Em 2025, três engenheiros da OpenAI iniciaram um experimento. As regras eram simples: eles não escreveriam código manualmente — apenas o Codex escreveria. Partindo de um repositório Git vazio, cinco meses depois o projeto continha aproximadamente um milhão de linhas de código. Lógica da aplicação, infraestrutura, ferramentas, documentação — tudo gerado por agentes. Os três engenheiros abriram um total de 1.500 PRs, média de 3,5 PRs por pessoa por dia.++O progresso inicial foi surpreendentemente lento. O Codex não era ruim — apenas não possuía ferramentas e estruturas suficientes para avançar em direção a objetivos de alto nível. Aos poucos, os engenheiros descobriram um padrão: quebrar grandes objetivos em pequenos blocos — design, código, revisão, testes — deixar o agente montar esses blocos individualmente e depois combiná-los em tarefas mais complexas. Sempre que algo dava errado, o problema quase nunca era “não estamos tentando o suficiente”. A pergunta correta era sempre: “o que o agente ainda não possui, e essa capacidade pode ser fornecida de maneira compreensível e executável?”++Esse experimento comprova diretamente a tese central desta aula: **o mesmo modelo produz resultados fundamentalmente diferentes em um ambiente cru versus um ambiente com harness completo.** O modelo não mudou. O ambiente mudou.++> Fonte: [OpenAI: Engenharia de aproveitamento: alavancando o Codex em um mundo centrado em agentes.](https://openai.com/index/harness-engineering/)++## Um Exemplo Mais Próximo da Realidade++Um time utilizou Claude Sonnet para adicionar novos endpoints de API em uma aplicação web Python de médio porte (FastAPI + PostgreSQL + Redis, ~15 mil linhas de código).++Inicialmente, forneceram apenas uma frase: “adicione endpoints de preferências do usuário em `/api/v2/users`”. O resultado? O agente gastou 40% da janela de contexto explorando a estrutura do repositório, gerou código aparentemente razoável, mas sem seguir os padrões de tratamento de erros do projeto, utilizou sintaxe antiga do SQLAlchemy e declarou conclusão enquanto os endpoints ainda apresentavam erros em runtime. A sessão seguinte precisou refazer todo o trabalho de descoberta.++Depois, adicionaram um `AGENTS.md` (descrevendo arquitetura do projeto e versões da stack), comandos explícitos de verificação (`pytest tests/api/v2/ && python -m mypy src/`) e registros de decisões arquiteturais. O mesmo modelo passou a ter sucesso em todas as três execuções independentes, com aproximadamente 60% mais eficiência de contexto.++Eles não mudaram o modelo. Mudaram o harness.++## Principais Conclusões++- Capacidade do modelo e confiabilidade de execução são coisas diferentes. Até um cavalo puro-sangue precisa de um bom equipamento.+- Quando algo falhar, verifique o harness antes do modelo. Trocar de modelo é a opção mais cara — e frequentemente o problema nem está no modelo.+- Toda falha é um sinal: seu harness possui um defeito estrutural. Descubra qual é e corrija.+- Não diga apenas “o modelo não é bom o suficiente”. Trabalhe sistematicamente pelas cinco camadas: tarefa mal definida, contexto insuficiente, ambiente mal configurado, ausência de verificação ou perda de estado entre sessões. Em nove de cada dez casos, o problema está em uma dessas camadas.+- Um único arquivo `AGENTS.md` pode ser mais eficiente do que migrar para um modelo mais caro.++## Leituras Complementares++- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)+- [SWE-bench Leaderboard](https://www.swebench.com/)+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)++## Exercícios++1. **Experimento de comparação**: Escolha uma base de código que você conhece bem e uma tarefa de modificação não trivial. Primeiro, execute o agente sem suporte de harness e registre as falhas. Depois, adicione um `AGENTS.md` e comandos explícitos de verificação, execute novamente com o mesmo agente e compare os resultados, atribuindo cada falha a uma das cinco camadas de defesa.++2. **Medição do verification gap**: Escolha 5 tarefas de programação. Após cada tarefa, registre se o agente afirma ter concluído o trabalho e depois valide a correção real com testes independentes. Calcule a proporção de vezes em que o agente afirma ter terminado quando na verdade ainda não terminou — esse é o seu verification gap. Depois reflita: quais comandos de verificação poderiam reduzir essa proporção?++3. **Prática de diagnostic loope**: Encontre uma tarefa na qual o agente falha repetidamente no seu projeto. Execute uma vez e registre a falha. Atribua-a a uma das cinco camadas. Corrija essa camada. Execute novamente. Repita de três a cinco rodadas registrando as melhorias a cada tentativa.