Coding-Regeln
22 Regelsätze mit 84 Gruppen. Ein Projekt schaltet einen Satz in docs/project/coding_rules.md ein; Gruppen-IDs CR-<set>-<name> sind stabil.
Coding-Regeln — Bash
Quelle: .act/coding/bash.md
Kurzfassung: Strict Mode, Quoting, Exit-Codes, Fehlermeldungen, shellcheck, Fallstricke
Regeln für Bash-Skripte. Gruppen-IDs (CR-bash-<name>) sind stabil und werden nie neu vergeben; eine
Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-bash-basics
Abschnitt betitelt „CR-bash-basics“Strict Mode, Quoting, Fehlerbehandlung, shellcheck
Kurzfassung: set -euo pipefail, Quoting, bewusste Exit-Codes, Fehler auf stderr, shellcheck, Fallstricke
- Jedes Skript beginnt mit
set -euo pipefailals erster ausführbarer Zeile. - Variablen konsequent quoten (
"$var"), besonders Pfade, die Leerzeichen enthalten können. - Exit-Codes bewusst setzen (
exit 0/exit 1/bestimmte Codes), statt den Status des letzten Befehls stillschweigend durchzureichen. - Argumente und Eingaben vor der Verwendung prüfen (Anzahl, ob ein Pfad existiert); Fehler auf stderr melden und benennen, was woran gescheitert ist — nicht nur ein pauschales „Fehler“.
shellcheckals Standard-Linter des Stacks vor jedem Commit ausführen; dessen Warnungen nicht pauschal unterdrücken.- Fallstricke:
- Die Ausgabe von
lsnie in einer Schleife auswerten — Globbing oderfind ... -print0mitread -d ''verwenden. - Das Ergebnis von
cdprüfen (cd dir || exit 1); sonst laufen die folgenden Befehle im falschen Verzeichnis.
- Die Ausgabe von
CR-bash-script-shape
Abschnitt betitelt „CR-bash-script-shape“Ein Skript, ein Zweck
Kurzfassung: Kopfkommentar, Funktionen statt Duplikation, Skripte mit nur einem Zweck
- Mit einem Kopfkommentar beginnen, der Zweck, einen Beispielaufruf und die erwartete Ausgabe bzw. das Exit-Verhalten nennt.
- Wiederverwendbare Abschnitte als Funktionen schreiben, statt dieselbe Befehlsfolge zu kopieren.
- Ein Skript, ein klar benannter Zweck — kein Mehrzweck-Skript mit Modus-Flags für unzusammenhängende Aufgaben.
Coding-Regeln — C
Quelle: .act/coding/c.md
Kurzfassung: Sprachstandard, Speicherbesitz und Puffer, geprüfte Rückgabewerte, Undefined Behavior, Warnungen und Sanitizer
Regeln nur für C; sie gelten nicht für C++, dessen Idiome sich unterscheiden (RAII, Container, Exceptions) und
das einen eigenen Satz hat. Gruppen-IDs (CR-c-<name>) sind stabil und werden nie neu vergeben; eine Gruppe,
deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-c-basics
Abschnitt betitelt „CR-c-basics“Standard, Build und Warnungen
Kurzfassung: fester Sprachstandard, strenge Warnungen als Fehler, clang-tidy, Build-System wie konfiguriert
- Den C-Standard aus der Build-Konfiguration nehmen (
-std=c11,c17,c23oderCMAKE_C_STANDARD) und nichts Neueres verwenden:nullptr,constexpr,boolals Schlüsselwort undtypeofgibt es erst in C23;_Generic,_Static_assertund<threads.h>brauchen C11. Ohne konfigurierten Standard C11 annehmen. - Keine C++-Gewohnheiten in C schreiben: kein Cast des
malloc-Ergebnisses, keinbool/trueohne<stdbool.h>vor C23, und parameterlose Funktionen alsf(void)deklarieren, nicht alsf(). - Warnungen ernst nehmen (
-Wall -Wextra; MSVC/W4): eine im Code beheben, nicht mit einem Cast oder einem Pragma zum Schweigen bringen.-Werror(/WX) einmal vorschlagen; Build-Flags nie ungefragt setzen (R-code-tools). clang-tidyals üblichen Linter undclang-formatals üblichen Formatter ausführen, oder was das Projekt konfiguriert hat (R-code-tools); beim vorhandenen Build-System bleiben (CMake, Make, Meson) und keines ungefragt installieren.
CR-c-memory
Abschnitt betitelt „CR-c-memory“Puffer und Besitz
Kurzfassung: jeder Puffer trägt seine Größe, ein Besitzer pro Allokation, keine unbegrenzten String-Funktionen
- Einen Puffer zusammen mit seiner Größe übergeben und die Größe vor dem Schreiben prüfen; nie
gets,strcpy,strcatodersprintfin einen Puffer fester Größe —snprintfundmemcpymit ausdrücklicher Länge verwenden und Strings selbst abschließen, wo die Funktion es nicht tut (strncpy). - Das Ergebnis jedes
malloc/calloc/reallocvor der Verwendung aufNULLprüfen.reallocschreibt in eine temporäre Variable, damit der alte Zeiger bei einem Fehlschlag nicht verloren geht. - Allokationsgrößen aus dem Ziel berechnen (
malloc(n * sizeof *p)) und die Multiplikation vorher auf Überlauf prüfen (callocübernimmt das). - Jede Allokation hat genau einen Besitzer, benannt in einem Kommentar oder im Kopfkommentar der Funktion:
wer sie freigibt und wer sie nur borgen darf. Einmal freigeben, den Zeiger danach auf
NULLsetzen, wo er im Gültigkeitsbereich bleibt, und auf jedem Fehlerpfad freigeben (ein einzigergoto cleanup-Ausgang ist das anerkannte Idiom). - Nie einen Zeiger auf eine lokale (Stack-)Variable zurückgeben oder speichern.
CR-c-correctness
Abschnitt betitelt „CR-c-correctness“Rückgabewerte und Undefined Behavior
Kurzfassung: keine ignorierten Fehler, Integer-Überlauf, signed/unsigned und Strict Aliasing
- Den Rückgabewert jedes Aufrufs prüfen, der scheitern kann (
fopen,fread,fwrite,fclose, Abschneiden beisnprintf,read/write,pthread_*); eine Fehlermeldung nennt den Aufruf, sein Argument underrno(strerror). - Ein Überlauf bei vorzeichenbehafteten Ganzzahlen ist Undefined Behavior: die Operanden vor der Rechnung
prüfen, nicht danach.
size_tfür Größen und Indizes verwenden und signed nie ohne ausdrückliche Umwandlung mit unsigned vergleichen. Schiebeweiten, Division durch null undINT_MIN / -1prüfen. - Ein Objekt nicht über einen Zeiger eines unverträglichen Typs lesen (Strict Aliasing) und keine
uninitialisierte Variable; für Type Punning
memcpyverwenden und bei der Deklaration initialisieren. - Ungenutzte Parameter und Durchfallen im
switchausdrücklich kennzeichnen ((void)x;, ein Kommentar oder in C23[[fallthrough]]), nicht stillschweigend.
CR-c-tests
Abschnitt betitelt „CR-c-tests“Tests unter Sanitizern
Kurzfassung: Tests laufen mit ASan und UBSan, Test Runner wie konfiguriert
- Die Test-Suite mindestens einmal mit
-fsanitize=address,undefined -fno-omit-frame-pointerausführen (MSVC:/fsanitize=address); ein Sanitizer-Bericht ist ein Fehlschlag und wird nie unterdrückt, um grün zu werden (R-code-checks-intact). - Das Test-Framework verwenden, das das Projekt eingerichtet hat (Unity, Check, CMocka oder schlicht
ctest); keines ungefragt hinzufügen. Den Fehlerpfad jeder Allokation und jedes I/O-Aufrufs abdecken, nicht nur den Normalfall.
Coding-Regeln — CI
Quelle: .act/coding/ci.md
Kurzfassung: gepinnte Actions, minimale Berechtigungen, injektionssichere Workflows, Secrets, Caching und Concurrency für GitHub Actions und GitLab CI
Regeln für Pipeline-Definitionen: GitHub Actions (.github/workflows/*.yml) und GitLab CI
(.gitlab-ci.yml). Eine Pipeline läuft mit den Secrets und dem Schreibzugriff des Projekts, daher erweitern
diese Regeln die Sicherheitsregeln (R-safe-no-secret-log, R-safe-no-secret-cli, R-safe-approval).
Gruppen-IDs (CR-ci-<name>) sind stabil und werden nie neu vergeben; eine Gruppe, deren Zweck nicht mehr
gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-ci-supply-chain
Abschnitt betitelt „CR-ci-supply-chain“Pinnen, was die Pipeline ausführt
Kurzfassung: Actions und Includes auf einen Commit-SHA gepinnt, minimale Token-Berechtigungen, automatische Updates
- GitHub: jede Action eines Dritten auf den vollständigen 40-stelligen Commit-SHA pinnen, die Version als
Kommentar dahinter (
uses: actions/checkout@<sha> # v4.2.2). Einen Tag oder Branch kann sein Eigentümer verschieben, und dann läuft unbemerkt neuer Code in deiner Pipeline. Prüfen, dass der SHA zum Upstream-Repository gehört. - GitLab:
include: project/remoteund CI-Images auf einen Commit-SHA oder einen Image-Digest pinnen, nie aufmainoderlatest. permissions:ganz oben in jedem Workflow aufcontents: readsetzen und pro Job nur erweitern, wo ein Job es braucht (pull-requests: write,id-token: write). Den Standardumfang des Tokens nie der Repository-Einstellung überlassen.- Kurzlebige OIDC-Zugangsdaten (
id-token: write, GitLabid_tokens:) langlebigen Cloud-Schlüsseln vorziehen, die als Secrets liegen. - Pins mit dem Updater des Projekts aktuell halten (Dependabot oder Renovate), nicht von Hand; ein Pin, den niemand aktualisiert, wird zu einer ungepatchten Abhängigkeit.
actions/checkoutmitpersist-credentials: false, außer ein späterer Schritt pusht.
CR-ci-injection
Abschnitt betitelt „CR-ci-injection“Nicht vertrauenswürdige Eingaben erreichen nie eine Shell oder einen privilegierten Lauf
Kurzfassung: keine Event-Daten inline in run:, kein pull_request_target mit Fork-Code, keine Secrets für Forks
- Nie
${{ github.event.* }},github.head_ref, den Titel oder Text eines Issues/PR, einen Branch-Namen oder eine Commit-Nachricht direkt in einrun:-Skript schreiben — der Text wird vor dem Parsen durch die Shell eingesetzt und wird zu Code. Stattdessen überenv:durchreichen und"$VAR"verwenden. GitLab expandiert Variablen zur Laufzeit in der Shell, dort liegt die Gefahr also in unquotierter Verwendung:"$CI_COMMIT_MESSAGE","$CI_MERGE_REQUEST_TITLE"und Branch-Namen inscript:quoten, nie perevalausführen oder in einen Befehl einsetzen. pull_request_targetundworkflow_runlaufen im Kontext des Basis-Repositorys mit Secrets und einem beschreibbaren Token. Dort nie den Head des Pull Requests auschecken oder ausführen (ref: ${{ github.event.pull_request.head.sha }}) und nie dessen Skripte oder Build-Schritt laufen lassen. Für alles, was beigesteuerten Code baut, schlichtespull_requestverwenden.- Fork-Pull-Requests bekommen keine Secrets: keine Prüfung entwerfen, die bei
pull_requesteines braucht; sie in einen unprivilegierten Build und einen getrennten, geprüften privilegierten Schritt aufteilen. - Ein Deploy- oder Release-Job läuft nur auf geschützten Branches und Tags (
if:auf dem Ref, GitLabrules:mit$CI_COMMIT_REF_PROTECTED), hinter der geforderten Freigabe des Environments.
CR-ci-secrets
Abschnitt betitelt „CR-ci-secrets“Secrets bleiben aus Logs, Argumenten und Artefakten heraus
Kurzfassung: Secrets über Secret Store und Umgebung, maskiert, nie ausgegeben, nie in Cache oder Artefakten
- Secrets aus dem Secret Store der Plattform nehmen (GitHub
secrets/Environment-Secrets, GitLab maskierte und geschützte CI/CD-Variablen) und einem Schritt überenv:übergeben, nicht als Argument. - Nie ein Secret oder einen daraus abgeleiteten Wert mit
echoausgeben, und keinset -x/CI-Debug-Trace in einem Job mit Secrets. Einen berechneten Wert mit::add-mask::maskieren, bevor er ausgegeben wird. - Kein Secret in ein Artefakt, einen Cache, ein Build-Argument (
docker build --build-arg) oder einen hochgeladenen Bericht; sie überdauern den Job und sind für mehr Leute lesbar als das Secret. - Ein Secret, das in ein Log gelangt ist, gilt als kompromittiert und wird rotiert, nicht nur aus dem Log gelöscht.
CR-ci-runtime
Abschnitt betitelt „CR-ci-runtime“Caching, Concurrency, Timeouts
Kurzfassung: Caches nach Lockfile benannt, Concurrency-Gruppen, Job-Timeouts, dieselben Prüfungen wie lokal
- Einen Cache über den Hash der Lockfile schlüsseln (
hashFiles('**/package-lock.json'), GitLabcache:key:files), nie über einen festen String; heruntergeladene Abhängigkeiten cachen, nicht die Build-Ausgabe nicht vertrauenswürdiger Branches. concurrency:mitcancel-in-progress: truefür Pull-Request-Prüfungen setzen; nie einen laufenden Deploy oder Release abbrechen — dafür eine Gruppe ohne Abbruch vergeben. GitLab:interruptible: trueundresource_groupfür Deploys.timeout-minutes:(GitLabtimeout:) an jedem Job setzen; der Standard der Plattform liegt bei Stunden.- CI führt dieselben Befehle aus, die das Projekt für die lokale Nutzung dokumentiert (
docs/ai/config.md,R-code-tools) — keine Prüfung, die nur in der Pipeline existiert. Eine fehlschlagende Prüfung wird im Code behoben, nicht übersprungen oder aufcontinue-on-errorgesetzt (R-code-checks-intact). - GitLab:
rules:verwenden, nicht das veralteteonly:/except:.
Coding-Regeln — C++
Quelle: .act/coding/cpp.md
Kurzfassung: Sprachstandard, RAII und Besitz, const und Rule of Zero, Warnungen und Sanitizer, CMake und Tests
Regeln nur für C++; sie gelten nicht für C, dessen Code mit manueller Speicherverwaltung und C-Idiomen
geschrieben wird und das einen eigenen Satz hat. Gruppen-IDs (CR-cpp-<name>) sind stabil und werden nie neu
vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-cpp-basics
Abschnitt betitelt „CR-cpp-basics“Standard, Build und Warnungen
Kurzfassung: Standard aus dem Build, davon abhängige Features, strenge Warnungen, clang-tidy, CMake
- Den Standard aus der Build-Konfiguration nehmen (
CMAKE_CXX_STANDARD,-std=c++17,20,23) und nichts Neueres verwenden. Je Standard:std::optional,std::variant,std::string_viewund Structured Bindings sind C++17; Concepts, Ranges,std::spanundstd::formatsind C++20 (std::formatbraucht zudem eine aktuelle Standardbibliothek);std::expectedundstd::printsind C++23. Ohne konfigurierten Standard C++17 annehmen. - Warnungen ernst nehmen (
-Wall -Wextra -Wpedantic; MSVC/W4): eine im Code beheben, nicht mit einem Cast oder einem Pragma zum Schweigen bringen.-Werror(/WX) einmal vorschlagen; Build-Flags nie ungefragt setzen (R-code-tools). clang-tidyals üblichen Linter undclang-formatals üblichen Formatter ausführen, oder was das Projekt konfiguriert hat (R-code-tools). CMake ist das übliche Build-System; das verwenden, das das Projekt hat (Make, Meson, Bazel), und keines ungefragt installieren.- Kein C in C++ schreiben: kein
malloc/free, keine C-Casts, keinNULL(nullptrverwenden) und keine rohen Arrays, wostd::array,std::vectoroderstd::stringpassen.
CR-cpp-ownership
Abschnitt betitelt „CR-cpp-ownership“RAII, kein rohes new und delete
Kurzfassung: Ressourcen gehören Objekten, Smart Pointer, Rule of Zero
- Jede Ressource (Speicher, Datei, Lock, Handle) gehört einem Objekt, das sie in seinem Destruktor freigibt
(RAII). Kein rohes
new/delete:std::make_unique(Standard) oderstd::make_shared(nur bei wirklich geteiltem Besitz), Container oderstd::lock_guard/std::scoped_lockverwenden. - Ein roher Zeiger oder eine Referenz ist nicht besitzend und geliehen; nie darüber
deleteaufrufen und nie länger als die Lebensdauer des Besitzers behalten. Keine Referenz und keinenstd::string_viewauf eine lokale Variable oder ein Temporary zurückgeben. - Rule of Zero: Eine Klasse, die nur RAII-Member hält, deklariert keine der speziellen Memberfunktionen.
Muss eines von Destruktor, Kopieren oder Verschieben geschrieben werden, alle fünf definieren oder löschen
(Rule of Five); Move-Operationen
noexceptmarkieren. - Exceptions nicht über eine C-Schnittstelle laufen lassen und keinen Thread unbehandelt verlassen lassen;
dem vorhandenen Fehlerstil des Projekts folgen (Exceptions oder
std::expected/Fehlercodes), statt beide zu mischen.
CR-cpp-correctness
Abschnitt betitelt „CR-cpp-correctness“const, Typen und Undefined Behavior
Kurzfassung: const als Standard, explizite Konstruktoren, keine ungeprüften Casts, Invalidierung von Containern
constals Standard für Variablen, Memberfunktionen und Parameter; große schreibgeschützte Argumente perconst&, kleine per Wert übergeben. Konstruktoren mit einem Argumentexplicitund Überschreibungenoverridemarkieren.static_castund Verwandte nur einsetzen, wo nötig; keine C-Casts und niereinterpret_castoder einen Cast, derconstentfernt, ohne einen Kommentar, warum das sicher ist.- Signed-Überlauf,
operator[]außerhalb des Bereichs, Verwendung nach einem Move und die Verwendung eines Iterators nach einer Änderung des Containers sind Undefined Behavior: bei nicht vertrauenswürdiger Eingabe.at()verwenden oder Grenzen prüfen, und ein verschobenes Objekt nur zum Zuweisen wiederverwenden. - Mit geschweiften Klammern oder bei der Deklaration initialisieren;
enum classdem schlichtenenumvorziehen.
CR-cpp-tests
Abschnitt betitelt „CR-cpp-tests“Tests unter Sanitizern
Kurzfassung: GoogleTest oder Catch2 über CTest, ASan und UBSan im Testlauf
- Das Test-Framework verwenden, das das Projekt eingerichtet hat (GoogleTest oder Catch2 sind die übliche
Wahl), ausgeführt über
ctest; keines ungefragt hinzufügen. - Die Suite mindestens einmal mit
-fsanitize=address,undefined -fno-omit-frame-pointerausführen; ein Sanitizer-Bericht ist ein Fehlschlag und wird nie unterdrückt, um grün zu werden (R-code-checks-intact).
Coding-Regeln — C#
Quelle: .act/coding/csharp.md
Kurzfassung: Nullable-Kontext, async-Konventionen, Fehlerbehandlung, Analyzer, DI, Bibliothekscode
Regeln für C#-Projekte. Gruppen-IDs (CR-csharp-<name>) sind stabil und werden nie neu vergeben; eine
Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-csharp-basics
Abschnitt betitelt „CR-csharp-basics“Nullable-Kontext, async, Fehlerbehandlung, Analyzer
Kurzfassung: Nullable aktiviert, Async-Suffix, kein async void, kein Blockieren auf Tasks, using, Exceptions
- Den Nullable-Kontext (
<Nullable>enable</Nullable>) projektweit eingeschaltet lassen; die dabei entstehenden Warnungen nicht unterdrücken. - Asynchrone Methoden mit dem Suffix
Asyncbenennen undTask/Task<T>zurückgeben. async voidnie außerhalb von Event-Handlern verwenden — stattdessenasync Task, sonst werden Exceptions verschluckt..Result/.Wait()auf Tasks vermeiden; wer so auf einen Task blockiert, riskiert in synchronen Kontexten einen Deadlock.- Jede
IDisposable-Ressource ausschließlich überusing/await usingverwalten. - Exceptions für Ausnahmefälle verwenden, nicht für den regulären Kontrollfluss — für erwartbare
Fehlerfälle einen Rückgabetyp (
Result<T>/bool) erwägen; wo immer eine Exception geworfen wird, nennt ihre Meldung, was woran gescheitert ist. dotnet formatund die Analyzer-Regeln (.editorconfig, Abschnittdotnet_diagnostic) als Standard-Linting/statische Analyse des Stacks verwenden; in jedem Projekt einrichten, ausführen, was installiert ist.
CR-csharp-conventions
Abschnitt betitelt „CR-csharp-conventions“var, Records, ein Typ pro Datei
Kurzfassung: var nur bei offensichtlichem Typ, Records für Value Objects, ein öffentlicher Typ pro Datei
varnur verwenden, wenn der Typ aus der rechten Seite offensichtlich ist, sonst den Typ ausschreiben.- Records für unveränderliche Value Objects/DTOs verwenden, Klassen für Objekte mit Identität und Verhalten.
- Ein öffentlicher Typ pro Datei, der Dateiname entspricht dem Typnamen.
CR-csharp-dependency-injection
Abschnitt betitelt „CR-csharp-dependency-injection“Constructor Injection
Kurzfassung: Constructor Injection, kein Service Locator
- Abhängigkeiten über den Konstruktor injizieren; kein versteckter Zugriff über einen Service Locator.
CR-csharp-library-code
Abschnitt betitelt „CR-csharp-library-code“ConfigureAwait in Bibliothekscode
Kurzfassung: ConfigureAwait(false) in Code ohne UI-Kontext
- In Bibliothekscode ohne Abhängigkeit von einem UI-Kontext
ConfigureAwait(false)verwenden.
Coding-Regeln — CSS
Quelle: .act/coding/css.md
Kurzfassung: Custom-Property-Tokens, geringe Spezifität, kein !important, Mobile-first, stylelint
Regeln für handgeschriebenes CSS (und SCSS) in Projekten, die kein Tailwind verwenden. Diesen Satz nicht in
einem Projekt ankreuzen, das tailwind ankreuzt: Utility-Klassen und eine handgeschriebene Kaskade ziehen in
entgegengesetzte Richtungen, und die Regeln unten würden denen von Tailwind widersprechen (@apply,
getrennte CSS-Dateien). Gruppen-IDs (CR-css-<name>) sind stabil und werden nie neu vergeben; eine Gruppe,
deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-css-tokens
Abschnitt betitelt „CR-css-tokens“Design Tokens als Custom Properties
Kurzfassung: ein Ort für Farben, Abstände und Schrift; keine wiederholten Literale; Dark Mode durch Neuzuordnung
- Farben, Abstände, Radien, Schriftgrößen und z-index-Ebenen einmal als Custom Properties auf
:rootdefinieren (--color-surface,--space-2) und sonst überallvar(--…)verwenden; ein Hex-Wert oder13px, der sich in Regelrümpfen wiederholt, ist ein fehlendes Token. - Tokens nach Rolle benennen (
--color-text-muted), nicht nach Wert (--grey-600) oder Ort (--header-blue). - Dark Mode und Themes ordnen dieselben Tokens unter einem Selektor oder
prefers-color-schemeneu zu; nie ein zweiter Satz hartkodierter Farben in parallelen Regeln. var()nur dort einen Fallback geben, wo die Eigenschaft absichtlich fehlen kann, nicht um einen Tippfehler im Namen zu verbergen.
CR-css-cascade
Abschnitt betitelt „CR-css-cascade“Spezifität und die Kaskade
Kurzfassung: flache Selektoren, kein !important, keine ID-Selektoren, Layer für die Reihenfolge, ein Namensschema
- Selektoren flach halten: eine Klasse, höchstens eine weitere Ebene (
.card__title,.nav a). Keine#id-Selektoren, keine Ketten aus drei oder mehr Teilen, keine Klassen mit Elementbezug (div.card). - Kein
!important. Gewinnt eine Regel nicht, die Spezifität der konkurrierenden Regel senken oder die Quellen mit@layerordnen (seit 2022 in allen aktuellen Browsern unterstützt); eine Ausnahme für ein Utility, das gewinnen muss, wird an der Deklaration dokumentiert. - Ein Namensschema wählen (BEM oder was das Projekt schon verwendet) und dabei bleiben; in einer Datei nicht mehrere Schemata mischen.
- Über Klassen stylen, nie über DOM-Struktur, die eine Markup-Änderung brechen würde
(
div > div:nth-child(3)). - Kein
outline: noneohne einen sichtbaren Ersatz über:focus-visible.
CR-css-layout
Abschnitt betitelt „CR-css-layout“Layout und Responsivität
Kurzfassung: Mobile-first mit min-width-Queries, Flex/Grid, relative Einheiten, logische Eigenschaften
- Die Basisregeln für den kleinsten Bildschirm schreiben und für größere
@media (min-width: …)ergänzen; Breakpoints kommen aus Tokens oder einer Liste, nicht aus pro Komponente erfundenen Zahlen. - Flexbox und Grid für das Layout verwenden,
gapfür Abstände zwischen Elementen; keine Floats und keine festen Höhen, die Text abschneiden. - Text und Abstände in
rem/embemessen, nicht inpx, damit die Schrifteinstellungen der Nutzer weiter wirken;pxist für Rahmen und Haarlinien in Ordnung. - Logische Eigenschaften (
margin-inline,padding-block) im neuen Code bevorzugen, wenn das Projekt Rechts-nach-links-Schrift unterstützt. - Aussagen zur Browser-Unterstützung gegen die
browserslistoder die genannten Ziele des Projekts prüfen, bevor ein neues Feature verwendet wird (Container Queries,:has(), Nesting); nicht annehmen, dass die neueste Syntax verfügbar ist.
CR-css-toolchain
Abschnitt betitelt „CR-css-toolchain“Lint- und Format-Tooling
Kurzfassung: standardmäßig stylelint, Formatter des Projekts, SCSS nur wenn das Projekt es schon nutzt
stylelintmit der gemeinsamen Konfiguration des Projekts ist die übliche Wahl des Templates für das Linting,prettierfür die Formatierung — in beiden Fällen ausführen, was das Projekt tatsächlich konfiguriert hat (sieheR-code-tools).- SCSS, PostCSS-Plugins oder eine CSS-in-JS-Bibliothek nicht in ein Projekt einführen, das keine hat; mit nativem Nesting und Custom Properties sind die meisten alten Gründe entfallen.
- In SCSS das Nesting auf höchstens drei Ebenen halten und
@use/@forwardverwenden, nicht@import, das seit Dart Sass 1.80 veraltet ist.
Coding-Regeln — Docker
Quelle: .act/coding/docker.md
Kurzfassung: gepinnte Base Images, Non-root- und Multi-Stage-Builds, Build-Kontext und Secrets, Compose, hadolint
Regeln für Dockerfiles und Compose-Dateien. Gruppen-IDs (CR-docker-<name>) sind stabil und werden nie neu
vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-docker-image
Abschnitt betitelt „CR-docker-image“Gepinntes Base Image, klein und mehrstufig
Kurzfassung: Tag plus Digest, kein latest, Multi-Stage-Build, ein Prozess pro Container, Reihenfolge der Layer und Aufräumen
- Das Base Image mit Tag und Digest pinnen (
FROM python:3.12-slim@sha256:...); nielatestoder einen nackten Major-Versions-Tag allein. Die Sprachversion aus den Projektdateien nehmen (R-code-version), nicht aus Gewohnheit, und den Digest bewusst aktualisieren, nicht durch erneutes Bauen. - In Stufen bauen: Compiler, Dev-Abhängigkeiten und Caches bleiben in einer
builder-Stufe; die letzte Stufe kopiert nur das Ergebnis (COPY --from=builder) in eine schlanke oder distroless Basis. - Layer nach der Seltenheit ihrer Änderung ordnen: zuerst das Abhängigkeits-Manifest kopieren und
installieren, den Quellcode zuletzt, damit eine Codeänderung nicht alles neu installiert. Die Installation
und ihr Aufräumen in einem einzigen
RUNerledigen (apt-get update && apt-get install -y --no-install-recommends ... && rm -rf /var/lib/apt/lists/*), da ein späteresrmeinen früheren Layer nicht verkleinert. COPYdemADDvorziehen; fürCMDundENTRYPOINTdie Exec-Form verwenden (["python", "app.py"]), damit Signale das Programm erreichen; ein Hauptprozess pro Container.
CR-docker-security
Abschnitt betitelt „CR-docker-security“Non-root-Nutzer, keine Secrets in Layern
Kurzfassung: USER gesetzt, .dockerignore, Build Secrets statt ARG/ENV, keine Zugangsdaten im Image
- Als Non-root-Nutzer laufen: ihn anlegen (
RUN useradd --system --uid 10001 app) undUSERvorCMDsetzen; Dateien mit--chownkopieren. Einen Dienst nicht als root laufen lassen, „damit es geht“. - Neben dem Dockerfile eine
.dockerignoreführen, die mindestens.git,.env*, Abhängigkeitsordner (node_modules,.venv), Build-Ausgabe und lokale Daten ausschließt, damit nichts davon in den Build-Kontext oder einen Layer gelangt. - Ein Secret kommt nie in
ARG,ENV,COPYoder einRUN-Argument: Jedes bleibt in der Image-History lesbar (docker history). Für die Build-Zeit einen BuildKit Secret Mount verwenden (RUN --mount=type=secret,id=name ..., übergeben mit--secret), für die Laufzeit die Umgebung oder eine eingebundene Datei (R-safe-no-secret-cli). - Konfiguration, die sich je Umgebung unterscheidet, nicht ins Image einbacken; sie zur Laufzeit übergeben.
CR-docker-compose
Abschnitt betitelt „CR-docker-compose“Compose-Dateien
Kurzfassung: kein version-Key, gepinnte Images, benannte Volumes, Env-Datei außerhalb der Versionsverwaltung, gesunde Abhängigkeiten
- Die Compose Specification verwenden (Docker Compose v2,
docker compose): den veralteten Top-Level-Keyversion:weglassen. Die installierte Version mitdocker compose versionprüfen. - Jedes
image:wie oben pinnen; keinlatest. Volumes benennen statt anonymer zu verwenden, und den Docker-Socket (/var/run/docker.sock) nicht in einen Container einbinden. - Werte und Secrets in einer
.env-Datei oder insecrets:halten, nie incompose.yaml; nur eine.env.examplecommitten. Nur die nötigen Ports veröffentlichen, gebunden an127.0.0.1, außer der Dienst soll von außen erreichbar sein. Ein Host-Port kollidiert mit dem Server des Eigentümers — sieheR-safe-dev-server. - Die Startreihenfolge real machen:
depends_onmitcondition: service_healthyund einemhealthcheck, nicht ein Sleep.
CR-docker-toolchain
Abschnitt betitelt „CR-docker-toolchain“Lint und Build-Prüfungen
Kurzfassung: hadolint für Dockerfiles, docker compose config für Compose, oder was das Projekt eingerichtet hat
hadolintist der übliche Dockerfile-Linter des Templates; Compose-Dateien mitdocker compose config --quietvalidieren. Ausführen, was das Projekt konfiguriert hat, und nichts ungefragt installieren (R-code-tools).- Mit BuildKit bauen (Standard im aktuellen Docker) und das Ergebnis prüfen, indem das Image einmal ausgeführt wird, nicht nur anhand eines grünen Builds.
Coding-Regeln — Go
Quelle: .act/coding/go.md
Kurzfassung: strikte Fehlerprüfung, Werkzeuge für statische Analyse, Paketdesign
Regeln für Go-Projekte. Gruppen-IDs (CR-go-<name>) sind stabil und werden nie neu vergeben; eine
Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-go-basics
Abschnitt betitelt „CR-go-basics“Fehlerbehandlung, Formatierung, statische Analyse
Kurzfassung: Fehler prüfen und wrappen, mit gofmt formatieren, vet/staticcheck ausführen, Panics und Leaks vermeiden
- Jede Datei vor dem Commit mit
gofmt/goimportsformatieren; keine handgepflegte Abweichung von beiden. - Einen Fehler unmittelbar nach dem Aufruf prüfen, der ihn zurückgegeben hat (
if err != nil), statt Fehler für später zu sammeln, und einen Rückgabewert nie mit_verwerfen, wenn er einen ungeprüften Fehler mitbringt. - Fehler mit
%wwrappen (fmt.Errorf("...: %w", err)), damiterrors.Is/errors.Asweiter oben in der Aufrufkette funktionieren; den zugrunde liegenden Fehler nie verlieren oder einebnen. go vetundstaticcheckin der CI als Standard der statischen Analyse des Stacks ausführen — einrichten, aber nur ausführen, was installiert ist; fehlt ein Werkzeug, das einmal sagen und nichts ungefragt installieren.- Keine Panics in Bibliothekscode für erwartbare Fehlerfälle; panic nur bei echten Programmierfehlern.
context.Contextist der erste Parameter jeder Funktion, die Abbruch, eine Deadline oder request-bezogene Werte weitergeben muss.- Jede Goroutine hat ein sichtbares Lebensende (
WaitGroupoder Abbruch über den Context) — eine Goroutine ohne Möglichkeit zu stoppen ist ein Leak. - Zustand, den Goroutinen gemeinsam nutzen, über Channels oder explizite Locks synchronisieren, nie stillschweigend.
CR-go-package-design
Abschnitt betitelt „CR-go-package-design“Kleine Interfaces, keine Sammelpakete
Kurzfassung: Interfaces vom Konsumenten definiert, Pakete nach Domäne benannt und geschnitten
- Interfaces auf der Seite des Konsumenten definieren (klein, oft ein oder zwei Methoden), nicht vorab vom Anbieter, der sie implementiert.
- Pakete mit kurzen, aussagekräftigen Namen nach Domäne schneiden; kein Sammelpaket
util/commonohne eigenen Gegenstand.
Coding-Regeln — Java
Quelle: .act/coding/java.md
Kurzfassung: Nullability, Fehlerbehandlung, Struktur, Toolchain, Tests
Regeln für Java-Projekte. Gruppen-IDs (CR-java-<name>) sind stabil und werden nie neu vergeben; eine
Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-java-basics
Abschnitt betitelt „CR-java-basics“Nullability, Fehlerbehandlung, bekannte Fallstricke
Kurzfassung: explizite Nullability, keine Raw Types, korrekte Exception-Behandlung, sicheres Logging und SQL
- Nullability an Feldern, Parametern und Rückgabetypen explizit machen (JSpecify
@Nullable/@NonNulloder die Alternative, auf die sich das Projekt festgelegt hat), statt sie implizit zu lassen. - Kein rohes
Object, keine Raw Types bei Generics. - Keine leeren
catch-Blöcke und keincatch (Exception e)ohne konkreten Grund; Unchecked Exceptions für Programmierfehler, Checked Exceptions für erwartbare, behebbare Fehler — die Meldung muss nennen, was woran gescheitert ist. - Ressourcen ausschließlich über try-with-resources verwalten.
java.util.concurrent(Executors,CompletableFuture, Concurrent Collections) statt manuellemsynchronized/wait/notifyverwenden.- Über SLF4J loggen, parametrisiert (
log.info("user {} failed", id), nie per String-Konkatenation) — was gar nicht in eine Logzeile gehört, steht inR-safe-no-secret-log. varnur verwenden, wo der Typ aus der rechten Seite offensichtlich ist, sonst den Typ ausschreiben.Optional<T>nur als Rückgabetyp einer Methode für „möglicherweise kein Ergebnis“ zurückgeben — nie als Feld, als Parameter oder innerhalb einer Collection.- Fallstricke:
equals/hashCodenur gemeinsam überschreiben;java.timeverwenden, nieDate/Calendar; für GeldbeträgeBigDecimal, niefloat/double;UTF_8ausdrücklich angeben, sich nie auf den Plattform-Default verlassen; ausschließlich parametrisiertes SQL verwenden, nie per String-Konkatenation gebaute Abfragen; eine einfache Schleife liest sich unter Umständen besser als ein erzwungener Stream. - Statische Analyse ist der Standard des Stacks — einrichten, aber nur ausführen, was installiert ist; fehlt ein Werkzeug, das einmal sagen und nichts ungefragt installieren.
CR-java-modern-idioms
Abschnitt betitelt „CR-java-modern-idioms“Records, Sealed Types, Text Blocks, Virtual Threads
Kurzfassung: moderne Sprachfeatures, meist ab Java 17, Pattern Matching für switch und Virtual Threads ab Java 21
- Records für unveränderliche Datenträger (DTOs, Value Objects) verwenden statt einer handgeschriebenen
Klasse mit Gettern,
equals,hashCodeund Konstruktor — erfordert Java 16 (Records; Preview in 14 und 15). - Sealed Interfaces/Classes statt offener Hierarchien verwenden — erfordert Java 17; mit Pattern Matching
für
switch(switchauf den Typ) stattinstanceof-Ketten — erfordert Java 21 (dort final; in 17 nur Preview). - Text Blocks für mehrzeilige Strings (SQL, JSON-Vorlagen) statt Konkatenation verwenden — erfordert Java 17.
- Virtual Threads nur verwenden, wo die Laufzeit und jede Bibliothek auf dem Weg sie unterstützen — erfordert Java 21.
CR-java-structure
Abschnitt betitelt „CR-java-structure“Paketschnitt, Immutability, Constructor Injection
Kurzfassung: Pakete nach Domäne, Immutability als Standard, Constructor Injection
- Pakete nach fachlicher Domäne schneiden, nicht nach technischer Schicht.
- Sichtbarkeit so eng wie möglich halten, Felder
final, kein Setter ohne Grund — Immutability ist der Standard und der beste Schutz gegen Nebenläufigkeitsfehler. - Constructor Injection statt Field Injection verwenden, auch außerhalb eines DI-Containers.
CR-java-toolchain
Abschnitt betitelt „CR-java-toolchain“Build- und Analysewerkzeuge
Kurzfassung: standardmäßig Maven oder Gradle; statische Analyse mit dem, was das Projekt eingerichtet hat
- Mit Maven oder Gradle bauen — das Projekt entscheidet, womit.
- Formatierung und statische Analyse in der CI erzwingen: Spotless oder google-java-format für die
Formatierung, dazu Checkstyle, SpotBugs, Error Prone oder PMD — die übliche Wahl des Templates; ausführen,
was das Projekt tatsächlich eingerichtet hat (siehe
R-code-tools).
CR-java-tests
Abschnitt betitelt „CR-java-tests“Standardmäßig JUnit 5 mit AssertJ
Kurzfassung: standardmäßig JUnit 5/AssertJ, Testnamen beschreiben das Verhalten, keine Zufallswerte ohne Seed, kein Thread.sleep
- Tests mit JUnit 5 und AssertJ schreiben — die übliche Wahl des Templates; stattdessen das Test-Framework
verwenden, das das Projekt tatsächlich eingerichtet hat (siehe
R-code-tools). - Tests nach dem erwarteten Verhalten benennen, nicht nach der getesteten Methode.
- Nie Zufall ohne festen Seed verwenden.
- Nie mit
Thread.sleepwarten; stattdessen auf die tatsächliche Bedingung warten.
javascript
Abschnitt betitelt „javascript“Coding-Regeln — JavaScript
Quelle: .act/coding/javascript.md
Kurzfassung: ESM, moderne Syntax, gepinnte Node-Version, ESLint Flat Config, Prettier, eingebaute Tests oder Vitest, behandelte Promises
Regeln für JavaScript auf Node.js in Projekten ohne TypeScript; mit TypeScript gilt der Satz typescript.
Gruppen-IDs (CR-javascript-<name>) sind stabil und werden nie neu vergeben; eine Gruppe, deren Zweck nicht
mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-javascript-basics
Abschnitt betitelt „CR-javascript-basics“Moderne Sprachstandards
Kurzfassung: ESM, const/let, strikte Gleichheit, async/await, ausdrückliche Fehler
- ES-Module verwenden:
"type": "module"inpackage.json,import/export, das Präfixnode:für eingebaute Module (import fs from "node:fs/promises") und die Dateiendung in relativen Imports. Kein neues CommonJS (require,module.exports);__dirnamewird zuimport.meta.dirname(Node 20.11+). constals Standard,letwo neu zugewiesen wird, nievar.- Mit
===/!==vergleichen;==nur für die bewusste Prüfungx == null, mit einem Kommentar. async/awaitstatt.then-Ketten.forEachwartet nicht auf einen asynchronen Callback —for…ofmitawaitverwenden oderPromise.allübermap, wenn die Aufrufe unabhängig sind.Error-Objekte werfen (mitcause, wenn umhüllt wird), nie Strings. Jede Fehlermeldung nennt, was mit welchem Wert gescheitert ist.- Die Standardbibliothek und eingebaute Funktionen (
fetch,structuredClone,node:test,util.parseArgs) vor einem zusätzlichen Paket verwenden. - Die Form strukturierter Daten mit einem JSDoc-
@typedefbeschreiben, nicht als loses Objekt herumreichen.
CR-javascript-promises
Abschnitt betitelt „CR-javascript-promises“Keine freischwebenden Promises
Kurzfassung: jedes Promise erwartet, zurückgegeben oder abgefangen; unbehandelte Rejections beenden den Prozess
- Jedes Promise wird erwartet (
await), zurückgegeben oder endet in.catch(...). Der Aufruf einer asynchronen Funktion als bloße Anweisung verbirgt ihren Fehlschlag; ab Node 15 beendet eine unbehandelte Rejection den Prozess. - Keine
async-Funktion als Event-Handler odersetInterval-Callback ohne eigenestry/catch. - Kein
new Promise(async (resolve) => …); keinawaitin einer Schleife, wo die Aufrufe unabhängig sind. - ESLint Core findet freischwebende Promises nicht (
@typescript-eslint/no-floating-promisesbraucht Typen), also im Review darauf achten und einen Handler auf oberster Ebene fürunhandledRejectionsetzen, der loggt und mit Fehlercode beendet.
CR-javascript-toolchain
Abschnitt betitelt „CR-javascript-toolchain“Node-Version, Lint, Format, Tests
Kurzfassung: Node-Version gepinnt, ESLint 9+ Flat Config, Prettier, node:test oder Vitest, Lockfile
- Die Node.js-Version pinnen:
engines.nodeinpackage.jsonplus.nvmrc(oder.node-version), und in der CI dieselbe Version verwenden. Eine aktive LTS-Linie verwenden; die installierte Version prüfen (R-code-version). - ESLint ab v9 liest nur die Flat Config
eslint.config.js;.eslintrc*ist Legacy und wird nicht verwendet, solange das Projekt nicht noch ESLint 8 betreibt. Ausführen, was das Projekt konfiguriert hat (R-code-tools). - Prettier ist der übliche Formatter des Templates; ESLint deckt nur Korrektheit ab, mit
eslint-config-prettier, wo beide laufen — kein zweiter Styleguide. - Tests: der eingebaute Runner
node:test(node --test) oder Vitest, je nachdem, was das Projekt eingerichtet hat. - Die Lockfile des Paketmanagers committen und in der CI daraus installieren, eingefroren:
npm ci,pnpm install --frozen-lockfileoderyarn install --immutable, nie eine schlichte Installation. Mit pnpm ersetzenpnpm updateundpnpm why <package>die Befehlenpm update/npm ls; Script-Argumente gehen ohne--(pnpm run test -t name). - Ein fehlschlagendes Lint oder ein fehlschlagender Test wird im Code behoben, nicht mit
eslint-disablezum Schweigen gebracht (R-code-checks-intact).
Coding-Regeln — Kotlin
Quelle: .act/coding/kotlin.md
Kurzfassung: Null Safety, Structured Concurrency, Datenmodellierung, Toolchain, Tests
Regeln für Kotlin-Projekte (JVM, Android oder Multiplatform). Gruppen-IDs (CR-kotlin-<name>) sind stabil
und werden nie neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in
diesem Kopf als retired: aufgeführt. Ein Kotlin-Projekt nimmt normalerweise nicht den Java-Satz; bei
gemischten Quellen kreuzt init beide an, und wo nur gelegentlich ein Java-Aufruf vorkommt, genügt die
Interop-Regel unten.
CR-kotlin-basics
Abschnitt betitelt „CR-kotlin-basics“Null Safety, Unveränderlichkeit, Fehlerbehandlung
Kurzfassung: kein !!, val vor var, spezifische Exceptions, explizite API an Grenzen, Java-Interop
- Nie
!!verwenden. Nullability mit?.,?:,let, einem frühenreturnoderrequireNotNull(x) { "message" }/checkNotNullbehandeln, wo ein fehlender Wert ein Fehler ist — die Meldung nennt, was fehlte.lateinitnur für vom Framework injizierte Felder. valdemvarvorziehen, in Signaturen schreibgeschützte Collections (List,Map) statt veränderlicher, und Ausdrücke (when,if) statt Mutation.- Spezifische Exception-Typen abfangen; nie eine Exception verschlucken oder
Throwableabfangen. In Coroutines nieCancellationExceptionabfangen, ohne sie erneut zu werfen.Resultoder einen Sealed Type für erwartbare Fehler statt Exceptions als Kontrollfluss verwenden. - Den Typ öffentlicher Funktionen und Properties ausdrücklich deklarieren, statt sich über eine Modulgrenze hinweg auf Inferenz zu verlassen.
- Plattformtypen aus Java (
String!) werden nicht vertraut: ihnen am Eintrittspunkt einen nullable oder nicht-null Typ geben, und Kotlin-APIs für Java-Aufrufer (@JvmStatic,@JvmOverloads,@Throws) nur dort annotieren, wo die Java-Seite es braucht. - String-Templates statt Konkatenation verwenden, und auf der JVM
java.time-Typen (nichtDate/Calendar). - Über SLF4J oder die Logging-Fassade des Projekts loggen, mit parametrisierten Meldungen — was nie in eine
Logzeile gehört, steht in
R-safe-no-secret-log.
CR-kotlin-coroutines
Abschnitt betitelt „CR-kotlin-coroutines“Structured Concurrency
Kurzfassung: kein GlobalScope, Scopes mit Lebenszyklus, injizierte Dispatcher, kein runBlocking im Produktionscode
- Nie Arbeit im
GlobalScopestarten. Coroutines in einem Scope starten, der ihren Lebenszyklus besitzt (coroutineScope,supervisorScope,viewModelScope, der eigeneCoroutineScopeeines Dienstes), damit Fehler und Abbruch weitergegeben werden. - Im Produktionscode außerhalb von
mainund Test-Brücken keinrunBlockingaufrufen und keinen Coroutine-Thread mitThread.sleepoder blockierendem I/O blockieren:delayundwithContext(Dispatchers.IO)verwenden. - Dispatcher als Parameter injizieren, statt
Dispatchers.IO/Defaultfest zu verdrahten, damit Tests sie ersetzen können. Aus APIssuspend-Funktionen oderFlowbereitstellen, nichtDeferredoder Callbacks. - Für Coroutine-Tests
kotlinx-coroutines-test(runTest) verwenden; nie mitThread.sleepwarten.
CR-kotlin-data-modeling
Abschnitt betitelt „CR-kotlin-data-modeling“data class, Sealed Types, Value Classes
Kurzfassung: data class für Werte, Sealed Types für geschlossene Mengen, copy statt Mutation
- Schlichte Werte als
data classmitval-Properties modellieren und mitcopy()ändern; keine Logik mit Nebenwirkungen in einedata classlegen. - Geschlossene Mengen von Fällen als
sealed interface/sealed classmodellieren und mit einem erschöpfendenwhenohneelse-Zweig behandeln, damit ein hinzugefügter Fall den Build bricht. @JvmInline value classfür typisierte Bezeichner (IDs, Einheiten) statt nacktemString/Longverwenden;enum classnur für eine feste Menge ohne Daten je Fall.
CR-kotlin-toolchain
Abschnitt betitelt „CR-kotlin-toolchain“Build, Formatierung, statische Analyse, Tests
Kurzfassung: Gradle Kotlin DSL als Standard, ktlint und detekt, JUnit 5 oder Kotest
- Die Kotlin-Version aus der Build-Datei oder dem Version Catalog (
libs.versions.toml) lesen und nur Sprachfeatures verwenden, die diese Version unterstützt (R-code-version): Context Parameters und Guard-Bedingungen inwhensind zum Beispiel neuer als Kotlin 2.0. - Mit Gradle und der Kotlin DSL (
build.gradle.kts) bauen — die übliche Wahl des Templates; Versionen von Abhängigkeiten an einer Stelle halten und den Gradle Wrapper verwenden, den das Projekt mitbringt. - Mit ktlint (oder
ktfmt/Spotless) formatieren und mit detekt analysieren — die übliche Wahl des Templates; ausführen, was das Projekt tatsächlich eingerichtet hat (sieheR-code-tools), und nichts ungefragt installieren. - Tests mit JUnit 5 schreiben — die übliche Wahl des Templates —, optional mit Kotest-Assertions oder MockK; das Framework verwenden, das das Projekt eingerichtet hat. Tests nach dem erwarteten Verhalten benennen; nie Zufall ohne festen Seed verwenden.
Coding-Regeln — Nuxt
Quelle: .act/coding/nuxt.md
Kurzfassung: Verzeichniskonventionen, Datenabruf, Runtime-Konfiguration, SSR-Modus, Tooling
requires: vue, typescript
Regeln für Nuxt-Projekte. Gruppen-IDs (CR-nuxt-<name>) sind stabil und werden nie neu vergeben; eine
Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
Auf Nuxt 5 ergänzt der Satz nuxt5 (.act/coding/nuxt5.md) diesen. init prüft ihn, wenn package.json nuxt in
Hauptversion 5 nennt. Fehlt die Zeile des Satzes in docs/project/coding_rules.md in einem Nuxt-5-Projekt (eines,
das vor dem Satz eingerichtet wurde), vor Arbeit an Nuxt-Code .act/coding/nuxt5.md lesen und vorschlagen,
- [x] use: .act/coding/nuxt5.md samt seinen Gruppen hinzuzufügen; eine abgewählte Zeile ist die Entscheidung des
Eigentümers.
CR-nuxt-basics
Abschnitt betitelt „CR-nuxt-basics“Bewährte Nuxt-Standards
Kurzfassung: Verzeichnisstruktur, Datenabruf, typisierte Handler, Runtime-Konfiguration, Fallstricke
-
Der Verzeichniskonvention folgen (
pages/,components/,composables/,server/), statt eine eigene Struktur zu erfinden; Auto-Imports nutzen, keine manuellen Re-Exports für Dateien in diesen Verzeichnissen. -
Daten beim Rendern mit
useFetch/useAsyncDatalesen,$fetchfür einmalige Schreibzugriffe und Aktionen verwenden. -
Den Rückgabewert von
useFetch/useAsyncDatanie in ein eigenesrefkopieren — das zurückgegebene Objekt durchreichen und dortawaiten, wodata/status/errordas Template erreichen. Kopieren verliert die Awaitability: Der Aufruf löst sich später auf, der Server rendert ohne Daten, der Client füllt sie nachträglich ein, und das Ergebnis ist ein Hydration-Mismatch.```ts// Falsch — die Awaitability geht verlorenfunction useThing() {const result = ref()useFetch('/api/thing').then(r => (result.value = r.data.value))return result}// Richtig — das zurückgegebene Objekt unverändert durchreichenasync function useThing() {return await useFetch('/api/thing')}``` -
Pfad-Aliase, je nach installierter Nuxt-Hauptversion (
R-code-version). Seit Nuxt 4 zeigt~aufapp/, ohne eigenen Eintrag löst~/typesalso woanders auf als~types.- Nuxt 4 und neuer: Aliase nur in
nuxt.config.ts(alias) deklarieren; Nuxt übernimmt jeden in die erzeugten.nuxt/tsconfig*.json. Dietsconfig.jsonim Root enthält nichts außerreferencesauf diese erzeugten Konfigurationen und nie eigenepaths: Mitfiles: []plusreferencesersetzt einpathsdort nichts, es erreicht die referenzierten Projekte schlicht nicht, der Alias wirkt also nirgends. Nur ein Root, der eine erzeugte Konfiguration erweitert, ersetzt die ganze erzeugte Zuordnung durch seinepaths, und die Framework-Aliase verschwinden. - Nuxt 3: Aliase ebenfalls in
nuxt.config.tsdeklarieren; eine Root-tsconfig.json, die./.nuxt/tsconfig.jsonerweitert, darfpathsnur ergänzen, wenn sie jeden erzeugten Eintrag wiederholt. Nuxt 3 schreibt außerdem jedenaliasin die erzeugtenpaths, der Eintrag innuxt.config.tsallein genügt also; die erzeugte.nuxt/tsconfig.jsonzeigt es.
- Nuxt 4 und neuer: Aliase nur in
-
Dateien, die die erzeugten Kontexte auslassen (Unit- und E2E-Tests, Konfigurationen des Test Runners), überspringt
nuxt typecheckohne Meldung. Sie über die TypeScript-Optionen von Nuxt innuxt.config.tsaufnehmen (typescript.tsConfig.include, oder auf Nuxt 4 die Objekte je Kontexttypescript.sharedTsConfig/typescript.nodeTsConfig/typescript.tsConfig; den Server-Kontext übernitro.typescript.tsConfig) und dann jeden Kontext einmal nachweisen: einen absichtlichen Typfehler in eine Datei davon setzen,nuxt typecheckfehlschlagen sehen, ihn wieder entfernen. Die Namen der Optionen in der Doku der installierten Nuxt-Version prüfen, bevor man sie verwendet. -
pnpm-Projekte: siehe die Hinweise zum Paketmanager in den JavaScript-Regeln.
-
runtimeConfigfür Konfigurationswerte verwenden, stattprocess.envin Komponenten zu lesen; Secrets gehören in den privaten Teil vonruntimeConfig, nie unterpublic. -
Typen für Props, Emits, Store-Actions, Composables und
defineEventHandlerausschreiben, einschließlich der Rückgabetypen. -
Server-Routen unter
server/api/mit einem Verb-Suffix benennen (login.post.ts,users.get.ts) und Fehler mitcreateErrorund einem passenden HTTP-Status zurückgeben — nie einen Fehler verschlucken oder mit 200 antworten. -
Lint und Typecheck sind der Standard des Stacks und gehören ins Projekt;
nuxt typecheckbrauchtvue-tscals Abhängigkeit, ohne es gibt es keinen Typecheck. Ausführen, was installiert ist, nichts ungefragt installieren. -
Die npm-Scripts überall gleich benennen:
lint(eslint .),typecheck(nuxt typecheck), dazutest(vitest run) undtest:e2e(playwright test), wo es Tests gibt. -
Fallstricke:
- SSR-Code darf Browser-Globals (
window,document) nicht ohne Absicherung anfassen. <ClientOnly>nur dort verwenden, wo eine Komponente auf dem Server wirklich nicht rendern kann, nicht als Standardlösung.- Sicherheit: nie Zustand pro Request in einem
ref/reactiveauf Modulebene halten. Auf dem Server überlebt ein solcher Wert den Request und wird zwischen Nutzern geteilt — der nächste Request sieht die Daten des vorigen. Für Zustand, der den Request überleben muss,useStateverwenden. - Formulare mit
@submit.preventbrauchen zusätzlichmethod="post"(sieheCR-vue-basics). - Exportnamen in Ordnern mit Auto-Import (
composables/,utils/,server/utils/,shared/utils/) sind über alle ihre Dateien eindeutig. Exportieren zwei Dateien denselben Namen, gewinnt eine von ihnen ohne Fehler, es erscheint nur eine Warnung über doppelte Imports, und Lint und Typecheck können grün bleiben. Jedem Bereich ein Präfix geben und diese Warnung in der Ausgabe von Dev, Build oder Typecheck als Befund behandeln. - Eine Page-Komponente hat genau ein Wurzelelement; ein HTML-Kommentar zählt als eines. Bei mehr warnt Nuxt nur im
Dev (im Nuxt-5-Nightly:
NUXT_E4004), und die Seite bricht bei einem clientseitigen Routenwechsel, während das direkte Öffnen und Tests der einzelnen Seite grün bleiben. Nach dem Anlegen oder Umbauen einer Seite die Browser-Konsole und die Dev-Ausgabe auf diese Warnung prüfen; sie ist ein Befund. - Windows: Ein abgebrochener Dev-Server kann seinen Port belegt halten; der nächste Start weicht auf
den nächsten freien Port aus, und HMR-/WebSocket-Fehler folgen. Ist es ein Server, den der Assistent
selbst gestartet hat, genau diesen Prozess beenden, statt einen eigenen HMR-Port zu konfigurieren. Die
lauschende PID findet
(Get-NetTCPConnection -LocalPort <port> | Where-Object RemotePort -eq 0).OwningProcess. Weder auf-State Listenverlassen (liefert auf manchen Windows-Builds Client-Verbindungen oder nichts) noch aufnetstat | findstr LISTENING(das Wort ist lokalisiert, auf deutschem WindowsABHÖREN). Der Filter kann trotzdem Bound- oder Closed-Einträge und mehrere oder veraltete PIDs liefern: vorStop-Process -Id <pid>prüfen, dass die Befehlszeile des Prozesses ((Get-CimInstance Win32_Process -Filter "ProcessId=<pid>").CommandLine) der selbst gestartete Testserver ist (R-safe-dev-server). Aus Git Bash die Befehle inpowershell -NoProfile -Command "…"packen odertaskkill //PID <pid> //Fverwenden (ein einzelnes/PIDwird dort in einen Pfad umgeschrieben und beendet nichts). Danachhttp://localhost:<port>/anfragen (ein Server kann nur auf::1lauschen): die Anfrage muss abgelehnt werden. Anderswolsof -iTCP:<port> -sTCP:LISTENundkill <pid>. Ein Server auf dem Port des Eigentümers gehört ihm: erst fragen. - Sicherheit:
workspaceDirinnuxt.config.tsauf den Projektordner selbst setzen und den aufgelösten Wert prüfen, ohne den Server zu starten, indem man die Config lädt. Grund: Ist der Dev-Server aus dem Netz erreichbar, kann eine verirrte Lock- oder Workspace-Datei in einem übergeordneten Ordner diesen Ordner darüber lesbar machen (AdvisoryGHSA-mjrq-cffv-q4qc, Nuxt 3 und 4 mit@nuxt/schemaab 3.5.0 bis unter 4.6.4, behoben in 4.6.4).
- SSR-Code darf Browser-Globals (
CR-nuxt-root-folders
Abschnitt betitelt „CR-nuxt-root-folders“Feste Root-Ordner mit eigenen Aliasen
Kurzfassung: /types, /constants, /server und shared/utils/ im Repo-Root, jeweils der einzige Ort seiner Art
- Vier Ordner im Repository-Root halten, jeweils mit eigenem Alias und jeweils der einzige Ort seiner Art:
/types(~types, gemeinsame Typen und Interfaces),/constants(~constants, Konstanten, Enumerationen, feste Schlüssel),/server(~server, das Nitro-Backend),shared/utils/(Nuxts#shared, Code, den App und Server beide ausführen, etwa Formatierung, Validierung oder Berechnungen). - Typen und Konstanten von dort importieren, statt sie in Komponenten zu duplizieren. Ein zweiter
Typen-Ordner unter
app/types/odershared/types/ist ein Fehler, keine Ergänzung: Typen bleiben in/types. - Code in
shared/importiert weder Vue noch Nitro-Code (Nuxts eigene Grenze). Code, den nur die App ausführt, bleibt inapp/utils/, Code, den nur der Server ausführt, inserver/utils/. shared/braucht Nuxt 3.14 oder neuer (R-code-version). Nuxt 4 importiertshared/utils/in App und Server automatisch; Nuxt 3 tut das nur mitfuture.compatibilityVersion: 4, sonst aus#shared/utils/…importieren.
CR-nuxt-ssr
Abschnitt betitelt „CR-nuxt-ssr“Den SSR-Modus bewusst wählen
Kurzfassung: vor der Annahme von SSR fragen, die Hydration-Kosten kennen, nach SSR-Arbeit auf Mismatches prüfen
ssr: falseoder eine reine SPA ist bei einer rein lokalen Oberfläche ohne SEO- oder First-Paint-Anforderung (z. B. ein Admin-Tool) oft die einfachere Wahl. Den Nutzer einmal fragen, wenn die App aufgesetzt oder umstrukturiert wird, statt ungefragt SSR als Standard zu nehmen.- Wissen, was SSR kostet: Jedes Rendern einer Seite läuft zweimal, einmal auf dem Server und einmal auf dem
Client. Alles, was nur im Browser existiert oder sich zwischen beiden Läufen unterscheidet — Zeitstempel,
Zufallswerte,
window,localStorage, Erkennung von Locale oder Zeitzone —, erzeugt einen Hydration-Mismatch. - Nach Arbeit an einer Komponente, die serverseitig rendert, gezielt auf Hydration-Fehler prüfen: die Seite im Browser laden und die Konsolenwarnung „Hydration … mismatch“ lesen — sie nennt Komponente und Knoten. Diese Warnung als Befund behandeln, nicht als Fußnote.
- Bekannte Ursachen und ihre Behebung in Kürze: Werte, die nur im Browser existieren, hinter
onMounted/import.meta.clientlegen; request-bezogenen Zustand überuseStateteilen, nie über einrefauf Modulebene; ungültige HTML-Verschachtelung beheben (z. B. ein Block-Element in einem<p>);<ClientOnly>nur als letztes Mittel einsetzen. - Ein HTML-Kommentar zwischen den Zweigen einer
v-if-/v-else-if-/v-else-Kette bricht die Hydration im Dev, und weder Lint noch der Typecheck bemerken es; den Kommentar vor die ganze Kette oder in einen Zweig setzen. - Das Ergebnis von
useFetch/useAsyncDatain ein eigenesrefzu kopieren ist ebenfalls eine häufige Ursache für Hydration-Mismatches — Grund und Behebung stehen inCR-nuxt-basics, hier nicht wiederholt. - Mit
ssr: falselädt@nuxt/icon(auch über@nuxt/ui) Icons zur Laufzeit von der öffentlichen Iconify-API, solange sie nicht gebündelt sind: die Icon-Sets als@iconify-json/<set>installieren, Providernone,clientBundle.scan,fallbackToApi: false; ein unbekanntes Icon erscheint dann als fehlend, mit einer Warnung in der Konsole.
CR-nuxt-toolchain
Abschnitt betitelt „CR-nuxt-toolchain“Lint- und Format-Tooling
Kurzfassung: ESLint mit @nuxt/eslint plus Prettier, oder was das Projekt eingerichtet hat
- ESLint mit
@nuxt/eslint, konfiguriert ineslint.config.mjs, und Prettier für die Formatierung sind die übliche Wahl des Templates; maßgeblich ist, was das Projekt tatsächlich installiert und konfiguriert hat (sieheR-code-tools).
CR-nuxt-tests
Abschnitt betitelt „CR-nuxt-tests“Unit- und End-to-End-Tests
Kurzfassung: standardmäßig vitest/Playwright, aber die Suite, die das Projekt ausführt, muss bestehen; verankerte Locators, isolierte parallele Testserver
vitest(vitest.config.ts) für Unit- und Komponententests,@playwright/test(playwright.config.ts) für End-to-End-Tests — die übliche Wahl des Templates; hat das Projekt einen anderen Test Runner installiert und konfiguriert (z. B. Selenium, Nightwatch, Cypress), stattdessen diesen verwenden (sieheR-code-tools).- Welche Test-Suiten das Projekt tatsächlich hat, die existieren und laufen; eine Änderung, die sie bricht, ist nicht fertig.
- Einen Locator aus Rolle und Name vollständig verankern: Ein Pflichtfeld kann
*in seinem zugänglichen Namen tragen, sodass/^Name/auf mehrere Felder passt und der Strict Mode von Playwright fehlschlägt;/^Name\*?$/verwenden. - Die eingebauten Beschriftungen einer UI-Bibliothek (Paginierung, Schließen-Buttons) aus ihren Locale-Dateien
nehmen, statt den Text in den Test zu schreiben: Eine Bibliothek kann bei einem Update anfangen, der i18n-Sprache
der App zu folgen (gemeldet für
@nuxt/ui4.12 mit@nuxtjs/i18n). - Parallele Test-Builds oder Testserver laufen unter dem Wegwerf-Ordner (
R-work-throwaway); Lint, Formatter und File Watcher müssen ihn als Ganzes ausnehmen:.act-local/in ihre Ignore-Listen aufnehmen (ignoresineslint.config,.prettierignore,ignoreinnuxt.config), wo sie ihn nicht schon überspringen. Jeder Testserver bekommt ein eigenesbuildDir, ein eigenes Nitro-Ausgabeverzeichnis und ein eigenes Vite-cacheDir(absolut: Vite löst ein relatives gegenapp/auf), alle drei aus einer Umgebungsvariable, dienuxt.configliest, dazu einen eigenen Port. Gemeldet für die CLI von Nuxt 5:nuxt devsperrt seinbuildDirund verweigert einen zweiten Dev-Server darauf, und auf demselben Port beendet ein nicht interaktivesnuxt deveinen nicht interaktiven Inhaber, sodass ein Test Runner auf dem Port des Eigentümers dessen Server stoppen kann (R-safe-dev-server). Eine veraltete Lock-Datei im eigenenbuildDireines Testservers darf vor dem Start nur entfernt werden, wenn ihr Prozess nicht mehr läuft oder ihre PID inzwischen einem anderen Prozess gehört, nie nach ihrem Alter.
Coding-Regeln — Nuxt 5
Quelle: .act/coding/nuxt5.md
Kurzfassung: Nightly-Kanal, Module, Nitro 3/h3 v2, typisiertes Routing und $fetch, Unhead 3, Prüfungen nach jedem Update
requires: nuxt
Regeln für Projekte auf Nuxt 5, geschrieben gegen den Nightly-Kanal vor dem stabilen Release. Sie ergänzen
CR-nuxt-* und ersetzen davon nichts. init prüft diesen Satz, wenn package.json nuxt in Hauptversion 5
nennt (^5.0.0, npm:nuxt-nightly@5x). Gruppen-IDs (CR-nuxt5-<name>) sind stabil und werden nie neu vergeben;
eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-nuxt5-channel
Abschnitt betitelt „CR-nuxt5-channel“Nightly-Kanal und Versionen
Kurzfassung: nuxt-nightly@5x als Tag, die Lockfile als einzige Festlegung, pnpm löst den Tag neu auf, der vue-Bereich der Nightly, Hauptversionen im Gleichschritt mit Nuxt, DevTools ausdrücklich, ein Paket ohne Nuxt bewegt
- Bis zum stabilen Release
nuxtals"npm:nuxt-nightly@5x"eintragen — ein Tag, nie eine Build-Nummer. Schreibtnpm install(pnpm install) eine feste Version, sie von Hand auf@5xzurücksetzen und erneut installieren (mit pnpm ist diese Installation selbst ein Nuxt-Update, siehe unten); nur die Lockfile hält den Stand fest. Entfällt, sobaldnuxt/nuxtv5.0.0getaggt hat (github.com/nuxt/nuxt/releases); dann^5.0.0. - Mit
npm update nuxt(pnpm update nuxt) vorrücken, als eigener Commit, danach die volle Prüfung ausCR-nuxt5-checks. - Direkte Abhängigkeiten, die Nuxt mitbringt, bleiben auf derselben Hauptversion wie Nuxt (z. B.
vue-router5,@unhead/vue3); nach jedem Update zeigtnpm ls <package>(pnpm why <package>) je Paket eine Kopie. - Mindestens Node 22.21 oder 24.11.
@nuxt/devtoolsausdrücklich als devDependency installieren; nur im Dev-Server und nur mitNUXT_DEVTOOLS=1ausführen, und jeden Browser einmal mit dem Code aus dem Dev-Terminal bestätigen.devtools.disableAuthorizationnie setzen.- Mit pnpm und
nuxtals Alias auf den Nightly-Tag kann jedes Schreiben der Lockfile den Tag neu auflösen und Nuxt auf eine neuere Nightly bewegen:pnpm add,pnpm installnach einer Änderung von Hand,pnpm update <package> --depth Infinityfür einen transitiven Fix; selbst mit Nuxt exakt festgelegt inpackage.jsonwurde sein Teilbaum neu aufgelöst. Mit pnpm daher Pakete nur direkt nach einem bewussten Nuxt-Update hinzufügen, entfernen oder aktualisieren (eigener Commit, volle Prüfkette) und danach mitpnpm why nuxtbestätigen, dass das aufgelöste Nuxt unverändert ist. Entfällt, sobald Nuxt 5 ein stabiles Release hat und das Projekt den Nightly-Tag verlässt. - Um ein einzelnes Paket (einen Sicherheitsfix) ohne Nuxt zu bewegen, mit pnpm:
nuxtinpackage.jsonfür den Lauf auf die genaue Version setzen, die die Lockfile hält, das Paket aktualisieren,package.jsonwiederherstellen, dann den Specifier vonnuxtin der Lockfile auf den Kanal-Tag zurücksetzen. Danach musspnpm install --frozen-lockfilebestehen, und der Lockfile-Diff zeigt nur neue Einträge, keine geänderten oder entfernten; sonst von vorn als bewusstes Nuxt-Update. Ein mitgewanderter Nightly-CLI wird in der Lockfile zurückgenommen. Dieselben Schritte heben die inCR-nuxt5-checksgenannten Modulkopien auf die behobene Version, ohne die Nightly zu bewegen. Entfällt mit der pnpm-Zeile oben. - Eine Nightly kann ihren eigenen
vue-Bereich anheben; einvue-Eintrag des Projekts, der auf dem alten Minimum bleibt, hält eine zweite Vue-Kopie. Nach jedem Vorrücken den Bereich der Nightly lesen (npm view <nightly>@<version> dependencies.vue,pnpm viewebenso), den eigenen Eintrag darauf anheben, danach zeigtnpm ls vue/pnpm why vueeine Version. Auchnuxt prepareausführen: Die erzeugte ESLint-Konfiguration kann auf den alten Store-Pfad zeigen, bis es läuft (meist erledigt daspostinstall). - Mit
minimumReleaseAgevon pnpm 11 nimmtpnpm update nuxtdie neueste Nightly, die älter als dieses Alter ist: das nicht umgehen; die tatsächlich installierte Version in Commit und Upgrade-Log nennen. - Nach
devoderbuildden Diff vonpackage.jsonlesen: Jeder Eintrag, den das Tooling von sich aus ergänzt hat, ist einer, den du erklären kannst.
CR-nuxt5-modules
Abschnitt betitelt „CR-nuxt5-modules“Module unter Nuxt 5
Kurzfassung: NUXT_B8013 heißt abgeschaltet, Pinia 4 mit seinem Peer, der i18n-Rückweg, gebündelte Icons, die Nitro-v2-Brücke nur in Modulen
NUXT_B8013schaltet ein Modul ab, dessen Feldcompatibilitynicht passt, und zeigt nur eine Warnung: das Feld vor dem Update prüfen, die Warnungen danach lesen.- Pinia 4:
@pinia/nuxt1 oder neuer,@vue/devtools-api^8 als direkte Abhängigkeit. @nuxtjs/i18n10.6, solange es Nuxt 5 nicht unterstützt:i18n.experimental.nitroContextDetection: false. Ohne das bekommt ein Pfad ohne Locale-Präfix keine Weiterleitung vom Server (geprüft mit Strategieprefixauf Nightly5.0.0-2611122105); wie gemeldet wartet der Standardwert auf den Nitro-Hookrender:before, den Nitro 3 nie aufruft, und die Weiterleitung im Client endet in einem Hydration-Mismatch. Entfernen, sobald ein Release nuxt-modules/i18n#4066 schließt (Unterstützung für Nuxt 5 und Nitro 3).experimental.nitroViteEnvironment: falseist ab Nightly5.0.0-2611031025nicht mehr nötig; entfernen, sobaldbuildund die E2E-Tests ohne es bestehen.- Unter Nuxt 5 liefert der Provider
servervon@nuxt/icondie Icons nicht aus: Er antwortet mit leerem Body (2.5.1), oder der Browser fragt direkt die öffentliche Iconify-API (2.6.2 mit@iconify/vue5) (gemeldet, Upstream-Issue nuxt/icon 571). Das gebündelte Setup ausCR-nuxt-ssrverwenden und eine E2E-Prüfung, dass Icons gerendert werden und keine Anfrage an die Iconify-API geht; entfällt, sobald dieses Issue in einem Release behoben ist. - Die Nitro-v2-Brücke (
NUXT_B9003) nie im eigenen Code nachbauen.
CR-nuxt5-server
Abschnitt betitelt „CR-nuxt5-server“Nitro 3 und h3 v2
Kurzfassung: ausdrückliche Imports aus nuxt/server, event.req als Web-Request, typisierte Bodies, status/statusText, kein Komma in Kommentaren an Export-Zeilen, Header und CSP, keine Datei gelöscht unter dem Dev-Server des Eigentümers
- In
server/defineEventHandler,readBody,getQuery,createError… ausnuxt/serverimportieren und Plugins mitdefinePluginausnitrodefinieren;server/utils/bleibt auto-importiert. event.reqist der Web-Request(es gibt keinevent.node); einen Multipart-Body mitevent.req.formData()lesen.readBody<T>()mit einem eigeneninterface, Fallback.catch((): Body => ({})). Der Typ ist keine Validierung — den Body wie bisher validieren (z. B. mit einer Schema-Bibliothek).- Eine Antwort am Rückgabewert typisieren (
const response: ApiThing = …; return response), der Typ im/types(CR-nuxt-root-folders). - Fehler mit
createError({ status, statusText });statusTextnur in ASCII (z. B.'Unprocessable Entity'), lokalisierter Text kommt indata. - Im Client kommt
createError({ data })unterresponse._data.dataan; die Feldfehler einer 422 liegen unter…data.errors(z. B. fürUForm.setErrorsvon Nuxt UI). useRuntimeConfig()ohneevent.- In einem Ordner, der in den Server auto-importiert wird (
server/utils/,shared/utils/…), kein Komma in einem Zeilenkommentar hinter einer exportierten Deklaration: Der Export-Scan (mlly) liest das Wort nach dem Komma als weiteren Export und schreibt es in.nuxt/types/server-imports.mjs, und der Server-Build scheitert mitMISSING_EXPORT, sobald ein Modul verhindert, dass diese Datei per Tree-Shaking wegfällt (gesehen mitmlly1.8.2,@nuxtjs/i18n10.6.0, Nightly5.0.0-2611122105). Den Kommentar über die Zeile setzen. Entfällt, sobald die erzeugte Datei nur echte Exporte auflistet (kein Upstream-Bericht bekannt). - Feste Sicherheits-Header (nicht die CSP) kommen in eine Route Rule
/**innuxt.config: Nitro 3 liefert Dateien auspublic/und/_nuxt/vor den Middlewares der App aus, ein Header, den eine Middleware setzt, erreicht sie also nie. Die Header gegen den Produktions-Build prüfen. - Von einem Projekt gemeldet, nicht nachgestellt: Nuxt 5 setzt selbst keine CSP, und noch kein CSP-Modul
unterstützt es. Den CSP-Header in einem Server-Plugin auf
render:htmlsetzen (useServerHooksausnuxt/server), mit Hashes für die festen Inline-Skripte und einer Nonce je Request auf dem Payload-Skript; Nuxt setzt eine Nonce auf seine eigenen Streaming-Skripte nur, wenn schon ein Head-Skript eine trägt. Eine CSP, die eine frühe Middleware setzt, überschreibt die des Renderers, dort also nur für API-Routen eine setzen. Entfällt, sobald ein CSP-Modul (z. B.nuxt-security) Unterstützung für Nuxt 5 erklärt. - Nach dem Umbenennen oder Entfernen eines Exports in
server/utils/den eigenen Testserver neu starten (sein Port, wieR-safe-dev-serveres sagt), bevor Tests gegen ihn zählen; den Server des Eigentümers erst nach Rückfrage. Kein Übergangs-Alias für den alten Namen. NieNUXT_IGNORE_LOCKoderNUXT_LOCK=0setzen. - Eine Datei aus einem auto-importierten Ordner zu löschen, während der Dev-Server des Eigentümers läuft, lässt jede Seite bis zu einem Neustart mit 500 antworten: Der laufende Modulgraph hält den alten Import. Da der Assistent diesen Server nie neu startet, die Datei leeren und stehen lassen, sie nach dem nächsten Neustart des Eigentümers löschen oder vorher fragen. Ein Testserver, der je Lauf frisch startet, ist nicht betroffen.
- Jede Runtime-Abhängigkeit kommt in
package.json, auch eine, die transitiv schon da ist.
CR-nuxt5-app
Abschnitt betitelt „CR-nuxt5-app“Seiten, Routing, Datenabruf, Head
Kurzfassung: import.meta.*, query statt params, typisiertes $fetch und typisierte Routenziele, Unhead 3 und sein og-Hinweis, kein baseUrl
import.meta.*stattprocess.*(import.meta.client,import.meta.dev…).querystattparamsin den Optionen von$fetch/useFetch.$fetchwird aus den erzeugten Server-Routen typisiert: Ein Wrapper, der freie Pfade annimmt, bekommt eine eigene, enge Signatur (type FreeFetch = <R>(request: string, options: FetchOptions) => Promise<R>) und wandelt$fetchmitas unknown as FreeFetchum, mit einem Kommentar, der sagt, warum.- Mit Typed Pages und
@nuxtjs/i18nist ein Seitenziel ein Routenname ohne Locale-Suffix:localePath({ name, params, query })oder<NuxtLinkLocale :to="{ name: … }">— auch fürnavigateTo,router.push,NuxtLinkund eintovon Nuxt UI; ein schlichter Pfad bekommt kein Locale-Präfix und endet in einer 404. Aus demselben GrunddefinePageMeta({ redirect })relativ zum aktuellen Pfad bauen. - Unhead 3: kein
hid/vmid, mitkeydeduplizieren; ein Dev-Hinweis zuog:*oder zur Description ist ein Befund, außer im bekannten Fall unten. - Unhead 3 meldet
og-missing-titleauf einer Seite, die andereog:-Meta-Tags trägt (oft app-weit gesetzt), aber keinog:title(geprüft in Unhead 3.4.3, das Validate-Plugin indist/plugins.mjs). Auf einer Seite, die bewusst keinog:titlehat (private Seite, Fehlerseite), dort auch die anderenog:-Tags weglassen; wo das nicht geht, den Hinweis als bekannten Fehlalarm behandeln und nach jedem Unhead-Update neu prüfen.rules: { 'og-missing-title': 'off' }am Validate-Plugin schaltet ihn für jede Seite ab und verdeckt damit echte Fälle. - Jede Seite setzt ihren Titel, eine öffentliche Seite auch ihre Description; die Fallbacks (Titel-Template,
og:site_name, Standard-Description) kommen inapp.vueunderror.vue, da Nuxterror.vueanstelle vonapp.vuerendert. Ein fehlender Head-Wert wird weggelassen, nie alsundefinedübergeben —useSeoMeta({ description: undefined })entfernt den Fallback (derog:title-Fall oben wird also durch Weglassen von Tags gelöst, nicht durchundefined). workspaceDirfestlegen, wie es die Sicherheitszeile inCR-nuxt-basicssagt; das gilt auch für Nuxt 5.- Kein
compilerOptions.baseUrlintsconfig.json— Nuxt ignoriert es; Aliase kommen nur innuxt.config.ts(CR-nuxt-basics).
CR-nuxt5-checks
Abschnitt betitelt „CR-nuxt5-checks“Prüfungen nach jedem Nuxt-Update
Kurzfassung: die volle Prüfkette, die Typfehlerliste verglichen statt gezählt, Warnungen (eine bekannte Listener-Warnung), Kopien (wie man zählt, der erwartete @nuxt/schema-Treffer) und invalid im Baum, Workarounds gegen Upstream, ein Build vor Commits an auto-importierten Ordnern oder nuxt.config, ein Protokoll
- Die Ausgabe des Typechecks vor dem Update sichern und danach die Fehler vergleichen — die Liste, nicht die Zahl.
- Dann
npm run lint,typecheck,test,build,dev(Hauptseiten antworten mit 200, keine Hydration-Warnung), die Hauptseiten noch einmal gegen den gebauten Server, die Browser-Konsole gelesen (ein Modul kann nur dort brechen), undtest:e2e;devund der gebaute Server als eigene Testserver (Port, wieR-safe-dev-serveres sagt), danach beendet. - Auch zwischen Updates führt ein Commit, der einen auto-importierten Ordner (
server/,shared/,app/composables/,app/utils/) odernuxt.configändert, neben Lint, Typecheck und Tests auchbuildaus: Sie bleiben bei einem kaputten Export-Scan grün (CR-nuxt5-server), nur der Build scheitert. Mit eigenembuildDirund eigenem Nitro-Ausgabeverzeichnis bauen, wieCR-nuxt-testses sagt, nie in das.nuxt/des Eigentümers, während dessen Dev-Server läuft (R-safe-dev-server). - Die Warnungen lesen (
NUXT_B8013,NUXT_B9003,[unhead]), auf doppelte Kopien prüfen,python .act/scripts/security_scan.py --depsausführen. - Kopien eines Pakets zählen mit
npm ls <package>/pnpm why <package>; Ordner unternode_modules/.pnpm, die von früheren Installationen übrig sind, bleiben, bis pnpm sie bereinigt (modulesCacheMaxAge), und sind keine Kopien. - Unter der Nightly ziehen gängige Module noch
@nuxt/kit4.x und damit ein@nuxt/schema4.x: Der Abhängigkeits-Scan meldet dasworkspaceDir-Advisory (CR-nuxt-basics) auf dieser Kopie, nicht auf der Nightly, der Treffer ist also erwartet. Die Kopie heben, wieCR-nuxt5-channeles für ein einzelnes Paket beschreibt. Entfällt, sobald die gängigen Module von einem Nuxt-5-Kit abhängen. - Eine
MaxListenersExceededWarningzuclose-Listenern auf der Server-Response imnuxt devder Nightly ist Toolchain-Rauschen: Die Listener kommen vom CLI, von Vite, der Server-Schicht und Stream-Helfern (mit TTY auch von der Oberfläche des CLI), ihre Zahl hängt von der Art der Anfrage ab, nicht von der Laufzeit, und fällt wieder auf null, sobald die Response schließt; Anwendungscode erreicht die Response nicht. Eine einfache CLI-Ausgabe ohne die Oberfläche vermeidet sie. Nur untersuchen, wenn sie auch im Produktions-Build erscheint oder mit der Lebensdauer eines Streams wächst. Entfällt, sobald die Warnung imnuxt deveiner aktuellen Nightly nicht mehr erscheint. npm ls --all 2>&1 | grep invalid: eine veraltete Auflösung mitnpm update <package>beheben (mit pnpm:pnpm why <package>,pnpm update <package>, unter der pnpm-Zeile vonCR-nuxt5-channel); bereits bekannte Einträge stehen im Upgrade-Log, nur neue melden.- Jeden Workaround dieses Satzes gegen das Upstream-Issue oder Release prüfen, das er nennt; den entfernen, dessen Bedingung erfüllt ist, und das im Upgrade-Log vermerken.
- Jeden Bruch in einem Upgrade-Log des Projekts festhalten (z. B.
docs/project/nuxt-5-upgrade.md): das Symptom kurz zitiert, die Ursache geprüft oder als assumption markiert, die Behebung, die Stelle. Eine allgemeine Lehre wird eine eigene Regel indocs/project/coding_rules.mdund geht peract-feedbackans Template.
Coding-Regeln — PHP
Quelle: .act/coding/php.md
Kurzfassung: strict types, PSR-12/PSR-4, Exceptions, Prepared Statements, Toolchain
Regeln für PHP-Projekte (8.x und neuer). Gruppen-IDs (CR-php-<name>) sind stabil und werden nie neu
vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-php-basics
Abschnitt betitelt „CR-php-basics“Strict Types, sichere Fehler, sichere Abfragen
Kurzfassung: strict_types, PSR-12/PSR-4, typisierte Methoden, Exceptions, PDO, Fehler in Produktion, statische Analyse
declare(strict_types=1);als erste Anweisung in jede PHP-Datei schreiben.- Für die Formatierung PSR-12 befolgen (Einrückung mit 4 Leerzeichen) und für Namespaces PSR-4, ein Namespace pro Composer-Autoload-Root.
- Eine Klasse pro Datei, der Dateiname entspricht dem Klassennamen.
- Abhängigkeiten ausschließlich über Composer verwalten; nie eine Bibliothek von Hand einbinden.
- Parameter- und Rückgabetypen an jeder öffentlichen Methode deklarieren.
mixednur mit einem Kommentar verwenden, der es begründet, und nullable Typen (?Type) ausdrücklich markieren, statt auf ein implizitesnullauszuweichen. - Exceptions werfen, statt
falseoder einen Fehlercode zurückzugeben. Eine Exception-Klasse pro Fehlerdomäne definieren, statt pauschal\Exceptionzu werfen, und die Meldung nennen lassen, was woran gescheitert ist — eine Datenbank-Exception nennt die Abfrage oder Tabelle, eine Validierungs-Exception das Feld und den abgelehnten Wert. - Geschäftslogik aus Templates (Blade, Twig, reine PHP-Templates) heraushalten; Templates rendern, sie entscheiden nicht.
- Auf die Datenbank ausschließlich über PDO mit Prepared Statements zugreifen; nie SQL bauen, indem Werte in den Abfrage-String konkateniert werden.
===/!==verwenden, wo Typgleichheit gemeint ist, nicht die losen Operatoren.display_errorsin Produktion ausschalten; Fehler gehören ins Log, nicht in die Antwort.- Statische Analyse ist der Standard des Stacks und gehört ins Projekt. Ausführen, was installiert ist, nichts ungefragt installieren.
CR-php-conventions
Abschnitt betitelt „CR-php-conventions“Closures statt globaler Callbacks
Kurzfassung: Arrow Functions und Closures statt globaler Callback-Funktionen
- Arrow Functions/Closures statt globaler Callback-Funktionen verwenden.
CR-php-toolchain
Abschnitt betitelt „CR-php-toolchain“Formatter und Werkzeuge für statische Analyse
Kurzfassung: standardmäßig PHP-CS-Fixer/PHP_CodeSniffer plus PHPStan/Psalm, oder was das Projekt eingerichtet hat
- PHP-CS-Fixer oder PHP_CodeSniffer, für PSR-12 konfiguriert, und PHPStan oder Psalm für die statische
Analyse — die übliche Wahl des Templates; ausführen, was das Projekt tatsächlich eingerichtet hat
(siehe
R-code-tools).
powershell
Abschnitt betitelt „powershell“Coding-Regeln — PowerShell
Quelle: .act/coding/powershell.md
Kurzfassung: gepinnte PowerShell-Edition, Encoding, Strict Mode und Fehler, Exit-Codes nativer Programme, Skriptstil, PSScriptAnalyzer und Pester
Regeln für PowerShell-Skripte und -Module. Gruppen-IDs (CR-powershell-<name>) sind stabil und werden nie
neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-powershell-edition
Abschnitt betitelt „CR-powershell-edition“Die Edition pinnen, das Encoding ausdrücklich halten
Kurzfassung: Windows PowerShell 5.1 gegenüber PowerShell 7, ein Ziel pro Skript, ausdrückliches Encoding, keine Bash-Syntax
- Das Ziel im Projekt benennen: Windows PowerShell 5.1 (
powershell.exe) oder PowerShell 7+ (pwsh).$PSVersionTable.PSVersionund die Projektdateien prüfen, bevor etwas unten Genanntes angewendet wird (R-code-version); es im Skript mit#Requires -Version 5.1oder#Requires -Version 7.0deklarieren. - Die beiden Editionen unterscheiden sich in den Standardwerten: 5.1 schreibt mit
>,>>undOut-FileUTF-16 LE, undSet-Contentnutzt die ANSI-Codepage; 7 schreibt überall UTF-8 ohne BOM. Sich nie auf den Standard verlassen — jedemOut-File,Set-Content,Add-ContentundExport-Csv-Encoding utf8mitgeben (5.1 fügt ein BOM hinzu;utf8NoBOMgibt es nur in 7) und das Encoding einer vorhandenen Datei beibehalten (R-code-encoding). - Keine Bash-Syntax einmischen: kein
&&/||zwischen Befehlen (nur PowerShell 7 kennt sie), keinexport VAR=...($env:VAR = ...verwenden), keinrm -rf(Remove-Item -Recurseauf einem geprüften Pfad verwenden). - Windows-Fallen (die PowerShell-Punkte geprüft in 5.1 und 7.6, der Fehler mit CRLF-Shebang in Bash unter WSL):
scist in 5.1 der Alias vonSet-Content(in 7 löst es zum Programm auf); das Dienstwerkzeug alssc.exeaufrufen.Set-Content/Add-Contentbeenden den Text mit CRLF, auch wenn er LF enthält. Ein Shell-Skript braucht-NoNewlineund durchgehend LF (oder[IO.File]::WriteAllTextmitUTF8Encoding $false); ein Shebang mit CRLF scheitert unter Linux mit „required file not found“ oderbad interpreter.- Eine UTF-8-Datei ohne BOM, die 5.1 mit
Get-Contentliest, wird als ANSI-Codepage genommen und macht aus──: beim Lesen-Encoding UTF8mitgeben. - CSV für Excel in einem Gebietsschema mit Dezimalkomma:
-UseCultureoder-Delimiter ';'; 5.1Export-Csvschreibt standardmäßig ASCII (Nicht-ASCII wird zu?),-Encoding UTF8schreibt dort ein BOM, das Excel braucht; in 7-Encoding utf8BOMverwenden. - Ein abgefangener oder umgeleiteter Fehlerstrom von
pwsh7 enthält ANSI-Escape-Sequenzen; in diesem Prozess$PSStyle.OutputRendering = 'PlainText'setzen, um sie zu entfernen (5.1 hat keine).
- Pfade: mit
Join-Pathund$PSScriptRootbauen, nie durch Zusammenfügen von\; Pfade quoten, die Leerzeichen enthalten können;-LiteralPathverwenden, wenn ein Name[oder]enthalten kann.
CR-powershell-strictness
Abschnitt betitelt „CR-powershell-strictness“Strict Mode und Fehler, die anhalten
Kurzfassung: Set-StrictMode, ErrorActionPreference Stop, Exit-Codes nativer Programme, try/catch mit dem fehlgeschlagenen Wert
- Ein Skript mit
Set-StrictMode -Version Latestund$ErrorActionPreference = 'Stop'beginnen; ein nicht abbrechender Fehler lässt das Skript sonst mit fehlerhaften Daten weiterlaufen. - Ein natives Programm (
git,docker,npm) löst bei einem Fehlschlag keinen Fehler aus, und$ErrorActionPreferencefängt ihn nicht ab:$LASTEXITCODEunmittelbar nach dem Aufruf prüfen und mitthrowoderexitund einer Meldung beenden, die den Befehl und den Code nennt. PowerShell 7.4+ kann das mit$PSNativeCommandUseErrorActionPreference = $true; 5.1 nicht. - Spezifische Fehler in
try/catchabfangen und nennen, was mit welchem Wert gescheitert ist ("Cannot read '$Path': $($_.Exception.Message)"); nie ein leerescatch {}.-ErrorAction SilentlyContinuenur an einem einzelnen Aufruf verwenden, dessen Fehlschlag erwartet und danach geprüft wird. - Exit-Codes bewusst setzen (
exit 0/exit 1) am Ende eines Skripts, das CI oder ein anderes Programm aufruft; Fehler mitWrite-Erroroderthrowausgeben, nicht mitWrite-Host.
CR-powershell-style
Abschnitt betitelt „CR-powershell-style“Namen, Parameter, keine Aliase
Kurzfassung: freigegebene Verben, Advanced Functions, param-Blöcke mit Typen, volle Cmdlet-Namen, Ausgabe als Objekte
- Funktionen als
Verb-Nounmit einem freigegebenen Verb benennen (Get-Verblistet sie:Get-,Set-,New-,Remove-,Test-,Invoke-…); ein Nomen im Singular, keinDo-,Run-oderCheck-. - Eine Funktion als Advanced Function schreiben:
[CmdletBinding()], einparam()-Block mit einem Typ an jedem Parameter,[Parameter(Mandatory)]und[ValidateSet()]/[ValidateNotNullOrEmpty()], wo sie passen. Funktionen, die Zustand ändern, mitSupportsShouldProcessmarkieren und-WhatIfbeachten. - Keine Aliase in einem Skript (
ls,gci,%,?,foreachfürForEach-Object,curl,wget) und keine Positionsparameter über den ersten hinaus; das volle Cmdlet und den vollen Parameternamen schreiben.curlundwgetsind in 5.1 Aliase vonInvoke-WebRequest, nicht die Programme. - Objekte zurückgeben, keinen formatierten Text: kein
Format-TableoderWrite-Hostin einer Funktion, deren Ausgabe weiterverwendet wird;Write-Verbosefür den Fortschritt undWrite-Outputoder eine implizite Rückgabe für das Ergebnis verwenden.
CR-powershell-toolchain
Abschnitt betitelt „CR-powershell-toolchain“Lint und Tests
Kurzfassung: PSScriptAnalyzer für Lint, Pester 5 für Tests, oder was das Projekt eingerichtet hat
PSScriptAnalyzer(Invoke-ScriptAnalyzer -Path . -Recurse) ist der übliche Linter des Templates; seine Einstellungen in einerPSScriptAnalyzerSettings.psd1im Projekt halten und keine Regeln pauschal ausschließen.Pesterist der übliche Test Runner; zuerst die installierte Hauptversion prüfen (Get-Module Pester -ListAvailable) — Pester 5 brauchtBeforeAllfür das Setup, und Code zur Discovery-Zeit unterscheidet sich von Code zur Laufzeit, daher laufen Tests für Pester 3/4 nicht unverändert. MitInvoke-Pester -CIausführen.- In beiden Fällen ausführen, was das Projekt konfiguriert hat, und nichts ungefragt installieren
(
R-code-tools).
Coding-Regeln — Python
Quelle: .act/coding/python.md
Kurzfassung: strikte Annotationen, stdlib zuerst, Datenmodelle, Modulaufbau, Toolchain, Tests
Regeln für Python 3 mit Typannotationen, einer Vorliebe für die Standardbibliothek und automatisiertem
Linting. Gruppen-IDs (CR-python-<name>) sind stabil und werden nie neu vergeben; eine Gruppe, deren Zweck
nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-python-basics
Abschnitt betitelt „CR-python-basics“Bewährte Python-Standards
Kurzfassung: Annotationen, f-strings, Context Manager, Exception-Behandlung, venv, Lint
- Jede Funktionssignatur annotieren (Parameter und Rückgabewert), auch interne/private Funktionen.
- f-strings verwenden, nicht
%-Formatierung oder.format(). withfür alles verwenden, was geöffnet und geschlossen werden muss (Dateien, Locks, Verbindungen).- Nie ein veränderliches Default-Argument verwenden (
def f(x: list = [])) — als DefaultNonesetzen und im Funktionsrumpf initialisieren. - Spezifische Exception-Typen abfangen; nie ein nacktes
except Exceptionohne erneutes Auslösen oder Loggen. Jeder ausgelöste oder geloggte Fehler nennt, was woran gescheitert ist, mit welchem Wert — wer aufruft oder das Log liest, muss die Ursache finden, ohne den Quellcode zu öffnen. Nie ein Zugangsdatum oder personenbezogene Daten als dieser Wert: stattdessen eine Kennung oder ein maskierter Wert (R-safe-no-secret-log). is/is notnur für Identitätsvergleiche verwenden (None, Singletons), nie für Werte.- Ein Virtual Environment (
venv) pro Projekt, Abhängigkeiten in einer Lockfile festgeschrieben (requirements.txt,poetry.lock); nie eine globale Installation von Projektabhängigkeiten. - Lint ist der Standard des Stacks und gehört ins Projekt; ausführen, was installiert ist, nichts ungefragt installieren.
CR-python-stdlib-first
Abschnitt betitelt „CR-python-stdlib-first“Standardbibliothek vor einer neuen Abhängigkeit
Kurzfassung: zuerst zur stdlib greifen, bevor ein Paket hinzukommt
- Die Standardbibliothek einer zusätzlichen externen Abhängigkeit vorziehen; eine hinzufügen, nur wo die stdlib wirklich nicht ausreicht.
CR-python-data-models
Abschnitt betitelt „CR-python-data-models“Typisierte Daten statt loser dicts
Kurzfassung: dataclasses, TypedDict oder pydantic für strukturierte Daten
- Strukturierte Daten mit
dataclasses,TypedDictoderpydanticmodellieren, nicht mit einem losendict.
CR-python-module-structure
Abschnitt betitelt „CR-python-module-structure“Ein Modul pro Verantwortung
Kurzfassung: Modulgrenzen, keine zirkulären Imports
- Ein Modul pro fachlicher Verantwortung, kein Sammelmodul ohne klare Grenze.
- Zirkuläre Imports durch Korrektur der Modulgrenzen auflösen, nicht durch Umgehung mit verzögerten oder lokalen Imports.
CR-python-toolchain
Abschnitt betitelt „CR-python-toolchain“Lint- und Format-Tooling
Kurzfassung: standardmäßig ruff für Lint und Formatierung, oder was das Projekt eingerichtet hat
rufffür Linting und Formatierung ist die übliche Wahl des Templates;blackbleibt in bestehenden Projekten eine verbreitete Alternative für die Formatierung — in beiden Fällen ausführen, was das Projekt tatsächlich konfiguriert hat (sieheR-code-tools).
CR-python-tests
Abschnitt betitelt „CR-python-tests“Unit-Tests
Kurzfassung: standardmäßig pytest, oder der Test Runner, den das Projekt eingerichtet hat
pytestist die übliche Wahl des Templates, mit Fixtures statt wiederholtem Setup-Code in jedem Testmodul; den Test Runner verwenden, den das Projekt tatsächlich konfiguriert hat (sieheR-code-tools).
Coding-Regeln — React
Quelle: .act/coding/react.md
Kurzfassung: Rules of Hooks, Keys, Effekte nur zur Synchronisierung, Änderungen in React 19, Server Components, Testing Library
Regeln für React. Sie gelten zusammen mit javascript oder typescript — einen der beiden ebenfalls
ankreuzen; das Template kann „eines von beiden“ nicht als Voraussetzung ausdrücken. Versionsabhängige Punkte
nennen die Version, die sie brauchen; zuerst die installierte React-Version prüfen (R-code-version).
Gruppen-IDs (CR-react-<name>) sind stabil und werden nie neu vergeben; eine Gruppe, deren Zweck nicht mehr
gilt, bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-react-components
Abschnitt betitelt „CR-react-components“Komponenten, Hooks und Keys
Kurzfassung: Rules of Hooks, reines Rendern, stabile Keys, kein aus Props kopierter State
- Hooks nur auf oberster Ebene einer Komponente oder eines eigenen Hooks aufrufen, nie in einer Bedingung,
Schleife oder verschachtelten Funktion; die Regeln von
eslint-plugin-react-hooksbleiben an und werden nicht zum Schweigen gebracht. - Das Rendern rein halten: keine Mutation von Props oder State, kein Fetch, Timer oder
Date.now()im Render-Rumpf. keyist eine stabile ID aus den Daten, nie der Array-Index bei einer Liste, die sich umordnen, ergänzen oder kürzen kann, und nieMath.random().- Eine Prop nicht in den State kopieren, um ihn zu „initialisieren“; die Prop verwenden oder den State nach oben verlagern.
- Komponenten auf Modulebene definieren, nie innerhalb einer anderen Komponente: Eine verschachtelte Definition mountet ihren Teilbaum bei jedem Rendern neu.
- Memoisieren (
useMemo,useCallback,memo) nur bei einem gemessenen Problem; ist der React Compiler im Projekt aktiviert, vorhandene handgeschriebene Memoisierung in Ruhe lassen (die Doku des Compilers rät dazu) und keine neue hinzufügen; sie erst nach sorgfältigem Testen entfernen.
CR-react-effects
Abschnitt betitelt „CR-react-effects“Effekte nur zur Synchronisierung mit der Außenwelt
Kurzfassung: kein abgeleiteter State in Effekten, vollständige Abhängigkeiten, Cleanup, Daten laden nach Wahl des Projekts
- Ein Effekt synchronisiert mit etwas außerhalb von React (Netzwerk, Subscription, DOM-API, Timer). Alles, was sich aus Props und State berechnen lässt, wird beim Rendern berechnet; die Folge eines Events gehört in den Handler.
- Ein
useEffect, der nursetStateaus anderem State aufruft, ist ein Fehler in Wartestellung: den Wert ableiten oder durch Ändern deskeyder Komponente zurücksetzen. - Jeden reaktiven Wert, den der Effekt liest, als Abhängigkeit deklarieren; eine falsche Liste durch Umbau beheben, nie durch Entfernen der Abhängigkeit oder Abschalten der Lint-Regel.
- Für jede Subscription, jeden Timer und jede Anfrage ein Cleanup zurückgeben (
AbortController); Effekte laufen in der Entwicklung unterStrictModebeim Mounten zweimal, und der Code muss das überstehen. - Den Ansatz zum Laden von Daten verwenden, den das Projekt schon hat (TanStack Query, SWR,
Framework-Loader); kein selbstgebautes
fetchin einem Effekt, wo es einen gibt.
CR-react-19
Abschnitt betitelt „CR-react-19“Änderungen in React 19 und später
Kurzfassung: ref als Prop, use, Actions, Context Provider, entfernte APIs
- Ab React 19 nimmt eine Funktionskomponente
refals normale Prop;forwardRefist im neuen Code nicht nötig. Unter React 18 und früher bleibtforwardRef. use(promise)unduse(context)lesen beim Rendern ein Promise oder einen Context und dürfen anders als andere Hooks in einer Bedingung aufgerufen werden. Das Promise kommt aus einem Cache oder einer Elternkomponente, nicht aus demselben Rendern.- Formularbehandlung: eine Funktion als
<form action>,useActionState(früheruseFormState),useFormStatus(ausreact-dom) unduseOptimisticersetzen handgeschriebenen Pending- und Fehler-State. - In 19 entfernt, nicht schreiben:
propTypesunddefaultPropsan Funktionskomponenten,ReactDOM.renderundhydrate(createRoot/hydrateRootverwenden), String-Refs, Legacy Context. useEffectEventgibt es ab React 19.2; davor den neuesten Wert in einem Ref halten.
CR-react-structure
Abschnitt betitelt „CR-react-structure“Server Components und Tests
Kurzfassung: Server Components nur mit unterstützendem Framework, Grenze mit “use client”, Testing Library nach Rolle
- Server Components,
"use server"und"use client"brauchen ein Framework oder einen Bundler, der sie unterstützt (Next.js App Router; die Unterstützung in React Router ist noch experimentell). In einer schlichten Vite-Single-Page-App gibt es sie nicht; die Direktiven dort nicht hinzufügen. - Mit Server Components ist eine Komponente standardmäßig eine Server Component: kein State, keine Effekte,
keine Browser-APIs.
"use client"auf das kleinste Blatt setzen, das Interaktivität braucht; Props über die Grenze müssen serialisierbar sein. - Mit
@testing-library/reactunduser-eventtesten: Elemente so finden, wie ein Nutzer es täte, nach Rolle, Label oder Text, nicht nach Klassenname oder Interna;findBy…den festen Wartezeiten vorziehen. - Tests mit dem Runner ausführen, den das Projekt eingerichtet hat (Vitest oder Jest), und das Netzwerk an
seiner Grenze mocken (
msw), nicht die eigenen Module der Komponente.
Coding-Regeln — Rust
Quelle: .act/coding/rust.md
Kurzfassung: Fehlerbehandlung, Zahlen, Ownership und unsafe, Async, Edition und Toolchain, Tests
Regeln für Rust-Projekte, die mit Cargo gebaut werden. Gruppen-IDs (CR-rust-<name>) sind stabil und werden
nie neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-rust-basics
Abschnitt betitelt „CR-rust-basics“Fehlerbehandlung, Zahlen, Ownership, unsafe
Kurzfassung: kein unwrap/expect in Bibliotheken, geprüfte Umwandlungen und Überläufe, kein unnötiges clone, SAFETY-Kommentare
- Bibliothekscode löst bei einem behebbaren Zustand nie einen
panicaus: keinunwrap()/expect(), keine Indizierung, die bei externer Eingabe außerhalb der Grenzen liegen kann, keinpanic!für falsche Argumente —Resultzurückgeben und den Aufrufer entscheiden lassen.unwrap()/expect()sind in Tests, in Beispielen und inmainbei Startfehlern erlaubt;expect("...")nennt dann die verletzte Annahme, nicht das Symptom. - Fehler als typisierte Werte definieren: in Bibliotheken ein Fehler-
enum(mitthiserror, wenn das Projekt es hat),anyhowoderBox<dyn Error>nur in der obersten Schicht des Binaries. Jeder Fehler nennt, was mit welchem Wert gescheitert ist; mit?weiterreichen und Kontext hinzufügen, statt die Ursache zu verwerfen. - Kein
.clone()hinzufügen, um den Borrow Checker zum Schweigen zu bringen. Zuerst Borgen versuchen (&T,&mut T), eine kürzere Lifetime, den Code umstrukturieren oderRc/Arc, wo geteilter Besitz real ist; nur klonen, wenn ein eigener, besessener Wert gemeint ist. - In Parametern
&str,&[T]und&Pathstatt&String,&Vec<T>,&PathBufnehmen. - Jeder
unsafe-Block trägt einen// SAFETY:-Kommentar, der die Invariante nennt, die ihn korrekt macht, und umschließt so wenig Code wie möglich; jedeunsafe fndokumentiert ihren Vertrag unter# Safety. Nicht zuunsafegreifen, um einen Compilerfehler zu umgehen. - Ein
Resultoder einen#[must_use]-Wert nie ohne genannten Grund mitlet _ =ignorieren. - Warnungen nicht pauschal unterdrücken (
#![allow(warnings)]); ein#[allow(clippy::...)]nennt die Lint-Regel und den Grund. - Ein verengendes oder vorzeichenwechselndes
asschneidet still ab oder bricht still um:TryFrom/try_into()verwenden und den Fehler behandeln, zum ErweiternFrom/into();asnur bei belegtem Wertebereich, mit Kommentar. Die passende Clippy-Lint-Regel (cast_possible_truncation) steht inpedantic,-D warningsfängt es also nicht. - Arithmetik auf Werten von außen (Eingaben, Dateien, Netzwerk, Größen, Offsets) behandelt Überläufe
ausdrücklich:
checked_*mit einem Fehler, odersaturating_*/wrapping_*, wo das gewollt ist; Release-Builds brechen still um, solange das Profil nichtoverflow-checks = truesetzt.
CR-rust-async
Abschnitt betitelt „CR-rust-async“Async-Code
Kurzfassung: kein Blockieren in Tasks, Runtime des Projekts, abbruchsicheres select!, begrenzte Channels, async fn in Traits
- In async-Code nie einen Task blockieren: kein
std::fs/std::net, kein blockierender HTTP-Client, keinstd::thread::sleepund keine lange CPU-Arbeit in einerasync fn; die async-Variante verwenden (tokio::fs,tokio::time::sleep) oder den Blocking-Pool (spawn_blocking). Kein Standard-Lint fängt das. - Die Runtime und ihre
featuressind eine Entscheidung des Projekts: ausCargo.tomllesen (tokio,async-std,smol…), für diese Runtime schreiben, keine zweite hinzufügen, kein neues Feature ungefragt aktivieren. select!in einer Schleife verwirft in jedem Durchlauf die Futures der Zweige, die nicht gewonnen haben: dort nur Futures verwenden, die als abbruchsicher dokumentiert sind, oder das Future einmal vor der Schleife anlegen, pinnen und per&mutpollen; sonst gehen halb gelesene Daten verloren.- Channels zwischen Tasks sind begrenzt (
tokio::sync::mpsc::channel(n), nichtmpsc::channel()aus std), damit ein langsamer Verbraucher den Erzeuger bremst; unbegrenzt nur, wo der Erzeuger von sich aus begrenzt ist, mit einem Kommentar, warum. - Ab
rust-version1.75async fndirekt im Trait schreiben statt überasync_trait, außer der Trait wird alsdyn Traitverwendet; in einem öffentlichen Trait (dort warnt der rustc-Lintasync_fn_in_trait) oder wo Aufrufer einSend-Future brauchen,fn name(&self) -> impl Future<Output = T> + Senddeklarieren.async_traitbehalten, wo das Projekt es fürdynbraucht. Unter 1.75 gilt dieser Punkt nicht (R-code-version).
CR-rust-edition-toolchain
Abschnitt betitelt „CR-rust-edition-toolchain“Edition, Formatierung, Lint
Kurzfassung: Edition und rust-version aus Cargo.toml, Lints des Projekts, zur MSRV passende Abhängigkeiten, fmt, clippy
- Die Edition (
edition = "2021"oder"2024") und die Mindestversion von Rust (rust-version) ausCargo.tomllesen und Code schreiben, der unter ihnen kompiliert: Die Edition 2024 braucht Rust 1.85 oder neuer und ändert unter anderem dieunsafe-Regeln fürextern-Blöcke und den Geltungsbereich von Temporaries; keine Syntax und keine Bibliotheksbestandteile verwenden, die neuer sind alsrust-version(R-code-version). Die Edition nicht ungefragt ändern. - Mit
cargo fmt(rustfmt) formatieren und mitcargo clippy --all-targets -- -D warningslinten — die übliche Wahl des Templates; ausführen, was das Projekt konfiguriert hat (sieheR-code-tools), und nichts ungefragt installieren. Cargo.lockfür Binaries und, nach dem aktuellen Rat von Cargo, auch für Bibliotheken committen; Abhängigkeiten gering halten und die Standardbibliothek bevorzugen, wo sie genügt. Nur die Crate-Features aktivieren, die verwendet werden.- Der Lint-Konfiguration des Projekts folgen (
[lints]/[workspace.lints]inCargo.toml,clippy.toml,#![deny(...)]auf Crate-Ebene); sie nie ungefragt lockern oder erweitern (R-code-checks-intact). Eine neue Abhängigkeit kommt in einer Version, deren eigenerust-versionzu der des Projekts passt:resolver = "3"(Standard ab Edition 2024) wählt solche Versionen; sonst selbst prüfen, und dierust-versiondes Projekts nie anheben, um eine Abhängigkeit passend zu machen.
CR-rust-tests
Abschnitt betitelt „CR-rust-tests“cargo test
Kurzfassung: standardmäßig cargo test, Unit-Tests neben dem Code, Integrationstests in tests/, Doc-Tests
cargo testist der übliche Runner des Templates; den verwenden, den das Projekt eingerichtet hat (zum Beispielcargo nextest— sieheR-code-tools).- Unit-Tests in ein
#[cfg(test)] mod testsneben den Code legen, Integrationstests intests/, und Beispiele in Doc-Kommentaren als Doc-Tests kompilierbar halten. - Tests nach dem erwarteten Verhalten benennen. Nie Zufall ohne festen Seed verwenden und nie mit
thread::sleepwarten; stattdessen auf die tatsächliche Bedingung warten.
Coding-Regeln — SQL
Quelle: .act/coding/sql.md
Kurzfassung: Abfragesicherheit, Transaktionen, Indizes, Benennung, Migrationen, MySQL/MariaDB-Fallstricke
Regeln für Schemaänderungen und Datenbankzugriff aus Anwendungscode. Gruppen-IDs (CR-sql-<name>) sind
stabil und werden nie neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird
in diesem Kopf als retired: aufgeführt.
CR-sql-basics
Abschnitt betitelt „CR-sql-basics“Abfragesicherheit und Schemadisziplin
Kurzfassung: parametrisierte Abfragen, Transaktionen ohne Netzwerkaufrufe, UTC, Indizes, keine versteckte Logik, Locking
- Ausschließlich parametrisierte Abfragen verwenden — nie eine Abfrage bauen, indem Werte in den SQL-String konkateniert werden, in jeder Sprache und mit jedem Treiber.
- Im Anwendungscode nie
SELECT *; Spalten ausdrücklich benennen, damit eine Schemaänderung sichtbar bricht, statt unbemerkt zu verändern, was eine Abfrage zurückgibt. - Mehrschrittige Schreibvorgänge in einer Transaktion bündeln; Teilfehler nicht nachträglich von Hand abgleichen.
- Keinen Netzwerkaufruf innerhalb einer Transaktion machen, die Zeilen-Locks hält: Die Locks dauern so lange wie die langsamste entfernte Antwort. Externe Werte vor dem Öffnen der Transaktion auflösen (nach den Berechtigungsprüfungen), die Zahl der Abrufe je Request begrenzen und sie parallel ausführen; Helfer, die in der Transaktion aufgerufen werden, bekommen nur aufgelöste Werte. Eine wiederholte Transaktion verschlimmert es, da der Callback und jeder Aufruf darin erneut läuft. Im Review fragen: wo beginnt und endet die Transaktion, wie viele Aufrufe nach außen, wie lange höchstens.
- Zeitstempel in UTC speichern; erst in der Darstellungsschicht in eine Zeitzone umrechnen (auf MySQL/MariaDB
CONVERT_TZbeachten, sieheCR-sql-mariadb). - Jede Fremdschlüsselspalte mit einem Index versehen — ohne Index werden Joins und kaskadierende Löschungen mit wachsender Tabelle langsamer.
- Anwendungslogik aus Stored Procedures und Triggern heraushalten; Logik, die im Anwendungscode nicht sichtbar ist, lässt sich nicht reviewen.
- Eine Änderung des Spaltentyps bei einer großen Tabelle auf Lock-Verhalten und erwartete Laufzeit prüfen, bevor sie live ausgeführt wird.
CR-sql-naming
Abschnitt betitelt „CR-sql-naming“Benennung von Bezeichnern
Kurzfassung: snake_case, Tabellen im Plural, Spalten im Singular
- Tabellen und Spalten in
snake_casebenennen. - Für Tabellennamen den Plural verwenden, für Spaltennamen den Singular.
CR-sql-migrations
Abschnitt betitelt „CR-sql-migrations“Migrationsdisziplin
Kurzfassung: versionierte Benennung, idempotent, umkehrbar, ein Werkzeug
- Migrationen mit einer Version (laufende Nummer oder Zeitstempel) plus Beschreibung benennen; eine Datei pro Änderung.
- Migrationen idempotent schreiben (
IF NOT EXISTSoder eine Existenzprüfung) — ein erneuter Lauf über einen bereits migrierten Stand darf nicht fehlschlagen. - Zu jeder Migration eine Down-Migration mitliefern, wo das Migrationswerkzeug das unterstützt.
- Ein Migrationswerkzeug konsequent verwenden (z. B. Flyway, Prisma Migrate, Alembic); nicht mischen.
CR-sql-mariadb
Abschnitt betitelt „CR-sql-mariadb“Fallstricke bei MySQL und MariaDB (InnoDB)
Kurzfassung: Gap-Locks bei Bereichsschreibzugriffen, Fehler 1020 unter Snapshot-Isolation, LOCK IN SHARE MODE statt FOR SHARE, ALTER- und ENUM-Änderungen an versionierten Tabellen, CONVERT_TZ ohne Zonentabellen
- InnoDB (Standard-Isolationsstufe
REPEATABLE READ): EinUPDATEoderDELETEüber einen Bereich auf einer Tabelle, in die andere einfügen, nimmt Gap-Locks und kann mit einem gleichzeitigenINSERTin einen Deadlock laufen. Die Ids zuerst ohne Lock lesen, dann mitWHERE id IN (…)ändern. Es zeigt sich nur bei vielen Zeilen und mehreren gleichzeitigen Schreibenden, ein kleiner Test findet es also nicht. - MariaDB 11.6.2 und neuer (
innodb_snapshot_isolationist standardmäßig an): Fehler 1020 („record has changed since last read“) bricht einen sperrenden Lesezugriff und einUPDATE/DELETEeiner Zeile ab, die nach dem Snapshot der Transaktion geändert wurde. Er bricht auch die Fremdschlüsselprüfung einesINSERTab, sobald die Transaktion etwas ohne Lock gelesen hat und eine andere Transaktion die Elternzeile seither geändert hat, in einer beliebigen Spalte. 1020 rollt die ganze Transaktion zurück: nur die ganze Transaktion wiederholen, mit wachsenden, zufälligen Wartezeiten, dann mit einem klaren Fehler aufgeben; Wirkungen außerhalb der Datenbank werden nicht zurückgerollt. Die Elternzeile vor dem ersten Lesen ohne Lock zu sperren (FOR UPDATE) vermeidet den Fremdschlüssel-Fall. Absicherung: jede Transaktion durch einen Retry-Helfer laufen lassen oder mit einem Markerkommentar versehen, der sagt, warum sie keinen braucht, und einen schnellen Unit-Test Transaktionen mit keinem von beiden finden lassen. - MariaDB: Ein gemeinsamer Lesezugriffs-Lock heißt
LOCK IN SHARE MODE; die MySQL-8-FormFOR SHAREist dort ein Syntaxfehler. DasforShare()eines Query-Builders (etwa Kysely) erzeugt die MySQL-Form, und der Fehler zeigt sich erst zur Laufzeit gegen eine echte Datenbank: stattdessen die Lock-Klausel roh ans Ende der Abfrage hängen (Kysely:.modifyEnd(sql`lock in share mode`)); MySQL 8 akzeptiert diese Form ebenfalls.FOR UPDATEist in beiden gleich. - MariaDB, systemversionierte Tabelle: Ein
ALTER TABLE, das ihre Spalten ändert, wird standardmäßig abgelehnt.system_versioning_alter_history = KEEPfür die Sitzung nur um dasALTERherum setzen, auf derselben Verbindung aus dem Pool, und in einemfinallyzurücksetzen; eine Migration beim Anwendungsstart bricht sonst jeden Start ab.KEEPlässt die Historienzeilen, wie sie sind, eine Änderung, die alten Werten widerspricht, schlägt also weiter fehl (derENUM-Fall unten). - MariaDB, systemversionierte Tabelle: Einen Wert aus einem
ENUMzu entfernen schlägt bei Historienzeilen fehl, auch bei eben ersetzten. Den Wert im Typ lassen, die aktuellen Zeilen umziehen, den alten Wert in der Anwendung ablehnen und den Default mitALTER COLUMN … SET DEFAULTändern. Die Migration gegen eine Datenbank testen, die solche Historienzeilen hat. - MySQL/MariaDB:
CONVERT_TZmit Zonennamen liefert ohne jeden FehlerNULL, wenn die Zeitzonentabellen nicht geladen sind (üblich bei verwalteten oder Container-Datenbanken). Den Offset als Zahl übergeben oder die Umrechnung im Anwendungscode machen.
tailwind
Abschnitt betitelt „tailwind“Coding-Regeln — Tailwind
Quelle: .act/coding/tailwind.md
Kurzfassung: Utility-first-Styling, Design Tokens, Dark Mode, Sortierung der Klassen
Regeln für Tailwind CSS, meist innerhalb eines Frontend-Frameworks eingesetzt. Gruppen-IDs
(CR-tailwind-<name>) sind stabil und werden nie neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt,
bekommt eine neue ID und wird in diesem Kopf als retired: aufgeführt.
CR-tailwind-basics
Abschnitt betitelt „CR-tailwind-basics“Bewährte Tailwind-Standards
Kurzfassung: Utilities im Markup, Tokens, Theme, Dark Mode, Extraktion, Tooling, Fallstricke
- Utility-Klassen direkt im Markup schreiben; keine separaten CSS-Dateien ohne konkreten Grund.
- Design Tokens (die Skala für Abstände, Farben und Radien aus der Konfiguration) statt beliebiger Werte
verwenden —
p-[13px]nur als dokumentierte Ausnahme. - Theme-Änderungen (Farben, Schriften, Breakpoints) zentral in der Tailwind-Konfiguration halten, nicht über Dateien verstreut.
- Dark Mode über die konfigurierten Tokens/Varianten abbilden, nie über parallele hartkodierte Farbwerte.
- Eine wiederholte Klassenkombination in eine Komponente/ein Partial auslagern; nie als Textschnipsel herumkopieren.
- Lint-/Format-Tooling ist der Standard des Stacks und gehört ins Projekt:
prettier-plugin-tailwindcssfür die automatische Sortierung der Klassen (Layout, Box-Modell, Typografie, Farbe, Zustand), vom Formatter erzwungen statt von Hand sortiert. Ausführen, was installiert ist, nichts ungefragt installieren. - Fallstricke:
@applynur in Ausnahmen verwenden (z. B. Basisstile einer Drittanbieter-Komponente), nie als Standardweg zum Stylen.- Die Quellenerkennung korrekt halten — v3: die
content-Pfade in der Konfiguration; v4 und neuer: automatisch, mit@sourcefür Ergänzungen. Eine falsche oder fehlende Quelle lässt entweder tatsächlich genutzte Klassen wegfallen oder lässt ungenutzte Utility-Klassen im Build.
typescript
Abschnitt betitelt „typescript“Coding-Regeln — TypeScript
Quelle: .act/coding/typescript.md
Kurzfassung: Strict Mode, kein any, typisierte Fehler, Modulaufbau, Tooling
Regeln für TypeScript-Projekte im Strict Mode. Gruppen-IDs (CR-typescript-<name>) sind stabil und werden
nie neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-typescript-basics
Abschnitt betitelt „CR-typescript-basics“Strict Mode, Narrowing, typisierte Fehler
Kurzfassung: strict, kein any, Rückgabetypen, as/!, Fehlerbehandlung, Lint
strict: trueintsconfig.jsonaktivieren; nur mit einem Kommentar lockern, der den Grund nennt.- Nie
anyverwenden — unbekannte Werte alsunknowntypisieren und vor der Verwendung eingrenzen. - Die Grenze ziehen, wo Strenge nicht mehr hilft: Ein Typ, der tiefer verschachtelt ist als der Code, den er
beschreibt (stark verschachtelte Generics, verkettete Conditional Types, überdehnte Mapped Types), ist
schlechter als ein einfacherer. Auf
unknownmit einer Prüfung an der Grenze zurückfallen oder auf ein schmalesinterfacenur für die benutzten Felder, mit einem Kommentar, der den Grund nennt — die Ausnahme dient der Lesbarkeit, nicht der Bequemlichkeit, undanybleibt auch hier ausgeschlossen. - Exportierten Funktionen einen expliziten Rückgabetyp geben, statt sich auf Inferenz zu verlassen.
as Typenur verwenden, wenn Narrowing die Aufgabe nicht erfüllen kann, und den Grund in einem Kommentar nennen.- Nie die Non-null-Assertion (
!) verwenden — sie unterdrückt eine echte Nullability-Prüfung. - Fehler als typisierte Error-Objekte auslösen, nie einen beliebigen Wert mit
throwwerfen; was auch immer geworfen, geloggt oder erneut geworfen wird, dessen Meldung nennt, was woran gescheitert ist — wer aufruft, muss die Ursache finden, ohne den Quellcode zu öffnen. - Lint und Typecheck (
tsc --noEmit) sind der Standard des Stacks und gehören ins Projekt; ausführen, was installiert ist, nichts ungefragt installieren.
CR-typescript-conventions
Abschnitt betitelt „CR-typescript-conventions“interface, type, Generics
Kurzfassung: interface für Strukturen, type für Unions, keine Enums, Generics ab der zweiten Verwendung
interfacefür Objektstrukturen/Verträge verwenden,typefür Unions, Intersections und abgeleitete Typen.- Enums vermeiden — stattdessen
as const-Objekte oder Union-Literaltypen verwenden. - Ein Generic erst einführen, wenn es eine zweite konkrete Verwendung gibt; für die erste genügt ein konkreter Typ.
CR-typescript-module-structure
Abschnitt betitelt „CR-typescript-module-structure“Zentrale Typen, explizite Exports
Kurzfassung: gemeinsame Typen an einem Ort, öffentliche Exports über einen Index
- Gemeinsame Typen/Schemas an einer zentralen Stelle definieren und von dort importieren, statt sie pro Modul neu zu deklarieren.
- Die öffentliche API eines Moduls über einen expliziten Index bereitstellen, nicht über tiefe Importpfade in ein anderes Modul.
CR-typescript-toolchain
Abschnitt betitelt „CR-typescript-toolchain“Lint- und Format-Tooling
Kurzfassung: standardmäßig ESLint mit @typescript-eslint plus Prettier, oder was das Projekt eingerichtet hat
- ESLint mit
@typescript-eslintund Prettier für die Formatierung sind die übliche Wahl des Templates; maßgeblich ist, was das Projekt tatsächlich installiert und konfiguriert hat (sieheR-code-tools).
Coding-Regeln — Vue
Quelle: .act/coding/vue.md
Kurzfassung: Composition API, typisierte Props, SFC-Reihenfolge, gemeinsamer Zustand, Tooling
requires: typescript
Regeln für Vue-3-Komponenten mit der Composition API. Gruppen-IDs (CR-vue-<name>) sind stabil und werden
nie neu vergeben; eine Gruppe, deren Zweck nicht mehr gilt, bekommt eine neue ID und wird in diesem Kopf als
retired: aufgeführt.
CR-vue-basics
Abschnitt betitelt „CR-vue-basics“Composition API, typisierte Props, sichere Formulare
Kurzfassung: script setup, typisierte Props/Emits, Konventionen, Fehlerbehandlung, Fallstricke
- In jeder Komponente
<script setup lang="ts">verwenden; im neuen Code keine Options API. defineProps<...>()unddefineEmits<...>()typisieren — keine losen Objekt-Props.- Keine Geschäftslogik im
<template>— Berechnungen incomputedoder eine Methode verlagern. reffür primitive/atomare Werte wählen,reactivenur für den zusammenhängenden Zustand eines Objekts.- Composables mit einem Namen
useXund einem expliziten Rückgabetyp versehen, wenn er nicht trivial inferiert wird. - Einen Watcher/Effect, der eine Ressource bindet (Timer, Listener), aufräumen, sobald er nicht mehr gebraucht wird.
- Fehler bei Aufrufen in Komponenten und Composables bewusst abfangen: dort sichtbar machen, wo das Template
sie anzeigen kann, oder erneut werfen — nie stillschweigend verschlucken; die Meldung nennt, was woran
gescheitert ist.
onErrorCapturedverwenden, um den Fehler einer Kindkomponente gezielt zu behandeln, nicht als globales Auffangbecken. - Lint ist der Standard des Stacks und gehört ins Projekt; ausführen, was installiert ist, nichts ungefragt installieren.
- Fallstricke:
- Nie
v-ifundv-foram selben Element kombinieren. - Eine Prop nie direkt verändern — eine Änderung dem Parent über ein Event melden.
- Sicherheit: Ein Formular mit
@submit.preventbraucht zusätzlichmethod="post"am<form>-Element. Der Handler existiert erst, wenn die Hydration abgeschlossen ist; ein Absenden vor diesem Zeitpunkt (ein Passwortmanager, der Enter drückt, eine langsame Verbindung, ein blockiertes JS-Bundle) löst das native Absenden des Browsers aus. Ohnemethodist das ein GET auf die aktuelle URL — ein Formular mit Zugangsdaten legt die Werte in die Adressleiste, den Browserverlauf und das Serverlog. Gilt für jede serverseitig gerenderte App, nicht nur für Auth-Formulare (siehe GHSA-gj2h-2fpw-fhv9, derselbe Fehler in@nuxt/uivor 4.8.1).
- Nie
CR-vue-sfc-order
Abschnitt betitelt „CR-vue-sfc-order“Feste Reihenfolge der SFC-Blöcke
Kurzfassung: template, script setup, style
- SFC-Blöcke in der Reihenfolge
<template>,<script setup>,<style>anordnen.
CR-vue-state-store
Abschnitt betitelt „CR-vue-state-store“Store-Modul für gemeinsamen Zustand
Kurzfassung: Pinia-Store statt provide/inject
- Zustand, der in der ganzen App geteilt wird, in einem eigenen Store-Modul (Pinia) halten, nicht in
provide/inject.
CR-vue-toolchain
Abschnitt betitelt „CR-vue-toolchain“Lint- und Format-Tooling
Kurzfassung: standardmäßig ESLint mit eslint-plugin-vue plus Prettier, oder was das Projekt eingerichtet hat
- ESLint mit
eslint-plugin-vueund Prettier für die Formatierung sind die übliche Wahl des Templates; maßgeblich ist, was das Projekt tatsächlich installiert und konfiguriert hat (sieheR-code-tools).