O Que Você Irá Aprender

Este guia aborda a engenharia de harness desde os princípios fundamentais até a implementação prática. Você entenderá o que é, por que a OpenAI apostou seu maior projeto interno nisso, os padrões arquitetônicos específicos que a fazem funcionar e como aplicar esses princípios aos seus próprios fluxos de trabalho de agentes de IA — quer você esteja usando Codex, Claude Code, OpenCode ou qualquer outro sistema de agentes.

Engenharia de Harness: O Guia Completo para Desenvolvimento de Agentes de IA em 2026

Se 2025 foi o ano em que os agentes de IA provaram que podiam escrever código, 2026 é o ano em que aprendemos que o agente não é a parte difícil — o harness é.

A equipe do Codex da OpenAI publicou um post marcante em seu blog em Fevereiro 2026 descrevendo como construíram uma aplicação de produção contendo aproximadamente um milhão de linhas de código onde zero linhas foram escritas por mãos humanas. O segredo não foi um modelo melhor ou um prompt mais inteligente. Foi o sistema que construíram em torno do agente — o harness. Source

Este guia detalha cada princípio, padrão e técnica prática desse experimento e do movimento mais amplo de engenharia de harness que surgiu em torno dele.

Parte 1: O Que É Engenharia de Harness?

A Definição

A engenharia de harness é a disciplina de projetar todo o ambiente — andaimes (scaffolding), loops de feedback, documentação, restrições arquitetônicas e artefatos legíveis por máquina — que permite que agentes de IA de codificação realizem um trabalho confiável e de alta qualidade em escala com intervenção humana mínima.

O termo "harness" vem do equipamento de montaria: rédeas, sela, freio — o conjunto completo de equipamentos para canalizar um animal poderoso, mas imprevisível, na direção certa. Um cavalo descontrolado é perigoso. Um cavalo com harness (encilhado) construiu civilizações. O mesmo se aplica aos agentes de IA. Source

Por Que Surgiu Agora

A mudança de prompt engineering para engenharia de harness reflete um amadurecimento do cenário de desenvolvimento de IA:

Source

A percepção chave que impulsionou essa transição: os agentes tornaram-se capazes o suficiente para que o gargalo mudasse da qualidade do modelo para a qualidade do ambiente. Um modelo de última geração operando em um repositório mal estruturado produz resultados piores do que um modelo medíocre operando em um ambiente bem equipado com um harness.

Parte 2: O Experimento Codex da OpenAI

A Escala

Em um experimento interno de cinco meses, os engenheiros da OpenAI construíram e lançaram um produto beta contendo cerca de um milhão de linhas de código. O repositório abrange lógica de aplicação, infraestrutura, ferramentas, documentação e utilitários internos para desenvolvedores. Não havia código escrito por humanos pré-existente para ancorar o sistema. Source

A Equipe

O projeto começou com apenas três engenheiros conduzindo o Codex. Ao longo do período de cinco meses, cerca de 1,500 pull requests foram abertos e mesclados. À medida que a equipe cresceu para sete engenheiros, o rendimento aumentou — um resultado contraintuitivo que sugeriu que o próprio harness era o principal multiplicador de produtividade, não a habilidade individual.

A OpenAI estima que eles construíram o sistema em aproximadamente um décimo do tempo que levaria para escrever o código à mão. Source

O Andaime Inicial

O projeto começou com a Codex CLI gerando o andaime (scaffold) inicial usando GPT-5, guiado por um pequeno conjunto de templates existentes:

• Estrutura do repositório e convenções de diretórios
• Configuração de CI/CD
• Formatação de código e regras de linting
• Configuração do gerenciador de pacotes
• Boilerplate do framework da aplicação

A partir dessa semente, tudo o mais cresceu através do desenvolvimento guiado por agentes.

O Problema de Sexta-Feira

No início do experimento, a equipe descobriu um problema crítico: eles estavam gastando toda sexta-feira — 20% do seu tempo de engenharia — limpando o que chamavam de "AI slop". Isso incluía padrões inconsistentes, lógica duplicada, variáveis mal nomeadas e desvio arquitetônico.

Isso não era escalável. A solução foi codificar seus padrões no próprio harness para que os agentes produzissem resultados mais limpos desde o início, e construir sistemas automatizados de limpeza para o desvio residual.

Parte 3: Os Cinco Princípios Fundamentais

Princípio 1: Conhecimento Focado no Repositório

Do ponto de vista do agente, qualquer coisa que ele não possa acessar em contexto enquanto está em execução efetivamente não existe. Conhecimento que vive em Google Docs, threads de chat, mensagens de Slack ou na cabeça das pessoas é invisível para o sistema.

Isso significa que todo o conhecimento deve viver como artefatos versionados e locais ao repositório:

• Código — o artefato primário
• Documentação Markdown — decisões de arquitetura, convenções, guias de integração
• Schemas — contratos de API, esquemas de banco de dados, definições de tipos
• Planos executáveis — detalhamentos de tarefas passo a passo que o agente pode seguir
• Configuração — regras de linter, pipelines de CI, padrões de formatação

A equipe aprendeu que precisava empurrar cada vez mais contexto para o repositório ao longo do tempo. Cada vez que um agente cometia um erro por falta de contexto, a correção não era um prompt melhor — era adicionar esse contexto ao repositório. Source

Implementação prática:

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

Princípio 2: Princípios de Ouro

Princípios de ouro são regras opinativas e mecânicas codificadas diretamente no repositório que mantêm a base de código legível e consistente para futuras execuções de agentes. Eles não são diretrizes aspiracionais — são restrições impostas.

Exemplos do experimento da OpenAI:

1. Preferir pacotes de utilitários compartilhados em vez de helpers manuais — centraliza invariantes para que, quando o comportamento precisar mudar, mude em um só lugar
2. Não sondar dados no estilo YOLO — validar limites ou confiar em SDKs tipados para que os agentes não construam acidentalmente sobre formatos de dados presumidos
3. Um conceito, um arquivo — cada arquivo deve representar um único conceito, facilitando para os agentes encontrarem e modificarem o local correto
4. Explícito sobre implícito — evitar comportamentos mágicos que um agente precisaria de conhecimento tribal para entender

Source

Esses princípios não são apenas documentação. Eles são aplicados por:

• Regras de linter — linters customizados (eles próprios gerados pelo Codex) que sinalizam violações
• Testes estruturais — testes que validam a conformidade arquitetônica
• Portões de CI — pull requests que violam princípios de ouro são automaticamente rejeitados

Princípio 3: Arquitetura em Camadas com Imposição Mecânica

Cada domínio de negócio no projeto da OpenAI é dividido em um conjunto fixo de camadas com direções de dependência estritamente validadas:

Types → Config → Repo → Service → Runtime → UI

As dependências fluem em apenas uma direção. Um componente de UI pode depender de Runtime e Service, mas um Service nunca pode importar da UI. Um Repo pode depender de Config e Types, mas nunca de Service. Source

Essas restrições são impostas mecanicamente:

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

Os testes estruturais validam a conformidade e evitam violações do camadas modulares. Isso não é uma sugestão — é imposto pelo CI. Cada pull request, seja criado por um humano ou por um agente, deve passar nesses testes.

Princípio 4: Garbage Collection Automática

Mesmo com princípios de ouro e imposição estrutural, o código gerado por agentes sofre desvios com o tempo. A equipe da OpenAI resolveu isso implementando uma Garbage Collection automática — tarefas de segundo plano recorrentes que:

1. Escaneiam por desvios dos princípios de ouro em toda a base de código
2. Atualizam notas de qualidade para cada módulo com base em pontuações de conformidade
3. Abrem pull requests de refatoração direcionados que corrigem categorias específicas de desvio

Isso substituiu a "limpeza de sexta-feira" manual por um sistema que roda continuamente. O próprio coletor de lixo é alimentado por agentes Codex, criando um loop de automanutenção. Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Princípio 5: Planos Executáveis

Antes que os agentes escrevam código, eles escrevem planos. Esses planos não são notas informais — são documentos estruturados e executáveis que especificam:

• Objetivo: O que a tarefa realiza
• Arquivos a modificar: Lista explícita de arquivos que o agente tocará
• Dependências: Outras tarefas ou módulos dos quais este trabalho depende
• Critérios de aceitação: Como verificar se o trabalho está concluído
• Restrições: Regras arquitetônicas que não devem ser violadas

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

Os planos vivem no repositório como arquivos markdown, são controlados por versão e podem ser revisados antes da execução — dando aos humanos um ponto de controle entre a intenção e a implementação.

Parte 4: O Loop do Agente Codex

Entender como o loop do agente Codex opera dentro de um harness é essencial para uma engenharia de harness eficaz.

A Arquitetura do Loop

A OpenAI publicou um detalhamento do loop do agente Codex em seu post complementar "Unrolling the Codex agent loop." Source O loop segue este ciclo:

Read Context → Plan → Execute → Validate → Commit (or Retry)

Cada iteração:

1. Ler Contexto: O agente lê arquivos relevantes, documentação, schemas e o plano da tarefa no repositório
2. Planejar: Com base no contexto, o agente determina quais mudanças fazer
3. Executar: O agente escreve ou modifica o código
4. Validar: O harness executa testes, linters e verificações estruturais contra as mudanças
5. Commit ou Tentar Novamente: Se a validação passar, o agente faz o commit. Se falhar, o agente lê a saída do erro e tenta novamente.

O papel do harness é tornar as etapas 1 e 4 o mais ricas em informações possível. Quanto mais contexto o agente lê, melhor seu plano. Quanto mais específico o feedback de validação, mais rápido ele converge para uma solução funcional.

O Harness do App Server

No post "Unlocking the Codex harness: how we built the App Server," a OpenAI descreve a infraestrutura concreta que alimenta o loop do agente. Source O App Server fornece:

• Ambientes de execução isolados (sandboxed) para cada tarefa do agente
• Acesso a ferramentas pré-configuradas (sistema de arquivos, terminal, navegador)
• Injeção automática de contexto a partir de artefatos do repositório
• Feedback de validação em tempo real para que os agentes possam ver falhas de teste instantaneamente

Parte 5: Aplicando a Engenharia de Harness na Sua Equipe

Primeiros Passos: O Harness Mínimo Viável

Você não precisa replicar toda a infraestrutura da OpenAI para se beneficiar da engenharia de harness. Comece com estes elementos fundamentais:

Passo 1: Crie um ARCHITECTURE.md

Documente as regras arquitetônicas do seu projeto em um formato legível por máquina na raiz do seu repositório. Inclua:

• Limites de módulos e dependências permitidas
• Convenções de nomenclatura
• Regras de organização de arquivos
• Requisitos de teste

Este único arquivo melhora drasticamente a qualidade da saída do agente porque os agentes o leem antes de fazer mudanças.

Passo 2: Adicione Testes Estruturais

Escreva testes que validem suas regras arquitetônicas. Esses testes não verificam a lógica de negócio — eles verificam se o código está organizado corretamente:

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

Passo 3: Configure a Validação de CI

Garanta que seu pipeline de CI execute testes estruturais, linters e verificações de tipo em cada pull request — incluindo aqueles criados por agentes. O agente deve ver a mesma saída de validação que um desenvolvedor humano veria.

Passo 4: Escreva Planos de Tarefa Antes da Execução do Agente

Antes de pedir a um agente para implementar uma funcionalidade, escreva um documento de plano estruturado que especifique os arquivos a modificar, as restrições a seguir e os critérios de aceitação. Armazene esses planos no seu repositório.

Passo 5: Configure a Limpeza Automatizada

Implemente um job de CI semanal ou noturno que escaneie sua base de código em busca de desvios dos seus padrões documentados e crie PRs de refatoração focados.

Escolhendo Seu Sistema de Agente

Os princípios da engenharia de harness se aplicam independentemente de qual agente você usa:

O harness vive no seu repositório, não no seu agente. Isso significa que você pode trocar de agentes sem perder seu investimento no harness.

Escalando de Um para Muitos Agentes

O experimento da OpenAI demonstrou que a engenharia de harness permite a execução paralela de agentes. Como o harness impõe limites arquitetônicos, vários agentes podem trabalhar em diferentes partes da base de código simultaneamente sem criar conflitos.

Requisitos principais para a execução paralela de agentes:

1. Propriedade clara de módulos — cada agente trabalha dentro de um limite definido
2. Interfaces tipadas entre módulos — agentes podem codificar contra interfaces sem conhecer detalhes de implementação
3. Prevenção de conflitos de merge — tarefas têm escopo definido para minimizar a sobreposição de arquivos
4. Validação centralizada — todos os agentes submetem ao mesmo pipeline de CI

Parte 6: Armadilhas Comuns e Anti-padrões

Anti-padrão 1: Tratar o Agente como o Harness

O agente não é o harness. O harness é o ambiente em que o agente opera. Pedir a um modelo mais inteligente para compensar um repositório mal estruturado é a abordagem errada. Corrija o ambiente, não o prompt.

Anti-padrão 2: Documentação no Lugar Errado

Se suas decisões arquitetônicas vivem no Confluence, Notion ou Google Docs, os agentes não podem vê-las. A correção é simples, mas requer disciplina: mova toda a documentação relevante para o desenvolvimento para dentro do repositório.

Anti-padrão 3: Limpeza Manual em Vez de Imposição Automatizada

Se você está gastando um tempo significativo limpando código gerado por agentes, você precisa de uma imposição melhor, não de mais sessões de limpeza. Cada tarefa de limpeza recorrente deve se tornar uma regra de linter, um teste estrutural ou um job de refatoração automatizado.

Anti-padrão 4: Excesso de Restrições

Um harness que é rígido demais impede que os agentes encontrem soluções criativas. O objetivo é restringir a arquitetura, não a implementação. Diga aos agentes quais módulos eles podem modificar e quais dependências são permitidas, mas deixe que eles decidam como implementar a lógica dentro desses limites.

Anti-padrão 5: Ignorar o Feedback do Agente

Quando um agente falha repetidamente em certas tarefas, a falha geralmente indica uma lacuna no harness, não uma limitação do agente. Rastreie padrões de falha e use-os para melhorar sua documentação, testes estruturais ou restrições arquitetônicas.

Parte 7: O Futuro da Engenharia de Harness

A Perspectiva de Martin Fowler

Martin Fowler publicou uma análise sobre a engenharia de harness em seu blog, observando que ela representa uma mudança fundamental na forma como as equipes de software operam. A disciplina toma emprestado décadas de melhores práticas de engenharia de software — integração contínua, registros de decisão de arquitetura, injeção de dependência — mas as reaproveita para um mundo guiado por agentes. Source

O Framework HumanLayer

A equipe da HumanLayer publicou sua análise chamando a engenharia de harness de uma "questão de habilidade" (skill issue) — argumentando que a capacidade de projetar harnesses eficazes se tornará o principal diferencial entre equipes de engenharia de alto desempenho e aquelas em dificuldade. Source

O Que Isso Significa para os Desenvolvedores

A engenharia de harness não substitui a habilidade do desenvolvedor — ela a redireciona. Em vez de escrever código, engenheiros seniores projetam os sistemas que permitem que os agentes escrevam código bem. As habilidades que importam mudam da implementação para a arquitetura, da codificação para o design de sistemas, da escrita de testes para o design de frameworks de teste.

Para equipes que constroem aplicações, plataformas como ZBuild já estão incorporando princípios de engenharia de harness em seus fluxos de trabalho de construção de apps. Em vez de exigir que os desenvolvedores projetem seus próprios harnesses do zero, o ZBuild fornece padrões arquitetônicos pré-configurados, gerenciamento de dependências e sistemas de validação que guiam os agentes de IA em direção a resultados de alta qualidade — permitindo que os desenvolvedores foquem em decisões de produto em vez de infraestrutura.

Os Três Horizontes

Olhando para o futuro, a engenharia de harness provavelmente evoluirá através de três fases:

1. Curto prazo (2026): As equipes adotam documentação focada no repositório, testes estruturais e princípios de ouro. O desenvolvimento assistido por agentes torna-se prática padrão para projetos com bons harnesses.

2. Médio prazo (2027): A própria geração de harness torna-se guiada por agentes. Os agentes analisam bases de código existentes e propõem configurações de harness — regras de linter, testes estruturais, limites de dependência — com base nos padrões que observam.

3. Longo prazo (2028+): Os harnesses tornam-se adaptativos. Em vez de regras estáticas, eles evoluem com base nos resultados do código gerado pelos agentes, estreitando automaticamente as restrições em áreas onde os agentes frequentemente produzem erros e relaxando as restrições onde eles são consistentemente bem-sucedidos.

Parte 8: Checklist Prático

Use este checklist para avaliar a maturidade da engenharia de harness da sua equipe:

Fundação (Comece Aqui)

• ARCHITECTURE.md existe na raiz do repositório
• Formatação de código é automatizada (Prettier, Black, gofmt)
• Linting é executado em cada pull request
• Verificação de tipos é imposta (TypeScript strict, mypy, etc.)

Intermediário

• Testes estruturais validam limites de dependência
• Princípios de ouro são documentados e passíveis de imposição mecânica
• Planos de tarefa são escritos antes da execução do agente
• PRs gerados por agentes passam pelo mesmo CI que PRs humanos

Avançado

• Garbage Collection automática é executada em cronograma regular
• Múltiplos agentes podem trabalhar em paralelo sem conflitos
• Padrões de falha dos agentes são rastreados e usados para melhorar o harness
• O próprio harness é controlado por versão e revisado como código

Especialista

• Agentes geram partes do harness (regras de linter, testes estruturais)
• Notas de qualidade são atribuídas automaticamente a cada módulo
• Melhorias no harness são baseadas em dados de taxas de sucesso dos agentes
• A equipe entrega mais código por engenheiro por semana do que antes de adotar agentes

Conclusão

A engenharia de harness não é um modismo. É a evolução natural da engenharia de software em uma era onde os agentes de IA são capazes o suficiente para escrever código de produção, mas precisam de ambientes estruturados para fazê-lo bem. O experimento de um milhão de linhas da OpenAI provou o conceito em escala, e os princípios articulados — conhecimento focado no repositório, princípios de ouro, arquitetura em camadas, Garbage Collection automática e planos executáveis — são aplicáveis a equipes de qualquer tamanho.

As equipes que dominarem a engenharia de harness em 2026 entregarão mais rápido, manterão uma qualidade de código superior e escalarão de forma mais eficaz do que aquelas que tratam os agentes de IA como um autocomplete glorificado. O agente é o cavalo. O harness é o que o torna útil.

Fontes

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote