Skip to content

Harness engineering beginner tutorial, from 0 to 1

refactor: Add lecture 06 on dedicated initialization phase in Portuguese

João Paulo Fricksd9f008adc387
diff --git a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
new file mode 100644
index 0000000..7f487ff
--- /dev/null
+++ b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
@@ -0,0 +1,8 @@
+# Código da Aula 06
+
+Utilize esta pasta para exemplos de:
+
+- saídas da fase de inicialização (*initializer outputs*)
+- scripts de inicialização
+- arquivos de progresso
+- estrutura inicial criada na primeira execução (*first-run scaffolding*)
\ No newline at end of file
diff --git a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
new file mode 100644
index 0000000..2910fd5
--- /dev/null
+++ b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
@@ -0,0 +1,296 @@
+/**
+ * init-check.ts
+ *
+ * Verifica programaticamente os pré-requisitos de inicialização:
+ * - Versão do Node.js
+ * - Dependências instaladas (existência de node_modules)
+ * - Existência do diretório de dados
+ * - Presença dos arquivos de configuração
+ *
+ * Simula a execução com e sem uma fase explícita de inicialização,
+ * demonstrando como pré-requisitos ausentes causam falhas silenciosas posteriormente.
+ *
+ * Executar: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as childProcess from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Tipos
+// ---------------------------------------------------------------------------
+
+interface CheckItem {
+ name: string;
+ category: string;
+ check: () => { pass: boolean; detail: string };
+ impactIfMissing: string;
+}
+
+interface CheckResult {
+ name: string;
+ category: string;
+ passed: boolean;
+ detail: string;
+ impactIfMissing: string;
+}
+
+// ---------------------------------------------------------------------------
+// Verificações
+// ---------------------------------------------------------------------------
+
+function createChecks(targetDir: string): CheckItem[] {
+ return [
+ {
+ name: "Versão do Node.js >= 18",
+ category: "Runtime",
+ check: () => {
+ try {
+ const version = process.version; // ex.: "v20.11.0"
+ const major = parseInt(version.replace("v", "").split(".")[0], 10);
+ return {
+ pass: major >= 18,
+ detail: `Detectado: ${version} (necessário >= v18)`,
+ };
+ } catch {
+ return { pass: false, detail: "Não foi possível detectar a versão do Node.js" };
+ }
+ },
+ impactIfMissing: "Recursos do TypeScript e APIs nativas indisponíveis",
+ },
+ {
+ name: "package.json existe",
+ category: "Configuração",
+ check: () => {
+ const p = path.join(targetDir, "package.json");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Encontrado: ${p}` : "Não encontrado no diretório alvo",
+ };
+ },
+ impactIfMissing: "Não é possível instalar dependências ou executar scripts",
+ },
+ {
+ name: "Dependências instaladas (node_modules)",
+ category: "Dependências",
+ check: () => {
+ const p = path.join(targetDir, "node_modules");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Encontrado: ${p}` : "node_modules/ não encontrado — execute npm install",
+ };
+ },
+ impactIfMissing: "Todos os imports falham em tempo de execução",
+ },
+ {
+ name: "TypeScript disponível",
+ category: "Ferramentas",
+ check: () => {
+ try {
+ const result = childProcess.execSync("npx tsc --version", {
+ encoding: "utf-8",
+ timeout: 10000,
+ stdio: ["pipe", "pipe", "pipe"],
+ }).trim();
+ return { pass: true, detail: `Detectado: ${result}` };
+ } catch {
+ return { pass: false, detail: "TypeScript não disponível via npx" };
+ }
+ },
+ impactIfMissing: "Não é possível compilar arquivos TypeScript",
+ },
+ {
+ name: "tsconfig.json existe",
+ category: "Configuração",
+ check: () => {
+ const p = path.join(targetDir, "tsconfig.json");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Encontrado: ${p}` : "Não encontrado",
+ };
+ },
+ impactIfMissing: "O compilador TypeScript usará configurações padrão, que podem não atender às necessidades do projeto",
+ },
+ {
+ name: "Diretório de código-fonte existe",
+ category: "Estrutura",
+ check: () => {
+ const candidates = ["src", "lib", "app"];
+ const found = candidates.filter((d) => {
+ const p = path.join(targetDir, d);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return {
+ pass: found.length > 0,
+ detail: found.length > 0 ? `Encontrado: ${found.join(", ")}` : "Nenhum diretório src/, lib/ ou app/ encontrado",
+ };
+ },
+ impactIfMissing: "O agente não consegue localizar os arquivos-fonte para modificar",
+ },
+ {
+ name: "Diretório de testes existe",
+ category: "Estrutura",
+ check: () => {
+ const candidates = ["test", "tests", "__tests__", "spec"];
+ const found = candidates.filter((d) => {
+ const p = path.join(targetDir, d);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return {
+ pass: found.length > 0,
+ detail: found.length > 0 ? `Encontrado: ${found.join(", ")}` : "Nenhum diretório de testes encontrado",
+ };
+ },
+ impactIfMissing: "O agente não consegue localizar ou executar os testes existentes",
+ },
+ {
+ name: "Repositório Git inicializado",
+ category: "Controle de Versão",
+ check: () => {
+ const gitDir = path.join(targetDir, ".git");
+ const exists = fs.existsSync(gitDir);
+ return {
+ pass: exists,
+ detail: exists ? "Repositório Git detectado" : "Nenhum diretório .git encontrado",
+ };
+ },
+ impactIfMissing: "Sem capacidade de rollback e sem histórico de alterações",
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Simulação: com e sem fase de inicialização
+// ---------------------------------------------------------------------------
+
+interface SimResult {
+ scenario: string;
+ checksRun: boolean;
+ failuresBeforeWork: number;
+ workAttempted: boolean;
+ workSucceeded: boolean;
+ timeWastedMs: number;
+}
+
+function simulateWithoutInit(): SimResult {
+ // O agente ignora a inicialização e começa a trabalhar imediatamente.
+ // Encontra falhas uma a uma à medida que esbarra em pré-requisitos ausentes.
+ const checks = createChecks(process.cwd());
+ let failures = 0;
+ let timeWasted = 0;
+
+ for (const check of checks) {
+ const result = check.check();
+ if (!result.pass) {
+ failures++;
+ timeWasted += 200; // O agente gasta tempo descobrindo cada problema
+ }
+ }
+
+ return {
+ scenario: "SEM FASE DE INICIALIZAÇÃO",
+ checksRun: false,
+ failuresBeforeWork: 0, // Não verificou previamente
+ workAttempted: true,
+ workSucceeded: failures === 0,
+ timeWastedMs: timeWasted,
+ };
+}
+
+function simulateWithInit(): SimResult {
+ // O agente executa a fase de inicialização primeiro e descobre todos os problemas antecipadamente.
+ const checks = createChecks(process.cwd());
+ let failures = 0;
+
+ for (const check of checks) {
+ if (!check.check().pass) {
+ failures++;
+ }
+ }
+
+ return {
+ scenario: "COM FASE DE INICIALIZAÇÃO",
+ checksRun: true,
+ failuresBeforeWork: failures,
+ workAttempted: failures === 0,
+ workSucceeded: failures === 0,
+ timeWastedMs: 0,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Relatórios
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const targetDir = process.cwd();
+ console.log("\n" + "=".repeat(80));
+ console.log(" VERIFICAÇÃO DOS PRÉ-REQUISITOS DE INICIALIZAÇÃO");
+ console.log("=".repeat(80));
+ console.log(` Alvo: ${targetDir}\n`);
+
+ const checks = createChecks(targetDir);
+ const results: CheckResult[] = checks.map((c) => {
+ const r = c.check();
+ return {
+ name: c.name,
+ category: c.category,
+ passed: r.pass,
+ detail: r.detail,
+ impactIfMissing: c.impactIfMissing,
+ };
+ });
+
+ // Relatório detalhado
+ const header = `| ${pad("Verificação", 35)}| ${pad("Categoria", 12)}| ${pad("Status", 6)}| Detalhe`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const status = r.passed ? "PASSOU" : "FALHOU";
+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);
+ }
+
+ const passCount = results.filter((r) => r.passed).length;
+ const failCount = results.filter((r) => !r.passed).length;
+
+ console.log("\n" + "-".repeat(80));
+ console.log(` Resultados: ${passCount} aprovadas, ${failCount} falharam de um total de ${results.length} verificações`);
+
+ if (failCount > 0) {
+ console.log("\n VERIFICAÇÕES FALHARAM — Impacto se não forem corrigidas:");
+ for (const r of results.filter((r) => !r.passed)) {
+ console.log(` - ${r.name}: ${r.impactIfMissing}`);
+ }
+ }
+
+ // Comparação: com e sem inicialização
+ const noInit = simulateWithoutInit();
+ const withInit = simulateWithInit();
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" COMPARAÇÃO DA FASE DE INICIALIZAÇÃO");
+ console.log("=".repeat(80) + "\n");
+
+ const cHeader = `| ${pad("Métrica", 35)}| ${pad("Sem Inicialização", 18)}| ${pad("Com Inicialização", 18)}|`;
+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;
+ console.log(cHeader);
+ console.log(cSep);
+ console.log(`| ${pad("Pré-requisitos verificados antecipadamente", 35)}| ${pad("Não", 18)}| ${pad("Sim", 18)}|`);
+ console.log(`| ${pad("Trabalho iniciado apesar dos problemas", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);
+ console.log(`| ${pad("Tempo perdido descobrindo problemas tardiamente", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);
+ console.log(`| ${pad("Trabalho concluído com sucesso", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);
+
+ console.log("\n Uma fase explícita de inicialização identifica problemas antes que eles desperdicem tempo.\n");
+}
+
+run();
diff --git a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
new file mode 100644
index 0000000..30afd58
--- /dev/null
+++ b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[init] instalando dependências"
+npm install
+
+echo "[init] iniciar o site da documentação é opcional"
+echo "[init] use npm run docs:dev para a documentação do curso"
+
+echo "[init] a inicialização específica do projeto seria definida aqui"
\ No newline at end of file
diff --git a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
new file mode 100644
index 0000000..d556085
--- /dev/null
+++ b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
@@ -0,0 +1,7 @@
+# Checklist de Saída da Inicialização
+
+- Existe um comando canônico para iniciar o projeto?
+- Existe um comando canônico para verificação?
+- Existe um primeiro artefato de progresso?
+- Existe um primeiro commit estável?
+- Existe uma superfície de funcionalidades visível para execuções futuras?
\ No newline at end of file
diff --git a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
new file mode 100644
index 0000000..a875b37
--- /dev/null
+++ b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -0,0 +1,163 @@
+[中文版 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+
+> Exemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)
+> Projeto prático: [Projeto 03. Continuidade entre múltiplas sessões](./../../projects/project-03-multi-session-continuity/index.md)
+
+# Aula 06. Faça o Agente Inicializar Antes de Cada Sessão de Trabalho
+
+Você inicia uma nova sessão do agente e pede: "adicione uma funcionalidade de busca". Ele parte imediatamente para a implementação — um entusiasmo admirável. Após 20 minutos, descobre que o framework de testes não está configurado corretamente, passa mais 10 minutos corrigindo isso e, em seguida, percebe que o formato do script de migração do banco de dados está incorreto, exigindo mais ajustes. No final, a funcionalidade de busca é implementada, mas toda a sessão foi ineficiente. A maior parte do tempo foi gasta "descobrindo como este projeto funciona" em vez de implementar a funcionalidade de busca em si.
+
+Uma abordagem melhor é utilizar uma fase separada antes de permitir que o agente comece a trabalhar: preparar o ambiente base, executar os comandos de verificação e compreender a estrutura do projeto. O trabalho de inicialização não deve ser agrupado com a implementação de funcionalidades — são dois tipos de tarefas fundamentalmente diferentes.
+
+Esta aula discute por que a inicialização deve ser uma fase separada, e não misturada com a implementação.
+
+## Dois Tipos de Trabalho Fundamentalmente Diferentes
+
+Inicialização e implementação possuem objetivos de otimização completamente distintos. A fase de implementação busca maximizar a quantidade e a qualidade de funcionalidades verificadas. Já a fase de inicialização busca maximizar a confiabilidade e a eficiência de toda a implementação subsequente.
+
+Quando você mistura inicialização e implementação, o agente passa a enfrentar um problema de otimização com múltiplos objetivos: precisa simultaneamente construir a infraestrutura e escrever o código da funcionalidade. Sem uma definição explícita de prioridades, o agente tende naturalmente a focar na escrita de código (pois esse é um resultado visível imediatamente), sacrificando a infraestrutura (cujo valor só aparece nas sessões seguintes). O resultado é que a infraestrutura não é construída de forma sólida e a confiabilidade do código da funcionalidade também acaba comprometida.
+
+## Ciclo de Vida da Inicialização
+
+```mermaid
+flowchart TB
+ subgraph Wrong["Misturado em uma única sessão (errado)"]
+ W1["Iniciar o desenvolvimento da funcionalidade imediatamente"] --> W2["Descobrir lacunas no ambiente e nos testes durante a tarefa"]
+ W2 --> W3["Acumular código não verificado"]
+ W3 --> W4["A próxima sessão precisa redescobrir o estado do projeto"]
+ end
+
+ subgraph Right["Fase de inicialização dedicada (correto)"]
+ R1["Sessão 1: ambiente executável"] --> R2["Teste de exemplo passando"]
+ R2 --> R3["Checklist de prontidão inicial + lista de tarefas documentados"]
+ R3 --> R4["Checkpoint limpo registrado em commit"]
+ R4 --> R5["Sessões posteriores iniciam diretamente em tarefas verificadas"]
+ end
+```
+
+## O Que Acontece Quando Você Mistura as Duas Coisas
+
+O problema mais direto é que a infraestrutura não é construída de forma sólida. O agente gasta 80% do esforço escrevendo código de funcionalidades e os 20% restantes configurando alguma infraestrutura de maneira superficial. O framework de testes é configurado, mas nunca validado; as regras de lint são definidas, mas permissivas demais; nenhum arquivo de progresso é criado. Esses problemas não são evidentes na primeira sessão (porque o agente ainda se lembra do que fez), mas aparecem na segunda sessão: o novo agente não sabe como executar o projeto, como testá-lo ou em que estado ele se encontra.
+
+Um custo mais oculto é o "acúmulo de código não verificado". Código de funcionalidades é escrito antes que o framework de testes esteja corretamente configurado — quando você finalmente volta para adicionar testes, pode descobrir que o próprio design estava incorreto. Se isso tivesse sido percebido antes, a implementação teria seguido outro caminho. Quanto mais código é escrito antecipadamente, mais código precisará ser descartado e refeito posteriormente.
+
+O orçamento de contexto também é desperdiçado. O trabalho de inicialização (configuração de ambientes, preparação dos testes, compreensão da estrutura do projeto) consome uma grande parte desse orçamento, deixando menos espaço para a implementação efetiva de funcionalidades. O resultado: a primeira sessão conclui apenas metade das funcionalidades, e a segunda sessão ainda precisa começar do zero para entender o projeto. O orçamento foi gasto com inicialização, mas a inicialização também não foi bem feita — o pior dos dois mundos.
+
+O problema mais fácil de ignorar são as armadilhas das suposições implícitas. Decisões tomadas pelo agente durante a inicialização (qual framework de testes usar, como organizar diretórios, como gerenciar dependências) — se não forem registradas explicitamente, sessões posteriores podem tomar decisões contraditórias. A primeira sessão escolheu o Vitest como framework de testes, mas o agente da segunda sessão não sabe disso e introduz o Jest. Dois frameworks de testes passam a coexistir, e o custo de manutenção dobra.
+
+A pesquisa da Anthropic sobre desenvolvimento de aplicações de longa duração recomenda explicitamente separar inicialização de implementação. Os dados experimentais mostraram que projetos que utilizam uma fase dedicada de inicialização apresentaram taxas de conclusão de funcionalidades 31% maiores em cenários com múltiplas sessões quando comparados a abordagens mistas. Além disso, o tempo investido na fase de inicialização é totalmente recuperado ao longo das 3 ou 4 sessões seguintes.
+
+O guia de *harness engineering* do Codex da OpenAI também enfatiza o princípio de que o "repositório é o registro operacional": é necessário estabelecer uma estrutura operacional clara desde a primeira execução; caso contrário, cada nova sessão precisará inferir novamente as convenções do projeto.
+
+## Conceitos Fundamentais
+
+- **Fase de Inicialização (*Initialization Phase*)**: A primeira fase do ciclo de vida do agente — seu único objetivo é estabelecer os pré-requisitos para a implementação subsequente, sem desenvolver funcionalidades. Sua saída é infraestrutura, não código de negócio.
+
+- **Checklist de Prontidão Inicial (*Startup Readiness Checklist*)**: As condições sob as quais um projeto pode ser operado sem ambiguidades por uma nova sessão do agente: consegue iniciar, consegue executar testes, consegue visualizar o progresso e consegue identificar os próximos passos. São quatro condições, todas obrigatórias.
+
+- **Do Zero vs. A Partir de um Template (*From Scratch vs From Template*)**: Começar do zero significa que o agente precisa inferir a estrutura do projeto por conta própria a partir de um diretório vazio; começar a partir de um template significa que a infraestrutura já está pronta. Iniciar a partir de um template apresenta desempenho muito superior ao início do zero.
+
+- **Sempre Pronto para Transferência (*Always Ready to Hand Off*)**: O projeto permanece, a qualquer momento, em um estado que permite que um novo agente assuma o trabalho. Nenhuma explicação verbal é necessária — apenas observar o conteúdo do repositório já é suficiente para continuar.
+
+- **Tempo até o Primeiro Teste Aprovado (*Time from Start to First Passing Test*)**: O tempo decorrido desde o início do projeto até que o primeiro ponto de funcionalidade passe na verificação. Esta é a principal métrica para medir a eficiência da inicialização.
+
+- **Taxa de Sucesso das Sessões Subsequentes (*Success Rate of Subsequent Sessions*)**: A proporção de sessões posteriores que conseguem executar tarefas com sucesso sem depender de conhecimento implícito. Esta é a melhor medida da qualidade da inicialização.
+
+## Como Fazer a Inicialização da Forma Correta
+
+**Trate a inicialização como uma fase dedicada.** A primeira sessão deve realizar apenas a inicialização — nenhum código de funcionalidade de negócio deve ser implementado. A inicialização deve produzir:
+
+**1. Ambiente executável.** O projeto inicia corretamente, as dependências estão instaladas e não existem problemas de ambiente.
+
+**2. Framework de testes verificável.** Pelo menos um teste de exemplo deve passar, comprovando que o framework de testes está corretamente configurado.
+
+**3. Documento de checklist de prontidão inicial.** Um documento claro informando às sessões subsequentes:
+```markdown
+# Checklist de Prontidão Inicial
+
+## Comandos de Inicialização
+- Instalar dependências: `make setup`
+- Iniciar servidor de desenvolvimento: `make dev`
+- Executar testes: `make test`
+- Verificação completa: `make check`
+
+## Estado Atual
+- Todas as dependências instaladas e travadas
+- Framework de testes configurado (Vitest + React Testing Library)
+- Teste de exemplo aprovado (1/1)
+- Regras de lint configuradas (ESLint + Prettier)
+
+## Estrutura do Projeto
+- src/ — Código-fonte
+- src/components/ — Componentes React
+- src/api/ — Cliente da API
+- tests/ — Arquivos de teste
+```
+
+**4. Decomposição das tarefas.** Divida todo o projeto em uma lista ordenada de tarefas, cada uma com critérios de aceitação claros:
+
+```markdown
+# Decomposição das Tarefas
+
+## Tarefa 1: Fundamentos da Autenticação de Usuários
+- Implementar middleware de autenticação JWT
+- Adicionar endpoints de login e registro
+- Critério de aceitação: todos os testes em `pytest tests/test_auth.py` aprovados
+
+## Tarefa 2: Página de Perfil do Usuário
+- Implementar CRUD do perfil de usuário
+- Adicionar formulário de edição de perfil
+- Critério de aceitação: todos os testes em `pytest tests/test_profile.py` aprovados
+
+## Tarefa 3: Funcionalidade de Busca
+- ...
+```
+
+**5. Commit Git como checkpoint.** Após a conclusão da inicialização, registre um checkpoint limpo em um commit. Todo o trabalho subsequente deve partir desse checkpoint.
+
+**Começando a partir de um template**: Não comece com um diretório vazio. Utilize um template de projeto (*create-react-app*, *fastapi-template*, etc.) para pré-configurar a estrutura padrão de diretórios, a configuração de dependências e o framework de testes. Incorpore as etapas comuns de inicialização ao template, deixando apenas o trabalho de inicialização específico do projeto.
+
+**Critério de conclusão da inicialização**: Não é "quanto código foi escrito", mas sim se as quatro condições do checklist de prontidão inicial foram atendidas: consegue iniciar, consegue executar testes, consegue visualizar o progresso e consegue identificar os próximos passos. Utilize este checklist para validar a inicialização:
+
+```markdown
+## Checklist de Aceitação da Inicialização
+- [ ] `make setup` executa com sucesso a partir do zero
+- [ ] `make test` possui pelo menos um teste aprovado
+- [ ] Uma nova sessão do agente consegue responder "como executar" e "como testar" apenas com base no conteúdo do repositório
+- [ ] Existe um arquivo de decomposição de tarefas com pelo menos 3 tarefas
+- [ ] Tudo está registrado em commits no Git
+```
+
+## Exemplo do Mundo Real
+
+Comparação entre duas abordagens de inicialização para um projeto frontend em React:
+
+**Abordagem mista**: O agente criou simultaneamente a estrutura inicial do projeto e implementou a primeira funcionalidade na sessão 1. Ao final da sessão, o repositório possuía código executável, mas não havia documentação explícita dos comandos de execução e testes, nem arquivo de acompanhamento de progresso, nem decomposição de tarefas. A sessão 2 gastou cerca de 20 minutos inferindo a estrutura do projeto, o framework de testes e o processo de build.
+
+**Inicialização dedicada**: A sessão 1 foi dedicada exclusivamente à inicialização — criação da estrutura de diretórios a partir de um template, configuração do framework de testes (Vitest + React Testing Library), criação e validação de um teste de exemplo, elaboração do checklist de prontidão inicial e do arquivo de decomposição de tarefas, além do commit do checkpoint inicial. O tempo de reconstrução da sessão 2 foi inferior a 3 minutos, permitindo iniciar o trabalho diretamente a partir da lista de tarefas.
+
+Comparação do ciclo completo do projeto: a abordagem mista apresentou um tempo total de reconstrução (somando todas as sessões) cerca de 60% maior do que a abordagem com inicialização dedicada. Os 20 minutos extras investidos na inicialização foram recuperados diversas vezes nas sessões subsequentes. Investir um pouco mais de tempo no início para realizar uma inicialização adequada resulta em maior eficiência ao longo do restante do projeto.
+
+## Principais Conclusões
+
+- Inicialização e implementação possuem objetivos de otimização diferentes — misturá-las apenas prejudica ambas.
+- O resultado da inicialização não é código de negócio, mas infraestrutura: ambiente executável, testes verificáveis, checklist de prontidão inicial e decomposição de tarefas.
+- Valide a inicialização utilizando as quatro condições do checklist de prontidão inicial: consegue iniciar, consegue executar testes, consegue visualizar o progresso e consegue identificar os próximos passos.
+- Começar a partir de um template é superior a começar do zero. Utilize templates de projeto para pré-configurar infraestrutura padronizada.
+- O tempo investido na inicialização é totalmente recuperado nas 3 ou 4 sessões seguintes. Isso não é um custo extra — é um investimento antecipado.
+
+## Leitura Complementar
+
+- [Anthropic: Harnesses eficazes para agentes de longa duração](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [HumanLayer: Harness Engineering para Agentes de Programação](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)
+- [SWE-agent: Interfaces entre Agentes e Computadores](https://github.com/princeton-nlp/SWE-agent)
+
+## Exercícios
+
+1. **Criação de um checklist de prontidão inicial**: Escreva um checklist de prontidão inicial completo para um projeto que você esteja desenvolvendo. Em seguida, abra uma sessão totalmente nova do agente, mostre apenas o conteúdo do repositório (sem qualquer contexto verbal) e peça para ele iniciar o projeto, executar os testes e compreender o progresso atual. Registre todos os problemas encontrados — cada um deles corresponde a uma cláusula ausente no seu checklist de prontidão inicial.
+
+2. **Experimento de comparação**: Escolha um novo projeto de complexidade moderada. Abordagem A: permita que o agente realize a inicialização e a primeira implementação simultaneamente. Abordagem B: dedique uma sessão inteira à inicialização e inicie a implementação apenas na sessão 2. Após 4 sessões, compare o tempo até o primeiro teste aprovado, o custo de reconstrução e a taxa de conclusão de funcionalidades.
+
+3. **Checklist de aceitação da inicialização**: Desenvolva um checklist de aceitação da inicialização para o seu projeto. Faça com que uma nova sessão do agente execute cada item do checklist e registre quais itens passaram e quais falharam. Os itens que falharem indicam exatamente onde o seu *harness* precisa ser fortalecido.
\ No newline at end of file