daniel1zz/canon-design

Design (canon)

Design ist erfolgt, wenn eine spätere Sitzung warum (eine Entscheidung, canon/decisions/D-n.md) und was gelten muss (Regeln, canon/rules/<domain>/BR-n.md) lesen kann, ohne jemanden fragen zu müssen. Ein Design, das nur in dieser Unterhaltung lebt, ist verloren.

1. Wähle den Modus

Modus	Lesen	Fokus
architecture	references/mode-architecture.md, references/architecture-patterns.md	Schichten, Grenzen, C4, Migration
api	references/mode-api.md, references/api-design.md	Endpunkte / Befehle, Fehler, Authentifizierung, Paginierung
database	references/mode-database.md, references/database-design.md	Schema, Indizes, Migrationen, Zugriffsmuster
system	references/mode-system.md, references/system-design.md	SLAs, Fehlermodi, Kapazität
module	references/mode-module.md	Verantwortung, Tiefe (Löschtest), Nähte, Abhängigkeitskategorien

Lies nur die Dateien des Modus, den du benötigst. Querschnittsreferenzen (references/cross-cutting/: Autorisierung, Fehlerbehandlung, Idempotenz, Sitzungsidentität) falls das Design diese berührt.

2. Vor dem Design

1. canon context <pfad|domäne|C-n>: die gesamte aktuelle Domäne, ihre Regeln, die akzeptierten Entscheidungen und offenen Änderungen. Das Design darf einer aktiven Regel oder einer akzeptierten Entscheidung nicht widersprechen; falls dies doch nötig ist, sage dies und ändere sie in derselben Änderung.
2. canon search <thema>: frühere Entscheidungen und Notizen zur gleichen Frage. Erweitere oder ersetze (--supersedes D-n), nie stillschweigend wiederhole.
3. Betrachte, wie 1–3 etablierte Produkte oder Bibliotheken das gleiche Problem lösen, bevor du ein eigenes erfindest.
4. Lies den bestehenden Code, den du änderst (Symbole, Aufrufer), bevor du eine Struktur vorschlägst.

3. Design

• Rahme das Problem ein, bevor du Optionen auflistest: Welche Fragen muss dieses Design beantworten, welche Szenarien muss es bedienen? Bei der Bewertung eines bestehenden Designs ist eine Liste seiner Mängel ein Input, nicht der Rahmen: Ein Plan, der nur aus der Mängelliste erstellt wurde, ist ein Patch, kein Design.
• Gib mindestens zwei echte Optionen mit ihren Abwägungen und eine Empfehlung. Echt bedeutet unterschiedliche Designs, nicht ein Design, das mehr oder weniger umgesetzt wird („3 Dinge reparieren“ vs. „10 Dinge reparieren“ ist eine Option). Drei oder mehr Optionen oder mehrere Dimensionen → schreibe die Begründung Dimension für Dimension auf, anstatt eine Vor-/Nachteilsliste aus dem Gedächtnis zu erstellen.
• Bevor du die Empfehlung gibst, lass sie einmal von einem Unter-Agenten herausfordern, der das Problem und die Optionen, aber nicht deine Empfehlung sieht. Frage ihn: Ist die Frage selbst falsch gestellt, fehlt ein wirklich anderes Design, in welchem Szenario versagt jede Option? Gehe auf das ein, was er vorbringt, und gib dann die Empfehlung. Überspringe dies nur bei einem kleinen Design innerhalb eines Moduls, das kein Interface ändert, und sage, dass du es übersprungen hast und warum.
• Überprüfe die offiziellen aktuellen Dokumentationen, bevor du eine Bibliothek, Version oder API vorschlägst.
• Eine Frage, die sich mit einem Wegwerf-Prototyp schneller beantworten lässt als mit Argumentation (Hält dieses Zustandsdiagramm oder Datenmodell im Einsatz stand, welches von mehreren Bildschirmlayouts funktioniert), wird zuerst mit dem canon-prototype-Skill geklärt; das Design zitiert dann, was der Prototyp gezeigt hat.
• Quantifiziere vage Ziele zuerst („schnell“ → p99 unter X ms bei Y rps).
• Jedes Szenario, das das Design bedient, benennt mindestens einen geschäftskritischen Fehler, den es behandeln muss (Limits erreicht, Zahlung abgelehnt, Berechtigung mitten im Fluss entzogen, Ausfall eines vorgelagerten Systems) und wie es laut und erholsam fehlschlägt; „es liegt kein Fehlermodus vor“ muss argumentiert, nicht angenommen werden.
• Wäge die Komplexität jeder Option gegen das ab, was sie kostet, wenn das Szenario eintritt, und stelle jedem Szenario eine Frage: Führen normale Abläufe dazu? Für canon ist das gleichzeitige Arbeiten und Ausliefern mehrerer Sitzungen normal; wie ein Test es reproduzieren könnte, ist nicht entscheidend. Eine Situation, die ein anormales Setup oder eine anormale Aktion erfordert (ein Wrapper eines Benutzers um einen Systembefehl, ein nicht standardmäßiges Backend, das niemand nutzt, das Töten eines bestimmten Prozesses mitten im Schritt, feindliche Eingabe, die keine Sicherheitsgrenze überschreitet), wird zu einer bekannten Einschränkung (eine Zeile in den 后果 der Entscheidung oder der Regel), nicht zu einem neuen Mechanismus; Datenverlust, Sicherheit und die Verletzung eines der Versprechen des Projekts (für canon, P1 bis P7 in canon/product.md) sind die Ausnahmen.
• Überprüfe den Entwurf selbst anhand der Prüflisten des Modus. Parallele Prüf-Unter-Agenten (einer pro Prüfliste, siehe Modusdatei) sind optional: jeder beginnt ohne Kontext und kostet zehntausende Token, verwende sie daher nur, wenn der Wirkungskreis groß ist (modulübergreifend, öffentliche API, Datenmigration, Sicherheit).

Qualitätssicherung (alle müssen bestanden werden, oder es muss gesagt werden, welche nicht und warum)

Modus	Prüfungen
architecture	jede nicht-funktionale Anforderung hat eine messbare architektonische Antwort; jede Spannung hat eine Entscheidung mit Begründung; hohe Risiken haben Minderungsmaßnahmen; Migrationsphasen mit Rollback
api	jede Operation hat ihre Fehler; jede Operation hat ihre Authentifizierungsanforderung; Sicherheitsprobleme gelöst oder mit Begründung akzeptiert; Paginierung und Ratenbegrenzungen angegeben
database	alle Fremdschlüssel indiziert; jede Tabelle durch ein Zugriffsmuster begründet; Null-Downtime-Migration für jede Schemaänderung; kein Float für Geld, Zeitzonen bei Zeitstempeln
system	SLA-Ziele (Durchsatz, p99, Verfügbarkeit); kein ungemilderter Single Point of Failure; jede Komponente hat einen Fehlermodus und eine Degradation; Kapazität bei 1×/10×/100×
module	keine Abhängigkeitszyklen; eine klare Verantwortung pro Modul; jedes Modul besteht den Löschtest; keine Naht mit einem einzigen Adapter; öffentliche Oberfläche ausreichend, um als Black Box zu testen; Abhängigkeiten injizierbar

Querschnittsaspekte (jedes Mal bewerten; nur mit einem genannten Grund überspringen)

Aspekt	Wann	Was tun
Sicherheit	Benutzereingabe, Authentifizierung, Speicherung, externe Aufrufe	Verfolge den Datenfluss, liste Bedrohungen und Minderungen auf
Gleichzeitigkeit	Gemeinsamer Zustand, mehrere Sitzungen oder Prozesse	Benenne die Verschachtelung, die es im normalen Gebrauch zerstören könnte, und was sie atomar macht; seltenere sind bekannte Einschränkungen, es sei denn, sie verlieren Daten
Leistung	Latenzempfindliche Pfade, große Datenmengen	Setze ein Budget und zeige, dass das Design es einhält
Beobachtbarkeit	Neue Komponente	Was wird protokolliert oder aufgezeichnet, und wie wird ein Fehler bemerkt?
Datenschutz	PII oder andere Benutzerdaten	Klassifiziere ihre Sensitivität; Verschlüsselung im Ruhezustand und während der Übertragung; Aufbewahrungsfrist und Löschung; Prüfpfad, wer liest oder ändert

4. Zeichne das Design auf

1. Entscheidung für jede echte Wahl: canon decision new --title "..." → fülle 背景 (Fakten, Daten), 方案 (jede Option markiert mit 采用 oder 否决 mit Begründung, mindestens eine von jeder), 决定, 后果. Schreibe es auf Chinesisch (canon/-Dokumente sind Chinesisch). Zitiere unter den Optionen, woher die Fakten stammen, eine Zeile pro Quelle: - 来源：<URL oder Repository-Pfad> "<wörtliches Zitat, 8+ Zeichen>" — recherchiere zuerst die externe Praxis, dann zitiere sie; eine neue Entscheidung benötigt mindestens eine Quelle, und das Landen holt jede neue Quelle ein und lehnt sie ab, es sei denn, das Zitat ist tatsächlich vorhanden. Füge keine selbstbewerteten Noten oder Konfidenzniveaus hinzu: niemand kann sie überprüfen.
2. Regeln für jedes Verhalten, zu dem das Design das Produkt verpflichtet: canon rule new --domain <d> --title "...". Eine Regel = ein Auslöser und ein Ergebnis; fülle 规则 und 例子 mit konkreten Eingaben auf beiden Seiten der Grenze. Ein Verhalten, das diese Änderung nicht implementiert (ihr Code kommt in einem späteren Schritt des Plans), erhält status: planned im Front Matter der Regel: es benötigt 规则 und 例子, aber keinen Test, und die Änderung, die es implementiert, listet es unter rules: auf und macht es aktiv. Verankere in den 例子 einer geplanten Regel nur die Grenzen, die das Design festlegt; die Randfälle, die die Implementierung findet, werden von dem Schritt hinzugefügt, der sie implementiert.
3. Änderungsdatei (canon/changes/C-n.md): 为什么 / 要改什么 mit Verweis auf die Entscheidung und die Regeln.
4. Wenn das Design einen Container (einen Laufzeitteil, wo seine Daten leben) oder einen Hauptablauf ändert, aktualisiere canon/architecture.md in derselben Änderung: es beschreibt das System, wie es jetzt ist, jeder Teil endet mit seinen Entscheidungsnummern. Überprüfe seine Entscheidungsnummern auf das, was du gerade entschieden hast: eine ersetzte oder geänderte bedeutet eine Zeile zum Umschreiben.
5. Lande wie gewohnt (canon work land). Die Regelprüfung liest die Entscheidung und die Regeln gegen die gesamte Domäne und die Übersicht; behebe, was sie blockiert.

Kein separates Dokument pro Design: Schnittstellen, die es wert sind, vor der Implementierung festgelegt zu werden (Typen, Befehlssignaturen, Schema) kommen in die Änderungsdatei oder den Code selbst.