rtaffe28/arch-plan

Architektur-erster Plan

Der Plan beantwortet vor allem zwei Fragen: Welche Teile gibt es und wie verbinden sie sich (Diagramme), und Was sind die genauen Verträge zwischen ihnen (Schnittstellen). Aufgabenlisten sind zweitrangig; ein kompetenter Implementierer kann sie aus guten Schnittstellen ableiten.

Pläne sind lokal und persönlich: ~/plans/<JJJJ-MM-TT>-<slug>/. Die Markdown-Datei ist die Quelle der Wahrheit. Das Artefakt ist eine Ansicht davon.

1. Anforderung verstehen

• Formuliere das Ziel in ein oder zwei Sätzen sowie, was explizit nicht zum Umfang gehört.
• Falls Anforderungen mehrdeutig sind, frage nach (siehe Fragen stellen unten). Frage nur, was das Design ändern würde. Wiederhole die Runde, wenn die Antworten neue Verzweigungen eröffnen.
• Wenn eine gute Standardeinstellung davon abhängt, was der Code bereits tut, führe zuerst einen schnellen Durchlauf von Schritt 2 durch, damit deine Empfehlungen auf dem Repository basieren und nicht geraten sind.

Fragen stellen

Jede Frage an den Benutzer – in diesem Schritt, nach der Debatte und während der Iteration – erfolgt über das AskUserQuestion-Tool, niemals als Liste im Chat. Der Benutzer sollte die meisten mit einem Klick beantworten können:

• Empfehlung vorausfüllen. Mache die Option, die du wählen würdest, zur ersten, mit (Empfohlen) am Ende ihres Labels. Orientiere dich an den bestehenden Mustern der Codebasis, an AGENTS.md und daran, was das Design am einfachsten hält.
• 2–4 konkrete Optionen pro Frage, jede eine echte Wahl, mit einer Beschreibung, die sagt, was sie für das Design bedeutet (z.B. „fügt eine Migration hinzu“, „verwendet useCursorFeed erneut“). Füge keine „Andere“-Option hinzu: Das Tool fügt eine für Freitext hinzu.
• In sich geschlossen. Der Benutzer sieht möglicherweise nur den Dialog, daher benennt jede Frage die Funktion und die zu entscheidende Sache und sagt kurz, was du gefunden hast, falls dies die Frage motiviert.
• Bis zu 4 Fragen pro Aufruf, mit einem kurzen header-Chip pro Frage (≤12 Zeichen, z.B. „Speicher“, „Auth“, „Umfang“). Fasse verwandte Fragen zusammen; mache einen weiteren Aufruf für den Rest.
• Verwende multiSelect nur, wenn Optionen sich nicht ausschließen (z.B. „welche Oberflächen bekommen das?“). Verwende preview beim Vergleich konkreter Artefakte: einer Schnittstellenskizze, einem Schema, einem ASCII-Layout.
• Wenn du eine klare Antwort hast und die Wahl leicht rückgängig zu machen ist, frage nicht: Entscheide und dokumentiere es in der Entscheidungstabelle.

2. Kontext sammeln

Im Haupt-Checkout oder im Worktree des Stacks:

• Lies zuerst CLAUDE.md, AGENTS.md und .claude/rules/*. Sie kodieren Entscheidungen, die du nicht widersprechen darfst.
• Finde heraus, was existiert: die Typen, Dienste, Routen, Tabellen, Jobs und Komponenten, die die Funktion berührt oder wiederverwenden könnte. Für einen breiten Überblick führe parallele Explore-Agenten aus, einen pro Bereich, und behalte nur ihre Schlussfolgerungen.
• Notiere jede bestehende Schnittstelle, die du erweitern wirst, mit ihrem Pfad:Zeile.

3. Größe bestimmen

	Klein	Groß
Anzeichen	Ein Bereich der Codebasis, ungefähr ein PR (unter ~400 Zeilen), keine Migration oder eine triviale	Mehrere Bereiche, Schemaänderungen, neue Hintergrundjobs, mehr als ein PR oder mehrere Personen oder Sitzungen
Ausgabe	Nur plan.md	plan.md plus slices/01-<name>.md, slices/02-<name>.md, ...

Zerkleinere kleine Arbeiten nicht. Formalismus bei einer Änderung für einen PR ist Verschwendung.

Bei großen Arbeiten schneide vertikale Scheiben: Jede Scheibe ist für sich allein mergebar, lässt main funktionsfähig und liefert etwas Testbares. Eine reine Schema-„Scheibe“ oder eine „Frontend-Scheibe“ ist keine Scheibe. Ordne die Scheiben nach Abhängigkeiten und halte jede etwa in der Größe eines PR.

4. Den Plan schreiben

~/plans/<Datum>-<slug>/plan.md:

# <Titel>

**Status:** Entwurf | Genehmigt | In Arbeit | Erledigt
**Größe:** Klein | Groß (N Scheiben)
**Repo / Basis:** phave-ng @ <Commit>

## Ziel
<2–3 Sätze> · **Nicht im Umfang:** <Aufzählungspunkte>

## Architektur
### Komponenten
<Mermaid-Flussdiagramm: vorhandene Teile in schlichtem Stil, neue Teile hervorgehoben, geänderte Teile markiert>
### Wichtige Abläufe
<Mermaid-Sequenzdiagramm für jeden wichtigen Ablauf, einschließlich des Hauptfehlerpfads>
### Datenmodell
<Mermaid-ER-Diagramm, wenn sich Tabellen oder Spalten ändern; Zustandsdiagramm, wenn etwas einen Lebenszyklus hat>

## Schnittstellen
<Jeder Vertrag, den die Funktion hinzufügt oder ändert, als echter Code in der Sprache des Repos.
 Markiere jeden als NEU oder GEÄNDERT, mit seinem Zieldateipfad.>
- Typen / Domänenmodelle
- Funktionen und Dienste: vollständige Signaturen, plus was sie werfen
- HTTP / Server-Aktionen: Methode, Pfad, Anfrage- und Antworttypen, Authentifizierung, Fehlercodes
- Datenbank: Tabellen, Spalten, Indizes, RLS-Richtlinie, Migrationsname
- Jobs / Ereignisse: Name, Payload-Typ, Idempotenz, Wiederholungen
- UI-Komponenten: Props und welche Seite sie rendert

## Wichtige Designentscheidungen
| Entscheidung | Optionen erwogen | Gewählt | Warum |

## Offene Fragen
- [ ] <Frage> — wer sie beantworten kann und was sich je nach Antwort ändert

## Scheiben        (nur groß)
| # | Scheibe | Liefert | Abhängig von | Status |

## Plan (nur klein)
<Geordnete Schritte; für jeden: die Schnittstellen, die er implementiert, Dateien und wie er getestet wird>

## Teststrategie
<Was wird unit-getestet und was wird gegen einen Stack getestet (siehe `ai-test` / `manual-test`)>

## Risiken

Jede slices/0N-<name>.md enthält: Ziel, die Schnittstellen aus plan.md, die sie implementiert (verlinken, nicht kopieren), Dateien, geordnete Schritte, Abnahmekriterien, Tests und Implementierungshinweise (leer gelassen, von implement-plan ausgefüllt).

Regeln:

• Diagramme sind Mermaid, mit einer Idee pro Diagramm. Wenn eines mehr als ~12 Knoten benötigt, teile es auf.
• Schnittstellen sind Code, kein Text. Nenne echte Dateien. Verwende vorhandene Typen, wo möglich, und sage dies.
• Jede Entscheidung, die ein vernünftiger Entwickler anders treffen könnte, kommt in die Entscheidungstabelle.
• Unbekanntes kommt in die Offenen Fragen, jeweils mit der Antwort, die du empfehlen würdest. Rate nicht stillschweigend.

5. Kritiker / Verteidiger Debatte

Starte zwei Agenten parallel mit dem Agent-Tool. Gib jedem den Planpfad und die wichtigsten Repo-Dateien zum Lesen, nicht deine Schlussfolgerungen:

• Kritiker: „Finde, was falsch ist. Erfüllt das Design das Ziel? Fehlen Schnittstellen, sind sie undicht oder inkonsistent mit den Mustern der Codebasis? Sind die Scheiben nicht wirklich vertikal? Gibt es einen überentwickelten oder unter spezifizierten Teil, eine verpasste Wiederverwendung, einen Fehlermodus, ein Migrationsrisiko, eine Berechtigungslücke? Melde jedes Problem mit einer konkreten Lösung.“
• Verteidiger: „Mache den stärksten Fall für die Entscheidungen des Plans, insbesondere dort, wo die naheliegende Alternative verworfen wurde. Nenne, was der Kritiker wahrscheinlich angreifen wird und warum das aktuelle Design Bestand hat.“

Dann eine Erwiderungsrunde: Sende jedem Agenten die Ausgabe des anderen (SendMessage) und bitte ihn, jeden Punkt zuzugeben oder zu verteidigen, mit Gründen.

Du bist der Richter. Für jeden Streitpunkt:

• Zugestimmte Änderung: Wende sie auf plan.md / Scheibendateien an.
• Ungeklärt und benötigt den Benutzer: Verschiebe es in Offene Fragen, mit der Option, die du empfehlen würdest.
• Abgelehnt: Behalte die Entscheidung und dokumentiere in der Entscheidungstabelle, warum.

Hänge eine ## Debattenzusammenfassung an plan.md an: Punkt → Kritiker → Verteidiger → Lösung.

6. Als Artefakt präsentieren

Lade artifact-design und artifact-diagramming für die Diagramme. Veröffentliche eine Seite zur Überprüfung, in dieser Reihenfolge:

1. Titel, Status, Größe und eine einleitende Zusammenfassung
2. Wichtige Designentscheidungen (die Tabelle)
3. Offene Fragen: was du vom Benutzer benötigst, hervorgehoben und leicht zu finden
4. Architekturdiagramme, gerendert, nicht als roher Mermaid-Text
5. Schnittstellen, als hervorgehobener Code, nach Schichten gruppiert, mit NEU / GEÄNDERT Abzeichen
6. Scheiben (groß) oder Schritte (klein)
7. Höhepunkte der Debatte: nur die Punkte, die den Plan geändert haben oder noch offen sind
8. Der lokale Pfad von plan.md

Gebe im Chat den Link. Frage dann die offenen Fragen mit AskUserQuestion (siehe Fragen stellen), jeweils mit den Positionen des Kritikers und des Verteidigers als Optionen und deiner Empfehlung zuerst.

7. Iterieren bis zur Genehmigung

Die Antworten und Kommentare des Benutzers gehen zuerst in plan.md: beantwortete Fragen wandern von Offenen Fragen in die Entscheidungstabelle. Neue Fragen, die während der Iteration aufkommen, werden auf die gleiche Weise gestellt, mit AskUserQuestion und einer empfohlenen Option. Veröffentliche dann dasselbe Artefakt erneut (gleicher Dateipfad, damit die URL gleich bleibt). Wenn der Benutzer genehmigt, setze Status: Genehmigt und verweise auf implement-plan.

Schreibe in diesem Skill keinen Produktcode.