Visão

O modelo

Como se trabalha

A plataforma

Origem e rumo

Decisões

Este repositório
Começar
Aparência

Vale na hora e fica lembrada neste navegador.

O modelo

04 · Ciclo de vida de uma stack

Uma stack passa por cinco fases. Entre elas há portões: condições verificáveis sem as quais a fase seguinte não começa. O mais importante é o portão 1: nenhum código antes de a stack estar definida.

As fases

Uma trilha com cinco fases — nascimento, definição, fundação, produto e operação — separadas por quatro portões; da operação, cada nova change volta ao produto. portão 0o agente se achaportão 1nenhuma lacunaportão 2login, telemetria, E2Ee deployportão 31º deploy0Nascimentomodelo copiado1Definiçãolacunas preenchidas2Fundação6 changes fixas3Produtochange a change4Operaçãodeploys e backupcada nova changecada portão tem um critério que se confere — não uma opinião
A stack cresce como uma torre, fase a fase: na Fase 0 tem só as regras, as ORGs e as ADRs pré-escritas; a Fase 1 acrescenta a ficha e as ADRs da stack; a Fase 2, as seis changes de fundação; a Fase 3, uma capability por change; na Fase 4 está no ar, com backup, e continua recebendo changes. Fase 0nascimentoregras · AGENTS.mdORGso modelo, sem códigoFase 1definiçãoficha da stackacesso no papeltudo decidido por escritoFase 2fundaçãoesqueleto · identidadeE2E · observabilidadeaparência · implantaçãoroda de ponta a pontaFase 3produtocapabilitycapabilitycapabilityuma change por vezFase 4operaçãono ar, com backup,e novas changeso que a fase acrescenta

Fase 0 — Nascimento

Objetivo: existir um repositório com as regras do jogo e nenhum código.

Fase 0: o mantenedor escolhe uma versão da arquitetura, cria o repositório e copia o modelo zerado com eng/new-stack.sh; o novo repositório traz README, AGENTS.md e CLAUDE.md, docs com as ORGs, as ADRs pré-escritas e a ficha em lacunas, openspec inicializado, os hooks e o arquivo ARQUITETURA. O portão 0 se abre quando um agente lê o AGENTS.md e diz que está na Fase 1. stack-architecturearquitetura-vX.Y.Zmodelo zeradoORGs · regrasnova stackREADME.mdEstado: Fase 1AGENTS.md · CLAUDE.mdas regras do jogodocs/decisoes/ORGs e ADRs pré-escritasdocs/stack.mda ficha, em lacunasopenspec/inicializado.claude/os hooksARQUITETURAvX.Y.Zeng/new-stack.sh copia1 · escolhe a versão2 · cria o repositório3 · roda a cópia4 · faz o 1º commitportão 0:"li o AGENTS.md: estou na Fase 1, definir a stack"
O que existeO que não existe
README.md com o nome, o propósito e "Estado: Fase 1 — definindo a stack"O que não existe: nenhum código
AGENTS.md completo; CLAUDE.md importando-o (@AGENTS.md)O que não existe: nenhum Dockerfile, compose.yaml, build
docs/decisoes/organizacao/ com a cópia das ORGs; docs/decisoes/ com as ADRs pré-escritas, propostas e com lacunasO que não existe: nenhuma spec de produto
docs/stack.md — a ficha da stack, toda em lacunasO que não existe:
docs/produto/visao.md — o propósito do produto, em lacunasO que não existe:
openspec/ inicializado (os comandos /opsx:*, na versão do OpenSpec que o modelo traz), config.yaml com lacunasO que não existe:
.claude/ com os hooks; ARQUITETURA com a versão de origemO que não existe:
eng/gaps.sh, eng/pinned-versions.sh, eng/tdd-order.sh e o kit de rabiscosO que não existe:
e2e/hierarchy/, o harness do E2EO que não existe:

O mantenedor cria a stack a partir deste repositório, numa versão da arquitetura:

Terminal
eng/new-stack.sh ../enterprise-stack-atendimento --platform enterprise --product atendimento \
  --version arquitetura-v0.1.0

O script copia o modelo, as ORGs e o kit de rabiscos; escreve o ARQUITETURA; preenche o que a Fase 0 já sabe (o nome do produto, a plataforma e o repositório); roda o openspec init; e confere o resultado (hooks, scripts, versões fixas, ordem do TDD). Ele não toca no Git: no fim, imprime os comandos do primeiro commit, que são do mantenedor. Uma pré-versão também serve (--version arquitetura-v0.1.0-dev). Antes da primeira tag, --draft copia a árvore de trabalho e grava arquitetura-rascunho-<commit> no ARQUITETURA.

Portão 0: o repositório existe, o mantenedor fez o primeiro commit, e um agente aberto nele lê o AGENTS.md e responde que está na Fase 1.

Fase 1 — Definição da stack

Objetivo: decidir tudo o que depende de tecnologia e de produto, por escrito, antes de construir.

Fase 1, em sete degraus: visão do produto, aplicações, identidade no papel, tecnologia, versões, estrutura e as ADRs pré-escritas preenchidas. O mantenedor revisa; ajustes voltam à tecnologia. Aceita a ficha, eng/gaps.sh confere que não sobrou lacuna e o portão 1 se abre. 1visão do produtoquem usa, o que resolve2aplicaçõesnomes, públicos, endereços, cores3identidade no papelrealms, permissões, perfis4tecnologialinguagem, framework, banco, testes5versõesexatas, cada uma num só lugar6estruturamódulos, pastas, dono do schema7ADRs pré-escritaspreenchidas a partir da ficharevisãoajusteseng/gaps.shnenhuma lacunaaceitaportão 1sem código nesta fase: o agente preenche a ficha e propõe as ADRs

Como se trabalha nesta fase: em conversa com o agente, usando /opsx:explore para pensar. O agente não escreve código — ele preenche a ficha, propõe as ADRs e aponta as consequências de cada escolha. A ordem importa: tecnologia vem depois de saber quem usa e quantas aplicações há, porque é isso que pesa na escolha.

Por que não há change do OpenSpec aqui: a Fase 1 decide como construir, não o que o produto faz. Isso é ADR. O OpenSpec entra na Fase 2.

Portão 1 (verificado por eng/gaps.sh, que roda na CI desde o primeiro commit):

  • nenhuma ocorrência de {{LACUNA: no repositório;
  • todas as ADRs pré-escritas com status aceita;
  • docs/stack.md com toda ferramenta acompanhada da versão exata;
  • README.md com os pré-requisitos e as versões.

Enquanto o portão 1 estiver fechado, o AGENTS.md instrui o agente a recusar qualquer pedido de código e voltar à ficha.

Fase 2 — Fundação

Objetivo: ter o esqueleto da stack funcionando de ponta a ponta, antes de qualquer funcionalidade de produto. Toda stack faz as mesmas changes de fundação, na mesma ordem — o que muda é a tecnologia dentro delas.

Fase 2: a fundação são seis changes, na ordem, iguais em toda stack — esqueleto, identidade, e2e-base, observabilidade, aparência e implantação. O produto vem depois, construído sobre ela. o produto vem depois1esqueletobuild, testes, Dockerfile, compose, CI2identidadelogin, permissões, perfis, usuários dedev3e2e-baseharness hierárquico, um caso porperfil4observabilidadelog JSON, métricas, traces, /up5aparenciadesign system, layout, temas, avisoLOCAL6implantacaodeploy, segredos, backup, guiasa fundação, de baixo para cimaa mesma em toda stack
#ChangeEntregaProva
1Change: esqueletoEntrega: módulos que compilam; um teste de unidade e um de integração (banco em container); Dockerfile por aplicação; compose.yaml com o banco; CI com build, testes, lacunas e versõesProva: <build> && docker compose up sobe tudo; CI verde
2Change: identidadeEntrega: cada aplicação exige login no seu realm; permissões e perfis conferidos pelo código; eng/auth/provision.sh idempotente; realms de desenvolvimento com um usuário por perfil; página de acesso negado; logoutProva: teste de integração com Keycloak real em container; docs/acesso/<app>.md completo
3Change: e2e-baseEntrega: e2e/ com o harness hierárquico, eng/e2e.sh, login por perfil, capturas desligadas por padrão; agrupamento identidadeProva: eng/e2e.sh verde do zero; eng/e2e.sh identidade/login/<caso> verde sozinho
4Change: observabilidadeEntrega: log JSON no stdout, métricas na porta interna, traces OTLP, /up; Tempo + Grafana locais num perfil do ComposeProva: teste de integração do contrato; trace visível no Grafana local
5Change: aparenciaEntrega: cópia do design system, entrega pelo build, layout com os três menus, temas, página de erro, aviso de ambiente LOCALProva: verificador sem erro; caso E2E de aparência; capturas nos dois temas
6Change: implantacaoEntrega: deploy/<app>/ com Dockerfile, deploy.yml, .kamal/secrets (só referências), a partir dos esqueletos de deploy/README.md; accessory de banco e de backup; script de restauração; guias de implantação (com o catálogo de todas as variáveis e o portão 3 na ordem), identidade em produção e backupProva: docker build de cada imagem; restauração testada localmente; instruções de deploy para o mantenedor

A identidade vem antes da e2e-base porque o E2E entra com um usuário por perfil, e esses usuários nascem na identidade. Por isso as telas dela (login, acesso negado, logout) são a única exceção à regra de que nenhuma tela muda sem caso E2E: na própria change, ficam cobertas por teste de rota e pelo teste de integração com o Keycloak, e os casos E2E delas chegam na e2e-base, no agrupamento identidade.

Portão 2: o mantenedor sobe o ambiente local do zero com um comando, entra em cada aplicação com cada perfil, vê telemetria local, roda a regressão E2E verde, e tem em mãos as instruções para o primeiro deploy.

Observação:

Por que a fundação vem antes do produto: observabilidade, aparência e E2E que chegam depois das telas obrigam a revisitar cada tela já pronta, uma a uma. Com a fundação primeiro, toda tela de produto já nasce no padrão.

Fase 3 — Produto

Objetivo: entregar as capabilities do produto, uma change por vez.

O ciclo de uma change em duas raias. O mantenedor pede; se o escopo é incerto, o agente explora com perguntas e o mantenedor responde. O agente propõe a change (e uma ADR, se houver decisão técnica); o mantenedor revisa. O agente aplica em TDD, roda os casos E2E novos e a regressão completa, e entrega com o ambiente no ar. O mantenedor valida — ajustes voltam ao apply —, o agente sincroniza e arquiva, e o mantenedor faz o commit. mantenedoragentepedido/opsx:exploreperguntas numeradas, opções, recomendaçãorespostas"1a, 2b, 3a"/opsx:proposeproposal · design · specs · tasks (+ ADR)revisãoajusta ou aprova/opsx:applytarefa a tarefa, em TDDcasos E2Edos cenários novos, setups em cascataregressão completado zero, com 0 falhaentregaambiente no ar, resumo por telavalidaçãona tela, com os dados/opsx:sync + archiveas specs vivas atualizadascommite deploy, se for o casoajustessó se o escopoé incerto

O ciclo completo está em 09 · Mudanças com OpenSpec e TDD.

Portão 3 (antes do primeiro deploy real): realms e clients provisionados no Keycloak real; segredos no Bitwarden; DNS apontado; métricas e traces ligados no toolbox; restauração de backup testada. Cada item é uma linha do guia de implantação com uma caixa de seleção, na ordem do 13: a identidade vem antes de qualquer deploy, porque o segredo do client é um dos segredos dele.

Fase 4 — Operação

A stack está no ar e continua recebendo changes. Algumas rotinas passam a existir:

RotinaGatilhoComo
DeployGatilho: change concluída e commitadaComo: mantenedor, kamal deploy a partir de deploy/<app>/
BackupGatilho: diário, automáticoComo: accessory de backup
Teste de restauraçãoGatilho: antes de subir versão maior do banco; periodicamenteComo: guia de backup
Atualizar o design systemGatilho: nova versão no enterprise-stack-designComo: change (ver 16)
Atualizar a arquiteturaGatilho: nova versão aquiComo: change (ver abaixo)
Atualizar dependênciasGatilho: aviso de segurança ou versão maiorComo: change; ADR se houver alternativa

Uma stack acompanha a arquitetura como acompanha o design system

A arquitetura também tem versões. A stack registra de qual versão nasceu (arquivo ARQUITETURA na raiz, como o vendor/hibex/VERSAO) e adota as versões novas por change, seguindo o "Para as stacks" do CHANGELOG.md daqui. O caminho de volta são os pedidos: o que a stack aprende e a arquitetura não dá vai para docs/decisoes/pedidos-a-arquitetura.md, o mantenedor o traz para cá, e a versão que o atende o cita no "Para as stacks".

A arquitetura publica a versão 1.3.0 com o CHANGELOG "Para as stacks". A stack abre a change arquitetura-1-3-0: lê o CHANGELOG entre a versão do seu arquivo ARQUITETURA e a nova, copia as ORGs da versão nova, ajusta AGENTS.md, scripts e CI, e grava a versão nova. O que aprende volta como pedido. stack-architecturev1.1.0v1.2.0v1.3.0CHANGELOG"Para as stacks"a stackARQUITETURAv1.2.0v1.3.0change arquitetura-1-3-0ler o CHANGELOG de v1.2.0 a v1.3.0copiar as ORGs, ajustar AGENTS.mdajustar eng/ e a CIgravar a versão em ARQUITETURAaprendizadose pedidos