# O que é uma software factory para agentes de código (e o que ela não é)

> Um agente escreve código. Uma fábrica decide o que acontece com esse código antes de ele chegar na main.

- Por: Djan Magno
- Publicado em: 2026-09-19
- Atualizado em: 2026-09-19
- URL: https://t25.io/blog/o-que-e-uma-software-factory-para-agentes-de-codigo/
- Guias · software factory, agentes de código, claude code, codex, pipeline de desenvolvimento, human in the loop

> **Resumo:** > - Uma **software factory para agentes de código** é a camada que recebe uma tarefa e a conduz por estados fixos (spec, plano, aprovação, implementação, QA, review, pull request) usando agentes de código como mão de obra.
> - O agente escreve. A fábrica decide: qual papel roda agora, em que diretório, com que limite, e quando o trabalho para numa pessoa.
> - Ela **não** é um agente melhor, nem um IDE, nem um merge automático. É a política em volta dos agentes que você já usa.

## A definição curta

Uma software factory para agentes de código é um orquestrador que transforma um pedido em linguagem natural num pull request revisável, passando por uma sequência de estados que ninguém pula. Cada estado é executado por um agente com um papel definido (planner, dev, QA, reviewer, security), e a passagem de um estado para o outro é decidida por código determinístico, não pelo próprio agente.

A palavra "fábrica" é literal. Numa linha de produção, quem aperta o parafuso não decide se o carro sai do pátio. Há estações, inspeção entre elas e um responsável que assina a saída. Trocar "parafuso" por "diff" e "pátio" por "main" dá a ideia.

## Por que um agente sozinho não basta

Claude Code, Codex e Cursor já escrevem código bom o suficiente para mudar a forma como times trabalham. O problema deixou de ser "o agente consegue fazer isso?" e passou a ser "como eu confio no que ele fez, em escala, sem ler cada linha no terminal?".

Rodar um agente direto no seu checkout tem três custos que crescem com o uso:

1. **O agente se autoavalia.** Quem escreveu o código também diz se está pronto. Um relatório que termina em "APPROVE" é um palpite do modelo, não uma verificação.
2. **O estado é implícito.** Não existe um lugar que diga "esta tarefa está no QA, falhou duas vezes, está esperando a aprovação do plano". Existe uma conversa no terminal.
3. **O raio de explosão é o repositório inteiro.** O agente trabalha no mesmo diretório que você, com o mesmo branch e as mesmas credenciais.

Uma fábrica existe para tornar essas três coisas explícitas: quem avalia, em que estado a tarefa está e onde o agente pode mexer.

## O percurso de uma tarefa

No T25, uma tarefa atravessa esta máquina de estados. As transições permitidas ficam num único arquivo (`src/core/state-machine.ts`) e nenhuma parte do sistema muda o estado sem passar por ela.

| Estado | O que acontece | Quem decide a saída |
|---|---|---|
| `RECEIVED` | A tarefa entra com texto livre, tipo e nível de risco | Triagem |
| `SPEC` | O pedido vira critérios de aceite verificáveis, com checklist | **Humano** (aprova a spec) |
| `PLAN` | O planner corta o trabalho em fatias | Parser do plano |
| `AWAITING_APPROVAL` | A fábrica para e espera uma pessoa, conforme o risco | **Humano** |
| `IMPLEMENTING` | Agentes de dev escrevem código num worktree isolado | Limites de diff |
| `QA` | Testes e checagens; falha volta para `IMPLEMENTING` | Veredito de QA |
| `REVIEW` | Reviewer e security leem o diff; findings em escopo devolvem o trabalho | `evaluateReview()` |
| `PR_OPEN` | O pull request existe e espera o merge | **Humano** |
| `DOCS` → `DONE` | Documentação pós-merge | Pipeline |

Três estados de escape (`NEEDS_INPUT`, `FAILED`, `CANCELLED`) existem para quando a tarefa precisa de uma resposta, quebrou ou foi abandonada. O que importa na tabela é a última coluna: há três pontos em que só uma pessoa move a tarefa. A spec é sempre aprovada por alguém, o plano depende do risco, e o merge é sempre humano.

## As quatro peças que fazem uma fábrica

### 1. Estados com transições fechadas

Se qualquer parte do código pode escrever `task.state = 'DONE'`, você não tem uma fábrica, tem um script. Centralizar as transições em uma função que recusa movimentos ilegais é o que permite confiar no quadro. QA pode devolver para implementação; review também. Implementação não pode pular direto para pull request.

### 2. Papéis separados, com fallback

Planner, dev, QA e reviewer são papéis diferentes, cada um com seu prompt e suas referências. No T25, cada papel tem uma **lista de preferência** de CLIs, não um CLI fixo. Por padrão o dev de backend tenta Codex, depois Claude, depois Kimi. Se um CLI não está instalado ou autenticado, a fábrica usa o próximo da lista. Isso tira a dependência de um fornecedor sem exigir chave de API: os agentes rodam com a assinatura que você já paga.

### 3. Isolamento por tarefa

Cada tarefa ganha o próprio `git worktree` e o próprio branch. Nenhum agente de implementação roda no checkout principal. Isso tem um post inteiro: [Uma ordem, um worktree](https://t25.io/blog/uma-ordem-um-worktree-isolando-agentes-de-codigo/).

### 4. Gates que não dependem do modelo

A aprovação do plano é decidida por política (o risco da tarefa e a configuração do projeto). O resultado do review é recalculado a partir dos findings, não copiado do veredito que o modelo escreveu. Isso também tem um post: [O APPROVE do modelo não é o merge](https://t25.io/blog/o-approve-do-modelo-nao-e-o-merge/).

## O que uma software factory não é

**Não é um agente novo.** O T25 não tem modelo próprio e não compete com Claude Code, Codex ou Cursor. Ele chama esses CLIs.

**Não é merge automático.** "Dark factory" é o termo usado para fábricas que rodam sem ninguém olhando. Dá para chegar perto disso em tarefas de baixo risco, mas o merge na main continua sendo uma decisão humana no T25, por desenho.

**Não é um IDE.** Você não edita código dentro da fábrica. Ela produz um pull request, e o pull request é revisado onde você já revisa.

**Não é só um prompt comprido.** Um prompt que diz "planeje, depois implemente, depois teste" ainda deixa o modelo decidir quando cada etapa terminou. A fábrica tira essa decisão dele.

## Limites contra o agente que não para

Todo mundo que usou agente de código já viu um reescrever meio repositório para corrigir um teste. A fábrica mede o diff depois da implementação e reprova quando ele passa dos limites configurados. Os padrões do T25 são 40 arquivos alterados e 2000 linhas de diff, mais um detector de linhas duplicadas para pegar copy-paste em massa. Os números mudam por projeto; o importante é que o limite existe fora do agente.

Também existe teto de tentativas: um erro que se repete não vira um loop infinito de "vou tentar de novo".

## Quando faz sentido usar uma

Uma fábrica compensa quando o gargalo deixou de ser escrever código e virou **revisar** código. Dois perfis sentem isso primeiro:

- **O operador solo** que já roda dois ou três agentes em paralelo e perde a conta de qual terminal estava fazendo o quê.
- **O time com revisor escasso**, em que o sênior passa o dia lendo diffs gerados e precisa que cada um chegue com plano, testes e review já feitos.

Se você roda um agente por vez, numa tarefa que acompanha do começo ao fim, o CLI direto provavelmente basta. A fábrica começa a pagar quando há mais tarefas do que atenção.

## Perguntas frequentes

### Software factory é o mesmo que dark factory?

Não exatamente. Software factory é a estrutura: estados, papéis, gates e isolamento. Dark factory é um modo de operar essa estrutura com o mínimo de intervenção humana. O T25 é uma software factory que mantém o merge humano de propósito.

### Preciso de chave de API para usar o T25?

Não. O T25 chama os CLIs de agente que já estão instalados e autenticados na sua máquina, então usa a assinatura que você já tem com cada ferramenta.

### O T25 substitui o Claude Code ou o Codex?

Não. Eles continuam escrevendo o código. O T25 decide em que ordem cada papel roda, em que diretório e com que limites, e para a tarefa quando ela precisa de uma pessoa.

### O código sai da minha máquina?

O T25 é self-hosted: o orquestrador, o banco e os worktrees ficam no seu ambiente. O que cada CLI de agente envia para o próprio provedor segue a configuração daquele CLI.