Uma metodologia de 12 passos para engenharia com IA: do UML à entrega
Escrever código com apoio de um agente de IA torna a primeira versão mais rápida a produzir.
Não torna, sozinho, essa versão correcta, segura ou fácil de manter — e sem processo, o ganho de velocidade inicial costuma transformar-se em dívida técnica e correcções repetidas mais tarde.
Estes são os 12 passos que a PontoTi segue, na prática, para levar um pedido desde o desenho até à produção, com IA como ferramenta dentro de cada passo e não como substituto do processo.
1. Definir o problema e os critérios de sucesso
Antes de qualquer desenho ou código, escrever em uma ou duas frases o que muda para o utilizador ou para a operação quando o trabalho estiver concluído, e como se vai saber que resultou — não "melhorar o sistema", mas um critério verificável.
Um agente de IA a que se pede "resolve isto" sem um critério de sucesso claro tende a produzir uma solução plausível para o problema errado.
2. Levantar requisitos e restrições reais
Que dados existem já, que sistemas têm de continuar a funcionar sem alteração, que limites de tempo, orçamento ou conformidade se aplicam. Restrições não documentadas nesta fase aparecem tarde, normalmente já em código, onde custam mais para corrigir.
3. Modelar antes de escrever código (UML e equivalentes)
Um diagrama de casos de uso mostra quem interage com o sistema e porquê; um diagrama de classes mostra as entidades principais e as suas relações; um diagrama de sequência mostra a ordem real das chamadas num fluxo crítico.
Não é preciso UML completo e formal para cada tarefa pequena, mas para qualquer funcionalidade com mais do que um actor ou mais do que um sistema envolvido, um esboço destes obriga a pensar na estrutura antes de a IA gerar a primeira linha de código — e dá ao agente um contexto muito mais preciso do que uma descrição em prosa.
4. Registar a decisão de arquitectura antes de a implementar
Um documento curto — o que se decidiu, porque, que alternativas se rejeitaram e porquê — evita que a mesma decisão seja discutida outra vez três meses depois, e dá a um agente de IA que trabalhe no código mais tarde o histórico que precisa para não contradizer uma escolha já tomada por boas razões.
Esta prática (Architecture Decision Record) é exactamente o que sustenta, por exemplo, o ficheiro de decisões técnicas do projecto Astro da PontoTi.
5. Prototipar antes de comprometer a arquitectura final
Um protótipo descartável, mesmo gerado rapidamente com IA, serve para validar uma hipótese técnica arriscada antes de a integrar na base de código principal.
O objectivo do protótipo é aprender, não entregar — se ele nunca for para produção sem reescrita, cumpriu o papel.
6. Separar o que é cálculo determinístico do que é gerado por IA
Nem tudo o que um sistema produz devia vir de um modelo de linguagem.
Dados que podem ser calculados com regras claras — preços, datas, posições astronómicas, validações — devem sê-lo de forma determinística, auditável e reproduzível; a IA deve ficar reservada para o que genuinamente precisa de interpretação ou geração de linguagem natural.
Misturar as duas coisas sem esta separação explícita é uma das causas mais comuns de sistemas de IA que produzem resultados diferentes para a mesma pergunta, ou que "alucinam" factos que deviam ser um simples cálculo.
7. Implementar de forma incremental, com testes automatizados desde o início
Pedaços pequenos e verificáveis, cada um com um teste que falha antes da implementação e passa depois.
Um agente de IA a gerar uma funcionalidade inteira de uma vez, sem testes intermédios, é muito mais difícil de rever com confiança do que a mesma funcionalidade dividida em passos que cada um se pode confirmar isoladamente.
8. Revisão humana do que a IA propôs
Um agente de IA pode gerar uma alteração plausível, bem formatada e que passa nos testes existentes, e ainda assim estar errada de uma forma que só um humano com contexto de negócio detecta — por exemplo, uma regra de preço tecnicamente correcta mas comercialmente errada.
A revisão humana não é uma formalidade depois da IA: é o ponto onde o julgamento que a IA não tem entra no processo.
9. Validar qualidade além dos testes automáticos
Casos de fronteira, entradas hostis, dados reais em vez de apenas dados de exemplo, e uma verificação adversarial deliberada — tentar activamente provar que a solução está errada antes de a considerar pronta.
Testes automáticos confirmam que o código faz o que o programador pensou que devia fazer; a validação de qualidade confirma que essa ideia estava certa.
10. Implantar por fases, com possibilidade real de recuar
Ambiente de testes antes de produção, lançamento faseado quando o risco o justifica, e um plano de rollback que já foi pensado antes de ser preciso — não improvisado a meio de um incidente.
Uma alteração que só pode avançar, nunca recuar, transforma qualquer erro de produção numa emergência maior do que precisava de ser.
11. Observar depois de entregar, não só antes
Alertas com informação legível e acionável, registo de execuções e erros, e verificação periódica de que o que foi entregue continua a funcionar como esperado — não apenas no dia do lançamento.
Um sistema sem observabilidade só revela que algo correu mal quando um cliente ou um colega o reporta, o que é sempre mais tarde e mais caro do que detectar internamente.
12. Fechar o ciclo: documentar e iterar
Actualizar a decisão registada no passo 4 se algo mudou durante a implementação, anotar o que se aprendeu, e tratar o resultado como ponto de partida da próxima iteração, não como um fim definitivo.
Um processo de engenharia que não se actualiza com o que a própria equipa aprendeu a repetir os mesmos erros, com ou sem IA a ajudar a escrever o código.