AIOX Course Platform | Professional Bootcamp & Mastery

Módulo 2 · RockQuiz: Pipeline Completo Duração: 3-4 horas Agentes praticados: @architect, @ux-expert, @sm, @po Projeto: RockQuiz

🏆 Vitória desta aula

Architecture Doc + UX Spec + stories hiperdetalhadas prontas para implementação. Ao final, qualquer Dev poderia abrir uma story e implementar sem perguntas adicionais.

Critério binário: docs/architecture.md + docs/ux-spec.md + pelo menos 6 stories em docs/stories/.

Conceito

O Architect transforma "O QUÊ" em "COMO"

O Analyst disse o que o problema é. O PM disse o que a solução faz. O @architect diz como a solução é construída. Ele pega requisitos e os transforma em decisões técnicas: stack, schema de banco, endpoints de API, padrões de código, estratégia de cache.

A diferença entre um Architecture Doc bom e um ruim: trade-offs documentados. Não basta listar tecnologias — é preciso justificar cada escolha e registrar o que foi considerado e descartado.

O SM traduz documentos em tarefas

O @sm (Scrum Master) é a ponte entre planejamento e código. Ele lê todos os documentos e os transforma em stories hiperdetalhadas — arquivos que contêm absolutamente tudo que o Dev precisa: o quê entregar (acceptance criteria testáveis), como implementar (detalhes técnicos), e por quê assim (decisões arquiteturais).

Nesta aula: descreva necessidades, avalie propostas

Você vai dizer ao Architect "preciso de uma arquitetura para 5 serviços containerizados com banco relacional e cache" — não vai ditar o schema, os endpoints ou os padrões. O Architect propõe, você avalia, refina até estar satisfeito.

Contexto

Esta aula completa a Fase 1 (planejamento) e transiciona para a Fase 2 (desenvolvimento). O Architect e o SM produzem os últimos documentos antes de começar a codificar. A qualidade desses documentos determina a qualidade de tudo que vem depois.

Prática

Passo 1 — Architect avalia complexidade

cd ~/aiox-bootcamp/rockquiz
claude

@architect

Aria, leia os documentos que o Analyst e o PM produziram:
- docs/project-brief.md
- docs/domain-map.md
- docs/prd.md

Quero que você avalie a complexidade técnica desse projeto 
antes de projetar a arquitetura. Considere: número de serviços, 
complexidade da lógica de negócio, necessidades de cache e 
real-time, e a infraestrutura de deploy.

*assess-complexity

Como avaliar: O Architect deve classificar a complexidade e identificar pontos de atenção. Se ele classificar como "simples" sem mencionar a lógica de scoring ou a estratégia de cache para ranking, questione:

Aria, você classificou como complexidade baixa, mas o sistema 
de scoring tem multiplicadores que dependem de tempo real e streak.
E o ranking precisa ser atualizado em tempo real para múltiplos 
jogadores. Isso não adiciona complexidade?

Passo 2 — Gerar o Architecture Doc

Descreva o que precisa — não como fazer:

Aria, projete a arquitetura completa do RockQuiz baseada no PRD.

Preciso de:
- Uma API REST performante que suporte o gameplay em tempo real
- Um banco de dados relacional para perguntas, jogos e jogadores
- Cache para rankings (precisa ser rápido e atualizar em tempo real)
- Frontend com server-side rendering para SEO e performance
- Tudo containerizado para desenvolvimento e produção
- Observabilidade (saber quando algo está errado em produção)

Decida a stack, o schema do banco, os endpoints, os padrões 
de código e a estratégia de cache. Justifique cada decisão — 
quero saber por que escolheu cada tecnologia e o que descartou.

Salve em docs/architecture.md

Note: não listamos as tecnologias (Fastify, PostgreSQL, Redis). O Architect pode recomendar essas ou outras. O valor está na justificativa e nos trade-offs — se ele escolher Express em vez de Fastify, precisa explicar por quê.

Como avaliar o Architecture Doc gerado:

Checklist de avaliação

Cada tecnologia tem justificativa com trade-off (não apenas nome)?

O schema do banco cobre todas as entidades do Domain Map?

Os endpoints cobrem todos os requisitos funcionais do PRD?

A estratégia de cache é clara (o que cachear, quanto tempo, quando invalidar)?

Os padrões de código são específicos (naming, error handling, estrutura)?

A estratégia de testes está definida?

Se algo estiver incompleto, peça ajuste descrevendo a lacuna, não a solução:

Aria, o Architecture Doc não menciona como lidar com o 
caso de o cache estar indisponível. O que acontece com o 
ranking se o Redis cair? Preciso de uma estratégia de 
fallback.

Aria, os padrões de código estão genéricos demais. Preciso 
que um dev novo no projeto saiba: como nomear arquivos, como 
estruturar um endpoint, como tratar erros, e onde colocar 
lógica de negócio. Detalhe mais.

🏆 Checkpoint 1: docs/architecture.md com stack justificada, schema, endpoints e padrões.

Passo 3 — Gerar contexto para os Devs

*create-context

Aria, gere um documento de contexto técnico que o Dev vai 
consultar durante a implementação. Deve incluir: as decisões 
mais importantes resumidas, armadilhas que você antecipa, 
e referências às seções relevantes do Architecture Doc.

Passo 4 — UX Spec

*exit

@ux-expert

Uma, leia o PRD (docs/prd.md) e o Architecture Doc 
(docs/architecture.md) e projete a experiência do usuário 
do RockQuiz.

O jogo precisa ser visualmente atraente (tema rock/dark), 
dar feedback imediato a cada resposta (acertou/errou com 
explicação), ter um senso de progressão e urgência (timer, 
streak, pontuação subindo), e funcionar bem em mobile e desktop.

Preciso de:
- O fluxo completo do usuário (de entrar no site até ver o ranking)
- Como cada tela deve funcionar e se comportar
- Cores, tipografia e identidade visual
- Como mostrar feedback de acerto/erro de forma satisfatória
- Como funciona a gamificação visual (streak, timer, score)
- Considerações de acessibilidade

Salve em docs/ux-spec.md

Note: Não prescrevemos cores hex, não listamos componentes, não definimos breakpoints. A UX Expert sabe o que um quiz game precisa. Se o resultado não tiver acessibilidade ou responsividade, refinamos:

Uma, o UX spec não menciona como o quiz funciona no mobile. 
Em telas pequenas, 4 alternativas em grid 2x2 podem ficar 
apertadas. Como resolver?

🏆 Checkpoint 2: docs/ux-spec.md com UX completo.

Passo 5 — Revisão cruzada

Antes de criar stories, garanta que os documentos são consistentes:

*exit

@architect

Aria, faça uma revisão cruzada:
- O PRD (docs/prd.md) define requisitos que a arquitetura 
  (docs/architecture.md) não cobre?
- A arquitetura tem algo que não está nos requisitos?
- Os NFRs são viáveis com a stack escolhida?
- O UX spec é implementável com a stack escolhida?

Se encontrar inconsistências, corrija.

Por que este passo existe: Inconsistências entre documentos são bombas-relógio. Se o PRD diz "ranking atualiza em tempo real" mas a arquitetura não tem WebSocket nem cache, o Dev vai descobrir isso no meio da implementação — quando é 10x mais caro corrigir.

Passo 6 — SM cria stories

Agora a transição: o SM lê todos os documentos e cria tarefas implementáveis.

*exit

@sm

Sam, leia todos os documentos de planejamento:
- docs/project-brief.md
- docs/domain-map.md
- docs/prd.md
- docs/architecture.md
- docs/ux-spec.md

Crie stories para o desenvolvimento do RockQuiz. Cada story deve 
conter tudo que o Dev precisa para implementar sem perguntas:
- O que entregar (critérios testáveis)
- Como implementar (detalhes técnicos baseados no Architecture Doc)
- Por que fazer assim (decisões relevantes)
- Quais arquivos criar ou modificar
- Quais testes são esperados
- Estimativa de complexidade

Organize as stories por ordem de dependência — o que precisa 
existir antes do que.

Salve cada story em docs/stories/STORY-XX.md

Note: Não listamos as stories específicas (STORY-01: Setup, STORY-02: CRUD...). O SM sabe como decompor um projeto — faz parte do seu papel. Ele vai ler a arquitetura e decidir a melhor decomposição. Se a decomposição não fizer sentido, refinamos:

Sam, você colocou frontend e backend na mesma story. Isso 
é muito grande — um dev não vai conseguir implementar tudo 
de uma vez. Quebre em stories menores: uma para API, outra 
para frontend.

Como avaliar cada story:

Checklist de qualidade de story

Tem critérios de aceitação testáveis (não vagos)?

Tem detalhes de implementação (não apenas "faça o CRUD")?

Referencia decisões do Architecture Doc quando relevante?

Tem lista de arquivos a criar/modificar?

Tem seção de testes esperados?

É pequena o suficiente para ser implementada em uma sessão?

Um Dev que leia APENAS esta story (sem ler o PRD) sabe o que fazer?

A última pergunta é o teste definitivo.

Passo 7 — PO prioriza

*exit

@po

Pia, revise as stories em docs/stories/ e defina a ordem 
de implementação. Considere: dependências técnicas, valor 
para o MVP e risco técnico.

🏆 Checkpoint 3 — VITÓRIA DA AULA: Stories priorizadas em docs/stories/.

Passo 8 — Verificar estado completo

*exit
ls -la docs/
ls -la docs/stories/

Você deve ter ~7 documentos + 6-8 stories — todo o contexto para construir o RockQuiz, produzido por 6 agentes.

Reflexão

O padrão que emergiu

Em todas as interações com agentes nesta aula, o padrão foi o mesmo:

Descrever a necessidade: "preciso de uma arquitetura para..."
Agente propõe: gera documento/solução
Avaliar criticamente: "faltou X", "Y está vago", "Z é inconsistente"
Refinar: agente ajusta baseado no feedback
Validar: checklist de qualidade confirma completude

Esse padrão se repete em TODA interação com AIOX — planejamento, desenvolvimento, testes, deploy. Domine o padrão e você domina o framework.

O conceito-chave

O SM é a ponte entre documentos e código. Ele garante que NENHUM contexto se perde na transição — tudo que os agentes de planejamento decidiram está nas stories que o Dev vai implementar.

Conexão com a próxima aula

Na Aula 05, o @devops entra para criar a infraestrutura. Você vai descrever suas necessidades de ambiente (desenvolvimento e produção) e o DevOps vai propor e implementar a solução containerizada.

Anterior: Aula 03 — Analyst + PM Próxima: Aula 05 — DevOps: Infra do RockQuiz

Aula 04 — Architect + UX + SM: Da Especificação às Stories