SDD — Spec-Driven Development

SDD — Spec-Driven Development

Uma especificação, ou spec, é um arquivo Markdown versionado que descreve o comportamento esperado antes da implementação. No Swix, usamos SDD quando uma mudança cria ou altera uma regra.

O objetivo é substituir o vibe coding — pedir código e aceitar o que parece funcionar — por desenvolvimento dirigido por especificação. A IA pode gerar todo o código, mas o profissional continua no comando: define intenção, arquitetura, restrições e critérios de qualidade, depois revisa e valida o resultado.

O Codex aplica AGENTS.md, consulta docs/specs/README.md e classifica a tarefa como S0, S1 ou S2. O nível define quais documentos serão lidos ou atualizados. S0 não cria um novo documento.

Cada requisito recebe um ID ligado ao código, ao teste e ao roadmap. Se uma pessoa puder testar o resultado, o mesmo ID também é ligado a um roteiro do Dashboard.

Prompt → regras → S0/S1/S2 → documentos necessários → código → teste → roadmap → Dashboard

Como uma IA “pensa”?

Para entender por que a SDD é importante no desenvolvimento com IA, primeiro é preciso entender a diferença entre uma inteligência artificial e um programa tradicional. A palavra “pensa” é usada aqui como uma simplificação: o modelo realiza cálculos sobre padrões aprendidos; isso não significa que possua consciência ou experiências como uma pessoa.

Um programa tradicional segue regras explícitas

Imagine um sistema que decide se uma pessoa pode entrar em um evento. Na programação tradicional, poderíamos escrever uma regra como esta:

SE idade >= 18
  permitir entrada
SENÃO
  negar entrada

O computador não sabe o que significa ser maior de idade. Ele não compreende o evento, a pessoa ou a razão da regra. Apenas executa uma condição definida por quem programou. A lógica está explicitamente no código.

Nem todo problema cabe em um if/else

Problemas de linguagem, imagens e comportamento dependem de contexto. Uma mesma ação pode mudar de significado conforme a situação: causar um ferimento é normalmente algo ruim, mas uma incisão cirúrgica pode ser necessária para salvar uma vida. Tentar programar manualmente uma condição para cada possibilidade do mundo seria inviável.

É nesse tipo de problema que a IA se torna útil. Em vez de depender somente de uma lista completa de regras, ela aprende relações a partir de uma enorme quantidade de exemplos.

Como ideias diferentes se aproximam

Imagine que, durante o treinamento, o modelo encontre milhares de frases como estas:

Uma criança divide o lanche com um colega.

Uma vizinha leva comida para uma pessoa doente.

Um bombeiro entra em uma casa para retirar quem está em perigo.

Uma professora permanece depois da aula para ajudar um aluno.

As cenas falam de alimentos, doença, perigo e ensino. Mesmo assim, determinadas ideias aparecem repetidamente em contextos relacionados: dividir, ajudar, cuidar, proteger e solidariedade. Com exemplos suficientes, o modelo aprende que essas palavras e situações têm relações entre si.

dividir ─ ajudar ─ cuidar ─ proteger ─ solidariedade

A IA não cria uma gaveta literal chamada AJUDAR e coloca todas essas frases dentro dela. O que ela constrói é um grande espaço matemático no qual palavras, trechos, situações e conceitos podem assumir posições e direções relacionadas.

A matemática por trás das palavras

Para ser processado, o texto é dividido em unidades menores, chamadas tokens. Cada token é convertido em uma representação numérica que, de maneira simplificada, pode ser imaginada como uma lista de coordenadas — um vetor.

ajudar   → [0,82; 0,71; 0,14; ...]
cuidar   → [0,79; 0,76; 0,18; ...]
proteger → [0,75; 0,69; 0,27; ...]
explodir → [0,08; 0,11; 0,91; ...]

Os números acima são apenas ilustrativos. Em um modelo real, cada representação pode ter centenas ou milhares de dimensões. Não há uma coordenada isolada para “bondade”, “animal” ou “arquitetura”; o significado emerge da combinação de muitos valores e das relações entre eles.

Durante o treinamento, o modelo recebe partes de um conteúdo e tenta prever o que deveria aparecer a seguir. A previsão é comparada ao exemplo real, o erro é transformado em um valor numérico e um algoritmo ajusta os parâmetros internos para reduzir erros futuros. Esse ciclo se repete bilhões de vezes.

muitos exemplos
      ↓
previsões e erros
      ↓
ajustes numéricos nos parâmetros
      ↓
representações de palavras e contextos
      ↓
relações e probabilidades aprendidas

A “mágica” das palavras associadas

Palavras usadas em contextos semelhantes tendem a adquirir representações matemáticas relacionadas. Por isso, ajudar, cuidar e proteger podem ficar mais próximas nesse espaço, enquanto uma palavra empregada em situações muito diferentes tende a apontar para outra região.

Mas a IA não depende apenas da palavra isolada. “Explodir de alegria” não significa o mesmo que “explodir uma ponte”. Mecanismos de atenção calculam quanto cada parte do texto deve influenciar as demais. Assim, o contexto modifica a representação e ajuda o modelo a distinguir sentidos.

O que parece mágica é o resultado de muitas multiplicações, somas, comparações e transformações numéricas executadas em várias camadas. Cada camada refina as relações consideradas relevantes para o contexto atual.

Como uma resposta é construída

Quando recebe uma pergunta, o modelo processa os tokens, combina suas relações ao longo dessas camadas e calcula probabilidades para a próxima unidade da resposta. Depois de escolher um token, repete o processo para o seguinte. A resposta surge passo a passo.

pergunta → tokens → vetores → atenção ao contexto → probabilidades → próximo token → resposta

Isso permite generalizar. Mesmo sem ter visto exatamente aquela pergunta, o modelo pode relacioná-la a padrões aprendidos e produzir uma continuação coerente. Entretanto, a continuação mais provável não é necessariamente verdadeira, segura ou adequada ao produto.

A IA compreende como uma pessoa?

Não da mesma forma. Uma pessoa associa conceitos a experiências, sentidos, objetivos e emoções. A IA aprende relações presentes nos dados. Ela pode relacionar perda, luto, tristeza e saudade com grande sofisticação sem ter sentido saudade.

perda → luto → tristeza → saudade → sofrimento

Por isso, uma resposta pode parecer profundamente compreensiva sem resultar de uma experiência consciente. O modelo conhece padrões de como seres humanos descrevem essas ideias, e não precisa vivenciá-las para produzir linguagem sobre elas.

Um mapa gigantesco de relações

Uma maneira simples de imaginar uma IA moderna é como um mapa multidimensional de palavras, ideias, objetos, estilos, situações e estruturas. Cachorro se relaciona com animal, latir, coleira e veterinário; avião se relaciona com voo, asa, piloto, aeroporto e altitude.

cachorro ─ animal ─ mamífero
   ├── latir
   ├── coleira
   └── veterinário

avião ─ voo ─ aeroporto
   ├── piloto
   ├── asa
   └── altitude

O mapa real é incomparavelmente maior e mais complexo. A maior parte dessas relações não foi escrita manualmente por um programador: foi aprendida por meio dos ajustes numéricos do treinamento.

A diferença essencial

Sistemas modernos normalmente combinam as duas abordagens. A IA oferece interpretação e generalização; o software tradicional aplica contratos, permissões, validações e regras críticas. No desenvolvimento de software, a SDD é o mecanismo que conecta essas capacidades sem entregar à probabilidade o controle sobre o produto.

Desenvolvimento com IA e SDD

Como a IA trabalha com padrões e probabilidades, o desenvolvimento assistido precisa combinar sua capacidade de geração com regras, contratos e validações explícitas. É essa combinação que permite ganhar velocidade sem perder o controle técnico do projeto.

Por que a IA precisa da SDD

A IA pode produzir código plausível sem conhecer a intenção real do produto. A SDD reduz essa distância: registra antes da implementação o comportamento esperado, os limites, os critérios de aceite e as evidências necessárias. Assim, a IA não trabalha apenas com o que “parece fazer sentido”; trabalha com uma fonte versionada que pode ser confrontada com código e testes.

Intenção humana → SDD → contexto para a IA → implementação → testes e evidências → validação humana

De vibe coding à liderança técnica

Para alguns desenvolvedores, ainda é difícil imaginar como deixar a IA escrever o código sem perder o controle do projeto. Com SDD, a função humana muda de execução linha a linha para direção técnica: definir o que deve ser construído, de que forma, dentro de quais limites e segundo qual arquitetura.

É uma atuação próxima à de um Team Leader. Em vez de executar pessoalmente cada etapa, você orienta: “faça isto, siga esta abordagem, preserve este contrato, evite esta gambiarra e comprove o resultado com estes testes”. A IA implementa; a spec mantém a intenção explícita; e o profissional acompanha, corrige e decide.

A relação também pode ser comparada à de um engenheiro responsável por uma obra. Ele não precisa assentar cada tijolo para continuar no comando, mas precisa definir o projeto, coordenar a execução e verificar se a construção atende ao que foi especificado. Delegar a produção do código não transfere a responsabilidade por arquitetura, segurança, qualidade ou resultado.

Vibe coding: pedido → código plausível → tentativa e erro

SDD com IA: intenção → especificação → delegação → código gerado → revisão → evidência

Aplicação no SWIX

No projeto SWIX, a IA acelera análise, implementação, testes e documentação; ela não substitui decisão de produto, regra de negócio nem validação. A SDD funciona como o contrato entre a intenção humana e a execução assistida por IA, preservando rastreabilidade entre requisito, código, teste, roadmap e Dashboard.

O resultado é um modelo híbrido: regras críticas continuam explícitas e testáveis, enquanto a IA ajuda a navegar contexto, reconhecer padrões e construir mudanças com mais velocidade. Quando houver conflito, prevalecem a spec, as regras do repositório e a evidência validada.

Cloud, Firebase e arquitetura do Swix

Quando alguém abre o Swix no navegador, parece que existe apenas uma página: faz login, clica em uma função e recebe uma resposta. Por trás dessa experiência há serviços com responsabilidades diferentes. A ideia não é colocar “tudo no Firebase”, mas usar cada peça no trabalho que ela resolve melhor.

O Firebase cuida da entrada do usuário na aplicação e da entrega dos portais web. O Google Cloud executa os serviços que aplicam as regras do negócio. O banco, as integrações e os arquivos entram no fluxo somente depois que o Core sabe quem é a pessoa, qual produto ela está acessando e quais permissões possui.

O caminho de uma ação

Pense em uma pessoa que abre o Swix A para consultar um cliente. Primeiro, ela recebe o portal web. Depois, entra com sua conta. Só então o navegador pede os dados ao Core. O Core verifica a identidade, aplica as permissões e consulta os recursos necessários para responder. A tela nunca deveria decidir sozinha se uma pessoa pode ver ou alterar algo.

1. Firebase Hosting entrega a interface web
2. Firebase Authentication identifica a pessoa e cria a sessão
3. O navegador envia o token de identidade para a API
4. Cloud Run executa o Core e valida acesso, produto, cliente e permissões
5. O Core consulta banco, integrações ou arquivos quando necessário
6. A resposta volta para a interface já dentro das regras do Swix

O que cada serviço faz

Login não é autorização

Login responde “quem é esta pessoa?”. Autorização responde “o que esta pessoa pode fazer neste contexto?”. O Firebase resolve a primeira pergunta. O Core resolve a segunda: valida o token, encontra o usuário, aplica a allowlist ou o provisionamento, verifica papel, produto, cliente e permissão. Essa separação evita que uma regra crítica fique exposta apenas no JavaScript da página.

Os e-mails também têm papéis distintos. A recuperação de senha é um recurso do Firebase Authentication. Já os e-mails transacionais do produto — por exemplo, notificações e retornos operacionais — são enviados pelo Core via SMTP oficial. Em homologação, esses envios são redirecionados para uma caixa de teste, para não atingir destinatários reais por acidente.

Há Docker por trás?

Sim, no backend. Um Dockerfile descreve uma imagem reproduzível: qual versão do Python usar, quais dependências instalar e como iniciar a API. No deploy, essa imagem é construída, guardada no Artifact Registry e executada pelo Cloud Run. Isso torna a execução consistente entre máquinas e ambientes.

A diferença importante é que a equipe não precisa manter servidores ou containers manualmente. O Cloud Run recebe a imagem, cria revisões e direciona o tráfego para a versão aprovada. Docker continua existindo como embalagem da aplicação; a operação da infraestrutura que o executa é gerenciada pela plataforma do Google Cloud.

Como isso difere de subir um servidor com WildFly?

No modelo tradicional, seria preciso preparar uma máquina, instalar Java e WildFly, publicar o artefato da aplicação, configurar HTTPS, certificados, processos, logs, atualizações de segurança, capacidade e rollback. Esse modelo continua válido em cenários específicos, mas deixa mais responsabilidades operacionais com o time.

No Swix, o frontend é entregue pelo Firebase Hosting e o backend é executado pelo Cloud Run. Isso reduz a necessidade de administrar uma VM ou um servidor de aplicação, sem eliminar a responsabilidade da Swix: ainda é preciso cuidar do código, banco, permissões, segredos, custos, monitoramento e qualidade. O desenvolvimento local continua útil para criar e testar; homologação e produção existem para validar o sistema no ambiente que realmente o executa.

Modelo tradicional: código → servidor próprio → WildFly → operação manual

Modelo Swix: código → imagem Docker → Cloud Run + Firebase → operação gerenciada

Fluxo de execução no Codex

1. Aplicar as regras do repositório

   Ao trabalhar no repositório, o Codex aplica AGENTS.md. O arquivo define regras de engenharia, limite de contexto, validação e quando usar SDD ou Graphify.

2. Classificar a mudança

   AGENTS.md aponta para docs/specs/README.md. Esse arquivo define S0, S1, S2, os IDs e a ligação entre requisito, teste, roadmap e Dashboard.

3. Ler somente as fontes necessárias

   O Codex abre somente as fontes ligadas ao escopo. Uma mudança de billing consulta a spec de billing e suas regras; não precisa carregar a documentação de WhatsApp.

4. Escolher os documentos

   S0 usa a regra existente. S1 cria ou atualiza uma SPEC.md. S2 usa SPEC.md, PLAN.md e TASKS.md. Em S1, plano e tarefas podem ficar dentro da própria spec. Uma spec existente deve ser atualizada em vez de duplicada.

5. Implementar e testar

   O código atende ao requisito. Uma correção local pode usar um teste focado; uma mudança de contrato pode exigir teste de integração ou de contrato.

6. Atualizar roadmap e Dashboard

   Toda mudança relevante atualiza o roadmap. Se houver teste funcional, o tópico do Dashboard recebe o ID do requisito em requirement_ids.

7. Executar a verificação final

   S1 e S2 executam python3 scripts/check_sdd_docs.py e os testes relacionados. Graphify só é atualizado quando arquivos ou relações do projeto mudam de forma relevante.

Prompt
→ AGENTS.md
→ docs/specs/README.md
→ S0 / S1 / S2
→ fontes do domínio
→ SPEC / PLAN / TASKS quando aplicável
→ código e teste
→ roadmap
→ Dashboard quando observável
→ check_sdd_docs.py
→ Graphify quando necessário

Fonte de regras

As regras do Swix ficam em arquivos Markdown versionados junto com o código. Assim, regra e implementação podem ser revisadas no mesmo histórico. Cada arquivo tem uma função, e o Codex abre somente os necessários. Em caso de dúvida, comece por AGENTS.md.

Regras do repositório

Produto e arquitetura

Especificações e progresso

Contexto de engenharia

Use estas práticas para manter o código simples, testável e fácil de mudar. Crie abstrações somente quando houver uma necessidade concreta.

Estrutura do código

• Angular/TypeScript: separar models, componentes, facades/services e helpers por feature.
• Python: separar modelos, schemas, responses, routers, stores, serviços, adaptadores e domínio.
• Arquivos de fachada podem reexportar contratos, mas não concentrar toda a implementação.

Banco e APIs

• Integridade, unicidade e invariantes são protegidas no backend e no banco.
• Operações dependentes usam transação; consultas evitam N+1 e SELECT *.
• Listagens que podem crescer usam limite, paginação ou cursor.
• Autenticação, autorização, isolamento e dados sensíveis não dependem do frontend.

Entrega e testes

• Entregue itens de sprint em fatias funcionais, não em microtarefas mecânicas.
• Comece por testes focados. Rode suites amplas quando o risco exigir.
• Só avance checkpoint e roadmap depois de implementação, teste e evidência.
• Carregue contexto, agentes e ferramentas de maior custo somente quando necessários.

Codex, agentes e skills

Codex implementa mudanças no repositório. Subagentes são temporários e executam trabalho em paralelo. Skills são instruções especializadas. Agentes do produto executam no sistema publicado.

Configuração do repositório

• codex-primary é o agente principal sob demanda.
• codex-subagents representa subagentes temporários, nunca processos persistentes.
• O monorepo distribui as skills marini-mood-growth, searchs-plan, tasks-swix, swix-vertical-experience, swix-adjustment-processor, swix-quality-guardian e swix-roadmap-governor em .codex/skills/.
• Os arquivos agents/openai.yaml são metadados de descoberta das skills; não iniciam agentes em segundo plano.
• scripts/sync_codex_skills.sh mantém a instalação local idêntica às fontes versionadas.
• tests/test_agent_free_operations.py garante a presença do registro aprovado e a ausência de execução autônoma oculta.
• Scripts de roadmap e ajustes não executam codex exec em segundo plano.
• Graphify e Swix Roadmap Governor pertencem ao ambiente de desenvolvimento e são usados sob demanda.

Agentes do produto

Agentes de runtime não alteram o repositório e seguem os contratos de identidade, billing, segurança, auditoria, canais e isolamento do Swix. O status de cada capacidade é explícito:

• meta-business-agent: contrato de integração implementado; a operação real depende da ativação da plataforma Meta.
• swix-roadmap-probe: fallback técnico implementado quando o agente Meta não está ativo.
• ai-gateway: modelo operacional versionado, com runtime ainda pendente no roadmap.
• graphify-index: ferramenta de desenvolvimento sob demanda, protegida por gate de atualização no CI; não é agente de runtime.

Catálogo de skills e agentes Codex

Consulte o inventário completo: nome, função descrita na fonte, origem e situação. Ele inclui as skills do Swix, as instaladas no Codex e os plugins locais, distinguindo cache de habilitação confirmada. A disponibilidade pode variar por sessão.

Os perfis de especialistas são separados dos subagentes temporários e dos agentes do produto. Metadados de uma skill não significam um agente em execução.

Manutenção contínua do Swix Documents

A documentação deve acompanhar cada entrega relevante. Uma revisão semanal confere mudanças na arquitetura, integrações, ferramentas, processos e pendências, sem declarar como concluído o que ainda depende de validação ou terceiros.

Ritos e automações

O registro canônico é docs/engineering/operating-model.json. Ele liga cada item desta página a uma fonte versionada e é verificado por teste. Ritos exigem decisão humana; automações executam gates ou rotinas operacionais com gatilho explícito.

Ritos de engenharia e operação

Automações ativas

Controles manuais

• Deploys de produção e homologação partem da main e exigem alvo e ambiente explícitos: Core, Admin, Corporate, Backlog, Documents, Engineering, Swix One, pacote estático ou sistema completo.
• Skills orientam o Codex, mas não executam sozinhas.
• A fila de ajustes só é encerrada após correção, teste e confirmação do operador.
• Status do roadmap só é promovido pelo rito de evidência; CI verde isolado não equivale a aceite funcional.

CI/CD e Gates

CI/CD é o fluxo automatizado que verifica uma mudança e controla sua entrega. CI significa integração contínua: cada pull request e cada push na main passam por testes, builds e verificações. CD significa entrega contínua: depois dos checks, um deploy pode ser disparado manualmente para homologação ou produção com ambiente e alvo explícitos.

Um gate é uma condição de passagem. Se um job falha, a mudança não deve avançar para o próximo estágio do fluxo. No Swix, os gates combinam código executável, documentação, rastreabilidade e evidência operacional; um checklist sozinho não substitui uma verificação automatizada.

O fluxo no Swix

Pull request ou push na main
        ↓
CI: testes Core + Swix One + frontend/build
        ↓
Gates: qualidade + SDD + Graphify
        ↓
CD manual: homologação ou produção, com alvo explícito
        ↓
Smoke test, aceite funcional, rollback e go/no-go

Checks e gates implementados

Como o deploy é protegido

• O job deploy depende de Core, Swix One, frontend, qualidade e Graphify.
• O deploy não acontece automaticamente em todo push: ele é acionado por workflow_dispatch.
• O operador escolhe explicitamente homolog ou production e um alvo como Core, Admin, Corporate, Documents, Engineering, Swix One ou all.
• A autenticação usa Workload Identity Federation; credenciais não ficam no código.
• Depois da publicação, o roteiro de release exige smoke test técnico, jornada afetada, evidência, rollback e decisão de go/no-go.

O que está funcionando e o limite atual

O workflow está versionado em .github/workflows/swix-quality.yml e os gates falham de fato quando encontram regressões. O script ci_graphify_check.sh valida hashes dos arquivos, e o quality ratchet diferencia dívida histórica de piora nova para evitar esconder regressões dentro do baseline.

O fluxo de CI/CD e o bloqueio do deploy estão implementados. A proteção do merge é uma camada separada do YAML: CODEOWNERS e o template de pull request orientam a revisão, mas só uma branch protection ou ruleset do GitHub torna os checks obrigatórios antes do merge. Essa exigência deve ser confirmada na configuração do repositório e não é presumida apenas porque o CI existe.

Fontes principais: .github/workflows/swix-quality.yml, platform/swix-zero/scripts/swix_quality_audit.py, platform/swix-zero/scripts/ci_graphify_check.sh e platform/swix-zero/ops/release-acceptance.md.

Classificação S0, S1 e S2

O impacto da mudança define o nível S0, S1 ou S2 e quais arquivos serão usados.

Aqui, comportamento significa um resultado observável, uma regra de negócio, um contrato de API, uma alteração persistida ou uma regra de acesso.

Regra de decisão

1. Se a solicitação não cria comportamento novo, classificar como S0.
2. Se altera um comportamento delimitado em um domínio, classificar como S1.
3. Se atravessa componentes, integrações ou arquitetura, classificar como S2.

Uma correção é S0 quando restaura uma regra existente. Se criar uma regra ou alterar um contrato, ela passa a S1 ou S2.

Exemplo: ajustar um texto é S0; criar um endpoint de um domínio é S1; criar um microsserviço ou uma integração externa é S2.

SPEC, PLAN e TASKS

Pense assim: SPEC define o que deve acontecer; PLAN define como será implementado; TASKS divide o trabalho em entregas verificáveis.

- [ ] `Swix-BILL-001-T03` Concluir homologação com o provedor.
  - atende: `Swix-BILL-001-R01`, `Swix-BILL-001-R04`
  - evidência: pendente

IDs e requisitos

IDs conectam specs, tarefas, código, testes, roadmap e Dashboard. Use o mesmo ID em todas essas fontes para localizar a implementação e a evidência sem depender do nome da feature.

EARS e GEARS

EARS e GEARS são convenções para escrever requisitos com condição e resultado explícitos; não são ferramentas executadas pelo Codex. Use-as quando o comportamento precisa ser testado sem ambiguidade.

Quando um evento financeiro válido for confirmado,
o Swix Core deve aplicá-lo de forma idempotente à assinatura
e registrar auditoria.

Roadmap, Dashboard e testes

Roadmap corporativo

development-steps/TODO_ESCOPO_FINAL.md é o registro oficial do projeto. Ele mostra status, evidências, pendências, bloqueios e próximas ações. As specs descrevem a mudança; o roadmap mostra seu estado.

Dashboard

O Dashboard publica roteiros de validação humana. O script scripts/build_roadmap_portal.py liga cada validation-topic-N aos requisitos da spec por meio de requirement_ids.

Uma mudança observável exige atualizar esse vínculo. Refactors, reorganizações e otimizações sem resultado visível ficam cobertos somente por testes técnicos.

Verificação documental

scripts/check_sdd_docs.py verifica:

• presença dos documentos estruturais;
• IDs de specs e requisitos duplicados;
• PLAN e TASKS obrigatórios em S2;
• tópicos do Dashboard sem requisito;
• requisitos referenciados pelo Dashboard que não existem.

Esse script valida os documentos e suas relações. Ele não substitui os testes do código.

Graphify

Graphify mostra as relações entre arquivos, requisitos, decisões e componentes. Use-o para consultar a arquitetura e investigar mudanças que atravessam vários arquivos.

No grafo, cada arquivo ou requisito é um nó. As conexões mostram quais itens dependem ou fazem referência uns aos outros.

Código e Markdown são as fontes oficiais. Graphify é um índice gerado a partir deles.

Consultar o grafo é uma leitura. Regenerá-lo reprocessa os arquivos e custa mais, por isso fica reservado para mudanças relevantes de código, contrato ou arquitetura.

Regra de uso

• Use busca direta para ajustes locais.
• Consulte o grafo para arquitetura e dependências.
• Regenere o grafo após mudanças relevantes em arquivos, contratos ou arquitetura.
• Não regenere o grafo para alterações simples de texto, CSS ou configuração.

Novos microsserviços

Todo novo microsserviço começa como S2 porque adiciona produto, contratos com o Core, código, dados, deploy e validação próprios.

O Core mantém serviços compartilhados, como identidade, billing e auditoria. A vertical contém somente as regras específicas do novo produto.

1. Confirmar caso de uso, público e limites da vertical.
2. Definir o product-key e o domínio curto. Exemplo: clinic nos arquivos e CLINIC nos IDs.
3. Criar docs/specs/<vertical>/SPEC.md, PLAN.md e TASKS.md.
4. Relacionar Constituição, modelo de domínio e ADRs aplicáveis.
5. Criar ADR somente quando houver uma decisão arquitetural nova.
6. Gerar a estrutura com ./scripts/create_microservice.sh <product-key> "<display-name>".
7. Manter identidade, billing, canais, IA e auditoria no Core.
8. Implementar na vertical somente as regras específicas do produto.
9. Registrar a iniciativa e as evidências no roadmap.
10. Criar validação no Dashboard para comportamentos observáveis.
11. Executar verificação SDD, testes de contrato e isolamento.
12. Atualizar Graphify quando a nova estrutura estiver consolidada.

microservices/<product-key>/
├── backend/
├── frontend/
├── db/
└── README.md

docs/specs/<vertical>/
├── SPEC.md
├── PLAN.md
└── TASKS.md

Encerramento de uma entrega

Antes de concluir a tarefa, confirme os itens abaixo.

• requisito implementado;
• teste técnico necessário executado;
• evidência registrada;
• SPEC atualizada em S1/S2 e, em S2, PLAN e TASKS atualizados;
• roadmap corporativo atualizado;
• requirement_ids atualizados quando houver validação humana;
• python3 scripts/check_sdd_docs.py aprovado;
• Graphify atualizado somente quando necessário;
• status promovido somente com evidência.

Specs ativas

Consulte uma spec ativa antes de criar um novo ID para o mesmo domínio.