Como construir uma fábrica de software com agentes de IA: do briefing ao deploy

Resumo em uma frase: uma fábrica de software com agentes não nasce de um agente melhor, mas de uma esteira em que briefing vira especificação, especificação vira tarefa, tarefa vira pull request e pull request só chega ao cliente depois de passar por portas que a IA não consegue abrir sozinha.

Existe uma diferença grande entre usar IA para programar e operar uma linha de produção de software com agentes. A primeira acelera uma pessoa dentro do editor. A segunda muda a unidade de trabalho: o insumo deixa de ser o prompt e passa a ser a especificação, e o produto deixa de ser o trecho de código e passa a ser a entrega revisada, testada e publicada.

Este artigo é o manual de construção dessa segunda coisa. Ele descreve as camadas de uma fábrica de software operada por múltiplos agentes, o que cada uma precisa produzir, onde ficam as portas de aprovação humana e como medir custo, qualidade e tempo sem se enganar.

A base conceitual está em orquestração de agentes de IA com governança, que trata de quando multi-agentes se justificam e quais riscos vêm junto. Aqui o recorte é operacional: como montar a esteira.

Resumo do artigo

• A fábrica tem quatro camadas: especificação, decomposição em tarefas, execução por agentes especializados e integração com repositório, CI/CD e hospedagem.
• O ganho de qualidade vem de tirar decisões do agente, não de dar mais liberdade a ele: contratos, scaffolds, design system e testes de arquitetura definem o caminho antes da primeira linha de código.
• Quatro portas humanas seguram a esteira: especificação, contratos, pull request de código sensível e liberação de produção.
• A métrica que importa é custo por entrega aceita, que inclui tokens, tempo de revisão e retrabalho. Custo por token isolado é um número que engana.

O que é uma fábrica de software com agentes

Uma fábrica de software com agentes é uma esteira em que a demanda entra em linguagem natural e sai como software publicado, com rastro de decisão em cada etapa. O que a define não é a quantidade de agentes, e sim três propriedades:

• Unidade de trabalho declarada. Existe um artefato formal, a especificação, entre o pedido do cliente e o código. Sem ele, cada agente reinterpreta o briefing do seu jeito.
• Fronteiras que o agente não move. Padrões da casa, contratos de API, design system e regras de arquitetura vivem fora do agente e são impostos por máquina.
• Portas de saída. Nada chega ao cliente sem passar por testes determinísticos e, nos pontos críticos, por uma pessoa.

Se qualquer uma das três faltar, o que existe é um time usando IA rápido, o que já é valioso, mas não é uma fábrica. A diferença aparece no dia em que a mesma demanda precisa ser reproduzida, auditada ou refeita por outra pessoa.

O fluxo completo, do briefing ao link do cliente

O desenho abaixo é a esteira inteira. Chamamos de Forge a camada de orquestração que ocupa as etapas 2 a 5: ela é quem transforma pedido em plano, plano em tarefas e tarefas em trabalho distribuído entre agentes.

Briefing, a demanda do cliente em linguagem natural, com regras, restrições e o que não pode mudar

Especificação, o agente especificador converte o briefing em escopo, contratos, critérios de aceite e riscos

Aprovação da especificação, a primeira porta humana, antes de existir uma linha de código

Tarefas, o orquestrador quebra a especificação em unidades pequenas com dependência declarada

Agentes especializados, front-end e back-end em runtimes separados, cada um com as skills e os scaffolds do padrão da casa

Pull request, uma branch por tarefa, com diff, testes e justificativa da decisão tomada

Testes e revisão, CI determinística em tudo e revisão humana no que for irreversível

Deploy e validação, ambiente publicado e link para o cliente aprovar o que foi entregue

Repare que a IA aparece em três etapas das oito. As outras cinco são engenharia comum: versionamento, testes, ambientes e revisão. É essa proporção que separa uma fábrica de uma demonstração.

Camada 1: o agente especificador

O papel mais subestimado da esteira é o primeiro. O agente especificador não escreve código: ele transforma um pedido ambíguo em um documento que outro agente consegue executar sem adivinhar.

O que ele precisa devolver, sempre:

1. Escopo negativo, o que explicitamente não entra nesta entrega. É o campo que mais evita retrabalho.
2. Contratos, o formato dos dados e das rotas antes de existir implementação, porque é isso que permite front-end e back-end avançarem em paralelo.
3. Critérios de aceite, escritos como verificação, não como desejo. "O usuário consegue exportar" não serve; "ao clicar em exportar com filtro aplicado, o CSV traz apenas as linhas filtradas" serve.
4. Riscos e decisões em aberto, a lista do que ele não conseguiu resolver sozinho e precisa de resposta humana.
5. Impacto no que já existe, quais telas, rotas e tabelas serão tocadas.

O último item costuma ser o que falha. Um agente especificador que só leu o briefing produz uma especificação bonita e desconectada do sistema real. Ele precisa de acesso de leitura ao repositório, ao esquema do banco e à documentação de arquitetura para dizer onde a mudança encosta.

Camada 2: decomposição em tarefas

Especificação aprovada, o orquestrador quebra o trabalho. O tamanho da tarefa é uma decisão de engenharia, não um detalhe: tarefa grande demais produz pull request que ninguém revisa, e tarefa pequena demais multiplica custo de contexto e de coordenação.

A régua prática que usamos:

A dependência declarada é o que permite paralelismo real. Quando o contrato da API existe como artefato versionado, o agente de front-end pode trabalhar contra um mock gerado a partir dele enquanto o agente de back-end implementa o outro lado. Sem esse contrato, os dois adivinham e o encontro só acontece na integração, que é o pior lugar para descobrir divergência.

Camada 3: agentes executores e a distribuição entre modelos

Aqui entra a decisão que mais gera discussão: usar o mesmo modelo para tudo ou rotear por competência.

Rotear compensa por dois motivos independentes. O primeiro é competência: front-end e design premiam consistência visual, leitura de interface e fidelidade a um design system, enquanto back-end premia raciocínio sobre estado, dados, concorrência e regra de negócio. São habilidades diferentes, e os modelos não são igualmente bons nas duas. O segundo é preço: dentro de um mesmo projeto, existe trabalho caro de pensar e trabalho barato de repetir, e pagar o preço do primeiro pelo segundo é desperdício puro.

O critério de roteamento que funciona não é "qual modelo é melhor", e sim:

• O erro aqui é visível para o cliente? Se sim, use o modelo mais forte disponível. Tela e texto que o cliente vê não comportam economia.
• A tarefa é repetitiva e verificável por teste? Se sim, use o modelo mais barato que passa nos testes. CRUD, migração de padrão e variação de componente entram nesta linha.
• A tarefa exige entender o sistema inteiro? Se sim, o custo está no contexto, não no modelo. Antes de trocar de modelo, reduza o que ele precisa ler.

Esse último ponto merece uma seção própria, porque é onde a maior parte do dinheiro vaza.

Skills, scaffolds e o problema de reler o projeto inteiro

Um agente que precisa reler o repositório a cada tarefa é caro e impreciso. Caro porque contexto se paga por token. Impreciso porque quanto mais texto irrelevante entra na janela, maior a chance de o modelo ancorar na parte errada.

A solução não é um modelo com janela maior. A própria Anthropic descreve o fenômeno como context rot: conforme a janela cresce, o desempenho degrada, porque a arquitetura do modelo cria relações par a par entre todos os tokens presentes. Mais contexto não é mais competência, é mais ruído com custo.

A saída é estruturar o conhecimento da casa em peças que o agente carrega sob demanda:

Cada peça resolve um problema específico:

Instruções de repositório. Um arquivo de convenções na raiz, lido automaticamente, com o que vale para qualquer tarefa naquele projeto: como rodar, como testar, o que nunca mexer, qual o padrão de commit. É o contexto que não deveria precisar ser redescoberto. A recomendação oficial da Anthropic para esse arquivo é manter menos de 200 linhas, justamente porque um arquivo inchado consome contexto e reduz a aderência às próprias instruções que ele carrega.

Skills, ou instruções reutilizáveis por tipo de tarefa. "Como criar um endpoint neste projeto", "como adicionar uma tela ao painel", "como escrever uma migração segura". O agente carrega apenas a skill correspondente à tarefa, e não o manual inteiro. É o mesmo princípio de um procedimento operacional: quem vai trocar o pneu não lê o manual do motor.

O mecanismo tem nome e tem número. Na implementação da Anthropic, uma skill se apresenta em três níveis: apenas nome e descrição ficam sempre carregados, ao custo aproximado de 100 tokens por skill; o corpo das instruções só entra quando a skill é acionada, na casa de poucos milhares de tokens; e os arquivos anexos custam zero até serem lidos. Com dez procedimentos catalogados, o agente paga mil tokens para saber que eles existem e carrega só o que a tarefa exige. É a diferença entre uma biblioteca com índice e uma pilha de papel.

Scaffolds. Um esqueleto de projeto ou de módulo já no padrão, gerado por comando. Grande parte das decisões arquiteturais ruins de um agente acontece em terreno vazio, quando ele precisa inventar estrutura. Scaffold elimina o terreno vazio.

Design system como código. Se os componentes existem, são tipados e estão documentados, o agente compõe em vez de recriar. Se não existem, ele inventa um botão novo por tela, e a inconsistência só aparece na revisão visual, tarde demais.

Como impedir decisões arquiteturais ruins

A tentação é resolver isso com prompt: pedir educadamente que o agente siga o padrão. Não funciona de forma confiável, porque instrução em linguagem natural é sugestão, e sugestão falha em escala.

O que funciona é retirar a decisão do agente. Quatro mecanismos, do mais barato ao mais forte:

1. Geração a partir do contrato, tipos e clientes de API gerados do OpenAPI ou do schema, não escritos à mão. O agente não pode divergir de um arquivo que ele não escreve.
2. Testes de arquitetura, regras executáveis do tipo "a camada de domínio não importa nada da camada de infraestrutura". Quebrou, a CI reprova, e o agente recebe o erro e corrige sozinho.
3. ADRs curtos e uma constituição do projeto, o registro de por que uma decisão foi tomada e a lista curta de princípios inegociáveis, lidos antes de qualquer iteração. O conceito aparece com esse nome em ferramentas de desenvolvimento orientado a especificação, como o Spec Kit da GitHub, e serve para impedir que o próximo agente reabra uma discussão já encerrada.
4. Fronteira de permissão, o agente que implementa uma tela não tem escrita no diretório de migrações. Menor privilégio vale para agente igual vale para pessoa.

A regra que resume os quatro: o agente propõe, o sistema decide. Toda vez que a fábrica depender da boa vontade do modelo, ela vai falhar em algum momento sem avisar.

Vale notar que a própria documentação do Claude Code é explícita nesse ponto: arquivo de instruções e memória são tratados como contexto, não como configuração obrigatória, e para bloquear uma ação independentemente do que o modelo decidir existe um gancho de ciclo de vida que roda antes do uso da ferramenta e pode reprovar a chamada. Ou seja, quem desenhou a ferramenta já assume que instrução em texto não é garantia. Uma fábrica séria trabalha com a mesma premissa.

As portas de aprovação humana

Autonomia total é uma meta ruim. A meta certa é autonomia dentro de trilhos, com portas nos pontos em que o erro é caro ou difícil de reverter. São quatro.

1. Porta 1 antes do código
   Aprovação da especificação

   É a porta mais barata e a mais rentável. Corrigir escopo aqui custa uma conversa; corrigir depois do deploy custa uma sprint.

2. Porta 2 antes da implementação
   Aprovação dos contratos

   Modelo de dados, rotas e formatos. Depois que front-end e back-end forem construídos em cima, mudar contrato vira mudança em cascata.

3. Porta 3 antes do merge
   Revisão do pull request

   Obrigatória em autenticação, permissão, cobrança, dado pessoal e migração de banco. Nas demais áreas, a CI decide e a revisão vira amostragem.

4. Porta 4 antes de produção
   Liberação do deploy

   Homologação publica sozinha. Produção exige aprovação registrada, com plano de rollback pronto.

O detalhe que faz diferença é onde essas portas moram. Se elas existem só como combinado do time, elas cedem sob pressão de prazo. Se moram na plataforma, como regra de proteção de branch, revisão obrigatória por dono de código, verificação de status obrigatória e ambiente com aprovação, elas não cedem. Vale a pena tratar a configuração do repositório como parte do produto.

Repositório, CI/CD e hospedagem: onde a fábrica encosta no mundo

A entrega do agente não é o código: é o pull request. E o pull request só vira valor quando a esteira ao redor dele está pronta.

O arranjo mínimo:

• Uma branch por tarefa, nomeada a partir do identificador da tarefa, para que o rastro do briefing até o commit seja reconstituível.
• Pull request com contexto, contendo o que foi pedido, o que foi feito, o que ficou de fora e como testar. Um PR de agente sem essa descrição transfere trabalho de arqueologia para o revisor.
• CI que reprova cedo, com lint, tipos, testes e verificações de arquitetura rodando antes da revisão humana. Revisor não deveria ser o primeiro a descobrir que o teste quebrou. Como acelerar essa etapa está em CI/CD para times pequenos.
• Ambiente de pré-visualização por PR, publicado automaticamente, com um endereço próprio. É esse link que fecha o ciclo com o cliente, e é a peça que transforma "está pronto" em "veja funcionando".
• Separação real entre homologação e produção, tema tratado em ambientes de homologação e produção.

Vale copiar as decisões que as próprias plataformas tomaram, porque elas funcionam como manual de boas práticas. O GitHub, ao lançar seu agente de codificação, fixou três regras: o agente trabalha em branch com prefixo próprio, os workflows do pull request ficam congelados até que uma pessoa com permissão de escrita clique para liberar a execução, e o agente não pode aprovar nem fazer merge do próprio pull request, restrição que se estende a quem pediu o trabalho a ele. São exatamente os três controles que faltam nas fábricas improvisadas.

Vale registrar também um risco que aparece exatamente aqui: um agente com acesso ao repositório lê issues, comentários e dependências, e todos esses são canais por onde instrução maliciosa pode entrar. Isso deixou de ser hipótese. Em junho de 2026, uma pesquisa de segurança publicou uma cadeia de ataque que começa com a abertura de uma issue pública no GitHub e termina com código malicioso no repositório de uma action amplamente usada, combinando falha de verificação de permissão com prompt injection para roubar credenciais do runner. Uma variante da mesma configuração insegura foi explorada de verdade contra outro projeto meses antes.

Tratar conteúdo lido pelo agente como dado, e nunca como comando, é requisito de segurança, não refinamento. Na prática isso significa não deixar agente ser disparado por conteúdo de terceiros sem revisão, usar identidade federada de curta duração em vez de chave de API guardada como segredo do repositório, e conceder ao aplicativo do agente o conjunto mínimo de permissões. O tema está detalhado em como proteger chatbots e agentes contra prompt injection.

Como medir custo, qualidade e tempo

Fábrica sem medição vira aposta cara. E a métrica mais usada, custo por token, é justamente a que mais engana, porque uma entrega barata que volta duas vezes custa mais que uma entrega correta na primeira.

A conta que importa é custo por entrega aceita:

A primeira linha da tabela costuma ser tratada como impossível, e não é. Os principais fornecedores expõem hoje APIs administrativas de uso e custo: a Anthropic tem endpoints de relatório de uso e de custo na Admin API, com filtro e agrupamento por chave, workspace e modelo, e a OpenAI expõe custos por projeto em endpoint equivalente. Ambas exigem uma chave administrativa, diferente da chave usada pela aplicação. A consequência prática é simples: crie uma chave ou um projeto por cliente desde o primeiro dia. Separar consumo depois, com tudo misturado em uma conta única, é impossível.

Existe um caminho ainda mais direto para quem usa ferramentas de agente no terminal: exportar telemetria por OpenTelemetry. O Claude Code, por exemplo, publica métricas como custo em dólares por sessão, contagem de tokens, linhas de código, número de commits, número de pull requests e até as decisões de permissão em ferramentas de edição, que funcionam como registro dos gates humanos. Com isso, custo e entregas ficam na mesma série temporal, sem depender de relatório manual.

Três indicadores de qualidade valem mais que qualquer painel:

• Taxa de PR aceito sem retrabalho. Percentual de pull requests de agente que entram sem exigir uma segunda rodada. É o termômetro direto da qualidade da especificação.

Para essa primeira métrica existe até uma referência externa. Um estudo empírico analisou milhares de pull requests abertos por agentes em repositórios públicos do GitHub e mediu a taxa de merge por ferramenta:

Fonte: estudo empírico com 9.799 pull requests agênticos revisados por humanos no GitHub, 2026.

Dois detalhes do mesmo estudo importam mais que o ranking. Apenas 35,7% das rejeições refletiam falha clara do agente: 31,2% caíram por restrição de processo ou workflow, e o restante ficou sem evidência suficiente. E entre os PRs aprovados, 15,4% exigiram envolvimento humano explícito para chegar lá. Traduzindo: boa parte do que a fábrica perde não se perde na qualidade do código, e sim no desenho do processo ao redor dele. Vale também lembrar que a amostra é de código aberto, o que costuma ser mais favorável do que uma base proprietária e legada.

Os outros dois indicadores:

• Regressão pós-merge. Quantos incidentes vieram de código que passou pela esteira. Se sobe, a CI está frouxa, não o modelo.
• Tempo de fila de revisão. Assim que a fábrica funciona, o gargalo migra para a revisão humana. Medir isso cedo evita a ilusão de que basta gerar mais.

O contrapeso honesto

Um artigo sobre fábrica de agentes que só mostra o ganho é peça de marketing. Vale registrar o que a evidência pública ainda não sustenta.

Primeiro, ganho de velocidade não é automático nem uniforme, e o dado mais desconfortável é sobre percepção. O ensaio randomizado do METR, publicado em 2025, acompanhou 16 desenvolvedores experientes em 246 tarefas reais dentro de repositórios maduros em que eles já trabalhavam há anos. Antes de começar, eles estimavam que a IA reduziria o tempo em 24%. Depois de terminar, ainda achavam que tinham economizado 20%. O tempo medido foi 19% maior.

Vale ler esse número com o mesmo cuidado que os autores pedem: eles afirmam explicitamente que o estudo não é evidência de que IA não acelera a maioria dos desenvolvedores, nem em outros contextos, nem no futuro. O cenário era justamente o mais difícil: base grande, madura, com padrão de qualidade alto e gente de casa. É o pior caso, e é útil justamente por isso. Pesquisa apresentada por Stanford e citada pelo relatório DORA aponta o mesmo formato de resposta: ganho de 35% a 40% em código novo e simples, e de 10% ou menos em código legado complexo. Esses percentuais foram apresentados em conferência e ainda não publicados em artigo, então valem como indício de padrão, não como medida fechada.

Segundo, volume de código não é entrega. O relatório DORA de 2025, com quase 5.000 respondentes, encontra relação positiva entre adoção de IA e throughput, e ao mesmo tempo mantém relação positiva entre adoção de IA e instabilidade de entrega. O relatório de 2026 dá nome ao custo escondido: verification tax, o tempo extra investido em teste e revisão para dar conta do volume maior de saída, e modela a adoção como uma curva em J, com queda temporária de produtividade antes do retorno.

No mesmo espírito, a GitClear, que analisa mudanças de código em escala, reporta em 2026 uma queda expressiva das linhas classificadas como refatoração e alta na duplicação de blocos quando comparado a 2023. São dados de uma empresa comercial, sem revisão por pares, e devem ser lidos como sinal de tendência e não como prova causal. Mas a direção casa com o que descrevemos em vibe coding e regressões: a dívida de manutenção escala junto com a fábrica se ninguém estiver olhando para ela.

Terceiro, custo de multi-agente é superlinear, e existe número público para isso. Quando a Anthropic descreveu o próprio sistema multi-agente de pesquisa, em junho de 2025, registrou que arquiteturas desse tipo consomem por volta de 15 vezes mais tokens que uma interação de chat comum, enquanto um agente único já consome cerca de 4 vezes mais. O contexto é replicado em cada ramo, e alguém paga por isso.

Dois cuidados ao usar esse dado: ele veio de uma avaliação interna, na geração de modelos daquela época, e tratava de tarefas de pesquisa, não de engenharia de software. A conclusão que viaja bem não é o múltiplo exato, e sim a direção: multi-agente é uma troca explícita de custo por qualidade. Ela se justifica quando o trabalho é genuinamente paralelizável, excede o que cabe em um agente só e produz resultado verificável. Não se justifica para tarefas simples, em que um agente único bem instruído entrega igual por uma fração do preço.

Quarto, autonomia sem porta é risco acumulado. Um agente que abre pull request, aprova o próprio pull request e faz deploy não é uma fábrica avançada: é uma fábrica sem controle de qualidade.

Roteiro de implantação em 90 dias

Ninguém monta a esteira inteira de uma vez. A ordem abaixo é a que dá resultado mais cedo com menos risco.

Checklist antes de chamar de fábrica

• Existe uma especificação aprovada por uma pessoa antes de qualquer código
• Contratos de dados e de API estão versionados e geram tipos automaticamente
• A CI reprova sozinha o que sai do padrão de arquitetura
• Nenhum agente consegue fazer merge ou deploy em produção sem aprovação registrada
• Consumo de tokens está atribuído por projeto, não em uma conta única
• Existe número de taxa de aceitação sem retrabalho e ele é acompanhado

Se os seis itens estiverem marcados, você tem uma linha de produção. Se faltarem três ou mais, o que existe é um time rápido usando IA, que é um bom lugar para estar, mas não sobrevive à primeira auditoria nem ao terceiro cliente simultâneo.

Perguntas frequentes

Leia também

• Orquestração de agentes de IA com governança
• Criou um app com IA? Do protótipo à produção
• Qual IA usar para criar protótipos de software em 2026

Conclusão

A pergunta que abre um projeto de fábrica de software com agentes não é "qual modelo vamos usar". É: o que precisa ser verdade no nosso repositório para que um agente consiga trabalhar aqui sem quebrar nada?

Quem responde essa pergunta primeiro descobre que boa parte do trabalho é engenharia clássica: contratos, testes, ambientes, permissões e revisão. A IA entra depois, e entra melhor, porque encontra trilhos em vez de terreno aberto.

O objetivo final continua o mesmo desde antes dos agentes: transformar uma demanda de negócio em software que funciona, com custo previsível e sem surpresa em produção. A diferença é que agora dá para fazer isso com uma esteira, e não com heroísmo.

Referências

• How we built our multi-agent research system, Anthropic Engineering
• Effective context engineering for AI agents, Anthropic Engineering
• Writing tools for agents, Anthropic Engineering
• Agent Skills: visão geral e progressive disclosure
• Claude Code: subagentes, memória e instruções de repositório e hooks
• Usage & Cost Admin API, Anthropic
• Measuring the impact of early-2025 AI on experienced open-source developer productivity, METR e o paper no arXiv
• DORA, State of AI-assisted Software Development 2025 e The ROI of AI-assisted Software Development, 2026
• GitClear, pesquisa sobre qualidade e manutenibilidade de código com IA
• GitHub: regras disponíveis para rulesets de branch e environments com aprovação
• OWASP Top 10 for LLM Applications

Documentação e números verificados em 6 de agosto de 2026. Os dados do sistema multi-agente da Anthropic são de junho de 2025 e referem-se à geração de modelos daquela data.