dannys42/design-session

Was macht design-session?

Denken Sie ein Design gemeinsam mit dem Eigentümer durch, bevor etwas festgehalten wird. Der Eigentümer führt; der Agent erweitert die Optionen, zeigt, was jede impliziert, und sorgt für eine ehrliche Diskussion. Nichts gelangt in das Systemdesign, bis der Promote-Schritt am Ende erfolgt, bei dem der Eigentümer auswählt, was übernommen wird.

Verwenden Sie es zu jedem Zeitpunkt: bevor das Systemdesign existiert, während der Meilensteinplanung oder mitten in einem Meilenstein. Begriffe (Systemdesign, additive Überprüfung, reviewable Oberflächen, settled/working, owner/proposed, Meilenstein, Spike, provisorischer Code, Eigentümerpräferenz, Zwei-Überstimmungen-Regel) sind im Skill system-design in der Datei terms.md definiert; verwenden Sie sie wie dort definiert.

Dateien

<DocDir>/SystemDesign/
  Overview.md                       das Systemdesign (system-design); wird nur durch den Promote-Schritt geändert
  Sessions/<Datum>-<Kurzes_Thema>.md  Notizen dieses Skills, nach dem Promote-Schritt gelöscht

<Datum> ist JJJJ-MM-TT; <Kurzes_Thema> sind 2–3 Wörter in Großbuchstaben_Snake_Case, z. B. 2026-11-01-Bewertung_Import.md. Die Notizen sind frei formatiert: keine IDs, keine Status, keine Zustimmungsmarkierungen und keine Frageobergrenze. Sie enthalten die Skizze des Eigentümers, die betrachteten Formen mit ihren Diagrammen, verfolgte Konsequenzen, gefundene Widersprüche und wie sie gelöst wurden, Spikergebnisse und wo der Eigentümer tendiert. Aktualisieren Sie sie, sobald sich das Gespräch bewegt, damit eine vorzeitig beendete Sitzung von der Datei aus fortgesetzt werden kann.

Arbeitsablauf

1. Lesen, dann den Eigentümer führen lassen

Lesen Sie das Systemdesign und alle Unterlagen zu Subsystemen, die das Thema berührt, den aktuellen Meilenstein der Roadmap, <DocDir>/Taxonomy.md, die Projektregeldatei (CLAUDE.md oder Äquivalent) und die Eigentümerpräferenzen-Datei ${DANNY_SKILLS_STATE_DIR:-$HOME/.local/state/danny-agent-skills}/owner-preferences.md, falls vorhanden. Wenn eine Notizendatei zu diesem Thema bereits in Sessions/ existiert, setzen Sie von dort fort. Andernfalls erstellen Sie sie und geben den Pfad an.

Fragen Sie den Eigentümer, was er sich vorstellt, und spiegeln Sie seine Skizze in einigen Zeilen und, wenn sie zwei oder mehr Teile hat, einem Diagramm wider. Fragen Sie nur, was die Form ändern würde; fragen Sie nie, was Sie als Standard angeben könnten.

2. Alternative Formen anbieten

Bieten Sie 2–3 Formen an, wobei die Skizze des Eigentümers als eine zählt. Für jede: ein Mermaid-Diagramm gemäß den diagrams.md des Skills plan-milestone (Knotenbeschriftungen sind genau die Komponentennamen des Systemdesigns, neue Teile sketched, was die Form ändert, markiert touched), ein klares Beispiel, wie sie sich bei einem Fall aus dem Projekt verhält, und ein einzeiliges Pro und Contra. Empfehlen Sie dann eine oder sagen Sie „keine Empfehlung“ und warum. Benennen Sie neue Dinge nach dem, was sie tun (terms.md, „Namen und Beschriftungen“). Prüfen Sie jedes Diagramm auf korrekte Darstellung, wie diagrams.md es angibt.

3. Konsequenzen verfolgen

Für die Form, zu der der Eigentümer tendiert, sagen Sie, was sie ändert: Subsysteme, Schnittstellen, das Datenmodell, reviewable Oberflächen (feldweise nur dort), Namen und den Abschnitt zu Bedrohungen und Datenschutz. Führen Sie den additiven Check gegen jeden späteren Meilenstein durch: Wenn ein späterer Meilenstein nicht ohne Umstrukturierung hinzugefügt werden könnte, sagen Sie, welche Schnittstelle jetzt entschieden werden müsste. Wenn es kein Systemdesign oder keine späteren Meilensteinlinien gibt, überspringen Sie den additiven Check, bis Meilensteine existieren; erfinden Sie nie Meilensteine zum Überprüfen. Nennen Sie jedes settled-Element, das die Form ändern würde; das Ändern eines solchen Elements ist ein Auslöser für eine Neuplanung. Lassen Sie Interna innerhalb der Schnittstellen unentschieden; Details kommen auf die Liste „nach dem Ausführen entscheiden“.

4. Widersprüche aufdecken

Sagen Sie es klar, wenn etwas, das der Eigentümer sagt, einer früheren Aussage in dieser Sitzung, einem settled-Element, einer Eigentümerpräferenz, den Projektregeln oder einem Namen in Taxonomy.md widerspricht. Zitieren Sie beide Seiten und fragen Sie, welche gilt. Notieren Sie die Antwort in den Notizen.

5. Einen wegwerfbaren Spike anbieten

Wenn nur das Ausführen von etwas eine Frage klären kann (ist es schnell genug, gibt die API dies zurück, kann die Plattform jenes tun), bieten Sie den kleinsten Lauf, der sie beantwortet: was er tut, welches Ergebnis in welche Richtung weist, und ungefähr wie lange es dauert. Bauen Sie ihn nur, wenn der Eigentümer zustimmt, außerhalb des Produktionscodes (ein Scratch-Verzeichnis oder ein Wegwerf-Branch), führen Sie ihn aus und notieren Sie das Ergebnis in den Notizen. Der Code wird weggeworfen; wenn der Eigentümer ihn behalten möchte, wird er in Schritt 6 als provisorischer Code übernommen.

6. Übernehmen (Promote)

Wenn der Eigentümer sagt, dass er fertig ist, oder das Gespräch konvergiert ist, listen Sie jedes Element in den Notizen auf, das in das Systemdesign eingehen könnte, in der Form aus presenting-for-review.md, jedes mit einer empfohlenen Aktion:

• Als settled übernehmen oder als working übernehmen mit einem Hinweis zur Wiederaufnahme („erneut prüfen, falls …“).
• Zurückstellen für einen späteren Meilenstein, unter Nennung des Meilensteins.
• Verwerfen.

Schlagen Sie in derselben Nachricht Eigentümerpräferenzen gemäß der Zwei-Überstimmungen-Regel vor: nur, wenn der Eigentümer zweimal in dieser Sitzung dieselbe Art von Form, die Sie angeboten haben, überstimmt hat oder einen Geschmack direkt geäußert hat. Jeweils eine Zeile (die Präferenz, ein Beispiel, das Datum), die angibt, ob sie in die projektübergreifende Eigentümerpräferenzdatei oder in die Projektregeldatei gehört. Eine einzelne Entscheidung ist keine Präferenz; Feedback zum Verhalten dieses Skills gehört in die Retrospektive, nicht hierher. Für jedes Element in den Worten des Eigentümers (ein Name, Ergebnistext, eine Schnittstelle) machen Sie das Angebot der Verschärfung aus Schritt 4 des Skills system-design einmal in derselben Nachricht: Listen Sie jede Mehrdeutigkeit auf und zeigen Sie eine verschärfte Version neben dem Original; der Eigentümer akzeptiert, bearbeitet oder behält sie. Beenden Sie mit einer Frage.

Wenden Sie die Entscheidungen des Eigentümers auf das Systemdesign an (overview-template.md) als normale Bearbeitung:

Übernommenes Element	Wohin es geht
Eine Komponente	eine Zeile Komponenten (sketched, Build-Ziel, Vereinbarung) und ein Diagrammknoten mit seiner Tiefenklasse, niemals touched
Eine Schnittstelle	eine Zeile Schnittstellen und Übergaben mit ihrer Vereinbarung
Eine Tabelle, API oder öffentliches Symbol	Reviewable Oberflächen, feldweise, mit ihrer Markierung
Eine Entität oder Beziehung	Datenmodell
Ein Name	Namen, dann <DocDir>/Taxonomy.md, überprüft mit dem Rest als Satz
Eine Wahl zwischen Formen	eine Zeile Entscheidungen: nächste freie D-ID, Art choice, Vereinbarung settled oder working (erneut prüfen falls …), Warum mit Nennung der abgelehnten Form
Ein in der Sitzung gefundenes Unbekanntes	eine Zeile Risiken mit dem günstigsten Experiment
Eine Änderung an einem späteren Meilenstein	dessen Zeile Umfang und Meilensteine und Zelle Additiver Check
Spike-Code, den der Eigentümer behält	eine Zeile Provisorischer Code und den Marker PROVISIONAL im Code
Ein zurückgestelltes strukturelles Element	eine Zeile Offene Fragen mit Nennung des Meilensteins, auf den es wartet, z. B. „Q4 (zurückgestellt bis M3, Änderungen protokollieren): …“
Ein zurückgestelltes Detail	die Liste „nach dem Ausführen entscheiden“, unter dem Meilenstein, der es klären wird

Vereinbarungsmarkierungen folgen der Vorlage: Ein vom Eigentümer geschriebenes oder bearbeitetes Element liest owner (z. B. settled · owner); ein vom Eigentümer unverändert akzeptiertes Element trägt keine proposed-Markierung. Neue IDs setzen die Dokumentsequenz fort und werden nie wiederverwendet. Eine Änderung an einem vereinbarten Element geht über das Entscheidungsprotokoll, nicht über eine stille Bearbeitung. Wenn ein übernommenes Element ein settled-Element (z. B. eine Schnittstelle) ändert oder eine Anfrage des Eigentümers dem aktuellen Meilenstein Struktur hinzufügt, sagen Sie klar, dass eine Neuplanung fällig ist, und schreiben Sie nach den unten stehenden Commits eine Übergabenotiz, damit /rung die Neuplanung in einer späteren Sitzung leitet: <DocDir>/Handoff/replan-<Datum>.md mit Route: replan, Model: opus, Waiting on: Neuplanung nach der Design-Session zu <Thema>, Datum: und einem Textkörper, der die geänderten Elemente und den Commit nennt (handoff.md). Verworfene Elemente werden nicht aufgezeichnet; die Notizendatei in der Git-Historie bewahrt sie. Schreiben Sie akzeptierte Präferenzzeilen in die vom Eigentümer gewählte Datei.

Wenn noch kein Systemdesign existiert, schreiben Sie die übernommenen Elemente in eine neue Overview.md mit dem Header der Vorlage (Status: draft) und nur den Abschnitten, die sie füllen; system-design arbeitet damit weiter.

Committten Sie, indem Sie explizite Pfade bereitstellen, das Systemdesign, Taxonomy.md, die Projektregeldatei, falls geändert, und die Notizendatei, als Design-Session: <Thema>, damit die Historie die Notizen behält. Führen Sie dann git rm für die Notizendatei aus und committen Sie dies als Notizen der Design-Session entfernen: <Thema>. Protokollieren Sie ein step-Ereignis mit skill design-session 1.0.1 und kind design-session (andere Felder im Metriklog von tasklist-run), sowie die Anzahl der von Ihnen zur Übernahme vorgeschlagenen Elemente: proposed, accepted (unverändert), edited und rejected.

Beenden Sie mit einem klaren Satz, der sagt, was sich geändert hat und was der nächste Schritt ist, dann Nächster Schritt: /rung, und fügen Sie (Opus: /model opus) hinzu, wenn dieser Schritt Opus benötigt: ein noch zu vereinbarendes Systemdesign, Meilensteinplanung oder eine Neuplanung, die Schritt 6 als fällig bezeichnet.

Wenn der Eigentümer vor der Übernahme abbricht, lassen Sie die Notizendatei uncommittet an Ort und Stelle und geben Sie ihren Pfad an; die nächste Design-Session zu diesem Thema setzt von dort fort.

Wenn eine verknüpfte Datei oder ein Skill fehlt

Wenn eine verknüpfte Datei fehlt, halten Sie nicht an: Verwenden Sie das Minimum hier und sagen Sie einmal, in ein oder zwei Zeilen, was fehlt und wie es installiert wird (claude plugin install project-planning@danny-sung-agent-skills, oder npx skills add dannys42/agent-skills --skill <Skill-Name> in dasselbe Skills-Verzeichnis, damit relative Links aufgelöst werden).

• Keine terms.md: settled wird erwartungsgemäß Bestand haben; working ist gut genug, um zu starten, und benennt, was uns veranlassen würde, es erneut zu prüfen; owner-Elemente sind die Worte des Eigentümers, proposed die des Agenten. Der additive Check fragt, ob jeder spätere Meilenstein ohne Umstrukturierung hinzugefügt werden kann.
• Keine diagrams.md: Mermaid flowchart, zitieren Sie jede Beschriftung, Beschriftungen sind die Komponentennamen, eine Klasse pro Tiefe (sketched gestrichelt, designed dünn, built fett).
• Keine presenting-for-review.md: wichtige Elemente zuerst (höchstens 5, schwer umkehrbar oder weitreichend), jedes mit Optionen, einem klaren Beispiel, einem Pro und Contra und einer Empfehlung; enden Sie mit einer Frage.
• Keine overview-template.md: Übernehmen Sie in die vorhandenen Abschnitte des Systemdesigns und passen Sie deren Tabellen und Markierungen an.

Ermessensentscheidungen

• Der Eigentümer führt. Bieten Sie Formen und Konsequenzen an; fragen Sie nicht aus oder lenken Sie zu Ihrem Favoriten. Eine Frage, die die Form nicht ändern würde, ist es nicht wert, gestellt zu werden.
• Frei erkunden, eng übernehmen. Alles kann in der Sitzung besprochen werden, aber nur Struktur gelangt in das Systemdesign: Subsysteme, Schnittstellen, Datenmodell, reviewable Oberflächen, Namen, Entscheidungen und Risiken. Interna bleiben draußen.
• Ein Spike schlägt eine Diskussion. Wenn der Eigentümer und der Agent sich über eine Tatsache uneinig sind, die ein kurzer Lauf klären würde, bieten Sie den Lauf an, anstatt zu debattieren.