LaiAnTan/agentic-setup

Design before building (Entwurf vor dem Bauen)

Agenten sind schnell beim Implementieren und schlecht darin, zu bemerken, dass ein Design verfällt. Die Lösung ist, sich vor der Codeerstellung auf Entscheidungen zu einigen, sodass jeder Pull-Request schnell zu überprüfen ist, weil er dem bereits Genehmigten entspricht. Sie entwerfen jede Phase; der Benutzer prüft und genehmigt sie.

1. Umfang der Arbeit abschätzen und Phasen auswählen

Arbeit	Phasen
Mittlere Funktion, eingegrenzte Refaktorisierung	Programmentwurf → Scheiben
Große Funktion, übergreifende Refaktorisierung	Architektur → Programmentwurf → Scheiben
Neues Projekt, mehrere Repos oder unklares Problem	Produkt → Architektur → Programmentwurf → Scheiben

Geben Sie in einer Zeile an, welche Größe Sie gewählt haben und warum. Der Benutzer kann Phasen hinzufügen oder überspringen.

2. Zuerst Kontext sammeln

Bevor Sie etwas entwerfen: Lesen Sie docs/README.md und die darin verlinkten lebenden Dokumente, alle offenen Entwürfe in docs/designs/, den relevanten Code und die Git-Historie für den Bereich. Für Entscheidungen zwischen Werkzeugen oder Ansätzen recherchieren Sie (Dokumentation, Benchmarks, bekannte Probleme) und geben Sie konkrete Optionen mit Quellen an. Entwerfen Sie nicht auf der Grundlage von Annahmen.

3. Jede Phase durchführen

Erstellen Sie die Designdatei docs/designs/YYYY-MM-DD-<slug>.md aus template.md (richten Sie zuerst das docs/-Layout gemäß den globalen Regeln ein, falls das Repository es nicht hat). Lesen Sie für jede Phase die entsprechende Phasendatei unten (im Ordner dieser Fertigkeit), entwerfen Sie diesen Abschnitt der Designdatei und stoppen Sie dann:

• product.md: Problem, Benutzer, Verhalten, nicht im Umfang
• architecture.md: Komponenten, Verträge, Datenmodell, Einschränkungen
• program-design.md: Typen, Signaturen, Dateilayout, Aufruffluss
• slices.md: Build-Reihenfolge, Repos, Pull-Requests und der Check für jede Scheibe

Wenn Sie stoppen, zeigen Sie dem Benutzer:

• ein Diagramm, wo es hilft, plus eine kurze Zusammenfassung (nicht das gesamte Dokument in den Chat eingefügt)
• die getroffenen Entscheidungen und die offenen Fragen, nummeriert, damit sie mit "2: ja" antworten können

Beginnen Sie erst mit der nächsten Phase, wenn der Benutzer diese genehmigt hat. Wenn der Benutzer etwas ändert, aktualisieren Sie die Designdatei, nicht nur den Chat.

4. Scheibe für Scheibe bauen

Nachdem der Scheibenplan genehmigt ist:

• Bauen Sie jeweils eine Scheibe; jede endet damit, dass der vereinbarte Check erfolgreich ist und der Nachweis erbracht wird.
• Ein Pull-Request (oder Commit, falls der Benutzer keine Pull-Requests verwendet) pro Scheibe, beschrieben gemäß den globalen Regeln.
• Wenn die Implementierung zeigt, dass das Design falsch ist, stoppen Sie und schlagen Sie die Änderung am Design vor, anstatt stillschweigend davon abzuweichen. Aktualisieren Sie die Designdatei, wenn eine Änderung vereinbart ist.
• Haken Sie die Scheiben in der Designdatei ab, wenn sie abgeschlossen sind, damit eine spätere Sitzung von dort fortfahren kann.

5. Abschluss

Wenn die letzte Scheibe abgeschlossen ist, führen Sie das Ergebnis zurück, damit die lebenden Dokumente die Quelle der Wahrheit bleiben:

• Aktualisieren Sie die docs/product.md, docs/architecture.md und alle Themendokumente des Repos (nicht die Phasendateien dieser Fertigkeit), um das System so zu beschreiben, wie es jetzt ist, und folgen Sie dabei den Dokumentationsregeln der globalen Regeln.
• Fügen Sie alle neuen schwierigen oder projektspezifischen Begriffe zu docs/glossary.md hinzu.
• Machen Sie jede bedeutende Entscheidung zu einem docs/decisions/NNNN-<slug>.md-Hinweis.
• Markieren Sie die Designdatei als erledigt und fügen Sie sie zu docs/README.md hinzu. Überschreiben Sie sie danach nicht.
• Zeigen Sie dem Benutzer, was sich in den lebenden Dokumenten geändert hat.