Die Goldene Regel: CLI erzeugt Fakten, Modell verarbeitet Fakten

Dies ist eine 10-teilige Serie, die zeigt, wie Apidog Apidog CLI, ein Befehlszeilentool für API-Tests und API-Lebenszyklusmanagement, entwickelt hat. Lesen Sie die Beiträge der Reihe nach oder springen Sie zu einem beliebigen Post, der Sie interessiert:

Lassen Sie das Modell nicht alle Regeln auswendig lernen – lassen Sie Regeln an den richtigen Stellen ausführen. cli-schema validate verwandelt Schema von Wissen in ein Qualitäts-Gateway.

Das Kernprinzip: Regeln an den richtigen Stellen ausführen.

Wir haben aus unserer Erfahrung ein Kernprinzip abgeleitet:

Lassen Sie das Modell nicht alle Regeln auswendig lernen. Lassen Sie Regeln an den richtigen Stellen ausführen.

Dies ähnelt einer Lektion aus der Agentenbewertung:

In Apidog CLI + SKILL:

Lassen Sie CLI die Struktur validieren. Lassen Sie Agenten den Inhalt generieren.

Das Problem mit dem Modellgedächtnis

Wenn ein KI-Agent beim Erstellen oder Aktualisieren von Apidog-Ressourcen hilft, ist der riskante Teil nicht nur das Generieren von Inhalten.

Der riskante Teil ist das Schreiben von generierten Inhalten in ein reales Projekt ohne ausreichende Struktur oder Überprüfung.

Apidog-Ressourcen sind strukturiert. Überlegen Sie, was ein Testfall oder ein Testszenario beinhaltet:

Wenn ein Agent die Struktur errät:

• Falscher Feldname → Fehlerhafter Schreibvorgang
• Ungültiger Enum-Wert → Server-Ablehnung
• Fehlendes Pflichtfeld → Unvollständige Ressource
• Falscher Typ → Probleme bei der UI-Anzeige
• Falsche Verschachtelung → Tests verhalten sich nicht wie erwartet

cli-schema validate: Das Qualitäts-Gateway

Die direkteste Verkörperung unseres Prinzips ist cli-schema validate.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

Wenn ein Agent ein Testszenario schreiben oder aktualisieren möchte, ist das Generieren komplexer Schrittstrukturen durch KI sehr fehleranfällig.

Der Befehl validate:

• Bestätigt Feldnamen
• Überprüft die strukturelle Gültigkeit
• Verifiziert die Wirksamkeit von Enum-Werten
• Validiert Typeinschränkungen

All dies, bevor die Schreibanforderung initiiert wird.

Häufige Fehler, die cli-schema abfängt

Hier sind reale Beispiele für Fehler, die Agenten häufig machen – und die cli-schema validate abfängt:

Diese sind nicht theoretisch. Wir haben sie durch reale Agenten-Interaktionen entdeckt.

Jeder Fehler würde verursachen:

• Eine fehlgeschlagene Schreibanfrage
• Eine API-Fehlerantwort
• Verwirrung des Agenten darüber, was schiefgelaufen ist
• Mehrere Wiederholungsversuche
• Token-Verschwendung bei wiederholten Aufrufen

Mit cli-schema validate werden diese Fehler lokal, vor dem Netzwerkaufruf, abgefangen.

Die Designphilosophie

Betrachten wir die Alternativen:

Alternative 1: Regeln in den Prompt schreiben

Wenn wir alle Feldregeln in den Prompt des Agenten schreiben würden:

• Jeder Feldname dokumentiert
• Jeder Enum-Wert aufgelistet
• Jede Typeinschränkung erklärt
• Jede verschachtelte Struktur beschrieben

Ergebnis: Massive Kontextlast.

Ein umfassendes Testszenario-Schema könnte leicht 5.000+ Tokens an Beschreibung erfordern. Das ist Kontext, den das Modell für jede Aufgabe mitführen müsste, selbst wenn die meisten Regeln nicht relevant sind.

Alternative 2: Sich auf das Modellgedächtnis verlassen

Wenn wir uns darauf verlassen, dass das Modell die korrekte Struktur "kennt":

• Modell auf einige API-Muster trainiert
• Aber nicht speziell auf Apidog-Schemas
• Feldnamen variieren zwischen Produkten
• Enum-Werte sind produktspezifisch

Ergebnis: Hohe Fehlerraten.

Das Modell hat keine perfekte Erinnerung an Apidog-spezifische Konventionen. Es wird raten – und die Vermutungen werden falsch sein.

Besserer Ansatz: Lokal validieren

Lassen Sie den Agenten Entwürfe generieren. Lassen Sie CLI die Validierung vor dem Schreiben ausführen.

# Agent generiert JSON
# (Agent muss nicht alle Regeln auswendig lernen)

# CLI validiert
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLI gibt spezifische Fehler aus, falls vorhanden
# Agent passt sich basierend auf Fehlern an

# Nur gültige Schreibvorgänge werden fortgesetzt
apidog test-case create --project <projectId> --file ./test-case-create.json

Schema-Transformation

cli-schema validate transformiert, was Schema bedeutet:

Probleme werden nicht in sinnlosen Hin- und Her-Netzwerkanfragen verbraucht.

Qualitätsprüfungen werden durch lokale Befehle abgeschlossen.

Praktisches Beispiel

Gehen wir einen realen Workflow durch:

# Agent liest Endpunkt
apidog endpoint get <endpointId> --project <projectId>

# Agent generiert Testfall-JSON
# (Erstellt ./test-case-create.json)

# Validierung vor dem Schreiben
apidog cli-schema validate test-case-create --file ./test-case-create.json

Wenn die Validierung bestanden wird:

apidog test-case create --project <projectId> --file ./test-case-create.json

Wenn die Validierung fehlschlägt:

Error: Feld "assertions[0].comparator" hat einen ungültigen Wert "contains"
Gültige Werte: equal, not_equal, greater, less, include, not_include, exists, not_exists

Error: Feld "extractors[0].type" hat einen ungültigen Wert "global"
Gültige Werte: globals, environment, collection, local

Vorschlag: Beheben Sie diese Felder und validieren Sie erneut, bevor Sie schreiben.

Der Agent:

1. Liest die spezifischen Fehler
2. Versteht genau, was falsch ist
3. Passt die JSON-Datei an
4. Führt die Validierung erneut aus
5. Fährt nur fort, wenn gültig

Keine fehlgeschlagenen Schreibvorgänge. Keine verwirrten Wiederholungsversuche. Keine verschwendeten Tokens.

Die größere Lektion

Dieses Prinzip geht über die Validierung hinaus.

Deterministische Regeln → Ingenieursystem

Semantische Beurteilung → Agent

Was kommt als Nächstes?

Nachdem wir das Validierungsprinzip etabliert haben, stellt sich die nächste Frage:

Wie leitet CLI den Agenten nach der Validierung zum nächsten Schritt?

In Teil 4, agentHints: CLIs beibringen, mit Agenten zu sprechen, werden wir untersuchen, wie strukturierte Ausgaben mit Vorschlägen für den nächsten Schritt CLI von einem Befehlsausführer in einen Workflow-Navigator verwandeln.

Wichtigste Erkenntnisse

• Kernprinzip: Regeln gehören in die Ausführung, nicht in den Kontext
• cli-schema validate ist das Qualitäts-Gateway vor dem Schreiben
• Häufige Fehler: falsche Feldnamen, ungültige Enums, falsche Typen
• Die Validierung fängt Fehler lokal ab und spart Netzwerk-Roundtrips
• Schema wandelt sich von "Wissen zum Auswendiglernen" zu "Gateway zum Passieren"
• Deterministische Regeln → Engineering; semantische Beurteilung → Agent

Laden Sie Apidog herunter, um APIs in einem einzigen Arbeitsbereich zu entwerfen, zu mocken, zu testen und zu dokumentieren. Erfahren Sie mehr über Apidog CLI für Befehlszeilen-API-Tests, CI-Automatisierung und KI-Agenten-Workflows.