Como a OpenAI criou 1 milhão de linhas de código usando apenas agentes: 5 princípios de Harness Engineering

A palavra “harness” tem aparecido com cada vez mais frequência ultimamente. Um artigo de blog publicado pela OpenAI deu finalmente uma definição clara a este conceito. Eis o que os engenheiros realmente precisam de fazer na era dos agentes.

Um harness é o invólucro de ferramentas que permite a um agente de IA atuar no mundo real. Se o modelo de raciocínio é o cérebro, o harness são as mãos e os pés. Ler ficheiros, corrigir código, executar testes, fazer deploy em produção, tudo acontece dentro do harness.

Uma equipa interna da OpenAI partiu de um repositório vazio no final de agosto de 2025 e construiu um produto de um milhão de linhas usando apenas agentes Codex. A condição: nenhum código escrito por humanos. O tempo necessário foi um décimo do desenvolvimento manual. Os cinco princípios descobertos durante este processo são detalhados a seguir.

O conhecimento que o agente não consegue ver não existe

Do ponto de vista do Codex, qualquer informação inacessível em tempo de execução é como se não existisse. Os documentos de planeamento no Google Docs, as decisões de arquitetura acordadas no Slack, o conhecimento tácito guardado na cabeça de alguém, nada disso é visível. É a mesma situação que enfrentaria um novo colaborador que chegasse três meses depois.

Por isso, a equipa transferiu cada decisão para o repositório em forma de markdown, schemas e planos de execução (ExecPlans).

• ExecPlan é um documento de design autocontido definido em PLANS.md
• O critério de aprovação: um iniciante deve conseguir lê-lo e implementar a funcionalidade de ponta a ponta
• Existem casos em que o Codex trabalhou continuamente durante mais de 7 horas com um único prompt
• A estrutura estende o conceito ARCHITECTURE.md do matklad para utilização por agentes

Pergunte “que capacidade falta” em vez de “esforça-te mais”

No início, a velocidade do agente ficou abaixo das expectativas. A causa não era o desempenho do modelo, mas sim um ambiente insuficientemente equipado. A cada falha, a equipa perguntava: “Que capacidade falta e como a tornamos legível e verificável pelo agente?”

• Helpers de concorrência desenvolvidos internamente em vez de bibliotecas externas, com integração a 100% com o OpenTelemetry
• A chamada “tecnologia aborrecida” revela-se favorável para os agentes (pela estabilidade das APIs e alta representação nos dados de treino)

A aplicação mecânica, não a documentação, mantém a consistência do código

Apenas com documentação não foi possível manter a consistência da base de código gerada por agentes. A equipa optou então por aplicar mecanicamente regras invariantes em vez de prescrever os detalhes de implementação. Exigiram parsing nas fronteiras de dados, mas deixaram a escolha da biblioteca ao agente. A arquitetura foi fixada numa estrutura de domínios em camadas, com as direções de dependência verificadas por linters.

• Camadas fixas por domínio de negócio: Providers → Service → Runtime → UI
• Estrutura de preocupações transversais onde Types, Config e Repo são partilhados nos níveis inferiores
• Linters personalizados e testes estruturais que fazem falhar o build imediatamente em caso de violação
• Os próprios linters também foram escritos pelo Codex

Dê olhos ao agente e ele trabalha sozinho durante 6 horas

A equipa ligou o Chrome DevTools Protocol ao runtime do agente, dando ao Codex acesso a snapshots do DOM, capturas de ecrã e navegação. A estrutura compara snapshots antes e depois da tarefa, observa eventos em tempo de execução e aplica correções em ciclo até que tudo fique limpo.

As ferramentas de observabilidade foram ligadas da mesma forma. Por cada git worktree é lançada uma stack de observabilidade temporária que desaparece quando o trabalho termina.

• Victoria Logs (LogQL) e Victoria Metrics (PromQL) permitem ao agente consultar logs e métricas diretamente
• Prompts como “faz o serviço arrancar em menos de 800ms” tornam-se executáveis
• Execuções únicas do Codex mantêm regularmente o foco numa única tarefa durante mais de 6 horas

Dê um mapa, não um manual de 1000 páginas

A gestão de contexto determina a eficácia do agente. Inicialmente, a equipa tentou colocar tudo num único ficheiro AGENTS.md massivo, sem sucesso. O conceito de ARCHITECTURE.md escrito pelo matklad em 2021 provou o seu valor aqui. O princípio: oferecer uma visão panorâmica breve da estrutura do projeto, incluindo apenas o que raramente muda. O mesmo princípio aplica-se aos agentes.

• ARCHITECTURE.md é um mapa do código, não um atlas do código
• Os invariantes arquiteturais são frequentemente expressos na forma de “algo não existe”
• Declarar fronteiras de forma explícita restringe toda a implementação a jusante

Questões ainda em aberto

Mesmo para a equipa Codex, algumas questões permanecem sem resposta. Ninguém sabe se um sistema construído inteiramente por agentes consegue manter a consistência arquitetural ao longo de anos. Como esta framework irá evoluir à medida que os modelos melhoram também é incerto.

Uma coisa é clara: a era de escrever bom código está a terminar, e a era de desenhar bons ambientes começou.