Problema
Usar agentes de IA para gerar código rápido é fácil; difícil é manter qualidade arquitetural, aderência ao domínio e ausência de regressões ao longo de meses em sistemas reais. Sem estrutura, o ganho inicial de velocidade se transforma em dívida técnica, código duplicado e bugs sutis introduzidos por suposições da IA.
O desafio era transformar a IA de um "gerador de trechos" em um processo de engenharia previsível, aplicável tanto em ambiente corporativo com equipe enxuta (modernização de sistema legado) quanto em produto próprio em produção (Fit Tracker).
Restrições
- Zero alucinação em infraestrutura crítica: em bancos de dados corporativos, o agente não pode adivinhar nomes de colunas nem executar alterações destrutivas por conta própria.
- Economia de contexto e custo: sessões longas sem especificação clara degradam a qualidade das respostas e desperdiçam tokens.
- Verificabilidade objetiva: nenhuma tarefa pode ser considerada "pronta" apenas porque a IA afirmou que terminou; o resultado precisa passar por gates determinísticos.
Decisão
Chosen
Fluxo SDD + TDD com gates determinísticos antes de cada commit
Discarded alternative
Prompting ad-hoc direto no editor sem especificação ou validação automática
Escrever uma spec curta adiciona minutos no início da tarefa, mas economiza horas de revisão e evita que a IA construa a abstração errada em alta velocidade.
- Spec curta (critérios + fora de escopo)
- Leitura real via MCP (somente-leitura)
- Testes falhando (TDD)
- Implementação incremental
- Gates (build, lint, testes, paridade)
Desenvolvi e passei a operar diariamente um harness combinado de SDD (Spec-Driven Development) + TDD, estruturado em quatro pilares:
- Fluxo Spec → Testes → Implementação: cada entrega começa com uma especificação curta (objetivo, critérios de aceite e o que fica fora de escopo), seguida pela geração de testes automatizados e só então pela implementação até os testes passarem.
- Inspeção segura via MCP: utilização de servidor MCP somente-leitura para SQL Server para consultar schemas, tabelas, relacionamentos e planos de execução reais antes de escrever qualquer query ou código de acesso a dados.
- Gates determinísticos de conclusão: skills e hooks que exigem saída verde de
build,typecheck,lint, testes unitários/E2E e — no caso de relatórios migrados — validação de paridade com o legado antes do commit. - Automação prática no dia a dia: aplicação do mesmo ferramental para resolver gargalos operacionais reais, como pipelines de extração estruturada de planilhas de contratos em PDF para carga estruturada no banco de dados.
Resultado
- Fluxo adotado no desenvolvimento diário da modernização do sistema legado corporativo e do Fit Tracker (produto em produção), além deste próprio portfólio (
verri.dev), cujo repositório documenta as specs e os testes desde o primeiro commit. - Redução expressiva de retrabalho e de erros de contrato/schema, pois o agente valida tipos, queries e testes contra o ambiente real antes de concluir qualquer etapa.
- Capacidade de coordenar e entregar projetos de alta complexidade mantendo padrão consistente de código, testes e documentação.
O que aprendi
- O diferencial não está no prompt mágico, e sim no harness: contexto bem estruturado, ferramentas de leitura confiáveis (MCP) e gates de verificação automática valem mais do que qualquer ajuste cosmético de prompt.
- Spec curta economiza horas de revisão: alinhar critérios de aceite e escopo negativo antes do código evita que a IA construa a solução errada com extrema eficiência.
- Engenharia assistida por IA aproxima gestão e execução: quem coordena consegue validar decisões arquiteturais com protótipos testados e manter visibilidade real sobre a qualidade do que entra em produção.