Veraltete API-Dokumentation: Agent-Aktionen sicher testen

Veraltete API-Dokumentation ist ein Sicherheitsproblem für Agenten, kein redaktionelles Ärgernis. Ein Mensch liest vielleicht ein altes Beispiel, zögert und fragt einen Kollegen. Ein autonomer Programmieragent macht aus demselben Beispiel oft eine Anfrage und wertet die Antwort anschließend als Beleg dafür, dass er richtig gehandelt hat.

Das verändert den Maßstab. Wenn deine Dokumentation einem Agenten erklärt, wie er eine API aufruft, ein Token rotiert, einen Datensatz löscht oder einen Produktions-Host erreicht, behandle den Text als ausführbare Eingabe. Teste ihn gemeinsam mit dem Tool. Eine Seite, die bei ihrer Veröffentlichung korrekt war, aber nicht mehr zum Live-Dienst passt, kann einen Agenten zu einer unsicheren Aktion bewegen, selbst wenn die API genau so funktioniert, wie ihre aktuellen Betreuer es vorgesehen haben.

Die gefährlichste Abweichung zeigt sich selten durch einen lauten Fehler. Ein 404 fällt auf. Eine Anfrage, die weiterhin 200 liefert, aber mehr Ressourcen auswählt, einen geänderten Standardwert nutzt oder eine erwartete Bestätigung umgeht, tut das nicht. Genau solche Unterschiede erzeugen ein sauberes Aktivitätsprotokoll und einen sehr schlechten Nachmittag.

Dokumentation wird Teil der Steuerungsebene des Agents

Ein Agent nutzt Dokumentation, um Operationen auszuwählen, Parameter zu befüllen, Antworten zu verstehen und über Wiederholungen zu entscheiden. Damit gehören Beispiele, Referenztabellen, Authentifizierungsanleitungen und Migrationshinweise zu seiner Steuerungsebene. Der Dienstcode kann korrekt sein, während diese Ebene dem Agenten die falsche Nutzung vorgibt.

Teams ziehen oft eine künstliche Grenze zwischen einer Tooldefinition und einem Leitfaden. Eine Tooldefinition sagt deleteProject(project_id). Der Leitfaden erklärt, welche Projekt-ID zu verwenden ist, ob es einen Probelauf gibt, ob das Löschen weitere Objekte erfasst und was nach einem Autorisierungsfehler zu tun ist. Der Agent braucht beides. Wenn eine der beiden Quellen falsch ist, kann die daraus entstehende Aktion falsch sein.

Deshalb ist ein veraltetes Beispiel etwas anderes als ein Tippfehler in einem Absatz. Eine alte Anweisung könnte sagen, dass ein fehlender Parameter scope «aktuelles Projekt» bedeutet. Eine spätere Änderung im Backend macht aus derselben Auslassung «alle für diese Zugangsdaten verfügbaren Projekte». Der Endpunkt funktioniert weiterhin. Das Beispiel lässt sich weiterhin parsen. Ein Agent, der dem alten Leitfaden folgt, kann eine angeblich lokale Änderung nun auf ein ganzes Konto anwenden.

Dokumentation bestimmt außerdem das Vertrauen des Agents. Konkrete Snippets wiegen mehr als eine vage Warnung im umgebenden Text. Sagt eine Seite «Prinzip der geringsten Rechte verwenden», während eine andere ein Bearer-Token mit kontoweitem Zugriff zeigt, gewinnt in der Praxis das Snippet. Agenten optimieren auf einen Weg, der ein Ergebnis liefert.

Behandle Folgendes als handlungsrelevante Dokumentation:

• Anfrage- und Befehlsbeispiele
• Parametertabellen mit Standardwerten und zulässigen Werten
• Anweisungen zur Einrichtung von Authentifizierung, Zugangsdaten und Umgebungen
• Hinweise zu Wiederholungen, Paginierung, Idempotenz und Fehlerbehandlung
• Migrations- und Abkündigungshinweise, die den Ersatz für eine Operation nennen

Unterscheide zwischen Syntaxabweichung und Bedeutungsabweichung. Bei einer Syntaxabweichung schlägt ein Beispiel fehl, weil sich ein Feld oder Pfad geändert hat. Bei einer Bedeutungsabweichung bleibt das Beispiel gültig, wirkt sich aber anders aus. Syntaxabweichungen sind peinlich für den Autor. Bedeutungsabweichungen können Daten beschädigen, Geld kosten, Datensätze offenlegen oder den Zugriff erweitern. Deine Tests müssen beides erkennen.

Eine erfolgreiche Anfrage kann trotzdem beweisen, dass das Beispiel falsch ist

Ein Dokumentationstest, der nur Statuscodes prüft, findet die einfachen Fehler und übersieht die gefährlichen. Ein HTTP-Erfolg bedeutet, dass der Server die Anfrage angenommen hat. Er sagt nichts darüber aus, ob die Anfrage das richtige Objekt betraf, die beschriebene Nebenwirkung hatte oder die genannte Grenze einhielt.

Angenommen, eine Referenzseite veröffentlicht diese Anfrage:

curl -sS -X POST "$API_URL/v1/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project":"demo","include_archived":false}'

Ein einfacher Test prüft auf 202 Accepted und erklärt den Vorgang für erfolgreich. Dabei entgehen ihm mehrere relevante Änderungen:

• Der Dienst benennt project still in project_id um und behandelt das alte Feld als fehlend.
• include_archived wird von einer Option zum Ausschließen zu einem ignorierten Kompatibilitätsfeld.
• Die Zugangsdaten erhalten kontoweite Sichtbarkeit, sodass demo auf das Projekt eines anderen Mandanten verweist.
• Der Endpunkt reiht die Arbeit weiterhin ein, exportiert nun aber Anhänge, die der Leitfaden als ausgeschlossen beschreibt.

Der Test muss Ergebnis und Dienstzustand prüfen, nicht nur den Status. Lege in einem wegwerfbaren Konto einen aktiven und einen archivierten Datensatz an. Sende die dokumentierte Anfrage. Frage den resultierenden Auftrag ab. Stelle sicher, dass das Artefakt den aktiven Datensatz enthält, den archivierten auslässt und die erwartete Projekt-ID aufzeichnet. Kann der Dienst nicht genug Belege für diese Prüfung liefern, kann die Dokumentation dieses Verhalten ebenfalls nicht sicher versprechen.

RFC 9110 definiert HTTP-Statuscodes als Ergebnis der Verarbeitung einer Anfrage. Es behauptet nicht, dass ein erfolgreicher Status die geschäftliche Absicht des Aufrufers beweist. Das klingt offensichtlich, trotzdem bauen Teams weiterhin Dokumentationsprüfungen nach dem Muster curl plus grep 200. Nutze HTTP-Semantik für Protokollzusicherungen und ergänze Zusicherungen für das tatsächliche Ergebnis.

Ein guter Test benennt die Behauptung, die er prüft. export_excludes_archived_records ist nützlich. docs_example_returns_success sagt hauptsächlich, dass jemand eine Anfrage ausgeführt hat.

Beispiele brauchen Vertragstests statt Screenshot-Prüfungen

Ein Beispiel während des Release-Reviews von der Dokumentationsseite in ein Terminal zu kopieren ist besser als nichts. Es skaliert nicht, hinterlässt keine verlässlichen Belege und bevorzugt den Happy Path. Menschen reparieren den Befehl außerdem oft lokal und vergessen, die Seite zu korrigieren.

Lege ausführbare Beispiele in einer strukturierten Quelldatei ab, erzeuge daraus das gerenderte Snippet und führe dieselbe Quelle in CI aus. Du kannst OpenAPI-Beispiele, die Extraktion von Markdown-Code oder ein separates Fixture-Verzeichnis verwenden. Der Mechanismus ist weniger wichtig als eine Eigenschaft: Der Befehl, den der Leser sieht, muss der Befehl sein, den der Test ausführt.

Pflege nicht heimlich eine «Testversion» mit sichereren URLs, engeren Berechtigungen oder vollständigeren Headern als im veröffentlichten Beispiel. Diese Trennung erzeugt einen beruhigenden grünen Build, während die öffentliche Anleitung verrottet. Parametrisiere nur Werte, die je nach Umgebung abweichen müssen, etwa Basis-URL, Testzugangsdaten und Fixture-IDs. Methode, Pfad, Struktur des Bodys und sicherheitsrelevante Flags müssen identisch bleiben.

Ein kleiner Shell-Test kann das Muster zeigen:

set -euo pipefail

project_id="docs-check-$RANDOM"
response=$(curl -sS -X POST "$API_URL/v1/projects" \
  -H "Authorization: Bearer $DOCS_TEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"id\":\"$project_id\",\"name\":\"Documentation check\"}")

printf '%s' "$response" | jq -e \
  --arg id "$project_id" \
  '.id == $id and .name == "Documentation check" and .archived == false'

Die erwartete Ausgabe von jq -e ist der JSON-Wert true; bei einer Abweichung endet der Prozess mit einem Fehler. Wichtig ist nicht die Shell-Syntax. Die Zusicherung hält fest, was der Text verspricht: Die API erstellt ein Projekt mit der angegebenen ID, bewahrt den Namen und archiviert es standardmäßig nicht.

Baue eine eigene Prüfung für die gerenderte Dokumentation. Wenn ein Markdown-Extractor einen mit bash markierten Block von der Seite holt, muss der Test genau diesen Block nach dem Ersetzen der freigegebenen Umgebungsvariablen ausführen. Erzeugst du Dokumentation aus einer OpenAPI-Beschreibung, teste das generierte Beispiel und nicht einen von Hand kopierten Verwandten.

Screenshot-Prüfungen bleiben für die Lesbarkeit sinnvoll. Verhalten können sie nicht beweisen. Ein Prüfer übersieht einen fehlenden Header erstaunlich oft, besonders wenn die Seite mehrere ähnliche Beispiele enthält. Maschinen werden nicht müde, ein Feld mit einem Fixture zu vergleichen.

Live-Dienstprüfungen müssen Standardwerte und Fehlerpfade abdecken

Die meisten gefährlichen API-Änderungen betreffen Standardwerte, Autorisierungsgrenzen und die Fehlerbehandlung. Happy-Path-Tests vermeiden alle drei Bereiche, weil sie leicht zu schreiben und leicht grün zu halten sind.

Teste die Fälle, in denen ein Agent ein Feld auslässt. Agenten bauen Nutzdaten häufig bedingt auf. Ein optionales Feld kann daher verschwinden, wenn eine vorherige Abfrage keinen Wert liefert. Entscheide für jeden dokumentierten optionalen Parameter, ob das Weglassen sicher ist, abgelehnt wird oder eine andere Bedeutung hat. Teste danach das dokumentierte Verhalten direkt.

Für eine Operation mit dem Feld dry_run solltest du in einer isolierten Umgebung mindestens diese Fälle ausführen:

1. dry_run: true liefert einen Plan und lässt das Fixture unverändert.
2. dry_run: false führt die beschriebene Änderung nur am benannten Fixture aus.
3. Das Weglassen von dry_run lehnt die Anfrage ab oder verwendet den dokumentierten Standardwert.
4. Ein Token mit unzureichendem Umfang schlägt fehl, bevor eine Änderung erfolgt.
5. Eine Wiederholung der dokumentierten Anfrage verhält sich wie in den Idempotenzhinweisen beschrieben.

Der dritte Fall findet eine häufige Ursache für versehentliche Schäden. Ein Serviceteam ändert einen Standardwert zugunsten interaktiver Nutzer, während die Dokumentation noch vom alten Wert ausgeht. Eine menschliche Oberfläche kann einen Bestätigungsdialog zeigen. Ein API-Client hat keinen solchen Dialog.

Auch Fehlerbeispiele brauchen Tests. In der Dokumentation steht oft «bei 429 wiederholen», ohne zu erklären, ob die Antwort Retry-After enthält, ob die Operation gefahrlos wiederholt werden kann oder ob ein Idempotenz-Token nötig ist. Diese Empfehlung kann aus einer kurzen Drosselung doppelte Rechnungen, Bereitstellungen oder Widerrufe machen.

Teste die genaue Fehleranweisung. Erzwinge den gedrosselten Zustand in einem Testdienst oder einer kontrollierten Umgebung. Prüfe, dass der dokumentierte Client den genannten Header liest, wie angegeben wartet und dieselbe Idempotenz-ID erneut sendet, sofern die API eine solche unterstützt. Kann der Dienst den Fehler nicht zuverlässig erzeugen, dokumentiere die Unsicherheit, statt ein selbstsicheres Rezept zu veröffentlichen.

OpenAPIs Schlüsselwort default erzeugt eine verwandte Falle. In JSON Schema und OpenAPI beschreibt ein deklarierter Standardwert häufig, was Tools annehmen oder anzeigen können. Er bewirkt nicht automatisch, dass jeder Server diesen Wert verwendet. Prüfe den bereitgestellten Dienst mit einem ausgelassenen Feld. Ein Schema-Standardwert und ein Server-Standardwert sind getrennte Aussagen, bis ein Test sie miteinander verbindet.

Zerstörerische Abläufe brauchen wegwerfbare Belege

Teste zerstörerische Beispiele nicht gegen ein gemeinsam genutztes Staging-Konto und nenne sie dann sicher. In gemeinsam genutzten Umgebungen sammeln sich alte Fixtures, manuelle Experimente und Zugangsdaten mit unklarem Zugriff. Irgendwann trifft ein Dokumentationstest das falsche Objekt oder ein Bereinigungsbefehl überschreitet seine vorgesehene Grenze.

Verwende einen dedizierten Testmandanten oder ein eigenes Konto mit Zugangsdaten, die nur die Testressourcen erreichen. Erstelle jedes Fixture mit einer eindeutigen Laufmarkierung. Suche es vor der Änderung anhand dieser Markierung. Prüfe nach dem Test den tatsächlichen Zustand, statt einfach anzunehmen, dass die API die behauptete Antwort umgesetzt hat.

Ein Löschbeispiel sollte den vollständigen Lebenszyklus zeigen:

create fixture: docs-delete-<run-id>
read fixture: confirm owner=test-suite and run_id=<run-id>
delete fixture: send the rendered documentation request
read fixture: expect the documented absence or tombstone state
list nearby fixtures: confirm unrelated fixtures remain

Die letzte Prüfung ist wichtig. Ein Löschtest, der nur bestätigt, dass das ausgewählte Objekt verschwunden ist, erkennt keinen zu weit gefassten Selektor. Ich habe Teams erlebt, die einen Sammelendpunkt akzeptierten, weil ihr einzelnes Fixture wie erwartet verschwand, obwohl der Endpunkt auch jede Ressource mit einem ähnlichen Präfix löschte. Der Test brauchte einen absichtlich ähnlichen Nachbarn, der erhalten bleiben sollte.

Lass die Dokumentation Agenten keine bequemen Selektoren wie latest, all, einen leeren Filter oder einen lesbaren Namen verwenden, wenn eine unveränderliche ID existiert. Solche Selektoren wirken in einem Tutorial freundlich und werden unsicher, wenn ein Agent das Rezept in einem ausgelasteten Konto ausführt. Wenn ein Vorgang wirklich einen breiten Selektor braucht, setze den Umfang in den Request-Body oder in die Befehlsargumente, wo ein Prüfer ihn sehen kann. Verstecke ihn nicht in einem Server-Standardwert.

Veröffentliche bei irreversiblen Operationen zunächst eine Vorabprüfung und lass das Beispiel deren Ergebnis verwenden. Rufe zuerst das Objekt ab, prüfe seine unveränderliche ID und den relevanten Zustand und führe danach die Änderung aus. Das erzeugt Reibung. Diese Reibung ist günstiger, als erklären zu müssen, warum ein Agent das Objekt mit einem zufällig gleichen Anzeigenamen gelöscht hat.

Tool-Tests müssen Bedeutung vergleichen, nicht nur Schemas

Schema-Validierung ist nötig, doch Schemas beschreiben meist die Form genauer als die Folgen. Ein Request-Body kann alle Typvorgaben erfüllen und trotzdem eine Aktion an die falsche Umgebung oder mit den falschen Berechtigungen richten.

Baue Zusicherungen rund um vier Fragen: Wen hat die Aktion betroffen? Welcher Zustand hat sich geändert? Welcher Zustand blieb unverändert? Welche Identität hat die Aktion autorisiert? Diese Fragen gelten für HTTP-APIs, SSH-Befehle und interne Tools.

Erfasse bei HTTP eine Anfrage-ID, sofern der Dienst eine liefert, und frage anschließend die resultierende Ressource oder den Audit-Eintrag in der Testumgebung ab. Vergleiche Anfrage-ID, Akteur, Ziel und Änderung. Führe SSH-Befehle auf einem wegwerfbaren Host aus, erfasse Exit-Status und Ausgabe und prüfe den Hostzustand anschließend mit einem separaten Befehl. Lass den Aktionsbefehl nicht seine eigene Arbeit bewerten.

Ein gutes Fixture enthält einen Kontrast. Wenn du einen Befehl zum Neustart eines Dienstes testest, erstelle einen weiteren Dienst, der weiterlaufen muss. Testest du eine auf ein Repository beschränkte Abfrage, füge ein zweites Repository hinzu, das dieselben Zugangsdaten sehen können, das die Anfrage aber nicht berühren darf. Ohne Kontrast kann eine zu weit reichende Aktion korrekt aussehen.

Hier missbrauchen viele Teams Vertragstests. Consumer-driven-Contract-Tools können bestätigen, dass ein Anbieter eine Anfrageform akzeptiert und erwartete Felder zurückgibt. Sie können nicht bestimmen, ob die Anfrage das richtige Produktionskonto auswählte, ob eine Option force eine neue Bedeutung erhielt oder ob ein Löschvorgang über das dokumentierte Objekt hinaus kaskadiert. Behalte den Vertragstest und ergänze einen Ergebnistest mit Fixtures, die ein Übergreifen sichtbar machen.

Auch eine Toolbeschreibung muss getestet werden. Wenn ein Tool environment anbietet, beschreibe production nicht als zulässigen Wert, solange ein Test nicht bestätigt, dass der Wert zum dokumentierten Host führt und den angegebenen Autorisierungspfad verwendet. Agenten nutzen Beschreibungen, um Argumente zu befüllen. Eine veraltete Beschreibung ist einfach die Prosa-Version eines veralteten API-Beispiels.

Ein Agent braucht Aktualitätsnachweise und einen sicheren Verweigerungspfad

Ein Agent sollte nicht annehmen, dass Dokumentation aktuell ist, nur weil sie in einem Repository oder einem internen Portal liegt. Gib ihm maschinenlesbare Verifikationsbelege, die an die geplante Operation gebunden sind.

Ein einfaches Manifest kann genügen:

{
  "operation": "POST /v1/exports",
  "documentation_source": "docs/api/exports.md#creating-an-export",
  "verified_in": "isolated-test-tenant",
  "verification_commit": "<commit-id>",
  "assertions": [
    "returns an export job",
    "omits archived fixtures when include_archived is false",
    "rejects a token without export scope"
  ],
  "review_required_when": ["production", "include_archived=true"]
}

Die Commit-ID ist für sich genommen kein Vertrauenssiegel. Sie ermöglicht einem Prüfer, die Dokumentation und die Testquelle zurückzuverfolgen, die den Nachweis erzeugt haben. Speichere eine Prüfzeit in deinen Build-Aufzeichnungen, wenn dein Release-Prozess eine Altersgrenze braucht, aber behaupte nicht, dass ein Zeitstempel altes Verhalten sicher macht. Eine Dienstbereitstellung kann den Test vom Vortag ungültig machen.

Die Entscheidungsregel des Agents sollte klar sein. Fehlt für die angeforderte Operation ein bestandener Verifikationsnachweis für die bereitgestellte Schnittstelle, muss er entweder eine nicht verändernde Vorabprüfung in einem freigegebenen Testkontext ausführen oder eine Person um die Freigabe der konkreten Aktion bitten. Er darf nicht auf Grundlage eines benachbarten Endpunkts improvisieren.

Trenne «unbekannt» von «sicher». Agenten füllen Lücken gern, weil der Abschluss einer Aufgabe positives Feedback bringt. Das Tool-Design muss Enthaltung als erfolgreiches Ergebnis behandeln, wenn Belege fehlen. Gib beispielsweise den Grund zurück: documentation example has no verified outcome test for this operation. Diese Meldung liefert dem Entwickler ein konkretes Reparaturziel statt einer vagen Verweigerung.

Versuche nicht, das Problem mit einer langen Richtliniendatei zu lösen, die riskante Formulierungen in jedem Dokument aufzählen will. Der Wortlaut verändert sich schneller als die Regeln. Binde eine konkrete Operation an einen konkreten Test und gib dem Agenten das Ergebnis.

Release-Gates funktionieren nur, wenn sie die irreführende Seite blockieren

Ein Dokumentationsprogramm scheitert, wenn es Berichte erzeugt, auf die niemand reagieren muss. Die Prüfung muss die Veröffentlichung blockieren oder zumindest den Agent-Zugriff auf das betroffene Beispiel sperren, sobald sich der Dienstvertrag ändert.

Verknüpfe die Prüfungen mit Änderungen an API-Spezifikation, Routen-Handlern, Authentifizierungs-Middleware, SDK-Request-Buildern und Dokumentationsquellen. Eine Änderung in einem dieser Bereiche sollte die relevanten Beispieltests ausführen. Schlägt ein Test fehl, hat das Team drei ehrliche Möglichkeiten: das alte Verhalten wiederherstellen, Dokumentation und Tests an das neue Verhalten anpassen oder die Operation für Agenten sperren, bis die Verifikation erfolgreich ist.

Manuelle Prüfung bleibt für Ermessensentscheidungen nützlich, ist aber allein die falsche Empfehlung. Sie ist beliebt, weil sie günstig wirkt und einen schnellen Veröffentlichungsprozess erhält. Gleichzeitig soll ein Prüfer Dienst, Zugangsdaten, Standardwerte und Zustandsübergänge aus Text gedanklich simulieren. Das gelingt Menschen bei regelmäßigen Releases nicht zuverlässig.

Mache Fehler verständlich. Ein nützlicher Bericht nennt Seite, Codeblock, Operation, Test-Fixture, beobachtete Antwort und verletzte Zusicherung. «Dokumentationsintegration fehlgeschlagen» erzeugt eine Schnitzeljagd. «exports.md Zeile 42 sagt, dass archivierte Datensätze ausgeschlossen werden; das Exportartefakt enthielt Fixture archived-run-817» gibt dem Verantwortlichen eine direkte Reparatur vor.

Lockere einen Test nicht nur deshalb, weil eine Dienständerung ihn unbequem gemacht hat. Entscheide zuerst, ob das alte Versprechen nützlich war. Falls ja, stelle es wieder her oder nenne die neue Einschränkung deutlich. War es unsicher, entferne das Beispiel, statt es mit einem weicheren Satz zu erhalten. Ein Agent folgt normalerweise dem verbleibenden Befehl.

Versionierte Dokumentation braucht dieselbe Disziplin. Eine Seite für eine ältere API-Version kann eine frühere Bereitstellung korrekt beschreiben und trotzdem einen Agenten irreführen, der auf die aktuelle Basis-URL zeigt. Setze die Version in Endpunktpfad, Server-URL oder Tool-Metadaten, damit der Agent sie an die Anfrage binden kann. Eine Überschrift «v1» irgendwo am Anfang ist ein schwacher Nachweis.

Autorisierungsgrenzen begrenzen den Schaden, reparieren aber keine falschen Anweisungen

Freigaben und isolierte Zugangsdaten bleiben wichtig, weil Dokumentationsprüfungen Fehler übersehen werden. Sie verringern den Schaden, wenn ein Agent die falsche Operation auswählt. Eine veraltete Anweisung machen sie nicht korrekt.

Halte die beiden Aufgaben getrennt. Dokumentationsprüfung fragt: «Beschreibt dieses Beispiel den Live-Dienst und seine Folgen?» Aktionsautorisierung fragt: «Darf dieser Agent diesen Aufruf jetzt ausführen?» Werden beide Aufgaben vermischt, entsteht Verwirrung. Ein Nutzer kann einen Aufruf freigeben, weil der Agent sagt, er werde ein Projekt exportieren, während das veraltete Beispiel tatsächlich jedes für die Zugangsdaten sichtbare Projekt exportiert.

Für agentengesteuerte HTTP- und SSH-Aktionen hält Sallyport Zugangsdaten vom Agenten fern und kann verlangen, dass eine Person eine Sitzung oder die Nutzung einzelner Zugangsdaten autorisiert. Das ist eine nützliche letzte Grenze, wenn die Dokumentationsprüfung keine vertrauenswürdigen Belege findet oder eine Aktion Folgen hat, die eine menschliche Prüfung verdienen.

Der Freigabebildschirm muss Operation, Ziel und Umfang so anzeigen, dass eine Person sie beurteilen kann. «POST /v1/exports» reicht nicht, wenn der Request-Body include_archived=true oder einen kontoweiten Selektor enthält. Kann deine Autorisierungsschicht den relevanten Umfang nicht zeigen, verkleinere die Tool-Schnittstelle, bis sie es kann.

Audit-Aufzeichnungen liefern dann das Material zur Verbesserung der Tests. Wenn eine Person einen Lauf widerruft oder eine Aktion hinterfragt, prüfe die genaue Anfrage, die vom Agent zitierte Dokumentationsquelle und die vorhandenen Verifikationsbelege. Betrachte die Prüfung nicht als Schuldzuweisung. Nutze sie, um das fehlende Fixture, die fehlende Zusicherung oder die fehlende Verweigerungsbedingung hinzuzufügen.

Beginne mit dem Beispiel, das am ehesten bereut wird

Beginne nicht mit der saubersten GET-Anfrage der Referenz. Beginne mit dem Beispiel, das löschen, veröffentlichen, rotieren, Berechtigungen vergeben, abrechnen oder einen Produktions-Host erreichen kann. Gib ihm ein isoliertes Fixture, führe den exakt gerenderten Befehl aus und prüfe sowohl die beabsichtigte Änderung als auch die nahe liegende Änderung, die nicht passieren darf.

Verbinde diesen Test anschließend mit der Dokumentationsquelle und mache einen Fehler vor der Veröffentlichung oder Agent-Nutzung sichtbar. Die Arbeit ist weniger glamourös als das Schreiben einer neuen Toolbeschreibung, entfernt aber eine gefährliche Annahme: dass eine Seite sicher ist, weil sie einst geprüft wurde.

Ein Live-Dienst verändert sich. Seine Dokumentation ändert sich langsamer, solange du beide nicht in einem Test zusammenführst. Mache dieses Treffen zu einem Teil des Releases, bevor ein Agent aus einem alten Satz eine Aktion macht.