ADR-005 — examples/ ships as opt-in reference, not via dotnet new default

Date: 2026-05-29 Status: Accepted Pareado com: TODO TEMPLATE-CANON-CLIENTES

Context

A Sessão C de 2026-05-07 entregou a feature Customers em workspace isolado, implementando padrões complementares ao canon Orders:

• Campo único (Email, CPF) com handler pre-check + unique index.
• Value objects no Domain (Email, Cpf) com normalização no construtor.
• Deactivation como state transition.

Cobre ~20% dos casos de feature; os outros 80% (state transitions, listing, role-gated CRUD) já estão cobertos por Orders.

Onde colocar a feature?

1. Canon obrigatório (src/Application/Customers/...) — todo dotnet new inclui.
2. Examples opt-in (examples/Customers/...) — repo-only, copy-paste reference.
3. Variante separada (itlab-fullstack-with-customers) — template novo no dotnet new.

Decision

Opção 2: opt-in em examples/Customers/.

• Estrutura mirror de src//tests/ dentro do exemplo (examples/Customers/src/Domain/Customers/, etc.) para que copy-paste seja mecânico.
• README.md do exemplo documenta o que demonstra + recipe de 8 passos para incorporar.
• examples/** é excluído do .template.config/template.json via sources.modifiers.exclude — não viaja no scaffold dotnet new.
• Examples não são compilados pelo dotnet build da solution principal (não há .csproj em examples/). Ficam como source-only reference.

Consequences

Positivas:

• Canon fica enxuto — Orders é a unidade educativa básica que todo consumidor vê.
• Padrões complementares ficam descobertos e copiáveis sem inflar o scaffold default.
• Adicionar examples futuros (Multi-tenancy, Outbox, etc.) segue o mesmo modelo — sem proliferar variantes.

Negativas:

• Files em examples/ não são compilados automaticamente — drift entre o exemplo e o canon (ex: namespace de Result mudou no DevPack) só aparece quando alguém copia. Mitigação: examples ship com versão do DevPack pinned no momento do shipping; quando atualizar o canon, refletir em examples manualmente.
• Tests do exemplo não rodam no CI principal. Compromisso: README documenta que ao copiar, integration tests passam contra o factory existente.

Alternatives considered

Opção	Por que descartada
Customers no canon obrigatório	Inflaria o scaffold com 25 arquivos que apenas 20% dos consumidores usam.
Variante dotnet new itlab-fullstack-with-customers	Multiplica matriz de variantes — manutenção dobra com cada example novo.
Examples em outro repo	Cria fricção de descoberta; o consumidor que olha o repo do template não acha o pattern.
Examples como projeto que compila junto	Obriga ter Domain/Application próprios — duplicação ou referência circular.

How to add new examples

1. Criar examples/{FeatureName}/ espelhando estrutura src//tests/.
2. README explicando o padrão + recipe de copy.
3. Atualizar CLAUDE.md § Examples com link para o novo example.
4. Confirmar que template.json sources.modifiers.exclude cobre examples/** (já cobre).

References

• examples/Customers/README.md.
• CLAUDE.md § Examples.
• .template.config/template.json § sources.modifiers.
• TODO TEMPLATE-CANON-CLIENTES em docs/todos/2026-05-07-todos-decisoes-pre-fase-3-template.md.