Skip to content

Harness engineering beginner tutorial, from 0 to 1

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.ts
new file mode 100644
index 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 file
diff --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.md
new file mode 100644
index 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 file
diff --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.md
new file mode 100644
index 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 file
diff --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.md
new file mode 100644
index 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 file
diff --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.md
new file mode 100644
index 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.