Fundamentos de Engenharia
Controle determinístico sobre modelos probabilísticos.
Esta seção explica por que o SpecForge funciona, não apenas como usá-lo. Se você só quer entregar código, o Início Rápido é por ali. Se você quer entender os princípios de engenharia que garantem o comportamento do SpecForge sob condições adversas — fique.
O Problema
Large Language Models são probabilísticos. Dada a mesma entrada duas vezes, podem produzir saídas diferentes. Dada uma tarefa complexa, podem alucinar restrições que não existem, pular requisitos que existem, ou tomar decisões arquiteturais que contradizem decisões anteriores.
Isso não é um bug. É a natureza fundamental do sistema. Probabilidades, não determinismo.
A maioria das ferramentas de IA para código aceita isso e compensa com revisão humana. O humano lê a saída, encontra os erros, corrige, re-executa. Isso funciona para um agente em uma tarefa. Não funciona para cinco agentes em cinquenta tarefas. O humano se torna o gargalo — exatamente o gargalo que a IA deveria eliminar.
A pergunta que o SpecForge responde: como impor comportamento determinístico a um sistema probabilístico sem eliminar as qualidades do sistema probabilístico?
A resposta vem de uma disciplina que resolve exatamente essa classe de problema há mais de 80 anos.
Teoria de Controle Aplicada a Agentes de IA
Teoria de controle é a disciplina de engenharia que faz sistemas se comportarem de forma previsível apesar de perturbações. Um termostato é um controlador. Um piloto automático é um controlador. Um loop PID em uma planta industrial é um controlador. Em todos os casos, o padrão é o mesmo: um sinal de referência define o alvo, um comparador mede o erro, e um loop de feedback direciona o erro para zero.
O comparador recebe duas entradas: o que deveria acontecer (referência) e o que está realmente acontecendo (feedback). Ele computa o erro. A planta recebe o erro e corrige. O loop se repete até que o erro esteja dentro da tolerância.
O Loop de Controle do SpecForge
O SpecForge se mapeia diretamente a essa arquitetura:
| Teoria de Controle | SpecForge |
|---|---|
| r (Referência) | Especificação — critérios de aceitação, guardrails, arquivos esperados, passos de implementação. Fixo. |
| Σ (Comparador) | MCP server — a lógica dentro do complete_work_session. Recebe a spec (r) e os resultados de validação, computa o que falta. |
| e (Sinal de erro) | Prompt injection — “você não terminou. Estes critérios de aceitação não foram atendidos. Estes arquivos estão faltando.” Específico, acionável. |
| Planta | Agente de IA — o elemento probabilístico. Recebe correções, produz código. O único componente não-determinístico. |
| D (Perturbação) | Alucinação — ruído no agente. Ele recebe instruções corretas mas pode produzir saída incorreta. |
| Saída | Código implementado — os arquivos, testes, commits produzidos pelo agente. |
| H(s) (Feedback) | Validações — status dos critérios de aceitação, checagem de existência de arquivos, conformidade com guardrails, git diff. |
Na prática, o loop funciona assim:
- O agente recebe um ticket com sua especificação: critérios de aceitação, passos de implementação, arquivos esperados, guardrails.
- O agente implementa. Alucinação pode introduzir erros — estrutura de arquivos errada, critérios de aceitação faltando, violações de guardrails.
- O agente chama
complete_work_sessionpara finalizar. - O MCP server (comparador) verifica: Todos os critérios de aceitação foram satisfeitos? Todos os arquivos esperados existem? Guardrails foram respeitados?
- Se não: o MCP server rejeita a conclusão e injeta um prompt de volta para o agente com exatamente o que falta. Este é o sinal de erro.
- O agente corrige com base no feedback específico.
- O agente tenta completar novamente. O MCP server verifica novamente.
- O loop se repete até que todas as checagens passem — ou
maxReviewAttemptsacione a parada de segurança.
O agente não sabe que está em um loop de controle. Ele acha que está tentando completar uma tarefa. O MCP server é o controlador invisível — medindo a saída contra a referência e injetando correções quando o erro é diferente de zero.
Tudo neste loop é determinístico exceto o agente. A spec é fixa. O comparador é algorítmico (checagens booleanas). A validação é estrutural (existência de arquivos, status dos ACs). O código é código. O sistema inteiro existe para domar o único elemento probabilístico.
Sistemas Open-Loop vs Closed-Loop
O Termômetro (open-loop)
A maioria das ferramentas de IA para código é open-loop. Elas mostram a saída e deixam você decidir o que está errado. O agente não tem mecanismo para se auto-corrigir. O humano é o loop de feedback. Isso é um termômetro — ele te diz a temperatura mas não a controla. Você lê o número e ajusta o dial sozinho.
O Termostato (closed-loop)
O SpecForge é closed-loop. O MCP server mede a saída contra a especificação automaticamente. O humano define a temperatura (especificação). O sistema a mantém. O humano define 22°C e vai embora.
A especificação é fixa. O agente implementa. O MCP server valida: ACs atendidos? Arquivos existem? Guardrails respeitados? Se não, o sinal de erro volta para o agente como prompt injection com exatamente o que falta. O loop fecha no MCP server. O humano intervém apenas quando o sistema precisa de uma decisão — não quando precisa de supervisão.
Resposta ao Degrau — Como Sistemas Convergem
Este é o gráfico que todo engenheiro de controle reconhece. A resposta ao degrau mostra o que acontece quando um sistema recebe uma tarefa e tenta atingir o alvo. Como ele chega lá — ou não — revela tudo sobre o design do sistema.
No contexto do SpecForge: o “degrau” é um agente recebendo um ticket para implementar. O alvo é zero desvio da spec. A pergunta é: como a saída converge para o alvo ao longo de iterações sucessivas?
Quatro comportamentos são possíveis. Cada um mapeia para uma classe de ferramenta de IA:
Sem Controlador (Instável) — O sistema oscila sem convergir. Cada correção introduz um novo erro. Isso é vibe coding: Lovable, Bolt, v0.
Sub-amortecido (Babysitter Agent) — Oscila mas eventualmente converge após 12-15 iterações. Overshoot grande: o agente reescreve um módulo inteiro quando só uma função precisava de mudança. Isso é Devin, Cursor Agent em modo autônomo.
Super-amortecido (Spec-Driven Manual) — Sem oscilação, mas convergência glacialmente lenta. 10+ iterações porque o humano revisa cada linha. Isso é Sweep, CodePlan, e a abordagem manual cuidadosa.
Criticamente Amortecido (SpecForge) — Mínimo overshoot, converge em 2-3 iterações. O MCP server detecta exatamente quais ACs não foram atendidos, quais arquivos estão faltando. O sinal de erro é específico: não “tente novamente” mas “AC #3 não atendido e auth.middleware.ts não foi criado.” O sistema converge rápido porque o feedback é preciso.
maxReviewAttempts (default: 3) é o limite de segurança — o equivalente em teoria de controle de uma parada de segurança em um sistema instável.
O Grafo de Dependências como Espaço de Restrição
Em teoria de controle, você não apenas controla a saída — você restringe o espaço de estados. Um piloto automático não apenas mira no destino; ele restringe a aeronave a faixas seguras de altitude, envelopes de velocidade e corredores de aproximação. O espaço de restrição impede o sistema de atingir estados onde a recuperação é impossível.
O grafo de dependências serve a mesma função. Não é uma lista de tarefas. É um espaço de restrição que impede agentes de atingir estados inválidos: Agente B não pode começar até que a saída do Agente A passe na validação. Dependências circulares são rejeitadas no planejamento. Isolamento de ticket garante que cada agente opera dentro de seu próprio contexto limitado. Sem o grafo de dependências, agentes em paralelo são irrestritos — Agente A escolhe Prisma, Agente B escolhe Drizzle, e o código diverge.
Estabilidade e Convergência
Um sistema de controle é estável se o erro diminui ao longo do tempo e converge para zero. O loop de revisão do SpecForge é projetado para convergência:
Planning Review previne condições iniciais instáveis — capturando specs falhas antes de qualquer código ser escrito. maxReviewAttempts (default: 3) é uma guarda de convergência — se o sistema não convergiu após 3 iterações, ele para e requer intervenção humana. Critérios de aceitação fornecem medição de erro multi-eixo — não “está bom?” mas “AC #1 foi atendido? arquivos esperados existem? guardrails foram respeitados?”
Por Que Isso Importa
Toda ferramenta de IA para código afirma “orquestrar agentes.” A maioria delas são sistemas open-loop com um dashboard. Elas mostram o que aconteceu. Você decide o que fazer a respeito.
SpecForge é um sistema de controle em malha fechada. A especificação é o sinal de referência. O MCP server é o comparador. O agente é a planta. O grafo de dependências é o espaço de restrição. O prompt injection com findings específicos é o sinal de erro.
Isso não é uma metáfora. É a arquitetura de engenharia literal.
E é por isso que o sistema escala. Sistemas open-loop escalam linearmente — mais agentes, mais revisão humana necessária. Sistemas closed-loop escalam por design — mais agentes, mesmo comparador, mesmas garantias. O MCP server não se importa se há 5 workers ou 50. Ele mede saída contra referência e computa erro. É isso que controladores fazem.
“Ele não sabia que era impossível e fez.”
Leitura Adicional
- Quality Gates — O comparador em detalhe: dimensões de scoring, thresholds, configuração
- Ciclos de Vida — Os três ciclos que estruturam o loop fechado
- Sessões de Trabalho — Como o MCP server gerencia o loop de controle por ticket