Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
refactor: Add lecture 08 in Portuguese
João Paulo Fricksad597f7a1cbc
diff --git a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.tsnew file mode 100644index 0000000..f8881f7--- /dev/null+++ b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts@@ -0,0 +1,264 @@+/**+ * feature-list-validator.ts+ *+ * Lê um feature_list.json, valida seu esquema e verifica se existem+ * funcionalidades marcadas como "pass" sem evidências de verificação.+ * Gera um relatório estruturado.+ * Pode ser executado em qualquer diretório de projeto que contenha um feature_list.json.+ *+ * Uso:+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [caminho-para-o-diretório]+ * (por padrão, utiliza o diretório que contém este script)+ *+ * Executar:+ * npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts+ */++import * as fs from "node:fs";+import * as path from "node:path";++// ---------------------------------------------------------------------------+// Tipos+// ---------------------------------------------------------------------------++interface FeatureEntry {+ id?: string;+ category?: string;+ description?: string;+ verification?: string[];+ passes?: boolean;+ // Permite campos desconhecidos para maior flexibilidade+ [key: string]: unknown;+}++interface ValidationResult {+ featureId: string;+ schemaValid: boolean;+ schemaErrors: string[];+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+ passes: boolean;+ verificationCount: number;+}++// ---------------------------------------------------------------------------+// Validação do esquema+// ---------------------------------------------------------------------------++function validateSchema(entry: FeatureEntry, index: number): string[] {+ const errors: string[] = [];+ const label = entry.id ?? `entrada ${index + 1}`;++ if (!entry.id || typeof entry.id !== "string") {+ errors.push(`[${label}] Campo 'id' ausente ou inválido`);+ }+ if (!entry.category || typeof entry.category !== "string") {+ errors.push(`[${label}] Campo 'category' ausente ou inválido`);+ }+ if (!entry.description || typeof entry.description !== "string") {+ errors.push(`[${label}] Campo 'description' ausente ou inválido`);+ }+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {+ errors.push(`[${label}] 'verification' deve ser um array, se estiver presente`);+ }+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {+ errors.push(`[${label}] 'passes' deve ser um booleano, se estiver presente`);+ }++ return errors;+}++// ---------------------------------------------------------------------------+// Validação de evidências+// ---------------------------------------------------------------------------++function checkEvidence(entry: FeatureEntry): {+ hasVerification: boolean;+ markedPassWithoutEvidence: boolean;+} {+ const hasVerification =+ Array.isArray(entry.verification) && entry.verification.length > 0;++ const markedPassWithoutEvidence =+ entry.passes === true && !hasVerification;++ return { hasVerification, markedPassWithoutEvidence };+}++// ---------------------------------------------------------------------------+// Processamento da lista de funcionalidades+// ---------------------------------------------------------------------------++function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {+ return entries.map((entry, index) => {+ const schemaErrors = validateSchema(entry, index);+ const evidence = checkEvidence(entry);++ return {+ featureId: (entry.id as string) ?? `entry-${index + 1}`,+ schemaValid: schemaErrors.length === 0,+ schemaErrors,+ hasVerification: evidence.hasVerification,+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,+ passes: entry.passes === true,+ verificationCount: Array.isArray(entry.verification)+ ? entry.verification.length+ : 0,+ };+ });+}++// ---------------------------------------------------------------------------+// Relatórios+// ---------------------------------------------------------------------------++function pad(s: string, len: number): string {+ return s.length >= len ? s : s + " ".repeat(len - s.length);+}++function run(): void {+ // Resolve o diretório de destino+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);++ const targetDir = process.argv[2]+ ? path.resolve(process.argv[2])+ : scriptDir;++ const filePath = path.join(targetDir, "feature_list.json");++ console.log("\n" + "=".repeat(90));+ console.log(" VALIDADOR DE LISTA DE FUNCIONALIDADES");+ console.log("=".repeat(90));+ console.log(` Lendo: ${filePath}\n`);++ if (!fs.existsSync(filePath)) {+ console.error(+ ` ERRO: feature_list.json não encontrado em ${filePath}`+ );+ console.error(+ " Uso: npx tsx feature-list-validator.ts [caminho-para-o-diretório-que-contém-feature_list.json]\n"+ );+ process.exit(1);+ }++ let entries: FeatureEntry[];++ try {+ const raw = fs.readFileSync(filePath, "utf-8");+ entries = JSON.parse(raw);+ } catch (err) {+ console.error(+ ` ERRO: Não foi possível interpretar o feature_list.json: ${err}`+ );+ process.exit(1);+ }++ if (!Array.isArray(entries)) {+ console.error(+ " ERRO: feature_list.json deve conter um array JSON no nível superior."+ );+ process.exit(1);+ }++ // Para fins de demonstração, também valida um conjunto estendido de testes+ const demoEntries: FeatureEntry[] = [+ ...entries,+ {+ id: "qna-002",+ category: "import",+ description: "O usuário pode importar um documento PDF.",+ verification: [+ "Fazer upload de um arquivo PDF",+ "Verificar se ele aparece na lista de documentos",+ ],+ passes: true,+ },+ {+ id: "qna-003",+ category: "grounded_qa",+ description: "A taxa de alucinação do sistema é inferior a 5%.",+ verification: [], // Vazio — sem evidências+ passes: true, // Marcado como aprovado SEM evidências+ },+ {+ id: "missing-fields",+ // Campos 'category' e 'description' ausentes+ passes: true,+ } as FeatureEntry,+ ];++ const results = processFeatureList(demoEntries);++ // Exibe o relatório+ const header = `| ${pad("ID da Funcionalidade", 14)}| ${pad("Esquema", 8)}| ${pad("Passa", 7)}| ${pad("Verificações", 14)}| ${pad("Evidência?", 12)}| Observações`;++ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;++ console.log(header);+ console.log(sep);++ for (const r of results) {+ const schemaLabel = r.schemaValid ? "OK" : "INVÁLIDO";+ const passesLabel = r.passes ? "PASS" : "FAIL";+ const evidenceLabel = r.hasVerification ? "Presente" : "AUSENTE";++ const notes = r.markedPassWithoutEvidence+ ? "SINALIZADO: aprovado sem evidências!"+ : r.schemaErrors.length > 0+ ? r.schemaErrors[0]+ : "";++ const marker = r.markedPassWithoutEvidence+ ? ">>"+ : r.schemaValid+ ? " "+ : "!!";++ console.log(+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(+ passesLabel,+ 7+ )}| ${pad(String(r.verificationCount), 14)}| ${pad(+ evidenceLabel,+ 12+ )}| ${notes}`+ );+ }++ // Resumo+ const total = results.length;+ const schemaOk = results.filter((r) => r.schemaValid).length;+ const passing = results.filter((r) => r.passes).length;+ const flagged = results.filter(+ (r) => r.markedPassWithoutEvidence+ ).length;++ const withEvidence = results.filter(+ (r) => r.hasVerification+ ).length;++ console.log("\n" + "-".repeat(90));+ console.log(" RESUMO");+ console.log("-".repeat(90));++ console.log(` Total de funcionalidades: ${total}`);+ console.log(` Esquema válido: ${schemaOk}/${total}`);+ console.log(` Marcadas como aprovadas: ${passing}/${total}`);+ console.log(` Com evidências de verificação: ${withEvidence}/${total}`);+ console.log(` Sinalizadas (aprovadas sem evidência): ${flagged}`);++ if (flagged > 0) {+ console.log(+ `\n AVISO: ${flagged} funcionalidade(s) marcadas como "pass" sem qualquer evidência de verificação.`+ );+ console.log(+ " Essas funcionalidades precisam ser verificadas antes de serem consideradas confiáveis.\n"+ );+ } else {+ console.log(+ "\n Todas as funcionalidades aprovadas possuem evidências de verificação. A lista de funcionalidades está saudável.\n"+ );+ }+}++run();\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.jsonnew file mode 100644index 0000000..fc12dc0--- /dev/null+++ b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json@@ -0,0 +1,15 @@+[+ {+ "id": "qna-001",+ "category": "grounded_qa",+ "description": "O usuário pode fazer uma pergunta sobre um documento importado e receber uma resposta com citações visíveis.",+ "verification": [+ "Importar um documento Markdown",+ "Abrir o painel de Perguntas e Respostas (Q&A)",+ "Fazer uma pergunta sobre um conteúdo conhecido",+ "Verificar se a resposta é retornada",+ "Verificar se uma ou mais citações são exibidas"+ ],+ "passes": false+ }+]\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.mdnew file mode 100644index 0000000..5ea56e4--- /dev/null+++ b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md@@ -0,0 +1,8 @@+# Código da Aula 08++Use esta pasta para exemplos de:++- controle por estado de aprovação (pass-state gating)+- verificação de ponta a ponta (end-to-end)+- critérios de conclusão fracos versus fortes+- exemplos de loops de avaliação (evaluator-loop)\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdnew file mode 100644index 0000000..a99b047--- /dev/null+++ b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -0,0 +1,8 @@+# Política de Aprovação (Pass Gate)++Uma funcionalidade só pode passar de `passes: false` para `passes: true` quando:++- o fluxo de trabalho esperado tiver sido executado+- a evidência de sucesso tiver sido registrada+- não existir nenhum erro bloqueador no caminho testado+- a implementação não deixar a aplicação em um estado quebrado ou ambíguo\ No newline at end of filediff --git a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdnew file mode 100644index 0000000..3564e92--- /dev/null+++ b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -0,0 +1,142 @@+[中文版 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)++> Exemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> Projeto prático: [Projeto 04. Feedback em tempo de execução e controle de escopo](./../../projects/project-04-incremental-indexing/index.md)++# Aula 08. Use Listas de Funcionalidades para Restringir o que o Agente Faz++Você pede a um agente para construir um site de e-commerce. Depois que ele termina, ele diz: "concluído". Você olha o código — a autenticação de usuários funciona, mas o botão de checkout no carrinho não faz nada, e o fluxo de pagamento nem sequer está conectado. Onde as coisas deram errado? Você nunca disse ao agente o que significa "concluído", então ele usou o próprio padrão: "escrevi bastante código e parece razoavelmente completo".++Na visão de muitas pessoas, listas de funcionalidades são apenas um lembrete — anote as coisas para não esquecer e depois descarte. Mas no mundo dos harnesses, uma lista de funcionalidades não é um lembrete para humanos. Ela é a estrutura fundamental sobre a qual todo o harness é construído. O escalonador depende dela para selecionar tarefas, o verificador depende dela para julgar a conclusão, e o gerador de relatórios de handoff depende dela para criar resumos. Sem ela, esses componentes não têm um consenso compartilhado em que possam se apoiar.++Tanto a Anthropic quanto a OpenAI enfatizam: **artefatos devem ser externalizados.** O estado das funcionalidades deve existir em um arquivo legível por máquina dentro do repositório, e não em texto de conversa não estruturado.++## Agentes Não Sabem o que Significa "Concluído"++Nem o Claude Code nem o Codex sabem automaticamente o que você quer dizer com "concluído". Você diz "adicione uma funcionalidade de carrinho de compras", e a interpretação do modelo pode ser "escrever um componente Cart e um método addToCart". Mas o que você queria dizer era "o usuário pode navegar pelos produtos, adicionar itens ao carrinho e concluir a compra de ponta a ponta".++Essa lacuna de entendimento persiste sem uma lista de funcionalidades. O agente usa seu próprio padrão implícito — geralmente "o código não tem erros de sintaxe evidentes". O que você precisa é de uma verificação comportamental de ponta a ponta. Sem uma lista, os dois lados nunca concordarão sobre o que significa "concluído".++Veja esta anotação de progresso comum:++```text+Autenticação do usuário concluída, carrinho de compras quase pronto, faltam apenas os pagamentos.+```++Uma nova sessão de agente consegue responder às seguintes perguntas com base nessa anotação? O que significa "quase concluído"? Quais testes o carrinho passou? O que está bloqueando os pagamentos? A resposta para todas elas é: "ninguém sabe".++O resultado: a nova sessão passa 20 minutos tentando inferir o estado do projeto e pode acabar reimplementando funcionalidades já concluídas. Dados de engenharia da Anthropic mostram que bons registros de progresso reduzem o tempo de diagnóstico no início de uma sessão em 60–80%.++## Máquina de Estados das Funcionalidades++```mermaid+flowchart LR+ Feature["Uma linha de funcionalidade"] --> Behavior["Comportamento<br/>ex.: POST /cart/items retorna 201"]+ Feature --> Check["Comando de verificação<br/>a verificação exata a ser executada"]+ Feature --> State["Estado<br/>not_started / active / blocked / passing"]++ Behavior --> Complete["Todos os três campos presentes<br/>a linha da funcionalidade é utilizável"]+ Check --> Complete+ State --> Complete+```++```mermaid+flowchart LR+ List["feature_list.json / features.md"] --> Scheduler["Selecionar o próximo item not_started"]+ Scheduler --> Agent["O agente trabalha nesse único item"]+ Agent --> Verifier["Executar o comando de verificação desse item"]+ Verifier -->|pass| Passing["Marcar como passing<br/>e anexar evidências"]+ Verifier -->|fail| Active["Manter como active"]+ Verifier -->|dependency issue| Blocked["Marcar como blocked"]+ Passing --> Handoff["Atualizar a nota de handoff<br/>e o progresso atual"]+ Active --> Agent+```++## Conceitos Fundamentais++* **Listas de funcionalidades são primitivas do harness**: Não são "ferramentas opcionais de planejamento", mas estruturas de dados fundamentais das quais todos os outros componentes do harness dependem. O escalonador, o verificador e o gerador de relatórios de handoff precisam ler a lista de funcionalidades para funcionar.+* **Estrutura tripla**: Cada item da lista de funcionalidades contém três elementos: `(descrição do comportamento, comando de verificação, estado atual)`. O comportamento informa ao agente o que fazer, a verificação define o que conta como concluído e o estado informa a situação atual. A ausência de qualquer um desses elementos torna o item incompleto.+* **Modelo de máquina de estados**: Cada item de funcionalidade possui quatro estados — `not_started`, `active`, `blocked`, `passing`. As transições de estado são controladas pelo harness, e não alteradas livremente pelo agente.+* **Controle por estado de aprovação (pass-state gating)**: A única forma de uma funcionalidade passar de `active` para `passing` é por meio da execução bem-sucedida do comando de verificação. Essa transição é irreversível — uma vez em `passing`, não pode voltar atrás.+* **Fonte única da verdade (single source of truth)**: Todas as informações sobre "o que precisa ser feito" devem derivar de uma única lista de funcionalidades. Não deve haver contradições entre a lista de funcionalidades e o histórico da conversa.+* **Back-pressure**: O número de funcionalidades que ainda não atingiram o estado `passing` representa a pressão que o harness exerce sobre o agente. Pressão zero = projeto concluído.++## Por que Listas de Funcionalidades Devem Ser "Primitivas"++Documentos são feitos para humanos lerem; primitivas são feitas para sistemas executarem. Documentos podem ser ignorados; primitivas não podem ser contornadas.++Pense nisso como restrições (constraints) de gatilhos de banco de dados versus validações na camada da aplicação: as primeiras são aplicadas pelo mecanismo do banco de dados — nenhum SQL consegue ignorá-las. As segundas dependem da correção do código da aplicação e podem ser contornadas acidentalmente. Listas de funcionalidades como primitivas do harness desempenham o mesmo papel das restrições no nível do banco de dados — o agente não pode ignorá-las.++Especificamente, a lista de funcionalidades atende a quatro componentes do harness:++1. **Scheduler (Escalonador)**: Lê os estados e seleciona a próxima funcionalidade em `not_started`.+2. **Verifier (Verificador)**: Executa os comandos de verificação e decide se permite ou não as transições de estado.+3. **Handoff Reporter (Gerador de Relatórios de Handoff)**: Gera automaticamente resumos de handoff da sessão a partir da lista de funcionalidades.+4. **Progress Tracker (Rastreador de Progresso)**: Consolida a distribuição dos estados e fornece métricas de saúde do projeto.++## Como Fazer++### 1. Defina um Formato Mínimo para a Lista de Funcionalidades++Você não precisa de um sistema complexo — um arquivo Markdown estruturado ou JSON já funciona. O importante é que cada entrada contenha a estrutura tripla:++```json+{+ "id": "F03",+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",+ "state": "passing",+ "evidence": "commit abc123, test output log"+}+```++### 2. Permita que o Harness Controle as Transições de Estado++O agente não pode alterar diretamente o estado de uma funcionalidade para `passing`. Ele só pode enviar uma solicitação de verificação. O harness executa o comando de verificação e decide se permite ou não a transição. Isso é chamado de **pass-state gating**.++### 3. Escreva as Regras no CLAUDE.md++```text+## Regras da Lista de Funcionalidades+- Arquivo da lista de funcionalidades: /docs/features.md+- Apenas uma funcionalidade ativa por vez+- O comando de verificação deve ser aprovado antes de marcar como passing+- Não altere os estados da lista de funcionalidades manualmente — o script de verificação os atualiza automaticamente+```++### 4. Calibre a Granularidade++Cada item de funcionalidade deve ter um escopo que possa ser **concluído em uma única sessão**. Se for amplo demais, não será finalizado; se for detalhado demais, o custo de gerenciamento aumenta. "O usuário pode adicionar itens ao carrinho" é uma boa granularidade. "Implementar o carrinho de compras" é amplo demais. "Criar o campo `name` no modelo Cart" é detalhado demais.++## Caso Real++Uma plataforma de e-commerce com 10 funcionalidades. Duas abordagens de acompanhamento foram comparadas:++**Modo memorando**: O agente utiliza anotações não estruturadas para acompanhar o progresso. Após 3 sessões, as anotações se tornam algo como: "autenticação de usuários e lista de produtos concluídas, carrinho de compras quase pronto mas com bugs, pagamentos não iniciados". Uma nova sessão precisa de 20 minutos para inferir o estado do projeto e, no fim, reimplementa funcionalidades já concluídas.++**Modo estruturado**: Cada funcionalidade possui um estado claro e um comando de verificação. Uma nova sessão lê a lista de funcionalidades e, em 3 minutos, sabe que: F01–F05 estão em `passing`, F06 está em `active` (em andamento) e F07–F10 estão em `not_started`. Ela continua diretamente a partir da F06, sem retrabalho.++Resultado quantificado: projetos que utilizam listas de funcionalidades estruturadas apresentam uma taxa de conclusão de funcionalidades 45% maior do que aqueles que utilizam acompanhamento livre, com zero implementações duplicadas.++## Principais Aprendizados++* **Listas de funcionalidades são a estrutura fundamental do harness**, não memorandos para humanos. O scheduler, o verifier e o handoff reporter dependem delas.+* **Cada item de funcionalidade deve conter a estrutura tripla**: descrição do comportamento + comando de verificação + estado atual. A ausência de qualquer elemento torna o item incompleto.+* **As transições de estado são controladas pelo harness** — o agente não pode alterar estados por conta própria. Uma verificação aprovada é o único caminho para promoção de estado.+* **A lista de funcionalidades é a fonte única da verdade do projeto** — todas as informações sobre "o que fazer" derivam dela.+* **Calibre a granularidade para algo que possa ser concluído em uma única sessão.** Se for amplo demais, não será finalizado; se for detalhado demais, torna-se difícil de gerenciar.++## Leitura Complementar++* [Construindo Agentes Eficazes - Anthropic](https://www.anthropic.com/research/building-effective-agents) — Identifica explicitamente a lista de funcionalidades como a "estrutura de dados central" para controlar o escopo do agente.+* [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Enfatiza o princípio da "externalização de artefatos".+* [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — Princípios de Design by Contract, a base teórica das listas de funcionalidades.+* [Como o Google testa softwares](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — Pirâmide de testes e práticas de engenharia de especificação comportamental.++## Exercícios++1. **Projeto de Lista de Funcionalidades**: Defina um esquema JSON mínimo para uma lista de funcionalidades. Inclua: id, descrição do comportamento, comando de verificação, estado atual e referência de evidência. Use-o para descrever um projeto real com 5 funcionalidades.++2. **Comparação de Rigor na Verificação**: Escolha 3 funcionalidades e projete tanto uma verificação "flexível" (por exemplo, "o código não possui erros de sintaxe") quanto uma verificação "rigorosa" (por exemplo, "o teste end-to-end passa com sucesso"). Compare as taxas de falso positivo em cada abordagem.++3. **Auditoria do Princípio da Fonte Única da Verdade**: Revise um projeto existente com agentes e verifique informações de escopo que contradizem a lista de funcionalidades (requisitos implícitos em conversas, comentários TODO no código etc.). Elabore um plano para unificar todas as informações na lista de funcionalidades.