SAMA 2.0 — Voorstel voor de volgende evolutie

Hier is een uitgewerkte, concrete versie van SAMA 2.0. Ik houd de kern intact (want die is sterk), maar maak het completer, toekomstbestendiger en nog beter geschikt voor agentic coding in 2026+. Kern blijft hetzelfde (de vier letters)

S — Sorted: Alphabetical + dependency direction (lager nummer importeert nooit hoger).

A — Architecture: Numerieke lagen met duidelijke contracten.

M — Modeled: Types + sibling tests.

A — Atomic: Bestanden klein houden (~700 regels) + split per domein.

Wat verandert / wordt toegevoegd in 2.0

Ik voeg twee nieuwe letters toe → SAMA wordt SAMAX (of je houdt SAMA en maakt de extra’s optioneel). Nieuwe letter: X — eXtensible & Vertical

Doel: Combineer de kracht van horizontale lagen (duidelijke dependency flow) met verticale slices (alles van één feature dicht bij elkaar).

Regel: Optionele feature-prefix bovenop de laag: c32_user_auth.ts of feat_payment_c32_processor.ts.

Voordeel voor agents: Een agent die aan “user authentication” werkt, ziet alle relevante bestanden gegroepeerd via zoekopdracht feat_user_*.

Nieuwe letter: D — Documented (de vijfde discipline)

Regel: Elke module én elke feature-map heeft een README.md of .agent.md met:

    One-sentence responsibility

    Key types & contracts

    Acceptance criteria / invariants

    “Where to put new code” instructies

Dit wordt de levende specificatie voor de agent.

Uitgebreide Layer Mapping (Architecture 2.0) Laag Naam Verantwoordelijkheid Voorbeelden Mag importeren van c11 Entry / Composition Root App bootstrap, wiring main.ts, server.ts Alles c13 Data / Persistence DB, repositories, queries c13_user_repo.ts c31 c14 I/O Adapters HTTP, queues, external APIs c14_auth_controller.ts c21, c31, c32 c21 Handlers / Presenters Request/response orchestration c21_login_handler.ts c32, c31 c31 Models & Types Domain models, DTOs, Value Objects, Zod schemas c31_user.ts - (puur) c32 Business Logic / Use Cases Pure functions, domain rules c32_user_auth.ts c31 c40 Application Services Orchestratie van meerdere use cases (nieuw!) c40_user_service.ts c32, c31 c51 UI / Presentation Components, pages, server components c51_user_profile.tsx c31, c32 c60 Infrastructure / External Third-party clients, config, logging c60_stripe_client.ts - c70 Cross-cutting Auth middleware, logging, monitoring, tracing c70_logger.ts alles (voorzichtig)

Atomic-regel verfijnd: Max ~600-700 regels of max 1 feature per bestand (zelfs als het kleiner is). Tooling & Automatisering (kritisch voor gold standard)

SAMA 2.0 moet dit hebben:

Officiële sama CLI

    sama check → voert alle verificaties uit

    sama new c32_user_auth → maakt bestand + template + .agent.md

    sama split → helpt bij Atomic splits

    sama verify-repo

Pre-commit hooks + GitHub Action

LSP / Editor integration (VS Code, Cursor, Windsurf)

Claude / Cursor skill met automatische checks

Extra verbeteringen

Monorepo support: Package-prefixen (pkg_auth_c32_...)

Graduele adoptie: SAMA Light (alleen Sorted + Atomic) → Full SAMAX

Frontend + Backend harmonisatie (vooral Next.js App Router)

Deprecation policy: Duidelijke manier om oude lagen/bestanden af te bouwen

Performance & Security gates in Atomic-check (bijv. flag grote N+1 queries)

Voorbeeld folder structuur (SAMA 2.0)

src/ ├── c11_app.ts ├── features/ │ └── user/ │ ├── feat_user_c13_repo.ts │ ├── feat_user_c31_types.ts │ ├── feat_user_c32_auth.ts │ ├── feat_user_c32_profile.ts │ ├── feat_user_c40_service.ts │ └── feat_user.agent.md ├── c60_stripe.ts └── c70_auth_middleware.ts

Samenvatting: Waarom dit de gold standard wordt

Behoudt mechanische verifieerbaarheid (grep + CLI)

Wordt hybride (horizontaal + verticaal)

Voegt documentatie als first-class citizen toe

Wordt echt toolbaar en adopteerbaar

Schaalt van solo-agent project tot middelgroot team

Dit is geen over-engineering — het lost precies de pijnpunten op die ontstaan als projecten groter worden dan 20-30k regels met agents.

Wil je dat ik een volledige officiële spec uitwerk (zoals de originele tdd.md pagina), inclusief verificatie commando’s en templates? Of focus op één deel (bijv. de CLI spec of een concrete Next.js template)?