Apex

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.

Grau
Mestrado em Engenharia Informática e de Computadores, Instituto Superior Técnico, Universidade de Lisboa
Defendida
23 de outubro de 2026
Nota
17/20
Registo completo da tese
Título
Governed Human-AI Collaboration Across the Software Development Lifecycle: A Process Framework and Its Reference Implementation
Orientador
Prof. Miguel Mira da Silva
Júri
Prof.ª Helena Galhardas (presidente), Prof. Ademar Aguiar (vogal)
Entregue
7 de outubro de 2026
Método
Revisão Sistemática da Literatura (646 artigos) + Design Science Research Methodology

Em resumo

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.

Resumo completo

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.

O problema

  • 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

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.

As seis fases do ciclo de vida da frameworkAlinhamento Estratégico, depois seis fases em sequência, cada uma com um portão de qualidade. A Manutenção tem três retornos governados: defeito em produção para a Implementação, lacuna na especificação para o Design, desvio de negócio para a Descoberta. Todas as fases se ancoram numa especificação versionada.especificação persistente e versionada: camada global + localAlinhamentoEstratégicoP1Descoberta eRequisitosP2Design,Prototipagem eArquiteturaP3ImplementaçãoP4TestesP5ImplantaçãoP6Manutençãoportãodefeito em produção (Fix-Bolt)lacuna na especificaçãodesvio de negócio
As seis fases, os seus portões e os três retornos governados a partir da Manutenção
FasePapel da IAControlo de saída
P1 Descoberta e RequisitosRedige histórias e compila os cenários aprovados em GherkinPortão de Descoberta (o Trio)
P2 Design, Prototipagem e ArquiteturaPropõe a estrutura de interface e uma especificação técnicaPortão de Design (Design Lead, Tech Lead)
P3 ImplementaçãoGera e refatora código dentro de um BoltPortão de Implementação (Developer)
P4 TestesRedige scripts BDD ponta a ponta a partir do Gherkin bloqueadoPortão de Testes (QA)
P5 ImplantaçãoGera o delta de infraestrutura só quando necessárioPortão de Implantação (chapéu de quem implanta)
P6 ManutençãoReconstrói um contexto estreito para diagnosticar um sinalFirewall de diagnóstico, retorno governado

Chapéus

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.

Continuidade ancorada na especificação

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.

Três métricas de governação

Bolt Cycle Time
O tempo decorrido desde que uma tarefa é puxada como Bolt até à sua conclusão, medido ao nível da tarefa para isolar a execução de filas, revisões e transições de portão.
Context Traceability Rate
A proporção de Bolts e histórias implantados cujos artefactos podem ser rastreados, através das especificações bloqueadas, até à Unidade de Trabalho de origem.
AI Defect Escape Rate
A proporção de defeitos em produção com origem em lógica gerada por IA que passaram o Portão de Testes. O Apex só o consegue observar através de um proxy assumido.

Implementação de referência

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.

  • Fluxo por fases, com portões

    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.

  • Grafo de rastreabilidade

    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.

  • Métricas de governação

    Bolt Cycle Time, Context Traceability Rate e AI Defect Escape Rate, calculadas a partir do projeto e exportáveis em Markdown ou CSV.

  • Salvaguardas com a pessoa no circuito

    Verificação cruzada entre modelos, diff ao regenerar, registo de decisões e uma orientação opcional “Guide the AI” em cada passo generativo.

  • Autopilot

    Executa todo o pipeline das Fases 1 a 5, de ponta a ponta, em segundo plano.

  • Armazenamento ancorado na especificação

    O estado do fluxo fica em ficheiros de contexto Markdown versionados e legíveis, e num índice de histórias.

Diagrama de componentes: o frontend Next.js, com React Query, Zustand e um adaptador de gestão de projetos, chama um backend FastAPI cujos routers de fase acedem a um ContextService e a uma camada de saída protegida; as especificações ficam em Markdown e num índice de histórias, em disco local ou Azure File Share.
Arquitetura do Apex, parte 1 de 2: caminho interno dos pedidos e o repositório de especificações
Diagrama de componentes: os routers de fase e o adaptador de gestão de projeto chamam uma camada de saída FastAPI com proxies de Taiga e Plane, encaminhamento de fornecedores no ai_engine, um proxy de Figma e handlers de fetch, actions e webhook do GitHub. Estes chegam ao Taiga através de um relay Cloudflare, ao Plane, ao Anthropic Claude, ao OpenAI, ao Google Gemini, à API REST do Figma e à API REST do GitHub. O github-browser.ts chama o GitHub diretamente a partir do browser.
Arquitetura do Apex, parte 2 de 2: a fronteira de saída protegida e os serviços externos a que chega
Ecrã do Portão de Implantação com o veredicto do delta de infraestrutura, um pacote de implantação, uma matriz de rastreabilidade com três cenários aprovados e duas aprovações humanas por assinalar.
Portão de Implantação no Apex: veredicto do delta, pacote de implantação, matriz de rastreabilidade e as duas aprovações humanas

A demonstração, fase a fase

Ecrãs do capítulo de demonstração da dissertação, capturados enquanto o Apex governava a construção do Outfolio.

Engenharia

  • 1,171commits
  • 1,640testes de backend
  • 318testes unitários de frontend
  • 24casos E2E

Stack

Backend
Python 3.12, FastAPI, Pydantic v2, LangChain
Frontend
Next.js 15, TypeScript, React Query, Zustand, Tailwind CSS
Plataforma
Docker, GitHub Actions, Azure Container Apps, Redis
Gestão de projeto
Taiga, Plane

Demonstração

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.

Context Traceability Rate
92.6%
Conformidade média com a especificação
98.65%
AI Defect Escape Rate
1.85%
Página inicial do Outfolio com o título do produto, ações da conta e uma fila de projetos publicados em destaque.
Painel do Outfolio: o produto construído para a demonstração do ciclo de vida

Avaliação e resultados

MedidaResultado
Construtos de governação realizados10 de 12 como especificado, 1 como proxy assumido, 1 parcialmente
Sessões com tarefas13
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%

Limitações encontradas na avaliação

Carga baixa, usabilidade abaixo da norma

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.

Um portão que um conjunto de testes obsoleto conseguia passar

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.

A demonstração numa organização parceira não aconteceu

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.

Histórico

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.

  • 1,171commits
  • 186dias, do primeiro ao último commit
  • 199commits na dissertação
  • 5ramos de funcionalidade integrados
  • 47dia mais ativo (18 jul.)
Histórico de commits do Apex em forma de grafo gitDe 24 de abril a 27 de outubro de 2026: a linha principal com o volume semanal de commits, cinco ramos de funcionalidade integrados e a linha da dissertação a partir de 4 de agosto. Os marcadores numerados correspondem à lista abaixo.mai.jun.jul.ago.set.out.mainthesisreflex-migration, 13fastapi-nextjs, 23jira-integration, 4ui-revamp, 7plane.so-integration, 235 commits35 commits82 commits81 commits80 commits61 commits67 commits115 commits67 commits85 commits41 commits30 commits88 commits20 commits26 commits12 commits17 commits10 commits4 commits1 commits37 commits7 commits1 commits11 commits12 commits19 commits6 commits26 commits6 commits50 commits1 commits24 commits37 commits7 commits12345678910
  1. primeiro commit (bolt, Streamlit)
  2. passa a chamar-se Apex
  3. análise de governação
  4. integração Figma
  5. sistema de design
  6. Outfolio escolhido
  7. dissertação iniciada
  8. dados de avaliação completos
  9. entregue
  10. defendida, 17/20
Grafo de commits: main, os cinco ramos de funcionalidade integrados e a linha da dissertação. O tamanho de cada ponto é o número de commits por semana.

Commits por dia

abr.mai.jun.jul.ago.set.out.segquasex2026-04-19: 02026-04-20: 02026-04-21: 02026-04-22: 02026-04-23: 02026-04-24: 22026-04-25: 02026-04-26: 02026-04-27: 02026-04-28: 22026-04-29: 12026-04-30: 02026-05-01: 02026-05-02: 02026-05-03: 12026-05-04: 202026-05-05: 62026-05-06: 12026-05-07: 72026-05-08: 72026-05-09: 112026-05-10: 32026-05-11: 362026-05-12: 202026-05-13: 22026-05-14: 32026-05-15: 172026-05-16: 02026-05-17: 42026-05-18: 202026-05-19: 282026-05-20: 12026-05-21: 112026-05-22: 232026-05-23: 292026-05-24: 02026-05-25: 02026-05-26: 202026-05-27: 12026-05-28: 72026-05-29: 102026-05-30: 02026-05-31: 02026-06-01: 72026-06-02: 112026-06-03: 212026-06-04: 122026-06-05: 82026-06-06: 52026-06-07: 52026-06-08: 152026-06-09: 162026-06-10: 72026-06-11: 112026-06-12: 252026-06-13: 82026-06-14: 202026-06-15: 182026-06-16: 132026-06-17: 172026-06-18: 142026-06-19: 122026-06-20: 172026-06-21: 102026-06-22: 132026-06-23: 72026-06-24: 22026-06-25: 62026-06-26: 02026-06-27: 162026-06-28: 72026-06-29: 82026-06-30: 272026-07-01: 222026-07-02: 52026-07-03: 62026-07-04: 42026-07-05: 182026-07-06: 32026-07-07: 02026-07-08: 52026-07-09: 52026-07-10: 42026-07-11: 42026-07-12: 132026-07-13: 62026-07-14: 02026-07-15: 32026-07-16: 02026-07-17: 52026-07-18: 472026-07-19: 92026-07-20: 112026-07-21: 112026-07-22: 12026-07-23: 42026-07-24: 22026-07-25: 112026-07-26: 52026-07-27: 22026-07-28: 02026-07-29: 02026-07-30: 02026-07-31: 02026-08-01: 02026-08-02: 02026-08-03: 02026-08-04: 102026-08-05: 212026-08-06: 62026-08-07: 12026-08-08: 32026-08-09: 02026-08-10: 42026-08-11: 112026-08-12: 52026-08-13: 02026-08-14: 02026-08-15: 02026-08-16: 02026-08-17: 12026-08-18: 22026-08-19: 252026-08-20: 82026-08-21: 52026-08-22: 02026-08-23: 02026-08-24: 12026-08-25: 02026-08-26: 02026-08-27: 02026-08-28: 92026-08-29: 02026-08-30: 32026-08-31: 102026-09-01: 122026-09-02: 12026-09-03: 12026-09-04: 12026-09-05: 02026-09-06: 02026-09-07: 12026-09-08: 22026-09-09: 02026-09-10: 62026-09-11: 02026-09-12: 02026-09-13: 202026-09-14: 292026-09-15: 22026-09-16: 02026-09-17: 02026-09-18: 62026-09-19: 132026-09-20: 112026-09-21: 72026-09-22: 02026-09-23: 02026-09-24: 12026-09-25: 02026-09-26: 02026-09-27: 62026-09-28: 12026-09-29: 32026-09-30: 22026-10-01: 122026-10-02: 72026-10-03: 12026-10-04: 152026-10-05: 192026-10-06: 02026-10-07: 22026-10-08: 02026-10-09: 02026-10-10: 02026-10-11: 02026-10-12: 02026-10-13: 02026-10-14: 02026-10-15: 02026-10-16: 02026-10-17: 02026-10-18: 02026-10-19: 02026-10-20: 02026-10-21: 02026-10-22: 02026-10-23: 02026-10-24: 02026-10-25: 02026-10-26: 72026-10-27: 1

Por tipo de commit

feat
332
docs
315
fix
310
refactor
25
test
16
chore
10

Linha do tempo: produto, design e tese

  1. Design

    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.

  2. Design

    Reescrita em Reflex

    Renomeado Apex a 7 de maio, passou para Reflex com um painel inicial e navegação por separadores entre fases.

  3. Design

    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.

  4. Aplicação

    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.

  5. Aplicação

    Verificação cruzada com outro modelo

    Um segundo modelo revê o resultado do primeiro.

  6. Aplicação

    Integração Figma

    Ligação entre frames e histórias, com alterações de design sinalizadas na Fase 6.

  7. Aplicação

    Chave de API própria

    Chaves OpenAI, Google e Anthropic por projeto.

  8. Design

    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.

  9. Aplicação

    Outfolio escolhido para a demonstração

    No mesmo dia: acompanhamento do ciclo de vida de cada Bolt.

  10. Aplicação

    Auditoria completa ao repositório

    Todas as falhas, de críticas a baixas, fechadas em 24 horas.

  11. Tese

    Dissertação estruturada

    Modelo do IST, os dez capítulos como esboços \todo.

  12. Aplicação

    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.

  13. Tese

    Capítulo 6 reduzido de 28 para 18 páginas

    O primeiro corte a sério no capítulo da framework.

  14. Tese

    Critérios da demonstração registados à partida

    Escritos antes de qualquer trabalho de campo, para impedir escolhas a posteriori.

  15. Encontrado ao escrever

    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”.

  16. Tese

    Dados de avaliação completos

    13 participantes para uma meta de 12; nenhum desistiu.

  17. Design

    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.

  18. Encontrado ao escrever

    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.

  19. Tese

    Auditoria de conformidade do IST

    71 de 80 páginas de texto principal, 99 de 100 no total.

  20. Encontrado ao escrever

    Bolt Cycle Time em falta na exportação

    O painel calculava-o; as exportações em Markdown e CSV nunca o incluíam.

  21. Tese

    Entregue

    Dissertação (99 páginas) e resumo alargado (8 páginas), no prazo.

  22. Tese

    Defendida, 17/20

    Defesa pública perante o júri.

  23. Tese

    Versão final pós-defesa

    Designação dos papéis uniformizada, júri impresso na capa.

Diagramas, antes e depois

Diagrama geral da framework: Alinhamento Estratégico seguido das seis fases, cada uma com entradas, saídas e literatura de suporte.
A visão geral da framework, 20 jul. 2026: fases, entradas, saídas e fundamentação na literatura

Apex & Thesis Ledger

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ário

O que aprendi

  1. Construir a framework foi o teste mais duro que lhe fiz

    No 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.

  2. Um controlo pode passar e estar errado

    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.

  3. As pessoas conhecem o método através da ferramenta

    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.

  4. Medir o resultado que se afirma, ou dizer que não se mediu

    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.

Citar este trabalho

@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}
}
Escreva-me sobre a tese