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 + 12 anti-patterns)
• Conhecimento da Nomenclatura dos Blocos (BASE/PLUGIN/STACK)
• Leitura do Template Completo (86 campos em 15 blocos: 0 + A–N)

Roteiro de aplicação em 7 passos

Passo 1 — Decidir 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” — instâncias externas podem tratar 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 35 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” — se S, preencher B2.
• “Há cálculo/lógica não-trivial OU regra mutável por admin? S/N” — se S, preencher C2.
• … (continuar pelos 30)

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

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

Passo 4 — Avaliar os 18 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 35 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 — não só a saída/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 + um campo-proxy. Capturar só o resultado e simplificar a estrutura é erro de elicitação, não “requisito novo a descobrir depois”. (Origem: Outsource — a planilha de precificação foi enviada no dia 1, mas o DRS modelou 1 cargo/serviço em vez de N, e usou composed_of como proxy; só apareceu meses depois, no QA.)

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 — Handoff de implementação (Prompt Gerador)

Depois que o documento passa no gate (Passo 6) e é aprovado, quem vai construir não começa direto do DRS: roda antes o Prompt Gerador de Handoff. É um prompt padrão do MDS que, colado numa LLM com capacidade de agente seguido do documento completo, produz um handoff de implementação (sistema em 5 linhas, mapa do documento, pré-requisitos, ordem de construção, definição de pronto, regras invioláveis e primeiro passo concreto). Em uma sessão nova, um agente recebe esse handoff e implementa usando o documento como fonte única.

O prompt é genérico (serve a qualquer DRS escrito em MDS), nunca específico de um produto. Cole o bloco abaixo em uma LLM com capacidade de agente, seguido do DRS completo:

Você recebeu abaixo um Documento de Requisitos de Software (DRS) escrito no padrão MDS (Modular Development Style). Sua tarefa NÃO é implementar agora. Sua tarefa é produzir um HANDOFF DE IMPLEMENTAÇÃO: um documento curto e operacional que permita a um agente, em uma sessão nova, implementar o sistema do zero usando este DRS como fonte única da verdade.

Leia o DRS inteiro. Depois gere o handoff com EXATAMENTE estas seções:

1. O SISTEMA EM 5 LINHAS
   O que é, para quem serve, o que faz e o que NÃO faz. Extraia da Visão Geral e do bloco de Identidade.

2. MAPA DO DOCUMENTO
   Uma tabela que diz onde o agente encontra cada coisa no DRS (adapte os números e nomes das seções ao DRS recebido):
   | Quando eu precisar de... | Vou ler a seção... |
   | Requisitos e seus critérios de aceitação | Requisitos Funcionais |
   | Como os dados são modelados (tabelas, relações) | Modelo de Dados |
   | Contratos entre as partes (eventos, APIs) | Interfaces |
   | Tecnologias e arquitetura | Arquitetura e Stack |
   | Em que ordem construir | Entrega e Evolução |
   | Como saber que algo está pronto e correto | Validação |
   | Como operar em produção | Operação |
   | O que é configurável por cliente | Configurabilidade |
   | Recursos de inteligência artificial | Automação e IA |

3. PRÉ-REQUISITOS
   O que precisa existir antes de escrever a primeira linha de código: stack, ambiente, contas e segredos, schemas/dados base. Extraia de Arquitetura e Operação.

4. ORDEM DE CONSTRUÇÃO
   A sequência de ondas/fases copiada da seção de Entrega, com a dependência entre elas. Para cada onda: o que entra e do que depende. Nunca construir um item antes daquilo de que ele depende.

5. DEFINIÇÃO DE PRONTO
   Como o agente sabe que terminou cada requisito: cada requisito traz seus critérios de aceitação; a entrega só fecha com a bateria de testes e a inspeção visual descritas na seção de Validação. Resuma o critério de pronto.

6. REGRAS INVIOLÁVEIS
   Extraia as regras de negócio transversais e os princípios de arquitetura que o agente NUNCA pode violar (isolamento entre clientes, nada com valor fixo em código quando deveria ser configurável, etc).

7. PRIMEIRO PASSO CONCRETO
   Qual a primeira onda, qual o primeiro módulo, quais os 3 a 5 primeiros requisitos a implementar, e como validá-los. O agente deve conseguir começar a trabalhar só com isto.

REGRAS DO HANDOFF:
- Seja operacional, não narrativo. Aponte sempre para a seção do DRS, não copie o conteúdo inteiro.
- Não invente requisitos que não estão no DRS.
- Se faltar algo essencial para implementar, liste no fim em "LACUNAS A RESOLVER ANTES DE COMEÇAR".
- Texto em português. Nunca use travessão.

A seguir, o DRS:
[COLE O DRS COMPLETO AQUI]

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

O handoff acima é efêmero (vive numa sessã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 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.
• 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% (a Fase 0), Construção 40%, 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.

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 (agent automatizado)

Sub-fase do process-enforcer Modulareasy:

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 tempo de elicitação porque “o produto é claro na minha cabeça”. CANON ModularHub teve 33 seções construídas em 7 sessões. MDS é deliberado.