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 (75 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.

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 → preencha a declaração de Conformidade MDS da instância (tabela: bloco · tipo · coberto/N/A+motivo · onde no doc) 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]

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.