ntucker/agentenfreundliche-Designsysteme

Designsysteme für agentische Nutzung

Dieses Skill informiert Designentscheidungen; es schreibt sie nicht vor. Jede Empfehlung kann gegenüber einem legitimen Projektziel (Expert:innen-Ausdruckskraft, Markenbedürfnisse, Plattformgrenzen, bestehende Konventionen) verlieren. Benenne den Trade und weiche bewusst ab. Beispiele sind React und TypeScript, weil dort die Modell-Priors am schärfsten sind; die Überlegung lässt sich auf jeden Stack übertragen.

Das Ziel

Ein Code-generierendes Modell ist ein Sampler. Es gibt das Programm aus, das es angesichts seines Trainings (Prior) und des Sitzungkontextes für am plausibelsten hält, und behält, was die ausführbaren Checks übersteht. Eine menschenzentrierte API fragt: „Kann das Richtige ausgedrückt werden?" Eine agentenzentrierte API fragt: „Von allem, was richtig aussieht – wie viel ist auch richtig?"
Das Ziel hat zwei Hälften: Mache das wahrscheinlichste Programm zum korrekten, und bringe die unwahrscheinlichen Programme zum Scheitern, bevor sie ausgeliefert werden.

Dies ist gewöhnliches API-Design (Blochs „easy to use correctly, hard to use incorrectly", Minskys „make illegal states unrepresentable", der Pit of Success) unter zwei strengeren Annahmen: Die Vertrautheit des Konsumenten ist eine messbare Verteilung über öffentlichen Code, und der Konsument verifiziert nur das, was er ausführen kann.

Drei Eigenschaften des Konsumenten

Alles Folgende leitet sich daraus ab. Lies Evidence ledger, wenn eine Behauptung für eine Entscheidung wichtig ist oder du lokal messen musst; dort finden sich Quellen, Gültigkeitsbereich und das Messprotokoll.

1. Der Prior ist frequenzgeformt, versionengemischt und nicht patchar. Ein Modell kennt ein Muster proportional dazu, wie oft es im Training vorkam; die Genauigkeit steigt logarithmisch-linear mit der Korpusfrequenz. Jede jemals erschienene Version einer Bibliothek ist zu einer Verteilung überlagert – daher geben Modelle veraltete APIs in 25–38% der Fälle aus und erzielen bei versionsfixierten Aufgaben nur etwa 50% Trefferquote. Nichts, was eine Bibliothek veröffentlicht, kann dies bearbeiten. Es kann nur erreicht oder überschrieben werden.

2. Kontext überschreibt den Prior – aber nur Kontext, der tatsächlich präsent ist. Prompts aus veraltetem Code erzeugten 70–90% veraltete Nutzung; Prompts aus aktuellem Code erzeugten 9–18%. Geschwistercode in der Datei lenkt die Ausgabe mehr als alles, was eine Bibliothek veröffentlicht. Abgerufene Dokumentation hilft; ein bloßer Versionshinweis hilft ein wenig. Veröffentlichte Dokumentation, die der Agent nie lädt, bewirkt nichts.

3. Nur ausführbares Feedback ist Verifikation. Der Typprüfer ist deterministisch, billig und immer im Kreislauf, und 94% der Kompilierungsfehler in von LLMs generiertem TypeScript sind Typfehler – also fängt er viel ab. Rendering ist teuer, erfordert Setup, und die vision-sprachliche Beurteilung von Layouts ist selbst mit Screenshot schwach. Was die Typen nicht kodieren, wird ausgeliefert, wenn das Modell es falsch macht.

Zwei Konsequenzen. Die Fehlerkosten sind asymmetrisch: Ein Mensch sieht einen schlechten Abstand und behebt ihn in Sekunden; ein Agent liefert einen schlechten Abstand aus. „Leicht zu beheben" ist also weit weniger wert als „schwer falsch zu machen". Und Evolution muss additiv sein: Eine Umbenennung oder Bedeutungsänderung kostet Agenten bis zum nächsten Training, und die alte Form verlässt die Verteilung nie vollständig. Wenn du also etwas brechen musst, stecke die Migration in die Typen und die kollokierte Dokumentation – nicht nur in ein Changelog.

Drei Heuristiken

Jeder Design-Hebel ist eine dieser drei. Bei der Bewertung eines Designs frage: Welche Heuristik wird genutzt, und welche untergräbt sie?

Heuristik 1: Mache den Default-Rat richtig

Der erste Rat des Agenten ist Prior plus sichtbarer Kontext. Zwei Dinge formen ihn.

Namen sind Wetten auf Verteilungen. Der Wert eines Namens ist Schärfe mal Übereinstimmung: Wie eindeutig seine öffentliche Nutzung ist, multipliziert mit der Frage, ob diese Bedeutung deine ist. Schärfe korreliert mit Korpusgröße, Alter und Stabilität – daher ist HTML/CSS-Vokabular besser als ARIA-Pattern-Namen, diese besser als bibliotheksübergreifende Wörter („sm"/„md"/„lg", „primary"/„danger", „solid"/„outline"/„ghost"), und diese besser als die Idiome einer einzelnen Bibliothek. Verankere so tief, wie es die Semantik erlaubt. Übereinstimmung ist binär, und ein vertrauter Name mit anderem Verhalten ist der schlimmste Fall: Das Modell wendet die gelernte Bedeutung selbstbewusst an, und der Code kompiliert. Wenn kein scharfer Name mit deiner Semantik übereinstimmt, setze einen neuen aus gelernten Mustern zusammen. „Page"/„PageHeader"/„PageTitle" existiert in keiner großen Bibliothek, aber die „X"/„XHeader"/„XTitle"-Fügung trägt Hierarchie und Kind-Reihenfolge kostenlos und bleibt in Autocomplete und im Plan des Agenten auffindbar. Ein Prop, dessen Bedeutung von einem anderen Prop abhängt („align" unter einem „direction"-Schalter), sind zwei gekoppelte Wetten; entkopple sie in eine Komponente pro Achse oder explizite Namen. Der Gewinn ist ein Freiheitsgrad weniger, nicht ein geretteter Prior – Modelle kommen mit CSS' eigenem Achswechsel gut zurecht.

Der sichtbare Codebase ist der Prompt. Geschwister-Nutzungen, der Katalog und das kanonische Beispiel sind das, woran der Agent tatsächlich konditioniert ist. Regularität komprimiert diesen Prompt: Wenn jede Komponente die gleichen Achsen mit dem gleichen Vokabular konjugiert, lehren zwei Komponenten im Kontext den gesamten Katalog, und jedes Synonym oder jede komponentenspezifische Ausnahme ist eine separate Tatsache, die gelehrt werden muss – und meist nicht gelehrt wird. Der Katalog partitioniert die Ausgabe: Agenten planen in Einheiten wie „Seitenkopf" und „Werkzeugleiste", bevor sie Code lesen, und zwingen den Plan durch das, was existiert – nenne Komponenten also nach diesen Einheiten. Was die Beispiele zeigen, wird zum Workflow, inclusive „className"-Overrides; zeige den beabsichtigten Pfad und halte Beispiele versionsgemischt und kollokiert mit dem Code, den der Agent bearbeiten muss.

Stärke des Priors rechtfertigt Konformität in der Syntax, die der Agent schreiben muss. Sie rechtfertigt niemals, dem Agenten eine Entscheidung auszusetzen, die er nicht treffen sollte – das ist Heuristik 3.

Heuristik 2: Bringe falsche Ausgabe vor dem Ship zum Scheitern

Alles, was ein Renderer oder Laufzeit abgefangen hätte, muss früher scheitern – oder es wird ausgeliefert.

Wo Typen es ausdrücken können, stecke es in den Typ. Geschlossene Unions statt von niemandem entworfener Boolescher Kombinationen. Diskriminierte Unions für modusabhängige Props. „Omit" für das, was ein Teil nicht unterstützt, statt „verwende das hier nicht" zu dokumentieren. Notwendige Props für die Bedeutung, die der Konsument selbst liefern muss (Dialogtitel, Icon-Button-Labels, Fehlertexte; Radix und React Aria warnen davor nur in einer Konsole, die der Agent nie sieht). Kompilierungsfehler für die nicht unterstützten Fälle von „asChild"/„as" oder explizite nicht-polymorphe Alternativen wie „ButtonLink". Der Test ist jedes Mal derselbe: Ein Agent, der das Prop vervollständigt, sieht das gültige Vokabular, und das illegale Programm kompiliert nicht.

Wo Typen es nicht ausdrücken können, mache die Abweichung dort sichtbar, wo der Code geschrieben wird. Namen tragen Layouterwartungen, die kein Typ kodiert (ein Container besitzt seine Padding, ein Block füllt seinen Elter, Abstand kommt von übergeordneten Gaps; die Fallstudie listet sie). Eine Komponente, die die durch ihren Namen erzeugte Erwartung bricht, kompiliert und rendert still falsch in der einen Dimension, die der Agent nicht sehen kann. Signalisiere den Bruch am Aufrufort (ein erforderliches Prop, ein nicht kollidierender Name) oder in Kontext, den der Agent zuverlässig lädt (eine Regel neben dem Code). Dokumentation, auf die der Agent nicht stoßen wird, zählt nicht.

Heuristik 3: Entferne die Entscheidung

Eine Entscheidung, deren Korrektheit nur beim Rendering sichtbar ist, gehört in die Bibliothek, nicht an den Aufrufort. Ein Prinzip auf vier Granularitäten:

• Werte. Quantisiere jede Größe und kläre Erscheinung über semantische Rollen: „gap="3"" und „tone="danger"" am Aufrufort, px und hex im Theme. Modelle kennen Flex- und Grid-Mechaniken; sie können 12 versus 16 nicht blind wählen, und unabhängige Wahlen driften über Dateien hinweg in einen Rhythmus, den niemand sieht. Schlüsselwörter („justify="space-between"") halten die Semantik frei, während die Skala das Raten entfernt.
• Komposition. Besitze Layout, nicht nur Widgets. Braids Regel ist die saubere Version: Komponenten liefern keinen äußeren Abstand, und Layout-Komponenten besitzen den gesamten Abstand. Ein System, das an der Widget-Grenze aufhört, zwingt jeden Aufrufort zu Improvisation.
• Patterns. Wo sich eine Komposition wiederholt („FormField", „EmptyState", „PageHeader", „ConfirmDialog"), liefere sie aus. Jede erneute Ableitung aus Primitiven ist eine Chance zu divergieren.
• Adaptation. Behandle Viewport, Inhaltslänge, Schreibrichtung, Motion- und Kontrastpräferenzen sowie Lade-/Leer-/Fehlerzustände von Haus aus, oder fordere sie im Typ. Medialogik am Aufrufort ist eine blinde Entscheidung.

Ausstiegsluken („className", „style", CSS-Variablen) sollten existieren und unterhalb des Standardpfads in der Wahrscheinlichkeit liegen: verfügbar, gerankt, nie hervorgehoben. Wenn sie den demonstrierten Workflow darstellen, hat Heuristik 1 sie zum Default-Rat gemacht.

Das Regime entscheidet über Lesbarkeit vs. Vertrag

Zwei kohärente Philosophien existieren; shadcn ist das klarste Statement der ersten.

• Lesbarkeit (Legibility). Liefere Quelltext ins Repository aus. Der Agent liest und bearbeitet ihn, und Styling ist dort sichtbar, wo es geschrieben wird. Richtig, wenn der Agent die Komponenten besitzt: Er wird die Datei öffnen, und lesbare Implementierung (kollokiertes Styling, minimale Indirektion) ist das, was er braucht.
• Vertrag (Contract). Gib eine typisierte API nach außen und verstecke die Implementierung. Richtig, wenn der Agent die Komponenten aus dem App-Code konsumiert: Er sieht Imports, Typen und einige Geschwister-Nutzungen und öffnet die Implementierung selten. Lesbares Styling ist schreibendes Styling, und Styling am Aufrufort ist die Entropie, die Heuristik 3 entfernt.

Die meisten Systeme brauchen beide, geteilt nach Publikum: Lesbarkeit für den, der „components/" wartet, Vertrag für den, der daraus importiert. Entscheide vor Anwendung der Heuristiken, in welchem Regime eine Datei liegt. Lies shadcn case study, wenn das System auf shadcn aufbaut oder mit ihm verglichen wird; das Dokument arbeitet durch, was zu behalten, was zu ändern und warum.

Spannungsfelder

Zwei, jedes mit mehreren Gesichtern. Benenne den Trade; tue nicht so, als sei er kostenlos.

• Konzentrierte Wahrscheinlichkeit vs. Ausdrucksstärke. Jeder entfernte Freiheitsgrad ist jemandes verlorene Fähigkeit. Es erscheint als Intent-Komponenten vs. Primitive, als geschlossene Achsen vs. orthogonale Props, und als Dehnung einer Achse vs. Teilung (dehne, solange jeder Wert dieselbe Frage beantwortet; shadcn's „Button"-Variante, die Intent, Aussehen und Elementidentität verschmilzt, ist die kanonische verschmolzene Achse). Die gerankte Ausstiegsluke ist die übliche Antwort.
• Prior-Alignment vs. Ownership. Konvention zu treffen kauft kostenlose Korrektheit und importiert die Fehler und den Wandel der Konvention. Es erscheint als vertraute vs. distincte Namen (distinct kostet Auffindbarkeit; grammatikkonforme, neuartige Namen holen das meiste zurück) und als priorfreundlich vs. besser gestaltet. Abweichen kostet einmal Alignment; ein behaltener Fehler kostet ein Leben lang Korrektheit.

Miss statt zu vertrauen

Die drei Eigenschaften sind auf Modellebene gemessen. Die Heuristiken sind Mechanismen, die mit diesen Messungen konsistent sind, nicht gemessen an einer UI-Bibliothek; die Evidenzdatei markiert, was was ist. Bevor du eine Regel übernimmst, führe sie aus: 20 bis 40 realistische UI-Aufgaben, mehrfach pro Regime beprobt (kein Kontext, Typen plus zwei Geschwister-Nutzungen, vollständiger Quelltext); bewerte Erstversuch-Kompilierung, Missbrauch, der von Typen vs. still gefangen wird, Token-Varianz über Geschwister-Aufruforte, Accessibility-Lint und einen kurzen visuellen Durchlauf; ändere eine Designentscheidung; führe erneut aus. Behalte, was die Zahlen bewegt.

Review-Checkliste

• Heuristik 1: Würde ein mit vergleichbaren Bibliotheken vertrautes Modell dies beim ersten Versuch raten, und wenn der Name geliehen ist, verhält es sich identisch? Zeigt das kanonische Beispiel den beabsichtigten Pfad?
• Heuristik 2: Scheitert jeder realistische Missbrauch an der Kompilierung? Wo die visuelle Erwartung eines Namens gebrochen ist, ist der Bruch dort sichtbar, wo der Code geschrieben wird?
• Heuristik 3: Ist irgendein Wert, irgendeine Komposition, irgendein Pattern oder irgendeine Adaption dem Aufrufort zur blinden Entscheidung überlassen?
• Regime: Wird diese Datei vom Agenten besessen oder nur konsumiert, und ist die Wahl zwischen Lesbarkeit und Vertrag bewusst?
• Evolution: Würde diese Änderung Code brechen, der mit dem letztjährigen Prior geschrieben wurde, und ist die Migration in Typen und kollokierten Docs sichtbar?