esc:architecture — Solution Design & ADRs

Ziel: das WIE festlegen — Tech-Stack, Struktur, Datenmodell, Schnittstellen — und jede wichtige Entscheidung mit Begründung und verworfenen Alternativen dokumentieren. Das ist der bewusste Gegenentwurf zum bekannten Problem „Empfehlung ohne Trade-off".

Sichtweise & Schärfe

Diese Phase wird aus der Architektur-Sicht geführt — Trade-offs & Einfachheit: „Welche Annahme trägt das? Was bereuen wir in 2 Jahren?" (${CLAUDE_PLUGIN_ROOT}/shared/viewpoints.md). An jeder ADR/jedem Gate greift die skeptische Sicht an; Tiefe nach level (${CLAUDE_PLUGIN_ROOT}/shared/intensity.md). Erarbeite Abschnitt für Abschnitt (${CLAUDE_PLUGIN_ROOT}/shared/coauthoring.md).

Lies zuerst

• ${CLAUDE_PLUGIN_ROOT}/shared/elicitation.md, ${CLAUDE_PLUGIN_ROOT}/shared/principles.md
• esc/state.yaml, esc/specs/prd.md (oder quick-spec), esc/specs/ux-spec.md, esc/specs/constitution.md
• esc/specs/sources.md (bindende externe Quellen, falls vorhanden) — Geräte-/Schnittstellen-/Vorschriften-Vorgaben einhalten und zitieren
• Bei Brownfield: bestehende Codebase scannen (Glob/Grep) — Stack, Muster, Konventionen erfassen.

Routing nach Level

• Level 0/1: in der Regel keine Architektur — verweise auf esc:epics. Nur wenn eine echte Entscheidung ansteht, eine einzelne ADR erstellen.
• Level 2: „leicht" — nur ADRs für die 1–3 nicht-trivialen Entscheidungen, kein volles Dokument.
• Level 3/4: volles Architektur-Dokument + ADRs.

Ablauf

1. Architektur-Treiber sammeln

Leite aus PRD (besonders nicht-funktionalen Anforderungen) und Constitution die Treiber ab: Last/Skalierung, Konsistenz, Sicherheit/Compliance, Team-Erfahrung, Time-to-Market, Reversibilität. Bestätige sie mit dem Nutzer.

2. Entscheidungspunkte identifizieren

Liste die nicht-trivialen Entscheidungen (z. B. Persistenz, Sprache/Framework, Auth, Async/Queue, Hosting, Integrationsgrenzen). Triviales (offensichtlich aus Constitution/Brownfield) als gesetzt markieren, nicht künstlich diskutieren.

3. Je Entscheidung: Optionen mit Pro/Contra — GATE

Für jede nicht-triviale Entscheidung:

1. 2–3 realistische Optionen nennen.
2. Tabelle Option · Pro · Contra · Risiko (bei Bedarf via WebSearch aktuelle Fakten holen).
3. Empfehlung mit Begründung gegen die Treiber.
4. Pflicht-Vertiefung (Red-Team oder Pre-Mortem) auf die Empfehlung anwenden.
5. Nutzer entscheiden lassen, dann ADR schreiben: esc/specs/architecture/decisions/ADR-NNNN-<slug>.md mit Status/Kontext/Entscheidung/Begründung/verworfene Alternativen/Konsequenzen. Auch ins decisions-Log in state.yaml spiegeln. Nach allen ADRs gates.architecture_adrs: true.

4. Architektur-Dokument (Level 3/4)

esc/specs/architecture/architecture.md: Überblick & Treiber · Systemkontext/Komponenten · Datenmodell (Kern-Entitäten & Beziehungen) · Schlüssel-Schnittstellen/APIs · Querschnitt (Auth, Fehler, Logging, Tests) · Verweise auf die ADRs · bekannte Risiken. Kein Pseudo-Code — „Right Altitude".

5. Constitution abgleichen

Prüfe, ob neue verbindliche Regeln entstanden sind (z. B. „Datenzugriff nur über Repository-Layer"). Wenn ja, in esc/specs/constitution.md ergänzen.

6. Routen

state.yaml aktualisieren (artifacts.architecture: done, phase weiter) → esc:epics.

Definition of Done

• Spec-Self-Review (Abschluss-Gate, coauthoring.md): Vollständigkeit · Konsistenz · Klarheit · Scope · YAGNI geprüft, Probleme inline gefixt.
• Mitlaufende Artefakte aktualisiert: esc:track (TRACKER.md) und esc:docs (Komponenten + Datenmodell).
• Jede nicht-triviale Entscheidung hat eine ADR mit ≥2 Optionen, Pro/Contra und Begründung.
• Pflicht-Vertiefung je Empfehlung erfolgt; gates.architecture_adrs: true.
• Datenmodell und Schlüssel-Schnittstellen sind definiert (Level 3/4).
• Neue verbindliche Regeln in der Constitution ergänzt.
• Kein Implementierungs-Pseudo-Code; WAS-Grenzen aus PRD respektiert.