- Um caso experimental em que uma equipe interna da OpenAI construiu e lançou a beta interna de um produto de software sem escrever código manualmente por 5 meses, com todo o código gerado por agentes Codex
- Começando com 3 engenheiros, a equipe lidou com cerca de 1 milhão de linhas de código e 1.500 pull requests, com média de 3,5 PRs mesclados por engenheiro por dia
- O papel do engenheiro mudou da codificação direta para projetar o ambiente, explicitar a intenção e construir loops de feedback, e o ponto central passou a ser criar scaffolding para que os agentes trabalhem com estabilidade
- O
AGENTS.md foi usado como índice, não como enciclopédia, e a consistência arquitetural foi aplicada mecanicamente por meio de documentação estruturada, linters e testes estruturais
- Quanto maior a autonomia dos agentes, mais essencial se torna o controle da entropia e a limpeza contínua em estilo garbage collection, com a disciplina da construção de software migrando do código para o scaffolding
Um experimento que começou de um repositório git vazio
- No fim de agosto de 2025, foi feito o primeiro commit em um repositório vazio; o scaffold inicial (estrutura do repositório, configuração de CI, regras de formatação, configuração do gerenciador de pacotes e framework da aplicação) foi gerado no Codex CLI com GPT-5, com base em templates existentes
- O arquivo inicial AGENTS.md, que ensina ao agente como trabalhar no repositório, também foi escrito pelo próprio Codex
- Desde o início, o repositório foi moldado pelos agentes, sem código pré-existente escrito por humanos
- Após 5 meses, passou a incluir cerca de 1 milhão de linhas de código cobrindo lógica da aplicação, infraestrutura, tooling, documentação e utilitários internos para desenvolvedores
- Uma equipe enxuta de 3 pessoas abriu e mesclou cerca de 1.500 pull requests, o que equivale a uma vazão média de 3,5 PRs por engenheiro por dia
- Quando a equipe cresceu para 7 pessoas, a vazão aumentou ainda mais
- O sistema vinha sendo usado internamente todos os dias por centenas de usuários, incluindo power users internos
- Ao longo de todo o processo de desenvolvimento, humanos nunca contribuíram diretamente com código
- "Não existe código escrito manualmente" tornou-se a filosofia central da equipe
Redefinindo o papel do engenheiro
- Como as pessoas não codificam diretamente, passa a ser necessário outro tipo de trabalho de engenharia, centrado em sistemas, scaffolding e alavancagem
- O progresso inicial foi mais lento do que o esperado, não por limitação do Codex, mas por falta de ambiente adequado
- Faltavam ao agente ferramentas, abstrações e estrutura interna para atingir objetivos de mais alto nível
- O trabalho principal da equipe de engenharia passou a ser dar suporte para que o agente consiga executar tarefas úteis
- Grandes objetivos são decompostos em blocos menores (projeto, código, revisão, testes etc.), e o agente combina esses blocos para resolver tarefas mais complexas em um fluxo de trabalho depth-first
- Diante de falhas, a pergunta central não é "se esforçar mais", mas "qual capacidade está faltando, e como tornar isso legível e executável para o agente?"
- Humanos interagem com o sistema quase inteiramente por prompts
- Instruindo descrição de tarefas, execução de agentes e abertura de pull requests
- Para concluir um PR, o Codex recebe instruções para revisar localmente suas próprias alterações, pedir revisões adicionais de agentes localmente e na nuvem, responder ao feedback e repetir até satisfazer todos os revisores-agentes
- Na prática, um fluxo no estilo Ralph Wiggum Loop
- O Codex usa diretamente ferramentas padrão de desenvolvimento como
gh, scripts locais e skills embutidas no repositório para coletar contexto
- Revisão humana de pull requests é possível, mas não obrigatória; com o tempo, quase toda a revisão foi convertida em processamento entre agentes
Tornando a aplicação legível
- Com o aumento da vazão de código, surgiu um gargalo na capacidade humana de QA
- Como o tempo e a atenção humana são restrições fixas, foram adicionadas capacidades aos agentes para que o Codex pudesse ler e entender diretamente a UI da aplicação, logs e métricas do app
- Com a capacidade de subir o app por
git worktree, o Codex consegue executar e controlar uma instância separada para cada conjunto de mudanças
- O Chrome DevTools Protocol foi conectado ao runtime do agente, e foram criadas skills para snapshots de DOM, screenshots e navegação
- Isso permite ao Codex reproduzir bugs, validar correções e raciocinar diretamente sobre o comportamento da UI
- O mesmo método foi aplicado ao tooling de observabilidade
- Logs, métricas e traces são expostos ao Codex por meio de uma stack local de observabilidade mantida temporariamente para cada worktree
- Logs e métricas são apagados após a conclusão do trabalho
- O agente pode consultar logs com LogQL e métricas com PromQL
- Com esse contexto, torna-se fácil processar prompts como "fazer o serviço iniciar em até 800 ms" ou "garantir que nenhum span ultrapasse 2 segundos nas quatro jornadas críticas do usuário"
- Uma única execução do Codex pode trabalhar em uma tarefa por mais de 6 horas (muitas vezes enquanto a pessoa está dormindo)
Usando o conhecimento do repositório como sistema de registro
- A gestão de contexto é um dos maiores desafios para que agentes executem tarefas grandes e complexas com eficácia
- Lição inicial: é preciso dar ao Codex um mapa, não um manual de 1.000 páginas
- A abordagem de um "grande AGENTS.md" foi tentada e falhou de forma previsível
- Contexto é um recurso escasso: um arquivo enorme de instruções complica a tarefa, o código e os documentos relevantes, fazendo o agente perder restrições importantes ou otimizar para restrições erradas
- Instrução demais deixa de ser instrução: se tudo é "importante", nada é importante; o agente passa a fazer correspondência local de padrões em vez de exploração intencional
- Se degrada muito rápido: um manual monolítico logo vira um cemitério de regras obsoletas, e o agente não consegue julgar o que ainda é válido
- É difícil de verificar: um único bloco não serve para checagens mecânicas (cobertura, atualidade, ownership, links cruzados), então o drift é inevitável
- A solução foi tratar o AGENTS.md como índice, não como enciclopédia
- A base de conhecimento do repositório é gerida como sistema de registro em um diretório estruturado
docs/
- Um AGENTS.md curto (cerca de 100 linhas) é inserido no contexto e atua principalmente como mapa, apontando para fontes de informação mais profundas e confiáveis
- A documentação de design é classificada e indexada, incluindo crenças centrais que definem o estado de validação e princípios operacionais agent-first
- A documentação de arquitetura fornece o mapa de mais alto nível do domínio e das camadas de pacotes
- A documentação de qualidade dá notas para cada domínio do produto e cada camada da arquitetura, acompanhando lacunas ao longo do tempo
- Planos são tratados como artefatos de primeira classe
- Planos temporários e simples são usados para mudanças pequenas
- Tarefas complexas entram em planos de execução armazenados no repositório, junto com progresso e logs de decisão
- Planos em andamento, planos concluídos e dívida técnica conhecida ficam versionados no mesmo lugar
- Isso permite divulgação progressiva: o agente começa por um ponto de entrada pequeno e estável, sem sobrecarga inicial, e avança passo a passo
- Aplicação mecânica: linters dedicados e jobs de CI verificam se a base de conhecimento está atualizada, interligada e corretamente estruturada
- Um agente recorrente de "doc-gardening" revisa documentos antigos ou inválidos e abre pull requests com correções
O objetivo é a legibilidade para agentes
- Como o repositório foi gerado inteiramente por agentes, ele foi otimizado прежде de tudo para a legibilidade do Codex
- O objetivo dos engenheiros humanos é fazer com que o agente consiga raciocinar sobre todo o domínio de negócio diretamente a partir do próprio repositório
- Do ponto de vista do agente, o que não pode ser acessado no contexto de execução praticamente não existe
- Google Docs, threads de chat e conhecimento na cabeça das pessoas são inacessíveis ao sistema
- Só é possível acessar artefatos versionados no repositório (código, Markdown, schemas, planos de execução)
- Mesmo um padrão arquitetural acordado em uma discussão no Slack é ilegível para o agente se ele não puder encontrá-lo por busca
- Dar mais contexto ao Codex não significa sobrecarregá-lo com instruções temporárias, e sim organizar e expor a informação correta para que o agente consiga raciocinar
- Os resultados melhoram quando se fornece ao agente informações sobre princípios de produto, normas de engenharia e cultura da equipe (incluindo preferências por emoji) como se estivesse onboardando um novo integrante
- Há preferência por dependências e abstrações que possam ser completamente internalizadas e raciocinadas dentro do repositório
- Tecnologias "chatas" tendem a ser mais fáceis para agentes modelarem por causa do acoplamento, da estabilidade de API e da representação no conjunto de treino
- Em alguns casos, é mais barato o agente reimplementar diretamente um subconjunto da funcionalidade do que depender de comportamentos upstream opacos de bibliotecas públicas
- Exemplo: em vez de um pacote genérico no estilo
p-limit, foi implementado um helper próprio de map-with-concurrency, fortemente integrado com instrumentação OpenTelemetry, com 100% de cobertura de testes e comportamento exato ao esperado em runtime
- Quanto mais o sistema é trazido para uma forma que agentes possam inspecionar, validar e modificar diretamente, maior a alavancagem não só para o Codex, mas também para outros agentes (como Aardvark)
Aplicando arquitetura e preferências
- Só documentação não basta para manter totalmente consistente uma base de código gerada por agentes
- A base permanece sólida e os agentes conseguem lançar rápido ao aplicar invariantes sem microgerenciar a implementação
- Exemplo: queria-se que o Codex fizesse parsing do formato dos dados nas bordas, mas sem especificar em detalhes como fazer isso (o modelo tende a preferir Zod)
- Agentes funcionam melhor em ambientes com fronteiras rígidas e estrutura previsível
- A aplicação foi construída em torno de um modelo arquitetural estrito
- Cada domínio de negócio é separado em um conjunto fixo de camadas, com direções de dependência rigidamente validadas e um conjunto limitado de arestas permitidas
- O código flui na ordem Types → Config → Repo → Service → Runtime → UI
- Questões transversais (autenticação, conectores, telemetria, feature flags) entram por meio de uma única interface explícita chamada Providers
- Todo o resto é proibido e aplicado mecanicamente
- Essas restrições são aplicadas por linters customizados e testes estruturais gerados pelo Codex
- Esse nível de arquitetura costuma ser adiado até equipes com centenas de engenheiros, mas para agentes de codificação é uma pré-condição inicial
- Linters customizados aplicam estaticamente logging estruturado, convenções de nomenclatura de schemas e tipos, limites de tamanho de arquivo e requisitos de estabilidade específicos de plataforma
- Como o lint é customizado, é possível escrever mensagens de erro que injetam instruções de correção no contexto do agente
- Em workflows centrados em humanos, essas regras podem parecer detalhistas ou restritivas demais, mas com agentes elas multiplicam o efeito várias vezes
- As restrições deixam claro o que importa e o que não importa
- Algo parecido com operar uma grande organização de plataforma de engenharia: limites definidos no centro, autonomia permitida localmente
- O código resultante nem sempre bate com preferências estilísticas humanas, mas se a saída for correta, fácil de manter e legível durante a execução dos agentes, então atende ao critério
- As preferências humanas são continuamente realimentadas no sistema
- Comentários de revisão, PRs de refatoração e bugs reportados por usuários viram atualizações de documentação ou são codificados diretamente no tooling
- Quando a documentação não basta, a regra sobe para código
Mudança na filosofia de merge
- Com o aumento da vazão do Codex, normas tradicionais de engenharia passaram a ser contraproducentes
- O repositório opera com gates mínimos de bloqueio para merge
- Pull requests têm vida curta, e instabilidades de teste são resolvidas em execuções posteriores, em vez de bloquear indefinidamente o progresso
- Em sistemas onde a vazão dos agentes supera muito a atenção humana, corrigir é barato e esperar é caro
- Isso talvez não seja adequado em ambientes de baixa vazão; é preciso encontrar o trade-off certo
O escopo real de "gerado por agentes"
- Dizer que a base de código foi gerada por agentes Codex significa tudo o que existe nela
- Código de produto e testes
- Configuração de CI e tooling de release
- Ferramentas internas para desenvolvedores
- Documentação e histórico de design
- Harnesses de avaliação
- Comentários de revisão e respostas
- Scripts que administram o próprio repositório
- Arquivos de definição de dashboards de produção
- Humanos continuam sempre no loop, mas trabalham em uma camada de abstração diferente da anterior
- Priorizando trabalho, convertendo feedback de usuários em critérios de aceitação e validando resultados
- Quando o agente encontra dificuldade, isso é tratado como sinal para identificar o que está faltando em ferramentas, guardrails e documentação, e as correções são sempre escritas pelo próprio Codex e devolvidas ao repositório
- O agente também busca feedback de revisão, responde inline, faz push de updates e até faz squash e merge de seus próprios pull requests
Aumento do nível de autonomia
- À medida que mais loops de desenvolvimento — testes, validação, revisão, tratamento de feedback e recuperação — são codificados diretamente no sistema, chega-se a um ponto crítico importante
- O que o agente consegue fazer com um único prompt:
- Validar o estado atual da base de código
- Reproduzir um bug reportado
- Gravar um vídeo demonstrando a falha
- Implementar a correção
- Executar a aplicação para validar a correção
- Gravar um segundo vídeo mostrando a solução
- Abrir um pull request
- Responder ao feedback de agentes e de humanos
- Detectar e corrigir falhas de build
- Escalar para humanos apenas quando é necessário julgamento
- Mesclar a mudança
- Esse comportamento depende muito da estrutura e do tooling específicos deste repositório, e não se deve presumir que ele generaliza sem investimento semelhante
Entropia e garbage collection
- A autonomia total dos agentes cria novos problemas: o Codex replica padrões já existentes no repositório (incluindo padrões inconsistentes ou longe do ideal), e com o tempo o drift se torna inevitável
- No começo, isso foi tratado manualmente por humanos, consumindo toda sexta-feira (20% da semana) com limpeza de "AI slop"
- Como esperado, isso não escalou
- A alternativa foi codificar diretamente no repositório "princípios de ouro" e montar processos regulares de limpeza
- (1) Preferir pacotes utilitários compartilhados em vez de helpers criados ad hoc, para centralizar invariantes
- (2) Não explorar dados em estilo "YOLO-style"; validar nas bordas ou depender de SDKs tipados para impedir que o agente construa coisas por engano com base em formatos inferidos
- Operam-se jobs de background do Codex que verificam desvios periodicamente, atualizam notas de qualidade e geram PRs de refatoração direcionados
- Em sua maioria, são revisáveis em menos de 1 minuto e fazem auto-merge
- Isso funciona como garbage collection: dívida técnica é como um empréstimo com juros altos, então compensa pagá-la continuamente em pequenas parcelas antes que os juros se acumulem
- Uma vez capturada, a preferência humana passa a ser aplicada continuamente a todas as linhas de código, e padrões ruins são detectados e corrigidos todos os dias, sem se espalharem por dias ou semanas
Aprendizados em andamento e desafios futuros
- Essa estratégia funcionou bem dentro da OpenAI até a fase de lançamento interno e adoção
- Construir um produto real para usuários reais é o que ancora esse investimento na realidade e garante manutenção sustentável no longo prazo
- O que ainda não se sabe: como a consistência arquitetural evolui ao longo de anos em um sistema totalmente gerado por agentes
- Ainda se está aprendendo onde o julgamento humano tem maior impacto e como codificá-lo para obter efeito composto
- Com a melhora contínua das capacidades dos modelos, a direção de evolução desse sistema também permanece incerta
- Construir software ainda exige disciplina, mas essa disciplina se manifesta cada vez mais no scaffolding do que no código
- Tooling, abstrações e loops de feedback para manter a consistência da base de código estão se tornando cada vez mais importantes
- O desafio mais difícil hoje é desenhar ambientes, loops de feedback e sistemas de controle que ajudem agentes a construir e manter software complexo e estável em grande escala
1 comentários
40 dias, 1 milhão de linhas, 13 bilhões de tokens — o que o CEO da Lablup, Jungkyu Shin, descobriu sobre a realidade do workflow agêntico - Parque do Silício de Park Jae-hong - https://wikidocs.net/blog/@jaehong/8206/