Warum --help für Agenten nicht reicht
Stoppt eure CLI bei --help, raten Agenten den Rest. Sie sehen Befehlsnamen — init, push, publish — aber nicht den operativen Pfad für „Dokumentation für dieses Projekt anlegen und aktuell halten“.
Klassische Help-Ausgabe ist für schnelles menschliches Scannen gebaut, nicht für mehrstufige Maschinenausführung. Folge: falsche Flag-Kombinationen, Retries, Token-Verbrennung, Vertrauensverlust beim Endkunden.
Steve Baka empfiehlt Agentur-Teams mit SaaS-CLIs: zweite Schicht — Man-Dateien im Paket, zur Laufzeit abfragbar, versionsgebunden.
Das Minimal-Muster: Help, Bundle, cli-docs
1. `--help` bleibt kurz — Discovery-Einstieg, verweist auf tiefere Docs.
2. Docs im CLI-Paket unter man/ — offline, versioniert mit der installierten CLI, unabhängig von API-Uptime.
3. Drei explizite Befehle: cli-docs list, cli-docs read --path <topic>, cli-docs search "query" — plus Alias man <topic>.
Inspiration: Rewrite Your CLI for AI Agents (öffnet in neuem Tab) und Agent-Friendly CLIs (öffnet in neuem Tab) — einfache Oberfläche, zur Laufzeit abfragbare Tiefe.
Deterministisches Matching statt Raten
Suche gewichtet Titel, Summary, Pfad, Body — stabil sortiert nach Score, dann Pfad. Gleiche Query → gleiche Reihenfolge — wichtig für reproduzierbare Agent-Läufe und Debugging.
MVP bewusst simpel: Keyword-Gewichtung statt embedding-basiertem Rauschen. Agenten brauchen Vorhersagbarkeit, nicht cleverste Semantik in v1.
Ausgabe maschinenfreundlich halten — stabile Struktur, keine interaktiven Pager-Zwänge in Agent-Pipelines.
Infrastruktur, nicht Docs-Nice-to-have
Ohne Man-Schicht sehen Nutzer: inkonsistente Automatisierung, falsche „nicht unterstützt“-Meldungen, fragile CI-Skripte. Mit Man-Schicht: Agent führt Workflows end-to-end — besonders relevant für Docs-as-Product und DevTools-Kunden in DACH.
MCP ist nicht immer nötig — lokale, versionierte CLI-Docs decken viele Coding-Agent-Fälle ab, bevor ihr Remote-MCP betreibt.
Referenz-Implementierung: DocsAlot CLI (öffnet in neuem Tab).
Checkliste für Agentur-Delivery
□ Kurzes --help mit Verweis auf Man □ man/ im Release-Artefakt □ list/read/search (+ Alias) □ deterministische Suche □ Smoke-Test: Agent löst Standard-Task nur über CLI-Docs.
Langfristig: Man-Inhalt aus demselben Repo wie Web-Docs generieren — eine Wahrheitsquelle, zwei Kanäle.
Langweilig und zuverlässig schlägt clever und brüchig — besonders wenn KI-Beratung Automatisierung verspricht.
