Inhalt der Doku
ai-instructions · Doku
Code-Guidelines
Was CodeGuidlines.md für TypeScript, Node-Projekte, Fastify-Services, SDKs und Übersetzungen festlegt.
Auf dieser Seite
CodeGuidlines.md beschreibt, wie Code in
meinen Projekten aussieht und aufgebaut ist. Die Datei ist für Agenten geschrieben: knappe Regeln, jeweils mit einem
kurzen Beispiel. Code, Kommentare und Projekt-Doku sind auf Englisch.
Abschnitte
| Abschnitt | Worum es geht |
|---|---|
| Format | Kurzfassung des IntelliJ-Code-Styles für Agenten ohne Formatter |
| TypeScript & JavaScript | Exporte, Imports, Benennung, Klassenaufbau, Kontrollfluss, Fehler, Kommentare, Datum |
| Node-Projekte | package.json, tsconfig.json, Tests, einheitliche Script-Namen, Release |
| Services (Fastify) | Ordnerstruktur, Konfiguration aus der Umgebung, Routen, Datenbank und Migrationen |
| SDKs (API-Clients) | Client-Klasse, fetch-Methode, Modelle, Exceptions |
| Übersetzungen (i18n) | Aufbau der Übersetzungsdateien und Verwendung mit next-intl |
| README | Aufbau einer README |
Die wichtigsten Regeln
- Nur TypeScript und ESM. Keine
.js-Dateien insrc/undtest/. - Ein Default-Export pro Datei, benannt wie die Datei. Eine Klasse pro Datei, höchstens 500 Zeilen.
- Imports über den Alias
@/statt relativer Pfade, alphabetisch sortiert, Node-Module mitnode:-Präfix. - Suffixe im Namen:
…Interface,…Enum,…Type. Abkürzungen komplett groß (APIClient,JWTAuthHandler). - Explizit statt implizit: Rückgabetypen an jeder Funktion,
strict, keinany, Vergleiche wie=== falsestatt!. - Klassen erweiterbar halten:
protectedals Standard, keine#private-Felder, ab drei Parametern ein Options-Objekt. - Plattform vor Library:
fetch,structuredClone,crypto.randomUUID(); so wenige Abhängigkeiten wie möglich. - Konfiguration nur aus Umgebungsvariablen, jede Variable dokumentiert in
.env.example. - Releases nur per semantic-release mit Conventional Commits.
Ein typisches Beispiel aus der Datei:
export default class FileHandler {
private disk: Disk;
private mimeTypeDetector: MimeTypeDetector;
constructor(disk: Disk, mimeTypeDetector: MimeTypeDetector) {
this.disk = disk;
this.mimeTypeDetector = mimeTypeDetector;
}
async delete(key: string): Promise<boolean> {
try {
await this.disk.delete(FileHandler.getPath(key));
}
catch {
return false;
}
return true;
}
}Verwenden
Verweise in der CLAUDE.md oder AGENTS.md eines Projekts auf die Datei. Gilt für ein Projekt etwas anderes, schreib
die Abweichung dort dazu, statt die Guidelines zu ändern:
## Coding rules
Follow ./CodeGuidlines.md.
Exception for this project: plain JavaScript, no TypeScript.Tipp
Die Regeln zur Formatierung lassen sich am zuverlässigsten mit dem IntelliJ-Formatter durchsetzen. Die Kurzfassung im Abschnitt „Format“ ist für Agenten gedacht, die ihn nicht ausführen können.