Plan-Modus

Was macht Plan-Modus?

Verwende diese Fertigkeit, wenn der Benutzer einen Plan statt einer Ausführung wünscht.

Kernverhalten

In dieser Iteration planst du nur.

• Setze keinen Code um.
• Bearbeite keine Projektdateien, außer der Plan-Markdown-Datei.
• Führe keine mutierenden Terminalbefehle aus, committe nichts, pushe nichts und führe keine externen Aktionen durch.
• Du kannst das Repository oder andere Kontexte bei Bedarf mit schreibgeschützten Befehlen/Werkzeugen inspizieren.
• Dein Ergebnis ist ein Markdown-Plan, der im aktiven Arbeitsbereich unter .hermes/plans/ gespeichert wird.

Ausgabeanforderungen

Schreibe einen Markdown-Plan, der konkret und umsetzbar ist.

Füge, falls relevant, Folgendes ein:

• Ziel
• Aktueller Kontext / Annahmen
• Vorgeschlagener Ansatz
• Schritt-für-Schritt-Plan
• Dateien, die sich wahrscheinlich ändern
• Tests / Validierung
• Risiken, Kompromisse und offene Fragen

Wenn es sich um eine codebezogene Aufgabe handelt, füge genaue Dateipfade, wahrscheinliche Testziele und Verifizierungsschritte ein.

Speicherort

Speichere den Plan mit write_file unter:

• .hermes/plans/JJJJ-MM-TT_HHMMSS-<slug>.md

Behandle dies als relativ zum aktiven Arbeitsverzeichnis / Backend-Arbeitsbereich. Hermes-Dateiwerkzeuge sind backendbewusst, sodass die Verwendung dieses relativen Pfads den Plan im Arbeitsbereich auf lokalen, Docker-, SSH-, Modal- und Daytona-Backends hält.

Wenn die Laufzeit einen bestimmten Zielpfad vorgibt, verwende diesen genauen Pfad. Wenn nicht, erstelle selbst einen sinnvollen, mit Zeitstempel versehenen Dateinamen unter .hermes/plans/.

Interaktionsstil

• Wenn die Anfrage klar genug ist, schreibe den Plan direkt.
• Wenn keine explizite Anweisung /plan begleitet, leite die Aufgabe aus dem aktuellen Gesprächskontext ab.
• Wenn es wirklich unterspezifiziert ist, stelle eine kurze klärende Frage, anstatt zu raten.
• Nach dem Speichern des Plans antworte kurz mit dem, was du geplant hast, und dem Pfad, unter dem gespeichert wurde.

---

Den Plan gut schreiben

Der Rest dieser Fertigkeit ist die Kunst, einen guten Implementierungsplan zu verfassen – die Inhalte, die in die obige Markdown-Datei kommen.

Überblick

Schreibe umfassende Implementierungspläne unter der Annahme, dass der Implementierer keinerlei Kontext für die Codebasis und fragwürdigen Geschmack hat. Dokumentiere alles, was sie brauchen: welche Dateien zu bearbeiten sind, vollständigen Code, Testbefehle, zu prüfende Dokumentation, wie zu verifizieren ist. Gib ihnen mundgerechte Aufgaben. DRY. YAGNI. TDD. Häufige Commits.

Nimm an, dass der Implementierer ein erfahrener Entwickler ist, aber fast nichts über die Tool-Umgebung oder das Problemfeld weiß. Nimm an, dass gutes Testdesign nicht sehr gut bekannt ist.

Kernprinzip: Ein guter Plan macht die Implementierung offensichtlich. Wenn jemand raten muss, ist der Plan unvollständig.

Wann ein vollständiger Implementierungsplan hilft

Immer vorher verwenden:

• Implementierung von mehrschrittigen Funktionen
• Aufschlüsselung komplexer Anforderungen
• Delegation an Unteragenten via subagent-driven-development

Nicht überspringen, wenn:

• Funktion einfach erscheint (Annahmen verursachen Fehler)
• Du selbst implementieren willst (Zukunft-du braucht Anleitung)
• Allein arbeitest (Dokumentation ist wichtig)

Mundgerechte Aufgabengranularität

Jede Aufgabe = 2–5 Minuten fokussierte Arbeit.

Jeder Schritt ist eine Aktion:

• „Schreibe den fehlschlagenden Test“ – Schritt
• „Führe ihn aus, um sicherzustellen, dass er fehlschlägt“ – Schritt
• „Implementiere den minimalen Code, um den Test zu bestehen“ – Schritt
• „Führe die Tests aus und stelle sicher, dass sie bestehen“ – Schritt
• „Committen“ – Schritt

Zu groß:

### Aufgabe 1: Authentifizierungssystem bauen
[50 Codezeilen über 5 Dateien]

Richtige Größe:

### Aufgabe 1: Benutzermodell mit E-Mail-Feld erstellen
[10 Zeilen, 1 Datei]

### Aufgabe 2: Passwort-Hash-Feld zum Benutzer hinzufügen
[8 Zeilen, 1 Datei]

### Aufgabe 3: Passwort-Hash-Dienstprogramm erstellen
[15 Zeilen, 1 Datei]

Dokumentstruktur des Plans

Kopfzeile (Erforderlich)

Jeder Plan MUSS beginnen mit:

# [Funktionsname] Implementierungsplan

> **Für Hermes:** Verwende die Fertigkeit subagent-driven-development, um diesen Plan Aufgabe für Aufgabe zu implementieren.

**Ziel:** [Ein Satz, der beschreibt, was dies erstellt]

**Architektur:** [2–3 Sätze zum Ansatz]

**Tech-Stack:** [Wichtige Technologien/Bibliotheken]

---

Aufgabestruktur

Jede Aufgabe folgt diesem Format:

### Aufgabe N: [Beschreibender Name]

**Ziel:** Was diese Aufgabe erreicht (ein Satz)

**Dateien:**
- Erstellen: `genauer/pfad/zu/neuer_datei.py`
- Ändern: `genauer/pfad/zu/existierend.py:45-67` (Zeilennummern falls bekannt)
- Test: `tests/pfad/zu/test_datei.py`

**Schritt 1: Fehlschlagenden Test schreiben**

```python
def test_spezifisches_verhalten():
    ergebnis = funktion(eingabe)
    assert ergebnis == erwartet
```

**Schritt 2: Test ausführen, um Fehlschlag zu verifizieren**

Ausführen: `pytest tests/pfad/test.py::test_spezifisches_verhalten -v`
Erwartet: FAIL — „function not defined“

**Schritt 3: Minimale Implementierung schreiben**

```python
def funktion(eingabe):
    return erwartet
```

**Schritt 4: Test ausführen, um Bestehen zu verifizieren**

Ausführen: `pytest tests/pfad/test.py::test_spezifisches_verhalten -v`
Erwartet: PASS

**Schritt 5: Committen**

```bash
git add tests/pfad/test.py src/pfad/datei.py
git commit -m "feat: spezifische Funktion hinzugefügt"
```

Schreibprozess

Schritt 1: Anforderungen verstehen

Lies und verstehe:

• Funktionsanforderungen
• Designdokumente oder Benutzerbeschreibung
• Akzeptanzkriterien
• Einschränkungen

Schritt 2: Codebasis erkunden

Verwende Hermes-Werkzeuge, um das Projekt zu verstehen:

# Projektstruktur verstehen
search_files("*.py", target="files", path="src/")

# Ähnliche Funktionen ansehen
search_files("aehnliches_muster", path="src/", file_glob="*.py")

# Vorhandene Tests prüfen
search_files("*.py", target="files", path="tests/")

# Wichtige Dateien lesen
read_file("src/app.py")

Schritt 3: Ansatz entwerfen

Entscheide:

• Architekturmuster
• Dateiorganisation
• Benötigte Abhängigkeiten
• Teststrategie

Schritt 4: Aufgaben schreiben

Erstelle Aufgaben in der Reihenfolge:

1. Einrichtung/Infrastruktur
2. Kernfunktionalität (TDD für jede)
3. Randfälle
4. Integration
5. Bereinigung/Dokumentation

Schritt 5: Vollständige Details hinzufügen

Füge für jede Aufgabe ein:

• Genaue Dateipfade (nicht „die Konfigurationsdatei“, sondern src/config/settings.py)
• Vollständige Codebeispiele (nicht „Validierung hinzufügen“, sondern den tatsächlichen Code)
• Genaue Befehle mit erwarteter Ausgabe
• Verifizierungsschritte, die beweisen, dass die Aufgabe funktioniert

Schritt 6: Plan überprüfen

Prüfe:

• Aufgaben sind sequenziell und logisch
• Jede Aufgabe ist mundgerecht (2–5 Min.)
• Dateipfade sind genau
• Codebeispiele sind vollständig (kopierbar)
• Befehle sind genau mit erwarteter Ausgabe
• Kein fehlender Kontext
• DRY-, YAGNI-, TDD-Prinzipien angewendet

Prinzipien

DRY (Don't Repeat Yourself)

Schlecht: Validierung an 3 Stellen kopieren Gut: Validierungsfunktion extrahieren, überall verwenden

YAGNI (You Aren't Gonna Need It)

Schlecht: „Flexibilität“ für zukünftige Anforderungen hinzufügen Gut: Nur das implementieren, was jetzt benötigt wird

# Schlecht — YAGNI-Verstoß
class Benutzer:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.einstellungen = {}  # Noch nicht benötigt!
        self.metadaten = {}      # Noch nicht benötigt!

# Gut — YAGNI
class Benutzer:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD (Testgetriebene Entwicklung)

Jede Aufgabe, die Code erzeugt, sollte den vollständigen TDD-Zyklus enthalten:

1. Fehlschlagenden Test schreiben
2. Ausführen, um Fehlschlag zu verifizieren
3. Minimalen Code schreiben
4. Ausführen, um Bestehen zu verifizieren

Siehe Fertigkeit test-driven-development für Details.

Häufige Commits

Commite nach jeder Aufgabe:

git add [dateien]
git commit -m "typ: beschreibung"

Häufige Fehler

Vage Aufgaben

Schlecht: „Authentifizierung hinzufügen“ Gut: „Benutzermodell mit E-Mail- und Passwort-Hash-Feldern erstellen“

Unvollständiger Code

Schlecht: „Schritt 1: Validierungsfunktion hinzufügen“ Gut: „Schritt 1: Validierungsfunktion hinzufügen“ gefolgt vom vollständigen Funktionscode

Fehlende Verifizierung

Schlecht: „Schritt 3: Teste, ob es funktioniert“ Gut: „Schritt 3: Führe pytest tests/test_auth.py -v aus, erwartet: 3 bestanden“

Fehlende Dateipfade

Schlecht: „Erstelle die Modelldatei“ Gut: „Erstellen: src/models/benutzer.py“

Ausführungsübergabe

Nach dem Speichern des Plans biete den Ausführungsansatz an:

„Plan abgeschlossen und gespeichert. Bereit zur Ausführung mit subagent-driven-development – ich werde pro Aufgabe einen neuen Unteragenten mit zweistufiger Überprüfung (Spezifikationskonformität, dann Codequalität) einsetzen. Soll ich fortfahren?“

Bei der Ausführung verwende die Fertigkeit subagent-driven-development:

• Frischer delegate_task pro Aufgabe mit vollständigem Kontext
• Überprüfung der Spezifikationskonformität nach jeder Aufgabe
• Überprüfung der Codequalität nach Bestehen der Spezifikation
• Fortfahren nur, wenn beide Überprüfungen zustimmen

Denk dran

Mundgerechte Aufgaben (2–5 Min. jede)
Genaue Dateipfade
Vollständiger Code (kopierbar)
Genaue Befehle mit erwarteter Ausgabe
Verifizierungsschritte
DRY, YAGNI, TDD
Häufige Commits

Ein guter Plan macht die Implementierung offensichtlich.