Slash-Commands für Yurna sauber gestalten

Ein Befehl ist eine kleine Benutzeroberfläche. Sein Name verspricht eine Handlung, seine Optionen grenzen sie ein und seine Antwort erklärt, was tatsächlich passiert ist. Gerade bei Discord-Bots wird diese Oberfläche oft erst am Ende einer Funktion entworfen. Dann entsteht ein technisch korrekter Aufruf, dessen Bedeutung nur die Person versteht, die ihn geschrieben hat. Für Yurna lohnt es sich, den Befehl als ersten Entwurf der Funktion zu behandeln. Wenn die Handlung nicht knapp benannt werden kann, ist meist auch die fachliche Aufgabe noch zu unscharf.

Im untersuchten Yurna-Code beschreibt das Interface SlashCommand neben dem eigentlichen Aufruf unter anderem Kategorie, Cooldown, verzögerte Antwort, Nutzungshinweis und eine optionale Autovervollständigung. Diese Struktur bietet mehrere Ansatzpunkte für einen konsistenten Befehlsentwurf. Sie beweist allein jedoch nicht, dass jeder vorhandene Befehl sämtliche Regeln gleichermaßen umsetzt. Die folgenden Überlegungen sind deshalb ein Gestaltungsverfahren, mit dem neue Befehle entwickelt und bestehende systematisch geprüft werden können.

Mit dem gewünschten Ergebnis beginnen

Vor dem ersten Optionsfeld steht ein Satz aus Sicht des Mitglieds. „Ich möchte wissen, wie weit ich vom nächsten Level entfernt bin“ beschreibt eine andere Aufgabe als „Ich möchte die XP-Verteilung dieses Servers ändern“. Beide betreffen dasselbe Datengebiet, gehören aber nicht automatisch in dieselbe Bedienhandlung. Der erste Aufruf liest persönliche Informationen, der zweite verändert die Regeln einer Community. Ihre Berechtigungen, Fehlerrisiken und sinnvollen Antworten unterscheiden sich deutlich.

Ein Name sollte diese Absicht wiedergeben. Ein allgemeines „manage“ oder „system“ zwingt Menschen dazu, die Unterstruktur auswendig zu lernen. Eine Gruppierung nach einem verständlichen Gegenstand kann dagegen helfen: Rolle anzeigen, Rolle wählen, Rolle entfernen. Dabei sollten nicht beliebig viele Ebenen entstehen. Sobald das mentale Modell komplizierter wird als die eigentliche Handlung, ist die Aufteilung zu technisch. Die optimale Struktur ergibt sich aus häufigen Fragen der Mitglieder, nicht aus dem Ordnerbaum des Repositorys.

Die offizielle Dokumentation zu Application Commands beschreibt Namen, Optionen und Unterbefehle als Teile der registrierten Befehlsoberfläche. Für den eigenen Entwurf ist daraus vor allem relevant, dass die Registrierung eine öffentliche Schnittstelle bildet. Eine spätere Umbenennung betrifft nicht nur Code, sondern auch Anleitungen, Gewohnheiten und gespeicherte Hinweise. Deshalb verdienen besonders häufig verwendete Namen etwas mehr Sorgfalt als interne Funktionsnamen.

Optionen sparsam und eindeutig wählen

Jede Option sollte eine Frage beantworten, die für diese Handlung tatsächlich notwendig ist. Ein Rollenbefehl braucht beispielsweise eine wählbare Rolle. Er braucht nicht zwingend eine Serverkennung, wenn der Server bereits aus dem Kontext feststeht. Überflüssige Angaben schaffen zusätzliche Möglichkeiten für widersprüchliche Eingaben. Gleichzeitig sind versteckte Annahmen gefährlich: Wenn ein Befehl mehrere plausible Zielpersonen haben könnte, sollte die betroffene Person ausdrücklich ausgewählt oder eindeutig als aufrufende Person bezeichnet werden.

Pflichtfelder müssen fachlich notwendig sein. Ein optionaler Kommentar darf fehlen, eine benötigte Zielrolle nicht. Standardwerte sollten nur verwendet werden, wenn sie vorhersehbar sind und die Wirkung nicht überraschend verändern. Bei lesenden Befehlen kann „eigener Rang“ ein verständlicher Standard sein. Bei einer Verwaltungsaktion ist „alle Mitglieder“ als stiller Standard kaum vertretbar. Der wichtigste Test lautet: Würde jemand die Wirkung korrekt vorhersagen, wenn nur Name und Beschreibung des Befehls sichtbar wären?

Auswahllisten und Autovervollständigung vereinfachen Eingaben, ersetzen jedoch keine Prüfung. Zwischen Vorschlag und Ausführung kann eine Rolle verschwinden oder ihre Bedeutung ändern. Zudem kann ein Vorschlag aus einem älteren Zwischenspeicher stammen. Das Backend muss daher den übermittelten Wert erneut dem richtigen Server und der zulässigen Auswahl zuordnen. Die Oberfläche hilft beim Finden; sie erteilt keine dauerhafte Erlaubnis. Dieser Unterschied sollte im Code sichtbar sein, damit Komfort nicht versehentlich zur Sicherheitsannahme wird.

Ein Rollenbefehl als vollständiger Entwurf

Für das Beispiel soll ein Mitglied eine freiwillige Benachrichtigungsrolle erhalten. Angenommen wird, dass eine Verwaltungsperson vorher eine kleine Liste erlaubter Rollen festgelegt hat. Der Befehl darf ausschließlich daraus auswählen. Er verändert keine Moderationsrollen und bearbeitet nur das aufrufende Mitglied. Diese Begrenzung ist ein Produktentscheid: Sie hält den Aufruf einfach und verhindert, dass eine alltägliche Mitgliedsfunktion zu einer allgemeinen Rollenverwaltung anwächst.

Ein möglicher Befehl lautet sinngemäß „Benachrichtigung wählen“ mit der Option „Thema“. Die Option heißt absichtlich nicht „roleId“, weil ein Mitglied an einem Thema interessiert ist und keine interne Kennung bearbeiten möchte. Die Antwort nennt das gewählte Thema und die zukünftige Wirkung. „Du erhältst jetzt Hinweise zu Veranstaltungen“ erklärt mehr als „Erfolg“. Außerdem enthält sie einen Hinweis, wie die Auswahl wieder aufgehoben werden kann. Eine reversible Handlung wird dadurch tatsächlich praktisch umkehrbar.

// Illustrativer Fachvertrag für einen begrenzten Rollenbefehl.
type TopicChoice = {
  guildId: string;
  memberId: string;
  topicKey: string;
};
 
type ChoiceResult =
  | { kind: "added"; label: string }
  | { kind: "already-selected"; label: string }
  | { kind: "unavailable"; reason: string };

Der Rückgabewert unterscheidet eine neue Änderung von einer bereits bestehenden Auswahl. Das ist nicht bloß eine freundlichere Formulierung. Es verhindert, dass ein wiederholter Klick wie eine zweite erfolgreiche Änderung protokolliert wird. Ist die Rolle schon vorhanden, erklärt die Antwort den aktuellen Zustand. Ist sie nicht mehr verfügbar, bleibt die bestehende Mitgliedschaft unverändert. Der Entwurf lässt außerdem offen, wie Discord angesprochen wird; dadurch kann die fachliche Entscheidung unabhängig vom konkreten Bibliotheksaufruf getestet werden.

Lesen, ändern und bestätigen auseinanderhalten

Ein lesender Befehl kann meistens sofort Informationen zeigen. Eine verändernde Handlung braucht dagegen eine Antwort, die ihre Wirkung bezeichnet. Bei einer schwer rückgängig zu machenden Aktion kann ein zusätzlicher Bestätigungsschritt sinnvoll sein. Allerdings sollte nicht jeder harmlose Rollenwechsel eine zweite Rückfrage auslösen. Zu viele Bestätigungen trainieren Menschen darauf, den nächsten Knopf ungelesen zu drücken. Entscheidend sind Reichweite und Wiederherstellbarkeit der jeweiligen Aktion.

Ein XP-Reset für den gesamten Server verdient eine andere Oberfläche als die Abfrage des eigenen Rangs. Vor der Bestätigung müssen der betroffene Bereich und der erwartete Verlust sichtbar sein. Der Bestätigungsknopf sollte an die Person, den konkreten Vorgang und eine begrenzte Gültigkeit gebunden sein. Ein alter Knopf in einer lange sichtbaren Nachricht darf nicht irgendwann eine neue, inzwischen anders konfigurierte Aktion auslösen. Im Zweifel wird ein neuer Entwurf angefordert, statt eine alte Absicht umzudeuten.

Für den freiwilligen Rollenbefehl reicht dagegen eine klare unmittelbare Rückmeldung. Scheitert die Rollenänderung, darf der Bot die Auswahl nicht als erledigt darstellen. Wurde die Änderung bereits vorgenommen, aber die Antwort scheitert, ist ein erneuter Aufruf ungefährlich, weil der bestehende Zustand erkannt wird. Genau hier zahlt sich das getrennte Ergebnis „bereits ausgewählt“ aus. Wiederholbarkeit entsteht durch die Fachlogik und nicht allein durch einen deaktivierten Knopf im Discord-Client.

Hilfetexte an echten Missverständnissen ausrichten

Eine gute Optionsbeschreibung erklärt den Unterschied zwischen plausiblen Alternativen. „Wähle eine Option“ ist keine Hilfe. „Thema, zu dem du künftig benachrichtigt werden möchtest“ erklärt dagegen die Wirkung. Nutzungshinweise sollten vor allem besondere Grenzen nennen: nur auf diesem Server, nur für das eigene Mitglied oder nur für freigegebene Themen. Interne Implementierungsdetails gehören dort nicht hinein, solange sie für die Entscheidung des Nutzers keine Bedeutung haben.

Fehlermeldungen sollten sich nach der nächsten sinnvollen Handlung richten. Eine nicht mehr angebotene Rolle führt zurück zur aktuellen Auswahl. Eine fehlende Bot-Berechtigung führt zu einem Hinweis an die Serververwaltung. Ein kurzzeitiger externer Fehler kann eine spätere Wiederholung erlauben. Diese drei Fälle mit derselben Meldung zu beantworten, spart Text im Code, verschiebt aber die Denkarbeit auf Mitglieder. Besonders neue Nutzer können dann nicht erkennen, ob sie etwas falsch eingegeben haben oder der Bot gerade ein Problem hat.

Bei mehrsprachigen Befehlen bleibt die technische Identität stabil, während Bezeichnungen und Antworten übersetzt werden. Übersetzungen müssen nicht Wort für Wort dieselbe Länge haben. Wichtig ist, dass Handlung und Umfang übereinstimmen. Ein deutsches „entfernen“ darf nicht einer englischen Formulierung entsprechen, die wie ein vorübergehendes Pausieren klingt. Deshalb gehören Übersetzungen der Befehlsoberfläche in fachliche Prüfungen und nicht nur in eine abschließende sprachliche Kontrolle.

Antwortzeit als Teil der Bedienung

Der Befehl sollte möglichst früh erkennen lassen, dass die Aktion angekommen ist. Discord unterscheidet die erste Reaktion auf eine Interaktion von späteren Antworten; die Dokumentation zur Beantwortung von Interaktionen beschreibt diesen Ablauf. Für einen Yurna-Befehl mit externer Prüfung bedeutet das: Die Reaktion darf nicht erst nach allen Datenbank- und Netzschritten geplant werden. Eine bestätigte Bearbeitung und ein endgültiges Ergebnis sind zwei unterschiedliche Momente.

Das vorhandene defer-Feld im Command-Interface ist dafür ein relevanter Anknüpfungspunkt. Eine zentrale Behandlung kann wiederkehrende Antwortlogik vereinfachen, muss aber Sonderfälle beachten. Ein Befehl, der unmittelbar ein Formular öffnen soll, hat andere Anforderungen als einer, der zunächst einen Bericht berechnet. Deshalb sollte eine allgemeine Voreinstellung nicht unbesehen auf jeden Interaktionstyp angewendet werden. Der tatsächliche Ablauf ist wichtiger als ein möglichst einheitlicher Schalter.

Auch Sichtbarkeit gehört in diese Entscheidung. Eine persönliche Rollenbestätigung muss nicht den ganzen Kanal füllen. Ein öffentlich angeforderter Überblick kann dagegen für die gemeinsame Unterhaltung gedacht sein. Die Wahl sollte aus dem Zweck folgen und vor dem Senden feststehen. Sensible Informationen erst öffentlich auszugeben und anschließend zu löschen, ist keine saubere Alternative zu einer passend gewählten Antwortart. Die Oberfläche soll die beabsichtigte Öffentlichkeit ausdrücken, nicht nachträglich korrigieren.

Einen Befehl gezielt abnehmen

Die Abnahme des Rollenbeispiels beginnt mit vier Mitgliedszuständen: Rolle fehlt, Rolle ist vorhanden, Mitglied ist nicht mehr verfügbar und Rolle wurde nach der Auswahl gelöscht. Für jeden Zustand wird vorher eine erwartete Antwort formuliert. Danach werden die Aufrufe ausgeführt und sowohl Discord-Zustand als auch Rückmeldung verglichen. Ein Test ist erst überzeugend, wenn die richtige Änderung und die richtige Erklärung zusammenpassen. Ein korrekter Datenbestand mit einer irreführenden Erfolgsmeldung bleibt ein Bedienfehler.

Zusätzlich wird derselbe Vorgang zweimal ausgelöst. Er darf keine widersprüchlichen Antworten erzeugen und keine weiteren Rollen verändern. Ein langsamer Discord-Zugriff prüft, ob die frühe Bestätigung rechtzeitig erfolgt. Eine künstlich verweigerte Rollenänderung prüft die Fehlermeldung. Schließlich betrachtet eine unbeteiligte Person nur Namen, Beschreibungen und Antworten. Kann sie den Zweck ohne Erklärung durch die Entwicklung verstehen, hat der Befehl seine wichtigste Schnittstelle bestanden.

Ein sauber gestalteter Slash-Command hält damit mehrere Versprechen gleichzeitig: Er benennt eine begrenzte Handlung, verlangt nur notwendige Eingaben und berichtet präzise über das Ergebnis. Yurnas vorhandene Command-Struktur kann diese Disziplin unterstützen. Entscheidend bleibt, jeden neuen Aufruf als kleine vollständige Oberfläche zu behandeln. Dann wächst die Anzahl der Funktionen, ohne dass Mitglieder ein zweites Handbuch im Kopf mitführen müssen.