Aproveitar a engenharia: o Codex num mundo centrado no agente

Nos últimos cinco meses, a nossa equipa tem estado a realizar uma experiência: desenvolver e lançar uma versão beta interna de um produto de software com 0 linhas de código escrito manualmente.

O produto tem utilizadores internos diários e testadores alfa externos. É lançado, implementado, falha e é corrigido. A diferença é que cada linha de código — lógica de aplicação, testes, configuração de CI, documentação, observabilidade e ferramentas internas — foi escrita pelo Codex. Estimamos que o construímos em cerca de 1/10 do tempo que teria sido necessário para escrever o código à mão.

Os humanos conduzem. Os agentes executam.

Escolhemos intencionalmente esta limitação para construir o que era necessário para aumentar a velocidade de engenharia em ordens de grandeza. Tivemos semanas para enviar o que acabou por ser um milhão de linhas de código. Para isso, precisávamos de compreender o que muda quando a principal função de uma equipa de engenharia de software deixa de ser escrever código, mas sim conceber ambientes, especificar intenções e criar circuitos de feedback que permitam aos agentes do Codex realizar um trabalho fiável.

Esta publicação é sobre o que aprendemos ao criar um produto totalmente novo com uma equipa de agentes — o que falhou, o que se compôs e como maximizar o nosso único recurso verdadeiramente escasso: o tempo e a atenção humanos.

O primeiro commit num repositório vazio ocorreu no final de agosto de 2025.

O scaffold inicial — estrutura do repositório, configuração de CI, regras de formatação, configuração do gestor de pacotes e estrutura da aplicação — foi gerado pelo Codex CLI usando o GPT‑5, guiado por um pequeno conjunto de modelos existentes. Até o ficheiro AGENTS.md inicial, que orienta os agentes sobre como trabalhar no repositório, foi escrito pelo Codex.

Não havia nenhum código pré-existente escrito por humanos para ancorar o sistema. Desde o início, o repositório foi moldado pelo agente.

Cinco meses mais tarde, o repositório contém cerca de um milhão de linhas de código em lógica de aplicações, infraestruturas, ferramentas, documentação e utilitários internos para programadores. Durante esse período, foram abertos e integrados aproximadamente 1500 pull requests, com uma pequena equipa de apenas três engenheiros a dirigir o Codex. Isto traduz-se numa taxa de processamento média de 3,5 PRs por engenheiro por dia e, surpreendentemente, a taxa de processamento aumentou à medida que a equipa cresceu, sendo agora constituída por sete engenheiros. Importa salientar que isto não foi uma produção sem propósito: o produto tem sido utilizado por centenas de utilizadores internamente, incluindo utilizadores avançados que o usam diariamente.

Durante todo o processo de desenvolvimento, os humanos nunca contribuíram diretamente com qualquer código. Esta tornou-se uma filosofia fundamental para a equipa: não escrever código manualmente.

A falta de codificação prática por humanos introduziu um tipo diferente de trabalho de engenharia, centrado em sistemas, scaffolding e alavancagem.

O progresso inicial foi mais lento do que esperávamos, não porque o Codex fosse incapaz, mas porque o ambiente era pouco específico. O agente não dispunha das ferramentas, das abstrações e da estrutura interna necessárias para progredir em direção a objetivos de alto nível. A principal tarefa da nossa equipa de engenharia passou a ser capacitar os agentes para realizarem trabalho útil.

Na prática, isto significava trabalhar em profundidade: decompor objetivos maiores em blocos de construção menores (design, código, revisão, teste, etc.), solicitar ao agente que construísse esses blocos e utilizá-los para desbloquear tarefas mais complexas. Quando algo falhava, a solução quase nunca era "tentar mais". Uma vez que a única forma de progredir era pôr o Codex a fazer o trabalho, os engenheiros humanos entravam sempre na tarefa e perguntavam: "que capacidade está a faltar e como é que a tornamos legível e aplicável para o agente?"

Os humanos interagem com o sistema quase exclusivamente através de prompts: um engenheiro descreve uma tarefa, executa o agente e permite que ele abra um pull request. Para concluir um PR, instruímos o Codex a rever localmente as suas próprias alterações, solicitar revisões adicionais específicas de agentes, tanto localmente como na nuvem, responder a qualquer feedback dado por humanos ou agentes e iterar num ciclo até que todos os revisores agentes estejam satisfeitos (na prática, isto é um Ralph Wiggum Loop⁠(abre numa nova janela)). O Codex utiliza diretamente as nossas ferramentas de desenvolvimento padrão (gh, scripts locais e competências incorporadas no repositório) para reunir o contexto sem que os utilizadores tenham de copiar e colar na CLI.

Os humanos podem rever pull requests, mas não são obrigados a fazê-lo. Com o tempo, quase todos os esforços de revisão passaram a ser efetuados entre agentes.

À medida que a taxa de processamento do código aumentou, o nosso obstáculo passou a ser a capacidade de QA humano. Como a restrição fixa tem sido o tempo e a atenção humanos, trabalhámos para adicionar mais capacidades ao agente, tornando coisas como a IU da aplicação, os registos e as próprias métricas da aplicação diretamente legíveis para o Codex.

Por exemplo, tornámos a aplicação inicializável por git worktree, para que o Codex pudesse lançar e gerir uma instância por cada alteração. Também integrámos o protocolo Chrome DevTools ao tempo de execução do agente e criámos competências para trabalhar com snapshots, capturas de ecrã e navegação do DOM. Isto permitiu ao Codex reproduzir bugs, validar correções e raciocinar diretamente sobre o comportamento da IU.

Fizemos o mesmo com as ferramentas de observabilidade. Os registos, as métricas e os rasteios são expostos ao Codex através de uma pilha de observabilidade local que é efémera para qualquer worktree. O Codex opera numa versão totalmente isolada dessa aplicação, incluindo os seus registos e métricas, que são eliminados assim que a tarefa é concluída. Os agentes podem consultar os registos com o LogQL e as métricas com o PromQL. Com este contexto disponível, prompts como "garante que o arranque do serviço é concluído em menos de 800 ms" ou "nenhum intervalo nestes quatro percursos críticos do utilizador excede os dois segundos" tornam-se exequíveis.

Vemos regularmente execuções individuais do Codex a trabalhar numa única tarefa durante mais de seis horas (muitas vezes, enquanto os humanos estão a dormir).

A gestão do contexto é um dos maiores desafios para tornar os agentes eficazes em tarefas extensas e complexas. Uma das primeiras lições que aprendemos foi simples: dar ao Codex um mapa, não um manual de instruções de 1000 páginas.

Tentámos a abordagem do "one big AGENTS.md⁠(abre numa nova janela) . Falhou de formas previsíveis:

• O contexto é um recurso escasso. Um ficheiro de instruções gigantesco abafa a tarefa, o código e a documentação relevante, pelo que o agente ou não deteta restrições importantes ou começa a otimizar para as erradas.
• Demasiada orientação torna-se desorientação. Quando tudo é "importante", nada é. Os agentes acabam por fazer a correspondência de padrões a nível local em vez de navegarem intencionalmente.
• Apodrece instantaneamente. Um manual monolítico transforma-se num cemitério de regras obsoletas. Os agentes não conseguem identificar o que continua a ser verdade, os humanos deixam de o manter e o ficheiro torna-se discretamente um incómodo atrativo.
• É difícil de verificar. Um único blob não se presta a verificações mecânicas (cobertura, atualidade, propriedade, ligações cruzadas), pelo que a deriva é inevitável.

Assim, em vez de tratarmos o AGENTS.md como a enciclopédia, tratamo-lo como o índice.

A base de conhecimentos do repositório reside numa documentação estruturada/diretório tratado como o sistema de registo. Um AGENTS.md curto (cerca de 100 linhas) é injetado no contexto e serve principalmente como um mapa, com referências para fontes mais profundas da verdade noutros locais.

A documentação de design é catalogada e indexada, incluindo o estado de verificação e um conjunto de crenças fundamentais que definem princípios operacionais centrados no agente. A documentação da arquitetura⁠(abre numa nova janela) fornece um mapa de alto nível dos domínios e da organização em camadas dos pacotes. Um documento de qualidade classifica cada domínio de produto e camada arquitetónica, acompanhando as lacunas ao longo do tempo.

Os planos são tratados como artefactos de primeira classe. Planos efémeros e leves são usados para pequenas alterações, enquanto o trabalho complexo é captado em planos de execução⁠(abre numa nova janela) com registos de progresso e de decisões que são registados no repositório. Os planos ativos, os planos concluídos e a dívida técnica conhecida são todos versionados e co-localizados, permitindo que os agentes operem sem depender de contexto externo.

Isto permite uma divulgação progressiva: os agentes começam com um ponto de entrada pequeno e estável e são ensinados a saber onde procurar a seguir, em vez de serem sobrecarregados à partida.

Aplicamos isto mecanicamente. Os linters dedicados e os trabalhos de CI validam se a base de conhecimentos está atualizada, com ligações cruzadas e estruturada corretamente. Um agente recorrente de "doc-gardening" analisa documentação desatualizada ou obsoleta que não reflete o comportamento real do código e abre pull requests de correção.

À medida que a base de código evoluía, a estrutura do Codex para as decisões de design também precisava de evoluir.

Como o repositório é inteiramente gerado por agentes, está otimizado primeiro para a legibilidade do Codex. Da mesma forma que as equipas procuram melhorar a navegabilidade do seu código para novos engenheiros contratados, o objetivo dos nossos engenheiros humanos era possibilitar que um agente raciocinasse sobre todo o domínio empresarial diretamente a partir do próprio repositório.

Do ponto de vista do agente, tudo aquilo a que não pode aceder no contexto durante a execução, não existe efetivamente. O conhecimento que está no Google Docs, em conversas de chat ou na cabeça das pessoas não está acessível ao sistema. Os artefactos versionados locais do repositório (por exemplo, código, markdown, schemas, planos executáveis) são tudo o que consegue ver.

Aprendemos que precisávamos de inserir cada vez mais contexto no repositório ao longo do tempo. Aquela discussão no Slack que alinhou a equipa num padrão de arquitetura? Se não for detetável para o agente, é ilegível da mesma forma que seria desconhecido para um novo colaborador que entrasse três meses depois.

Dar mais contexto ao Codex significa organizar e expor a informação certa para que o agente possa raciocinar sobre ela, em vez de sobrecarregá-lo com instruções ad-hoc. Da mesma forma que se integra um novo colega de equipa nos princípios do produto, nas normas de engenharia e na cultura da equipa (incluindo as preferências de emojis), dar ao agente esta informação conduz a um resultado mais bem alinhado.

Este enquadramento esclareceu muitos compromissos. Privilegiámos dependências e abstrações que pudessem ser totalmente internalizadas e compreendidas no repositório. As tecnologias frequentemente descritas como "aborrecidas" tendem a ser mais fáceis de modelar pelos agentes devido à sua capacidade de composição, estabilidade da API e representação no conjunto de treino. Em alguns casos, era mais barato que o agente reimplementasse subconjuntos de funcionalidades do que contornar o comportamento opaco das bibliotecas públicas. Por exemplo, em vez de usarmos um pacote genérico ao estilo p-limit, implementámos o nosso próprio auxiliar map-with-concurrency: está estreitamente integrado com a nossa instrumentação OpenTelemetry, tem uma cobertura de teste de 100% e comporta-se exatamente da forma que o nosso tempo de execução espera.

Trazer mais do sistema para um formato que o agente possa inspecionar, validar e modificar diretamente aumenta a alavancagem — não apenas para o Codex, mas também para outros agentes (por exemplo, o Aardvark), que também estão a trabalhar na base de código.

A documentação por si só não mantém a coerência de uma base de código totalmente gerada por agentes. Ao impor invariantes, em vez de microgerir implementações, deixamos que os agentes avancem rapidamente sem comprometer a base. Por exemplo, exigimos que o Codex analise as formas de dados no limite⁠(abre numa nova janela), mas não somos prescritivos quanto à forma como isso acontece (o modelo parece gostar do Zod, mas não especificámos essa biblioteca em particular).

Os agentes são mais eficazes em ambientes com limites rigorosos e estrutura previsível⁠(abre numa nova janela), por isso construímos a aplicação em torno de um modelo de arquitetura rígido. Cada domínio empresarial é dividido num conjunto fixo de camadas, com direções de dependência rigorosamente validadas e um conjunto limitado de arestas permitidas. Estas restrições são aplicadas mecanicamente através de linters personalizados (gerados pelo Codex, claro!) e testes estruturais.

O diagrama abaixo mostra a regra: dentro de cada domínio empresarial (por exemplo, Definições da Aplicação), o código só pode depender "para a frente" através de um conjunto fixo de camadas (Types → Config → Repo → Service → Runtime → UI). As preocupações transversais (autenticação, conectores, telemetria, sinalizadores de funcionalidades) entram através de uma única interface explícita: Providers. Tudo o resto é proibido e aplicado mecanicamente.

Este é o tipo de arquitetura que normalmente se adia até se ter centenas de engenheiros. Com agentes de programação, é um pré-requisito inicial: as restrições permitem velocidade sem degradação ou desvio arquitetónico.

Na prática, aplicamos estas regras com linters personalizados e testes estruturais, além de um pequeno conjunto de "invariantes de gosto". Por exemplo, aplicamos de forma estática o registo estruturado, convenções de nomenclatura para schemas e tipos, limites de tamanho de ficheiro e requisitos de fiabilidade específicos da plataforma com lints personalizados. Como os lints são personalizados, escrevemos as mensagens de erro para inserir instruções de remediação no contexto do agente.

Num fluxo de trabalho centrado no ser humano, estas regras podem parecer pedantes ou restritivas. Com os agentes, tornam-se multiplicadores: uma vez codificadas, aplicam-se em todo o lado ao mesmo tempo.

Ao mesmo tempo, somos explícitos quanto a onde as restrições são importantes e onde não o são. Isto assemelha-se à liderança de uma grande organização de plataformas de engenharia: impor limites a nível central, permitir a autonomia a nível local. Preocupa-se profundamente com os limites, a correção e a reprodutibilidade. Dentro desses limites, permite que as equipa — ou os agentes — tenham uma liberdade significativa na forma como as soluções são expressas.

O código resultante nem sempre corresponde às preferências estilísticas humanas, e está tudo bem. Desde que o resultado esteja correto, seja passível de manutenção e legível para futuras execuções do agente, cumpre o requisito.

O gosto humano é continuamente alimentado no sistema. Os comentários de revisão, os pull requests de refatoração e os bugs voltados para o utilizador são captados como atualizações de documentação ou codificados diretamente nas ferramentas. Quando a documentação não é suficiente, passamos a regra para o código.

À medida que a taxa de processamento do Codex aumentava, muitas normas convencionais de engenharia tornaram-se contraproducentes.

O repositório funciona com um bloqueio mínimo de portas de fusão. Os pull requests são de curta duração. As falhas de teste são muitas vezes resolvidas com execuções de acompanhamento em vez de bloquear o progresso indefinidamente. Num sistema onde a taxa de processamento do agente supera largamente a atenção humana, corrigir é barato e esperar é dispendioso.

Isto seria irresponsável num ambiente de baixa taxa de processamento. Neste caso, é muitas vezes a solução correta.

Quando dizemos que a base de código é gerada por agentes Codex, referimo-nos a tudo o que está na base de código.

Os agentes criam:

• Código do produto e testes
• Configuração de CI e ferramentas de lançamento
• Ferramentas internas para programadores
• Documentação e história da conceção
• Aproveitamentos de avaliação
• Rever comentários e respostas
• Scripts que gerem o próprio repositório
• Ficheiros de definição do painel de controlo de produção

Os seres humanos permanecem sempre no circuito, mas trabalham num nível de abstração diferente do que costumavam fazer. Damos prioridade ao trabalho, traduzimos o feedback dos utilizadores em critérios de aceitação e validamos os resultados. Quando o agente tem dificuldades, tratamo-lo como um sinal: identificamos o que está em falta — ferramentas, guardrails, documentação — e devolvemos essa informação ao repositório, fazendo sempre com que o próprio Codex escreva a correção.

Os agentes utilizam diretamente as nossas ferramentas de desenvolvimento padrão. Estes extraem feedback de revisão, respondem em linha, enviam atualizações e, muitas vezes, comprimem e fundem os seus próprios pull requests.

À medida que uma maior parte do ciclo de desenvolvimento foi sendo codificada diretamente no sistema — testes, validação, revisão, tratamento de feedback e recuperação —, o repositório ultrapassou recentemente um limiar significativo em que o Codex pode conduzir uma nova funcionalidade de ponta a ponta.

Com um único prompt, o agente pode agora:

• Validar o estado atual da base de código
• Reproduzir um erro reportado
• Gravar um vídeo que demonstre a falha
• Implementar uma correção
• Validar a correção ao testar a aplicação
• Gravar um segundo vídeo que demonstre a resolução
• Abrir um pull request
• Responder ao feedback do agente e do humano
• Detetar e corrigir falhas de construção
• Passar para um humano apenas quando é necessário fazer uma avaliação
• Fundir a alteração

Este comportamento depende muito da estrutura e das ferramentas específicas deste repositório e não deve ser generalizado sem um investimento semelhante — pelo menos, para já.

A autonomia total dos agentes também introduz novos problemas. O Codex replica padrões que já existem no repositório, mesmo que sejam irregulares ou insuficientes. Com o tempo, isto conduz inevitavelmente ao desvio.

Inicialmente, os humanos lidaram com isto manualmente. A nossa equipa costumava passar todas as sextas-feiras (20% da semana) a limpar o "lixo da IA". Como era de se esperar, isso não funcionou.

Em vez disso, começámos a codificar aquilo a que chamamos "princípios de ouro" diretamente no repositório e criámos um processo de limpeza recorrente. Estes princípios são regras mecânicas e opinativas que mantêm a base de código legível e consistente para futuras execuções de agentes. Por exemplo: (1) preferimos pacotes de utilitários partilhados em vez de auxiliares feitos à mão para manter as invariantes centralizadas e (2) não sondamos dados "ao estilo YOLO" — validamos limites ou recorremos a SDKs tipados para que o agente não possa, acidentalmente, construir com base em formas adivinhadas. Com uma cadência regular, temos um conjunto de tarefas Codex em segundo plano que analisam desvios, atualizam classificações de qualidade e abrem pull requests de refatoração direcionados. A maioria pode ser revista em menos de um minuto e fundida automaticamente.

Isto funciona como a recolha de lixo. A dívida técnica é como um empréstimo com juros elevados: é quase sempre melhor pagá-la continuamente em pequenos incrementos do que deixá-la acumular-se e enfrentá-la em explosões dolorosas. O gosto humano é captado uma vez e depois aplicado continuamente em cada linha de código. Isto também nos permite identificar e resolver padrões incorretos diariamente, em vez de os deixar propagar-se na base de código durante dias ou semanas.

Esta estratégia tem funcionado bem até agora, desde o lançamento interno até à adoção na OpenAI. Construir um produto real para utilizadores reais ajudou a ancorar os nossos investimentos na realidade e a orientar-nos para a manutenção a longo prazo.

O que ainda não sabemos é como a coerência arquitetónica evolui ao longo dos anos num sistema totalmente gerado por agentes. Ainda estamos a aprender onde é que o julgamento humano é mais vantajoso e como codificar esse julgamento de forma a que este se componha. Também não sabemos como é que este sistema irá evoluir à medida que os modelos continuam a tornar-se mais capazes ao longo do tempo.

O que ficou claro: criar software ainda exige disciplina, mas a disciplina aparece mais no scaffolding do que no código. As ferramentas, as abstrações e os ciclos de feedback que mantêm a coerência da base de código são cada vez mais importantes.

Os nossos desafios mais difíceis centram-se agora na conceção de ambientes, circuitos de feedback e sistemas de controlo que ajudem os agentes a atingir o nosso objetivo: construir e manter software complexo e fiável em grande escala.

À medida que agentes como o Codex assumem partes maiores do ciclo de vida do software, estas questões serão ainda mais importantes. Esperamos que a partilha de algumas lições iniciais o ajude a refletir sobre onde investir o seu esforço para para que possa simplesmente criar coisas.