Curso de Harness Engineering (pela lente do Alembic) · Visual Course

O que é harness engineering

Ao fim desta lição você vai seguir uma única unidade de trabalho atravessando o Alembic — pedido → roteamento por tier → adapter Result → gates → custo+span → park ou ship — e entender por que o harness em volta do modelo, e não o prompt, é o que torna o sistema confiável.

Leia primeiro (fonte primária)

walkinglabs — "learn-harness-engineering" (PT-BR) + o HARNESS-MAP.md deste curso

Esta lição destila o resumo executivo do HARNESS-MAP.md (o mapeamento grounded dos 23 princípios × Alembic) e o ancora no único fato que tudo gira em torno: a cintura estreita (packages/contracts/src/model.ts + packages/adapters/src/cliproxyapi.ts). Tudo aqui é citado de arquivo real — nada é inventado.

Leia a versão simples, ou abra a camada técnica em qualquer seção.

O que você vai conseguir fazer

Distinguir harness engineering de prompt engineering — e dizer por que a primeira é o que "embarca LLM como infraestrutura, não demo".
Nomear as três camadas dos Self-Learning Agents (Model delegada / Harness possuída / Context composta) e o sinal do usuário que falta.
Ler as três etiquetas honestas do mapa — owned / delegated / gap — e saber por que delegar não é um buraco.
Apontar a cintura estreita (ModelAdapter + Result) e explicar por que ela é a dobradiça que decide o que o Alembic possui vs delega.

Suposições tolas (o que presumimos de você — bem pouco)

Você já conversou com um assistente de IA por texto e sabe que ele recebe uma mensagem e devolve uma resposta.
Você sabe ler um pseudocódigo simples. Não precisa saber TypeScript — vamos traduzir cada trecho.
Você não precisa saber o que é KV cache, tier, ou circuit breaker. A gente constrói esses termos do zero ao longo do curso.

A grande ideia

Um prompt genial é um motor de corrida sem carro: potente, e inútil sozinho. Harness engineering é construir o carro — o chassi, os freios, os instrumentos, o limite de combustível — em volta do motor, para que ele chegue ao destino de forma confiável, toda vez.

Prompt engineering ajusta uma string: a frase que você manda ao modelo. Harness engineering constrói o sistema em volta do modelo — roteamento (qual modelo chamar), retries (o que fazer quando falha), gates (provar que deu certo antes de seguir), memória, observabilidade e custo — para que o conjunto todo seja confiável. O Alembic é um harness: um monorepo cujo único propósito é ser essa carroceria de confiabilidade ao redor de modelos hospedados.

Pense como… a diferença entre escrever uma receita perfeita (prompt) e montar a cozinha de um restaurante que serve mil pratos por noite sem intoxicar ninguém (harness): estoque, fogões redundantes, fila de pedidos, controle de temperatura, descarte do que estragou. A analogia quebra num ponto: na cozinha o chef confia no fogão; aqui o harness assume que o modelo vai errar — e se desenha em volta dessa certeza.

Por baixo do capô

No HARNESS-MAP.md, o princípio nº 1 ("harness eng vs prompt eng") tem status owned com a nota: "this is the entire repo… the README's own framing: ship LLM systems as reliable infrastructure not demos." Os prompts em si são um pacote-folha de fragmentos puros (packages/prompts/src/fragments.ts) — deliberadamente a menor peça. Toda a massa de código (@alembic/harness, @alembic/coda dos gates, @alembic/adapters do roteamento, @alembic/vm do determinismo, @alembic/swarm da orquestração) é a carroceria, não o motor.

O número que dá a escala: o repo tem 27 pacotes + 1 app e 1364 testes em 102 PRs (HARNESS-MAP.md, cabeçalho). Quase nada disso é "o prompt". É tudo o que mantém o prompt confiável em produção.

O lema do repo: "ship LLM systems as reliable infrastructure, not demos". O harness é o que move o sistema da coluna da esquerda para a da direita.

princípios de harness mapeados × Alembic

pacotes no monorepo (a carroceria)

testes — confiabilidade provada, não prometida

À esquerda, um único ponto de ajuste. À direita, o sistema inteiro do Alembic — e o prompt é só o tijolinho lá embaixo.

A fatia clay à esquerda é o prompt; o resto da barra é o harness. A proporção é a tese do curso em uma imagem.

Guarde istoPrompt = a frase. Harness = tudo o que faz a frase virar um sistema que não te acorda às 3h da manhã. O resto do curso é só detalhar esse "tudo".

A clean explanatory diagram contrasting two things side by side, separated by a vertical divider. On the LEFT, labeled 'PROMPT', a single small rounded card holding one short line — A clean explanatory diagram contrasting two things side by side, separated by a vertical divider. On the LEFT,

Em uma imagem: a unidade de trabalho

Este é o único exemplo do curso inteiro. Toda lição abre um pedaço deste caminho. Acompanhe uma unidade de trabalho (digamos: "extraia os fatos desta petição") da entrada até o destino. Cada estação é uma peça do harness que vamos estudar.

Leia da esquerda → direita. Cada estação vira uma lição. Esta é a unidade de trabalho — não troque de exemplo, aprofunde-o.

Faça sua aposta antes de seguir

Das seis estações acima (pedido, tier routing, adapter, gates, custo+span, park/ship), quantas o Alembic constrói em TypeScript e quantas ele empurra para uma camada de baixo (o gateway de inferência)?

Praticamente todas as seis estações são possuídas pelo Alembic — elas são orquestração. O que ele empurra para baixo é o que acontece dentro da chamada de modelo (gerar os tokens em si): KV cache, batching, quantização. Essa fronteira — entre o que o harness possui e o que ele delega — é o coração da próxima seção.

A moldura: três camadas + o sinal que falta

A imagem que organiza o curso inteiro é a dos Self-Learning Agents: um agente que se auto-melhora se decompõe em três camadas — e uma quarta peça que quase ninguém constrói.

Model (delegada) sobre Harness (a casa do Alembic) sobre Context (parcial). A peça pontilhada — o veredito humano realimentando o sistema — é o gap estratégico, o clímax do curso.

Model — delegada. Os pesos e a inferência crua. O Alembic não treina nem serve modelo: ele fala com um gateway (cliproxyapi) e modelos locais MLX. Ele possui a visão de registry/roteamento/preço dos modelos, não os modelos.

Harness — possuída. O território do Alembic: gates (@alembic/coda), routing+breaker+retry (@alembic/adapters), VM de determinismo (@alembic/vm), swarm, OTEL (@alembic/harness), budget (@alembic/etl).

Context — parcial. O pack de contexto de 8 camadas + memória multi-store (@alembic/hermes). Mas a memória é composta + truncada por budget, não recuperada por similaridade — o lado de leitura vetorial é um gap (lição 0006).

O sinal do usuário — o buraco honesto. Toda camada observa o agente; ninguém observa o usuário. O veredito humano (aprovar/rejeitar em T4) não realimenta routing/prompt/memória. É a fronteira entre um harness confiável e um auto-aprendiz.

As caixas verdes existem hoje. A seta vermelha pontilhada — levar o veredito humano de volta para o sistema — é o gap. Fechá-la é o que transformaria "harness confiável" em "harness auto-aprendiz".

Nota de honestidadeO Alembic já tem as duas pontas do fio do loop de aprendizado: um caminho de write-back (grava a saída do modelo na memória, hermes A3b) e um caminho de veredito humano (T4 → approvals.jsonl). O que falta é conectar o veredito humano à auto-melhoria. Por isso é gap, não vaporware: a fiação existe, só não está plugada.

A left-to-right horizontal pipeline of one work item flowing through six labeled stations connected by arrows: a small token labeled 'request' enters, passes through 'tier routing' — A left-to-right horizontal pipeline of one work item flowing through six labeled stations connected by arrows:

owned / delegated / gap — e a cintura como dobradiça

O HARNESS-MAP.md etiqueta cada um dos 23 princípios com uma de três palavras. Aprenda essas três palavras agora — elas são a língua do curso:

owned · possuído

A camada TypeScript do Alembic implementa isto. Ex.: o roteamento por tier, os gates, a VM de determinismo, a contabilidade de custo.

delegated · delegado

O Alembic conscientemente empurra para baixo da cintura — para o gateway ou os modelos MLX locais. Ex.: KV cache, quantização, batching. Não é um buraco — é escopo de design.

gap · lacuna

Ainda não construído — vira roadmap. Ex.: retrieval vetorial, isolamento multi-tenant, o loop do sinal do usuário.

por que isso importa

Um curso honesto não finge que tudo está pronto. Saber onde a infra-confiável para e o auto-aprendizado começa é o que esse mapa entrega de mais valioso.

Olive = possuído, slate = delegado, rust = lacuna. Toda a honestidade do curso cabe nessas três cores.

A cintura estreita é a dobradiça

Por que ~7 dos 23 princípios são "delegated" e não "gap"? Por causa de uma única decisão de arquitetura: a cintura estreita. Toda chamada de modelo no Alembic passa por um ponto fino — a interface ModelAdapter — e o adapter padrão é um proxy HTTP OpenAI-compatível puro. Ele não tem cache de tokens, nem escalonador de lote, nem kernel de atenção. Ele empurra tudo isso para baixo da cintura.

Pense como… um servidor de aplicação que não gerencia o cache de páginas do disco — ele delega isso ao kernel do sistema operacional. O Alembic não está "faltando" gerência de KV cache; ele a empurrou para baixo da cintura, do mesmo jeito. A dobradiça (a cintura) é o que separa "minha responsabilidade" de "responsabilidade da camada de baixo".

A ampulheta: muita coisa em cima (o harness), muita em baixo (a inferência), e um único ponto fino no meio por onde tudo passa. Esse ponto é o ModelAdapter.

Estação da unidade	Camada	Etiqueta	Quem faz
tier routing (qual modelo)	Harness	owned	`contracts/registry.ts`
adapter Result (a cintura)	Harness	owned	`adapters/adapter-core.ts`
gerar os tokens (atenção, KV cache)	Model	delegated	gateway + MLX
gates (Proof, verifier)	Harness	owned	`coda/proof.ts`
custo + span	Harness	owned	`adapters/cost.ts`, `harness/otel.ts`
recuperar memória por similaridade	Context	gap	roadmap (lição 0006)

Erro comumConfundir "delegated" com "incompleto". O Alembic não está faltando um cache de KV — ele decidiu, de propósito, que isso é trabalho da camada de baixo. Tratar uma decisão de design como um bug é o erro nº 1 de quem lê o mapa rápido demais.

A primeira estação por dentro: o tier ladder

"tier routing" significa escolher o modelo pela faixa de risco da unidade. Mais risco → modelo mais forte (e mais caro), até o topo: T4, onde a unidade para e espera um humano. Na dúvida, o Alembic faz park (o default é T4). Você vai aprofundar isto na lição 0002 — aqui só veja o formato da escada.

Cada degrau é mais capaz e mais caro; o topo não é um modelo, é uma pessoa. "Na dúvida, park" porque o tier default é o T4.

O selo offline↔online: um campo só

Como o mesmo código roda de graça (offline, determinístico) ou contra o gateway real? A troca é um campo: o adapterId. 'local' = o caminho $0 offline; 'cliproxyapi' = o gateway. Não há dois caminhos de código — há um seletor.

O seam offline/online não é um if espalhado pelo código — é um único campo na cintura. Por isso "offline-por-padrão" é barato de manter.

No código: a cintura, em duas peças

A cintura inteira são duas coisas: o contrato (a interface que promete "nunca lança exceção, sempre devolve um Result") e o adapter padrão (um proxy fetch puro). Veja as duas peças reais, sem edição.

packages/contracts/src/model.ts — o contrato da cintura

// INVARIANTE: ModelAdapter.run NUNCA lança.
// Qualquer erro — rede, timeout, quota, bug — vira um
// ModelRunFailure. Quem chama nunca precisa de try/catch:
// ramifica em result.ok.
export interface ModelAdapter {
  readonly id: string;            // 'cliproxyapi' | 'local'
  readonly capabilities?: ModelCapabilities;
  run(input: ModelRunInput): Promise<ModelRunResult>;
}

// O resultado é uma união discriminada em `ok`:
// sucesso E falha são valores de primeira classe.
const r = await adapter.run(input);
if (r.ok) usar(r.text); else tratar(r.error.code);

packages/adapters/src/cliproxyapi.ts — o adapter padrão é um proxy puro

// cliproxyapi — o adapter-gateway PADRÃO.
// Fala o formato OpenAI-compatível por `fetch` a um
// proxy local (http://127.0.0.1:8317). Sem cache de
// tokens, sem escalonador de lote, sem kernel de atenção.
const attempt = (input: ModelRunInput) =>
  callOpenAiCompatible(
    { adapterId: 'cliproxyapi', baseUrl, apiKey, fetchImpl },
    input,
    Date.now(),
  );

return {
  id: 'cliproxyapi',
  capabilities: { streaming: true, toolUse: true, vision: true },
  run: (input) => runWithGuards('cliproxyapi', attempt, input, runtime),
};

Repare no runWithGuards: é ele que envolve o attempt (a chamada crua) com as quatro garantias — validar com Zod, nunca lançar, circuit breaker, retry. É a próxima lição inteira. Aqui só plante a semente: a chamada crua é minúscula; a confiabilidade vem da carroceria em volta dela.

Sucesso e falha são dois ramos do mesmo valor. Quem chama faz if (r.ok) — nunca try/catch. É o que mantém o controle de fluxo uniforme.

A mesma ideia da seção 1, agora concreta: a chamada de modelo é a última caixinha; as quatro anteriores são o harness. (Detalhe na lição 0002.)

Acesse você mesmo

No repo /Users/acf/Documents/Projects/appfy/alembic, abra packages/contracts/src/model.ts (o invariante never-throws está documentado nas linhas ~128–151) e packages/adapters/src/cliproxyapi.ts (o attempt e o runWithGuards nas linhas ~47–77). O runWithGuards em si vive em packages/adapters/src/adapter-core.ts e enumera, em comentário, a ordem das 4 garantias (linhas ~23–36).

O HARNESS-MAP.md chama isto de "the one fact the whole map hinges on: the narrow waist" e cita exatamente cliproxyapi.ts:47-58 como prova de que o adapter é um proxy HTTP puro.

Exemplo resolvido — siga a unidade pela cintura

A unidade "extraia os fatos desta petição" chega. O router escolhe um modelId (próxima lição). O harness monta um ModelRunInput validável.

A chamada entra em adapter.run(input) — o ponto fino. O runWithGuards valida o input com Zod. Inválido? Devolve Result de falha CLIENT_ERROR. Não lança.

Válido: o attempt faz um fetch ao gateway. Lá embaixo (delegado) o gateway gera os tokens — KV cache, atenção, tudo invisível para o TypeScript.

Volta um ModelRunResult. r.ok === true → texto + usage de tokens (vira custo + span). r.ok === false → error.code + retryable, e o harness decide retry/escalar/park.

Agora você: em qual passo o Alembic delega? (Resposta: o passo 3, dentro do fetch — a geração dos tokens. Todo o resto é possuído.)

Tudo à esquerda da linha vermelha é código do Alembic; tudo à direita é a camada de baixo. O fetch é o último passo possuído — ele é a própria cintura em ação.

An hourglass-shaped architecture diagram explaining a narrow waist. A wide trapezoid at the TOP labeled 'HARNESS — owned' filled with several small tags (routing, gates, retry, cos — An hourglass-shaped architecture diagram explaining a narrow waist. A wide trapezoid at the TOP labeled 'HARNE

Experimente: o explorador owned / delegated / gap

Clique nas três etiquetas. A pilha de camadas acende a parte correspondente e o painel mostra um exemplo real do HARNESS-MAP.md — incluindo onde no código ele mora. Use isto para fixar a língua do curso: o que o Alembic possui, o que delega, e o que ainda é roadmap.

A camada que a etiqueta toca acende; as outras esmaecem.

owned

Roteamento por tier

O Alembic escolhe o modelo mais barato da faixa de risco com pickCheapestForTier — e se recusa a substituir um modelo silenciosamente (devolve err). É a camada Harness implementada em TypeScript.

contracts/src/registry.ts · adapters/src/router.ts

DicaNote que owned e gap acendem a mesma camada às vezes (Harness possui o routing; Context tem o gap de retrieval). A etiqueta não é sobre qual camada — é sobre se já existe. Essa é a sutileza que separa quem leu o mapa de quem entendeu o mapa.

Você é o aluno e também o professor: pergunte-se "qual estação da minha unidade de trabalho é delegated?" — e se a resposta não for óbvia, é sinal de que a próxima lição vai te ajudar. A seguir (0002): abrimos a cintura por dentro — Result never-throws, o core guardado (Zod → breaker → retry) e o router que se recusa a trocar de modelo em silêncio.

Recapitulando em 6 slides

A virada de chave

Não é o prompt. É o harness.

Prompt engineering ajusta uma string. Harness engineering constrói o sistema em volta do modelo — e é o que embarca LLM como infraestrutura, não demo.

O exemplo do curso

Uma unidade de trabalho

pedido → tier routing → adapter Result → gates → custo+span → park ou ship. Toda lição abre uma estação desse caminho.

A moldura

Três camadas + um sinal

Model (delegada) · Harness (possuída) · Context (composta). E a peça que falta: o sinal do usuário — ninguém realimenta o veredito humano.

A língua do mapa

owned · delegated · gap

Implementa (owned), empurra para baixo da cintura (delegated, e isso é bom), ou ainda não tem (gap = roadmap). Honestidade é o valor do curso.

A dobradiça

A cintura estreita

Toda chamada passa por um ponto fino: ModelAdapter. O adapter padrão é um proxy fetch puro — por isso 7 dos 23 princípios são delegated, não gap.

Para a próxima

Abrir a cintura

A lição 0002 entra no runWithGuards: Result never-throws, validação Zod, circuit breaker, retry — e o router que nunca troca de modelo em silêncio.

1 / 6setas ← →

Simples ↔ Técnico: a mesma ideia, duas alturas

Alterne entre a explicação leiga e a precisa. Use a aba "Técnico" quando quiser os nomes reais; a "Simples" quando quiser a intuição.

Em linguagem de gente: o harness é a equipe de apoio em volta de um atleta genial mas imprevisível. Ele decide em qual prova o atleta corre (routing), o que fazer se ele tropeça (retry), confere se o resultado é válido antes de comemorar (gates), anota quanto custou (custo) e filma tudo (spans). O atleta — o modelo — só corre. A inteligência da operação está na equipe.

Com os termos reais: o harness do Alembic é a malha de orquestração em torno do ModelAdapter: pickCheapestForTier (registry) seleciona o modelo; runWithGuards (adapter-core) faz safeParse Zod → circuit breaker → withRetry; a Proof Gate executa unit.proof[] como bash -c fail-closed; o BudgetGuard bloqueia a próxima chamada paga acima do teto; o emissor OTEL dep-free escreve cada evento em spans.jsonl com chaves GenAI semconv. O modelo é uma chamada fetch atrás da cintura.

Cartões de memória

Vire cada cartão (clique, ou Enter/Espaço) e tente responder antes de ver o verso. É prática de recuperação — vale mais que reler.

Definição

Qual a diferença entre prompt e harness engineering?

clique para virar

Prompt ajusta uma string; harness constrói o sistema em volta do modelo (routing, retries, gates, memória, custo, observabilidade) para torná-lo confiável.

Moldura

Quais são as três camadas dos Self-Learning Agents?

clique para virar

Model (delegada), Harness (possuída pelo Alembic), Context (composta). A 4ª peça que falta é o sinal do usuário.

Etiquetas

O que significam owned / delegated / gap?

clique para virar

owned: implementado em TS. delegated: empurrado para baixo da cintura (gateway/MLX) — não é buraco. gap: não construído ainda (roadmap).

Cintura

O que é a "cintura estreita" e por que importa?

clique para virar

A interface ModelAdapter + Result: um ponto fino por onde toda chamada passa. O adapter padrão é um proxy puro — por isso a inferência é delegated.

Invariante

Por que ModelAdapter.run nunca lança exceção?

clique para virar

Para que quem chama nunca precise de try/catch: ramifica em result.ok. Falha é um valor de primeira classe, não uma exceção — controle de fluxo uniforme.

O gap

Por que o "sinal do usuário" é o gap estratégico?

clique para virar

O Alembic grava a saída do modelo e tem o veredito humano (T4), mas não conecta o veredito a routing/prompt/memória. É a fronteira entre harness confiável e auto-aprendiz.

As Dez ideias para levar desta lição

O prompt é o motor; o harness é o carro inteiro. Sem carroceria, o motor não chega a lugar nenhum.
O Alembic é um harness — 27 pacotes cujo trabalho é confiabilidade em volta de modelos hospedados.
O harness se desenha assumindo que o modelo vai errar.
A unidade de trabalho atravessa: pedido → tier routing → adapter Result → gates → custo+span → park/ship.
Três camadas: Model (delegada), Harness (possuída), Context (composta).
A quarta peça — o sinal do usuário — é o loop aberto: ninguém realimenta o veredito humano.
owned = implementado; delegated = empurrado para baixo de propósito; gap = roadmap.
Delegar não é um buraco. KV cache fora do TS é design, igual ao app que delega o cache de disco ao kernel.
A cintura estreita (ModelAdapter + Result) é a dobradiça que decide possuído vs delegado.
O adapter padrão é um proxy fetch puro — sem cache de tokens, sem batching, sem kernel de atenção.

Verifique seu entendimento

Três perguntas. Escolha e leia o porquê de cada opção — o feedback ensina tanto quanto a pergunta.

Checagem cumulativa

Acerte as três para fechar a lição. A pontuação aparece abaixo.

1. Qual frase descreve melhor harness engineering?

(b). Prompt eng é a frase (a). Treinar/quantizar pesos (c) é a camada Model, que o Alembic delega. Harness é a carroceria de confiabilidade em volta — o sistema inteiro.

2. No Alembic, gerar os tokens dentro da chamada (KV cache, atenção) é:

(c). A cintura estreita faz disso uma delegação consciente (como um app delegando o cache de disco ao kernel) — não é um buraco (b) nem código do harness (a). É escopo de design.

3. Por que a "cintura estreita" é chamada de dobradiça do mapa?

(a). Como toda chamada passa por ModelAdapter e o adapter padrão é um proxy puro, é exatamente aí que a fronteira possuído/delegado é decidida. (b) é falso (não há medição de latência por etapa aqui) e (c) descreve o gap do sinal do usuário, não a cintura.

Acertos: 0/3

Em uma frase, para você mesmo: "Harness engineering é ____, e o Alembic possui ____, delega ____ e ainda não tem ____." Se você consegue preencher as quatro lacunas, está pronto para a lição 0002.