Communitygithub.com

ai-states

Gestalte alle Momente einer KI-Funktion außer der richtigen Antwort – erste Nutzung, Arbeit, Nichtwissen, Unsicherheit, Ablehnung, Fehler, Korrektur, Übergabe an einen Menschen, und für Agenten die gesamte Delegation (Plan, Berechtigungen, unbeaufsichtigtes Arbeiten, „braucht dich“, Rückgabe, Rückgängigmachen, Gedächtnis) – als Zustandstafel mit exakten Texten, einer baubaren Spezifikation, Tests und Metriken.

Was ist ai-states?

Das Skill `ai-states` unterstützt Entwickler und Designer dabei, alle Zustände einer KI-gestützten Funktion zu entwerfen, die über die bloße Antwort hinausgehen. Es behandelt Momenten wie erste Nutzung, das Arbeiten der KI, Nichtwissen, Unsicherheit, Ablehnung, Fehler, Korrektur, Übergabe an einen Menschen sowie für Agenten die gesamte Delegation (Plan, Berechtigungen, unbeaufsichtigtes Arbeiten, „braucht dich“, Rückgabe, Rückgängigmachen, Gedächtnis). Das Skill bietet eine strukturierte Vorgehensweise, um diese Zustände als Zustandstafel mit exakten Texten, baubaren Spezifikationen, Tests und Metriken zu erfassen. Es ist nützlich für jede KI-Funktion – Chatbots, Copiloten, Assistenten, KI-Suche, Zusammenfassungen, „Mit KI generieren“-Buttons oder Agenten, die Aktionen ausführen, Tools verwenden oder im Hintergrund arbeiten – und hilft, kalibriertes Vertrauen aufzubauen. Es unterstützt die Analyse von Fehlermodi, das Definieren von Signalen, das Festlegen von Autonomie-Leveln und die Erstellung von Testszenarien, um sicherzustellen, dass Benutzer jederzeit wissen, was die KI tut, worauf dies basiert und was sie als Nächstes tun können.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/milagrosgonzalezarguello-des/ai-states-skill/tree/HEAD/ai-states

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

KI-Zustände

Gestalte die Momente einer KI-Funktion abgesehen von dem, in dem sie funktioniert.

Teams entwerfen den Demofall: Der Benutzer fragt, die KI antwortet, alle klatschen. Dann benutzen echte Menschen das Produkt. Sie fragen etwas, das die KI nicht kann, es dauert vierzehn Sekunden, es antwortet mit absoluter Sicherheit und liegt falsch, die Verbindung bricht mitten im Satz ab, und das Produkt zeigt einen Spinner und „Etwas ist schiefgelaufen“ an. Jetzt, wo die KI auch handelt – sie sendet, bucht, bearbeitet und arbeitet weiter, während niemand zusieht – sind die nicht gestalteten Momente noch schlimmer: Sie hat etwas getan, und der Benutzer kann nicht sagen, was.

Die Aufgabe ist also nicht „das Chat-Interface entwerfen“. Sie lautet: Zu jedem Zeitpunkt weiß der Benutzer, was die KI tut, worauf dies basiert und was er als Nächstes tun kann – und, wenn die KI für ihn handelt, was sie getan hat und wie er es rückgängig machen kann.

Das Ziel ist kalibriertes Vertrauen: Benutzer verlassen sich auf die Funktion so sehr, wie sie es verdient, Fall für Fall. Beide Arten des Verfehlens sind Fehlschläge – die Annahme ohne Überprüfung und das manuelle Neumachen von allem.

Was jede KI-Funktion richtig machen muss

Überprüfe diese zuerst. Sie sind das, was ein Benutzer bemerkt, wenn sie fehlen.

  1. Niemals ein nackter Spinner. Nach etwa zwei Sekunden muss der Benutzer wissen, was passiert, und nach zehn, wie er es stoppen oder verlassen kann.
  2. Vier verschiedene „Nein“s. Weiß nicht (keine Information), kann nicht (keine Fähigkeit), will nicht (nicht erlaubt) und kaputt (Systemfehler) haben unterschiedliche Ursachen und unterschiedliche nächste Schritte. Eine allgemeine Fehlermeldung für alle vier bringt Benutzer dazu, Dinge erneut zu versuchen, die niemals funktionieren werden.
  3. Nichtwissen ist ein entworfener Zustand, kein Fehler. „Ich konnte das in Ihren Dokumenten nicht finden“ ist eine gute Antwort. Sie macht die anderen Antworten glaubwürdig.
  4. Nichts sieht vollständig aus, wenn es das nicht ist. Ein unvollständiges Ergebnis, das vollständig erscheint, ist der gefährlichste Zustand überhaupt, weil niemand es überprüft.
  5. Grenzen werden vorab genannt. Der Benutzer erfährt, was die KI kann und was nicht, vom ersten Bildschirm an, nicht durch Scheitern.
  6. Jeder Sackgasse hat einen Ausweg, und nichts, was der Benutzer eingegeben hat, geht verloren: Das Getippte, Angehängte oder Ausgewählte sowie das vorherige Ergebnis sind nach jedem Fehler noch da.
  7. Überprüfen kostet weniger als Neumachen. Antworten zeigen ihre Grundlagen, im Verhältnis zu den Konsequenzen – die Quelle neben der Behauptung, die abgedeckten Seiten, das Datum, bis zu dem es aktuell ist. Wenn Überprüfen bedeutet, die Arbeit noch einmal zu machen, spart die Funktion nichts.
  8. Bevor sie handelt, zeigt sie an; nachdem sie gehandelt hat, kann sie rückgängig gemacht werden. Alles, was sendet, löscht, bezahlt oder etwas ändert, erhält eine Vorschau und, wenn es nicht rückgängig zu machen ist, eine Bestätigung. Bestätige, was wichtig ist, nicht alles: Ständige Aufforderungen trainieren Benutzer dazu, ohne Lesen zu genehmigen.
  9. Unbeaufsichtigt erledigte Arbeit wird als Bericht zurückgegeben, nicht als Jubel: Was getan wurde, was nicht, was nicht überprüft wurde und wo zuerst hingesehen werden sollte.
  10. Sie sagt nur, was das System wissen kann. Kein Vertrauenslabel, das das Modell nicht belegen kann, kein „Ich habe geprüft“, wenn nichts geprüft wurde, kein „Ich werde mich erinnern“, wenn nichts gespeichert wird.

Wie man arbeitet

  1. Verstehe die Funktion, bevor du etwas zeichnest. Du brauchst: Was die KI tut und für wen; die Oberfläche (lies references/surfaces.md, einschließlich der Frage, ob Chat die richtige ist); was sie liest und was sie ändern kann; was das System tatsächlich erkennen und bereitstellen kann – Streaming, Quellen, ein Ablehnungssignal, ein Retrieval-Score, Fehlertypen, Schritt-Ereignisse; ob es eine menschliche Auffangoption gibt; Sprache und Register. Lies, was der Benutzer dir gegeben hat, und frage dann in einer Runde nach dem, was fehlt. Wenn du nicht fragen kannst (ein nicht-interaktiver Durchlauf oder der Benutzer ist nicht da), nimm die wahrscheinlichste Antwort an, markiere jeden Auslöser, der davon abhängt, zur Bestätigung, und liste die Annahmen auf. Erfinde keine Fähigkeiten: Ein Zustand, den das System nicht erkennen kann, kann nicht gebaut werden. Das ist etwas anderes als ein Signal, das das Team bauen muss: Wenn ein Zustand, den die Funktion braucht, von etwas abhängt, das das System noch nicht bereitstellt (ein Fehlertyp, ein Ablehnungsflag), entwirf den Zustand und liste das Signal als zu bauen in der Signaltabelle auf – diese Tabelle ist oft das Nützlichste, was die Entwicklung von dir bekommt.

  2. Lege die Konsequenzen fest. Sie entscheiden, wie viel jeder Zustand braucht.

    KonsequenzenBeispieleWas sich ändert
    NiedrigBrainstorming, einen Satz umschreiben, lockere FragenLeichte Berührung: Neu generieren und Bearbeiten sind das Sicherheitsnetz
    MittelZusammenfassungen, nach denen Menschen handeln, Antworten über das eigene Konto oder Firmendaten des BenutzersQuellen, sichtbarer Umfang, ein klares „Nicht gefunden“
    HochGeld, Gesundheit, Recht, Sicherheit, alles, was an andere gesendet oder nicht rückgängig zu machen istBestätigung vor dem Handeln, Beleg im Pfad, ein menschlicher Weg, ein Prüfpfad

    Konsequenzen ergeben sich daraus, was Menschen mit der Ausgabe tun, nicht daraus, ob die KI handelt: Eine schreibgeschützte Zusammenfassung eines Vertrags, auf die Anwälte sich verlassen, hat hohe Konsequenzen. Für eine hochriskante Funktion, die keine Aktionen ausführt, bedeutet „hoch“ Beleg im Pfad, sichtbare Abdeckung und einen menschlichen Weg – es gibt nichts zu bestätigen.

  3. Gehe die Arten des Scheiterns durch (references/failure-modes.md). Die meisten sind stillschweigend: eine flüssige falsche Antwort, eine Auslassung, ein Agent, der mehr tut als verlangt, eine Anweisung, die in ein Dokument eingeschleust wurde. Nenne für jede, die hier vorkommen kann, den Zustand oder das Muster, der dagegen schützt.

  4. Baue die Zustandskarte. Gehe jeden Zustand in references/states.md durch und markiere ihn:

    • Trifft zu – ja, nein (mit dem Grund) oder nur wenn ein Signal existiert, das du nicht bestätigen konntest.
    • Heute (bei der Überprüfung von etwas, das existiert) – entworfen, unvollständig (es existiert, aber es fehlt etwas, das die Konsequenzen erfordern – sag was), generisch (ein Sammelbecken behandelt es) oder fehlt.

    Ein nur wenn-Zustand bekommt einen Spezifikationsblock und eine Zeile in der Karte, zählt als „zu bestätigen“ im Abdeckungsstreifen, nicht in der Gesamtzahl, und bekommt eine Karte nur, wenn er wahrscheinlich genug ist, um gezeichnet zu werden.

    Wenn die KI mehrere Schritte ausführt, eigenständig Tools verwendet oder arbeitet, während der Benutzer nicht da ist, mach dasselbe mit den Delegationszuständen in references/delegation.md und fülle die Autonomiestufe und die Berechtigungstabelle für jede Art von Aktion aus. Ein Chat, der eine Aktion nach Bestätigung durch den Benutzer ausführt, ist kein Agent: Zustand 5 (mit seinem „Nach Bestätigung“-Bildschirm und dem Rückgängigmachen) deckt ihn ab, plus eine dreispaltige Berechtigungstabelle. Zwinge keine D1-D12 darauf. Überspringe die Karte nicht, selbst wenn der Benutzer nach einem einzelnen Zustand gefragt hat: Sag ihnen, welche anderen die Funktion braucht.

  5. Spezifiziere jeden zutreffenden Zustand im untenstehenden Format.

  6. Zeichne die Tafel. Beginne mit assets/template.html: eine Karte pro Zustand, die die echte Komponente in diesem Zustand mit dem endgültigen Text zeigt. Eine Liste von Zuständen in Prosa wird genickt; eine Tafel, bei der die Lücken sichtbar fehlen, wird behoben. Verwende das eigene Aussehen des Produkts, wenn es dir gegeben wurde (Farben, Komponenten, Screenshots); ansonsten behalte den neutralen Stil der Vorlage bei und sag das. Zeichne die echte Oberfläche der Funktion: Eine Button-und-Panel-Funktion bekommt Panels, keine Chat-Bläschen. Ein Zustand, der mehrere Bildschirme braucht (vor und nach der Bestätigung), bleibt eine Karte mit diesen Bildschirmen. Für ein neues Design lösche den Erkenntnisblock der Vorlage und die Spalte „Heute“ der Karte und lass die Abdeckungszeile sagen, wie viele Zustände zutreffen, wie viele nicht und wie viele auf ein Signal warten.

  7. Schreibe die Texte gemäß references/copy.md, in der Sprache und dem Register des Produkts.

  8. Schreibe das Testskript und die Metriken (references/measure.md): eine Eingabe, die jeden Zustand auslöst, und was dafür protokolliert werden soll.

  9. Überprüfe gegen references/checklist.md und references/anti-patterns.md, mit Blick auf die gerenderte Tafel, nicht die Quelle. python scripts/screenshot.py board.html board.png rendert sie in ein Bild, das du öffnen kannst (In-App-Browser lehnen oft lokale Dateien ab); füge --tile 1400 hinzu, um es in lesbaren Abschnitten zu erhalten, wenn die Tafel lang ist. Wenn du die Tafel nach dem Betrachten änderst, rendere erneut.

  10. Liefere die Tafel, die Spezifikation und eine kurze Liste dessen, was du angenommen hast und was beantwortet werden muss. Sag, was du überprüft hast und was nicht.

Was zu lesen ist. Immer: states.md, copy.md, checklist.md und den Abschnitt von surfaces.md für diese Oberfläche. Für eine Überprüfung auch failure-modes.md und anti-patterns.md. Nur für Agenten (mehrere Schritte, Tools, unbeaufsichtigte Arbeit): delegation.md. measure.md, wenn du das Testskript schreibst.

Die Zustände

Vierzehn Antwortzustände in fünf Momenten. Jeder ist detailliert in references/states.md mit dem, was der Benutzer braucht, dem Muster, dem Anti-Muster und Text.

MomentZustandDer Benutzer fragt sich
Vorher1. Erste NutzungWas ist das und was kann ich fragen?
2. VerfassenWas wird es verwenden? Ist meine Eingabe in Ordnung?
Während3. ArbeitetTut es etwas? Wie lange? Kann ich es stoppen?
4. Braucht eine KlärungWas braucht es von mir?
5. Braucht meine ZustimmungWas genau wird es gleich tun?
Antwort6. AntwortWorauf basiert das? Was kann ich damit tun?
7. TeilantwortWelcher Teil ist fertig und welcher nicht?
8. UnsicherWie sehr kann ich mich darauf verlassen?
Nein9. Weiß nichtGibt es keine Antwort, oder hat es nicht am richtigen Ort gesucht?
10. Kann das nichtWer oder was kann es?
11. Will das nichtLiegt es an mir oder an der Regel? Was kann ich stattdessen fragen?
12. KaputtHabe ich meine Arbeit verloren? Soll ich es nochmal versuchen?
Danach13. KorrigiertHat es meine Korrektur übernommen? Wird es wieder passieren?
14. An einen Menschen übergebenWer hat es jetzt, was weiß er und wann?

Zwölf Delegationszustände, für KI, die handelt. Detailliert in references/delegation.md.

ZustandDer Benutzer fragt sich
D1. AuftragHat es den Job und seine Grenzen verstanden?
D2. PlanWie wird es es machen, und kann ich das ändern?
D3. BerechtigungWas genau lasse ich es berühren, und für wie lange?
D4. Arbeitet unbeaufsichtigtIst es noch auf Kurs? Muss ich zusehen?
D5. Braucht dichWorauf wartet es, und was passiert, wenn ich nicht antworte?
D6. GelenktHat es die neue Anweisung übernommen?
D7. RückgabeWas hat es getan, was nicht, und wo sehe ich zuerst hin?
D8. Überprüfung im MaßstabWelche dieser 140 Änderungen muss ich mir tatsächlich ansehen?
D9. Rückgängig machen und reparierenKann ich es zurücknehmen – ganz oder nur das?
D10. Ist schiefgelaufen, während ich weg warWie schlimm ist es, und wo hat es aufgehört?
D11. LerntWas nimmt es jetzt über mich an?
D12. Handelt gegenüber anderenWas sehen andere Leute – und wissen sie, dass es die KI war?

Bei einem Agenten, der im Hintergrund ohne Unterhaltung arbeitet, werden mehrere Antwortzustände durch ihr Delegationsgegenstück ersetzt, anstatt doppelt gezeichnet zu werden: Verfassen durch D1 Auftrag, Arbeitet durch D4, Braucht eine Klärung durch D5. Markiere den Antwortzustand „nein – siehe D4“ in der Karte. Ein wiederkehrender Job (jede Nacht, jeden Montag) hat einen festen Auftrag und Plan: D1 und D2 sind die Einstellungen, die der Benutzer einmal überprüft und vor jedem Durchlauf sehen kann. Auf einer solchen Tafel kannst du die Karten nach Zeit ordnen (vorher, während es arbeitet, wenn es zurückgibt) anstatt nach den fünf Momenten, wenn das besser lesbar ist; behalte die Zustandsnummern bei.

Eine Aktion, die das Produkt selbst aus geschäftlichen Gründen ablehnt (nicht genug Guthaben, ein bereits belegtes Datum), ist keines der vier „Nein“s der KI: Zeige sie als Bildschirm von Zustand 5, mit dem Grund vom System und was der Benutzer ändern kann.

Vier Dinge durchziehen alle und werden als Notizen auf die Tafel gesetzt: Unterbrechung, Gedächtnis, Proaktivität (die KI spricht zuerst) und Kosten (Guthaben, Kontingente, Ausgaben). Siehe das Ende von references/states.md.

Wenn du nur fünf entwerfen kannst: Arbeitet, Weiß nicht, Kaputt, Teilantwort und Braucht meine Zustimmung, wenn es handelt (Rückgabe, wenn es unbeaufsichtigt arbeitet). Das sind die, bei denen Vertrauen am schnellsten verloren geht.

Spezifikationsformat

Ein Block pro Zustand, in dieser Reihenfolge. Entwickler bauen vom Auslöser aus; ohne ihn ist der Zustand ein Wunsch.

### 9. Weiß nicht
- **Auslöser:** Retrieval gibt keine Passage über dem Schwellenwert zurück. (zur Bestätigung: der Schwellenwert)
- **Zeigt:** Die Antwortblase, neutraler Stil (nicht der Fehlerstil).
- **Text:** „No encontré información sobre licencias por mudanza en las políticas de RR. HH.“
- **Aktionen:** Umformulieren · Die Richtlinien ansehen · RR. HH. fragen
- **Behält:** Die Frage, bearbeitbar.
- **Geht zu:** 2 Verfassen, oder 14 An einen Menschen übergeben.
- **Test:** „¿Hay licencia por mudanza?“
- **Metrik:** `answer_not_found` mit der Abfrage; beobachte die Rate nach Thema.
- **Offene Frage:** Kann das System „keine Dokumente“ von „Dokumente existieren, aber der Benutzer hat keinen Zugriff“ unterscheiden?

Übersetze die Bezeichnungen (Auslöser, Zeigt, Text...), wenn das Team in einer anderen Sprache arbeitet: Disparador, Muestra, Texto, Acciones, Conserva, Lleva a, Prueba, Medición, Pregunta abierta.

Behält ist alles, was der Benutzer verlieren würde: getippter Text, Anhänge, die Auswahl, das vorherige Ergebnis, die Arbeit, die ein Agent bereits erledigt hatte.

Sprache und Register

Schreibe in der Sprache, die der Benutzer verlangt; wenn er es nicht sagt, verwende die Sprache seiner Anfrage und des Produkts. Das Register ist die Wahl des Produkts, kein Standard: Finde heraus, wie das Produkt bereits spricht (usted, vos, tú; formell oder warmherzig) und behalte es in jedem Zustand bei. Der Fehlerzustand ist der Ort, an dem Teams in eine andere Stimme verfallen – ein formelles „Ha ocurrido un error“ in einem Produkt, das überall sonst „¡Listo!“ sagt, wirkt wie ein anderes Unternehmen.

Zwei Sprachen können im Spiel sein. Der Text – alles innerhalb der gezeichneten Bildschirme – ist in der Sprache und dem Register des Produkts. Die Tafel und Spezifikation darum herum – Zustandsnamen, Überschriften, die Bezeichnungen der Spezifikation, deine Notizen – sind in der Sprache, in der das Team arbeitet, also der Sprache, in der der Benutzer dir geschrieben hat. Lasse die englischen Überschriften der Vorlage nicht auf einer Tafel für ein spanischsprachiges Team. Die Beispiele in den Referenzdateien sind in formalem Spanisch und Englisch; sie zeigen das Muster, also schreibe sie im Register des Produkts um, anstatt sie zu kopieren.

Die eigene Stimme der KI: Wenn das Produkt die KI in der ersten Person sprechen lässt, behalte das „Ich“ für das, was sie getan hat („No encontré...“, „Usé los tres archivos“), nicht für Gefühle, die sie nicht hat („Me encantaría ayudarte“). Wenn die Funktion keine Persona hat – ein Button, ein Panel – schreibe in der unpersönlichen Stimme des Produkts („No se pudo leer el archivo...“).

Was du lieferst

  1. Die Zustandstafel (board.html), die du im Browser öffnen und als Screenshot anfügen kannst. Keine zwei Versionen – die HTML-Datei ist die Quelle der Wahrheit. Sie enthält alle Zustände mit ihren Karten, die Abdeckungszeile („X von Y Zuständen entworfen“), die Signaltabelle („zu bauen“-Signale fett) und deine Annahmen und offenen Fragen am unteren Rand.
  2. Die Spezifikation (spec.md) mit den vollständigen Blöcken für jeden Zustand: Auslöser, Anzeige, Text, Aktionen, Behält, Geht zu, Test, Metrik, offene Fragen. Die Spezifikation ist das, was das Entwicklungsteam zum Bauen braucht – die Tafel ist das, was alle anderen brauchen, um zu verstehen, was sie bauen.
  3. Das Testskript (tests.md): Eine Liste von Eingaben, Befehlen oder Szenarien, die jeden Zustand auslösen, plus was gemessen werden soll. Siehe references/measure.md für das Format.
  4. Annahmen und ausstehende Antworten (assumptions.md): Eine kurze Liste. „Angenommen: Die Wissensdatenbank hat mindestens 100 Dokumente, bevor Retrieval aktiviert wird. Zu bestätigen: Schwellenwert für Nichtwissen. Offen: Kann die API einen Ablehnungsgrund zurückgeben oder nur einen Fehlercode?"

Die Referenzen lesen, nicht raten. states.md hat die Details jedes Zustands. copy.md hat die Textregeln. checklist.md hat die Überprüfungspunkte. anti-patterns.md hat die Fallen. surfaces.md hilft bei der Wahl der Oberfläche. failure-modes.md identifiziert, was schiefgehen kann. delegation.md für Agenten. measure.md für Metriken. Sage, was du gelesen hast.

Verwandte Skills