O texto de Qudrat Ullah no freeCodeCamp, “How to Build a Software Factory with Claude Code”, é o playbook prático mais limpo publicado este ano sobre como uma pessoa desenvolvedora mais Claude Code vira um time coordenado. Sete subagentes especializados. Três portões de aprovação humana. Ganchos como aplicação determinística. CLAUDE.md como camada de contrato. Duas a três horas para colocar a primeira versão de pé. A maior parte dos textos sobre “codificação agêntica” fala em metáforas; Ullah entrega uma especificação construível.
Concordamos com quase todos os primitivos. A arquitetura é sólida. O que vem a seguir não é uma crítica. É o passo natural em cima da cadeia que ele propôs: o eixo de medição que o playbook deixa em aberto.
Duas Fábricas, Uma Palavra
A palavra “fábrica” agora aponta para dois objetos diferentes, e os dois são reais.
Existe a fábrica em nível de organização: o manifesto da StrongDM de que nenhum humano escreve código e nenhum humano revisa código, com disciplinas de governança (cenários, DTU, Weather Report, CXDB) embutidas como arquitetura. Essa é uma fábrica em formato de empresa, e já escrevemos sobre como as disciplinas dela funcionam como política embutida na arquitetura.
O texto de Ullah descreve a outra fábrica: a fábrica em nível de repositório. Uma pessoa desenvolvedora, uma máquina, Claude Code como força de trabalho, um arquivo CLAUDE.md como constituição. Ambas são objetos de governança. Não estão em tensão. A fábrica organizacional diz como uma engenharia inteira torna a cadeia responsável. A fábrica de repositório diz como uma pessoa contribuinte transforma a mesma ideia em um arnês funcional dentro de uma base de código.
O resto deste texto trata da fábrica de repositório, porque foi isso que Ullah especificou, e é isso que a maioria dos times vai adotar primeiro.
O Que Ullah Acertou Exatamente
Um inventário curto dos primitivos que endossamos sem modificação:
Sete papéis com acesso a ferramentas escopado. Um codebase-researcher que só lê. Um story-writer e um spec-writer que produzem artefatos. Um backend-builder, frontend-builder, test-verifier e implementation-validator que fazem o trabalho e checam o trabalho. Cada subagente tem uma descrição de cargo e uma lista de ferramentas permitidas. Os papéis são diferentes porque as ferramentas são diferentes, que é a única razão honesta para separar agentes.
Três portões de aprovação humana. Depois da história. Depois do spec. Antes do PR. Ullah é explícito de que esses portões não são negociáveis. A frase com que ele fecha o texto, “Cloud AI is not a teammate. Accountability stays with the human”, é o enquadramento certo. Portões de aprovação não são fricção; são onde mora a autoria.
Ganchos como aplicação determinística. As recomendações de ganchos de Ullah se alinham com a tese de camada determinística que cobrimos quando Dabit e Wolfe publicaram na mesma semana. Os seis eventos de ciclo de vida são os primitivos certos. Um gancho SessionStart que carrega contexto do projeto. Um gancho PreToolUse que bloqueia edições em caminhos proibidos. Um gancho Stop que se recusa a declarar conclusão até os testes passarem. Código, não persuasão.
“Use AI to automate structured work, not chaotic work.” A melhor frase-mantra de disciplina do ano. Ela exclui toda a classe de prompts “deixa o agente descobrir” que produz os modos de falha de que todo mundo reclama.
Reinicie a conversa. Ullah nomeia desvio de contexto como um modo de falha real e prescreve a solução mais simples possível: jogue a sessão fora, comece limpo, deixe os artefatos carregarem o estado. É instinto de praticante, e está correto.
CLAUDE.md dimensionado em 100 a 300 linhas. Agentes especializados, não agentes-deus. Artefatos como meio de transporte de estado. Cada uma dessas é uma decisão estrutural e Ullah nomeia todas.
O Eixo Que Falta: A Fábrica Está Melhorando?
É aqui que a construção em cima começa.
Ullah ensina como montar a fábrica. Ele não ensina como saber se ela está melhorando. Não tem capítulo sobre instrumentação. Depois de duas a três horas de setup, você tem uma cadeia funcional. Depois de dois meses de uso, você não tem ideia se a cadeia está ficando melhor, se está derivando, ou se está silenciosamente queimando seu tempo.
Esse é o problema de medição do centauro aplicado uma camada abaixo. Já argumentamos antes que a unidade de medição certa no desenvolvimento de software com agentes é o par, não o modelo: humano mais IA como um único objeto de performance. A fábrica de Ullah é um centauro. Sete subagentes mais três portões de aprovação mais uma pessoa responsável pelo PR. Para saber se esse centauro está ficando mais rápido, mais confiável, mais honesto, você precisa de números em cima da cadeia.
Sem esses números, a fábrica de sete agentes é um loop de vibe coding mais disciplinado, ainda não é um sistema que aprende. É mais rápida do que prompting livre. Ela desliza na mesma direção em que prompting livre desliza, e você não consegue provar o contrário.
Três Números para Instrumentar
Os três eixos abaixo não são exaustivos. São o mínimo que uma pessoa operadora de fábrica deveria colocar em um CSV ao lado do repositório, começando na segunda-feira.
1. Confiabilidade por agente
Quando o implementation-validator sinaliza um defeito crítico, qual builder produziu? Quando o test-verifier traz à tona um teste instável, foi escrito pelo frontend-builder ou pelo backend-builder? Sem atribuição por agente, roteamento de modelo é palpite e atualização de prompt vira teologia.
Definição operacional: para cada PR que fecha, registre qual subagente foi autor do artefato que o próximo portão rejeitou ou aceitou. Depois de trinta PRs, você tem uma taxa de aceitação por agente. Depois de noventa, dá para ver qual seção do CLAUDE.md de cada agente precisa afiar, e qual já está puxando o peso dele. Esse é o loop que a cadeia de Ullah ainda não fecha sozinha.
2. Latência de portão de aprovação
Três portões humanos significa três filas. Acompanhe o tempo de relógio que a pessoa humana leva em cada um: revisão de história, revisão de spec, revisão de PR. Se revisão de história dura em média 90 segundos e revisão de PR dura em média 45 minutos, o gargalo humano está na camada errada. O portão de história não está fazendo nada; o portão de PR está fazendo o trabalho que os portões anteriores deveriam ter absorvido.
Essa é a métrica que diz se os artefatos anteriores (história, spec) estão de fato puxando o peso deles. Uma fábrica saudável tem latência de portão que cai conforme você desce a cadeia, porque cada portão filtrou mais do trabalho que o próximo teria que refazer. Uma fábrica doente tem os três portões comprimidos em uma única sessão de PR de noventa minutos, o que significa que as rodadas de história e spec foram cerimônia.
3. Frequência de restart
Ullah nomeia “jogar a conversa fora” como saudável. Ele não dá uma taxa a partir da qual isso vira patológico. Propomos uma: conte.
Frequência de restart é o número de sessões por semana que são resetadas antes de produzir um PR. Se está em uma ou duas por semana, você está rodando uma fábrica normal e limpando ruído de contexto do jeito que Ullah recomenda. Se sobe para uma por dia, seu CLAUDE.md ou suas definições de agente estão vazando, e o que parece trabalho produtivo é na verdade uma esteira de recarregar contexto. O restart vira o bug, não a solução.
Acompanhe. Plote semanalmente. Uma fábrica que reinicia diariamente está depurando um problema de contexto, não construindo software.
Quanto Isso Custa para Adicionar
Seja honesto consigo antes de procurar um fornecedor: nenhum dos três números exige um.
Um CSV ao lado do repositório. Um gancho PostToolUse que coloca timestamp em cada aprovação e escreve uma linha por portão. Uma revisão semanal de quinze minutos da saída do validator agrupada pelo builder que produziu. Duas horas de disciplina de operação por semana, em cima das duas a três horas que Ullah especificou para colocar a fábrica de pé. O custo marginal de instrumentar é erro de arredondamento perto do custo de uma fábrica que você não consegue provar que está melhorando.
Dá para adicionar dashboard depois. Comece com o CSV.
Fechamento
A frase mais limpa do texto de Ullah é a que já começou a aparecer em outros posts: “The teams that get there first will not be the ones with the best AI tools. They will be the ones who built the cleanest factories around the AI tools they already have.”
Está exatamente certo, e tem uma emenda honesta. A fábrica mais limpa só vence se você consegue provar que ela está ficando mais limpa. Uma fábrica instrumentada é uma fábrica que aprende. Uma fábrica sem instrumentação é um loop de vibe coding mais rápido com mais arquivos.
Ullah desenhou a linha de montagem. O placar vai em cima. Construa a cadeia este mês. Pendure os números na parede no mês que vem. No terceiro mês você vai saber se o centauro do seu repositório está mesmo ficando mais rápido, ou se você só andou ocupado de um jeito mais bem organizado.
Fontes
- freeCodeCamp / Qudrat Ullah. “How to Build a Software Factory with Claude Code.” Maio de 2026.
- freeCodeCamp / Qudrat Ullah. “How to Unblock the AI PR Review Bottleneck.” 2026.
A Victorino ajuda times de engenharia a instrumentar suas fábricas de agentes para que a cadeia que entrega código consiga provar que está ficando melhor: contato@victorino.com.br | www.victorino.com.br
Todos os artigos do The Thinking Wire são escritos com o auxílio do modelo LLM Opus da Anthropic. Cada publicação passa por pesquisa multi-agente para verificar fatos e identificar contradições, seguida de revisão e aprovação humana antes da publicação. Se você encontrar alguma informação imprecisa ou deseja entrar em contato com o editorial, escreva para editorial@victorino.com.br . Sobre o The Thinking Wire →
Se isso faz sentido, vamos conversar
Ajudamos empresas a implementar IA sem perder o controle.
Agendar uma Conversa