Case study

Como este site foi construído

Um portfólio tratado como produto de software: PRD antes da arquitetura, arquitetura antes do código, e o registro honesto das decisões, inclusive as que precisaram ser corrigidas no meio do caminho.

27riscos registrados

5ADRs com alternativas descartadas

13regras de negócio numeradas

4contradições detectadas e corrigidas

O fluxo Spec Driven & Harness

01Ideia & ContextoDocumento de referência com escopo, intenção e objetivos

02PRD de ProdutoProblema, personas, critérios de sucesso e o que fica fora via skill prd development

03Arquitetura e ContratosFonte de verdade técnica com ADRs, modelagem de dados e contratos via skill architecture design

04Spec Kit (.specify)Especificação funcional (spec.md), plano técnico (plan.md) e lista de tarefas (tasks.md)

05Harness & Execução IAImplementação guiada com MCPs (Context7, Serena, TestSprite) sob rédeas de regras duráveis

06Deploy & VerificaçãoDez gates bloqueantes de CI, testes automatizados e homologação em produção

A IA não escreveu este sistema sozinha e nem gerou código a partir de prompts soltos ("vibe coding"). O que está sendo demonstrado é a engenharia de harness: especificação como fonte única da verdade (SDD), autoridade hierárquica (PRD → Architecture → Spec → Plan → Tasks → Code), servidores MCP para contexto em tempo real e verificação contínua contra contratos definidos, com um engenheiro responsável por cada decisão técnica.

Decisões que valeram um ADR

ADR-001

Monolito modular em deploy serverlessMicroserviços descartados: um desenvolvedor, sem SRE e sem plantão, não sustenta operação distribuída.

Custo:sem isolamento de falha entre módulos.

ADR-002

Arquitetura hexagonal com custo assumidoPara um CMS de blog é over engineering pelos critérios normais. A justificativa não é técnica: a testabilidade é parte do que está sendo demonstrado.

Custo:mais arquivos e indireção por funcionalidade.

ADR-003

Dois adapters primários: HTTP e in-processA página pública chama o caso de uso direto, sem passar por HTTP. Isso mantém o site no ar mesmo se a API cair.

Custo:dois caminhos até o dado com risco de divergência de regra.

ADR-004

Monorepo isolado com pnpm workspacesSeparação física em pacotes desacoplados (domain, application, infrastructure, http). O domínio não possui nenhuma dependência externa (DEP-1).

Custo:configuração e orquestração de scripts no monorepo.

ADR-005

Eventos de domínio in-process sem brokerPublicar dispara a revalidação da página. É o que permite publicar em minutos sem deploy e sem mensageria para operar.

Custo:entrega best effort sem retentativa automática.

O que eu errei no caminho

A parte mais útil de documentar decisões é descobrir que duas delas se contradizem. Quatro contradições apareceram só ao cruzar as etapas, e cada uma teria virado defeito em produção.

Rollback instantâneo versus migration sem volta

Reverter o código não reverte o banco. O botão de rollback existiria, e apertá-lo derrubaria o sistema. Resolvido com a regra de que toda migration precisa ser compatível com a versão anterior.

Audit log que dura três dias

A retenção de log da plataforma é curta. Chamar aquilo de trilha de auditoria seria mentira confortável. Foi renomeado para o que de fato é: visibilidade operacional recente.

Teste de integração em banco compartilhado

Execuções paralelas de CI se atropelariam, gerando falha intermitente, que é pior que teste nenhum por ensinar a ignorar alertas vermelhos.

Acessibilidade exigida sem validação

WCAG AA aparecia em três lugares do documento e não existia gate nenhum no pipeline. Um requisito sem verificação é uma intenção.

Os documentos estão abertos

PRD, documento de arquitetura completo, contratos OpenAPI e evidências do processo, sem maquiagem para a foto.

Documentação Interativa da API (/api/docs)Relatório de Prontidão e Auditoria de Go Live PRD Completo (docs/prd.md)Decisões de Arquitetura (docs/architecture.md)Repositório no GitHub