Codex: Auftrag und Kontext — Cheat Sheet

Der Spickzettel zum Seminar Codex für Entwickler, erster Teil: alles, was vor dem ersten Diff passiert — Auftrag zuschneiden, Kontext setzen, Regeln verankern, planen. Der Betrieb steht auf dem zweiten Blatt, Codex im Projektbetrieb. Befehle und Konfigurationsschlüssel ändern sich schnell; maßgeblich bleibt die offizielle Codex-Dokumentation. Das Blatt fasst Entscheidungen zusammen — es bringt die Arbeitsweise nicht bei.

Assistent oder Agent

Klassischer Assistent	Codex als Agent
Vervollständigt die offene Datei	Arbeitet über das ganze Projekt
Schlägt vor, du tippst ab	Ändert Dateien selbst
Kennt keine Testausgabe	Führt Tests aus und liest sie
Ein Prompt, eine Antwort	Viele Schritte bis zum Ergebnis

Beides hat seinen Platz — nur die Erwartung an Aufwand und Prüfung ist eine andere: Vorschläge prüft man beim Lesen, Agentenarbeit erst am Diff.

Modul: Codex verstehen und einsetzen

Oberflächen und Modelle

Oberfläche	Stärke	Typischer Einsatz
CLI	direkt, skriptbar	lokale Arbeit, Automatisierung
IDE-Erweiterung	Diffs im Editor	Pairing beim Entwickeln
Desktop-App	mehrere Threads	parallele Aufträge im Blick
Cloud	läuft ohne dich weiter	lange Aufgaben, Reviews

Alle vier sprechen denselben Agenten an und teilen sich dieselbe Konfiguration — aber nicht denselben Kontext. Die Cloud kennt lokale Dienste und Datenbanken nicht.

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # empfohlen
npm install -g @openai/codex                           # Alternative
codex                                                  # Session im Projekt

Nach der Installation ein neues Terminal öffnen. Windows nutzt das PowerShell-Skript. Die Konfiguration landet unter ~/.codex/, nicht im Projekt.

/model                       # Modell in der Session umschalten
/status                      # Modell, Rechte, Kontextstand
codex --model <name>         # beim Start festlegen

# ~/.codex/config.toml — gilt für CLI, App und IDE
model = "<name>"
model_reasoning_effort = "high"

Modellnamen veralten schnell; die Auswahlregel nicht: großes Modell mit hohem Denkaufwand für Architektur und Planung, schnelles und günstiges fürs Sichten großer Codebasen und mechanische Umbenennungen. Kosten und Wartezeit gehören zur Entscheidung.

Ort	Auslöser	Ergebnis
Lokal vor dem Commit	`/review` in der Session	Hinweise vor dem Push
Pull Request	Kommentar an den Agenten	Review als Kommentar
Build-Pipeline	GitHub Action	Prüfschritt im CI

Ein Review des Agenten ersetzt kein menschliches Review — es geht ihm voraus. Automatisch auf jedem Pull Request erzeugt es schnell Rauschen.

Modul: Codex verstehen und einsetzen

Aufgaben zuschneiden

Größe	Beispiel	Vorgehen
Klein	Tippfehler, Umbenennung	direkt beauftragen
Mittel	Endpunkt ergänzen	Plan sichten, dann bauen
Groß	Modul umbauen	analysieren, planen, staffeln
Offen	Fehlersuche	erst untersuchen lassen

Im Zweifel eine Stufe kleiner schneiden. Ein guter Auftrag hat ein prüfbares Ziel, einen eingegrenzten Bereich, ein Erfolgskriterium (meist ein Test) und einen Umfang, der in ein Review passt.

Die fachliche Anforderung ist noch kein Auftrag — links die Anforderung, rechts der erste von mehreren Schnitten:

Fachliche Anforderung	Agentenauftrag
Kunden sollen später stornieren können	Stornofrist auf 48 h ändern
Wir brauchen bessere Fehlermeldungen	Fehlertexte in einem Modul ersetzen
Die Buchung ist zu langsam	Engpass messen, dann Abfrage ändern

Ziel:     Stornofrist von 24 h auf 48 h ändern.
Kontext:  @src/buchung/storno.ts und die Tests dazu.
Ergebnis: Änderung plus Test, npm test läuft grün.
Grenzen:  Preislogik und Migrationen nicht anfassen.

Diese vier Zeilen ersetzen keine Spezifikation, verhindern aber die häufigsten Rückfragen. Ohne Erfolgskriterium erklärt sich der Agent selbst für fertig.

Module: Codex verstehen und einsetzen · Context Engineering

Kontexthebel und ihre Reichweite

Hebel	Wirkt	Lebensdauer
Auftrag im Prompt	auf diese Aufgabe	eine Runde
Dateiverweise	auf diese Session	eine Session
`AGENTS.md`	auf jede Session	dauerhaft
`.codexignore`	auf den Suchraum	dauerhaft

Faustregel: Was sich wiederholt, gehört ins Repository — nicht in den nächsten Prompt. Immer längere Prompts kaschieren nur fehlenden Projektkontext.

@src/buchung/preis.ts    Datei erwähnen
/mention docs/api.md     Datei anhängen
/diff                    offene Änderungen zeigen
/status                  Kontextstand prüfen

Verweise ersetzen die Suche des Agenten — er liest zielgerichtet statt zu streifen. .codexignore ist dabei Kontexthygiene, keine Zugriffskontrolle.

Modul: Context Engineering

Context Window und Compaction

Anteil	Typischer Inhalt
Grundlast	Systemtext, `AGENTS.md`, Werkzeuge
Gelesene Dateien	oft der größte Posten
Werkzeugausgaben	Testläufe, Suchergebnisse, Logs
Verlauf	Aufträge und Antworten der Session

Schon vor der ersten Nachricht ist ein Teil des Fensters belegt. Ist es voll, wird verdichtet — und das kostet: Details aus Werkzeugausgaben gehen verloren, die Zusammenfassung ist eine Auslegung und kein Protokoll, und der Grund für frühere Entscheidungen fehlt danach oft. Deshalb vor dem Verdichten committen.

Symptom	Meist die Ursache
Agent ändert die falsche Datei	Ausschnitt nicht begrenzt
Antworten werden vage	Verlauf zu lang, verdichtet
Konventionen missachtet	Regeln stehen nirgends
Fehlersuche im Kreis	keine Reproduktion vorgegeben

Fast jedes Kontextproblem hat seine Ursache im Zuschnitt, nicht im Modell.

Modul: Context Engineering

Spezifikation im Repository

docs/spec/stornofrist.md
  Kontext     Warum die Änderung nötig ist
  Verhalten   Regeln, inklusive Grenzfällen
  Abnahme     prüfbare Kriterien
  Offen       bewusst ungeklärte Punkte

Der Abschnitt Offen ist der wichtigste — er verhindert, dass der Agent Lücken selbst füllt. Eine Spezifikation ohne Abnahmekriterien ist ein Wunschzettel; erfüllte Kriterien heißen „richtig zur Spezifikation”, nicht „richtig”. Für einen Einzeiler lohnt der Aufwand nicht.

Modul: Context Engineering

AGENTS.md gegen README.md

Merkmal	`README.md`	`AGENTS.md`
Für wen	Menschen	Coding-Agenten
Inhalt	Überblick, Einstieg	Befehle, Konventionen
Ton	erklärend	anweisend
Umfang	so kurz wie möglich	so knapp wie nötig

Die Datei gilt in jeder Session, für alle im Team gleich, ist versioniert und im Review diskutierbar. Sie kostet aber Kontext — jede Zeile muss sich rechnen, und was schon im Linter steht, gehört nicht hinein.

Gehört in den Prompt	Gehört in die `AGENTS.md`
Diese eine Aufgabe	Jede Aufgabe im Projekt
Das Ziel dieser Änderung	Der Testbefehl
Betroffene Dateien	Schichtgrenzen und Tabus
Einmalige Ausnahme	Dauerhafte Konvention

Faustregel: Gilt es auch nächste Woche und für Kolleginnen? Dann ins Repository. Entscheidend sind exakte Befehle statt Beschreibungen — „Wir testen gründlich” hilft dem Agenten nicht.

Modul: AGENTS.md und Projektregeln

Regelebenen und Leitplanken

Ebene	Wofür gedacht
Benutzerordner	eigene Vorlieben über alle Projekte
Projektwurzel	Regeln für das ganze Repository
Zwischenebenen	Regeln je Bereich oder Paket
Arbeitsverzeichnis	Regeln für genau dieses Modul

Die Ebenen werden zusammengefügt; eine AGENTS.override.md verdrängt auf ihrer Ebene die reguläre Datei. Das Ergebnis ist auf 32 KiB begrenzt, und global gesetzte Vorlieben wirken auch in fremden Projekten.

Ebene	Mittel	Wirkung
Absicht	`AGENTS.md`	dauerhaft, aber nicht erzwungen
Technik	Sandbox, Freigaben	hart begrenzt
Prüfung	Diff, Tests, Review	macht sichtbar

Regeln sind Text, keine Zusicherung. Immer neue Regeln ersetzen keine fehlende technische Grenze — die steht auf dem zweiten Blatt.

Modul: AGENTS.md und Projektregeln

Plan Mode

Sofort umsetzen	Erst planen
Entwurf bleibt implizit	Entwurf steht als Text da
Korrektur nach der Arbeit	Korrektur vor der Arbeit
Ein großes Diff am Ende	Prüfbare Teilschritte
Schnell zum ersten Ergebnis	Schnell zum richtigen Ergebnis

Die Grenze verläuft bei mehreren Dateien: Planen lohnt, wenn mehrere Schichten betroffen sind, mehr als ein Lösungsweg vertretbar ist, fremder oder alter Code im Spiel ist oder der Fehler nur beobachtet, aber nicht verstanden ist.

/plan               Plan Mode einschalten
/plan <Auftrag>     einschalten und gleich beauftragen
Shift+Tab           zwischen den Modi wechseln
/status             aktuellen Modus prüfen

Ein Plan besteht aus Schritten, nach denen sich anhalten und ausliefern ließe:

1  Frist als Konstante herausziehen, Tests grün
2  Konstante konfigurierbar machen, Test ergänzt
3  Wert auf 48 h setzen, Grenzfall-Test ergänzt
4  API-Dokumentation nachziehen

Modul: Plan Mode und agentische Workflows

Vier Fragen an einen Plan

Frage	Deckt auf
Was hast du verworfen?	unausgesprochene Annahmen
Was wird dadurch schwerer?	verschwiegene Kosten
Was passiert bei Fehlern?	fehlende Fehlerbehandlung
Was, wenn es doppelt läuft?	Nebenläufigkeitslücken

Sie kosten eine Minute und sparen regelmäßig einen Tag. Nachgeschärft wird gezielt — mit dem Hinweis, was bleibt, sonst erfindet der Agent den ganzen Plan neu:

Schritt 2 vor Schritt 1 — sonst brechen die Tests.
Schritt 3 zerlegen: erst Wert, dann Grenzfälle.
Migration fehlt, ergänze sie als eigenen Schritt.
Alles Übrige bleibt.

Phase	Der Agent	Du
Analyse	liest, fragt	beantwortest
Planung	schlägt vor	entscheidest
Umsetzung	ändert, testet	gibst frei, prüfst
Review	erklärt, korrigiert	bewertest

In jeder Phase liegt die Entscheidung beim Menschen — der Agent liefert die Vorarbeit.

Modul: Plan Mode und agentische Workflows

Prompt, Regel oder Skill

Mittel	Gilt	Wofür
Prompt	einmalig	diese eine Aufgabe
`AGENTS.md`	immer	Regeln und Konventionen
Skill	bei Bedarf	ein benannter Ablauf

Aspekt	`AGENTS.md`	Skill
Wann aktiv	immer	wenn passend
Inhalt	Regeln, Befehle	Ablauf mit Schritten
Umfang	knapp halten	darf ausführlich sein

Weil Skills nur bei Bedarf geladen werden, belasten sie den Kontext nicht dauerhaft. Die Prüffrage je Aussage: Muss sie auch dann gelten, wenn niemand den Skill ruft? Dann ist sie eine Regel.

Modul: Agent Skills und wiederverwendbare Fähigkeiten

Aufbau eines Skills

endpunkt-anlegen/
  SKILL.md      Name, Beschreibung, Anweisungen
  scripts/      optional, wo Genauigkeit zählt
  references/   optional, Hintergrundwissen
  assets/       optional, Vorlagen

Nur die SKILL.md ist Pflicht. Über das Laden entscheidet die Beschreibung, nicht der Inhalt — sie muss Zweck und Abgrenzung nennen:

---
name: endpunkt-anlegen
description: Legt einen neuen REST-Endpunkt samt
  Test und Doku an. Nicht für Änderungen an
  bestehenden Endpunkten verwenden.
---

Ablage	Wofür gedacht
Repository	Abläufe dieses Projekts, im Team geteilt
Heimatverzeichnis	eigene Arbeitsweise über Projekte hinweg
Systemweit	Vorgaben für alle Nutzer der Maschine

Im Zweifel enger wählen und später hochziehen — nur im Repository wird ein Skill mitgereviewt. Typische Kandidaten: Endpunkt anlegen, Review-Prüfliste, Testlücken suchen, Release vorbereiten. Je öfter ein Ablauf unter Zeitdruck stattfindet, desto mehr lohnt er sich als Skill.

Modul: Agent Skills und wiederverwendbare Fähigkeiten

Was wohin gehört

Erkenntnis	Gehört nach
Regel, die immer gilt	`AGENTS.md`
Ablauf, der sich wiederholt	Skill
Entscheidung mit Begründung	Commit oder Spezifikation
Persönliche Gewohnheit	eigene Prüfliste

Was nur im Kopf bleibt, ist beim nächsten Vorhaben wieder verschwunden.

Modul: Praxisprojekt: Vom Auftrag zum Ergebnis

Typische Fallen

Wie bei der Autovervollständigung prompten. Wer den Agenten wie eine Vervollständigung anspricht, bekommt Stückwerk.
npm i -g codex installiert das falsche Paket. Richtig ist @openai/codex.
Zwei Themen in einer Session. Vermischter Kontext führt zu vermischten Ergebnissen; Sessions gelten je Repository.
Alles mitgeben. Zu viele Verweise verdrängen den eigentlichen Auftrag — genauso schädlich wie zu wenig Kontext.
Regeln, die der Bestand selbst verletzt. Sie verwirren den Agenten mehr, als sie nützen; ungepflegte Regeln führen aktiv in die Irre.
Der /init-Entwurf beschreibt, was er sieht. Beschreibungen statt Befehle nützen nichts.
Planen für triviale Aufgaben. Reine Zeremonie — und ein Plan, den niemand liest, ist nur eine längere Antwort.
Vage Kritik am Plan. Führt zu einem beliebig anderen Plan statt zur gewünschten Korrektur.
Ein Skill, der alles kann, wird für nichts geladen; zu viele Skills konkurrieren um dieselbe Aufgabe.
Persönliche Skills wirken unbemerkt auch in fremden Projekten.

Zum Seminar Codex für Entwickler