XeroBis/website

Planen und Dokumentieren

Warum

Anfragen wie „Portiere Karten“ oder „Füge Tags zum Portfolio hinzu“ lesen sich wie endgültige Entscheidungen, verbergen aber normalerweise ungeklärte Optionen: Wie viel soll jetzt gebaut werden, was soll aus dem alten Repo übernommen, geändert oder weggelassen werden, welches Schema besitzt die Daten, was gehört in @shared. Sofortiges Bauen riskiert, das Falsche zu tun, es noch einmal zu machen oder von einer bereits in documentation/decisions.md festgehaltenen Entscheidung abzuweichen. Zuerst zu fragen stellt sicher, dass die Docs – und später der Code – eine genaue Aufzeichnung dessen sind, was der Benutzer tatsächlich möchte.

Wann dies gilt

Jede Anfrage, die etwas ändern würde, das documentation/ verfolgt: eine Funktion oder ein benutzersichtbares Verhalten, ein Schema/eine Tabelle/eine Spalte/eine Geschäftsregel, eine Technologie- oder Bibliothekswahl, die Ordner-/Architekturstruktur oder ein Schritt von migration-plan.md. Kleine, vollständig spezifizierte Bearbeitungen („Korrigiere diesen Tippfehler“, „Benenne dieses Label genau in X um“) benötigen das Interview nicht – verwende dein Urteilsvermögen, wie viel tatsächlich mehrdeutig ist.

Schritte

1. Vor dem Fragen lesen. Überfliege die Abschnitte in documentation/*.md, die sich auf die Anfrage beziehen (und den relevanten Code). Beim Portieren lies auch die Docs des alten Repos (../<repo>/documentation/, ../<repo>/CLAUDE.md) und den zu portierenden Code. Frage nicht etwas, das bereits beantwortet wird. Verwende sie als Grundlage für deine Fragen.

2. Stelle klärende Fragen mit AskUserQuestion. Bevorzuge mehrere kleine, konkrete Fragen anstelle einer großen allgemeinen. Gute Ziele für dieses Repo:

   • wie viel jetzt vs. später gebaut werden soll;
   • beim Portieren: was aus der alten App beibehalten, geändert oder weggelassen werden soll (altes Verhalten ist nicht automatisch gewünscht);
   • welches Schema neue Tabellen besitzt (eine eigene App, oder core, wenn jede App sie braucht);
   • ob ein Teil in eine App oder in @shared / ein gemeinsames Backend-Modul gehört;
   • UX-Details, die features.md festhalten müsste, und die Form neuer Daten.

   Gib jeder Frage eine empfohlene Standardeinstellung, damit der Benutzer schnell vorankommen kann.

3. Halte dich genau an den vom Benutzer zurückgegebenen Umfang. Wenn er auf „nur Docs“ oder „nur X, nicht Y“ eingrenzt, mache nicht stillschweigend mehr – bestätige erneut, bevor du den Umfang später erweiterst.

4. Aktualisiere die Docs im selben Schritt wie die Entscheidung, gemäß der Tabelle in CLAUDE.md:

   • Ordnerstruktur, Umgebungen, Ports, Anfragefluss → architecture.md
   • Schemas, Tabellen, Spalten, Beziehungen, Geschäftsregeln → data-model.md, unter dem entsprechenden Schema-Abschnitt
   • Technologie-/Bibliotheks-/Architekturentscheidung → decisions.md: ein datierter Eintrag, der angibt, was gewählt wurde, gegenüber was und warum, im Stil dieser Datei
   • Benutzersichtbares Verhalten, Validierungsregeln → features.md, unter dem entsprechenden App-Abschnitt
   • Alles, was zurückgestellt, ausgeschlossen oder noch eine bloße Möglichkeit ist → ideas.md
   • Portierungsfortschritt → Spalte „Status“ in migration-plan.md
   • Änderungen am Produktions-Runbook → deployment.md

5. Verschiebe erledigte Ideen aus ideas.md. Wenn eine Änderung einen Eintrag in ideas.md in eine tatsächliche Entscheidung verwandelt, entferne oder überschreibe diesen Eintrag, anstatt ein veraltetes Duplikat zu hinterlassen.