19 · Aprendizados da stack-projetos

Em resumo: o que muda

A stack-projetos foi construída enquanto as regras eram descobertas. O modelo traz as regras desde o primeiro dia e corrige o que ela aprendeu tarde:

Um exercício de estudo: onde cada coisa da stack-projetos ficaria se ela tivesse nascido do modelo. Não é plano de migração; serve para testar se o modelo tem lugar para tudo.

Números da stack-projetos em 2026-10-17, para dar escala:

As seções do roteiro ao vivo, como agrupamentos

O mesmo exercício para o E2E: como as seções do roteiro ao vivo se organizariam em agrupamentos.

Roteiro ao vivo em seções dependentes

• O que aconteceu: o roteiro cresceu para 27 seções; cada uma assume o estado da anterior. Para ajustar a seção 10 era preciso rodar de 1 a 9. Um erro numa seção parava tudo. O roteiro era "demonstração, não garantia", então não pegava regressão.
• Correção: E2E hierárquico, com setups em cascata e casos independentes (11).

Duas fontes para o mesmo roteiro

• O que aconteceu: roteiro-manual-de-testes.md (prosa) e eng/roteiro-ao-vivo/ (código) descreviam a mesma coisa e precisavam ser atualizados juntos.
• Correção: o caso E2E narra os passos; o roteiro legível é gerado (eng/e2e.sh --roteiro).

Design system adotado depois das telas

• O que aconteceu: a fundação visual veio com Bootstrap e tokens copiados de outro site; depois veio o design system próprio, e a adoção levou 17 changes, mais refinos de telas que nenhuma etapa tocou.
• Correção: o design system entra na Fase 2, antes de qualquer tela de produto.

Versões flutuantes

• O que aconteceu: a CI chama npx @fission-ai/openspec@latest validate … || true (versão flutuante e falha ignorada); o runner é ubuntu-latest; imagens como postgres:16 e eclipse-temurin:21-jre sem patch; o guia do OpenSpec sugere fixar a versão como "opcional".
• Correção: ORG-0010 + eng/pinned-versions.sh na CI; openspec validate --strict quebrando o build.

ARCHITECTURE.md inchado e com parágrafos datados

• O que aconteceu: a seção de domínio chegou a quase 300 linhas, com o detalhe de cada capability e um parágrafo "Estado em 2026-09-12 (desatualizado…)".
• Correção: um parágrafo e um link por capability; detalhe em docs/solucoes/ e nas specs; nada datado (08).

Um papel único para a aplicação de gestão

• O que aconteceu: o acesso é gestao:acesso, tudo ou nada. Um perfil novo (ex.: "financeiro só vê carteiras") exigiria mexer no código.
• Correção: permissões finas + perfis compostos desde a fundação; documento de acesso por aplicação (12).

Acervo de capturas regerado inteiro

• O que aconteceu: cada rodada trocava o acervo inteiro (1936 PNGs, 415 MB na rodada de 2026-10-10), todos diferentes em bytes por causa de datas e dados, mesmo sem mudança de tela. Foi preciso ir para o Git LFS e depois restringir às telas afetadas.
• Correção: acervo opcional (ORG-0025); capturas ligadas aos casos; --acervo=<telas> só com as telas que a change muda.

Renomear o produto no meio do caminho

• O que aconteceu: "orçamentos" virou "projetos" (ADR-0032) e o app do cliente foi renomeado (ADR-0041): repositório, módulos, pacotes, realms de dev, documentação, pasta local e memória do agente.
• Correção: a Fase 1 começa por docs/produto/visao.md e pelos nomes das aplicações, antes de qualquer pasta de código.

Regras no CLAUDE.md

• O que aconteceu: as regras moram no CLAUDE.md, o que as prende a uma ferramenta.
• Correção: AGENTS.md como fonte; CLAUDE.md aponta (17).

Fundação em ordem descoberta

• O que aconteceu: identidade, observabilidade, aparência, roteiro ao vivo e implantação chegaram em momentos diferentes; algumas pendências de infraestrutura (realm de produção, job_name no Prometheus, alias de rede no Kamal) só apareceram perto do deploy.
• Correção: seis changes de fundação fixas e o checklist do portão 3 (04).

Nomes de pasta misturados

• O que aconteceu: docs/decisoes/ e docs/guias/ em português, docs/solutions/ em inglês.
• Correção: docs/solucoes/ no modelo; pastas de documentação em pt-BR, pastas de código e ferramenta em inglês (eng/, deploy/, e2e/, vendor/).

As ORGs de 07 nasceram, quase todas, de ADRs e práticas da stack-projetos (os números de ADR abaixo são os de lá).

ADRs de lá que não viraram ORG (e por quê)

Decisões que são do produto de projetos e não generalizam: moeda Hibex, motor de agendamento, homologação, impedimentos, mural, landings de adesão como peça obrigatória. Elas ficam como exemplo de como decidir (ADR com alternativas, change por fatia), não como o que decidir.