Codex im Projektbetrieb — Cheat Sheet

Der Spickzettel zum Seminar Codex für Entwickler, zweiter Teil: der laufende Betrieb — arbeiten, prüfen, zurückrollen, Rechte setzen, anbinden, automatisieren. Auftrag, Kontext und Planung stehen auf dem ersten Blatt, Codex: Auftrag und Kontext. Konfigurationsschlüssel und Kommandonamen ändern sich; maßgeblich bleibt die offizielle Codex-Dokumentation. Das Blatt sammelt Entscheidungen — die Arbeitsweise vermittelt es nicht.

Auftragsformen im Projekt

Analyse, ohne etwas zu ändern — der Zusatz mit den Dateipfaden macht die Antwort nachprüfbar statt nur plausibel:

Beschreibe den Aufbau: Schichten und Zuständigkeiten.
Wie läuft eine Buchung vom Endpunkt bis zur Datenbank?
Welche Stellen wirken riskant oder ungetestet?
Ändere nichts, belege alles mit Dateipfaden.

Refactoring — „Tests unverändert” ist die schärfste Bedingung, sie verbietet das Anpassen der Messlatte:

Ziel:      Preisberechnung aus src/api nach src/buchung ziehen.
Bedingung: Verhalten unverändert, Tests unverändert.
Ergebnis:  npm test grün, keine neue Abhängigkeit.
Grenzen:   Keine Signatur nach außen ändern.

Ein Schnitt, ein Auftrag: Jeder Schnitt ist einzeln prüfbar und rückholbar, Fehler zeigen sich früh und lokal, ein Abbruch kostet nur den letzten Schritt.

Modul: Codex im Softwareprojekt

Fehlersuche und Tests

„Behoben ohne Test” heißt nur: heute nicht mehr sichtbar. Der Agent findet gern die erste, nicht die eigentliche Ursache.

Der rechte Test bricht bei jedem Refactoring — und schützt trotzdem vor nichts.

Modul: Codex im Softwareprojekt

Prüfen, iterieren, abbrechen

/diff              # Änderungen ansehen, inkl. neuer Dateien
/review            # Hinweise vom Agenten einholen
npm test           # selbst laufen lassen
git add -p         # bewusst einzeln übernehmen

Das eigene Testkommando ersetzt keine Durchsicht — und die Durchsicht keinen Testlauf. Beim Durchsehen zählen: neue Dateien, die niemand verlangt hat, Änderungen an Konfiguration und Abhängigkeiten, entfernte Prüfungen und Sonderfälle, Formatierungsrauschen, das die Sicht verstellt.

Die letzte Zeile ist ernst gemeint. Abbruchsignale: dieselbe Fehlerklasse kehrt zurück, jede Korrektur bricht etwas anderes, die Erklärungen werden allgemeiner statt genauer, der Prüfaufwand übersteigt den Schreibaufwand.

Modul: Codex im Softwareprojekt

Wege zurück

git restore <datei>      # eine Datei verwerfen
git restore .            # alle Änderungen verwerfen
git reset --hard HEAD    # auf den letzten Commit
git revert <commit>      # Commit zurücknehmen

Nach Härte sortiert. Verworfen wird auch, was du selbst geschrieben hast; neue, ungetrackte Dateien bleiben dabei liegen. Ohne Commit vor dem Lauf hilft kein Rücksprung — und auf geteilten Branches ist Umschreiben der Historie tabu.

Modul: Git, Sessions und parallele Arbeit

Sessions und Worktrees

codex            # neue Session starten
codex resume     # gespeicherte Session fortsetzen
/new             # neues Thema, gleiche Sitzung
/clear           # Verlauf zurücksetzen

Sessions hängen am Arbeitsverzeichnis — im Worktree beginnt eine eigene Ablage.

git worktree add ../kv-rabatt -b feature/rabatt
git worktree add ../kv-storno -b fix/storno
git worktree list
git worktree remove ../kv-rabatt

Jeder Worktree hat eigenen Stand und eigene Sessions; gemeinsam ist nur die Historie. Abhängigkeiten müssen je Worktree installiert werden, lokale Dienste und Ports kollidieren schnell, aufgeräumt wird über den Git-Befehl.

Drei bis vier parallele Aufgaben sind erfahrungsgemäß die Grenze des Überschaubaren — Ergebnisse stapeln sich sonst schneller, als sie geprüft werden.

Modul: Git, Sessions und parallele Arbeit

Sandbox und Freigaben

Beide Regler wirken zusammen — erst ihre Kombination ergibt das tatsächliche Verhalten. Voreinstellung für lokale Arbeit ist workspace-write mit on-request; der Netzzugriff bleibt dabei zu.

/permissions     # Voreinstellung in der Session wählen
/status          # aktuelle Rechte und Modus anzeigen
/approve         # laufende Anfrage freigeben

# ~/.codex/config.toml
sandbox_mode    = "workspace-write"
approval_policy = "on-request"

[profiles.sichten]          # fremde Repositorien nur lesen
sandbox_mode    = "read-only"
approval_policy = "untrusted"

In der Session gesetzte Rechte gelten nur für diese Session; Profile machen die Entscheidung wiederholbar, nehmen sie aber nicht ab. Die Sandbox schützt den Rechner, nicht das Repository.

Modul: Sicherheit, Permissions und Autonomie

Autonomie nach Risiko

Die Frage ist nicht, ob der Agent es kann, sondern was ein Fehler kostet. Autonomie setzt voraus: sauberer Ausgangszustand in der Versionskontrolle, Tests, die eine Verschlechterung bemerken, ein klar benannter Wirkungsbereich und jemand, der das Ergebnis tatsächlich prüft.

Ganz ohne Kontrolle geht keine der drei Zeilen — sie verschieben nur ihren Ort.

Modul: Sicherheit, Permissions und Autonomie

MCP anbinden

Jede Zeile spart Handarbeit — und erweitert zugleich den Wirkungsbereich des Agenten.

codex mcp add <name> -- <startbefehl>
codex mcp add <name> --url https://…
codex mcp list      # angebundene Server zeigen
/mcp                # in der Session prüfen

[mcp_servers.schema]
command = "npx"
args    = ["-y", "beispiel-db-mcp"]

[mcp_servers.tickets]
url                  = "https://mcp.beispiel.de/mcp"
bearer_token_env_var = "TICKET_TOKEN"

Zugangsdaten gehören in Umgebungsvariablen, nie in die Konfigurationsdatei selbst. MCP ist ein Protokoll, kein Qualitätsversprechen: Ein Server bringt fremden Code auf die Maschine.

Modul: MCP und externe Werkzeuge

Werkzeuge nach Wirkung einstufen

Die Risikostufe bestimmt, ob eine Freigabe je Aufruf sinnvoll ist. Prüfen, gegen welche Umgebung ein Werkzeug tatsächlich arbeitet.

Was selten gebraucht wird, gehört hinter ein Werkzeug — nicht in den ständigen Kontext. Zu viele Werkzeuge machen die Auswahl unzuverlässig.

Modul: MCP und externe Werkzeuge

Automatisieren: Befehl oder SDK

codex exec "Ergänze fehlende Tests in src/buchung"
codex exec --json "Prüfe die offenen Änderungen"

Die strukturierte Ausgabe lässt sich im Skript auswerten, der reine Text nur lesen. Erst den Befehl versuchen — das SDK lohnt, wenn dessen Grenzen erreicht sind: Lauf begleiten und steuern, Ereignisse statt Text, eingebettet in eine Anwendung statt in ein Skript.

Ohne Aufsicht gilt: Es gibt niemanden, der eine Rückfrage beantwortet, Rechte müssen vorab feststehen, Fehler müssen im Ergebnis erkennbar sein, und der Umfang muss vorhersagbar begrenzt bleiben.

Die rechte Spalte hat gemeinsam, dass jemand das Ergebnis bewerten muss.

Modul: Codex SDK und Automatisierungen

Anlässe und Einsatzfelder

Vorher klären: Wer liest das Ergebnis und entscheidet daraufhin? Was passiert bei einem Ausfall? Wie viel Rauschen toleriert das Team? Was kostet der Lauf, mal Anzahl der Anlässe?

Gemeinsam ist allen: Der Agent liest viel und schreibt wenig — genau seine Stärke.

Modul: Codex SDK und Automatisierungen

Lokal oder Cloud

Der Unterschied ist nicht die Fähigkeit des Agenten, sondern was er vorfindet.

Genau diese vier Punkte sind der Grund, warum lokal die Voreinstellung bleibt.

Modul: Codex lokal, im Web und in der Cloud

Auftrag für einen unbeaufsichtigten Lauf

Ziel:     Tests in src/buchung um Fehlerfälle ergänzen.
Kontext:  tests/buchung als Vorbild nehmen.
Ergebnis: npm test grün, keine Quelldatei geändert.
Grenzen:  Keine neue Abhängigkeit, kein Test gelöscht.
Bei Unklarheit: Annahme dokumentieren, nicht raten.

Die letzte Zeile ersetzt die Rückfrage, die in der Cloud niemand stellen kann. Unbeaufsichtigte Läufe scheitern an ungesagtem Wissen, fehlendem Fertig-Kriterium, unbegrenztem Umfang und daran, dass nicht gesagt ist, was bei Unklarheit gilt. Zurück kommt das Ergebnis nur über den lokalen Bau- und Testlauf — grün in der Cloud heißt nicht grün bei dir.

Modul: Codex lokal, im Web und in der Cloud

Typische Fallen

• Eigene und Agentenänderungen im selben Commit — und Arbeiten direkt auf dem Hauptbranch. Beides macht das Diff unlesbar.
• Zustimmen, weil die Erklärung überzeugend klingt. Die Erklärung des Agenten ist nicht der Code.
• Ein Diff über 40 Dateien wird erfahrungsgemäß überflogen; teilweise durchgeführte Umbenennungen sind schlimmer als keine.
• Angepasste Tests statt angepassten Codes verdecken Verhaltensänderungen.
• Freigaben im Minutentakt führen zum blinden Bestätigen — genau dem, was sie verhindern sollen.
• Die Ignorierdatei hält Inhalte aus dem Kontext, nicht vom Zugriff fern. Shell-Befehle des Agenten lesen an ihr vorbei.
• Ein Geheimnis, das der Agent gelesen hat, gilt als kompromittiert.
• Vergessene MCP-Server laufen weiter und kosten Kontext; Rechte werden beim Anbinden vergeben und danach nie geprüft.
• Ein Lauf, der auf eine Freigabe wartet, hängt still — ohne Zeitlimit blockiert ein Fehllauf die Pipeline.
• Ignorierte Dateien fehlen im Cloud-Klon — auch nötige wie Konfiguration und Beispieldaten.
• Ergebnisse übernehmen, weil der Aufwand sonst verloren wäre.