Esta é a segunda parte de Por que as Fábricas de Software Falham
A versão em palestra deste post está 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 vai 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 como algumas pessoas querem te fazer acreditar.
Por enquanto, o juiz é você -- então vamos colocar a revisão de código de volta.
Vamos abraçar aquela mesma coisa que fazemos desde antes da IA, que é fazer um pouco de planejamento adiantado, para reduzir as chances de uma revisão longa e difícil.
Vamos encontrar alavancagem, e vamos usar IA para 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 de voz e transformar em algo semi-estruturado.
Primeiro, alinhamos o problema a ser resolvido -- 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 workflow XYZ em menos tempo" ou "atinge o marco de onboarding ABC mais cedo". Às vezes é algo mais básico 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 fundamentado 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, muitas vezes me pego deslizando para os detalhes técnicos aqui. Quando isso acontece, tento apenas anotar para fases posteriores e voltar ao que o usuário realmente experimenta. Se decisões técnicas estão bloqueando decisões de produto, então comprometemos 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ê, eu não descrevo -- eu prototipo. Um mockup HTML bruto 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 JSON, depois dois mockups HTML brutos das telas reais:
https://x.com/dexhorthy/status/2078592010852982977
Claro, nem tudo recebe uma revisão de produto. Um ajuste de texto, um script avulso, um bug com reprodutor óbvio -- ainda fazemos esses disparos únicos direto para o agente. Isso é para as mudanças onde um mal-entendido do agente sobre nossa intenção é caro.
Para este e todos os documentos da série, fazemos revisões com opt-in do autor. Se você quiser economizar tempo durante a revisão, você escolhe a pessoa que revisaria o PR e passa pelas especificações de produto/tecnologia com ela, seja de forma assíncrona por comentários no documento (usamos humanlayer 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é os vibe coders estão começando a adotar.
Se você quer economizar tempo durante a revisão, escolha a pessoa que revisaria o PR e passe pelas especificações de produto/tecnologia com ela antes de chegar na parte de codificação.
Nesta fase, alinhamos como os serviços, endpoints, schemas, 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 é ok 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. Arquitetura tem alavancagem bastante alta e há muitos tiques potencialmente ruins do modelo 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 criminosamente subestimado em codificação agentic: design do programa.
A maioria das pessoas assume que, uma vez que a arquitetura está certa, 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 chamadas.
A primeira versão da nossa habilidade de design de programa foi horrível. Era difícil de ler, era exaustiva. Tentamos mermaid, que tem seu lugar, mas o que realmente amamos são visualizações leves em pseudocódigo:
Árvores de pilha de chamadas, 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 do seu processo de planejamento, e acho que é exatamente isso.
Diffs de árvore de arquivos - para que você mantenha contato com o layout do seu codebase e onde as coisas ficam
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 rascunha, você discute com ele), e cada um deles é uma decisão que você 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 "tracer bullets" em uma live em janeiro de 2026 - também é conhecido como tracer bullets
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, 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 foi 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 trabalhava para fora. Vagamente:
- Criar contrato da API e servir dados mock, testar com curl
- Criar frontend para consumir dados mock, iterar e polir no navegador
- Conectar API à camada de serviços (serviços servem dados mock/comportamento)
- Adicionar migrações de banco de dados, conectar serviços ao banco
- Adicionar um monte de lógica de negócio
- Adicionar um monte de tratamento de erros
E eu estava 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 codebase, estou revisando o código em cada etapa também. Verificar 100-200 linhas e redirecionar é muito mais barato.
Aqui, eu faria. A maioria dos modelos de fronteira não vai projetar um plano como este sem direção humana, e é difícil generalizar por codebase ou mesmo por tarefa, então prefiro ficar no loop aqui. Acredite em mim. Se eu pudesse terceirizar o pensamento
30 minutos de planejamento economizam horas de revisão
E assim temos alguns passos que eu diria que os humanos precisam estar envolvidos, se você quiser manter um nível de qualidade próximo ao humano sem se matar sobre montanhas de código slop tentando limpá-lo depois. (ou seja, 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 lançamos (veja a sidequest abaixo). Eu diria que a distribuição é aproximadamente:
- ~40% das tarefas são disparo único ou disparo único com 1-2 rodadas de feedback leve
- para tarefas médias, fazemos design de produto/sistema tudo em um único documento de plano, e não nos preocupamos em dividir o trabalho em fases
- para coisas grandes, fazemos todos os passos. Pulamos a parte de 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 enquanto avanço. É muito mais fácil redirecionar no início, seja sobre os internos ou a funcionalidade real, do que acabar do outro lado de mais 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 ótimo PR é uma alegria de revisar. Você está rolando por cada arquivo, o código está limpo, segue todas as suas decisões/discussões/opiniões conquistadas a duras penas sobre como o software deve ser.
Por outro lado, se um Pull Request precisa de pelo menos 20% de retrabalho (e isso é generoso, diria que a maioria dos PRs de disparo único de IA tende a ficar perto de 50%), isso é tanto um fardo intelectual quanto 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 te poupar 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 simplesmente 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, nem tão bons em outras. Como você otimiza seu processo à luz dessas restrições?
Modelos são bons em algumas coisas, nem 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 desastres ou pelo menos que você se divertiu vendo algumas animações fofas.
Obrigado por ler
-dex
PS Somos obcecados por isso
Estamos construindo humanlayer.com, uma IDE agentic e plataforma de colaboração para ajudar você a se mover 2-3x mais rápido enquanto mantém um nível humano (ou bem próximo do humano) de qualidade de código.
Estamos construindo em direção a duas ideias: "blocos de construção para sua fábrica de software" e "melhores verificadores para manutenibilidade de software" (talvez até modelos melhores).
HumanLayer é gratuito para pequenas equipes de até 3 pessoas, e se você quiser ajuda para começar, pode vir bater um papo no nosso discord ou nos enviar uma linha em founders@humanlayer.dev
Um agradecimento rápido ao @calvinfo pela inspiração, ao meu cofundador @0xBlacklight, ao @swyx e ao time do @aiDotEngineer por me dar uma arena para explorar essas ideias, e a todos os nossos incríveis clientes, investidores, amigos e familiares torcendo por nós.
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 longo, etc, abaixo.
PPS Outros recursos
Podcasts e Artigos:
- Dex e Gergely falam sobre engenharia de contexto e fábricas de software no The Pragmatic Engineer - Julho 2026
- Dex e Matt Pocock falam sobre conselhos atemporais de codificação com IA (e ralph loops) - Janeiro 2026
Episódios do AI That Works:
- Benchmarks não provam nada
- Especificações de Produto para Codificação com IA
- Testes de Aprendizado para melhor backpressure
- Aplicando princípios de agentes de 12 fatores à codificação com IA
Links deste post:
- Por que as Fábricas de Software Falham - keynote — AI Engineer World's Fair 2026
- Fábrica de software lights-off 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 slop"
- FT: Quedas da Amazon por acidentes com agentes de codificação
- Matt Pocock: codebases se desfazendo
- Faros AI: o relatório de chicotada de aceleração da IA
- Engenharia Avançada de Contexto para Agentes de Codificação (palestra 25/08)
- No Vibes Allowed (palestra 25/11)
- Tudo Que Erramos Sobre RPI (palestra 26/03)
- Awesome-RLVR - Recursos de Aprendizagem por Reforço
- Engenharia Avançada de Contexto para Agentes de Codificação (artigo)
- Agentes de 12 Fatores
- Addy Osmani sobre vibe-coding vs. manutenção
- Conferência de Engenharia de Software da OTAN, 1968
- Documento de Referência de DevSecOps do DoD (PDF)
- Plataforma de agente de codificação da Ramp
- Stripe: Minions, agentes de codificação ponta a ponta de disparo único
- WorkOS: Projeto Horizon
- Brex (Latent Space)
- Dan Shapiro: os cinco níveis para 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 SWE-Agent (2024)
- Palestra 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 / tracer bullets (live, Jan 2026)
- "O trabalho duro de pensar não pode ser terceirizado" (Jake Nations)
