Spec-first-dev
DDD, um Dinge zu benennen, BDD, um sie zu spezifizieren, die kleinste Änderung, um sie zu erfüllen, und Nachweise, um sie zu belegen. Stack-agnostisch.
1. Denken vor dem Codieren
- Annahmen formulieren. Wenn die Anfrage unklar ist oder mehrere Lesarten zulässt, benennen Sie sie und fragen Sie nach. Niemals stillschweigend eine auswählen.
- Wenn es einen einfacheren Ansatz gibt, sagen Sie dies und lehnen Sie den komplizierteren ab.
- Lesen Sie den Code, den die Aufgabe berührt. Listen Sie alles auf, was die Änderung erreichen muss (Aufrufer, Tests, Fixtures, Konfiguration, Exporte) und was sie beschädigen könnte (zerstörte oder offengelegte Daten, Aufrufer, die nicht mehr funktionieren). Das ist der Umfang; zusätzliche Funktionen sind nicht enthalten. Nennen Sie übersprungene Extras in einer Zeile.
- Vor dem ersten Schreiben von main abzweigen mit einem Namen, der zur Arbeit passt (z. B.
feat/<feature>,fix/<bug>). Schreibgeschützte Arbeit benötigt keinen Branch.
2. Die Domäne modellieren (DDD)
Notieren Sie vor dem Code in wenigen Zeilen:
- Bounded Context und seine ubiquitäre Sprache: die Begriffe, die die Domänenexperten verwenden. Verwenden Sie die vorhandenen Begriffe der Codebasis wieder; fügen Sie neue nur hinzu, wenn nötig.
- Aggregat und seine Invarianten: was immer wahr sein muss.
- Namen in Code, Tests und Nachrichten verwenden diese Begriffe. Lehnen Sie generische Namen ab (
handle,process,manager,utils). - Domänenlogik ist rein über einfache Daten. I/O (DB, Netzwerk, Uhr, Zufall) sitzt hinter einem Port am Rand, injiziert.
Speichern Sie es unter docs/specs/<feature>.md.
Überspringen Sie dies für triviale Änderungen, die kein Domänenkonzept hinzufügen.
3. Verhalten spezifizieren (BDD)
Schreiben Sie Given/When/Then-Szenarien in Domänensprache, eines pro Verhalten, einschließlich der Rand- und Fehlerfälle. Jedes beschreibt beobachtbares Verhalten, nicht Implementierung. Holen Sie die Zustimmung des Benutzers für nicht offensichtliche Szenarien ein; sie sind der Vertrag. Speichern Sie sie unter docs/features/<feature>.feature.
4. Planen
Für mehrschrittige Arbeit schreiben Sie einen kurzen Plan nach docs/plans/<feature>.md: jeder Schritt mit seinem Verifikationscheck. Wenn Sie von einer vorhandenen Spezifikation aus fortsetzen, schreiben Sie trotzdem zuerst den Plan. Halten Sie dann inne und bitten Sie den Benutzer, ihn zu überprüfen; führen Sie niemals aus, bevor er zustimmt. Wählen Sie die erste Option, die vollständig funktioniert:
- Muss es existieren? Wenn nicht, überspringen Sie es.
- Bereits in dieser Codebasis vorhanden? Verwenden Sie es, wie der umgebende Code es tut.
- Standardbibliothek oder Plattformfunktion? Verwenden Sie es.
- Installierte Abhängigkeit? Verwenden Sie es. Fügen Sie niemals eine für ein paar Zeilen hinzu.
- Eine Zeile, die ein Leser auf einen Blick versteht? Verwenden Sie es.
- Andernfalls der minimale Code, der funktioniert.
5. Ausführen
Orchestrierung
Wenn Sie Aufgaben ausführen, mit oder ohne Spezifikation oder Plan, prüfen Sie, ob sie passen: mehrere trennbare Elemente (z.B. 3+ Korrekturen), unabhängige Schritte oder Schritte mit deutlich unterschiedlichem Schwierigkeitsgrad. Wenn ja, lesen Sie orchestration.md (neben dieser Datei) und fragen Sie vor der ersten Bearbeitung nach seinen beiden Optionen (via AskUserQuestion): im selben Durchlauf wie die Planüberprüfung, wenn Sie einen Plan schreiben, sonst sofort. Fragen Sie immer; keine andere Genehmigung (Plan, Spezifikation, "ok") gilt als Auswahl. Wenn die Aufgaben nicht passen, führen Sie sie inline aus.
Rot, grün, refaktorisieren, pro Szenario
- Wandeln Sie ein Szenario in einen fehlschlagenden Test um. Führen Sie ihn aus; sehen Sie, dass er aus dem richtigen Grund fehlschlägt.
- Schreiben Sie den minimalen Code, der besteht. Führen Sie ihn aus.
- Refaktorisieren Sie nur das, was diese Änderung unordentlich gemacht hat.
- Fehlerbehebung: Reproduzieren Sie zuerst mit einem fehlschlagenden Szenario, durchsuchen Sie jeden Aufrufer der Funktion, beheben Sie die Grundursache einmal im gemeinsamen Code.
6. Halten Sie den Diff chirurgisch
- Berühren Sie nur das Nötigste. Passen Sie den vorhandenen Stil an; verbessern Sie keinen benachbarten Code. Jede geänderte Zeile geht auf die Anforderung zurück.
- Entfernen Sie nur Waisen, die Ihre Änderung geschaffen hat; erwähnen Sie anderen toten Code, löschen Sie ihn nicht.
- Keine Abstraktion, kein Wrapper, keine Option, keine Konfiguration oder "für später"-Code, den niemand verlangt hat. Löschen ist besser als Hinzufügen.
- Code, den Sie verschieben, behält seine Fehlerbehandlung und Validierung.
- Kommentieren Sie nur das Warum, in einer Zeile. Eine bekannte Einschränkung erhält
shortcut: <die Einschränkung>, <wann aktualisieren>. - Niemals kürzen: Validierung an Vertrauensgrenzen, Fehlerbehandlung, die Datenverlust verhindert, Sicherheit, Barrierefreiheit, alles, was der Benutzer verlangt hat.
7. Vor dem Abschluss verifizieren
Führen Sie die Tests und alle Build- oder Typprüfungen aus. Lesen Sie die Ausgabe. Melden Sie echte Ergebnisse; wenn etwas fehlgeschlagen ist oder nicht ausgeführt wurde, sagen Sie es. Kein "sollte funktionieren".
8. Antworten
Beenden Sie mit ein oder zwei Zeilen: was Sie übersprungen oder nicht geprüft haben, und jedes Risiko, das der Benutzer kennen muss.