Block-Referenzen
Eine Definition, eine Adresse — und 14 Stellen sind synchron statt 13 vergessen.
- ··Block-IDs sind UUIDv4: eine kanonische Stelle, beliebig viele ((id))-Zitate.
- ··Pflegeaufwand bei Definitions-Änderung sinkt um 95 % — Du editierst eine Stelle.
- ··ADR ist der natürliche Stamm-Use-Case: Entscheidung einmal, referenziert überall.
Transkript
Was, wenn dieselbe Definition nicht in vierzehn Kopien zerfällt, sondern an einer einzigen Adresse lebt — und vierzehn Stellen synchron bleiben, statt dreizehn zu vergessen? Genau das leisten Block-Referenzen, und in den nächsten Minuten hörst Du, wie sie funktionieren und warum sie den Pflegeaufwand fast auf null drücken.
Eine Block-ID ist eine UUIDv4 — eine kanonische Stelle, an der eine Aussage wirklich lebt. Mit doppelten Klammern und der ID dazwischen zitierst Du diesen Block überall, ((id)). Der Block bleibt an seiner Heimat, das Zitat zeigt immer den aktuellen Stand. Änderst Du die Quelle, ziehen vierzehn Zitate sofort nach.
Der Schmerz ohne Referenzen ist still und teuer. Eine Definition wandert per Strg+C in vierzehn Seiten. Sechs Monate später ändert sich etwas, Du pflegst eine Stelle und vergisst dreizehn. Die Konsistenz zwischen Definition und Verwendung fällt unter die Hälfte, ohne dass es jemand merkt — bis zwei Seiten sich widersprechen und beide plausibel klingen.
Wichtig ist der Unterschied zwischen Referenz und Embed. Die Referenz ((id)) verlinkt — der Leser springt mit Strg+Klick zum Block an seiner Heimat. Das Embed spiegelt den Block inline, er nimmt am Lesefluss teil. Faustregel: ((id)), wenn der Leser zum Kontext springen soll, Embed, wenn der Block mitlesen soll.
Der natürliche Stamm-Use-Case ist das Architecture Decision Record. Eine Entscheidung formulierst Du genau einmal, mit ihrer eigenen ID. Roadmap, Onboarding und Postmortem zitieren sie per ((id)). Ändert sich die Entscheidung, ist die Korrektur an einer Stelle in allen Zitaten sichtbar — keine Gabelung, keine veraltete Kopie.
So sieht der Unterschied in Zahlen aus. Vorher: vierzehn Seiten mit kopierter Definition, dreizehn davon stillschweigend veraltet, der Pflegeaufwand wächst mit jeder Verwendung. Nachher: ein Block, vierzehn Referenzen, eine Edit-Stelle, alles synchron. Der Pflegeaufwand bleibt konstant, egal wie oft Du zitierst.
Die ehrliche Frage zum Schluss: An wie vielen Stellen ist „Kunde“, „Lead“ oder „Done“ in Deinem Wiki definiert? Liegt die Zahl über eins, ist mindestens eine davon veraltet. Eine Aussage, eine Adresse — alles andere ist Spiegel. Dein Zweitgehirn hält die Fäden zusammen und gibt zurück, was Du ihm anvertraust.
Block-IDs sind UUIDv4. Eine Definition, eine Adresse. ((id)) zitiert sie überall. Pflegeaufwand bei Definitions-Änderung sinkt um 95 %, weil Du genau einen Block bearbeitest und 14 Stellen synchron sind.
Copy-Paste über Seiten erzeugt Drift
Eine Definition wandert per Strg+C in 14 Seiten. Sechs Monate später ändert sich die Definition. Du pflegst eine Stelle, vergisst 13. Konsistenz Definition ↔ Verwendung fällt unter 50 %, ohne dass Du es merkst.
- Drift-Symptom 1: Zwei Seiten widersprechen sich, beide wirken plausibel.
- Drift-Symptom 2: Die Suche nach „ICP“ liefert 14 Treffer mit 4 verschiedenen Definitionen.
- Drift-Symptom 3: Niemand weiß, welche Version stimmt — also wird eine neue geschrieben. Jetzt sind es 15.
5 Regeln für Block-Referenzen
- UUIDv4 je Block. Jeder Block bekommt beim Anlegen eine ID, z. B. 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12. Stabil, kollisionsfrei, nicht raten.
- Block-Referenz ≠ Block-Embed. ((id)) verlinkt — der Block bleibt sichtbar an seiner Heimat. {{embed ((id))}} spiegelt — der Block erscheint inline an der Zitatstelle.
- ((id)) Syntax. Doppelte Klammern, UUID dazwischen, kein Leerzeichen. Auto-Vervollständigung nach Eingabe von ((.
- Single Source vs Spiegel. Definition lebt an genau einer Stelle (Source). Alle anderen Stellen sind Spiegel via ((id)). Edit am Spiegel = Edit an der Source.
- ADR als Stamm-Use-Case. Architecture Decision Records sind die natürliche Source: Entscheidung einmal formulieren, in Roadmap, Onboarding, Postmortem per ((id)) referenzieren.
## ADR-007: Block-IDs sind UUIDv4
id:: 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12
Wir verwenden UUIDv4 für Block-IDs, weil:
- kollisionsfrei ohne zentrale Vergabe
- 122 Bit Entropie reichen für 10^36 Blöcke
- offline generierbar (crypto.randomUUID())
---
## Roadmap Q3
Siehe Entscheidung: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))
## Onboarding für neue Devs
ID-Schema: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))Vorher/Nachher — 14 Wikipedia-Klone vs. ein Block, 14-fach embedded
| Vorher | Nachher |
|---|---|
| 14 Seiten mit kopierter ICP-Definition | 1 Block, 14 Referenzen via ((id)) |
| Edit an 14 Stellen, 13 vergessen | Edit an 1 Stelle, 14 Stellen synchron |
| Suche „ICP“ → 14 Treffer, 4 Versionen | Suche „ICP“ → 1 Source, 14 Backlinks |
| Drift unbemerkt, Widersprüche im Wiki | Drift strukturell ausgeschlossen |
| Pflegeaufwand wächst linear mit Verwendungen | Pflegeaufwand konstant, unabhängig von Verwendungen |
<!-- Source-Block (lebt in /glossar/icp.md) -->
id:: a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50
ICP (Ideal Customer Profile): Beschreibung des Konto-Typs, der mium am stärksten profitiert — Branche, Größe, Wissensvolumen, Compliance-Frame.
<!-- Verwendung in /sales/playbook.md -->
Unser ICP: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Verwendung in /onboarding/woche-1.md -->
Lies zuerst: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Verwendung in /roadmap/2026.md -->
Fokus 2026: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))Ehrliche Frage
Wie oft hast Du dieselbe Definition an verschiedenen Stellen pflegen müssen? Zähl die Stellen, an denen „Kunde“, „Lead“ oder „Done“ in Deinem Wiki definiert ist. Wenn die Zahl über 1 liegt, ist mindestens eine davon veraltet.
Eine Aussage, eine Adresse. Alles andere ist Spiegel.