Schreibpläne

Überblick

Erstellen Sie umfassende Implementierungspläne unter der Annahme, dass der Entwickler keinerlei Kontext für unsere Codebasis hat und einen fragwürdigen Geschmack besitzt. Dokumentieren Sie alles, was er wissen muss: welche Dateien für jede Aufgabe bearbeitet werden müssen, Code, Tests, Dokumentation, die er möglicherweise prüfen muss, sowie wie das Ganze getestet wird. Geben Sie ihm den gesamten Plan in Form von überschaubaren Teilaufgaben. DRY. YAGNI. TDD. Häufige Commits.

Gehen Sie davon aus, dass er ein erfahrener Entwickler ist, aber so gut wie nichts über unser Toolset oder unseren Problembereich weiß. Gehen Sie davon aus, dass er sich mit gutem Testdesign nicht besonders gut auskennt.

Kündige zu Beginn an: „Ich nutze die Fähigkeit ‚ writing-plans ‘, um den Implementierungsplan zu erstellen.“

Kontext: Wenn in einem isolierten Arbeitsbaum gearbeitet wird, sollte dieser zur Ausführungszeit über die Fertigkeit „superpowers:using-git-worktrees“ erstellt worden sein.

Pläne speichern unter: docs/superpowers/plans/YYYY-MM-DD-.md

• (Benutzereinstellungen für den Speicherort des Plans haben Vorrang vor dieser Standardeinstellung)

Umfangsprüfung

Wenn die Spezifikation mehrere unabhängige Teilsysteme abdeckt, hätte sie bereits während des Brainstormings in Teilprojekt-Spezifikationen aufgeteilt werden sollen. Ist dies nicht geschehen, schlage vor, sie in separate Pläne aufzuteilen – einen pro Teilsystem. Jeder Plan sollte für sich allein funktionierende, testbare Software hervorbringen.

Dateistruktur

Bevor Sie Aufgaben definieren, legen Sie fest, welche Dateien erstellt oder geändert werden und wofür jede einzelne zuständig ist. Hier werden die Entscheidungen zur Aufgliederung festgeschrieben.

• Entwerfen Sie Einheiten mit klaren Grenzen und genau definierten Schnittstellen. Jede Datei sollte eine eindeutige Aufgabe haben.
• Man kann Code am besten durchdenken, wenn man den gesamten Kontext auf einen Blick erfassen kann, und Änderungen sind zuverlässiger, wenn Dateien fokussiert sind. Bevorzuge kleinere, fokussierte Dateien gegenüber großen, die zu viele Aufgaben erfüllen.
• Dateien, die gemeinsam geändert werden, sollten zusammenbleiben. Teilen Sie nach Zuständigkeiten auf, nicht nach technischen Schichten.
• Halten Sie sich in bestehenden Codebasen an etablierte Muster. Wenn die Codebase große Dateien verwendet, sollten Sie diese nicht einseitig umstrukturieren – sollte eine Datei, die Sie bearbeiten, jedoch unübersichtlich geworden sein, ist es sinnvoll, eine Aufteilung in den Plan aufzunehmen.

Diese Struktur bestimmt die Aufteilung der Aufgaben. Jede Aufgabe sollte in sich geschlossene Änderungen hervorbringen, die für sich genommen Sinn ergeben.

Richtige Dimensionierung von Aufgaben

Eine Aufgabe ist die kleinste Einheit, die einen eigenen Testzyklus durchläuft und eine Überprüfung durch einen neuen Prüfer rechtfertigt. Beim Festlegen von Aufgabengrenzen: Integrieren Sie Schritte zur Einrichtung, Konfiguration, Strukturierung und Dokumentation in die Aufgabe, deren Ergebnis diese benötigt; teilen Sie nur dort auf, wo ein Prüfer sinnvollerweise eine Aufgabe ablehnen könnte, während er die benachbarte genehmigt. Jede Aufgabe endet mit einem unabhängig testbaren Ergebnis.

Überschaubare Aufgabengranularität

Jeder Schritt ist eine einzelne Aktion (2–5 Minuten):

• „Den fehlgeschlagenen Test schreiben“ – Schritt
• „Führe ihn aus, um sicherzustellen, dass er fehlschlägt“ – Schritt
• „Den minimalen Code implementieren, damit der Test besteht“ – Schritt
• „Führe die Tests aus und stelle sicher, dass sie bestehen“ – Schritt
• „Commit“ – Schritt

Kopfzeile des Planungsdokuments

Jeder Plan MUSS mit dieser Überschrift beginnen:

# [Feature-Name] Implementierungsplan

> **Für agentische Mitarbeiter:** ERFORDERLICHE TEILFÄHIGKEIT: Verwende „superpowers:subagent-driven-development“ (empfohlen) oder „superpowers:executing-plans“, um diesen Plan Aufgabe für Aufgabe umzusetzen. Schritte verwenden die Checkbox-Syntax (`- [ ]`) zur Nachverfolgung.

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

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

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

## Globale Einschränkungen

[Die projektweiten Anforderungen aus der Spezifikation – Mindestversionen, Abhängigkeitsgrenzen,
Namens- und Textregeln, Plattformanforderungen – jeweils eine Zeile, wobei die genauen
Werte wörtlich aus der Spezifikation übernommen werden. Die Anforderungen jeder Aufgabe
umfassen implizit diesen Abschnitt.]

---

Aufgabenstruktur

### Aufgabe N: [Name der Komponente]

**Dateien:**
- Erstellen: `genauer/Pfad/zu/Datei.py`
- Ändern: `genauer/Pfad/zu/existing.py:123-145`
- Testen: `tests/genauer/Pfad/zu/test.py`

**Schnittstellen:**
- Verwendet: [Was diese Aufgabe aus früheren Aufgaben nutzt – genaue Signaturen]
- Liefert: [worauf sich nachfolgende Aufgaben stützen – genaue Funktionsnamen, Parameter-
  und Rückgabetypen. Der Implementierer einer Aufgabe sieht nur seine eigene Aufgabe; über diesen
  Block erfährt er die Namen und Typen, die benachbarte Aufgaben verwenden.]

- [ ] **Schritt 1: Den fehlschlagenden Test schreiben**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Schritt 2: Test ausführen, um zu überprüfen, ob er fehlschlägt**

Ausführen: `pytest tests/path/test.py::test_name -v`
Erwartet: FAIL mit „function not defined“

- [ ] **Schritt 3: Minimale Implementierung schreiben**

```python
def function(input):
    return expected
```

- [ ] **Schritt 4: Test ausführen, um zu überprüfen, ob er erfolgreich ist**

Ausführen: `pytest tests/path/test.py::test_name -v`
Erwartet: PASS

- [ ] **Schritt 5: Committen**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: bestimmte Funktion hinzufügen"
```

Keine Platzhalter

Jeder Schritt muss den tatsächlichen Inhalt enthalten, den ein Entwickler benötigt. Folgende Formulierungen sind Fehler im Plan – verwende sie niemals:

• „TBD“, „TODO“, „später implementieren“, „Details ergänzen“
• „Entsprechende Fehlerbehandlung hinzufügen“ / „Validierung hinzufügen“ / „Randfälle behandeln“
• „Tests für das Obige schreiben“ (ohne tatsächlichen Testcode)
• „Ähnlich wie Aufgabe N“ (Wiederholung des Codes – der Entwickler liest die Aufgaben möglicherweise nicht in der richtigen Reihenfolge)
• Schritte, die beschreiben, was zu tun ist, ohne zu zeigen, wie (Codeblöcke für Code-Schritte sind erforderlich)
• Verweise auf Typen, Funktionen oder Methoden, die in keiner Aufgabe definiert sind

Beachten Sie

• Immer genaue Dateipfade angeben
• Vollständiger Code in jedem Schritt – wenn ein Schritt den Code ändert, den Code anzeigen
• Genaue Befehle mit erwarteter Ausgabe
• DRY, YAGNI, TDD, häufige Commits

Selbstüberprüfung

Nachdem du den vollständigen Plan geschrieben hast, betrachte die Spezifikation mit frischem Blick und vergleiche den Plan damit. Dies ist eine Checkliste, die du selbst abarbeitest – kein Auftrag an einen Unteragenten.

1. Spezifikationsabdeckung: Überfliege jeden Abschnitt/jede Anforderung in der Spezifikation. Kannst du eine Aufgabe benennen, die diese umsetzt? Liste eventuelle Lücken auf.

2. Platzhalter-Check: Durchsuche deinen Plan nach Warnzeichen – nach Mustern aus dem obigen Abschnitt „Keine Platzhalter“. Behebe sie.

3. Typenkonsistenz: Stimmen die Typen, Methodensignaturen und Eigenschaftsnamen, die du in späteren Aufgaben verwendet hast, mit denen überein, die du in früheren Aufgaben definiert hast? Eine Funktion namens `clearLayers()` in Aufgabe 3, die in Aufgabe 7 jedoch `clearFullLayers()` heißt, ist ein Fehler.

Wenn du Probleme findest, behebe sie direkt im Code. Eine erneute Überprüfung ist nicht nötig – behebe den Fehler einfach und mach weiter. Wenn du eine Anforderung in der Spezifikation findest, zu der es keine Aufgabe gibt, füge die Aufgabe hinzu.

Übergabe zur Ausführung

Bieten Sie nach dem Speichern des Plans eine Auswahl an Ausführungsoptionen an:

„Plan fertiggestellt und gespeichert unter docs/superpowers/plans/.md. Zwei Ausführungsoptionen:

1. Subagentengesteuert (empfohlen) – Ich setze pro Aufgabe einen neuen Subagenten ein, überprüfe zwischen den Aufgaben, schnelle Iteration

2. Inline-Ausführung – Aufgaben in dieser Sitzung mithilfe von „executing-plans“ ausführen, Batch-Ausführung mit Checkpoints

Welcher Ansatz?“

Wenn „Subagentengesteuert“ gewählt wurde:

• ERFORDERLICHE TEILFÄHIGKEIT: Verwende „superpowers:subagent-driven-development“
• Neuer Subagent pro Aufgabe + zweistufige Überprüfung

Wenn „Inline-Ausführung“ gewählt wurde:

• ERFORDERLICHE TEILFÄHIGKEIT: Superkräfte einsetzen: „Pläne ausführen“
• Batch-Ausführung mit Checkpoints zur Überprüfung