Ein typisiertes Monorepo ändern, ohne es zu beschädigen, und sein Wiki aktuell halten

## Vor der Änderung betroffene Pakete, Tests und Dokumente finden Behandeln Sie die Agentenleitlinie im Wurzelverzeichnis als gemeinsamen Vertrag für alle Programmieragenten. Werkzeugspezifische Anweisungsdateien sollen schlank bleiben und auf diesen Vertrag verweisen, statt ihn zu wiederholen. - Ermitteln Sie, wo sich Kernpakete, optionale Anbindungen, Entwicklungswerkzeuge, Ökosystemmodule, Beispiele, Dokumentation und Tests befinden. - Gehen Sie davon aus, dass Tests und Prüfdaten nahe bei dem geprüften Paket liegen, sofern das Repository nichts anderes festlegt. - Lesen Sie die nächstgelegene Paketleitlinie, bevor Sie ein Teilsystem bearbeiten. - Verfolgen Sie eine angeforderte Änderung bis zu ihrem zuständigen Paket, ihrer öffentlichen Schnittstelle, ihren Tests und ihrer Dokumentation, bevor Sie Dateien anfassen. - Beschränken Sie sich auf den kleinsten betroffenen Bereich; machen Sie aus einer gezielten Aufgabe keine Neufassung des gesamten Repositorys. ## Den Paketmanager und die Skripte des Repositorys verwenden Verwenden Sie die Paketverwaltung, Arbeitsbereichsdefinition, Laufzeitversion und Skripte, die das Repository vorgibt. Ersetzen Sie diese nicht allein deshalb durch eine vertraute Alternative, weil sie lokal installiert ist. - Richten Sie den Arbeitsbereich mit dem dokumentierten Installationsbefehl ein. - Verwenden Sie für vollständige Prüfungen die Skripte `build`, `test`, `lint` und `type-check` im Wurzelverzeichnis. - Nutzen Sie unterstützte Arbeitsbereichsfilter für Arbeiten an einzelnen Paketen. - Bewahren Sie die Argumentweitergabe exakt, wenn ein Hüllskript Optionen an ein untergeordnetes Werkzeug übermittelt. - Prüfen Sie die Konfigurationsdateien des Repositorys, bevor Sie Annahmen über Paketverwaltung oder Laufzeitumgebung ändern. - Halten Sie jede Voraussetzung fest, von der ein enger gefasster Befehl abhängt. ## Tests in der CI-Reihenfolge ohne veraltete Build-Dateien ausführen Bilden Sie die Reihenfolge der kontinuierlichen Integration nach, statt eine eigene lokale Abfolge zu erfinden. Wenn die CI Abhängigkeiten installiert und ihren Prüfbefehl ohne vorherige Erstellung ausführt, führen Sie die Tests in derselben Reihenfolge aus. - Erstellen Sie nicht zuerst die Erzeugnisse, wenn generierte Ausgaben zusammen mit Quelldateien gefunden werden können. - Betrachten Sie Fehler wegen doppelter Registrierung, doppelter Schemata oder doppelt geladener dekorierter Klassen als möglichen Hinweis darauf, dass Quell- und generierte Dateien zugleich geladen wurden. - Entfernen Sie ausschließlich Verzeichnisse mit generierten Ausgaben unter den dokumentierten Quellwurzeln und schließen Sie Abhängigkeiten, Tests und Prüfdaten aus. - Löschen Sie niemals Quellverzeichnisse, um einen Fehler durch generierte Ausgaben zu beheben. - Führen Sie den fehlgeschlagenen Test nach der Bereinigung erneut aus, bevor Sie den Implementierungscode ändern. - Wenn die Bereinigung den Fehler nicht verändert, setzen Sie die normale Fehlersuche mit den neuen Erkenntnissen fort. ## Den vorhandenen Code-Stil befolgen und App-Zustand nicht global ablegen Bevorzugen Sie bewährte Muster des Repositorys gegenüber neuen Abstraktionen. Verwenden Sie das bereits eingeführte Modulsystem, die Konventionen der typisierten Sprache, Formatierungs- und Prüfwerkzeuge sowie das bestehende Dateinamensschema. - Schreiben Sie Dateinamen klein und mit Bindestrichen, wenn dies der Repositorykonvention entspricht. - Ändern Sie öffentliche APIs nur bewusst, sichern Sie die Änderung durch Tests ab und dokumentieren Sie sie. - Bewahren Sie veränderlichen anwendungsspezifischen Laufzeitzustand in einem anwendungseigenen Gültigkeitsbereich statt in einem prozessweiten Singleton auf. - Verwenden Sie den bereichsgebundenen Speicher des Rahmensystems für Lebenszyklus-Hilfsfunktionen und andere anwendungsbezogene Dienste. - Betreten Sie bei losgelösten Rückrufen wie Zeitgebern, Ereignisempfängern, Proxy-Handlern und Ausstiegspunkten auf Modulebene erneut den Gültigkeitsbereich der zugehörigen Anwendung. - Fügen Sie Zugriffsfunktionen, die bereits an den richtigen Anwendungskontext gebunden sind, keine überflüssigen Bereichshüllen hinzu. ## Beim Start geladene Module für Start-Snapshots geeignet halten Wenn eine Laufzeitumgebung ein Startabbild serialisieren kann, nehmen Sie an, dass der Startvorgang während der Erstellung noch vor dem normalen Anwendungsstart enden kann. Jedes in dieser Phase geladene Modul muss sicher serialisierbar sein. - Halten Sie Module extern, wenn Arbeiten beim Importieren oder Starten nicht serialisierbaren nativen Zustand erzeugen. - Behandeln Sie HTTP-Parser, HTTP/2-Anbindungen, TLS-Kontexte, DNS-Kanäle, WebAssembly-Instanzen, Dateiwächter, native Erweiterungen und offene Sockets als risikoreiche Abhängigkeiten für Startabbilder. - Leiten Sie extern gehaltene Module durch die Ladebrücke der Laufzeitumgebung für den Wiederherstellungszeitpunkt. - Pflegen Sie genau eine dokumentierte Standardliste der Module, die verzögert geladen oder extern gehalten werden müssen. - Erweitern Sie diese Liste über die unterstützte Konfiguration des Repositorys, statt generierte Ausgaben nachträglich zu verändern. - Unterscheiden Sie die direkte Erzeugung nativen Zustands von transitiver Netzwerknutzung: Verzögert externalisierte eingebaute Module können transitive Abhängigkeiten bereits schützen; ein Paket, das nativen oder WebAssembly-Zustand direkt erzeugt, muss dennoch ausdrücklich behandelt werden. - Ergänzen Sie einen Erstellungstest für Startabbilder, wenn eine Abhängigkeit des Rahmensystems beim Start auf den nativen Stapel oder den Netzwerkstapel zugreifen kann. ## Globale Typerweiterungen in eigenen Typmodulen bündeln Legen Sie paketweite globale Typerweiterungen in einem eigenen globalen Typmodul ab. Gemeinsam genutzte Erweiterungen für mehrere Pakete gehören in ein gemeinsames Typenpaket und nicht in ein einzelnes verbrauchendes Paket. - Halten Sie Deklarationsdateien durch ein `import`, ein reines Typ-`import` oder ein leeres `export` als Module kenntlich. - Importieren Sie die gemeinsame Erweiterung über den Paketeinstiegspunkt, der diese Typoberfläche benötigt. - Vermeiden Sie umgebungsweite Deklarationen, die nur deshalb global werden, weil einer Datei die Modulsyntax fehlt. - Testen Sie nach dem Verschieben gemeinsamer Typen sowohl das definierende Paket als auch mindestens ein verbrauchendes Paket. - Dokumentieren Sie jede Änderung an der öffentlichen Typoberfläche. ## Passende Tests ausführen und den finalen Diff vor dem Bericht prüfen Führen Sie zuerst die engsten Prüfungen aus, die das geänderte Verhalten belegen, und erweitern Sie den Umfang nur, wenn die betroffene Grenze dies erfordert. - Ergänzen Sie Regressionstests bei Änderungen an Ladern, Anwendungslebenszyklus, Clusterbetrieb, Agenten, HTTP-Verarbeitung oder Prozessverhalten. - Führen Sie Formatierung, `lint`, Typprüfung und die einschlägigen Tests über die Repositoryskripte aus. - Verwenden Sie die Konvention des Repositorys für Commit-Nachrichten und halten Sie den Geltungsbereich präzise. - Erläutern Sie in der Änderungsbeschreibung Beweggrund, geändertes Verhalten, Risiko und Testnachweise. - Prüfen Sie den abschließenden Änderungssatz auf sachfremde Bearbeitungen, generiertes Rauschen und nicht dokumentierte öffentliche Änderungen. - Melden Sie keinen Erfolg, bevor der einschlägige Befehl erfolgreich abgeschlossen wurde. ## Keine Geheimnisse committen und vor dem Veröffentlichen von Sicherheitslücken anhalten Lesen Sie die Sicherheitsrichtlinie des Repositorys, bevor Sie an Schwachstellen arbeiten. Übertragen Sie niemals Geheimnisse, Zugangsdaten, nicht öffentliche Endpunkte oder maschinenspezifische Konfiguration in das Repository. - Stimmen Sie die lokalen Versionen von Laufzeitumgebung und Paketverwaltung auf die Repositoryvorgaben ab. - Behandeln Sie Abhängigkeits-Sperrdateien und Arbeitsbereichskonfiguration als aufeinander abgestimmte Eingaben; ändern Sie sie nur für eine beabsichtigte Aktualisierung von Abhängigkeiten oder Werkzeugkette. - Verwenden Sie in Beispielen und Dokumentation Platzhalter statt echter Zugangsdaten oder nicht öffentlicher URLs. - Begrenzen Sie sicherheitsrelevante Änderungen eng und ergänzen Sie Regressionstests für die geschützte Grenze. - Halten Sie vor der Veröffentlichung von Schwachstellendetails oder vor Änderungen an geschützten externen Systemen an, sofern die Aufgabe diese Handlung nicht ausdrücklich erlaubt. ## Code und andere Quellen, Wiki und KI-Regeln getrennt halten Pflegen Sie drei klar getrennte Wissensebenen. Unbearbeitete Quellen liefern maßgebliche Nachweise, das Wiki speichert dauerhafte Zusammenfassungen, und die Agentenleitlinie im Wurzelverzeichnis definiert gemeinsame Ablaufregeln. - Behandeln Sie Code, benutzerbezogene Dokumentation, Projektdateien im Wurzelverzeichnis, ausdrücklich benannte externe Artefakte und importiertes Rohmaterial als Quellnachweise. - Nutzen Sie Wiki-Zusammenfassungen zur ersten Orientierung, prüfen Sie jedoch Details, Widersprüche und Aktualität anhand der unbearbeiteten Quellen. - Schreiben Sie unbearbeitete Quellen nur um, wenn die Aufgabe dies verlangt. - Übernehmen Sie wiederholt benötigte externe Nachweise in den Wissensbestand des Repositorys. - Halten Sie Widersprüche ausdrücklich fest, statt sie zu einem falschen Konsens zu glätten. - Halten Sie werkzeugspezifische Agentendateien schlank und lassen Sie sie auf das gemeinsame Schema verweisen. ## Jeder Wiki-Seite ein Thema und ihre Quelldateien geben Geben Sie jeder inhaltlich wesentlichen Wissensseite genau ein klares Thema und einen erklärten Seitentyp wie `package`, `concept`, `workflow`, `decision` oder `source`. - Verwenden Sie kleingeschriebene Dateinamen mit Bindestrichen. - Fügen Sie Kopfmetadaten mit einem menschenlesbaren Titel, dem Seitentyp, einer einzeiligen Zusammenfassung, den wichtigsten Quellpfaden, dem lokalen Kalenderdatum und dem Aktualitätsstatus ein. - Belegen Sie jede nicht triviale Aussage mit nachvollziehbaren Quelldateien. - Kennzeichnen Sie nicht offensichtliche Zusammenfassungen als Schlussfolgerung. - Markieren Sie Aussagen als veraltet oder ungeklärt, wenn ihre Aktualität unsicher ist. - Halten Sie das Wiki-Inhaltsverzeichnis knapp und nach Kategorien geordnet. - Verwenden Sie für umfangreiche Aufnahmen, dauerhafte Erkenntnisse, wesentliche Umstrukturierungen und Änderungen am dokumentierten Verständnis ein nur ergänzbares Protokoll. - Protokollieren Sie keine bloßen Tippfehlerkorrekturen. ## Vor dem Einpflegen von Quellen oder dem Beantworten von Fragen den Wiki-Index lesen Verwenden Sie einen vorhersehbaren Ablauf für die Aufnahme von Quellen, die Beantwortung von Repositoryfragen und die formale Prüfung des Wissensbestands. - Lesen Sie bei einer Aufnahme zuerst das Inhaltsverzeichnis, suchen Sie vorhandene Seiten, welche das Material aufnehmen sollen, erstellen oder aktualisieren Sie bei Bedarf eine Seite des Typs `source`, aktualisieren Sie betroffene Seiten und das Inhaltsverzeichnis und ergänzen Sie bei wesentlichen Änderungen einen Protokolleintrag. - Lesen Sie bei Anfragen zuerst das Inhaltsverzeichnis und die einschlägigen Wiki-Seiten, prüfen Sie sie anhand unbearbeiteter Quellen, schreiben Sie neue dauerhafte Erkenntnisse zurück und protokollieren Sie wesentliche Wissensänderungen. - Prüfen Sie bei der formalen Prüfung auf verwaiste Seiten, veraltete Aussagen, doppelte Konzepte, fehlende Quellenverweise, fehlende Seiten für häufig bearbeitete Bereiche und Widersprüche. - Strukturieren Sie sich überschneidende Seiten lieber neu, als sie unbegrenzt zu verlängern. - Geben Sie dauerhaftem Wissen über grundlegende Pakete, Anbindungen, Werkzeuge, Lebenszyklusverhalten, Ladevorgänge, Tests, Veröffentlichungsarbeit und Dokumentationspflege Vorrang. ## Das Wiki nur aktualisieren, wenn sich APIs oder Arbeitsabläufe ändern Aktualisieren Sie den Wissensbestand, wenn Arbeiten öffentliche APIs, Dokumentationsstruktur, Paketverantwortlichkeiten, Architektur, wiederkehrende Abläufe für Mitwirkende, Testerwartungen oder Veröffentlichungsverfahren wesentlich verändern. - Vermeiden Sie unnötige Wiki-Änderungen bei einer reinen Codeänderung, die das dauerhafte Verständnis nicht verändert. - Aktualisieren Sie die Leitlinie für Mitwirkende in derselben Änderung, wenn eine neue Regel allgemein gilt. - Halten Sie Quellpfade und Aktualitätsdaten mit den von ihnen belegten Tatsachen synchron. - Ergänzen Sie nur dann einen Protokolleintrag, wenn die Wissensänderung für künftige Arbeiten erheblich genug ist. - Prüfen Sie die endgültige Dokumentation anhand des implementierten Verhaltens, bevor Sie die Fertigstellung melden.