Esta é a parte dois de Por que as Fábricas de Software Fracassam
A versão em palestra deste post está disponível no youtube: https://www.youtube.com/watch?v=Ib5GBkD555M
Acendendo as luzes novamente
Na parte 1, abordei em profundidade por que os modelos não podem ser confiáveis para manter a qualidade do código ao longo do tempo. Por que nenhuma quantidade de engenharia de harness ou tokenmaxxing resolverá um problema de treinamento de modelos e benchmarks. Por que "modelo como juiz" para qualidade de código não funciona tão bem quanto alguns gostariam de fazer você acreditar.
Por enquanto, o juiz é você — então vamos colocar a revisão de código de volta no processo.
Vamos abraçar aquela mesma coisa que já fazíamos antes da IA, que é fazer um pouco de planejamento antecipado, para reduzir as chances de uma revisão longa e difícil.
Vamos encontrar alavancagem, e vamos usar a IA para nos ajudar nisso, em 4 fases:
- Requisitos do Produto
- Arquitetura do Sistema
- Design do Programa
- Fatias Verticais
Revisão do produto
Tudo começa com uma revisão do produto: um documento curto que define o que estamos construindo e por quê. O objetivo é pegar duas frases ou um longo áudio desorganizado e transformá-lo em algo semiestruturado.
Primeiro, alinhamos sobre o problema a resolver — a real dor do usuário, nos termos do usuário. Segundo, como é o sucesso — o que podemos ler após o lançamento para decidir se valeu a pena construir. Idealmente, isso é um resultado para o usuário como "consegue fazer o fluxo de trabalho XYZ em menos tempo" ou "atinge o marco de onboarding ABC mais cedo". Às vezes é algo mais técnico, como uma taxa de erro ou um número de latência, às vezes apenas "os tickets de suporte sobre X param".
Tentamos manter isso bem ancorado no espaço do produto, não no técnico. Como alguém que vive com um pé no mundo do produto e outro na tecnologia, frequentemente me pego divagando para os detalhes técnicos aqui. Quando isso acontece, tento apenas anotar para fases posteriores e volto ao que o usuário realmente experimenta. Se decisões técnicas estão bloqueando decisões de produto, então consolidamos o que temos e partimos para a arquitetura ou fazemos mais pesquisa de protótipo sobre o que é viável
E como a maior parte disso é sobre o que o usuário vê, não descrevo — eu prototipo. Um mockup HTML básico da tela real resolve uma discussão que três parágrafos só prolongariam.
Aqui está um exemplo real em andamento — o documento define o recurso com um esboço em JSON, depois dois mockups HTML básicos das telas reais:
https://x.com/dexhorthy/status/2078592010852982977
Claro, nem tudo recebe uma revisão de produto. Um ajuste de texto, um script pontual, um bug com reprodução óbvia — ainda mandamos esses diretamente para o agente. Isso é para as mudanças onde um mal-entendido do agente sobre nossa intenção é custoso.
Para este e todos os documentos da série, fazemos revisões com adesão opcional do autor. Se você quiser economizar tempo durante a revisão, escolha a pessoa que revisaria o PR e percorra as especificações de produto/tecnologia com ela, seja de forma assíncrona por meio de comentários no documento (nós usamos o HumanLayer internamente para isso, mas você pode facilmente fazer isso no GitHub/Notion/Plannotator/etc).
Arquitetura do sistema
Uma vez que a revisão do produto está resolvida, fazemos a arquitetura do sistema. Isso não é particularmente novo e é algo que até mesmo os codificadores de vibe estão começando a adotar.
Se você quer economizar tempo durante a revisão, escolha a pessoa que revisaria o PR e percorra as especificações de produto/tecnologia com ela antes de chegar à parte da codificação.
Nesta fase, alinhamos como os serviços, endpoints, esquemas, filas e armazenamentos se comunicam, sem entrar nos detalhes do design do programa. Para maximizar a largura de banda de comunicação humano<>agente, fazemos uso intenso de visualizações aqui - por exemplo, diagramas de sequência:
Formatos de contrato / endpoint:
Modelos de dados e transformações:
Mermaid é aceitável aqui, mas às vezes pode ser exagerado e, às vezes, pode te levar a uma falsa sensação de que vocês estão alinhados. A arquitetura tem alavancagem bastante alta e há muitos tiques de modelo potencialmente ruins que você pode evitar durante esta fase. Mas é insuficiente para produzir código de alta qualidade. Para isso, precisamos do design do programa.
Design do programa
Depois da arquitetura, fazemos algo que acho que é criminosamente subestimado na codificação agentiva: design do programa.
A maioria das pessoas assume que, uma vez que a arquitetura está correta, o modelo pode simplesmente cozinhar. Você pode ir em frente e fazer isso, mas pode não gostar do que recebe de volta.
Mas o que vejo funcionando bem é que, antes de qualquer um (humano ou agente) escrever a implementação, descemos um nível da arquitetura para a forma do código: os tipos, as assinaturas de métodos, o layout do programa e as pilhas de chamada.
A primeira versão da nossa habilidade de design de programa foi horrível. Era difícil de ler, era exaustiva. Tentamos o Mermaid, que tem seu lugar, mas o que nós realmente amamos são visualizações leves em pseudocódigo:
Árvores de pilha de chamada, para qualquer mudança de orquestração ou fluxo de controle. Use sintaxe de diff quando a parte interessante é o que está mudando:
Dillon Mulroy fala sobre usar grafos de chamada como parte de seu processo de planejamento, e acho que isso é exatamente certo.
Diffs de árvore de arquivos - para que você mantenha contato com o layout do seu código e onde as coisas estão
Tipos e assinaturas de métodos para as novas funções principais — aquelas coisas que são muito internas para um documento de arquitetura, mas que um agente ainda pode errar
Nenhum desses leva muito tempo para produzir (o modelo os rascunha, você discute com ele), e cada um deles é uma decisão que você, de outra forma, tomaria implicitamente durante a revisão de código — no momento mais caro possível para mudar de ideia.
Fatias verticais
Em seguida, adoramos fazer o que chamo de "fatias verticais" - Matt Pocock e eu tivemos uma
conversa sobre fatias verticais ou "balas traçadoras" em uma live em janeiro de 2026 - isso também é conhecido como balas traçadoras
Os modelos adoram o que chamo de "planos horizontais" - fazer as coisas em ordem de pilha:
- Migrações de Banco de Dados
- Camada de Serviço
- API
- Frontend
Na prática, o que isso significa é que não há uma maneira real de "tocar" a solução enquanto você avança. Você pode testar coisas com código, mas para quase qualquer recurso que já construí, ler os testes era um começo, mas puxar algo em um navegador, ou testar com curl enquanto trabalhava, sempre foi uma parte frequente do fluxo de trabalho.
Antes da IA, era raro alguém escrever mais de 2000 linhas de código ou mesmo 500 linhas de código sem verificar algo ao longo do caminho.
Levei um tempo para perceber a diferença em relação ao que estava acostumado - quando eu escrevia código antes da IA, sempre começava pelo meio e expandia para fora. Vagamente:
- Criar o contrato da API e servir dados mockados, testar com curl
- Criar o frontend para consumir dados mockados, iterar+polir no navegador
- Conectar a API à camada de serviços (serviços fornecem dados/comportamento mockados)
- Adicionar migrações de banco de dados, conectar serviços ao banco de dados
- Adicionar um monte de lógica de negócio
- Adicionar um monte de tratamento de erros
E eu estaria testando/iterando/polindo em cada etapa.
Se eu me importo muito com o código ou estou cético sobre a capacidade do modelo de fazer um bom trabalho nesta parte do código, estou revisando o código em cada etapa também. Verificar 100-200 linhas e redirecionar é muito mais barato
aqui, eu faria isso. A maioria dos modelos de fronteira não projetará um plano como este sem orientação humana, e é difícil generalizar por código ou mesmo por tarefa, então prefiro permanecer no loop aqui. Confie em mim. Se eu pudesse terceirizar o pensamento
30 minutos de planejamento economizam horas de revisão
E então temos algumas etapas nas quais eu argumentaria que os humanos precisam estar no loop, se você quiser manter um nível de qualidade próximo ao humano sem se matar sobre montanhas de código porcaria tentando limpá-lo depois. (ou seja, se você realmente quer ir rápido)
- Design do Produto
- Arquitetura do Sistema
- Design do Programa
- Fatias Verticais
Obviamente, não fazemos todo esse processo para tudo que entregamos (veja a sidequest abaixo). Eu diria que a distribuição é aproximadamente:
- ~40% das tarefas são resolvidas de uma vez ou com 1-2 rodadas de feedback leve
- para tarefas médias, fazemos o design do produto/sistema em um único documento de plano, e não nos preocupamos em dividir o trabalho em fases
- para coisas grandes, fazemos todas as etapas. Pulamos a parte do produto para coisas onde não faz sentido, como grandes refatorações.
E na maioria dos casos, envio um modelo para fazer 1-3 fatias de cada vez, e reviso o código conforme avanço. É muito mais fácil redirecionar no início, seja nos aspectos internos ou na funcionalidade real, do que acabar do outro lado de 2k+ linhas de código sem ideia do que está quebrado.
Você provavelmente sente que tem muitos pull requests
Você não tem muitos PRs. Você tem muitos PRs ruins.
Todos nós já revisamos muitos PRs que precisavam de retrabalho, muito antes da IA.
Mas um bom PR é uma alegria de revisar. Você está percorrendo cada arquivo, o código está limpo, segue todas as suas decisões/discussões/opiniões conquistadas com dificuldade sobre como o software deve ser.
Por outro lado, se um Pull Request precisa de 20% de retrabalho (e isso é generoso, eu diria que a maioria dos PRs feitos de uma vez por IA tende a ficar mais perto de 50%), isso é um fardo intelectual e um fardo emocional tanto para quem submete quanto para o revisor. (Mesmo que o submissor seja uma IA, alguém provavelmente iniciou este trabalho ou poliu o resultado da IA ou, no mínimo, se importa com o resultado).
Para poupar seu tempo (estamos quase no fim), divaguei mais sobre isso em uma side quest:
uma teoria das restrições (edição 2026)
É fácil ficar um pouco desanimado com a tese central aqui: "por enquanto estamos presos a ler o código".
Eu estava bem animado para um mundo onde pudéssemos apenas pedir coisas e deixar os modelos cozinharem e não ler o código e obter software de produção bonito que evolui com o tempo e não vai para o brejo.
Mas o que fiz o meu melhor para expor aqui são nada mais que restrições. Modelos são bons em algumas coisas, não tão bons em outras. Como você otimiza seu processo à luz dessas restrições?
Modelos são bons em algumas coisas, não tão bons em outras. Como você otimiza seu processo à luz dessas restrições?
É possível que você esteja muito ocupado tentando se mover 10-100x mais rápido e tentando se convencer de que a qualidade do código não importa mais, quando você poderia abraçar as restrições e se mover 2-3x mais rápido, com segurança.
Meu tipo de conselho final aqui é basicamente:
- Aprenda bem as restrições, desenvolva intuição trabalhando muito com modelos
- Otimize sistemas dentro da arena dessas restrições
- Busque alavancagem
- Leia a maldita código
É isso. Se você quiser ficar para o pitch, continue rolando, eu acho. Espero que isso ajude você a evitar um desastre ou pelo menos que você tenha se divertido assistindo algumas animações fofas.
Obrigado por ler
-dex
PS Somos obcecados por isso
Estamos construindo humanlayer.com, um IDE agentivo e plataforma de colaboração para ajudar você a se mover 2-3x mais rápido enquanto mantém um nível de qualidade de código humano (ou bem próximo disso).
Estamos construindo em direção a duas ideias: "blocos de construção para sua fábrica de software" e "verificadores melhores para a sustentabilidade do software" (talvez até modelos melhores).
O HumanLayer é gratuito para pequenas equipes de até 3 pessoas, e se você quiser ajuda para começar, pode vir bater um papo em nosso discord ou nos enviar uma linha para founders@humanlayer.dev
Um agradecimento rápido a @calvinfo pela inspiração, ao meu cofundador @0xBlacklight, a @swyx e à equipe da @aiDotEngineer por me dar uma arena para explorar essas ideias, e a todos os nossos incríveis clientes, investidores, amigos e familiares que nos torcem.
Se você quiser saber mais, eu basicamente não paro de falar sobre isso, então você pode encontrar todos os links deste post, bem como algumas outras projeções do material em podcasts, quadro branco em formato longo, etc, abaixo.
PPS Outros recursos
Podcasts e Artigos:
- Dex e Gergely discutem engenharia de contexto e fábricas de software no The Pragmatic Engineer - Julho de 2026
- Dex e Matt Pocock discutem conselhos atemporais de codificação com IA (e loops ralph) - Janeiro de 2026
Episódios do AI That Works:
- Benchmarks não provam nada
- Especificações de Produto para Codificação com IA
- Testes de Aprendizagem para melhor backpressure
- Aplicando princípios de 12-Factor Agents à codificação com IA
Links deste post:
- Por que as Fábricas de Software Fracassam keynote — AI Engineer World's Fair 2026
- Fábrica de software com luzes apagadas da StrongDM
- OpenAI: Engenharia de Harness (Fev 2026)
- Ryan Lopopolo sobre Symphony (palestra, Abr 2026)
- Mario no AI Engineer Europe: "Construindo pi em um mundo de porcaria"
- FT: Quedas da Amazon devido a erros de agentes de codificação
- Matt Pocock: bases de código se desfazendo
- Faros AI: o relatório do chicote da aceleração da IA
- Engenharia de Contexto Avançada para Agentes de Codificação (palestra 25/08)
- Sem Vibes Permitidos (palestra 25/11)
- Tudo o que Erramos Sobre RPI (palestra 26/03)
- Awesome-RLVR - Recursos de Aprendizagem por Reforço
- Engenharia de Contexto Avançada para Agentes de Codificação (texto)
- 12-Factor Agents
- Addy Osmani sobre vibe-coding vs. manutenção
- Conferência de Engenharia de Software da OTAN, 1968
- Documento de Referência de Design DevSecOps do DoD (PDF)
- Plataforma de agente de codificação da Ramp
- Stripe: Minions, agentes de codificação ponta a ponta de uma só vez
- WorkOS: Projeto Horizon
- Brex (Latent Space)
- Dan Shapiro: os cinco níveis até a fábrica de software
- Simon Willison sobre a fábrica de software da StrongDM
- "Ferver o oceano"
- Cirurgia de espingarda (refactoring.guru)
- John Ousterhout — Uma Filosofia de Design de Software
- Robert C. Martin — Código Limpo
- Martin Fowler — Refatoração
- aider
- cline
- codebuff
- Artigo do SWE-Agent (2024)
- Palestra do OpenAI Codex (Nov)
- Calvin French-Owen — Palestra no AI Council
- SWE-bench Multilíngue (dataset)
- AIE Worlds Fair 2026 - O Grande Debate dos Loops ("o hype está superando a disciplina")
- SWE-Marathon (Abundant AI)
- DeepSWE (Datacurve)
- Frontier Code (Cognition)
- Teste de mutação (Wikipedia)
- Dillon Mulroy sobre grafos de chamada no planejamento
- Dex × Matt Pocock: fatias verticais / balas traçadoras (live, Jan 2026)
- "O trabalho árduo do pensamento não pode ser terceirizado" (Jake Nations)
