Funcionou ontem. E hoje?

Foi numa feira, entre duas palestras, com um café ruim na mão. Um tech lead olhou o cartão e perguntou sem rodeio:

“Eu já uso o Claude Code. Meu time já usa o Codex. Por que eu precisaria do ArchGenerator?”

E antes que eu respondesse, ele mesmo completou: “E, mais importante: como eu provo que preciso?”

A primeira pergunta eu ouço toda semana. A segunda quase nunca é feita em voz alta — mas é a que importa. Vou responder as duas, começando pelo que é verdade e não me favorece: Claude Code, Codex e Cursor são ferramentas extraordinárias. Eu uso todos os dias. Elas mudaram a forma como eu trabalho, e não é retórica de palco.

1. O que os agentes fazem bem

Um agente de código te leva de “será que dá?” a “dá, e está rodando” numa tarde. Uma PoC, uma demonstração para a diretoria, um laboratório para testar uma API nova, uma ferramenta interna — e, em muitos casos, um sistema inteiro em horas ou dias, com código bem escrito, tipado, testado. Para a pergunta “isso é possível?”, não existe nada melhor.

O que ainda deixa a desejar é outra coisa: o desenvolvimento de ponta a ponta, do pedido até o sistema que continua funcionando meses depois. O agente é excelente em execução e indiferente a continuidade — não por limitação técnica, mas porque continuidade não é o que ele foi desenhado para otimizar.

Existe uma tentação simétrica, e ela é minha, não dele: aplicar um processo pesado em algo descartável. Montar projeto estrutural, ART e vistoria para erguer uma barraca de praia. Não faz sentido. Boa parte do que se constrói com agente é barraca, e tudo bem.

Agente puro: te leva de “será que dá?” a “está rodando” numa tarde.

ArchGenerator: não tem nada a ver com essa etapa. Ele entra quando a barraca precisa virar casa, ou quando a casa já está de pé e ninguém sabe se aguenta vento.

2. Onde dá errado

Há cerca de um mês construí uma ferramenta de conteúdo para mídias sociais. Um dia. Com skills que eu mesmo escrevi, com orientação detalhada, com o cuidado de quem já viu isso dar errado. Funcionou de ponta a ponta: gerava, publicava, registrava. Fiquei satisfeito.

No dia seguinte, a saída mudou. Uma API externa tinha parado de responder do jeito que respondia. Não sabia o que tinha mudado, quando, nem por quê. O sistema não quebrou de forma barulhenta — ele passou a produzir um resultado diferente, e eu só descobri porque olhei.

Isso não é falha do agente. É o comportamento esperado de quem foi instruído a entregar a tarefa recebida. Diante de um obstáculo — um teste que não passa, uma integração instável, um requisito ambíguo —, o caminho de menor resistência é o que faz a tarefa parecer concluída: um valor fixo no lugar da consulta, um tratamento de erro que engole a falha, um teste ajustado ao código em vez do código ajustado ao requisito. Para o agente, a missão foi cumprida. E, naquela sessão, foi mesmo.

O que falta não é capacidade. É um vigia. Algo que observe o trabalho, lembre o combinado, cobre a prova de pronto e recoloque o agente nos trilhos quando ele simplifica demais. Sem vigia, não há spec que sobreviva à sessão, não há teste que prove o comportamento de ontem, não há registro de decisão que explique a escolha de anteontem.

Não é preciso ir longe para ver o tamanho do problema quando ninguém está olhando. Em dezembro de 2025, um agente de código encarregado de um ajuste pequeno no AWS Cost Explorer concluiu que o caminho mais eficiente para um estado sem bugs era recriar o ambiente de produção. O resultado foi um apagão de 13 horas em uma região da China continental, e o post-mortem apontou controles de acesso mal configurados (Docker Blog). E o ecossistema inteiro ficou mais instável: uma comparação de status pages de 11 empresas de SaaS entre jan/2024–abr/2025 e mai/2025–set/2026 não encontrou alta generalizada de incidentes, mas achou alta justamente entre fornecedores de ferramentas de desenvolvimento — GitHub +86% no total e +137% nos graves (análise).

A tese deste artigo cabe numa linha: construir é diferente de dar continuidade. A primeira coisa um agente faz sozinho. A segunda exige vigilância e engenharia.

3. O que é o ArchGenerator

O ArchGenerator não substitui o seu agente. Ele não tem um agente melhor, não compete com o Claude Code nem com o Codex, e não quer que você largue o Cursor.

O que ele faz é entregar um kit SDD — Spec Driven Development — que roda dentro do agente que você já usa. Uma pasta .sdd/ no repositório, versionada junto com o código, com quatro camadas: uma Constituição de 25 artigos e um artigo “bis”, cada regra ligada a um mecanismo concreto que a faz valer; 27 papéis (Analista, PO, Designer, Arquiteto, Desenvolvedor, QA, Auditor de Segurança, Arqueólogo de Legado e por aí); ferramentas Python sem dependências externas — sensores, ganchos que bloqueiam ações, guarda de dependências, SAST, banco de mutantes; e memória entre sessões, para que a sessão de amanhã não comece do zero.

Na plataforma, os laudos técnicos fazem a outra metade: medir o sistema que já existe com evidência ancorada, antes de decidir o que fazer com ele.

A metáfora que eu uso: o agente é o pedreiro. Excelente profissional, rápido, resolve coisa que ninguém resolvia. O ArchGenerator é o projeto, o mestre de obras, o fiscal e o laudo de vistoria. O pedreiro continua sendo o mesmo. O que muda é que agora existe um vigia — e cada um dos dez pontos a seguir é uma forma concreta de esse vigia agir.

4. As dez formas do vigia agir

1) A spec sobrevive à sessão

Agente puro: a intenção mora no chat. Quando a sessão fecha, ela fecha junto. Amanhã o agente deduz — e deduzir é adivinhar com educação.

ArchGenerator: a spec é a fonte da verdade — brief, PRD, design, arquitetura e stories versionados no repositório. Toda sessão começa com um bootstrap que carrega o estado antes de qualquer linha ser escrita.

2) Laboratório primeiro

A velocidade do agente brilha no laboratório E cada experimento tem README obrigatório: objetivo, hipótese, setup, resultado medido e decisão explícita — APROVADO, REJEITADO ou PRECISA_MAIS_TESTES. Benchmark exige métrica com condições e limite aceitável. Experimento rejeitado nunca é apagado: vai para o arquivo com o motivo. A story referencia o experimento; mais de cem já passaram por esse rito. Falhar no laboratório é barato. Falhar em produção é caro.

3) Contrato assinado antes do código

Agente puro: o escopo é aquilo que parecer razoável às três da manhã.

ArchGenerator: o escopo é cláusula — o quê, critérios de aceite, sensores que provam, número máximo de tentativas. Necessidade nova exige renegociação; nos kits de correção, uma cláusula proíbe mudar além do achado. Mais lento no primeiro dia, muito mais rápido no trigésimo.

4) Quem implementa não aprova

O Desenvolvedor leva a story até “em revisão”. Só o QA marca pronto, com evidências anexadas. Um gancho bloqueia a passagem — “o agente deveria ter feito” virou “o agente não consegue avançar”. Dos nossos contratos, 62 já levaram ao menos uma reprovação do QA.

5) Sensores decidem

Cada sensor tem comando, critério, responsável e indicação de bloqueio: unidade, integração, e2e no navegador, suíte completa duas vezes na base do deploy, acessibilidade, desempenho. Dezoito regras de integridade vigiam a própria governança. Após cinco tentativas sem verde, o caso escala para um humano — o agente não fica em loop se enganando.

6) Testes que provam os testes

Cada regra de cada sensor tem um sabotador: o QA injeta mutantes no código da story. Sensor verde com o defeito presente é sensor decorativo — e isso é falha. As lições vieram do atrito: asserção que usa valor padrão passa sem o dado existir; oráculo que o próprio defeito preserva. O agente escreve testes. O ArchGenerator prova que funcionam.

7) Segurança em cada mudança

Tudo offline, sobre o que a story alterou. A guarda de dependências consulta OSV e o catálogo KEV da CISA, cruza gravidade com probabilidade de exploração e bloqueia pacote malicioso, já explorado, crítico ou alto — mostrando a versão que corrige —, lendo npm, pnpm, yarn, pip, uv, Pipfile, Maven e Composer. O SAST roda nas linhas alteradas com regras curadas e versionadas (licença permissiva, origem, hash), e supressão só existe com nome da regra e justificativa. Exceção tem motivo, responsável e prazo: 30 dias para explorada, 90 para as demais, nunca para malicioso. Há um papel de Auditor de Segurança, e o princípio é simples: nada fica verde por não ter sido olhado — fica “não verificável”. O volume justifica o rigor: a Cloud Security Alliance cita levantamento da Apiiro em dezenas de milhares de repositórios de Fortune 50, com achados mensais de segurança saindo de cerca de 1.000 para mais de 10.000 em seis meses (CSA Labs).

8) Lastro em toda afirmação

Toda frase técnica carrega seu selo: [A] ancorada em arquivo:linha, [P] presumida e a validar, [Q] em aberto. A diferença é prática. “Tem um problema de autenticação” é opinião. “[A] três credenciais fixas em src/auth/config.ts:42; [P] sessão sem expiração, validar em homologação” é um plano — e o [P] tem um sensor cobrando a validação.

9) Memória de processo

Decisões, dívidas técnicas, rastreabilidade e handoff por linha. Isso permite, por exemplo, Claude Code e Codex trabalhando em paralelo no mesmo repositório sem se atropelarem. O próprio ArchGenerator é feito com o kit: centenas de stories, mais de 800 contratos, cerca de 470 decisões e mais de 500 dívidas registradas. É um sistema que se explica.

10) Laudos e Evolução

A plataforma mede o que já existe: arquitetura, saúde do código, dívida, domínio e integrações, segurança, banco, prontidão de migração. Os artefatos vêm de referências conhecidas — grafo de dependências e ciclos, hotspots de complexidade × frequência de mudança no git, mapa de domínio, plano de remediação em ondas — e o índice de saúde vem acompanhado da confiança do índice, separando o que foi medido do que foi presumido. Na Evolução, uma nova medição mostra resolvidos, persistentes e novos; o achado tem identidade estável, então mudar de linha não o torna novo; e quando não houve mudança relevante, o sistema reaproveita a varredura elegível em vez de repetir tudo, com custo e condições mostrados no produto antes da confirmação. Do laudo nasce um kit de correção com stories, evidência transcrita e sensores apontando para caminhos reais. O laudo aponta, o kit executa, o próximo laudo confere. Você mede.

5. O custo honesto

Não vou vender isso como grátis. É mais lento no começo: uma hora vira uma tarde ou um dia. Esse tempo volta com juros — mas em produção, não em código descartável. Exige disciplina de quem assina: o sistema propõe, o dono decide, e o ArchGenerator nunca decide por você. Gera mais documentação, e isso incomoda quem gosta de trabalhar só no chat.

E não é mágico. Já tivemos testes verdes que não mediam nada. É exatamente por isso que o processo se audita — mutação, lastro, regra de integridade — e por isso o banco de mutantes existe.

6. Quando usar cada um

Situação	Agente puro	ArchGenerator
PoC, demo, hackathon	✅ melhor opção	exagero
Testar API ou biblioteca	✅	✅ no laboratório, se for alimentar produção
Ferramenta interna de uma semana	✅	opcional
Sistema usado por outros que precisa continuar funcionando	arriscado	✅
Legado que ninguém entende	arriscado	✅ laudo + kit de correção
Auditoria de código gerado por IA	não produz trilha	✅ trilha por construção
Vários agentes ou pessoas no mesmo repositório	conflitos	✅ papéis, contratos e handoff

O resumo da tabela é a divisão de trabalho que eu defendo: velocidade do agente no laboratório, disciplina do kit na produção, laudos para medir o caminho.

7. Como comprovar em quatro semanas

Não acredite em mim. Rode o experimento.

1. Escolha uma ferramenta real, pequena, que alguém vá usar de verdade.
2. Faça duas versões com o mesmo agente — uma com o kit, outra sem.
3. Gere um laudo de cada uma no dia 1.
4. Use de duas a quatro semanas com as mesmas mudanças nas duas.
5. Meça de novo: achados críticos e altos, regressões, tempo por mudança e o quanto você consegue explicar o sistema depois de uma semana parado.

Minha aposta, declarada de antemão: o agente puro ganha a primeira semana. O kit ganha o resto. E os laudos medem — os dois lados.

A pergunta que me fizeram na feira envelheceu. Não é mais “dá para construir?”. É “vai continuar funcionando quando eu não estiver olhando?”. As dez formas do vigia são a minha resposta: a spec que sobrevive, o laboratório, o contrato, o QA, os sensores, a mutação, a segurança, o lastro, a memória e o laudo.

Use o agente para descobrir o que é possível. Use o ArchGenerator para que o que você construiu continue funcionando.