yasyf/design-doc

Was macht design-doc?

gemini-4-argon schreibt und überarbeitet jegliche Prosa, einschließlich Zusammenfassungen, Plain Twins, Handles, Revisionsnotizen und Veröffentlichungstexte. Die Sitzung übergibt die Fakten und Regeln (den Schreibvertrag, die Qualitätsregeln, die Längenbeschränkungen) über gemini -m gemini-4-argon --skip-trust -p, übernimmt die Antwort wörtlich und sammelt Beweise und veröffentlicht das Ergebnis selbst. Prosa-Helfer rufen dasselbe Modell über gemini --skip-trust -p auf, ohne Fallback-Modell.

Ein Architekturentwurf ist ein Stapel von Entscheidungen auf einem Stapel von Annahmen. Dieses Skill führt den Entwurf als Gespräch – der Benutzer entscheidet alles – und rendert das Ergebnis als ein Dokument, in dem jede Behauptung auf eine Annahme, eine Entscheidung und die Fragerunde zurückgeführt werden kann, die sie hervorgebracht hat.

Ein Befehl steuert die mechanischen Teile:

TOOL="python3 ${CLAUDE_PLUGIN_ROOT}/skills/design-doc/scripts/design.py"
$TOOL scaffold --title <name>   # frisches ./<slug>/-Verzeichnis für genau dieses eine Design-Dokument
$TOOL scaffold --example        # ./tinyq/, ein kleines ausgefülltes Arbeitsbeispiel
$TOOL check <dir>               # lintet die Register, Plain Twins, Diagrammquellen und das Zusammenfassungsdeck; Fehler beenden mit Exit-Code ungleich Null, --strict macht die veröffentlichungsblockierenden Warnungen zu Fehlern
$TOOL summary-text <dir>        # das Deck als Markdown, ein ##-Abschnitt pro Panel; die Eingabe für die Gates
$TOOL plainify <dir> [--only DQ3,A2] [--dry-run]
$TOOL glossary <dir>            # Begriffe, die die Prosa verwendet und die im Glossar fehlen, als Kandidaten für Einträge
$TOOL build <dir>               # kompiliert components/*.tsx in components.js; nur für ein Dokument mit einem Verzeichnis components/
$TOOL render-check <dir>        # rendert jeden Mermaid-Block im kopflosen Chrome; schlägt bei Parse-Fehler oder Seitenausnahme fehl
$TOOL pdf <dir>                 # druckt das Dokument über das Druck-Stylesheet der Vorlage in <dir>/design-doc.pdf
$TOOL snapshot <dir> --note "..." --item "..." # erstellt eine Revision, mit der die Änderungsansicht verglichen wird; note ist die für den Leser sichtbare Überschrift, jeder --item eine Änderung
$TOOL links <dir> [--fetch] [--missing] # jede Entscheidung und jedes offene Element mit seinen Pull-Request-Links und dem Status; --fetch fragt GitHub, ob jeder Link gemerged wurde, und meldet Abweichungen; --missing listet die Einträge auf, die noch nicht verlinkt sind

Lies reference/method.md vor Phase 1, reference/writing.md vor Phase 5 und reference/publish.md vor Phase 6 – die Methodendatei ist das Runden-/Registerprotokoll, die Schreibdatei ist der Stimmvertrag, die Veröffentlichungsdatei ist der Hosting-Ablauf. reference/schema.md ist der feldspezifische Vertrag für die JSON-Dateien; erstelle das tinyq-Beispielgerüst, wenn du ein ausgefülltes Register neben dem Schema haben möchtest.

Terminologie

• Register – eine strukturierte Liste in registers.json, deren Einträge stabile IDs haben: A# Annahmen, DQ# Entscheidungen, Q# offene Fragen, V# Spikes, c-<slug> Architekturkarten.
• Runde – ein Board, das dem Benutzer vorgelegt und wörtlich in qa-log.json protokolliert wird. Eine Runde stellt jeden offenen Fork auf einmal, jeder als design-doc.fork-Block, und fragt nichts anderes. Antworten, die neue Forks öffnen, starten die nächste Runde, wieder alle auf einmal; qa-log.json zeichnet die Runden in der Reihenfolge auf, so dass ein späteres Board von einer früheren Antwort abhängen kann.
• Supersession – eine geänderte Entscheidung erhält einen neuen Eintrag, der alte bekommt s: "superseded" plus einen by-Zeiger, den das Dokument als "Ersetzt durch" und den Titel des Nachfolgers rendert. Die Historie bleibt lesbar, da niemand in-place editiert.
• Stern (★) – markiert die tragende Annahme, deren Scheitern das Dokument ungültig macht.
• Spike – ein benanntes, zeitlich begrenztes Experiment (V#), das eine mit (E) markierte Schätzung in eine gemessene Zahl verwandelt.
• Executive Summary – summary.html, ein handgeschriebenes HTML-Fragment neben registers.json, für den Leser, der sonst nichts liest: standardmäßig ein Deck aus Vollbild-Panels, ein Poster, wenn der Entwurf aus einer Idee und einer Abbildung besteht. Wird nie als Daten geparst; check lintet seine Form, seine Wortbudgets und seine Zitate.
• Plain Twin – das p-Feld neben der präzisen Formulierung eines Eintrags, ein oder zwei kurze Sätze, die sagen, was der Eintrag für jemanden bedeutet, der ihn nicht lesen wird. Das Dokument zeigt standardmäßig die Zwillinge und die genaue Formulierung einen Umschalter entfernt.
• Key und Theme – key: true markiert die 3–8 Entscheidungen und Annahmen, die das Dokument als Karten öffnet; theme ordnet jeden Eintrag einem der 3–5 Entwurfsthemen zu, die in Phase 0 benannt und in der themes-Karte definiert werden.
• Diagramm – die Mermaid-Quelle des Systemdiagramms, im diagram-Registerschlüssel; das Dokument rendert es, der Leser kann es schwenken und überfahren, und die Anforderungspfade schreiten hindurch. diagram.overview ist das Zehn-Knoten-Subset, das die Übersichtskarte zeichnet, mit dem vollständigen Graphen einen Klick entfernt. Ein handgezeichnetes sysd.svg bleibt gültig als diagram.kind: "svg".
• Handle – das h-Feld auf jeder Entscheidung, Annahme, offenem Element, Architekturkarte und Zahlentabelle: wie ein Leser sie nennen würde, zwei bis fünf Wörter. Zitate und Chip-Zeilen zeigen den Handle; die ID lebt in der Hover-Karte.
• Komponente – eine interaktive Abbildung, die in der components-Karte deklariert ist (dd.tabs, dd.before-after, dd.whatif, dd.steps, dd.timeline, dd.matrix, die beiden Vergleichspanel-Abbildungen dd.flow und dd.lanes, die handgezeichnete Systemkarte dd.system und dd.arch, die ein veröffentlichtes Architekturdokument einbettet) und per ID im Deck oder an einem Eintrag platziert wird; eine TSX-Datei unter components/ ist der Ausweg, den build kompiliert.
• Figure Brief und Kritik – die beiden NOTES.md-Abschnitte, aus denen das Deck gezeichnet und gegen die es gelesen wird. Ein Brief ist fünf Zeilen pro Abbildung, geschrieben bevor die Abbildung gezeichnet wird: die Aussage, die sie trifft, die Entscheidung, der sie dient (per ID), die kleinste Ansicht, die die Aussage vermittelt, was sie auslässt und die echten Labels, die sie verwendet. Die ersten beiden Zeilen werden zur <figcaption>. Die Kritik ist eine Zeile pro Panel, Abbildung, Tabelle und Statistik, geschrieben vor den Gates: die Entscheidung, der sie dient, die Behauptung, die sie aufstellt, die Frage, mit der ein Leser zurückbleibt, und behoben oder gestrichen. check warnt, wenn einer der beiden Überschriften fehlt.
• Link – ein Eintrag von links[] auf einer Entscheidung, einem offenen Element oder einer Erkenntniszeile: der Pull-Request, das Issue, der Commit oder das Dokument, das sie abschließt. closes: true auf dem Link eines offenen Elements markiert denjenigen, der es zurückzieht. Das Dokument zeigt jeden Link als Chip mit seinem GitHub-Status und leitet jede offene Gruppe damit ein, wie viele ihrer Elemente geschlossen sind.
• Statuswerte: Entscheidungen sind resolved | superseded | open, was das Dokument als "Entschieden", "Ersetzt" und "Noch offen" rendert; Annahmen sind working | validate, gerendert als "Angenommen" und