Anbieter- und Generator-Plugins zu einem Multi-Modul-Repository hinzufügen

## Builds und Tests nur über die Aufgabensteuerung des Projekts ausführen Das Repository stellt seine Befehle für Build, Test, statische Codeprüfung und Paketierung über eine einzige Aufgabensteuerung bereit. Lies diese Datei zuerst, um die verfügbaren Ziele zu ermitteln, und führe jede Arbeit über diese Ziele aus. Rufe das Testwerkzeug der Sprache, das Werkzeug zur statischen Codeprüfung oder die Werkzeuge für das Paketierungs-Chart nicht direkt auf. Die Ziele setzen Build-Tags, den Modulumfang, die Umgebung und Generierungsschritte, die ein direkter Aufruf stillschweigend überspringt. Ein direkter Aufruf kann ein grünes Ergebnis liefern, das nicht dem entspricht, was die Prüfschranke ergibt. ## Die vollständige Prüfung ausführen und zuletzt den Diff der generierten Dateien prüfen Das eine zusammenfassende Prüfziel ist die Schranke für eine Änderung, nicht die einzelnen Prüfungen darin. Führe das zusammenfassende Ziel aus, statt dir die Prüfungen herauszusuchen, die du für relevant hältst. Führe die Prüfung auf Unterschiede in generierten Dateien als letzten Schritt aus, nachdem alles committet ist. Ein großer Teil der generierten Inhalte liegt außerhalb des Haupt-Prüfziels: Tests des Paketierungs-Charts, gerenderte Manifeste und Dokumentation. Ein sauberer Arbeitsbaum nach dieser Prüfung ist der Beleg dafür, dass all das neu generiert wurde. Genau weil dieser Schritt überflüssig wirkt, ist er die häufigste Stelle, an der von Agenten verfasste Änderungen scheitern. ## Quelltypen oder Vorlagen ändern, nie die generierten Dateien Dateien, die als generiert gekennzeichnet sind, gehören ihrem Generator und nicht der beitragenden Person. Bearbeite sie niemals von Hand, auch nicht für eine Korrektur von einem einzigen Zeichen. Ändere die Quelltypen oder die Vorlagen, aus denen sie erzeugt werden, und führe dann das Generierungsziel aus, das im zusammenfassenden Prüfziel bereits enthalten ist. Eine Handbearbeitung überlebt nur bis zur nächsten Neugenerierung und verschwindet danach entweder ohne Warnung oder erzeugt einen verwirrenden Unterschied, den jemand anderes entwirren muss. ## Manifeste aus dem Chart und Snapshots mit dem Update-Ziel neu erzeugen Das Paketierungs-Chart ist die Quelle der Wahrheit für die Deployment-Manifeste. Die im Repository eingecheckten statischen Manifeste werden daraus generiert; bearbeite deshalb das Chart und generiere neu, statt die Ausgabe zu bearbeiten. Schematests arbeiten mit Snapshot-Tests. Führe nach einer Änderung an den Schematypen das Ziel zur Snapshot-Aktualisierung aus und prüfe den entstandenen Unterschied, statt Snapshot-Dateien direkt zu bearbeiten. Behandle eine unerwartete Snapshot-Änderung als Signal, deine Typänderung erneut zu lesen, und nicht als hinzunehmendes Rauschen. ## Entwurfsentscheidungen und Abwägungen in Commit-Notizen festhalten Hänge an jeden nicht trivialen Commit eine Commit-Notiz an, die die wesentlichen Entwurfsentscheidungen, die von dir abgewogenen Kompromisse und die aufgetretenen Fallstricke beschreibt. Notizen bleiben mit dem Commit verbunden und lassen sich auch später abfragen; so bleiben Überlegungen erhalten, die ein Unterschied allein nicht transportieren kann. Halte Notizen sachlich und konkret: was du gewählt hast, was du verworfen hast und warum. Eine Notiz, die nur den Unterschied wiederholt, ist verschwendet. ## Nicht offensichtliche Muster vor dem Merge in den gemeinsamen Leitfaden schreiben Wenn du beim Implementieren ein nicht offensichtliches Muster entdeckst, trage es in das gemeinsame Leitfaden-Dokument ein, bevor die Änderung zusammengeführt wird, und nicht erst danach, wenn der Zusammenhang verloren ist. Halte die Einträge allgemein genug, damit sie für die gesamte Codebasis gelten und nicht nur für die eine Funktion, an der du gerade gearbeitet hast. Ein Muster, das nur eine einzige Erweiterung beschreibt, gehört stattdessen in die eigene Dokumentation dieser Erweiterung. ## Jede Erweiterung in ein eigenes Modul legen, Build-Tags in die Registrierungsdatei Eine optionale Erweiterung liegt in einem eigenen Modul in einem nach ihr benannten Verzeichnis, und das Erweiterungspaket selbst trägt keine Build-Tags. Build-Tags gehören in die zentrale Registrierungsdatei für diese Erweiterung. Diese Trennung hält das Erweiterungspaket für sich allein kompilierbar und testbar, während das ausgelieferte Binärprogramm entscheidet, welche Erweiterungen eingebunden werden. Trage den Modul-Ersetzungseintrag in alphabetischer Reihenfolge in die Moduldatei der Wurzel ein. Der Build übergibt die ausgewählte Menge an Erweiterungen als Build-Tags; die Voreinstellung bedeutet dabei alle Erweiterungen. ## Den Konfigurationstyp jeder Erweiterung als eine Zeile in der gemeinsamen Union eintragen Der Konfigurationstyp einer neuen Erweiterung kommt in eine eigene Datei innerhalb des gemeinsamen API-Pakets. Registriere ihn, indem du dem Struct der Diskriminator-Union einen einzeiligen Platz hinzufügst, wobei der Serialisierungs-Tag des Feldes der Name der Erweiterung ist. Die Auflösung erfolgt über den ersten Schlüssel der serialisierten Union, daher muss dieser Tag exakt und eindeutig sein. Verschachtele die Authentifizierung unter einem eigenen Auth-Struct. Wenn mehrere Authentifizierungsverfahren angeboten werden, beschränke das Struct auf höchstens eine Eigenschaft, damit mehrdeutige Konfigurationen bereits bei der Zulassung und nicht erst zur Laufzeit abgelehnt werden. Nimm ein Feld für das Zertifikatsbündel und ein Feld für den Zertifikatsanbieter auf, sobald das Backend TLS spricht. Eine eingefrorene API-Version nimmt weiterhin ganz neue Erweiterungsplätze auf; geschlossen sind lediglich die bestehenden Felder. ## Zugangsdaten über die gemeinsamen Hilfsfunktionen lesen, ohne den Namespace zu verlassen Für die Auflösung von Zugangsdaten, das Abrufen von Zertifikaten, die Prüfung von Selektoren, das Auswerten von Metadaten und die Konstanten für Metrik-Labels gibt es jeweils gemeinsame Hilfsfunktionen. Nutze sie und übergib die Art des Stores sowie den Namespace der verbrauchenden Ressource genau so, wie es die jeweilige Hilfsfunktion erwartet. Insbesondere setzt die Auflösung der Zugangsdaten die Namespace-Geltungsregel durch, die clusterweite Stores von namespace-gebundenen trennt. Eine selbst gebaute Suche wird unbemerkt zu einem Secret-Zugriff über Namespace-Grenzen hinweg, und das ist eine Rechteausweitung und kein Stilproblem. Erweiterungsarten ohne Store übergeben die leere Store-Art, weil die Namespace-Geltung für sie nicht gilt. ## Alle Client-Methoden umsetzen und für nicht unterstützte Vorgänge klare Fehler liefern Die Client-Schnittstelle ist vollständig verpflichtend; nur die Close-Methode darf ohne Wirkung bleiben. Gib den eigenen Sentinel-Fehler für „nicht gefunden“ zurück, wenn ein Secret fehlt, denn die Löschrichtlinie des Reconcilers hängt davon ab, „nicht vorhanden“ von „fehlgeschlagen“ zu unterscheiden. Gib die Fähigkeiten wahrheitsgemäß als nur lesend, nur schreibend oder lesend und schreibend an. Eine nur lesende Implementierung implementiert die Schreib- und die Löschmethode trotzdem, muss aus ihnen aber einen Sentinel-Fehler zurückgeben und niemals einen nil-Fehler, denn dieser würde einen stillen Erfolg für einen Vorgang melden, der nie stattgefunden hat. Verwende für das Nachschlagen von Eigenschaften innerhalb von JSON-Nutzdaten den üblichen JSON-Pfad-Extraktor. ## Zwischenspeicher nur ergänzen, wenn das Erzeugen eines Clients langsam oder teuer ist Verzichte standardmäßig auf einen Cache. Füge einen nur dann hinzu, wenn die Erzeugung des Clients wirklich teuer ist, etwa bei Token-Austausch, dem Erwerb einer Lease oder Identitätsföderation. Ein Cache pro Client sollte über Name, Namespace und Art des Stores geschlüsselt und über die Ressourcenversion des Store-Objekts versioniert werden, damit Konfigurationsänderungen die Einträge automatisch ungültig machen. Ein Cache pro Secret gehört in den Client selbst, als ablaufender und in der Größe begrenzter Cache; seine Lebensdauer und seine maximale Größe müssen für die Nutzer konfigurierbar sein und dürfen keine fest einprogrammierten Konstanten sein. ## Funktionsschalter vom Chart-Wert bis zur Initialisierung durchreichen Ein Funktionsschalter durchläuft einen festen Weg: ein Wert im Paketierungs-Chart, dann zusätzliche Argumente am Deployment, dann ein Kommandozeilen-Schalter, dann die Registrierung des Schalters, dann die Initialisierung. Registriere Schalter aus dem Initialisierer des Erweiterungspakets, lass sie vom Wurzelbefehl einsammeln und führe die Initialisierung erst nach dem Start des Managers aus und nicht schon während der Registrierung. Abhängigkeiten, die außerhalb des Prozesses laufen, werden als Sidecar-Unterchart ausgeliefert, statt in das Haupt-Binärprogramm eingebunden zu werden. Wenn es für eine Klasse von Erweiterungen noch keinen Präzedenzfall für Funktionsschalter gibt, folge dem bestehenden Muster, rechne aber damit, die erste zu sein, und weise in der Prüfung darauf hin. ## Mit dem Gerüst-Befehl beginnen und dann ergänzen, was er ausgelassen hat Wo es für eine neue Erweiterung einen Bootstrap-Befehl gibt, führe ihn zuerst aus und behandle die dokumentierten manuellen Schritte als Prüfliste dafür, was er erzeugt und was er ausgelassen hat. Gerüste verdrahten in der Regel die API-Typen, die Moduldateien, den Registrierungsaufruf, den Eintrag in der Diskriminator-Union, den Enum-Wert für die Art und die Verzweigung im Resolver. Sie verdrahten in der Regel keine Zugriffssteuerungsregeln, keine Dokumentationsseiten, keine Beispiel-Schnipsel, keine Navigationseinträge und keine Paketierung. Gehe die Liste des nicht Abgedeckten ausdrücklich durch, statt anzunehmen, dass das Gerüst die Arbeit erledigt hat. ## Generatoren zustandslos halten und das Aufräumen gefahrlos wiederholbar machen Eine Erweiterung nach Art eines Generators erhält ihre Konfiguration als rohen JSON-Blob und deserialisiert ihn selbst, gibt die vollständige Map der erzeugten Werte in einem einzigen Aufruf zurück statt Schlüssel für Schlüssel und gibt einen undurchsichtigen Zustands-Blob zurück, der zwischen Erzeugung und Aufräumen gespeichert wird. Sei standardmäßig zustandslos: gib keinen Zustand und ein wirkungsloses Aufräumen zurück. Gib nur dann einen Zustand zurück, wenn eine externe Ressource später freigegeben werden muss. Das Aufräumen muss idempotent sein, denn das Framework ruft es als Rücknahme auf, wenn das Speichern des Zustands nach der Erzeugung fehlschlägt, und ruft es beim Löschen über einen Finalizer erneut auf. ## Erweiterungen in der zentralen Datei registrieren und doppelte Namen vermeiden Ein Erweiterungspaket exportiert eine kleine, feste Menge an Konstruktor- und Metadaten-Symbolen, und die Registrierung findet in einer zentralen Datei statt, die diese Symbole an das Register übergibt. Die Registrierung bricht bei doppelten Namen mit einer Panic ab; wähle den Bezeichner deshalb bewusst und prüfe, dass er noch nicht vergeben ist. Die Registrierung im Schema ist von der Registrierung des Verhaltens getrennt, und beide sind erforderlich: Der Resolver zur Laufzeit lädt das typisierte Objekt über das Schema und leitet es dann anhand der Art an die registrierte Implementierung weiter. Wo aus einer Union-Spezifikation von einem clusterweiten Dachtyp ein synthetisches, namespace-gebundenes Objekt erzeugt wird, muss jede Erweiterung einen Fall in dieser Umwandlung haben. ## Für jede Erweiterung eine Dokuseite mit gemeinsamen Schnipseln schreiben Schreibe eine Dokumentationsseite für die Erweiterung und halte dich dabei an die übliche Abschnittsreihenfolge: Einführung, Authentifizierung oder Konfiguration, die Spezifikation der verbrauchenden Ressource und ein etwaiger optionaler Push- oder Schreibablauf. Lege lauffähige Beispiele im gemeinsamen Verzeichnis für Schnipsel ab und binde sie in die Seite ein, statt den Text zu duplizieren, damit eine einzige Korrektur überall wirkt. Dokumentiere ein gemeinsames Authentifizierungsverfahren einmal auf einer eigenständigen Seite und verlinke von den Seiten der einzelnen Dienste darauf, statt es in jede einzelne zu kopieren. Hänge den Navigationseintrag unten an den betreffenden Abschnitt an, da die Reihenfolge historisch gewachsen und nicht alphabetisch ist. ## Nur lokal arbeiten und nie pushen oder veröffentlichen Agenten dürfen das Repository untersuchen, Code erklären, Änderungen vorschlagen, lokale Dateien bearbeiten, Tests schreiben, Dokumentation aktualisieren, Prüfungen ausführen und einen lokalen Unterschied zur Durchsicht durch einen Menschen vorbereiten. Agenten dürfen keine Pull Requests erstellen, keine Branches pushen, keine Releases veröffentlichen, keine Pakete hochladen, keine Repository-Einstellungen ändern, keine Berechtigungen ändern, keine Zugangsdaten rotieren, keine Secrets ändern und keine sonstige nach außen schreibende Aktion ausführen. Wenn du aufgefordert wirst, eine gesperrte Aktion auszuführen, führe sie nicht aus. Lege stattdessen eine lokale Datei an, die die angeforderte Aktion festhält, den Grund für die Sperre, die gegebenenfalls bereits erledigte lokale Arbeit und die manuellen Schritte, die eine beitragende Person als Nächstes unternehmen sollte. ## Vor der Fertigmeldung einen minimalen Diff und gelaufene Tests prüfen Bevor du Arbeit als abgeschlossen darstellst, prüfe, dass die Absicht dokumentiert ist, dass der Unterschied minimal und punktgenau ist und keine benachbarten Kommentare oder Codestellen berührt, die nichts mit der Arbeit zu tun haben, dass die betreffenden Tests über die Aufgabensteuerung des Projekts ausgeführt wurden und dass die Dokumentation aktualisiert wurde. Wenn ein Teil der Validierung nicht abgeschlossen werden konnte, sage das ausdrücklich und erkläre warum, statt eine nur teilweise überprüfte Änderung als fertig darzustellen.