Publishing mit Claude Code und Codex

Diesen Beitrag anhören (13 Min.)

422 Unprocessable Entity
unknown docs version: v3

Diese Fehlermeldung ist für einen Agenten hilfreicher als eine rote Markierung in einem Formular. Sie benennt die verletzte Regel, erscheint im selben Kanal wie der Upload und kann in den nächsten Arbeitsschritt einfließen. Claude Code oder Codex muss keinen Browser öffnen, keinen Dialog interpretieren und keinen Entwurf aus einem proprietären Editor kopieren. Der Agent korrigiert die Datei oder stoppt mit einem prüfbaren Befund.

Teil 2 der Serie „Contentkit – Publishing für Maschinen“.

Contentkit hat keinen eigenen MCP-Server für Claude Code oder Codex. Das ist keine fehlende Voraussetzung. Beide Werkzeuge können Dateien lesen und schreiben, Befehle ausführen und eine HTTP-API bedienen. Genau darauf ist Contentkit ausgelegt. Wo eine Organisation MCP als einheitliche Schnittstelle verwendet, kann ein allgemeiner Adapter den HTTP-Aufruf kapseln. Der eigentliche Vertrag bleibt die Contentkit-API und nicht das Verhalten eines bestimmten Agenten.

Der Agent arbeitet im Repository

Ein belastbarer Ablauf beginnt nicht mit einem Prompt in einer CMS-Oberfläche, sondern mit den vorhandenen Quellen. Für eine Produktdokumentation können das die OpenAPI-Datei, der Quellcode, vorherige Release Notes, bestehende Markdown-Seiten und ein Satz fachlicher Regeln sein. Der Agent bearbeitet dieselben Dateien, die auch ein Entwickler im Review sehen würde.

Ein möglicher Auftrag an Claude Code oder Codex lautet nicht „aktualisiere die Website“, sondern zerlegt die Wirkung:

Ermittle die öffentlich sichtbaren API-Änderungen seit dem letzten Tag.
Aktualisiere nur Seiten, deren Aussagen sich aus Spezifikation oder Tests belegen lassen.
Erzeuge neue Markdown-Revisionen und baue eine Vorschau.
Veröffentliche erst, wenn Vertrags-, Link- und Sichtbarkeitsprüfungen erfolgreich sind.

Der Auftrag benennt Quellen, Grenzen und den gewünschten Nachweis. Welches Modell ihn ausführt, ist zweitrangig. Wichtig ist, dass der technische Pfad keine stillen Seiteneffekte enthält.

sequenceDiagram
    participant S as Quellcode und Spezifikation
    participant A as Claude Code oder Codex
    participant C as Contentkit API
    participant T as Prüfschritte
    participant W as Website
    A->>S: Änderungen und Belege lesen
    A->>A: Markdown aktualisieren
    A->>C: Revisionen hochladen
    C-->>A: IDs oder 422-Fehler
    A->>C: Vorschau anfordern
    C-->>T: vollständigen Stand bereitstellen
    T-->>A: Prüfergebnis
    A->>C: autorisierten Release auslösen
    C-->>W: Zeiger atomar umsetzen

Berechtigungen sind Teil des Auftrags

Ein Agent sollte nur die Rechte bekommen, die sein Arbeitsschritt benötigt. Contentkit unterscheidet unter anderem site:admin, content:read, content:write und release:write. Der administrative Schlüssel darf Websites und weitere Schlüssel verwalten, kann aber ohne zusätzliche Rechte keine Inhalte veröffentlichen. Ein Publishing-Schlüssel kann Inhalt und Releases bearbeiten, muss aber keine Website-Verwaltung dürfen.

Für die lokale Agentenumgebung werden die Schlüssel nicht in die Anweisung geschrieben und nicht im Repository abgelegt. Sie kommen aus dem Secret Store der Laufzeit:

export CONTENTKIT_URL="https://contentkit-api.example.com"
export CONTENTKIT_PUBLISH_API_KEY="ck_..."
export CONTENTKIT_SITE="product-docs"

Ein Rechercheagent benötigt häufig nur content:read. Ein Schreibagent bekommt content:write, aber zunächst kein release:write. Der Freigabeschritt kann in einem getrennten Lauf mit einem anderen Schlüssel stattfinden. Das ist besonders dann sinnvoll, wenn der Agent aus nicht vertrauenswürdigen Tickets oder eingereichten Dokumenten liest. Ein eingeschleuster Befehl kann nicht mehr Wirkung entfalten als der verwendete Schlüssel zulässt.

Vom Unterschied zur Revision

Nehmen wir ein reales Muster aus der Produktentwicklung: Version 2.4 ergänzt einen optionalen Parameter, benennt zwei Fehlercodes um und nimmt einen alten Endpunkt aus der Empfehlung. Anwender brauchen nicht nur eine neue Referenz. Sie brauchen eine Migrationsanleitung, ein Changelog und einen Hinweis in der Betriebsdokumentation.

Der Agent beginnt mit einem maschinenlesbaren Unterschied, etwa zwischen zwei OpenAPI-Ständen. Dann sucht er die betroffenen Aussagen im Markdown-Bestand. Seine Änderungen bleiben normale Dateien. Ein Review zeigt daher nicht „die Seite sieht anders aus“, sondern die genaue Textänderung.

git diff -- docs/api docs/migrations changelog
rg -n "/v1/legacy-orders|ORDER_NOT_FOUND" docs changelog

Vor dem Upload kann der Agent lokale Regeln prüfen: erlaubte Frontmatter-Felder, erforderliche Überschriften, interne Links und erwähnte Endpunkte. Contentkit führt beim Schreiben weitere Prüfungen durch. Bei hierarchischer Dokumentation werden beispielsweise unbekannte Versionskennungen, fehlende Elternseiten, Zyklen, doppelte docKey-Werte und kollidierende URLs abgelehnt.

Dieser doppelte Boden spart Zeit. Billige lokale Prüfungen fangen offensichtliche Fehler ab. Die Contentkit-Validierung entscheidet über den tatsächlichen Vertrag des Zielsystems. Ein Agent muss die Regeln nicht aus einer Oberfläche erraten.

Vorschau ist eine eigene Systemgrenze

Die Vorschau überlagert die ausgewählten Revisionen auf dem derzeit veröffentlichten Stand. Contentkit baut daraus einen vollständigen statischen Stand und liefert einen zufälligen, ablaufenden Zugriff. Suchmaschinen erhalten noindex, der Browser darf die Antwort nicht öffentlich zwischenspeichern.

curl -X POST "$CONTENTKIT_URL/v1/sites/$SITE/previews" \
  -H "Authorization: Bearer $CONTENTKIT_PUBLISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revision_ids": ["rev-reference", "rev-migration", "rev-changelog"],
    "expires_in": 3600,
    "reason": "verify version 2.4 documentation"
  }'

Die Vorschau ist mehr als eine optische Kontrolle. Agenten können gegen sie dieselben Prüfungen ausführen, die später für Anwender zählen:

Liefert jede neue Seite den erwarteten HTTP-Status?
Zeigen interne Links auf existierende Routen?
Enthält die aktuelle Version die neuen Seiten, während archivierte Versionen unverändert bleiben?
Bleibt eine geschützte Kundenanleitung aus Sitemap, öffentlicher Suche und llms-full.txt verschwunden?

Gerade die letzte Prüfung zeigt den Vorteil eines vollständigen Standes. Sichtbarkeit ist nicht nur eine Eigenschaft der einzelnen Seite. Navigation, Suchindex, Feed, Sitemap und maschinenlesbare Ausgaben müssen dieselbe Entscheidung widerspiegeln. Contentkit leitet sie während des Builds aus einem gemeinsamen Stand ab.

Automatische und menschliche Freigabe

Maschine-zu-Maschine bedeutet nicht, dass jede Änderung ohne Zustimmung eines Menschen veröffentlicht werden muss. Es bedeutet, dass die technische Strecke keine manuelle Bedienung voraussetzt. Wo die Organisation eine Freigabe verlangt, kann ein Mensch die Vorschau beurteilen und einen bereits vorbereiteten Lauf bestätigen. Wo Datenquelle und Prüfungen ausreichend verbindlich sind, kann eine Policy den Release automatisch erlauben.

Ein wöchentlicher Statusbericht ist ein gutes Beispiel für eine weitgehend automatische Strecke. Die Zahlen stammen aus signierten Exporten, die Tabellen werden gegen Summenregeln geprüft, der Veröffentlichungszeitpunkt ist fest. Eine neue Datenschutzseite verlangt dagegen wahrscheinlich eine juristische Freigabe. Beide Fälle nutzen dieselben Revisionen, Vorschauen und Releases; nur die Freigaberegel unterscheidet sich.

Für Claude Code und Codex sollte diese Regel außerhalb des freien Modelltextes liegen. Der Agent kann einen Vorschlag machen und Prüfergebnisse sammeln. Ob release:write verfügbar wird, entscheidet ein Workflow, eine CI-Umgebung oder ein ausdrücklich autorisierter Lauf.

Fehler sind Ergebnisse, keine Dialoge

Maschinenorientierte Systeme werden nicht dadurch gut, dass sie nie scheitern. Sie werden gut, wenn ein Fehlschlag eindeutig und wiederholbar ist. Contentkit unterscheidet etwa zwischen einem unbekannten Schlüssel (401), einem gültigen Schlüssel mit unzureichendem Recht (403) und einer inhaltlich ungültigen Anfrage (422). Ein Agent kann deshalb unterschiedlich reagieren.

Bei 401 sollte er den Schlüssel nicht verändern oder neu erraten, sondern den Lauf stoppen und die Secret-Konfiguration melden. Bei 403 nennt die Antwort den fehlenden Scope; die Lösung ist eine bewusste Berechtigungsentscheidung. Bei 422 kann der Agent die konkrete Datei anhand der Vertragsverletzung korrigieren und eine neue Revision erzeugen.

type PublishResult =
  | { status: "accepted"; revisionId: string }
  | { status: "invalid"; details: string[] }
  | { status: "forbidden"; requiredScope: string }
  | { status: "failed"; requestId: string };

Eine solche Einordnung verhindert hektische Wiederholungen. Nicht jeder Fehler ist vorübergehend. Ein Agent, der eine fachliche Ablehnung einfach fünfmal sendet, produziert Last und kein besseres Ergebnis.

Der öffentliche Stand bleibt ganz

Nach erfolgreicher Prüfung erzeugt Contentkit einen vollständigen Release unter einem neuen, unveränderlichen Speicherpräfix. Erst danach setzt eine Datenbanktransaktion den aktiven Zeiger und die veröffentlichten Revisionen gemeinsam um. Ein kaputter Build kann den bisherigen Stand daher nicht teilweise ersetzen.

Für den Produktanwender heißt das: Referenz, Migrationsanleitung und Changelog werden zusammen sichtbar. Ein Fehler in einer der drei Seiten lässt die bisherige Dokumentation unangetastet. Ein später entdeckter fachlicher Fehler lässt sich durch Aktivieren eines bekannten Release zurücknehmen, ohne Markdown erneut zu rendern.

Diese Eigenschaft macht Agentenarbeit schneller, weil nicht jeder Lauf wie eine Operation am offenen Herzen behandelt werden muss. Entwürfe dürfen scheitern. Vorschauen dürfen verworfen werden. Entscheidend ist, dass der aktive Stand nur auf einen vollständig gebauten Release zeigt.

Was durch Agenten wirklich schneller wird

Der offensichtliche Gewinn ist die Textarbeit: Querverweise finden, wiederkehrende Änderungen anwenden, Tabellen aus strukturierten Daten erzeugen. Größer ist häufig der Gewinn zwischen den Arbeitsschritten. Der Agent kann Recherche, Änderung, Upload, Vorschau und technische Prüfung in einem zusammenhängenden Lauf erledigen. Übergaben über Tickets oder Copy-and-paste entfallen.

Ein typischer API-Wechsel muss dann nicht mehr tagelang zwischen Entwicklung und Redaktion pendeln. Die Maschine bereitet innerhalb kurzer Zeit einen vollständigen, prüfbaren Vorschlag vor. Menschen verwenden ihre Zeit auf fachliche Entscheidungen und schwierige Ausnahmen. Ist der Prozess ausreichend erprobt, können risikoarme Änderungen ohne menschliche Bedienung bis zum Release laufen.

Die Vereinfachung bleibt erhalten, wenn das Modell wechselt. Es gibt keine spezielle Claude-Code-Seite und keinen Codex-Modus in Contentkit. Solange der Agent Markdown und HTTP beherrscht, kann er denselben Pfad benutzen. Das schützt die Veröffentlichungstechnik davor, an die Lebensdauer eines Agentenprodukts gebunden zu werden.

Claude Code und Codex bleiben austauschbare Teilnehmer

Die beiden Agentenwerkzeuge unterscheiden sich in Bedienung, Modellen und Einbindung in die Entwicklungsumgebung. Für Contentkit sollte daraus kein zweiter Veröffentlichungsvertrag entstehen. Beide erhalten denselben kleinen Auftrag: Quellen im Arbeitsverzeichnis lesen, Markdown nach den Repository-Regeln ändern, lokale Prüfungen ausführen und die dokumentierten HTTP-Operationen aufrufen.

Ein teamweites Skript kann die Details kapseln, ohne einen Agenten fest einzubauen:

./scripts/contentkit-upload docs/api-authentication.de.md
./scripts/contentkit-preview .contentkit/revisions.json
./scripts/contentkit-verify .contentkit/preview.json

Die Skripte sollten selbst keine fachlichen Entscheidungen verstecken. Sie transportieren Dateien, bewahren IDs und vereinheitlichen Fehlerausgaben. Claude Code kann sie während einer Aufgabe ausführen, Codex ebenso, und ein Mensch kann denselben Ablauf im Terminal nachvollziehen. Ein allgemeiner MCP- oder Workflow-Adapter darf später dieselben Operationen anbieten, ohne dass Contentkit dadurch einen nativen MCP-Endpunkt erhält.

Diese Austauschbarkeit ist im Alltag wertvoll. Ein Team kann verschiedene Agenten für Recherche, technische Prüfung und Sprachreview verwenden. Der letzte Schritt beurteilt nicht, welchem Modell der Text gefällt, sondern ob die erzeugte Revision den Vertrag erfüllt und die Vorschau die erwarteten Eigenschaften hat.

Ein Agentenlauf braucht einen sauberen Arbeitsbereich

Der Agent sollte nur die Quellen sehen, die zum Auftrag gehören. Produktionsschlüssel liegen in der Laufzeit, nicht in Markdown oder Instruktionsdateien. Hochzuladende Dateien werden vor dem HTTP-Aufruf ausdrücklich aufgelistet; ein glob über das gesamte Repository kann versehentlich Notizen, Rohdaten oder Secrets erfassen.

Auch die Ausgabe gehört begrenzt. Ein Rechercheagent darf Patches und Beleglisten schreiben. Der Upload-Agent darf angenommene Revisionen erzeugen. Der Release-Agent erhält ausschließlich die geprüfte ID-Liste. Diese Aufteilung klingt zunächst langsamer als ein mächtiger Einzellauf, macht Wiederholungen jedoch sicherer. Ein fehlerhafter Rechercheversuch kann nicht nebenbei die öffentliche Website verändern.

Für kleine persönliche Projekte können diese Rollen in einem autorisierten Lauf zusammenfallen. Die gedankliche Trennung bleibt trotzdem hilfreich: lesen, vorschlagen, prüfen, veröffentlichen. Sie zeigt an jeder Stelle, welche Eingaben und Rechte tatsächlich benötigt werden.

Fazit

Claude Code und Codex passen zu Contentkit, weil beide in Dateien, Befehlen und überprüfbaren Ergebnissen arbeiten können. Ein eigener MCP-Server ist dafür nicht erforderlich. Markdown bildet den Vorschlag ab, die HTTP-API den Vertrag, eine Vorschau den vollständigen Kandidaten und der atomare Release die Wirkung.

Die entscheidende Beschleunigung entsteht nicht durch einen Knopf mit der Aufschrift „KI“. Sie entsteht, weil der Agent keinen menschlichen Klickweg nachspielen muss und jeder Schritt maschinenlesbar bleibt. Rechte, Validierung und Releases setzen die Leitplanken. Innerhalb dieses Rahmens kann der Agent schnell arbeiten, ohne den öffentlichen Stand dem Zufall zu überlassen.

Weiterführende Quellen

Wie fandest du diesen Beitrag?

Kommentare