Diagramme

Diagramme sind tragend, nicht dekorativ. Greife nur zu ihnen, wenn Prosa den Leser zwingt, eine ganze Form gleichzeitig im Kopf zu behalten — wähle dann die kleinste Ansicht, die die Form zeigt, anstatt sie aus Sätzen zu rekonstruieren. Alles hier rendert im Gespräch als Textblöcke oder Mermaid; es wird höchstens eine Artefakt-Datei geschrieben.

Das Vokabular

Wähle eine Ansicht; maximal zwei. Mehr ist Rauschen.

Pseudocode — Logik ohne Sprachrauschen. Reduziert eine Entscheidung auf ihre Verzweigungsform:

on(request)
  if state file locked by another writer
    queue and return pending
  acquire lock
  write
  release

Call Tree — Laufzeit-Kontrollfluss. Tiefe zeigt, wer den Fluss besitzt; annotiere, wo die interessante Kante liegt:

acquireStateFileLockSync()
  resolveLockPath()
  openExclusive()
  writePid()

Komponentenbaum — UI- oder Modulstruktur, mit den relevanten Grenzen inline annotiert:

<SettingsPage> (src/routes/settings)
  <SessionList> (besitzt seine fetches)
  <DangerZone>
    <ConfirmButton> (deaktiviert bis bestätigte Eingabe)

Dateibaum — wo Verantwortung lebt; flach halten, eine Annotation pro Verzeichnis:

src/
├── hooks/        # Hook-Registry + Typen
├── tools/        # MCP-Tool-Handler
└── workflow/     # Registry + Projektionen

Mermaid — Interaktion zwischen Parteien, Datenfluss oder Zustandsübergänge:

sequenceDiagram
    participant CLI
    participant Hook
    participant State
    CLI->>Hook: PreToolUse
    Hook->>State: read mode
    Hook-->>CLI: allow / deny + facts

Diff — die Form einer Änderung, wenn die umgebende Struktur bereits existiert. Passe den Diff an das Thema an:

eine Komponentenänderung:

 <SettingsPage>
   <SessionList />
   <DangerZone>
+    <ConfirmButton />
   </DangerZone>

eine Datei-Layout-Änderung:

 src/tools/
-└── state-tools.ts
+└── state-tools/
+   ├── handlers.ts
+   └── schema.ts

eine Kontrollfluss-Änderung:

 commit()
   stage()
     hashBlobs()
+  writeObject()
   updateRef()
+    acquireStateFileLock()

eine Zustandsmaschinen-Änderung:

 on(request)
-  write immediately
+  if locked
+    queue and return pending
+  acquire lock
+  write
+  release

Der ganze Block — wenn Auslassung verbergen würde, wer was besitzt oder in welcher Reihenfolge Dinge laufen, zeige die vollständige Einheit einmal, kopierbar:

export function isRegistryEnabled(): boolean {
  const flag = process.env.OMC_WORKFLOW_REGISTRY;
  return flag !== '0' && flag !== 'false';
}

Wenn der Text ausgeht

Ein UI-Layout, ein Vorher/Nachher-Vergleich oder ein Konzept, das für Mermaid zu dicht ist: schreibe eine fokussierte HTML-Datei — ein Diagramm, eine Infografik oder ein paar Folien — gestaltet in den eigenen Farben, Schriftarten und Komponenten des Produkts, gefüllt mit echten Bezeichnungen und Daten, funktionierend auf Desktop und Mobil. Öffne sie mit dem plattformspezifischen Öffner (start unter Windows, open unter macOS, xdg-open unter Linux) und höre dort auf: ein Artefakt, keine Galerie.

Disziplin

• Platziere jedes Diagramm direkt neben den zwei oder drei Sätzen, die es unterstützt.
• Führe nur die Aufrufe, Dateien, Props, Zustände und Grenzen, die die aktuelle Frage beantworten — jeder zusätzliche Knoten ist eine Dekodierungssteuer für den Leser.
• Wenn die ehrliche Antwort in einen Satz passt, schreibe den Satz.