ki-codex/03-alltag-und-workflows.md

Kapitel 3

Alltag und Workflows – Explore, Plan, Code, Verify, Commit

Kern in einem Satz: Produktive Sessions folgen einem Zyklus – erst verstehen, dann planen, dann ändern, dann verifizieren und committen – statt „ein Prompt, alles auf einmal“.

---

3.1 Der Zyklus

Ein Prompt, der teurer wird als fünf kurze: „Bau atomare Writes in store.py, Tests, README, und öffne einen PR.“ Der Agent startet breit, rät Architektur, flickt Tests, verbrennt Kontext – und du reviewst einen Diff, den niemand mehr in Phasen zerlegen kann.

Der Zyklus ist keine Bürokratie. Er ist die Fehlerbremse gegen genau diesen Impuls.

Phase	Ziel	Typische Mittel
Explore	Landkarte	Read-only-Prompts, @datei, „ändere nichts“
Plan	Vorgehen freigeben	/plan, Plan reviewen
Code	Umsetzen	enger Scope, Tests mitdenken
Verify	Realität prüfen	Test-Command aus AGENTS.md, /diff
Commit	nachvollziehbar speichern	Message, die ein Mensch in sechs Monaten versteht

Faustregel: Mehr als eine Datei oder unklare Architektur → erst Plan freigeben, dann Code. Agenten akkumulieren Fehler in langen Ketten: Eine falsche Annahme in Minute 2 wird in Minute 20 zum Refactor an der falschen Stelle.

{width=90%}

Scope eng halten ist hier der Alltagsgriff: pro Prompt Dateien, Done-Kriterium und Stop-Regel nennen – nicht „mach das Feature irgendwie fertig“.

---

3.2 Explore – ohne Nebenwirkungen

Jetzt selbst machen (todo-cli):

cd beispiele/todo-cli
codex

Karten das Repo: Einstiegspunkt, Persistenz, Tests.
Nenne die drei riskantesten Stellen für Datenverlust.
Ändere keine Dateien.

Ohne „ändere nichts“ startet Explore oft mit Aufräumen – und vermischt Lernen mit Side-Effects. Zusätzlich Read Only via /permissions, wenn du gar keine Edit-Pfade freigeben willst.

Gute Explore-Fragen:

• „Wo wird der Store geladen und gespeichert?“
• „Welche Tests decken save ab – und welche fehlen?“
• „Erkläre @todo/store.py in einfachen Worten.“

Schlechte:

• „Optimier alles“ – kein Ziel, maximaler Diff
• „Räum mal auf“ – subjektiv, endlos, review-feindlich

Gutes Explore: viele Reads, wenig oder keine Writes, am Ende eine Landkarte, die du gegenprüfen kannst.

---

3.3 Plan Mode – bevor Dateien fallen

/plan lenkt den Agenten auf Analysieren und Strukturieren, statt sofort zu editieren.

/plan Atomare Writes in store.py inkl. Testfällen.
Kein Code am Projekt, bis ich den Plan freigebe.

Oder nur /plan und den Auftrag im nächsten Turn. Stand Doku (Mitte/Ende 2026): Codex wechselt in Plan Mode; optionaler Inline-Text wird der erste Planning-Request. Während ein anderer Turn läuft, kann /plan vorübergehend nicht verfügbar sein – Labels und Details driftfähig; Konzept: Plan freigeben, dann implementieren.

Guter Plan enthält:

1. Betroffene Dateien
2. Schritte in Reihenfolge
3. Verify-Command (der echte aus AGENTS.md)
4. Nicht-Ziele

Skeleton zum Handoff: vorlagen/PLAN.md.skeleton.md; stabile Kerne in Anhang A. Lies den Plan wie einen Mini-RFC – nicht wie Statuszeile „sieht gut aus“.

Wann Plan	Wann überspringen
multi-file, Refactor, neues Feature	Einzeiler, Tippfehler, eine Log-Zeile
unklare Architektur	Diff in einem Satz beschreibbar
Daten-/Security-Risiko	reines Docs-Update mit klarem Scope

Optional parallel: /goal <Ziel> hält ein persistentes Ziel an der Session (max. Länge und Subcommands laut Doku – bei Drift / und Docs). Plan bleibt die Phasengrenze; Goal ist der rote Faden.

{width=90%}

---

3.4 Kontext steuern: @, !, Steering

Ohne @ rät der Agent oft Dateien; ohne Steering läuft der Scope weg, während du zusiehst. Die Syntax steuert, was im Kontext landet und wann du eingreifst – nicht nur Komfort.

Syntax / Mittel	Wirkung
@ im Composer	Dateipfad suchen und in den Prompt legen
/mention pfad	Datei gezielt an den Chat hängen
!befehl	Shell ohne Modell-Runde – unter aktueller Sandbox/Approval
Bilder	anhängen, wo die Surface/Vision es unterstützt
Steering (Enter während Arbeit)	Kurs im laufenden Turn korrigieren
Queue (Tab während Arbeit)	Folge-Prompt oder Slash einreihen
Stop	laufenden Turn abbrechen (Shortcuts je Version)
Ablehnen + Feedback	Tool ablehnen und sagen, was stattdessen (Kap. 1)

Anti-Pattern: alles ohne @ und ohne Stop-Regel → Scope-Creep. Beispiele:

Erkläre @todo/store.py – keine Änderungen.

!git status
!pytest -q

! ist nützlich, wenn du den Output selbst sehen und dann dem Agenten die Essenz geben willst – ohne Tool-Runde.

Beispiel-Steering, während der Agent noch an Tests bastelt:

Stop – kein Refactor von cli.py. Nur store.py und tests/.

---

3.5 Code – enge Aufträge

Setze den freigegebenen Plan um.
Nur todo/store.py und tests/test_store.py.
Nach jeder logischen Einheit: pytest -q.
Stoppe und berichte, wenn ein Test rot bleibt und du >2 Fix-Versuche brauchst.

Stop-Regel bremst Loops: Derselbe Fix mit Variationen frisst Runden; nach zwei Fehlversuchen ist menschliche Kurskorrektur billiger.

Feature-Beispiel: todo rm

Feature: `todo rm <id>` löscht einen Eintrag.
- argparse-Subcommand
- Exit 1 wenn ID fehlt
- Tests
- README eine Zeile
Kein Refactor außerhalb dieses Scopes.

Jede Bullet ist ein Check im Review. „Mach rm“ ohne Exit-Codes endet in halbgaren CLIs.

Lokal-first: der Agent ohne Remote

Kern: Eine Session ist fertig, wenn Explore–Plan–Code–Verify greifen – auch ohne Remote, Issue oder Pull Request. Cloud/PR-Flow ist Erweiterung, nicht Eintrittsschwelle.

Session-Typ	Typischer Abschluss	Remote nötig?
Feature/Fix nur lokal	grüne Tests, optional Commit	nein
Greenfield / PoC im CWD	lauffähiger Skelett-Stand, README	nein
Debug-Schleife	Repro + Fix + Verify	nein
Docs / Refactor ohne Merge-Druck	Diff gelesen, Tests grün	nein
Branch → PR / Cloud-Task	Review + menschlicher Merge	ja

Lokal-first, weniger Oberfläche: Plan bei multi-file, Diff lesen, enge Sandbox. Weg fallen oft Cloud-Ownership-Fragen und Push-Risiken. Bleiben: AGENTS.md, Sandbox × Approvals, Verify-Command.

Implementiere atomare Writes in store.py wie im freigegebenen Plan.
Nur store.py und tests. pytest -q nach dem Fix.
Kein Commit, kein Push – ich prüfe den Diff selbst.

---

3.6 Verify und /diff – der Schritt, den viele überspringen

Mindest-Verify:

pytest -q
# oder der Command aus AGENTS.md

In der Session:

Fasse Diff und Testergebnis zusammen. Nenne Restrisiken in 3 Bullets.

/diff: Git-Diff der Änderungen – inkl. untracked, soweit die CLI das anzeigt. Lies ihn, bevor du „fertig“ sagst.

Diff lesen vor Commit ist derselbe Hebel wie in Kapitel 1 und 2 – anderer Moment. Nach 20 Minuten Agent-Arbeit willst du abschließen. Genau dann rutschen Secrets, Debug-Prints und Scope-Creep durch.

git status
git diff

Verify ist die Realitätsschicht: Der Agent berichtet oft Optimismus; Tests und Diffs korrigieren das. Im Prompt den konkreten Command nennen – „teste bitte“ ist zu vage und öffnet Command-Halluzination (falscher Test-Stack, z. B. npm test im Python-Repo – Kapitel 2).

Agentic Review: /review

Nach grünen Tests und vor Commit/PR lohnt oft eine zweite Meinung im Terminal:

/review

Optional enger Scope im Folge-Prompt (Bugs, Security, Persistenz). Non-interaktiv:

codex review --untrusted
# oder: codex review --base main
# oder: codex review "Fokus: Datenverlust und Exit-Codes"

Genau ein Review-Ziel pro Aufruf (uncommitted / base / commit / custom Prompt – laut CLI-Hilfe; Flags nicht mischen). review_model in config.toml kann das Review-Modell setzen.

Wann /review	Wann nicht
multi-file Feature, Auth/Persistenz, vor PR	Tippfehler-Einzeiler
du willst Bias der Implement-Session brechen	du hast den Diff noch nicht gelesen
Security-Fokus	du brauchst Code-Änderungen – dann normaler Prompt

/review ersetzt weder /diff noch menschlichen Merge – es ist ein zusätzlicher Filter vorher.

Wenn der Agent daneben gelegen hat: Git-Reset der betroffenen Dateien; Session mit Esc zweimal forken – Vertiefung Kapitel 7.

---

3.7 Commit und Git-Alltag

Erstelle einen Commit mit klarer Message (Conventional Commits, wenn im Repo üblich).
Stage nur relevante Dateien. Kein push, bis ich es sage.

Schlechte Message: update · Bessere: fix(store): atomic save via temp file and replace

Commit ist lokal und reversibel; Push teilt; PR startet CI – die Stufen getrennt halten. Force-Push und destruktive Git-Operationen gehören in die Nie-Liste von AGENTS.md und bleiben hinter Approvals/enger Sandbox.

Typischer CLI-Strang ohne Extra-Produkt-Features:

1. Explore / Plan
2. Code + pytest -q
3. /diff → optional /review
4. Commit (Agent nur mit klarem „darfst committen“)
5. Push/PR bewusst selbst oder mit engem Auftrag

Cloud-PRs und codex exec in CI: Kapitel 6. Lokal Cloud-Diffs holen: codex apply – nur nach Review.

---

3.8 Modelle und Reasoning

/model

Wählt aktives Modell und, wo angeboten, Reasoning-Effort. In config.toml:

model = "gpt-5.6"                 # Beispielname – Katalog driftet
model_reasoning_effort = "high"   # wo das Modell es unterstützt

Situation	Tendenz
Architektur, hartes Debugging, nuancierter Refactor	stärkeres Modell / höherer Effort
Routine-CRUD, klare Tests	günstigeres / schnelleres Modell
Unsicher / Limits	Katalog und /usage prüfen; nicht raten

Namen und Defaults driften mit dem Angebot. Mid-Session wechseln ist erlaubt: Plan stark, Bulk sparsam – oder Review mit anderem Modell (review_model).

Optional, wo der Katalog es zeigt:

• /fast – Fast-Service-Tier des aktuellen Modells toggeln und speichern
• /personality – Kommunikationsstil (friendly / pragmatic / none), ohne Instructions umzuschreiben

Usage:

/usage

Tägliche/wöchentliche/kumulative Aktivität (wo Auth das hergibt). Lange Sessions und hohe Reasoning-Stufen kosten spürbar – dosieren, nicht als Alltags-Default auf Maximum.

Kern: Modellwahl ist eine Stellschraube, kein Glaubenssatz. Scope, Diff und Sandbox retten mehr Sessions als das „stärkste“ Modell allein.

---

3.9 Local vs. Cloud – Surface-Wahl

Laptop zu, aber der PR soll weiterlaufen? Oder live debuggen, wo /diff und Steering greifen? Surface-Wahl ist Ort und Isolation, nicht „Cloud = sicherer YOLO“.

	Lokal (CLI / IDE)	Codex Cloud
Wo	dein Rechner, aktuelle CWD	isolierte Remote-Umgebung
Wann	Debug, Exploration, enge Iteration	async Tasks, Laptop darf zu, PR-Orientierung
Du	steuerst live, /diff, Steering	arbeitest weiter; Ownership am Ergebnis
Policy	deine lokale Sandbox × Approvals	Cloud-Internet/Policy der Environment – nicht dasselbe wie Laptop-Deny

codex cloud          # interaktiver Picker
codex cloud list     # jüngste Tasks
codex cloud exec "…" # Task direkt einreichen (Auth wie CLI)

In der IDE oft Slash /cloud / /local (Labels driftfähig). Cloud-Diff lokal anwenden: codex apply – nach Review, nicht blind.

Achtung: Was du lokal per Ablehnen oder enger Sandbox blockst, gilt nicht automatisch in der Cloud-Environment. Ownership und Internet-Policy der Cloud sind eigene Grenzen (Kapitel 6). Cloud ist kein „sicherer YOLO-Schalter“ ohne Lesen der Environment-Settings.

Subagents / multi_agent und Parallelität: Kapitel 5. Hier reicht: Parallelität ersetzt weder Plan noch Diff-Disziplin.

---

3.10 Mikrogeschichte: Feature-Strang am todo-cli

Die Geschichte bleibt lokal bis Verify. Remote ist optionaler Nachsatz.

Annotation: > = du, Rest = Agent sinngemäß.

> Karten store.py und die Tests zu save/load.
  Nenne Risiken für Datenverlust. Ändere nichts.

Agent: [Landkarte, 3 Risiken]

> /plan Atomare Writes in store.py: temp file + replace.
  Nur todo/ und tests/. Verify: pytest -q. Kein README-Roman.

Agent: [Plan mit Dateien, Schritten, Nicht-Zielen]

> Plan ist ok. Scope eng halten. Umsetzen bis pytest -q grün.
  Stoppe nach >2 Fix-Versuchen an demselben Test.

Agent: [Edits, pytest -q → green]

> /diff

[Du liest den Diff – kein Scope-Creep, keine Secrets]

> /review Fokus Bugs und Datenverlust. Kein Style-Nörgeln.

> Commit mit klarer Message. Kein push, bis ich „push“ sage.

Weich vs. hart im Alltag: AGENTS.md sagt „pytest -q“ und „kein Force-Push“; Sandbox × Approvals bremsen Escapes und untrusted Shell. Zyklus = Memory für Qualität, Policy für Sicherheit.

Session-Hygiene kurz:

Situation	Mittel
Themenwechsel	/new oder /clear
Kontext voll / unscharf	/compact (verlustbehaftet – Kap. 7)
Fortsetzen	codex resume / /resume
Paralleler Ansatz	/fork oder codex fork
Status prüfen	/status

---

Checkliste Alltag

• Explore mit „keine Änderungen“, wenn du nur lernen willst
• /plan bei multi-file; Plan reviewen (Dateien, Nicht-Ziele, Verify)
• Code mit Scope + Stop-Regel; Tests mit Command aus AGENTS.md
• /diff oder git diff vor Commit
• Session darf lokal enden (grün + Diff) – Remote/PR ist optional
• Optional /review vor Commit/PR
• Push/PR bewusst; Merge menschlich
• Modell/Effort der Task anpassen; /usage im Blick
• Cloud nur mit klarem Ownership-Modell – nicht als Default-Escape

Symptom	Gegenmittel
Riesen-Diff ohne Struktur	/plan + engere Prompts
Agent „optimiert“ Nebenmodule	Nicht-Ziele im Plan; Steering
Endlose Fix-Loops	Stop-Regel; nach 2 Versuchen Mensch
Usage weg	engerer Scope; niedrigerer Effort; weniger Parallelität
Cloud-Überraschungen	Environment-Policy lesen; Diff vor codex apply

Jetzt selbst machen

cd beispiele/todo-cli
codex

1. Explore store.py (read-only).
2. /plan für atomare Writes oder todo rm.
3. Plan freigeben, umsetzen, pytest -q.
4. /diff lesen – hier darfst du lokal stoppen (Session fertig).
5. Optional: /review, Commit-Message, Push erst auf Kommando.

---

Was du jetzt kannst

• Den Zyklus Explore → Plan → Code → Verify → Commit bewusst steuern
• Lokal-first arbeiten: Session ohne Remote/PR als vollwertig behandeln
• /plan bedienen und Pläne vor der Freigabe prüfen
• Kontext mit @, !, Steering und Queue gezielt führen
• /diff und /review vor Commit einsetzen
• Commits eng halten und Push von Implementierung trennen
• Modelle, Reasoning-Effort und Usage grob handhaben
• Local vs. Cloud als Surface-Wahl mit Ownership-Hinweis einordnen

Nächste Schritte

• Kapitel 4 – Fortgeschrittene Konfiguration: Hierarchie, Profiles, Rules, Trust-Tiefe, Sessions
• Kapitel 5: MCP, Skills, Hooks, Subagents, Plugins
• Kapitel 7: Context, Compact, Rollback, Drift
• Vorlage vorlagen/PLAN.md.skeleton.md für Handoffs nutzen

Primärquellen: Developer commands, Prompting (wo verlinkt), Config basics, Non-interactive mode (Brücke zu Kap. 6).