---
name: code-strukturieren
description: Entwirft und verbessert die Struktur von Code entlang fachlicher Vertical Slices, tiefer Module, kleiner Schnittstellen und sinnvoller Testnähte. Verwenden, wenn neue Module oder Schnittstellen entstehen, eine Codebasis unnötige Schichten oder Wrapper bildet, Verantwortungen unklar sind oder ein Refactoring vorbereitet wird.
---

# Code strukturieren

Strukturiere Code entlang der fachlichen Änderung. Verberge notwendige
Komplexität hinter kleinen stabilen Schnittstellen und vermeide Architektur nur
um ihrer selbst willen.

## Fachliche Grundlage

- [John Ousterhout – A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/aposd.php)
  beschreibt tiefe Module und das Reduzieren sichtbarer Komplexität.
- [Jimmy Bogard – Vertical Slice Architecture](https://www.jimmybogard.com/vertical-slice-architecture/)
  beschreibt die Kopplung entlang fachlicher Anwendungsfälle statt technischer
  Schichten.
- [Eric Evans – DDD Reference](https://www.domainlanguage.com/ddd/reference/)
  verbindet Fachsprache, Modell und Implementierung.

## Vorgehen

1. Beginne mit dem fachlichen Verhalten, der bestätigten Sprache und der
   erwarteten Änderungsachse.
2. Halte zusammen, was für denselben Slice gemeinsam geändert wird. Erzeuge
   keine globale Controller-Service-Repository-Kette als Standardform.
3. Definiere die kleinste Schnittstelle, die Aufrufer für korrektes Verhalten,
   Fehlerfälle und wichtige Qualitätsmerkmale kennen müssen.
4. Verberge technische und fachliche Komplexität hinter dieser Schnittstelle.
   Ein Modul ist tief, wenn es viel nützliches Verhalten mit wenig sichtbarer
   Bedienfläche anbietet.
5. Lege Nähte an reale Veränderungsgrenzen: Fremdsysteme, Persistenz,
   Zeitquellen, Plattformen oder tatsächlich austauschbare Varianten.
6. Führe keine Abstraktion nur für einen hypothetischen zweiten Adapter ein.
   Eine Abstraktion muss aktuelle Komplexität reduzieren, einen benötigten Test
   ermöglichen oder bereits unterschiedliche Implementierungen verbinden.
7. Halte Fachregeln im Domain-Modell des zuständigen Bounded Contexts und
   technische Koordination im Slice. Dupliziere Regeln nicht zwischen Slices.
8. Prüfe mit `sicherheit-und-datenschutz-pruefen`, ob Schnittstellen
   Berechtigungen, Datenminimierung und Vertrauensgrenzen klar ausdrücken.
9. Teste Verhalten über die öffentliche Schnittstelle. Wenn Tests tief in die
   Implementierung greifen müssen, prüfe die Modulgrenze erneut.
10. Vergleiche bei einer folgenreichen Schnittstelle mindestens zwei einfache
    Entwürfe, bevor du dich festlegst. Dokumentiere nur dauerhafte Entscheidungen
    als ADR.

## Warnzeichen

- Durchreicher ohne eigene Verantwortung
- Schnittstellen mit fast derselben Komplexität wie ihre Implementierung
- gemeinsame Ordner wie `services` oder `utils` ohne fachliche Zugehörigkeit
- Abstraktionen für noch nicht vorhandene Anforderungen
- eine kleine Änderung verteilt sich regelmässig über viele technische Schichten
- Sicherheitsprüfungen sind nachträglich aufgesetzt statt Teil der Schnittstelle

## Fertig, wenn

- Struktur und Namen dem fachlichen Slice folgen.
- öffentliche Schnittstellen klein, vollständig und testbar sind.
- Abstraktionen eine heutige Begründung haben.
- Sicherheits-, Daten- und Fehlergrenzen sichtbar sind.
- die Lösung einfacher zu ändern ist als die naheliegende Schichtenvariante.