Versão 1.1 · Atualizado em 04 de agosto de 2026

GUIA DE APLICAÇÃO, MDS

Como instanciar o MDS em qualquer projeto novo ou existente. Roteiro operacional.

Pré-requisitos

• Conhecimento prévio do Manifesto (7 princípios + 14 anti-patterns)
• Conhecimento da Nomenclatura dos Blocos (BASE/PLUGIN/STACK)
• Leitura do Template Completo (86 campos em 15 blocos: 0 e A a N)

Roteiro de aplicação em 7 passos

Passo 1: decidir o formato do artefato

Toda instância MDS é um documento que renderiza o template. O formato varia conforme contexto:

A categoria de cada bloco (BASE/PLUGIN/STACK) não muda com o formato: só muda a quantidade de páginas que cada bloco ocupa.

Independente do formato, todo DRS aprovado gera a família de 5 artefatos (DRS + Roadmap + Inventário + Jornadas + Plano de Testes, Passos 7.1 a 7.4) e pertence a uma entidade (cliente direto Modulareasy ou cliente indireto de parceiro, Passo 7.5). Pergunte a entidade ao iniciar.

Passo 2: preencher os 22 BLOCO-BASE

Antes de qualquer outra coisa, preencher TODOS os 22 BASE com conteúdo real (não placeholder). Lista completa:

1. A1 Nome do sistema
2. A2 Problema que resolve
3. A3 Domínio
4. A4 Stakeholders
5. A5 Glossário
6. A6 Escopo + Não-escopo
7. A7 Premissas e restrições
8. B1 Atores
9. B3 Jornadas principais
10. C1 RFs catalogados
11. D1 Performance esperada
12. D2 Segurança/auth
13. D5 Auditabilidade (Modulareasy)
14. D10 Cadastro progressivo (Modulareasy)
15. G1 Stack
16. H1 Spec mínima por RF
17. I1 Estratégia de testes
18. I2 Critérios de aceitação
19. L1 Política de entitlement (Modulareasy)
20. M1 Mapa de automações cross-módulo (Modulareasy)

Nota: na contagem aparece 20 porque 4 são “BASE Modulareasy-opinionated”, e instâncias externas podem tratar esses 4 como PLUGIN. Modulareasy sempre BASE.

Se algum BASE não pode ser preenchido → STOP: você ainda não tem projeto, tem ideia. Volte 1 fase (elicitação conceitual) e responda os campos antes de prosseguir.

Passo 3: iterar pelos 38 BLOCO-PLUGIN respondendo gatilhos

Para cada PLUGIN do template, perguntar o gatilho em voz alta (literalmente, em formato S/N):

• “Há ≥2 perfis humanos com permissões distintas? S/N”, e se S, preencher B2.
• “Há cálculo/lógica não-trivial OU regra mutável por admin? S/N”, e se S, preencher C2.
• … (continuar por todos os demais)

Para cada resposta N, escrever N/A: [motivo em 1 linha] no campo. Sem exceção.

Tempo realista: 38 PLUGIN × 30 segundos cada = ~20 minutos pra responder todos os gatilhos. Preenchimento de conteúdo dos que disparam varia por projeto.

Passo 4: avaliar os 26 BLOCO-STACK

Para cada STACK, perguntar honestamente:

• “O projeto está num nível de maturidade/criticidade que justifica este bloco?”

Se sim → preencher. Se não → omitir (sem necessidade de declarar N/A). Sem pressão de checklist completo. STACK acompanha o projeto crescer.

Passo 5: validar com check de coerência

Antes de declarar instância MDS pronta:

• Todos os 22 BASE preenchidos com conteúdo real (não placeholder)?
• Todos os 38 PLUGIN têm resposta de gatilho explícita (preenchidos OU N/A: motivo)?
• Não há contradição entre blocos (ex: D1 promete sub-200ms E I7 omitido sem performance tests planejados)?
• Princípios 5, 6, 7 do Manifesto refletidos nos blocos L e M (Modulareasy-opinionated)?
• Anti-patterns do Manifesto auditados (banner-fix, gambiarra, hardcode, falha silenciosa, etc)?

Se tudo OK → registre a Conformidade MDS (cobertura de blocos + respostas de gatilho) nas SUAS notas, FORA do documento do cliente (a Conformidade e o gate são sobre o método, não entram no DRS do cliente) e siga para o Passo 6.

Passo 6: validação final do documento (gate das 2 perguntas)

Ao fim da montagem e antes de declarar a instância pronta ou enviá-la para aprovação, releia o documento inteiro e responda:

Pergunta 1, o documento cumpre seu propósito? (suficiência) “Se eu recebesse este documento sem ter participado da sua construção, conseguiria entender e implementar o sistema sem dúvidas?”

• Não → liste as lacunas concretas (módulo sem RFs detalhados, RNF sem métrica, entidade sem modelo de dados, capability sem critério de aceitação) e complete-as antes de aprovar.

• Checagem de artefatos-fonte (obrigatória): para CADA artefato que o cliente forneceu na elicitação (planilha, sistema/tela existente, documento, export), a ESTRUTURA dele foi refletida no Modelo de Dados, e não só a saída ou a fórmula visível? Liste cada artefato e onde sua estrutura aparece. Cardinalidade é o gargalo: se um artefato mostra “vários X por Y” (ex.: várias linhas de cargo por serviço numa planilha), o modelo TEM que ser N:N, nunca 1:1 com um campo-proxy. Capturar só o resultado e simplificar a estrutura é erro de elicitação, não “requisito novo a descobrir depois”. O caso que ensinou: a planilha de precificação chegou no primeiro dia, o documento modelou um cargo por serviço em vez de vários, e a lacuna só apareceu meses depois, na validação.

• Checagem de falseabilidade (obrigatória): para CADA requisito novo ou alterado, complete a frase “este requisito é violado quando ___” com um fato verificável (uma contagem, uma presença, uma ausência). Não completou, não passa. Requisito que não tem como reprovar nada atravessa as duas perguntas deste gate sem esforço e ainda assim deixa o defeito entrar; por isso a falseabilidade é checagem própria, e não consequência das outras duas. Detalhe e armadilhas na seção “Três exigências que a prática acrescentou”, adiante.

Pergunta 2, o documento segue o MDS? (conformidade) “Tem coisas a mais ou a menos em relação ao que o MDS define?”

• Não → o defeito está no documento (corrigir o documento) ou na metodologia (o documento revelou uma lacuna real do método → registrar evolução)?

A segunda pergunta faz de cada documento um teste vivo da metodologia: documentos reais expõem onde o MDS precisa evoluir. As respostas ficam registradas; lacunas são resolvidas antes da aprovação, nunca depois.

Passo 7: construção a partir do Roadmap publicado

Depois que o documento passa no gate (Passo 6) e é aprovado, a construção começa, e ela parte do Roadmap publicado: card a card, na ordem em que os cards estão, até os cards de construção fecharem. O estado de cada card vive no artefato publicado, o mesmo que a equipe e o cliente abrem, e não numa mensagem transmitida de uma sessão para a outra.

Não existe um passo intermediário de reescrever o plano em outro documento. O contexto durável já está publicado e cruzado: o DRS é a lei (o que o sistema faz e qual o critério de aceite de cada requisito), o Roadmap é a fila (o que vem agora e como verificar), o Inventário é a ficha (o que precisa existir e como deve ser construído) e o Plano de Testes é o aceite. Um documento de passagem escrito à mão seria mais uma cópia do mesmo estado, que envelhece no instante em que qualquer um dos quatro muda. Quem retoma o trabalho relê os artefatos publicados; quem termina uma etapa marca o card, e a marcação é o recado.

O que fecha um card está no Passo 7.1 e detalhado no Roadmap de Implementação: não basta o código existir e o teste passar; o papel que deveria usar aquilo precisa alcançar e usar.

O arquivo de construção do projeto não é o quinto companheiro. Um projeto em construção costuma manter, no seu próprio repositório, um arquivo que governa o ciclo de construção (por onde retomar, quando parar, e os fatos duráveis do ambiente em que ele roda). Esse arquivo nunca é publicado, porque carrega fatos de infraestrutura que não pertencem a um documento de cliente. Ele vive no repositório do projeto; a família publicada continua sendo cinco.

Quando o documento de passagem continua sendo o caminho certo. Projeto sem família MDS publicada não tem Roadmap para ler: trabalho exploratório, prova de conceito e correção pontual urgente seguem sendo passados adiante por um documento de passagem, que descreve o estado e o próximo passo. A regra é de precedência, não de proibição: onde existe família publicada, ela é a fonte do estado; onde não existe, escreve-se a passagem.

Passo 7.1: Roadmap de Implementação (artefato durável padrão)

O artefato padrão que todo DRS aprovado gera é o Roadmap de Implementação: um documento-companheiro durável, publicado ao lado do DRS, que traduz os requisitos em tarefas claras, em sequência, com checklist de feito ou não feito, orientadas a verificação-primeiro (TDD). É a fila que a construção percorre (Passo 7) e a ponte entre “o que o sistema deve fazer” (DRS) e “construído e verificado” (produção).

O Roadmap abre com a Fase 0 de Planejamento: 28 cards com prefixo P0-, todos marcados como concluídos na aprovação do DRS, tornando visível o trabalho de elicitação, especificação, geração dos companheiros e aprovação. Isso faz o projeto nascer em 40% de progresso em vez de 0%. O progresso do projeto tem 3 seções de peso fixo: Planejamento 40% (a Fase 0), Construção 40%, Testes 20%.

Regras do Roadmap (ver Roadmap de Implementação para o detalhe):

• Verificação-primeiro (TDD): cada tarefa declara primeiro o teste (o observável que prova que está pronta) e depois como construir. Em projeto de código, é o teste que falha antes de existir a implementação; em configuração de plataforma, é o critério observável que se confere após configurar. A ordem é sempre teste antes de construção.
• Sequência e dependência: as tarefas seguem a ordem de construção da seção de Entrega (ondas/módulos do DRS). Nunca uma tarefa antes daquela de que depende.
• Rastreável ao DRS: cada tarefa aponta para o(s) RF que satisfaz; cada RF do DRS é coberto por ao menos uma tarefa.
• Código estável por tarefa: cada item tem um código curto e estável (ex.: F1-03), que serve de âncora e de identificador do estado do checklist.
• Estado compartilhado: o feito/não feito é persistido e compartilhado (quem abre o link vê o mesmo progresso), com barra de progresso por fase.
• Pronto é benefício recebido: um card só fecha quando o papel que deveria usar aquilo alcança e usa, não quando o código existe e o teste passa. O card declara também quem, em produção, alimenta aquela peça.
• Link mútuo: o DRS aponta para o Roadmap e o Roadmap aponta de volta para o DRS.

Na infraestrutura Modulareasy, o Roadmap é um documento doc_kind = 'roadmap' com parent_slug apontando para o DRS; o checklist é renderizado interativo e o progresso vive em tabela própria. DRS e Roadmap são publicados juntos.

Passo 7.2: Inventário de Artefatos (registro de completude)

Ao lado do Roadmap, todo DRS gera um segundo companheiro padrão: o Inventário de Artefatos. Enquanto o Roadmap diz em que ordem construir, o Inventário lista tudo que precisa ser criado e cadastrado (funis, automações, tags, campos, integrações, papéis, dashboards), agrupado por tipo, cada artefato com seu checkbox, para responder de relance: “já criei todos os funis? todas as automações?”. Cada artefato declara o que é, para que serve, com o que se relaciona (RF e tarefa do Roadmap) e onde fica na plataforma. É um documento doc_kind = 'inventory' com parent_slug para o DRS, e reusa a renderização e o progresso do Roadmap.

Passo 7.3: Jornadas dos Atores (operação por função)

O terceiro companheiro padrão são as Jornadas dos Atores: um documento textual que descreve como cada papel opera o sistema, função por função (como entra, onde entra, o que faz), escrito por função e não por pessoa (genérico e abstrato, sem nomes próprios). Complementa o bloco de Atores do DRS (que é orientado a fluxo e capability) com a visão de cada papel no seu dia a dia, e serve a treinamento, onboarding e validação pela ótica do operador. É um documento doc_kind = 'journeys' com parent_slug para o DRS.

Passo 7.4: Plano de Testes (validação em Alfa e Beta)

O quarto companheiro padrão é o Plano de Testes: um documento doc_kind='tests' com parent_slug apontando para o DRS. É um checklist em duas seções:

• Alfa (interno): um item por RF usando o critério H1 do DRS, mais testes gerais de visual, segurança, performance, mobile e regressão. Executado pela equipe antes de entregar ao cliente.
• Beta (com o cliente): um item por jornada dos Atores, mais coleta de feedback. Executado com o cliente e usuários reais após o Alfa ser concluído.

É a seção Testes do progresso em 3 seções (peso 20%). Reusa a renderização e o mecanismo de progresso dos outros checklists (checklist interativo, estado compartilhado, barra de progresso). O Plano de Testes é publicado junto com os outros companheiros na entrega do DRS.

Os cinco artefatos (DRS, Roadmap, Inventário, Jornadas, Plano de Testes) formam uma família e se cruzam: cada um aponta para os outros quatro. O DRS diz o que o sistema faz; o Roadmap, em que ordem construir; o Inventário, o que precisa existir; as Jornadas, como cada papel opera; o Plano de Testes, o que validar. O progresso do projeto tem 3 seções de peso fixo (Planejamento 40%, que é a Fase 0, Construção 40% e Testes 20%), e na entrega do DRS aprovado o projeto nasce em 40%.

Referência cruzada a partir dos blocos do DRS (padrão). Além do bloco de companheiros no topo do DRS, cada bloco relevante aponta para o seu companheiro: o bloco Atores e Jornadas referencia as Jornadas dos Atores; o bloco Entrega e Evolução referencia o Roadmap; o bloco Modelo de Dados (e os catálogos de artefatos nos apêndices) referencia o Inventário; o bloco Qualidade e Testes referencia o Plano de Testes. Assim, de qualquer ponto da especificação o leitor chega ao artefato operacional correspondente.

Passo 7.5: entidade e publicação (direto vs parceiro)

Um MDS pertence a uma entidade: um cliente direto (Modulareasy) ou um cliente indireto de um parceiro (a estrutura da Modulareasy atende clientes próprios e clientes de parceiros). A entidade define a identidade visual e o caminho público, mas todos os MDS vivem no mesmo sistema, sob /mds, gerenciáveis e visíveis num só lugar. Ao criar um MDS, decida a entidade:

• Cliente direto (Modulareasy): publicado em /mds/<projeto>, com a identidade Modulareasy.
• Cliente indireto (parceiro): publicado em /mds/<parceiro>/<projeto>, como documento white-label com a identidade visual do parceiro (a IDV de cada parceiro fica salva e é reaproveitada). No conteúdo white-label, a marca Modulareasy não aparece.

A família inteira de um projeto (DRS e os 4 companheiros) compartilha a mesma entidade e o mesmo caminho-base.

Três exigências que a prática acrescentou

Três defeitos apareceram em todos os projetos acompanhados por MDS sem que nada no método os proibisse. Viraram exigência: a primeira é uma propriedade de todo requisito, a segunda é o critério de fechamento de um card, a terceira é a forma de construir qualquer trava.

1. Todo requisito precisa poder reprovar alguma coisa

Requisito que não tem como ser violado não é requisito, é intenção. Para cada requisito escrito ou alterado, complete “este requisito é violado quando ___” com um fato verificável. Não completou, não entra no documento.

Duas armadilhas produzem requisitos que nunca reprovam nada:

• Enumeração aberta. “Os eventos como A, B e C são emitidos” é ilustração, não requisito: qualquer item fora da lista fica de fora sem violar coisa alguma. Nomeie o conjunto exato ou dê a regra que o gera.
• Verbo que delimita mais do que parece. “Não retornar dados” proíbe leitura e não proíbe disparar ação. Liste nominalmente o que o requisito proíbe.

O caso que ensinou: um requisito dizia que “o histórico disponível é trazido”, e todo conector passou no aceite enquanto o painel exibia dois meses de dados e a fonte tinha três anos e meio. O número errado chegou ao cliente. O agravante é que esse requisito passa nas duas perguntas do gate: dá para implementar sem dúvida e está conforme o método. Gate que não tem como reprovar não é gate, e foi por isso que a falseabilidade virou checagem própria dentro da Pergunta 1 (Passo 6).

2. Card fechado significa que a pessoa recebe o benefício

Fechar um card não é “o código existe e o teste passou”. É o papel que deveria usar aquilo consegue alcançar e usar. Peça construída, testada, verde e inalcançável é trabalho perdido com aparência de trabalho entregue, e foi o defeito mais frequente medido nos projetos acompanhados.

Por isso o aceite de um card exige, além do critério do requisito, três checagens percorridas de fato e nunca imaginadas:

• Uso: alguém percorre o caminho real, com dados reais, e obtém o resultado.
• Navegação: existe caminho na interface até ali, partindo de onde o papel entra no sistema de verdade.
• Autonomia: o papel chega sozinho, sem instrução externa e sem alguém colando um link direto.

O card nomeia também quem, em produção, alimenta aquilo: o papel, o evento ou a rotina que mantém a peça viva no dia a dia. Peça sem alimentador nasce vazia.

As três checagens compõem a bateria do Plano de Testes, mas não podem esperar por ela: os Testes são a última seção do progresso e, por construção, rodam por último. Rodá-las no fechamento de cada card é o que evita descobrir no fim o que era barato consertar no começo.

3. Cobertura por construção vence cobertura por disciplina

Trava que percorre uma lista curada protege só o que alguém lembrou de listar. A lista envelhece em silêncio e a trava continua passando verde, agora sobre um conjunto que já mudou. Trava que deriva do próprio material o que precisa checar (percorre tudo que existe e decide por regra) protege também o que ainda não foi escrito.

A prova mais dura veio de dentro: a guarda que protege a publicação desta própria metodologia tinha esse defeito.

E toda trava nasce com uma prova de que ela reprova quando deve: um caso propositalmente errado que a trava precisa rejeitar. Sem essa prova, ninguém sabe se a trava trava.

Passo 8: a construção roda em dois papéis

Um projeto que entra em construção contínua ocupa duas posições ao mesmo tempo, e elas não se confundem.

A Execução constrói. Percorre a fila do Roadmap, card a card, sem interromper quem contratou a cada dúvida. Escreve o código, roda os testes, integra e publica. É a única posição que toca no que vai ao ar.

A Inspeção olha, mede e organiza a fila. É por onde o responsável fala enquanto a construção continua. Ela verifica o que já foi entregue contra o critério de aceite do requisito, executa a bateria Beta do Plano de Testes, mede o que está no ar, encontra falhas e realinha a rota. Traduz o que o responsável pede em requisito com critério de aceite, republica o documento e ordena a fila.

A Inspeção não constrói. É a regra que sustenta a separação: quem olha a obra não sobe o muro. Defeito que ela encontra vira card com evidência, e quem corrige é a Execução. Pedido novo vira requisito no documento republicado, e só então card na fila. Se a Inspeção quer algo no ar, ela pede e aguarda a Execução publicar.

O motivo é medido, não teórico. Onde as duas posições tiveram permissão de escrever no mesmo projeto, os erros de sobreposição vieram todos da Inspeção, incluindo uma publicação que removeu do ar duas entregas recém-concluídas sem produzir erro nenhum: a publicação funcionou, o sistema respondeu, e a funcionalidade simplesmente não estava mais lá. Erro silencioso não se corrige com disciplina, se corrige tirando a permissão.

A conversa entre as duas passa pelo documento

Pedido não viaja por recado. O Roadmap publicado é o estado do projeto, e despachar trabalho por conversa cria um segundo estado competindo com o primeiro. O caminho de qualquer pedido novo é sempre o mesmo: elicitar, escrever o requisito com critério de aceite, republicar, e então enfileirar.

Recado serve para o que é coordenação e não é trabalho: avisar que uma mudança veio da Inspeção e não precisa ser investigada, confirmar o entendimento de uma decisão, repassar a palavra do responsável com a frase exata e a quem ela foi dita. Cada posição enxerga só metade da conversa com quem contratou, e traduzir a fala dele é onde o mal-entendido entra.

Quem fecha o quê

A Execução fecha cards de construção, e nunca marca item de teste. A Inspeção fecha os itens da bateria Beta, e nunca marca card de construção. Cada progresso é assinado por quem tem como prová-lo.

Quando vale, e quando não vale

As três condições valem juntas: fila com cinco ou mais cards abertos, construção contínua de fato em andamento, e o responsável com algo a tratar agora. Fora disso, uma posição só, porque a segunda custa sem produzir entrega.

A Inspeção é temporária: existe enquanto há o que tratar e encerra depois. Posição parada observando é desperdício.

O sinal de que deu errado

A separação não falha por estrago, falha por congestionamento: a Inspeção enfileira mais rápido do que a Execução consegue drenar, e a obra desacelera. A pergunta que denuncia é “por que a construção ficou tão lenta?”.

Duas medidas desde o primeiro dia: cards fechados por semana, antes e depois de a Inspeção existir, e quantos itens ela injeta contra quantos vieram do Roadmap. Passando de um injetado para cada três da fila, a Inspeção virou fonte de escopo, e é ela que precisa apertar.

Modos de aplicação

Modo Greenfield (projeto novo)

Aplicar passos 1-5 em sequência antes de escrever código.

Modo Brownfield (projeto existente sem doc MDS)

1. Aplicar passos 1-5 lendo o código + entrevistando time
2. Identificar gaps (campos BASE faltantes = débito de elicitação)
3. Documentar gaps em backlog de “completude MDS”
4. Pagar débito incrementalmente sem parar entrega

Modo Audit (validação periódica)

1. Comparar instância MDS atual vs estado real do projeto
2. Identificar drift (RFs implementados não listados, ADRs não documentados, mudanças de stack não refletidas)
3. Refresh do documento

Modo Validator (verificação automatizada)

Verificação mecânica de completude, rodada por ferramenta:

1. Lê doc MDS de um projeto
2. Para cada BASE: verifica se preenchido (não placeholder)
3. Para cada PLUGIN: verifica se tem resposta de gatilho explícita
4. Para cada gatilho S: verifica se conteúdo está preenchido
5. Reporta gaps mecânicos

Erros comuns

”Pulei o BASE A6 (não-escopo) porque era óbvio”

Defeito. Não-escopo declarado salva 80% das discussões futuras de “achei que ia ter X”. Nunca pule.

”PLUGIN D6 (compliance): coloquei N/A porque não sei se LGPD aplica”

Defeito. Gatilho não respondido. Resposta correta: descobre se LGPD aplica (5 minutos lendo), responde S ou N concretamente.

”STACK G6 (padrões de código): sou solo dev, não precisa”

OK. STACK pode ser omitido sem justificativa. Mas quando entrar 2º dev, este STACK vira urgente.

”Inventei um campo que não está no template porque meu projeto é especial”

Defeito. Extensões do template precisam de proposta formal (vira evolução MDS, não fork local). Toda instância usa o template canônico.

”Coloquei tudo como BLOCO-BASE pra forçar disciplina”

Defeito. Reclassificação local quebra portabilidade. Categoria de bloco é canônica MDS, não escolha de instância.

Velocidade esperada de aplicação

Anti-pattern detectado em produtos Modulareasy: subestimar o tempo de elicitação porque “o produto é claro na minha cabeça”. Um produto multi-módulo real precisou de dezenas de seções construídas ao longo de várias sessões antes de o documento fechar. MDS é deliberado.