Harness Engineering

Uma terça-feira, 3 da manhã

3 da manhã de uma terça-feira. O engenheiro de plantão de uma equipe acorda com um alerta do PagerDuty.

O custo de API disparou. Olhando o painel: mais de US$ 400 queimados na última hora. Investigando, descobre-se que um agente de IA implantado no dia anterior vinha martelando uma API instável com retries. A cada erro, voltava ao loop “deixa eu tentar de novo,” e ficou assim até de manhã.

O agente não era o problema. O modelo estava bem. O prompt estava bem escrito. O que faltava era um harness. Disseram ao agente “corra,” mas nunca lhe deram freios nem volante.

Esta história não é incomum. Há uma frase que circula no campo:

“The model is commodity. The harness is moat.”

Quando um agente que funcionou perfeitamente na demo quebra em produção, quase sempre é problema de harness.

Em fevereiro de 2026, a OpenAI publicou um post no blog: “Harness engineering: leveraging Codex in an agent-first world.”

A história é a seguinte: por cinco meses, uma equipe de engenharia não escreveu uma única linha de código à mão. Construiu uma aplicação em produção com mais de um milhão de linhas usando apenas agentes Codex. Tempo de build: um décimo do que seria escrever manualmente.

“Humanos guiam. Agentes executam.”

Engenheiros não tiveram seus empregos roubados — a definição do trabalho mudou.

Esse post acendeu a chama. Depois veio o relatório da “tempestade de retries de US$ 47.000” de um fim de semana de fevereiro de 2026. Um agente de enriquecimento de dados interpretou um código de erro de API como “tente novamente com parâmetros diferentes” e disparou 2,3 milhões de chamadas. Segunda de manhã, os engenheiros voltaram a uma fatura de US$ 47.000. Bom que o agente trabalhou no fim de semana, mas nem tanto quando a entrega é zero e a fatura aparece. Dias depois, a Anthropic publicou dois guias de design de harness. A LangChain definiu “Agent = Model + Harness.” Martin Fowler escreveu um comentário. Um artigo acadêmico foi para o arXiv.

2024 foi o ano da Engenharia de Prompt. A era de polir “o que perguntar à IA.”

2025 foi o ano da Engenharia de Contexto. Andrej Karpathy disse “The hottest new programming language is English,” e o trabalho passou a desenhar “o que mostrar à IA.”

2026: o palco se amplia. Harness Engineering: “como projetar todo o ambiente em que o agente opera?”

Mas o termo é interpretado de forma um pouco diferente dependendo de quem escreve. OpenAI e Anthropic enfatizam coisas diferentes. LangChain e Martin Fowler atacam de ângulos diferentes. Os artigos acadêmicos vêm de outra direção ainda.

Este livro apresenta, de forma sistemática, uma visão geral de Harness Engineering.

• A relação entre as três práticas de engenharia (Prompt / Context / Harness)
• Como os principais players (OpenAI / Anthropic / LangChain / Martin Fowler / academia) divergem na interpretação
• A anatomia dos seis componentes
• Onde fica em relação a ideias próximas (Vibe Coding / Spec Coding / Agent Frameworks)
• Estudos de caso práticos da comunidade japonesa
• Para onde tudo isso está indo

É ao mesmo tempo um livro de organização conceitual e um guia prático que você pode usar amanhã. O objetivo: quando alguém perguntar “tá bom, mas o que é um harness?”, você entrega este livro e considera a tarefa cumprida.

Para quem é este livro

• Engenheiros que começaram a usar agentes de IA (Claude Code, GitHub Copilot, Cursor, etc.)
• Quem escreveu um AGENTS.md ou CLAUDE.md mas não tem certeza se acertou
• Quem conhece Engenharia de Prompt mas está ouvindo “Harness Engineering” pela primeira vez
• Gerentes e tech leads que querem trazer agentes de IA para o time

O único pré-requisito é o básico de Engenharia de Prompt — ter ouvido falar de Few-shot e Chain-of-Thought já é suficiente.

Como ler este livro

Você pode ler de capa a capa, ou pular para os capítulos que interessarem. Dito isso, três capítulos valem a pena de qualquer forma:

• Capítulo 1: entender como as três práticas de engenharia se relacionam (o mapa do território)
• Capítulo 8: aprender os seis componentes (o esqueleto da prática)
• Capítulo 11: aprender a escrever AGENTS.md (algo que você usa amanhã)

Por que 40% falham

Em 2026, 40% dos projetos de agentes de IA falham (pesquisa Company of Agents).

O que está por trás das falhas? Modelo errado? Prompts ruins?

Nenhum dos dois. “A diferença entre sucesso e fracasso não é o modelo.” Essa é a visão dominante entre as equipes que já colocaram agentes em produção.

Uma pesquisa no Y Combinator DevTool Day (março de 2026) entrevistou CTOs e CPOs e encontrou um fator comum nos projetos que falharam: ausência de harness. Nunca desenharam o ambiente em que o agente opera.

75% das empresas enterprise da YC já têm agentes de codificação implantados. Ainda assim, muitos batem na mesma parede: “funciona na demo, quebra em produção.”

Em março de 2026, a Linear declarou “issue tracking is dead.” A ideia: alimentar o contexto da issue diretamente em um agente de codificação e humanos não precisam mais gerenciar tickets. Workflows enterprise estão sendo redesenhados partindo do princípio de que agentes são o padrão.

Colocar agentes em produção neste ponto de inflexão sem entender o harness é como pegar a estrada em alta velocidade sem cinto de segurança. Dá para ir rápido, mas você sai voando na primeira curva.

Linha do tempo

O que torna as três diferentes

Engenharia de Prompt

Sujeito: Um único prompt (texto de entrada)

Otimiza “o que perguntar à IA e como.” Few-shot, Chain-of-Thought, ReAct. A arte de maximizar a precisão em uma única troca.

Engenharia de Contexto

Sujeito: Tudo o que se alimenta na IA (system prompt + RAG + definições de ferramentas + memória)

Nas palavras de Andrej Karpathy, “it is a lot more than just the prompt itself.” Como o prompt único passou a não resolver vários casos, surgiu a necessidade de projetar a janela de contexto inteira, montada dinamicamente.

Philip Schmidt (ex-Hugging Face, Google DeepMind) argumenta que “a nova habilidade para usar IA não é prompting. É engenharia de contexto.”

Harness Engineering

Sujeito: Todo o ambiente operacional (contexto + restrições + ferramentas + ciclo de vida + feedback + monitoramento)

A definição de Louis Bouchard é a mais concisa:

Engenharia de Contexto é “o que você envia ao modelo.” Harness Engineering é “como o todo funciona.”

Nem o prompt, nem o contexto. O ambiente ao redor do modelo. Se a analogia é cozinha, o prompt é a receita, o contexto são os ingredientes, e o harness é a cozinha em si.

Uma estrutura aninhada

Os três não são conceitos concorrentes. Aninham-se um dentro do outro.

O artigo da SmartScope coloca de forma clara:

Harness ⊇ Contexto ⊇ Prompt

Um artigo japonês da Elephancube usa uma metáfora certeira:

Ao construir uma casa, as paredes não ficam de pé sem fundação, e o teto não se sustenta sem paredes. Bons prompts fazem o desenho de contexto funcionar, e bom desenho de contexto faz o harness funcionar.

”Substituído” ou “estratificado”?

Aqui as interpretações divergem.

Campo da substituição:

A Data Science Dojo intitulou um artigo “Why Harness Engineering Is Replacing Prompt Engineering.” O argumento: agentes em 2025-2026 operam em ambientes para os quais prompts e contexto nunca foram desenhados.

Campo da estratificação:

A AnyTech (Medium) escreve: “Não há diferença essencial entre os três. A mudança de terminologia só reflete que LLMs e agentes passaram a fazer mais coisas.” Visão tranquilizadora. Você não precisa jogar fora tudo o que sabia toda vez que aparece um novo buzzword.

Posição deste livro: campo da estratificação. A Engenharia de Prompt continua importante. Só não basta sozinha em um número crescente de casos. Harness Engineering engloba prompt e contexto e ainda adiciona uma camada externa de restrições, gestão de ciclo de vida e loops de feedback.

Por que agora?

Um texto da WonderLab no DEV.to coloca bem:

O timing não é coincidência. Em 2025, agentes de IA passaram de “demos legais” para “ferramentas de produtividade reais.”

Quando agentes rodam autonomamente por longos períodos, otimizar um prompt não consegue mantê-los sob controle. O desenho de contexto sozinho também não basta. É preciso desenhar todo o ambiente.

Essa urgência foi o que deu origem a Harness Engineering.

O que “funciona na demo, quebra em produção” realmente significa

A harnessengineering.academy coloca assim:

Não implante agentes de IA sem um harness, da mesma forma que você não rodaria software diretamente em uma CPU sem um SO.

Uma CPU computa. Mas, sem um SO, não dá para gerenciar memória, agendar processos ou controlar I/O. Igual com modelos: um modelo gera texto. Mas, sem um harness, não dá para gerenciar contexto, controlar ferramentas ou lidar com falhas.

Nove em cada dez agentes que funcionam na demo e quebram em produção têm problema de harness. Para ser específico:

• Demo: ambiente controlado. Perguntas chegam no fluxo esperado. APIs funcionam. Contexto curto.
• Produção: caos. Entradas inesperadas. APIs caem. Contexto explode. Race conditions de execução paralela.

Um harness é a almofada que absorve o caos da produção. A demo é o showroom; a produção é a estrada aberta. Saber se um carro que anda perfeitamente no showroom sobrevive à estrada é outra discussão.

De onde vem a palavra “harness”

A NxCode explica a origem do termo:

O termo é emprestado de equipamento equestre. Um cavalo é poderoso e veloz, mas, sem rédeas, sela e freio, vai aonde quiser. O modelo de IA é o cavalo. O harness é tudo que canaliza essa força para trabalho produtivo.

Um artigo no note (kazu_t) usa uma analogia SO vs código de aplicação:

Se o prompt é código de aplicação, o harness é o sistema operacional.

Aakash Gupta (Medium) coloca de forma ainda mais simples:

O modelo é o motor. O harness é o carro. O melhor motor do mundo não vai a lugar nenhum sem direção e freios.

Distinguindo de “test harness”

A Parallel.ai levanta uma ressalva importante:

Não confunda com test harness (um termo antigo da engenharia de software). Test harness é um framework que entrega entradas e checa saídas automaticamente. Agent harness é todo o ambiente operacional de uma IA.

Pesquisar o termo traz resultados sobre fiação elétrica e a plataforma de CI/CD Harness.io. Harness, neste livro, refere-se ao ambiente de controle para agentes de IA.

Comparando as definições

Vamos colocar as definições lado a lado.

OpenAI

“Humanos guiam. Agentes executam. Ao impor essa restrição deliberadamente, construímos o que era preciso para elevar a velocidade de engenharia em ordens de magnitude.”

Harness = o ambiente em que agentes escrevem código de forma confiável.

Anthropic

“Suporte a múltiplas janelas de contexto, configuração do ambiente no contexto inicial, gestão de contexto e composição de subagentes.”

Harness = um sistema de controle estável para agentes de execução prolongada.

LangChain

“Agent = Model + Harness. O modelo tem a inteligência; o harness torna essa inteligência útil.”

Harness = a casca externa que converte inteligência do modelo em trabalho útil.

Martin Fowler

“Linguagens fortemente tipadas transformam checagens de tipos em sensores. Fronteiras de módulo fornecem regras de restrição arquitetural. Frameworks como o Spring abstraem detalhes em que o agente não precisa pensar, elevando implicitamente a taxa de sucesso do agente.”

Harness = a soma de restrições implícitas e explícitas que uma base de código carrega.

Louis Bouchard

“Pare de dizer ‘o modelo é burro.’ Diga ‘meu sistema tolerou esse modo de falha.’”

Harness = um ambiente que não tolera modos de falha.

No que todos concordam

A redação difere, mas todos concordam em alguns pontos.

1. O harness está fora do modelo: não se trata de mexer em parâmetros do modelo
2. Restrições são impostas, não pedidas: o sistema não avança a menos que sejam atendidas
3. Loops de feedback são obrigatórios: avalie saídas, melhore o ambiente continuamente
4. O papel humano muda: de escrever código para desenhar o ambiente

A definição operacional deste livro de Harness Engineering

Combinando as definições acima, este livro adota:

Harness Engineering é a disciplina de projetar todo o ambiente em que agentes de IA operam de forma autônoma por longos períodos. Inclui gestão de contexto, imposição de restrições, gestão de ciclo de vida, loops de feedback, monitoramento e fronteiras de segurança.

O que dá errado sem um harness

O valor de um harness fica claro quando se olha o que falha sem ele.

Um harness transforma “pedidos” em “mecanismos.” Falar “por favor, escreva testes” 100 vezes é menos confiável do que construir uma vez o sistema para que commits sem testes não aconteçam. É a mesma lógica de gerenciar pessoas, no fundo.

A diferença decisiva em relação à Engenharia de Prompt

A Engenharia de Prompt otimiza “uma troca.” Harness Engineering otimiza “100 trocas.”

Para uma única troca, um bom prompt basta. Mas, quando um agente codifica o dia inteiro, o efeito do primeiro prompt já enfraqueceu na 50ª troca. O contexto explode, as instruções iniciais escorregam para um passado distante, e o agente começa a se comportar diferente do começo.

Um harness resolve isso. Se um prompt é “o primeiro empurrão”, um harness é “a gravidade que sempre puxa.”

No próximo capítulo, vamos aprofundar em detalhe a interpretação de cada autor.