Defender o Apex: difícil, quase sempre bem, e críticas justas
Notas da defesa do meu mestrado, a 23 de outubro de 2026: o que foi difícil, o que correu bem e onde o júri teve razão.
O valor da assistência por IA em engenharia de software depende do processo que a rodeia, e não apenas do modelo.
Uma framework de processo para usar IA ao longo do ciclo de vida do software com as pessoas no controlo, e o Apex, a aplicação web que a implementa.
As ferramentas de IA para programação foram adotadas mais depressa do que qualquer método para as usar bem. Esta tese propõe uma framework de processo que trata a IA como um colaborador delimitado, validado e rastreado ao longo de todo o ciclo de vida do software, e constrói o Apex para a demonstrar em funcionamento.
A Inteligência Artificial Generativa e os Modelos de Linguagem de Grande Dimensão passaram de assistentes de preenchimento automático a contribuidores activos no Ciclo de Vida de Desenvolvimento de Software, permitindo exprimir requisitos em linguagem natural e supervisionar os artefactos gerados. A adopção ultrapassou o método. Uma Revisão Sistemática da Literatura sobre 646 artigos confirma benefícios substanciais a par de riscos recorrentes de fiabilidade, segurança, rastreabilidade e responsabilização, e identifica a ausência de orientação estruturada e repetível para integrar estas ferramentas em contextos profissionais como o principal problema por resolver. Concluindo então que o valor depende do processo, não apenas da capacidade do modelo em questão. Esta dissertação aborda essa lacuna através da Design Science Research Methodology, propondo uma framework orientada a processo para a colaboração Humano-IA governada, cujas contribuições de IA devem ser delimitadas, validadas e rastreadas. Define fases com portões de qualidade específicos, responsabilidades expressas como funções e não como cargos, e métricas de governação, ancoradas numa especificação versionada que liga cada artefacto ao seu requisito. É instanciada no Apex, aplicação web que operacionaliza cada fase, portão e artefacto sobre uma ferramenta real de gestão de projectos. A avaliação combina aplicação num projecto real, instrumentos padronizados de usabilidade e carga cognitiva, entrevistas, e avaliação analítica face a critérios previamente definidos. O contributo é um modelo de processo fundamentado em evidência que permite adoptar assistência por IA sem abdicar do controlo sobre qualidade, segurança e responsabilização.
84% usam, 29% confiam Os programadores que usam ou planeiam usar ferramentas de IA passaram a 84% (eram 76%), enquanto a parte que confia na exatidão do resultado caiu de 40% para 29%. Há mais inquiridos a desconfiar ativamente (46%) do que a confiar (33%). (Stack Overflow, 2025 Developer Survey: AI)
61% corretas, 10,5% seguras Em tarefas reais, um agente de programação de referência produziu soluções funcionalmente corretas em 61% dos casos, mas só 10,5% eram seguras. (Zhao et al., 2025, “Is Vibe Coding Safe?” (preprint))
+98% PRs, +91% tempo de revisão Em 1255 equipas, uma adoção elevada de IA trouxe mais 98% de pull requests integrados, mas revisões 91% mais longas e nenhuma correlação significativa com os resultados de entrega. (Faros AI, The AI Productivity Paradox Report 2025)
Waterfall, Scrum, Kanban e o Manifesto Ágil foram pensados para equipas em que todos os contribuidores são humanos. Não têm estrutura explícita para governar a participação da IA, delimitar o contexto sobre o qual um modelo pode agir, ou atribuir responsabilidade sobre os artefactos gerados.
A framework é um método: fases, chapéus, artefactos e regras de decisão que prescrevem como uma equipa organiza a participação da IA ao longo do ciclo de vida. Descreve o processo e não depende de nenhuma ferramenta. Uma etapa de Alinhamento Estratégico decide se uma Unidade de Trabalho deve sequer existir. Seguem-se seis fases, cada uma a consumir o resultado da anterior e fechada por um portão com um chapéu responsável. Uma falha nunca deita trabalho fora: devolve-o a uma fase anterior identificada, com a evidência anexada.
Dois termos repetem-se abaixo. Um Bolt é a unidade mais pequena de execução: a implementação de uma tarefa dentro de uma User Story. O Trio é o conjunto dos chapéus de Product Owner, Tech Lead e Design Lead, e é dono da Descoberta e do Design.
| Fase | Papel da IA | Controlo de saída |
|---|---|---|
| P1 Descoberta e Requisitos | Redige histórias e compila os cenários aprovados em Gherkin | Portão de Descoberta (o Trio) |
| P2 Design, Prototipagem e Arquitetura | Propõe a estrutura de interface e uma especificação técnica | Portão de Design (Design Lead, Tech Lead) |
| P3 Implementação | Gera e refatora código dentro de um Bolt | Portão de Implementação (Developer) |
| P4 Testes | Redige scripts BDD ponta a ponta a partir do Gherkin bloqueado | Portão de Testes (QA) |
| P5 Implantação | Gera o delta de infraestrutura só quando necessário | Portão de Implantação (chapéu de quem implanta) |
| P6 Manutenção | Reconstrói um contexto estreito para diagnosticar um sinal | Firewall de diagnóstico, retorno governado |
Cada papel é um chapéu: uma função que alguém na equipa tem de desempenhar. A mesma pessoa pode usar vários; numa equipa pequena, um chapéu por atribuir cabe a quem faz o trabalho adjacente. A autoridade logística (Bolt Master) fica separada da técnica (Tech Lead), e cada portão está ligado a uma função identificada.
Cada artefacto gerado por IA transporta o contexto das fases já validadas através de uma especificação persistente e versionada: uma camada global (arquitetura, decisões de stack, política de segurança) e uma camada local (o Gherkin bloqueado e a especificação técnica de cada história). Limitar o que um modelo consegue ver é, por si só, um controlo.
Um agente de programação acelera a escrita de código. O Apex verifica se esse código ainda cumpre o requisito para o qual foi escrito. É uma aplicação full-stack dividida, frontend em Next.js/TypeScript e backend em Python/FastAPI sobre uma API REST tipada, que executa cada fase, portão e artefacto sobre uma ferramenta real de gestão de projetos (Taiga ou Plane) e guarda o contexto em ficheiros de especificação legíveis e versionados.
As transições dependem do conteúdo: sem Gherkin bloqueado não há implementação, sem aprovação de QA ou CI verde não há implantação. O servidor valida as regras.
Um grafo de derivação interativo por projeto (épico → história → Gherkin → design → tarefas → testes → implantação), gerado a partir do índice de histórias, sem IA.
Bolt Cycle Time, Context Traceability Rate e AI Defect Escape Rate, calculadas a partir do projeto e exportáveis em Markdown ou CSV.
Verificação cruzada entre modelos, diff ao regenerar, registo de decisões e uma orientação opcional “Guide the AI” em cada passo generativo.
Executa todo o pipeline das Fases 1 a 5, de ponta a ponta, em segundo plano.
O estado do fluxo fica em ficheiros de contexto Markdown versionados e legíveis, e num índice de histórias.



Ecrãs do capítulo de demonstração da dissertação, capturados enquanto o Apex governava a construção do Outfolio.
Stack
A framework foi levada do Alinhamento Estratégico a um produto implantado em nove dias de calendário, crescendo de seis épicos assumidos à partida para nove épicos e 54 histórias, nenhuma abandonada, com os três retornos governados usados mais de uma vez.

| Medida | Resultado |
|---|---|
| Construtos de governação realizados | 10 de 12 como especificado, 1 como proxy assumido, 1 parcialmente |
| Sessões com tarefas | 13 |
| Carga percebida (Raw NASA-TLX) | 21,5 / 100 (baixa) |
| Usabilidade percebida (SUS) | 56,73, nota D (abaixo da norma publicada) |
| Critérios de design (5, fixados à partida) | 2 cumpridos, 3 parcialmente, 0 não cumpridos |
| Demonstração (Outfolio) | 9 dias, 9 épicos, 54 histórias, CTR 92,6%, Conformidade 98,65%, AI defect escape 1,85% |
Nas treze sessões, a carga percebida foi baixa (Raw NASA-TLX 21,5/100) e a usabilidade ficou abaixo da média publicada (SUS 56,73, nota D). A maior parte da dificuldade surgiu no primeiro contacto com uma interface densa: quem já sabe onde está acha-a pouco exigente, e a ferramenta faz pouco para lá levar quem chega de novo.
A demonstração com o Outfolio revelou um Portão de Testes que podia ser passado por um conjunto de testes que já não media o sistema que testava.
Foi procurada uma organização parceira independente, sem sucesso: uma migração a meio do projeto de Taiga para Plane atrasou o processo enquanto o adaptador do Apex era construído, e os contactos seguintes nunca chegaram a uma sessão marcada. A framework continua por testar numa equipa que não a desenhou.
A aplicação e a dissertação partilham um só histórico git ao longo de seis meses, por isso a forma como o trabalho foi feito pode ser lida a partir dele: quando a stack mudou, quando a tese começou a tirar commits à aplicação e que bugs só apareceram ao escrever sobre a ferramenta.
bolt, uma aplicação Streamlit
Transformava um épico em trabalho no Taiga com o Claude, guardando os requisitos aprovados em Markdown local. Um processo Python, quatro vistas de fase.
Reescrita em Reflex
Renomeado Apex a 7 de maio, passou para Reflex com um painel inicial e navegação por separadores entre fases.
Divisão FastAPI + Next.js
O monólito Reflex deu lugar a um backend FastAPI e um frontend Next.js 14 (React Query, Zustand, Tailwind), implantados como duas Azure Container Apps.
Painel de análise de governação
Bolt Cycle Time, Context Traceability Rate e AI Defect Escape Rate, as três métricas que o Capítulo 6 viria a definir.
Verificação cruzada com outro modelo
Um segundo modelo revê o resultado do primeiro.
Integração Figma
Ligação entre frames e histórias, com alterações de design sinalizadas na Fase 6.
Chave de API própria
Chaves OpenAI, Google e Anthropic por projeto.
Sistema de design “The Spec Ledger”
PRODUCT.md e DESIGN.md escritos: uma interface densa e plana, com um único acento violeta e letra monoespaçada para cada identificador, seguida de uma revisão completa da interface.
Outfolio escolhido para a demonstração
No mesmo dia: acompanhamento do ciclo de vida de cada Bolt.
Auditoria completa ao repositório
Todas as falhas, de críticas a baixas, fechadas em 24 horas.
Dissertação estruturada
Modelo do IST, os dez capítulos como esboços \todo.
Integração Plane integrada
Um segundo adaptador de gestão de projetos ao nível do Taiga, motivado pela migração de ferramenta de uma organização parceira.
Capítulo 6 reduzido de 28 para 18 páginas
O primeiro corte a sério no capítulo da framework.
Critérios da demonstração registados à partida
Escritos antes de qualquer trabalho de campo, para impedir escolhas a posteriori.
Primeira sessão de avaliação revela dois bugs
Um limite de tokens no pacote de contexto do GitHub, e contexto desatualizado ainda marcado como “High Confidence”.
Dados de avaliação completos
13 participantes para uma meta de 12; nenhum desistiu.
Diagramas redesenhados para a tese
Os diagramas de arquitetura e de fluxo de junho foram divididos e redesenhados como figuras da dissertação, e o diagrama das seis fases tornou-se a Figura 6.1.
Bug de perda de dados nos Fix-Bolts
Os relatórios de bugs eram reescritos em vez de acrescentados; detetado ao escrever o capítulo que descreve os Fix-Bolts.
Auditoria de conformidade do IST
71 de 80 páginas de texto principal, 99 de 100 no total.
Bolt Cycle Time em falta na exportação
O painel calculava-o; as exportações em Markdown e CSV nunca o incluíam.
Entregue
Dissertação (99 páginas) e resumo alargado (8 páginas), no prazo.
Defendida, 17/20
Defesa pública perante o júri.
Versão final pós-defesa
Designação dos papéis uniformizada, júri impresso na capa.
O painel original em que esta secção se baseia: todas as entradas da linha do tempo, datas de escrita dos capítulos, limites de páginas e o fecho do backlog.
Abrir o diárioNo papel, todos os conceitos pareciam completos. Implementá-los revelou o que o texto deixava por dizer: o Bolt Cycle Time foi medido primeiro com o indicador errado e só foi corrigido ao comparar o código com a definição escrita, e a deteção de desvios da especificação só funcionou quando assumi que a especificação pertence a cada história, não ao projeto. Hoje pergunto "consigo implementar isto?" logo ao rever a ideia.
Os portões cumpriram a função estrutural: gerar conteúdo nunca bastou para fechar uma fase. Mas o Portão de Testes aceitou testes que já não exercitavam o sistema atual, e a verificação antes da implantação reportou confiança alta a partir de um ficheiro de contexto desatualizado. A próxima versão precisa de portões que verifiquem se os dados de entrada estão atualizados, e de um controlo para ações destrutivas dentro de uma fase, que o modelo de portões hoje não cobre.
Os entrevistados gostaram da framework; os participantes deram ao Apex nota D (SUS 56,73), e 9 em 13 apontaram a densidade, a orientação ou a navegação como o que os confundiu, não os mecanismos de IA. Um ecrã sobrecarregado é lido como um método difícil, por isso a usabilidade no primeiro contacto, a clareza dos erros e a simplicidade visual pertencem aos requisitos da framework desde o início.
A demonstração registou 19 Fix-Bolts em 14 histórias; o indicador de AI Defect Escape viu um. Todos os instrumentos que usei mediram perceção, nenhum mediu a qualidade do software entregue, e o único ciclo de vida completo foi feito por mim, com todos os chapéus. A tese diz isto claramente, e os próximos passos vêm daí: telemetria direta em produção, uma métrica de custo de tokens e computação por Bolt com um chapéu responsável por ela, e uma avaliação com equipas independentes em mais do que uma ferramenta de gestão de projetos.
@mastersthesis{taborda2026apex,
author = {Tom{\'a}s dos Santos Taborda},
title = {Governed Human-AI Collaboration Across the Software Development Lifecycle: A Process Framework and Its Reference Implementation},
school = {Instituto Superior T{\'e}cnico, Universidade de Lisboa},
year = {2026},
month = oct,
type = {MSc dissertation},
url = {https://tomastaborda.com/work/apex}
}Notas da defesa do meu mestrado, a 23 de outubro de 2026: o que foi difícil, o que correu bem e onde o júri teve razão.