Du hast ein Kommandozeilen-Tool entwickelt, das die tägliche Arbeit erleichtert. Jemand schlägt vor, die Eingabe für KI-Agenten zu optimieren – alles in einen einzigen --json-Block packen, weil Maschinen strukturierte Daten lieben. Klingt plausibel. Waldek Mastykarz, Principal Developer Advocate bei Microsoft, hat diese Annahme getestet. Er wollte wissen, ob der Wechsel von klassischen Argumenten zu JSON wirklich Vorteile bringt. Das Messergebnis ist eindeutig – und überrascht viele.
Der Ansatz hinter JSON
Die Argumentation der Befürworter ist nachvollziehbar: KI-Agenten denken in hierarchischen Strukturen. JSON bildet tiefe Verschachtelungen natürlich ab, während flache Argumente mit mehrfach auftretenden Flags wie --service-name schnell mehrdeutig werden. Der Agent muss mühsam lernen, welcher Wert zu welchem Block gehört. Ein einzelner JSON-Payload verspricht klare Hierarchien: Jedes Service-Objekt steht für sich, Ressourcen sind logisch gruppiert – kein Ratespiel. So elegant die Theorie klingt, die Praxis zeigt etwas anderes.
Waldek Mastykarz hat ein Experiment entworfen, um die Behauptung zu prüfen. Er baute ein synthetisches CLI namens podctl, das ein komplexes Multi-Service-Deployment erzeugt – mit zwei Diensten, drei Verschachtelungsebenen, Arrays, gemischten Typen und Querverweisen. Insgesamt über 30 Einzelwerte. Eine Version des CLIs akzeptiert nur traditionelle Argumente (Flags), die andere nur einen --json-Payload. Beide nutzen denselben Validierungs-Backend und normalisieren zur gleichen kanonischen Struktur. Der Agent kennt das Tool nicht und muss es über die Hilfe entdecken. Fünf gängige Modelle wurden jeweils fünfmal pro Eingabemodus getestet – von Claude Haiku 4.5 bis GPT-5.3-Codex, mit GitHub Copilot Chat als Rahmen.
Die Ergebnisse: Args gewinnen durchgehend
Jedes Modell erreichte mit den klassischen Argumenten eine perfekte Korrektheit in allen fünf Läufen. Selbst das kleinste Modell, Claude Haiku 4.5, erzeugte zuverlässig korrekte Deployments. Bei der JSON-Variante sah es anders aus: Die drei stärksten Modelle hielten mit 5/5 mit, aber die beiden kleineren Modelle fielen ab. Haiku 4.5 schaffte nur 2 von 5 korrekten Aufgaben, MAI-Code-1-Flash immerhin 3 von 5. Argumente begrenzen den Eingaberaum so stark, dass auch schwächere Modelle konsistent korrekte Ausgaben liefern. JSON zwingt das Modell, seine eigene Struktur zu verwalten – eine Fähigkeit, die nicht jedes Modell beherrscht. Der Unterschied liegt in den Randbedingungen beim Generieren.
Noch deutlicher fällt der Kostenvergleich aus. Entwickler bezahlen für Token, nicht für Versuche. Waldek Mastykarz hat den Token-Verbrauch pro Aufgabe detailliert aufgeschlüsselt – Input, gecachte und Output-Token – und mit den Preisen der GitHub-Modelle multipliziert. Das Ergebnis: JSON-Modus kostete 4- bis 11-mal mehr pro Aufgabe als der Args-Modus – je nach Modell. Der rohe Token-Abstand war noch größer (4- bis 14-mal), aber Caching mildert die Wirkung etwas. Caching hilft nicht bei den Output-Token. Bei JSON führt das zu vielen Neuversuchen. Liest das CLI die JSON-Struktur nicht, analysiert der Agent den Fehler, baut einen neuen Payload und startet einen neuen Versuch. Diese Versuche werden kreativ: Piping durch Variablen, Schreiben in temporäre Dateien, verschiedene Escaping-Strategien. All das sind Output-Token – die teuerste Kategorie.
Das Problem mit Shell-Escaping
Die reinen Tokenkosten sind nicht alles. Ein oft übersehener Faktor beim JSON-Umstieg ist das Shell-Escaping. Wenn der Agent einen JSON-Payload auf der Kommandozeile übergibt, muss er die Anführungszeichen für die Shell maskieren. Verschiedene Shells haben unterschiedliche Regeln für verschachtelte Strings, keine ist trivial. Die Modelle produzierten regelmäßig valides JSON, das dann an der Shell scheiterte: doppelte Anführungszeichen in einfachen Anführungszeichen, Escaping, das die Shell anders interpretierte als beabsichtigt. Die Fehler von Haiku 4.5 bei JSON zeigen das Problem besonders deutlich: Drei von fünf Aufrufen erreichten nie eine erfolgreiche Ausführung. Der Agent erzeugte korrekte JSON-Inhalte, kam aber nicht durch die Shell. Er versuchte Base64-Kodierung, Piping, Here-Strings, cmd.exe-Durchleitung – alles vergebens. Die Token wurden verbrannt, ohne dass je ein gültiger Befehl zustande kam.
Um den Einfluss der Shell zu prüfen, führte Waldek Mastykarz denselben Test mit Claude Sonnet 4.6 auf macOS durch, wo standardmäßig Bash läuft. Auf PowerShell betrug der Kostenunterschied zwischen Args und JSON das 9-Fache. Auf Bash schrumpfte er auf das 1,5-Fache. Gleiches Modell, gleicher Payload, gleiche Korrektheit. Der Unterschied lag allein in der Art, wie jede Shell mit zitierten JSON-Strings umgeht. Args verhielten sich stabil über beide Shells hinweg: 0,05 $ auf PowerShell vs. 0,07 $ auf Bash. JSON führt eine Abhängigkeit vom Shell-Zitierverhalten ein, die je nach Umgebung stark variiert. Argumente tun das nicht.
Warum Einschränkungen dem Agenten helfen
Die Daten zeigen einen kognitiven Effekt von Einschränkungen. Bei Args legt der Hilfetext fest, welche Eingaben gültig sind. Jede Option hat einen Namen und einen Typ, manchmal eine Aufzählung erlaubter Werte. Das Modell muss von der Aufgabenbeschreibung auf konkrete Optionsnamen und Werte abbilden. Bei JSON erhält das Modell ein Schema (oder leitet es aus der Hilfe ab) und muss ein freies Objekt konstruieren, das diesem Schema genügt. Die Syntax muss gültig sein, die Verschachtelung korrekt, die Feldnamen und Typen müssen passen – und das Ganze muss das Shell-Escaping überleben. Jeder Punkt ist eine Fehlerquelle. Args vermeiden diese Fehlerquellen von vornherein. Stärkere Modelle lösen die JSON-Aufgabe irgendwann, aber mit Aufwand: Sie leisten sich Shell-Fehler, die sie dann reparieren müssen. Diese Reparatur kostet 4- bis 11-mal mehr als der Args-Pfad, selbst wenn die endgültige Korrektheit identisch ist. Kleinere Modelle scheitern an denselben Hürden und können sie nicht überwinden – dort sinkt die Korrektheit drastisch.
Die Einschränkung des gültigen Eingaberaums gleicht Modellschwächen aus. Das Modell muss kein korrekt verschachteltes JSON erzeugen, weil es gar kein JSON gibt. Es muss keine Shell-Zitierung beherrschen, weil die Argumente ohne Zitierung auskommen. Der kognitive Aufwand sinkt auf das Wesentliche: die Zuordnung von Werten zu Parametern. Selbst die kleinsten getesteten Modelle lösen das zuverlässig.
Was das für dein CLI bedeutet
Wenn du ein CLI baust, das auch von KI-Agenten verwendet werden soll, weisen die Daten in eine klare Richtung: Ersetze deine Argumente nicht durch einen --json-Payload. Behalte die klassischen Args. Sie funktionieren über das gesamte Modellspektrum hinweg, haben keine umgebungsabhängigen Fehlermodi und kosten weniger Token – und damit weniger Geld. Du darfst zusätzlich eine --json-Option anbieten, etwa für programmatische Batch-Aufrufe oder manuelle Nutzung. Aber entferne die Args nicht zugunsten von JSON, und erwarte nicht, dass JSON die Agentenerfahrung verbessert. In diesem Experiment hat JSON die Korrektheit nie erhöht und die Kosten immer gesteigert.
Die intuitive Annahme, dass JSON die Arbeit von Agenten erleichtert, ist auf dem Papier nachvollziehbar. In der Realität – mit tatsächlichen Modellen, die in tatsächlichen Shells auf tatsächlichen Betriebssystemen laufen – hält sie nicht stand. Args sind eingeschränkt und vorhersagbar über Shells hinweg. JSON ist ausdrucksstark, aber zerbrechlich. Für den agentengesteuerten CLI-Einsatz gewinnt das Eingeschränkte.
Waldek Mastykarz gibt eine praktische Empfehlung: Bevor du eine solche Änderung vornimmst, miss nach. Wähle ein Szenario, definiere Bewertungskriterien, wähle das für deine Zielgruppe relevante Modell und Betriebssystem, und führe ein paar Durchläufe mit beiden Ansätzen durch. Nach einem Tag hast du eine Antwort, ohne etwas umschreiben zu müssen, das du gar nicht umschreiben musstest. Die Lektion: Plausible Annahmen und gemessene Ergebnisse sind zwei verschiedene Dinge. Wenn sie auseinanderklaffen, haben die Ergebnisse recht.
Du musst dein bewährtes CLI nicht für Agenten umkrempeln. Es ist gut genug. Wenn du Zweifel hast, mach den Test. Die Antwort wird dich beruhigen – und dein Budget freut sich auch.
Quelle: developer.microsoft.com
