10. Plan Mode und Build Mode

Plan Mode und Build Mode

Die typische Fehlleistung im Umgang mit einem Agenten sieht so aus. Sie schreiben zwei Sätze, der Agent legt los, nach acht Minuten sind elf Dateien geändert, und beim Durchsehen stellt sich heraus: Er hat eine andere Aufgabe gelöst als die gemeinte. Nicht schlecht gelöst, sondern die falsche. Jetzt haben Sie die Wahl zwischen wegwerfen und reparieren, und beides kostet mehr als die zwei Sätze wert waren.

Der Fehler liegt nicht beim Agenten. Er liegt darin, dass zwischen Ihrem Auftrag und der ersten Codezeile nichts stand, was man hätte prüfen können. Genau das ist der Zweck der Trennung in zwei Modi.

Zwei Modi

Plan Mode. Der Agent darf lesen, suchen, Fragen stellen und nachdenken, aber nichts verändern. Er erkundet die Codebasis und legt am Ende einen Plan vor: was er tun will, in welcher Reihenfolge, mit welchen Annahmen.

Build Mode. Der Agent darf schreiben, ausführen und ändern. Er arbeitet den freigegebenen Plan ab.

Dazwischen steht eine Freigabe durch einen Menschen. Das ist die ganze Idee, und der einzige Grund, warum sie so wirksam ist: Sie verschiebt Ihren Prüfaufwand von zweihundert geänderten Zeilen auf dreißig Zeilen Plan.

stateDiagram-v2
  [*] --> Auftrag
  Auftrag --> Plan: Plan Mode
  Plan --> Prüfung: Plan liegt vor
  Prüfung --> Plan: Rückfragen, Korrekturen
  Prüfung --> Bauen: freigegeben
  Prüfung --> Auftrag: Plan zeigt, dass die Aufgabe falsch gestellt war
  Bauen --> Abnahme: Tests grün
  Bauen --> Plan: Annahme im Plan war falsch
  Abnahme --> [*]

Der Übergang von Prüfung zurück zu Auftrag ist der wertvollste Pfeil im Diagramm. Es kommt regelmäßig vor, dass der Plan zeigt, dass die Aufgabe so nicht sinnvoll ist, und diese Erkenntnis kostet dann drei Minuten statt einer Stunde.

Warum das funktioniert

Vier Gründe, die unabhängig voneinander tragen.

Ein Plan ist billiger zu korrigieren als Code. Das ist dasselbe Argument, das im Softwareentwicklung-Unterricht gegen den reinen Wasserfall spricht und hier dafür: Der Zeitpunkt der Erkenntnis entscheidet über die Kosten. Ein Missverständnis, das im Plan auffällt, kostet einen Satz; dasselbe Missverständnis in elf geänderten Dateien kostet einen Nachmittag.

Ein Plan ist außerdem lesbar, geänderter Code oft nicht. Ein Diff über fünfhundert Zeilen wird durchgescrollt, dreißig Zeilen Plan werden gelesen. Das ist kein Ideal, sondern eine Beobachtung über Menschen.

Dazu kommt, dass der Plan zur Erkundung zwingt. Im Plan Mode muss der Agent erst herausfinden, wie das Projekt aufgebaut ist, bevor er etwas vorschlägt. Ein Plan, der die falschen Dateien nennt, verrät auf einen Blick, dass die Erkundung nicht getragen hat, und das erkennt man am Plan schneller als am Ergebnis.

Und die Verantwortung bleibt sichtbar. Wer einen Plan freigibt, hat entschieden. Wer einen Agenten laufen lässt, hat gehofft. Der Unterschied wird spätestens im Review relevant (Kapitel 12).

Wann Sie den Plan Mode überspringen können

Nicht jede Aufgabe braucht einen Plan. Bei einer Tippfehlerkorrektur, einer Umbenennung in einer Datei oder einem Test, den Sie ergänzen wollen, ist der Plan Overhead. Die brauchbare Schwelle: Sobald mehr als eine Datei betroffen ist oder Sie das Ergebnis nicht in einem Blick beurteilen können, planen Sie. Alles darunter ist Kleinarbeit, alles darüber ist ein Projekt.

Was in einen brauchbaren Plan gehört

Ein Plan, der nur die Schritte aufzählt, ist eine To-do-Liste und hilft wenig. Ein brauchbarer Plan beantwortet sieben Punkte.

Abschnitt	Wozu
Ziel	Ein bis zwei Sätze: Was soll danach anders sein? Fachlich, nicht technisch.
Betroffene Dateien	Welche Dateien werden angefasst, welche neu angelegt. Der beste Prüfpunkt überhaupt.
Vorgehen	Die Schritte in Reihenfolge, mit erkennbaren Zwischenständen.
Annahmen	Was der Agent unterstellt, ohne es geprüft zu haben. Hier stecken die Fehler.
Offene Fragen	Was er nicht entscheiden kann und Sie entscheiden müssen.
Testplan	Woran wird gemessen, dass es funktioniert? Verbindung zu Kapitel 11.
Nicht-Ziele	Was ausdrücklich nicht gemacht wird. Das Gegenmittel gegen das Überbauen aus Kapitel 5 und 8.

Ein Beispiel aus dem Projektkontext der 4. Klasse:

## Ziel
Projekte können über die API angelegt werden, mit serverseitiger Validierung.
Fehlerhafte Eingaben führen zu 400 mit maschinenlesbaren Feldfehlern.

## Betroffene Dateien
- neu: src/app/api/projects/route.ts        (POST-Handler)
- neu: src/lib/schemas/project.ts           (Zod-Schema)
- neu: src/repositories/project.ts          (Datenzugriff)
- neu: tests/api/projects.post.test.ts
- geändert: prisma/schema.prisma            (Modell Project)

## Vorgehen
1. Prisma-Modell ergänzen, Migration erzeugen
2. Zod-Schema für die Eingabe
3. Repository mit createProject(data)
4. Route Handler: parsen, validieren, Repository aufrufen, Antwort formen
5. Tests gegen die vier Fälle aus dem Testplan

## Annahmen
- Das Fehlerformat { error: { code, message, fields } } aus AGENTS.md gilt auch hier
- Authentifizierung ist noch nicht Teil dieser Aufgabe
- Die Projektnummer ist eindeutig; ein Duplikat ergibt 409

## Offene Fragen
- Soll das Feld "customer" verpflichtend sein? Das Schema in INSY sagt nein,
  das Formular im Entwurf sagt ja.

## Testplan
- gültige Eingabe -> 201, Antwort enthält die erzeugte id
- fehlendes Pflichtfeld -> 400 mit fields.title
- Projektnummer im falschen Format -> 400 mit fields.projectNumber
- doppelte Projektnummer -> 409

## Nicht-Ziele
- Kein Frontend-Formular
- Keine Authentifizierung, keine Rollenprüfung
- Keine Änderungen an bestehenden Endpunkten

Zwei Abschnitte davon verdienen eine eigene Bemerkung.

Der Abschnitt Annahmen ist der Ort, an dem Missverständnisse sichtbar werden. Ein Agent, der nichts annimmt, hat entweder alles geprüft (unwahrscheinlich) oder verschweigt es (wahrscheinlich). Wenn dieser Abschnitt leer ist, fragen Sie nach.

Die offenen Fragen sind die eigentliche Leistung des Plan Mode. Im Beispiel oben hat der Agent einen Widerspruch zwischen Datenmodell und Entwurf gefunden, den Sie beim Formulieren des Auftrags nicht auf dem Schirm hatten. Genau dafür lohnt sich der Schritt.

Den Plan prüfen

Ein Plan, der ungelesen freigegeben wird, ist schlimmer als kein Plan, weil er das Gefühl von Kontrolle erzeugt, ohne sie zu liefern. Die Prüfung dauert zwei Minuten und folgt einer Checkliste.

1. Ist das Ziel meines? Lesen Sie den Zielabschnitt und vergleichen Sie ihn mit dem, was Sie gemeint haben. Das ist der häufigste Treffer.

2. Stimmt die Dateiliste? Sie kennen Ihr Projekt. Eine Datei, die dort nicht hingehört, oder eine fehlende, die dort hingehören müsste, verrät ein falsches Verständnis der Architektur, und zwar sofort.

3. Sind die Annahmen richtig? Punkt für Punkt. Jede falsche Annahme wird im Build Mode zu einem Fehler.

4. Sind die offenen Fragen beantwortet? Vor der Freigabe, nicht danach. Ein Agent, der eine offene Frage selbst entscheidet, entscheidet sie nach Wahrscheinlichkeit.

5. Prüft der Testplan das Richtige? Sind die Fehlerfälle drin, nicht nur der Gutfall? Ein Testplan mit ausschließlich Gutfällen ist ein Warnsignal.

6. Ist der Umfang angemessen? Zwölf Schritte über acht Dateien sind kein Plan, sondern drei Pläne. Teilen Sie auf.

7. Fehlen Nicht-Ziele? Wenn dieser Abschnitt leer ist, ergänzen Sie ihn selbst. Er kostet einen Satz und verhindert die Hälfte des Überbauens.

Der Plan als Artefakt

Ein Plan, der nur im Terminal steht, ist nach dem Schließen weg. Legen Sie ihn ab.

• Ins Repository. Ein Verzeichnis docs/plaene/ mit einer Datei je Aufgabe. Kostet nichts und beantwortet in sechs Monaten die Frage, warum etwas so gebaut wurde.
• In den Merge Request. Der Plan in der Beschreibung macht das Review erheblich schneller: Die reviewende Person weiß, wonach sie sucht, und kann prüfen, ob der Diff dem Plan entspricht.
• Als Aufgabenbeschreibung im Ticket. In Teams, die mit Issues arbeiten, ist der Plan die bessere Aufgabenbeschreibung, weil er die Annahmen enthält.

Das verbindet sich mit dem Kapitel über Qualität im Team aus der 4. Klasse: Ein Merge Request mit Plan, Diff und grünen Tests ist reviewbar. Einer mit fünfhundert geänderten Zeilen und der Beschreibung „Feature implementiert” ist es nicht, unabhängig davon, wer ihn geschrieben hat.

Anti-Muster

Der abgenickte Plan. Man liest die Überschriften, denkt „passt”, gibt frei. Der Plan hat dann nur Zeit gekostet. Wenn Sie nicht vorhaben, ihn zu lesen, lassen Sie den Schritt weg.

Der Roman. Ein Plan über vier Seiten wird auch nicht gelesen. Wenn ein Agent so etwas produziert, ist die Aufgabe zu groß geschnitten. Teilen.

Der Plan ohne Nicht-Ziele. Führt verlässlich zu einer Implementierung, die zusätzlich noch drei andere Dinge macht.

Das Festhalten am Plan. Wenn sich im Build Mode herausstellt, dass eine Annahme falsch war, ist der richtige Zug zurück in den Plan Mode und nicht das Durchziehen. Ein Plan ist eine Hypothese, kein Vertrag.

Der Plan ohne Testplan. Ohne Erfolgskriterium meldet der Agent „fertig”, sobald es plausibel aussieht. Damit sind wir beim nächsten Kapitel.

Häufige Stolperfallen

1. Ohne Plan starten, weil es „nur eine Kleinigkeit” ist. Die Schwelle ist eine Datei, nicht ein Gefühl.
2. Den Plan freigeben, ohne die Dateiliste zu prüfen. Der schnellste und aussagekräftigste Prüfpunkt bleibt ungenutzt.
3. Offene Fragen offen lassen. Der Agent entscheidet sie dann nach Wahrscheinlichkeit statt nach Fachlichkeit.
4. Nicht-Ziele weglassen. Und sich anschließend über die drei zusätzlichen Hilfsklassen wundern.
5. Zu große Pläne freigeben. Was nicht reviewbar ist, ist ungeprüft, egal wie es aussieht.
6. Am Plan festhalten, obwohl er widerlegt ist. Zurück in den Plan Mode kostet Minuten, Durchziehen kostet den Nachmittag.
7. Den Plan nicht ablegen. In sechs Monaten weiß niemand mehr, welche Annahmen der Entscheidung zugrunde lagen.

Lernergebnisse: Was Sie nach diesem Kapitel können sollten

• Erklären: Plan Mode und Build Mode unterscheiden und begründen, warum die Trennung den Prüfaufwand senkt.
• Erklären: die Trennung mit dem Argument des Erkenntniszeitpunkts aus den Vorgehensmodellen begründen.
• Nennen: die sieben Bestandteile eines brauchbaren Plans benennen.
• Anwenden: einen Plan für eine mehrschrittige Aufgabe erzeugen lassen und ihn anhand der Checkliste prüfen.
• Beurteilen: entscheiden, ob eine Aufgabe einen Plan braucht, und einen zu großen Plan sinnvoll aufteilen.
• Beurteilen: in einem vorgelegten Plan falsche Annahmen und fehlende Nicht-Ziele erkennen und korrigieren.
• Anwenden: Pläne als Artefakt im Repository und im Merge Request ablegen und für das Review nutzbar machen.